Prise en main

Amenez votre premier nœud SiHA d'une image vierge à un pare-feu en fonctionnement et configuré — le flux de bootstrap zéro-touch, de bout en bout.

Ce guide vous mène d’un nœud vierge, non configuré à un pare-feu SiHA en fonctionnement et configuré — tout le bootstrap. Il ne présuppose rien : pas de SSH préalable, pas de cloud-init, pas de secret pré-partagé sur la machine. Vous créez un secret de flotte, décrivez votre flotte et rendez sa config, puis vous imagez chaque nœud, le découvrez et l’adoptez — le tout via l’API.

L’idée — un nœud s’adopte lui-même

Une image SiHA est livrée sans identité. Au tout premier boot, un nœud est non adopté : il crée une CA auto-signée temporaire, démarre joignable, et attend qu’un opérateur le revendique. L’adoption est le moment où vous confiez au nœud votre véritable autorité de certification — dès lors il ne fait confiance (et n’est joignable) qu’aux clients détenant un certificat signé par cette CA.

Deux états, un seul verrou :

État	Ce que cela signifie	Comment l’atteindre
Non adopté	Nœud neuf, CA auto-signée temporaire. Sert un mode maintenance sur `:6443` qui expose uniquement l’endpoint d’adoption, et répond à la découverte.	`sihactl adopt --secret …`
Adopté	Votre CA est installée. mTLS complet ; la découverte se tait.	`sihactl config apply --sihaconfig …` (normal, mTLS)

Le basculement est un unique marqueur sur la partition inscriptible du nœud. Tout le reste — quel mode TLS apid sert, si le nœud répond à la découverte, s’il accepte une adoption — dépend de ce seul indicateur. Il n’y a aucune CA intégrée à l’image ni aucune injectée par cloud-init : l’adoption via l’API est le seul et unique moyen pour un nœud d’obtenir son identité.

Modèle de confiance — TOFU. Un nœud non adopté accepte la première CA qui lui est poussée sur son réseau local, puis en refuse toute autre (Trust On First Use). Le segment L2 est la frontière de confiance : adoptez vos nœuds sur un réseau que vous contrôlez.

1 · Créez le secret de votre flotte (une fois par flotte)

Une seule CA ancre toute votre flotte, détenue côté opérateur dans un fichier secret. Créez-le une fois :

sihactl gen secret prod -o siha-secret.yaml

Le secret contient le certificat de la CA et sa clé privée — utilisés uniquement pour adopter des nœuds (pour leur pousser la CA). Gardez-le précieusement ; chiffrez-le au repos avec SOPS :

sops -e -i siha-secret.yaml

Vous le gardez chiffré à partir de là : sihactl gen config et config apply --secret lisent directement le fichier chiffré et le déchiffrent en mémoire avec l’identité age fournie par SOPS_AGE_KEY_FILE (ou SOPS_AGE_KEY) — les mêmes variables d’environnement que sops lui-même utilise. Exportez-la une fois et toutes les commandes suivantes fonctionnent sur le fichier chiffré, sans étape de déchiffrement manuel :

export SOPS_AGE_KEY_FILE=~/.config/sops/age/keys.txt

Votre identité admin day-2 (un certificat client, pas de clé de CA) est dérivée de ce secret à l’étape suivante, quand vous rendez votre flotte. Une seule CA, une seule identité admin, atteint chaque nœud que vous adoptez — chaque nœud crée lui-même son propre certificat serveur sous votre CA lors de l’adoption, de sorte qu’il n’y a pas de PKI par nœud.

2 · Décrivez votre flotte et rendez-la

Vous n’écrivez pas à la main la config de chaque nœud. Décrivez toute votre flotte dans un unique fleet.yaml et rendez-le — cela produit à la fois le bundle de config de chaque nœud et votre sihaconfig opérateur (l’identité day-2). Voici un fleet.yaml minimal, mono-nœud :

version: v1alpha1
fleetName: prod

