Créer un volume distribué

Goal

Un volume distribué qui conserve plus d’une copie de ses données, monté dans un déploiement, répliquant entre les nœuds — et un opérateur qui sait quoi faire lorsque le nœud hébergeant une copie disparaît.

Before you start

Au moins deux nœuds prêts dans votre locataire — un volume répliqué avec une seule réplique n’a rien sur quoi basculer. Vérifiez le nombre et le statut sur l’écran Nœuds.
La permission volumes:manage pour créer le volume. Le rôle operator la porte, et admin la détient via son joker ; aucun autre rôle ne la possède, et le tableau de bord masque les contrôles de création et de basculement sans elle. Voir la référence des rôles.
La permission deployments:update pour attacher le volume à un déploiement existant — les rôles developer et operator portent tous les deux celle-là. Notez que la permission n’est pas toute l’histoire pour la route du tableau de bord ci-dessous : l’écran Modifier du déploiement n’est lui-même montré qu’aux operator et admin, et un développeur qui y accède directement est renvoyé en arrière. Un développeur attache le volume via le manifeste YAML ou l’API à la place, les deux acceptant le même deployments:update.
Le déploiement auquel vous prévoyez de l’attacher, et le chemin du conteneur où vous souhaitez le monter.

Steps

Créez le volume.

Ouvrez Volumes distribués dans la barre latérale — il se situe directement sous Volumes ; voir la page conceptuelle si vous n’êtes pas sûr de celui que vous voulez.
Choisissez Créer un volume.
Nommez le volume.
Laissez Classe de stockage sur Répliqué (rsync asynchrone) — c’est la valeur par défaut, et c’est la classe qui vous donne un nombre de répliques et un basculement automatique ; les trois autres classes (Éphémère, Partagé, Objet) ne prennent pas de nombre de répliques.
Augmentez Nombre de répliques de sa valeur par défaut de 1 à au moins 2, afin qu’il y ait une copie saine sur laquelle basculer si le nœud primaire disparaît.
Le formulaire expose également Politique de basculement, Intervalle de synchronisation (secondes) et Mode d’accès. Les valeurs par défaut — basculement automatique (qui vérifie quand même une réplique synchronisée vérifiée), une synchronisation toutes les 300 secondes, et ReadWriteOnce, signifiant qu’un seul nœud le monte en lecture-écriture — conviennent pour un premier volume ; laissez-les sauf si vous savez déjà pourquoi vous en avez besoin autrement.
Choisissez Créer un volume distribué.
Ouvrez le nouveau volume depuis la liste et copiez son ID sous le nom du volume. Il ressemble à vol-652e949d, et c’est ce qu’un déploiement utilise pour nommer le volume. Attendez que la phase du volume soit Prêt avant de continuer — un déploiement ne peut pas monter un volume encore en cours de matérialisation.

Attachez-le à un déploiement.

La section Volumes du formulaire de déploiement ne couvre que les montages bind, les volumes nommés et tmpfs ; un montage distribué s’écrit dans la vue YAML du même écran, qui édite la description complète plutôt que les champs exposés par le formulaire.

Ouvrez le déploiement, choisissez Modifier, et basculez le commutateur en haut du formulaire de Formulaire à YAML. La zone est remplie avec le déploiement tel qu’il existe actuellement.
Ajoutez le montage à la liste volumes — type: distributed, l’ID du volume dans distributedVolumeId, et le chemin du conteneur dans target. N’écrivez pas source : un montage distribué porte son identité dans l’ID, et un source à côté est refusé.

Cette zone contient le déploiement tel que l’API le stocke, pas un document manifeste, et les deux orthographient un volume différemment : ici le montage a besoin de type: distributed et l’indicateur est readonly, tout en minuscules. L’onglet Manifeste YAML montre l’autre orthographe. Coller un manifeste dans cette zone ne fonctionne pas — il est rejeté car il n’a pas de image de premier niveau.
Choisissez Enregistrer depuis le YAML. Seuls les champs que vous avez modifiés sont envoyés. Le montage est vérifié à ce moment-là, pas au démarrage, donc un ID qui ne se résout pas, un volume qui n’est pas Prêt, ou une seconde réclamation en lecture-écriture sur le même volume revient comme un refus nommant le champ — voir En cas d’échec ci-dessous.

