Conventions communes

Disponible

Fonctionnalité déployée et prise en charge. Les champs et commandes décrits ici sont stables au sein de la version v1alpha1.

Tous les manifestes StackNGO suivent les mêmes conventions. Les connaître évite de relire chaque page de référence pour les mêmes notions.

Forme d'un manifeste

apiVersion: <groupe>/v1alpha1   # ex. deploy.stackngo.io/v1alpha1
kind: <Kind>                    # ex. App
metadata:
  name: <nom>                   # unique par kind dans votre tenant ; seul champ de metadata
spec: {}                        # ce que vous voulez
status: {}                      # ce que la plateforme observe ; ne s'écrit pas

• metadata.name : un label DNS en minuscules (a-z, 0-9, -), de 63 caractères au plus. Certains kinds sont plus stricts (24 caractères pour App, nom de composant OCI pour RegistryRepository) : la page du kind le précise.
• metadata ne contient que name : ni tenant (déduit de votre session), ni labels, ni annotations. sng apply refuse toute autre clé avec metadata : seul name est permis (<clé> refusé). Un manifeste d'avant cette règle se relit sans ces clés (sng kind get, sng pull) : ré-appliquez-le tel que relu.
• status : écrit par la plateforme. S'il est présent dans votre fichier (par exemple après un sng kind get), il est ignoré à l'application.

Plusieurs documents par fichier

Un fichier peut contenir plusieurs manifestes séparés par ---. sng apply accepte aussi un dossier : il lit tous les .yml et .yaml.

Statut, conditions et raisons

Le status d'une ressource contient presque toujours :

Champ	Sens
observedGeneration	La version du spec que la plateforme a traitée. Si elle est inférieure à metadata.generation, votre dernière modification n'a pas encore été prise en compte.
conditions[]	Une liste d'états nommés, chacun avec type, status (True/False/Unknown), reason (un mot en CamelCase), message (une phrase) et lastTransitionTime.

Les types de condition les plus courants :

Type	True signifie	False signifie
Ready	La ressource fait ce que vous avez demandé	Quelque chose manque ou échoue : lire reason et message
Progressing	Une convergence est en cours (déploiement, tirage d'image)	Rien en cours
Degraded	Une partie fonctionne, une autre non	—
Accepted	Le manifeste a passé l'admission (quotas, cohérence)	Refusé : reason dit pourquoi
Synced	L'état externe (fournisseur, registre, DNS) correspond au spec	Désynchronisé

La reason est stable et documentée : chaque page de référence liste celles de son kind, et l'index des conditions les regroupe toutes.

sng app describe web       # état d'une App
sng secret describe db     # état d'un secret
sng kind get App web            # manifeste enregistré, puis son état en commentaires

Politiques de suppression

Plusieurs kinds portent un champ spec.deletionPolicy qui dit ce qui arrive aux objets externes quand vous supprimez le manifeste :

Valeur	Effet
Block	La suppression attend que la ressource ne soit plus utilisée (des images dans un dépôt, des membres dans un groupe, des utilisateurs qui portent un rôle…) : le status dit ce qui reste. Dès que vous avez vidé, elle aboutit d'elle-même et l'objet externe est supprimé.
Orphan	Le manifeste disparaît, l'objet externe est laissé en place.
Delete	L'objet externe est supprimé avec le manifeste.

Quand un kind n'a pas ce champ, la page de référence précise le comportement (par exemple, les volumes d'une App survivent toujours à sa suppression).

Une ressource en cours de suppression reste visible quelques instants, le temps que le nettoyage se termine. Elle disparaît ensuite d'elle-même.

Immuabilité

Certains champs ne peuvent plus changer après la création (par exemple spec.domain d'une DNSZone). Modifier un champ immuable est refusé au moment de l'application, avec un message qui le nomme. Il faut supprimer puis recréer la ressource.

Règles de validation

Deux niveaux de validation s'appliquent, tous deux avant que le manifeste n'entre dans l'état désiré :

1. Par champ : type, bornes (minimum, maxLength), motif (pattern), énumération. Ces règles apparaissent dans la colonne Validation des tableaux de champs.
2. Croisées : des règles qui lient plusieurs champs (« schedule est obligatoire si kind: cronjob », « un CNAME n'a qu'une cible »). Elles sont listées en français sous chaque tableau de champs, section Règles de validation croisées.

Un manifeste refusé n'est pas appliqué du tout, même partiellement.

Compatibilité

Tous les kinds sont en v1alpha1. La politique de compatibilité décrit ce qui peut changer et comment les évolutions sont annoncées.