iac-homelab/README.md

# iac-homelab

## Description

Ce repository contient l'Infrastructure as Code (IaC) pour un environnement de homelab. Il utilise Terraform pour provisionner des machines virtuelles sur Proxmox VE avec une configuration automatique via Cloud-Init et une intégration Tailscale.

## Fonctionnalités

- 🚀 **Déploiement automatisé** : Création de VMs via Terraform
- 🔧 **Configuration automatique** : Initialisation via Cloud-Init
- 🌐 **Réseau sécurisé** : Connexion automatique à Tailscale
- 📦 **Templates multiples** : Support Ubuntu, Debian, Alpine, Rocky, CentOS
- 🏷️ **Organisation** : Système de tags pour classifier les VMs

## Structure du projet

```
iac-homelab/
├── README.md
├── terraform/
│   └── prod/
│       ├── 01-virtual-machines.tf    # Configuration des VMs
│       ├── 02-cloud-init.tf          # Configuration Cloud-Init
│       ├── providers.tf              # Providers Terraform
│       ├── variables.tf              # Variables
│       ├── terraform.tfvars          # Configuration personnalisée
│       └── terraform.tfvars.example  # Exemple de configuration
└── cloud-init/
    └── user-data.yml.tftpl          # Template Cloud-Init
```

## Prérequis

- **Terraform** : Version récente installée
- **Proxmox VE** : Serveur opérationnel avec API activée
- **Templates VM** : Templates configurés avec les tags appropriés
- **Tailscale** : Compte avec clé d'authentification
- **SSH** : Clés SSH configurées

## Configuration initiale

### 1. Proxmox VE

Créer un utilisateur dédié avec les permissions nécessaires :

```bash
# Créer le rôle
pveum role add TerraformProv -privs "Datastore.Allocate Datastore.AllocateSpace Datastore.Audit Pool.Allocate Sys.Audit Sys.Console Sys.Modify VM.Allocate VM.Audit VM.Clone VM.Config.CDROM VM.Config.Cloudinit VM.Config.CPU VM.Config.Disk VM.Config.HWType VM.Config.Memory VM.Config.Network VM.Config.Options VM.Console VM.Migrate VM.Monitor VM.PowerMgmt SDN.Use"

# Créer l'utilisateur
pveum user add terraform@pve --password <mot_de_passe_securise>
pveum acl modify / -user terraform@pve -role TerraformProv

# Générer le token API
pveum user token add terraform@pve terraform -expire 0 -privsep 0
```

### 2. Templates VM

Créer des templates sur Proxmox avec les tags suivants :

| OS | Tags requis |
|---|---|
| Ubuntu | `["ubuntu", "template"]` |
| Debian | `["debian", "template"]` |
| Alpine | `["alpine", "template"]` |
| Rocky | `["rocky", "template"]` |
| CentOS | `["centos", "template"]` |

## Déploiement

### 1. Configuration

```bash
# Cloner le repository
git clone <repository-url>
cd iac-homelab/terraform/prod

# Copier le fichier d'exemple
cp terraform.tfvars.example terraform.tfvars

# Éditer avec vos valeurs
vim terraform.tfvars
```

### 2. Variables importantes

Dans `terraform.tfvars`, configurer :

```hcl
# Proxmox
proxmox_url = "https://pve01.taila5ad8.ts.net:8006"
proxmox_api_token = "terraform@pve!terraform=<token>"

# Tailscale
tailscale_auth_key = "tskey-auth-<votre-cle>"

# SSH
admin_ssh_public_key_path = "~/.ssh/id_rsa.pub"

# VMs
virtual_machines = {
  "monitoring" = {
    os       = "debian"
    cores    = 2
    memory   = 4096
    disk_gb  = 30
    ip       = "192.168.1.161"
    gateway  = "192.168.1.254"
    tags     = ["monitoring"]
  }
}
```

### 3. Déploiement

```bash
# Initialisation
terraform init

# Vérification
terraform plan

# Déploiement
terraform apply
```

## Configuration des VMs

### Options de base

```hcl
"nom-vm" = {
  os       = "debian"        # Template à utiliser
  cores    = 2               # Nombre de cœurs CPU
  memory   = 4096            # RAM en MB
  disk_gb  = 30              # Taille du disque en GB
  ip       = "192.168.1.100" # Adresse IP statique
  gateway  = "192.168.1.254" # Passerelle réseau
  tags     = ["web"]         # Tags pour l'organisation
}
```

### Options avancées

```hcl
"nom-vm-avancee" = {
  # Configuration de base
  os       = "ubuntu"
  cores    = 4
  memory   = 8192
  disk_gb  = 50
  ip       = "192.168.1.101"
  gateway  = "192.168.1.254"
  
  # Options avancées
  cpu_type       = "host"
  datastore      = "local-lvm"
  network_bridge = "vmbr0"
  username       = "admin"
  
  # Disques supplémentaires
  additional_disks = [
    {
      interface = "scsi1"
      datastore = "local-lvm"
      size      = 100
    }
  ]
}
```

## Fonctionnalités automatiques

### Cloud-Init

Chaque VM est automatiquement configurée avec :
- Installation des packages de base
- Configuration de l'utilisateur et des clés SSH
- Installation du QEMU Guest Agent
- Configuration du hostname

### Tailscale

Installation et connexion automatique :
- Téléchargement et installation de Tailscale
- Connexion au réseau avec la clé d'authentification
- Configuration du hostname sur le réseau

## Maintenance

### Ajouter une VM

```bash
# 1. Ajouter la configuration dans terraform.tfvars
# 2. Appliquer les changements
terraform apply
```

### Supprimer une VM

```bash
# 1. Retirer la configuration de terraform.tfvars
# 2. Appliquer les changements
terraform apply
```

### Modifier une VM

```bash
# 1. Modifier la configuration dans terraform.tfvars
# 2. Vérifier les changements
terraform plan
# 3. Appliquer
terraform apply
```

## Sécurité

- ✅ Authentification par tokens API
- ✅ Connexion SSH par clés uniquement
- ✅ Réseau sécurisé via Tailscale
- ✅ Isolation des VMs
- ✅ Permissions minimales sur Proxmox

## Dépannage

### Problèmes courants

| Problème | Solution |
|---|---|
| Template non trouvé | Vérifier les tags sur Proxmox |
| IP déjà utilisée | Vérifier les conflits d'adresses |
| Erreur SSH | Vérifier le chemin de la clé publique |
| Tailscale | Vérifier la validité de la clé d'authentification |

### Logs détaillés

```bash
# Logs Terraform détaillés
TF_LOG=DEBUG terraform apply

# État des ressources
terraform show

# Liste des ressources
terraform state list
```

## Ressources recommandées

| Type de service | CPU | RAM | Disque |
|---|---|---|---|
| Monitoring | 2 | 4GB | 30GB |
| Web server | 2 | 2GB | 20GB |
| Database | 4+ | 8GB+ | 50GB+ |
| Kubernetes | 4+ | 4GB+ | 40GB+ |

## Support

- 📚 [Documentation Terraform Proxmox Provider](https://registry.terraform.io/providers/bpg/proxmox/latest/docs)
- 🔧 [Proxmox VE Documentation](https://pve.proxmox.com/wiki/Main_Page)
- 🌐 [Tailscale Documentation](https://tailscale.com/kb/)