Renommer une clé de catégorie Prism Central sans perdre un seul tag

Une clé de catégorie mal nommée ne se corrige pas d’un clic dans Prism Central. Il faut migrer vers une nouvelle clé, VM et playbooks compris, sans laisser une VM sans tag en route.

Pourquoi on ne renomme pas

Une catégorie est une paire clé:valeur (Nutanix Bible). Selon la doc du SDK Prism v4.0, la mise à jour porte sur « la description, la valeur et le propriétaire ». La doc early access v4.0.a2 est plus nette : le champ key reste immuable après la création, l’extId est un UUID aléatoire généré à la création, et une catégorie encore associée ne peut pas être supprimée.

Passer de Département à Department est donc une migration.

La bascule en six phases

Un script, une phase par application, simulation par défaut.

1. create : nouvelle clé et toutes ses valeurs. Le nombre de paires listées doit augmenter exactement du nombre de valeurs créées.
2. retag : chaque VM Département=<valeur> reçoit Department=<valeur>, l’ancien tag restant en place. Refaites la simulation le jour J : en 24 h, le périmètre avait bougé de quelques VM.
3. playbooks : rebranchement de ceux qui posent l’ancienne clé.
4. verify : aucune référence restante à l’ancienne clé dans les playbooks ; par valeur, autant de VM sur la nouvelle clé que sur l’ancienne.
5. untag : retrait de l’ancien tag sur les seules VM qui portent l’équivalent, après relecture de l’état frais. Refus de démarrer si un playbook, une règle Flow ou une protection policy référence encore l’ancienne clé.
6. suppression de l’ancienne clé, à la main dans l’interface.

En v3, taguer impose un PUT de la VM complète, spec et metadata, les catégories étant dans metadata.categories. En v4, $actions/associate-categories ne demande pas la configuration de la VM : le corps liste les extId des catégories, et l’ETag de la VM, lu par un GET, part en If-Match (exemple nutanix.dev sur vmm/v4.0.b1).

Trois pièges

Les playbooks visent un UUID. L’action d’ajout de catégorie référence la paire par son UUID ; Département:<valeur> n’est qu’un libellé. Un rechercher-remplacer dans la spec ne rebranche rien. Contrôle croisé fait sur une valeur : l’extId v4 est l’UUID présent dans les playbooks.

L’accent dans l’URL. Observé sur Prism Central 7.3.1.5 : l’endpoint v3 categories/<clé>/list répond HTTP 200 avec zéro résultat si la clé est accentuée ; un filtre de l’API groups fait de même. Contournement : lister GET /api/prism/v4.0/config/categories en paginant, et filtrer côté client (voir ce billet).

La normalisation qui confond. Comparer sans accents pour tolérer les variantes d’encodage fusionne deux clés distinctes :

import unicodedata

def sans_accent(s):
    return "".join(c for c in unicodedata.normalize("NFD", s) if not unicodedata.combining(c))

print(sans_accent("Département") == sans_accent("Departement"))  # True

Cherchez la nouvelle clé en exact ; tolérez NFC, NFD ou mojibake pour l’ancienne seulement, en excluant la nouvelle. Et évitez deux clés qui ne diffèrent que par un accent : dans l’interface, on les confond facilement.

Tenir la nomenclature

L’audit qui a suivi : environ un quart des VM sans aucune catégorie. Les playbooks de tagging (regex sur le nom, déclenchés à la création ou à la modification de la VM) laissaient passer :

• des regex qui ne matchaient jamais, par exemple faute d’un .+ entre le code et les chiffres finaux ;
• des VM créées par Move ou par restauration, sans déclenchement du playbook de création dans plusieurs cas ;
• des noms hors convention : suffixe -clone, _OLD, casse différente.

Rattrapage en deux temps : un rapport classe chaque VM (conforme, taggable, non dérivable), puis l’application écrit le CSV exact des ajouts, donc réversible. Les non dérivables se traitent à la main. Planifié chaque semaine, ce rapport peut servir de filet sous les playbooks.

Ce qu’il faut retenir

• Une clé ne se renomme pas : créer, double-taguer, rebrancher, vérifier, détaguer, supprimer.
• Les playbooks pointent un UUID : rebranchez-les avec l’extId v4.
• Clé accentuée : liste v4 et filtre côté client.
• Nouvelle clé comparée en exact, jamais en normalisé.
• Un rapport périodique peut attraper ce que les playbooks ratent.

In English

A category key cannot be renamed. Recreate it, double-tag the VMs, repoint the playbooks by UUID, which is the v4 extId, verify, then remove the old key, followed by a naming audit. On Prism Central 7.3.1.5, the v3 categories list endpoint returns 200 with zero results when the key contains an accented character.

Sources & vérification

Testé sur : Prism Central 7.3.1.5

• Prism v4.0 Java SDK, CategoriesApi developers.nutanix.com
• Prism v4.0.a2 Java SDK, CategoriesApi developers.nutanix.com
• Nutanix v4 API Batch Operations Part 2, ACTION nutanix.dev
• Fil next.nutanix.com, assigner une catégorie par l'API v3 next.nutanix.com
• Prism v4.0.a2 Python SDK, modèle Category developers.nutanix.com
• Nutanix Bible, Flow Network Security nutanixbible.com
• Expérience directe de l’auteur, en production (versions ci-dessus)

Comment les billets sont vérifiés et corrigés