homelab-config/AGENT-creation-lxc-proxmox.md

# Guide : Création d'un container LXC sur Proxmox VE

## Sommaire
- [Prérequis](#prérequis)
- [Création du container LXC](#création-du-container-lxc)
- [Configuration réseau](#configuration-réseau)
- [Configuration SSH](#configuration-ssh)
- [Vérifications](#vérifications)
- [Commandes utiles](#commandes-utiles)
- [Exemple concret : CT201 (status-monitor)](#exemple-concret--ct201-status-monitor)

---

## Prérequis

### Environnement
- Cluster Proxmox VE 9.2.4 (Debian 13.5 Trixie)
- Stockage ZFS configuré : `vm-zfs` (rpool/vm)
- Réseau : `vmbr0` (bridge par défaut)
- Accès SSH aux nœuds Proxmox avec authentification par certificat

### Templates disponibles
Vérifier les templates disponibles sur le nœud :
```bash
ls /var/lib/vz/template/cache/
```
Exemple de sortie :
```
debian-12-standard_12.12-1_amd64.tar.zst
debian-13-standard_13.6-1_amd64.tar.zst
```

---

## Création du container LXC

### Commande de base

```bash
pct create <CTID> <TEMPLATE> \
  --rootfs <STORAGE>:<SIZE> \
  --ostype <OS_TYPE> \
  --hostname <HOSTNAME> \
  --password <PASSWORD> \
  --unprivileged 0 \
  --onboot 1 \
  --nameserver <DNS_IP> \
  --net0 name=eth0,bridge=vmbr0,ip=<IP>/24,gw=<GATEWAY> \
  --start 1
```

### Paramètres

| Paramètre | Description | Valeur recommandée |
|-----------|-------------|-------------------|
| `CTID` | Identifiant unique du container | 100-999999999 |
| `TEMPLATE` | Template système | `local:vztmpl/debian-13-standard_13.6-1_amd64.tar.zst` |
| `--rootfs` | Stockage et taille du disque racine | `vm-zfs:2` (2 GiB sur ZFS) |
| `--ostype` | Type du système d'exploitation | `debian`, `ubuntu`, `alpine` |
| `--hostname` | Nom d'hôte du container | `status-monitor` |
| `--password` | Mot de passe root | `secrettemp123` (temporaire) |
| `--unprivileged` | Container non privilégié | `0` (privilégié) ou `1` (non-privilégié) |
| `--onboot` | Démarrage automatique | `1` (oui) ou `0` (non) |
| `--nameserver` | Serveur DNS | `192.168.0.92` (AdGuard) ou `8.8.8.8` |
| `--net0` | Configuration réseau | `name=eth0,bridge=vmbr0,ip=192.168.0.X/24,gw=192.168.0.254` |
| `--start` | Démarrer après création | `1` (oui) |

---

## Configuration réseau

### Options réseau (`--net0`)

| Option | Description | Exemple |
|--------|-------------|---------|
| `name` | Nom de l'interface | `eth0` |
| `bridge` | Bridge Proxmox | `vmbr0` |
| `ip` | Adresse IP | `192.168.0.201/24` |
| `gw` | Passerelle | `192.168.0.254` |
| `hwaddr` | Adresse MAC | `BC:24:11:XX:XX:XX` (auto-générée) |
| `firewall` | Pare-feu activé | `1` (oui) ou `0` (non) |

### Exemple de configuration réseau complète
```bash
--net0 name=eth0,bridge=vmbr0,ip=192.168.0.201/24,gw=192.168.0.254,firewall=0
```

---

## Configuration SSH

### Ajout de la clé SSH pour accès sans mot de passe

1. **Créer le répertoire .ssh dans le container** :
   ```bash
   pct exec <CTID> -- mkdir -p /root/.ssh
   pct exec <CTID> -- chmod 700 /root/.ssh
   ```

2. **Ajouter la clé publique** :
   ```bash
   pct exec <CTID> -- bash -c 'echo ssh-ed25519\ AAAAC3NzaC1lZDI1NTE5AAAAIG8eq44iROSYLJj0G5jNh2Py57/f2Z0LnTE7rPG2T6HH\ theo@peis.fr > /root/.ssh/authorized_keys'
   ```

3. **Configurer les permissions** :
   ```bash
   pct exec <CTID> -- chmod 600 /root/.ssh/authorized_keys
   ```

4. **Vérifier la configuration SSH** (optionnel) :
   ```bash
   pct exec <CTID> -- cat /etc/ssh/sshd_config | grep -E 'PasswordAuthentication|PermitRootLogin|PubkeyAuthentication'
   ```

### Test de connexion
```bash
ssh -i ~/.ssh/id_ed25519 -o StrictHostKeyChecking=no root@192.168.0.201
```

---

## Vérifications

### Vérifier le statut du container
```bash
pct status <CTID>
```
Exemple de sortie :
```
status: running
```

### Vérifier l'adresse IP
```bash
pct exec <CTID> -- ip addr show eth0
```

### Vérifier le service SSH
```bash
pct exec <CTID> -- ss -tlnp | grep 22
```
Exemple de sortie :
```
LISTEN 0      4096               *:22              *:*    users:(("sshd",pid=121,fd=3))
```

### Tester la connectivité réseau
```bash
ping 192.168.0.<CTID_IP>
```

---

## Commandes utiles

### Gestion du container

| Action | Commande |
|--------|----------|
| Démarrer | `pct start <CTID>` |
| Arrêter | `pct stop <CTID>` |
| Redémarrer | `pct restart <CTID>` |
| Supprimer | `pct destroy <CTID>` |
| Voir les logs | `pct console <CTID>` |
| Exécuter une commande | `pct exec <CTID> -- <COMMANDE>` |

### Gestion du stockage

| Action | Commande |
|--------|----------|
| Redimensionner | `pct resize <CTID> rootfs +2G` |
| Voir l'utilisation | `pct df <CTID>` |

### Gestion du réseau

| Action | Commande |
|--------|----------|
| Ajouter une IP | `pct set <CTID> --net0 name=eth0,bridge=vmbr0,ip=192.168.0.X/24,gw=192.168.0.254` |
| Voir la config | `pct config <CTID>` |

---

## Exemple concret : CT201 (status-monitor)

### Contexte
Création d'un container dédié au monitoring du statut des services du homelab.

### Commande de création

```bash
pct create 201 \
  local:vztmpl/debian-13-standard_13.6-1_amd64.tar.zst \
  --rootfs vm-zfs:2 \
  --ostype debian \
  --hostname status-monitor \
  --password secrettemp123 \
  --unprivileged 0 \
  --onboot 1 \
  --nameserver 192.168.0.92 \
  --net0 name=eth0,bridge=vmbr0,ip=192.168.0.201/24,gw=192.168.0.254 \
  --start 1
```

### Post-création

1. **Ajout de la clé SSH** :
   ```bash
   # Sur le nœud Proxmox (prox2)
   pct exec 201 -- mkdir -p /root/.ssh && chmod 700 /root/.ssh
   pct exec 201 -- bash -c 'echo ssh-ed25519\ AAAAC3NzaC1lZDI1NTE5AAAAIG8eq44iROSYLJj0G5jNh2Py57/f2Z0LnTE7rPG2T6HH\ theo@peis.fr > /root/.ssh/authorized_keys'
   pct exec 201 -- chmod 600 /root/.ssh/authorized_keys
   ```

2. **Vérification** :
   ```bash
   # Vérifier le statut
   pct status 201
   
   # Tester le ping
   ping 192.168.0.201
   
   # Tester SSH
   ssh -i ~/.ssh/id_ed25519 -o StrictHostKeyChecking=no root@192.168.0.201 echo "OK"
   ```

3. **Installation des paquets** (si DNS fonctionne) :
   ```bash
   ssh root@192.168.0.201 "apt-get update && apt-get install -y python3 curl git"
   ```

   > **Note** : Si le DNS ne fonctionne pas avec `192.168.0.92` (AdGuard), utiliser `8.8.8.8` :
   > ```bash
   > ssh root@192.168.0.201 "echo 'nameserver 8.8.8.8' > /etc/resolv.conf"
   > ```

### Configuration finale

| Propriété | Valeur |
|-----------|--------|
| **CTID** | 201 |
| **Nom** | status-monitor |
| **IP** | 192.168.0.201 |
| **Stockage** | vm-zfs:2 (2 GiB) |
| **OS** | Debian 13 (Trixie) |
| **Statut** | running |
| **Démarrage auto** | ✅ Oui |
| **Accès SSH** | `ssh root@192.168.0.201` |

---

## Résolution des problèmes

### Problème : DNS ne fonctionne pas
**Symptômes** : `apt-get update` échoue avec "Temporary failure resolving"

**Solution** :
```bash
# Changer temporairement le DNS
ssh root@192.168.0.201 "echo 'nameserver 8.8.8.8' > /etc/resolv.conf"

# Ou vérifier AdGuard (CT103)
# Si AdGuard bloque les requêtes, vérifier sa configuration
```

### Problème : SSH ne répond pas
**Symptômes** : `ssh root@192.168.0.201` timeout

**Vérifications** :
1. Le container est bien démarré : `pct status 201`
2. L'IP est configurée : `pct exec 201 -- ip a`
3. SSH est en écoute : `pct exec 201 -- ss -tlnp | grep 22`
4. La clé SSH est correcte : `cat /root/.ssh/authorized_keys`

### Problème : Impossible de créer le container (template introuvable)
**Symptômes** : `volume 'local:vztmpl/...' does not exist`

**Solution** :
```bash
# Lister les templates disponibles
ls /var/lib/vz/template/cache/

# Si nécessaire, télécharger un template
pveam download local debian-13-standard_13.6-1_amd64.tar.zst
```

---

## Bonnes pratiques

1. **Nommage** : Utiliser des noms explicites pour les containers (ex: `ct201-status-monitor`)
2. **Stockage** : Utiliser ZFS pour les containers avec beaucoup d'E/S
3. **Réseau** : Toujours spécifier une IP statique pour les services critiques
4. **Sécurité** :
   - Désactiver l'accès root SSH si possible
   - Utiliser des clés SSH au lieu de mots de passe
   - Mettre à jour les paquets après création
5. **Sauvegarde** : Configurer des sauvegardes régulières des containers

---

## Commandes résumées pour CT201

```bash
# Création
pct create 201 local:vztmpl/debian-13-standard_13.6-1_amd64.tar.zst --rootfs vm-zfs:2 --ostype debian --hostname status-monitor --password secrettemp123 --unprivileged 0 --onboot 1 --nameserver 192.168.0.92 --net0 name=eth0,bridge=vmbr0,ip=192.168.0.201/24,gw=192.168.0.254 --start 1

# Ajout clé SSH
pct exec 201 -- mkdir -p /root/.ssh && chmod 700 /root/.ssh
pct exec 201 -- bash -c 'echo ssh-ed25519\ AAAAC3NzaC1lZDI1NTE5AAAAIG8eq44iROSYLJj0G5jNh2Py57/f2Z0LnTE7rPG2T6HH\ theo@peis.fr > /root/.ssh/authorized_keys'
pct exec 201 -- chmod 600 /root/.ssh/authorized_keys

# Connexion
ssh -i ~/.ssh/id_ed25519 -o StrictHostKeyChecking=no root@192.168.0.201

# Vérifications
pct status 201
ping 192.168.0.201
```

---

*Document généré le 18/07/2026*