83 lines
2.9 KiB
Markdown
83 lines
2.9 KiB
Markdown
|
# Node Onboarding Workflow
|
||
|
|
|
||
|
|
This document describes the process of onboarding a new Linux machine into the homelab platform.
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
|
||
|
|
The onboarding process consists of three main stages:
|
||
|
|
1. **Preparation**: Setting up the runtime environment and dependencies.
|
||
|
|
2. **Discovery**: Collecting hardware and software characteristics of the node.
|
||
|
|
3. **Inventory Generation**: Creating the YAML configuration files for the node in the central inventory.
|
||
|
|
|
||
|
|
## Prerequisites
|
||
|
|
|
||
|
|
- A fresh Linux machine (Debian/Ubuntu recommended).
|
||
|
|
- SSH access with sudo privileges.
|
||
|
|
- Tailscale account (if using Tailscale for networking).
|
||
|
|
|
||
|
|
## Onboarding Steps
|
||
|
|
|
||
|
|
### 1. Node Preparation
|
||
|
|
|
||
|
|
Run the `prepare-node.sh` script on the target node. This script will install Docker, Tailscale, and create the `/opt/homelab` directory structure.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
sudo ./scripts/bootstrap/prepare-node.sh
|
||
|
|
```
|
||
|
|
|
||
|
|
**Manual Step**: If you are using Tailscale, you must manually authenticate it after the script runs:
|
||
|
|
```bash
|
||
|
|
sudo tailscale up
|
||
|
|
```
|
||
|
|
|
||
|
|
### 2. Node Discovery
|
||
|
|
|
||
|
|
Run the `discover-node.sh` script to collect system information. It is recommended to redirect the output to a file.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
./scripts/bootstrap/discover-node.sh > discovery-$(hostname).json
|
||
|
|
```
|
||
|
|
|
||
|
|
### 3. Inventory Generation
|
||
|
|
|
||
|
|
Copy the discovery JSON file to your management machine (where the homelab repository is located) and run the inventory generator.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
./scripts/bootstrap/generate-node-inventory.py discovery-node-name.json
|
||
|
|
```
|
||
|
|
|
||
|
|
This will create a new directory in `hosts/<hostname>/` with the following files:
|
||
|
|
- `host.yaml`: Basic host identity and roles.
|
||
|
|
- `capabilities.yaml`: Hardware and software capabilities.
|
||
|
|
- `paths.yaml`: Runtime path definitions.
|
||
|
|
- `networking.yaml`: Networking configuration.
|
||
|
|
|
||
|
|
### 4. Finalization
|
||
|
|
|
||
|
|
1. Review the generated YAML files in `hosts/<hostname>/`.
|
||
|
|
2. Assign appropriate roles to the node in `hosts/<hostname>/host.yaml`.
|
||
|
|
3. Commit the new host configuration to the repository.
|
||
|
|
4. Run the deployment script to apply the initial configuration:
|
||
|
|
```bash
|
||
|
|
./scripts/deploy/deploy-node.sh <hostname>
|
||
|
|
```
|
||
|
|
|
||
|
|
## Recovery Onboarding
|
||
|
|
|
||
|
|
If a node needs to be re-onboarded after a failure:
|
||
|
|
1. Run `prepare-node.sh` again. It is idempotent and will ensure the environment is correct.
|
||
|
|
2. Restore any critical data to `/opt/homelab/data/` and `/opt/homelab/backups/`.
|
||
|
|
3. Re-run `discover-node.sh` if hardware has changed, or reuse the existing inventory if it hasn't.
|
||
|
|
|
||
|
|
## Tailscale Assumptions
|
||
|
|
|
||
|
|
- Nodes are assumed to use Tailscale for management and inter-node communication.
|
||
|
|
- The `networking.yaml` will be populated with the Tailscale IP found during discovery.
|
||
|
|
- If Tailscale is not used, manual adjustment of `networking.yaml` and `host.yaml` is required.
|
||
|
|
|
||
|
|
## Troubleshooting
|
||
|
|
|
||
|
|
- **Docker not starting**: Check `journalctl -u docker`.
|
||
|
|
- **Discovery fails**: Ensure all required tools (lscpu, lsblk, ip, etc.) are installed.
|
||
|
|
- **Inventory Generation error**: Ensure `PyYAML` is installed on the management machine.
|