# Node Onboarding Guide

This guide covers onboarding new nodes into Ansible management from the watchtower control node.

---

## Prerequisites

**On Control Node (watchtower):**
- ✅ Ansible installed
- ✅ SSH key generated (`~/.ssh/id_ed25519`)
- ✅ Inventory configured

**On Target Nodes:**
- SSH access with password authentication enabled
- User account with sudo privileges
- Python 3 installed

---

## Quick Onboarding

### Step 1: Update Inventory

Edit [inventory/hosts.ini](../inventory/hosts.ini) to add the new node:

```ini
[docker_nodes]
newnode ansible_host=10.0.0.X ansible_user=chester
```

### Step 2: Run Onboarding Playbook

```bash
cd /home/chester/homelab/ansible

# Onboard specific nodes (will prompt for passwords)
ansible-playbook playbooks/onboard-nodes.yml -k -K --limit newnode

# Onboard all unonboarded nodes
ansible-playbook playbooks/onboard-nodes.yml -k -K --limit heimdall,waldorf
```

**Flags:**
- `-k` = Prompt for SSH password (initial connection)
- `-K` = Prompt for sudo password (if passwordless sudo not configured)

### Step 3: Test Connectivity

```bash
# Test basic connectivity
ansible newnode -m ping

# Test with privilege escalation
ansible newnode -b -m command -a 'whoami'

# Gather facts about the node
ansible newnode -m setup
```

---

## Current Node Status

| Node | IP | Platform | Services | Status |
|------|-------|----------|----------|--------|
| **watchtower** | 10.0.0.200 | Raspberry Pi 5 | Control Plane, Komodo Periphery | ✅ Control Node |
| **heimdall** | 10.0.0.151 | Proxmox VM | Komodo Core, Gitea, Traefik | ⏳ Pending onboarding |
| **waldorf** | 10.0.0.251 | Physical Server | Plex, Tunarr | ⏳ Pending onboarding |

---

## What the Onboarding Playbook Does

1. ✅ Deploys watchtower's SSH public key to target node
2. ✅ Verifies passwordless sudo configuration
3. ✅ Checks Python 3 availability
4. ✅ Validates Docker installation
5. ✅ Verifies NFS mount points

---

## Post-Onboarding

After successful onboarding, you can:

- Use all Ansible modules without password prompts
- Run playbooks against the node
- Automate deployments and configuration management

---

## Troubleshooting

### SSH Connection Fails

```bash
# Test manual SSH connection first
ssh chester@10.0.0.151

# If that works but Ansible fails, check inventory syntax
ansible-inventory --list
```

### Passwordless Sudo Required

Edit `/etc/sudoers.d/90-cloud-init-users` on target node:

```bash
# Allow user to run sudo without password
chester ALL=(ALL) NOPASSWD:ALL
```

### Python Not Found

```bash
# Install Python 3 on target node
sudo apt update && sudo apt install -y python3
```

---

## Next Steps

After onboarding, consider:

1. Configure automated deployments for Docker stacks
2. Set up monitoring and health checks
3. Implement backup automation
4. Create maintenance playbooks (updates, reboots, etc.)