Premier VPC, premier subnet, première VM
========================================
Ce tutoriel crée de bout en bout une VM joignable, sur un hyperviseur où l'agent est installé et
répond. Il suppose l'API sur ``127.0.0.1:8080`` et une image disque déjà présente sur l'host.
Tout se passe sur un **seul nœud** : un subnet ne s'étend à d'autres hyperviseurs qu'une fois le
plan de contrôle du cluster en place, cf. :doc:`/deploiement/architecture-cluster`.
Ce que l'on construit
---------------------
.. mermaid::
graph LR
subgraph netns vp-admin
BR["br-000001
10.1.1.253"]
GW["gw-000001
gateway 10.1.1.254"]
MD["metadata@i-web
169.254.169.254"]
end
VM["VM i-web
10.1.1.2"] --- BR
BR --- GW
GW --- MD
BR --- VXLAN["VXLAN vni 65537
br-000000"]
Le VPC est un network namespace ; le subnet y pose un bridge ``br-000001`` — ``br-`` suivi de ce
qui suit le premier tiret du nom du subnet — porteur de l'adresse d'émission, et un macvlan
``gw-000001`` porteur de la gateway ; la VM se raccroche au bridge par un tap, reçoit son
adresse en DHCP et son cloud-init depuis le serveur de metadata du netns.
1. Le VPC
---------
.. code-block:: bash
curl -X POST http://127.0.0.1:8080/vpcs \
-H 'Content-Type: application/json' \
-d '{"name": "vp-admin", "cidr": "192.168.0.0/16"}'
Le ``cidr`` est l'espace d'adressage global du VPC : c'est lui qui sera annoncé aux VM comme
route interne, quel que soit le mode du subnet.
La réponse est un **202** : la création est acceptée, pas terminée.
.. code-block:: bash
curl -s http://127.0.0.1:8080/vpcs/vp-admin
Un subnet peut être demandé dès maintenant : il est accepté tant que le VPC est en ``creating``
ou ``running``, et sa création attend que le VPC soit ``running``, dans la limite de
``times.timeout_subnet_start``. Il n'est refusé en **422** que si le VPC est absent, en ``error``
ou en ``deleting``. Le modèle d'attente est décrit dans :doc:`/exploitation/api-agent/asynchronisme`.
2. Le subnet
------------
.. code-block:: bash
curl -X POST http://127.0.0.1:8080/subnets \
-H 'Content-Type: application/json' \
-d '{"name": "sn-000001",
"vpc": "vp-admin",
"mode": "vxlan",
"vxlan_id": 65537,
"iface_type": "vms",
"cidr": "10.1.0.0/23"}'
``iface_type`` est une clé **logique** résolue dans la configuration de l'agent (section
``interfaces``) vers un bridge physique de l'host ; une clé inconnue retombe sur
``default_interface``.
En mode ``vxlan``, les adresses de la gateway sont **calculées** et ne se fournissent pas (un
``interface_ip`` est refusé) : la gateway vue par les VM est l'avant-dernière adresse du CIDR
(``interface_ip`` = ``10.1.1.254`` ici), l'adresse d'émission propre au netns la précédente
(``relay_ip`` = ``10.1.1.253``) ; le CIDR doit valoir au plus ``/29``. Aucune VM ne peut prendre
ces deux adresses, ni celles du réseau et du broadcast. En mode ``bridge``, ``interface_ip`` reste
obligatoire.
Les modes disponibles et leurs conséquences sur le routage sont détaillés dans
:doc:`/concepts/modes-reseau`.
Là encore, attendez ``running`` :
.. code-block:: bash
curl -s http://127.0.0.1:8080/subnets/sn-000001
3. La VM
--------
.. code-block:: bash
curl -X POST http://127.0.0.1:8080/vms \
-H 'Content-Type: application/json' \
-d '{"name": "i-web",
"memory": 2048,
"cpus": 2,
"uefi": true,
"metadata": {"sshkey": "ssh-ed25519 AAAA…",
"user_data": "'"$(base64 < user-data.yml | tr -d '\n')"'"},
"interfaces": [{"subnet": "sn-000001", "ip": "10.1.1.2", "mac": "52:54:00:01:01:02", "primary": true}],
"storage": [{"path": "/var/lib/two/volumes/i-web.qcow2", "dev": "vda"}]}'
Six points qui coûtent du temps quand on les découvre en production :
``user_data`` est **encodé en base64**
Un base64 invalide est rejeté en 400 plutôt que servi vide. L'agent n'interprète jamais ce
contenu.
``password`` est un **hash**, pas un mot de passe
Le champ attend la valeur de la clé ``passwd`` de cloud-config (``$6$…``). Sans ``password``
ni ``sshkey``, aucun compte n'est créé.
Chaque interface a sa ``mac``
Choisie par l'appelant, obligatoire (400 sinon) et jamais vérifiée : deux interfaces sur le
même segment L2 doivent avoir des MAC distinctes.
Exactement une interface est ``primary``
Elle porte la route par défaut et le serveur de metadata. L'ordre du tableau détermine le
slot PCI (``0x03 + index``), donc le nom de l'interface dans le guest. Tous les subnets d'une
VM doivent appartenir au même VPC.
``vda`` pour la racine, ``xvdX`` pour les autres disques
``vda`` est le disque racine, virtio, démarré en premier. Les disques supplémentaires sont des
``xvdX`` (``xvda`` = cible SCSI 0) ; ``sdX`` est refusé (400). La carte PCI en dépend — voir
:doc:`/architecture/contraintes`.
``/dev/xvdX`` dans le guest, jamais ``/dev/sdX``
Le noyau du guest nomme les disques SCSI ``sdX`` dans l'ordre de détection, qui change d'un
démarrage à l'autre. L'agent donne à chaque disque le numéro de série ```` ; une image
conforme (:doc:`/deploiement/image-qcow2`) en fait le lien ``/dev/xvdX``. Sans cette règle,
le nom stable reste ``/dev/disk/by-id/scsi-0QEMU_QEMU_HARDDISK_xvdX``.
4. Vérifier
-----------
.. code-block:: bash
curl -s http://127.0.0.1:8080/vms/i-web
En ``running``, la VM est démarrée et le serveur de metadata est en place. Le provisionnement
cloud-init, lui, se déroule dans le guest ; on l'observe par la console série :
.. code-block:: bash
socat -,raw,echo=0 UNIX-CONNECT:/run/two/vms/serial/i-web.sock
Puis, depuis l'host, en passant par le netns du VPC :
.. code-block:: bash
ip netns exec vp-admin ssh syonad@10.1.1.2
.. note::
En mode ``vxlan``, la VM vit dans le netns du VPC : elle n'est pas joignable depuis l'host
sans route explicite, d'où le ``ip netns exec``. En mode ``bridge``, elle l'est directement.
5. Supprimer
------------
Dans l'ordre inverse — un VPC dont il reste des subnets est refusé en **409** :
.. code-block:: bash
curl -X DELETE http://127.0.0.1:8080/vms/i-web
curl -X DELETE http://127.0.0.1:8080/subnets/sn-000001
curl -X DELETE http://127.0.0.1:8080/vpcs/vp-admin
La suppression d'une VM ne touche **jamais** aux fichiers disque.
.. warning::
``instance-id`` vaut le nom de la VM. Recréer une VM du même nom sur le même disque fait que
cloud-init la reconnaît et **n'applique pas** le user-data. Pour rejouer un provisionnement,
changez de nom ou repartez d'un disque neuf.