appliances:
  - name: fw-1
    endpoint: "192.168.1.10:6443"

    network:
      interfaces:
        # La forme nomme le kind : `pci:` = un port PMD (DPDK).
        - name: wan
          pci: "0000:05:00.0"
          addresses: ["203.0.113.2/24"]
        - name: lan
          pci: "0000:06:00.0"
          addresses: ["10.0.0.1/24"]

    firewall:
      acls:
        - name: wan-in
          family: IPv4
          defaultAction: DROP
          rules:
            - seq: 10
              action: ACCEPT_STATEFUL
              protocol: 6            # TCP
              destinationPortFirst: 443
              description: "HTTPS in"
          bindTo:                    # les bindings vivent sur l'ACL
            - interface: wan
              direction: INPUT

    nat:
      interfaces:
        - name: lan-inside
          interface: lan
          role: inside
        - name: wan-outside
          interface: wan
          role: outside

Rendez-le :

sihactl gen config -f fleet.yaml --secret siha-secret.yaml

Cela écrit tout sous configs/ — auto-gitignoré, parce qu’il contient des clés :

configs/
  sihaconfig      # your day-2 admin identity (context "prod", every endpoint)
  fw-1.yaml       # fw-1's appliance config — ONE document, ready to apply

Quelques points à connaître :

endpoint est l’adresse de management où l’API du nœud répond — elle vient de votre plateforme (DHCP ou un seed statique), pas de SiHA. La carte de management est propriété de la plateforme et n’est pas déclarée dans fleet.yaml.
Les interfaces se lisent à leur forme : pci: = un port DPDK physique, bond:/bridge:/vxlan: déclarent ces kinds, les VLANs s’imbriquent sous leur parent. Pas de bloc networks:, pas de calcul de préfixe — indépendant de la plateforme.
Ajoutez d’autres nœuds sous appliances:, partagez la politique avec les groupes et les patches ($patch: delete, fichiers @./patch.yaml) — voir Flotte déclarative pour le modèle de superposition complet.
configs/ est régénérable : relancez gen config chaque fois que vous éditez fleet.yaml. Prévisualisez ce qu’un nœud dérive avec sihactl gen config -f fleet.yaml --show-derived fw-1.

Si vous pilotez SiHA via le workflow task fourni, task up ENV=<env> rend l’équivalent pour les envs de test fournis (dans gen/<env>/) à votre place.

3 · Bootez un nœud

Imagez le nœud et allumez-le. Sans configuration, il démarre non adopté et se rend joignable :

S’il obtient une adresse de management statique ou DHCP, il l’utilise (p. ex. le 192.168.1.10 que vous avez déclaré comme endpoint de fw-1).
S’il ne trouve aucune adresse du tout (pas de seed, pas de DHCP), il bascule sur une IP de secours (break-glass) — une adresse link-local plus 192.168.1.1/24 — et émet un ARP gratuit pour que votre switch l’apprenne. Vous pouvez toujours joindre un nœud neuf.

Rien d’autre n’est nécessaire sur le nœud. Pas de SSH, pas de login console, pas de secrets.

4 · Découvrez le nœud

Depuis une machine sur le même segment L2 :

sihactl discover

HOSTNAME     MGMT               UNADOPTED  CA-FINGERPRINT
fw-1         192.168.1.10/24    true       3E:72:CD:90:56:1D:BF:0F:…

discover diffuse une petite sollicitation et liste chaque nœud non adopté qui répond, avec son adresse et l’empreinte de sa CA temporaire. Il n’exige ni root ni privilège particulier — juste un réseau capable de broadcast. Les nœuds adoptés ne répondent pas, donc une liste vide signifie « tout ici est déjà revendiqué ».

5 · Adoptez et configurez

Adopter

Revendiquez le nœud avec votre secret de flotte :

sihactl adopt --secret siha-secret.yaml --addr 192.168.1.10:6443

Sous le capot, dans l’ordre :

