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 to add the new node:

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

Step 2: Run Onboarding Playbook

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

# 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

✅ Deploys watchtower's SSH public key to target node
✅ Verifies passwordless sudo configuration
✅ Checks Python 3 availability
✅ Validates Docker installation
✅ 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

# 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:

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

Python Not Found

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

Next Steps

After onboarding, consider:

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

2.8 KiB Raw Blame History