L'écran Volumes Distribués du tableau de bord Odysseus, listant chaque volume avec sa classe de stockage, sa taille, son nombre de répliques, son nœud principal et sa phase, ainsi que le bouton Créer un Volume utilisé à l'étape 2.

Steps

Créez d’abord le volume — ce n’est pas quelque chose qu’une description de déploiement peut faire exister. Utilisez le tableau de bord, ou POST /api/v1/dvm/volumes, et notez l’ID typé qu’il retourne.
Ajoutez le montage à spec.volumes. Il n’y a pas de clé type sur cette surface : la présence de distributedVolumeId est ce qui rend le montage distribué, et chaque volume de manifeste simple est un montage bind. Notez également que l’indicateur en lecture seule s’écrit readOnly ici, avec un O majuscule. spec.image est requis dans chaque manifeste de déploiement, que vous le modifiiez ou non.
```
apiVersion: odysseus/v1
kind: Deployment
metadata:
  name: my-app
spec:
  image: nginx:1.27-alpine
  volumes:
    - distributedVolumeId: vol-652e949d
      target: /var/lib/my-app
      readOnly: false
```
Omettez source. C’est le champ qu’un montage bind ou un volume nommé utilise, et le fournir à côté de distributedVolumeId est refusé plutôt qu’ignoré.
Si le déploiement épingle également un nœud explicite, c’est spec.placement.node sur cette surface, et il doit nommer le nœud principal actuel du volume pour un montage en lecture-écriture. L’omettre est la meilleure réponse : le placement suit alors le volume.
Appliquez le document en l’envoyant à PUT /api/v1/deployments/{name} avec Content-Type: application/yaml — la même route et la même permission deployments:update qu’une mise à jour JSON, en choisissant le format avec un en-tête. Le document est décodé de manière stricte, donc une clé que cette surface n’a pas est un refus nommant le champ et offrant la forme acceptée, jamais une ligne ignorée silencieusement. Les définitions des champs sont dans la référence du déploiement.

Steps

POST /api/v1/dvm/volumes pour créer le volume, avec la classe de stockage et le nombre de répliques dans le corps. La réponse contient l’ID typé.
GET /api/v1/dvm/volumes/{id} jusqu’à ce que la phase du volume soit Ready.
PUT /api/v1/deployments/{name} avec une liste volumes contenant le montage distribué. Rappelez-vous qu’une liste envoyée remplace celle stockée entièrement plutôt que de fusionner avec elle, donc envoyez tous les montages avec lesquels le déploiement doit se terminer, pas seulement le nouveau.
GET /api/v1/dvm/volumes/{id}/replicas pour lire le rôle, le statut et le retard de chaque copie.

Verify

Le volume réplique. Ouvrez l’écran de détail du volume. Chaque ligne du tableau Répliques affiche le statut synchronisé, une ligne a le rôle primaire, et Nœud Principal nomme l’un des nœuds que vous attendiez pour héberger une copie. La carte Répliques indique n/n synchronisées. Chaque ligne porte également Dernière Synchronisation et Retard de Sync : avec l’intervalle par défaut de 300 secondes, un retard de quelques minutes est le volume fonctionnant normalement, et un retard qui continue d’augmenter ne l’est pas.

Le maillage sous-jacent est actif. La réplication se déplace via un maillage WireGuard entre les nœuds. Choisissez État du Maillage depuis l’écran Volumes Distribués et confirmez que le tableau Pairs WireGuard liste chaque nœud hébergeant une copie, avec une Dernière Poignée de Main récente et un Données Envoyées ou Données Reçues qui n’est pas zéro. Un pair sans poignée de main est un volume qui ne répliquera pas, quelle que soit l’apparence de santé de la propre page du volume. L’écran est décrit dans la référence de l’écran Volumes Distribués.