La CLI lit votre CA depuis --secret et la pousse vers l’endpoint d’adoption du nœud.
Le nœud valide la CA, l’installe, réémet son certificat serveur sous elle, se marque adopté, et redémarre en mTLS complet.
La CLI attend que le mTLS soit opérationnel avant de rendre la main.

adopt est idempotente : si le nœud est déjà adopté, elle sort avec le code 0 immédiatement. Relancez-la à tout moment — c’est sans danger.

Vous adoptez via l’adresse de secours ? Passez --addr 192.168.1.1:6443 à la place — tout le reste est identique.

Vérifier l’état

Une fois adopt terminée, confirmez que le nœud est opérationnel :

sihactl status --addr 192.168.1.10:6443

status fournit une vue d’ensemble sur un seul écran — adopté / mode maintenance / injoignable — et répond à n’importe quel stade du cycle d’adoption (sonde mTLS d’abord, puis repli sur le canal de maintenance ouvert).

Appliquer la configuration

Le nœud étant adopté, poussez sa config d’appliance sur le canal mTLS désormais de confiance :

sihactl --sihaconfig configs/sihaconfig \
  config apply -f configs/fw-1.yaml

Le document est déclaratif : ce que vous retirez de fleet.yaml est retiré (prune) du nœud au prochain apply.

ZTP tout-en-un (alternative)

Si vous préférez une seule commande qui fait adopt + apply en une passe, utilisez :

sihactl config apply --insecure \
  --secret siha-secret.yaml \
  --sihaconfig configs/sihaconfig \
  --addr 192.168.1.10:6443 \
  -f configs/fw-1.yaml

--insecure signifie « je n’ai pas encore établi la confiance ». Après avoir poussé la CA, la CLI attend le redémarrage du nœud, puis applique la config en mTLS en une seule passe. La commande est idempotente : sur un nœud déjà adopté elle saute l’adoption et ne réapplique que le bundle.

6 · Vérifiez

sihactl status --addr 192.168.1.10:6443

Ce contrôle sur un seul écran sonde d’abord avec votre identité mTLS, puis retombe sur le canal de maintenance ouvert — il répond à n’importe quel stade. Pour une vue complète de la santé des services :

sihactl --sihaconfig configs/sihaconfig --addr 192.168.1.10:6443 health

status: STATUS_HEALTHY
  vpp        STATUS_HEALTHY  restarts=1     ← the adoption restart
  apid       STATUS_HEALTHY  restarts=0
  pilotd     STATUS_HEALTHY  restarts=0
  probed     STATUS_HEALTHY  restarts=0
  metricsd   STATUS_HEALTHY  restarts=0

Un restarts=1 sur VPP est attendu — c’est l’unique redémarrage effectué par l’adoption. Relancez sihactl discover et le nœud a disparu de la liste : il est adopté.

Day two — configurer un nœud adopté

Une fois un nœud adopté, vous n’utilisez plus jamais --insecure (ni --secret). La boucle est : éditer fleet.yaml → re-rendre → appliquer, en mTLS normal avec votre identité sihaconfig :

sihactl gen config -f fleet.yaml --secret siha-secret.yaml   # refresh the bundle
sihactl --sihaconfig configs/sihaconfig config apply -f configs/fw-1.yaml

Même forme de commande, moins --insecure et --secret — parce que maintenant les deux côtés s’authentifient. --addr est optionnel ici : avec un seul contexte, le sihaconfig fournit l’endpoint. À partir d’ici, tout est déclaratif : vous appliquez des ressources (interfaces, ACL, NAT, routes, VIP de load-balancer…) et le plan de contrôle fait converger le dataplane pour correspondre. Voir Ressources pour le modèle objet et CLI · sihactl pour la surface complète des commandes.

Récupérer un nœud

Si un nœud devient un jour injoignable (mauvaise config, perte du réseau), l’IP de secours (192.168.1.1/24 + link-local) est toujours disponible au boot lorsque aucune autre adresse ne se résout — joignez-la et réappliquez. L’adresse de secours est configurable (sihactl mgmt set) et prend effet au prochain boot.