Concepts

Cycle de vie et adoption des ressources

Inventorier, reconnaître et adopter sans ambiguïté les ressources créées par XBee.

XBee ne déduit jamais la propriété d’une ressource cloud à partir de son seul nom. Il utilise des labels ou métadonnées portables, complétés si nécessaire par les anciens marqueurs du provider. Cette preuve protège les VM et les volumes contre une adoption ou une suppression accidentelle.

Modèle de propriété

Clé	Rôle
`xbee-managed=true`	la ressource est gérée par XBee
`xbee-env`	environnement propriétaire
`xbee-name`	nom logique de la ressource
`xbee-resource-kind`	`host` ou `volume`
`xbee-schema=1`	version du contrat de propriété

Les formats physiques varient : tags AWS/Azure, labels GCP/Hetzner/Exoscale, tags Scaleway ou métadonnées OpenStack chez OVHcloud. Le provider les normalise dans l’inventaire XBee.

Une ressource peut être gérée (propriété courante prouvée), historique (anciens marqueurs valides, schéma absent), étrangère (preuve différente) ou orpheline (gérée mais retirée de xbee-env.yaml).

Examiner avant de modifier

xbee plan --state
xbee adopt --plan

xbee plan --state compare la déclaration avec l’état distant en lecture seule. xbee adopt --plan ne modifie rien et ne retient que les hosts et volumes historiques ayant un identifiant provider et une preuve compatible.

Adoption plan:
  host web
    provider ID: i-0123456789abcdef0
    scope: eu-west-3
    add: xbee-managed=true, xbee-resource-kind=host, xbee-schema=1

Adopter

xbee adopt          # confirmation interactive
xbee adopt --force  # CI ou terminal non interactif

Pour chaque candidat, le provider :

relit la ressource par son identifiant exact dans son scope historique ;
vérifie l’environnement, le nom et les anciens marqueurs ;
refuse une ressource étrangère ou déjà versionnée ;
conserve les tags ou métadonnées existants ;
ajoute le contrat courant et attend l’opération distante ;
relit la ressource pour confirmer le schéma ;
rafraîchit le registre local.

Une seconde exécution de xbee adopt --plan ne propose plus les ressources adoptées. L’option --force désactive seulement la confirmation : elle ne contourne aucune preuve de propriété.

Scopes historiques et registre local

.xbee/state.yaml mémorise les identifiants et scopes nécessaires pour retrouver une ressource après le retrait de sa déclaration : région, zone, projet GCP, abonnement Azure et resource group.

xbee state show
xbee state refresh

state refresh relit le provider sans modifier l’infrastructure et remplace le registre atomiquement. Ne modifiez pas ce fichier : il ne constitue pas à lui seul une preuve de propriété.

Exemples par provider

Le workflow reste identique ; la preuve et le scope relus diffèrent.

AWS

xbee adopt --plan   # instance i-… ou volume vol-… et région
xbee adopt --force

AWS relit EC2/EBS par ID et vérifie les anciens tags xbee.id et xbee.name.

Google Cloud

xbee adopt --plan   # projet, zone et ID Compute Engine/Persistent Disk
xbee adopt --force

GCP réutilise le fingerprint lu avant SetLabels, attend l’opération puis relit la ressource.

Microsoft Azure

xbee adopt --plan   # abonnement, resource group et ID ARM
xbee adopt --force

L’ID ARM retourné doit correspondre exactement au candidat. XBee attend le poller des VM ou Managed Disks.

Scaleway

xbee adopt --plan   # zone et ID de serveur ou volume
xbee adopt --force

Les volumes historiques de l’API Instance et les volumes Block Storage sont couverts.

OVHcloud

xbee adopt --plan   # région OpenStack et UUID Nova/Cinder
xbee adopt --force

Les métadonnées des serveurs Nova et volumes Cinder sont conservées puis enrichies.

Hetzner Cloud

xbee adopt --plan   # ID numérique du serveur ou volume
xbee adopt --force

Les anciens labels xbee, xbee-env et éventuellement xbee-host sont validés.

Exoscale

xbee adopt --plan   # zone et UUID de l'instance ou du volume
xbee adopt --force

XBee attend l’opération Exoscale puis relit la ressource par UUID.

Provider interne Docker

Les nouveaux conteneurs et volumes persistants portent le contrat versionné. xbee plan --state vérifie les cinq labels et signale un objet homonyme qui ne les possède pas comme ressource locale historique non vérifiée.

Docker ne permet pas d’ajouter sûrement des labels à un conteneur existant et les anciens conteneurs XBee ne portaient pas d’identifiant d’environnement. XBee refuse donc de les adopter sur la seule base de leur nom.

Pour un ancien conteneur : sauvegardez les données, supprimez-le manuellement seulement après vérification, puis utilisez xbee up pour le recréer. Pour un ancien volume : arrêtez les écritures, sauvegardez-le, laissez XBee créer un volume labellisé, puis copiez et contrôlez les données avant toute suppression manuelle.

Résolution des erreurs

Situation	Action
scope incomplet	vérifier `xbee state show`, les credentials, puis rafraîchir l’état
propriété ou nom différent	vérifier le compte/projet et ne pas forcer l’adoption
ressource déjà versionnée	aucune action ; elle est déjà gérée
relecture non confirmée	relancer `xbee plan --state` et contrôler les permissions
ressource Docker non vérifiée	sauvegarder puis recréer ou migrer ; ne pas se fier au nom

À lire ensuite : Provider interne Docker, Providers VM & volumes et Commandes CLI.