Le déploiement en dispose. Les conteneurs du déploiement sont en cours d’exécution, et l’écriture d’un fichier au chemin de montage sur le nœud principal apparaît dans la taille locale de la réplique lors de la prochaine synchronisation.

When it fails

Une réplique n’atteint jamais l’état synchronisé. Le nœud auquel elle a été assignée n’a pas de place, ou ne peut pas être atteint — vérifiez le statut de ce nœud sur l’écran Nœuds avant de recréer le volume. Si le volume semble sain mais qu’aucune réplique ne progresse, vérifiez d’abord le Statut du maillage : un pair sans poignée de main récente est la cause la plus courante.

Le volume est créé sans véritable redondance. Le formulaire de création Nombre de répliques est par défaut à 1, ce qui donne un volume répliqué sans rien sur quoi basculer. Augmentez-le à au moins 2 avant de choisir Créer un volume distribué.

Créer un volume n’apparaît jamais. Votre rôle ne porte pas volumes:manage — voir la référence des rôles et votre opérateur de plateforme pour un changement de rôle.

Le montage est refusé lorsque vous enregistrez le déploiement. Chaque refus nomme le champ, la valeur reçue et la valeur attendue ; la référence des rejets les liste en détail. Celles que vous êtes le plus susceptible de rencontrer :

l’ID ne se résout pas vers un volume que ce locataire possède — vérifiez-le par rapport à la liste des Volumes distribués, et notez qu’un volume appartenant à un autre locataire se lit exactement comme un qui n’existe pas ;
le volume n’est pas en phase Prêt — attendez plutôt que de monter un stockage qui pourrait ne pas encore exister sur le nœud cible ;
la classe est shared ou object — seuls les volumes éphémères et répliqués peuvent être dispatchés aujourd’hui, et admettre les autres monterait silencieusement du stockage local au nœud au lieu de ce que la classe promet ;
un autre déploiement le monte déjà en lecture-écriture — un seul rédacteur par volume est la garantie de la classe, donc montez en lecture seule ou détachez l’autre déploiement d’abord ;
le déploiement épingle un nodeId qui n’est pas le primaire du volume — un montage lecture-écriture hors du primaire écrit sur une réplique que la prochaine synchronisation écrase, donc supprimez l’épingle et laissez le placement suivre le volume.

Un nœud hébergeant une réplique disparaît. Ce qui se passe ensuite est décidé par la politique de basculement du volume — le paramètre que vous avez choisi à Politique de basculement sur le formulaire de création, affiché ensuite comme Politique de basculement dans le panneau de spécification du volume. Il y a deux résultats.

Il bascule de lui-même. Avec la politique automatique, une réplique qui est synchronisée et prouvée à jour par rapport à la dernière activité du primaire défaillant est promue sans attendre personne. Vous la voyez comme un événement nommant l’ancien et le nouveau primaire, et la page du volume affiche le nouveau primaire. Il n’y a rien à faire ; vérifiez ensuite que le volume est revenu à son nombre complet de répliques.

Il vous attend. Avec la politique manuelle, ou lorsqu’aucune réplique n’est assez fraîche pour être promue en toute sécurité, la promotion s’arrête et demande. L’écran Volumes distribués affiche une bannière Basculements de volume en attente d’approbation avec une ligne par volume, chacune portant Examiner et approuver → ; la page propre au volume affiche une bannière Basculement en attente d’approbation nommant le nœud défaillant, la réplique proposée, le décalage de cette réplique et pourquoi le chemin automatique l’a refusée. Choisissez Approuver le basculement vers ce nœud et la confirmation reformule la conséquence — approuver promeut cette réplique en sachant qu’elle est en retard, donc ce qu’elle n’a pas rattrapé est ce que vous perdez. L’approbation nécessite volumes:manage.

Rien n’est en attente et rien n’a basculé. Le volume n’est pas répliqué (un volume éphémère n’a pas de seconde copie à promouvoir), ou aucune réplique n’existe du tout. Vérifiez la classe de stockage et le nombre de répliques sur la page du volume.