Utiliser les paramètres d’option Helm pour empêcher la suppression en cas d’échec d’installation

  • Article

Les déploiements SNS (Site Network Service) peuvent échouer, car un déploiement de fonction réseau (NF) sous-jacent ne parvient pas à effectuer l’installation correctement. Azure Operator Service Manager (AOSM) supprime les déploiements ayant échoué du cluster Kubernetes ciblé par défaut pour préserver les ressources. Helm install échecs nécessitent souvent que les ressources persistent sur le cluster pour permettre le débogage de l’échec. Cet article de procédure explique comment modifier le modèle ARM NF pour remplacer ce comportement en définissant le paramètre helm install --atomic sur false.

Prérequis

  • Vous devez avoir intégré votre NF à AOSM à l’aide de l’extension Az CLI AOSM. Cet article fait référence à la structure de dossiers et à la sortie des fichiers par l’interface CLI et fournit des exemples basés sur l’interface CLI
  • Les échecs d’installation Helm peuvent être complexes. Le débogage nécessite une connaissance technique de plusieurs technologies en plus de la connaissance du domaine de votre NF
  • Vous avez besoin des Contributorattributions de rôles sur le groupe de ressources qui contient le magasin d’artefacts géré par l’AOSM
  • Un environnement de développement intégré (IDE) convenable tel que Visual Studio Code
  • Le CLI ORAS

Important

Il est fortement recommandé d’avoir testé qu’une helm install de votre package Helm réussit sur votre environnement Kubernetes connecté à Arc cible avant d’essayer un déploiement à l’aide d’AOSM.

Remplacer --atomic pour un graphique helm unique NF

Cette section explique comment remplacer --atomic pour un NF qui se compose d’un graphique helm unique.

Rechercher et modifier le modèle BICEP NF

  1. Accédez au répertoire nsd-cli-output, ouvrez le répertoire artifacts, puis ouvrez le fichier <nf-arm-template>.bicep. <nf-arm-template> est configuré dans le fichier d’entrée NSD de l’extension Az AOSM CLI. Vous pouvez confirmer que vous disposez du fichier approprié en comparant le modèle d’exemple suivant pour une fonction réseau conteneurisée Contoso fictive (CNF).

    @secure()
param configObject object

var resourceGroupId = resourceGroup().id

var identityObject = (configObject.managedIdentityId == '')  ? {
  type: 'SystemAssigned'
} : {
  type: 'UserAssigned'
  userAssignedIdentities: {
    '${configObject.managedIdentityId}': {}
  }
}

var nfdvSymbolicName = '${configObject.publisherName}/${configObject.nfdgName}/${configObject.nfdv}'

resource nfdv 'Microsoft.Hybridnetwork/publishers/networkfunctiondefinitiongroups/networkfunctiondefinitionversions@2023-09-01' existing = {
  name: nfdvSymbolicName
  scope: resourceGroup(configObject.publisherResourceGroup)
}

resource nfResource 'Microsoft.HybridNetwork/networkFunctions@2023-09-01' = [for (values, i) in configObject.deployParameters: {
  name: '${configObject.nfdgName}${i}'
  location: configObject.location
  identity: identityObject
  properties: {
    networkFunctionDefinitionVersionResourceReference: {
      id: nfdv.id
      idType: 'Open'
    }
    nfviType: 'AzureArcKubernetes'
    nfviId: (configObject.customLocationId == '') ? resourceGroupId : configObject.customLocationId
    allowSoftwareUpdate: true
    configurationType: 'Open'
    deploymentValues: string(values)
  }
}]

  2. Recherchez le nom de l’application de fonction réseau en accédant au répertoire cnf-cli-output, en ouvrant le répertoire nfDefinition et en copiant la valeur à partir de la seule entrée du tableau networkFunctionApplications dans la ressource nfdv. Vérifiez que vous disposez de la valeur correcte en comparant l’exemple d’extrait de code BICEP de Contoso fictif suivant. Dans ce cas, le nom de l’application de fonction réseau est Contoso.

    resource nfdv 'Microsoft.Hybridnetwork/publishers/networkfunctiondefinitiongroups/networkfunctiondefinitionversions@2023-09-01' = {
  parent: nfdg
  name: nfDefinitionVersion
  location: location
  properties: {
    deployParameters: string(loadJsonContent('deployParameters.json'))
    networkFunctionType: 'ContainerizedNetworkFunction'
    networkFunctionTemplate: {
      nfviType: 'AzureArcKubernetes'
      networkFunctionApplications: [
        {
          artifactType: 'HelmPackage'
          name: 'Contoso'

  3. Modifiez le modèle pour remplacer l’option d’installation helm par défaut --atomic en ajoutant la configuration suivante aux propriétés nfResource dans le modèle ARM NF :

    roleOverrideValues: ['{"name": "Contoso-one", "deployParametersMappingRuleProfile": {"applicationEnablement": "Enabled", "helmMappingRuleProfile": {"options": {"installOptions": {"atomic": "false"}},{"upgradeOptions": {"atomic": "false"}}}}}']

  4. Vérifiez que vous avez effectué cette modification correctement en comparant l’extrait de code suivant à partir de l’exemple NF de Contoso

resource nfResource 'Microsoft.HybridNetwork/networkFunctions@2023-09-01' = [for (values, i) in configObject.deployParameters: {
  name: '${configObject.nfdgName}${i}'
  location: configObject.location
  identity: identityObject
  properties: {
    networkFunctionDefinitionVersionResourceReference: {
      id: nfdv.id
      idType: 'Open'
    }
    nfviType: 'AzureArcKubernetes'
    nfviId: (configObject.customLocationId == '') ? resourceGroupId : configObject.customLocationId
    allowSoftwareUpdate: true
    configurationType: 'Open'
    deploymentValues: string(values)
    roleOverrideValues: [
      '{"name":"Contoso-one","deployParametersMappingRuleProfile":{"helmMappingRuleProfile":{"options":{"installOptions":{"injectArtifactStoreDetails":"true", "atomic": "false"},"upgradeOptions":{"injectArtifactStoreDetails":"true","atomic": "false"}}}}}'
    ]}}]

Générez le modèle ARM modifié et chargez-le dans le magasin d’artefacts

  1. Accédez au répertoire nsd-cli-output/artifacts créé par la commande az aosm nsd build et générez le modèle ARM de fonction réseau à partir du fichier BICEP généré par l’interface CLI.

    bicep build <nf-name>.bicep

  2. Générez des informations d’identification de jeton de mappage d’étendue à partir du manifeste d’artefact créé dans la commande az aosm nsd publish.

    Important

    Vous devez utiliser le manifeste d’artefact créé dans la commande az aosm nsd publish. Le modèle ARM NF est déclaré uniquement dans ce manifeste. Par conséquent, seul le jeton de mappage d’étendue généré par ce manifeste vous permet d’envoyer (ou d’extraire) le modèle ARM NF vers le magasin d’artefacts.

    az rest --method POST --url 'https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.HybridNetwork/publishers/<publisher>/artifactStores/<artifact-store>/artifactManifests/<artifactManifest>/listCredential?api-version=2023-09-01'

  3. Connectez-vous à l’ACR managé par AOSM. Le nom ACR managé par AOSM est disponible dans la vue d’ensemble des ressources du Magasin d’artefacts du portail Azure. Vous trouverez le nom d’utilisateur et le mot de passe dans la sortie de l’étape précédente.

    oras login <aosm-managed-acr-name>.azurecr.io --username <username> --password <scope map token>

  4. Utilisez ORAS pour charger le modèle ARM de fonction réseau dans azure Container Registry (ACR) géré par AOSM. La balise d’artefact <arm-template-version> doit être au format 1.0.0. Les <arm-template-name> et les <arm-template-version> doivent correspondre aux valeurs du manifeste d’artefact créé dans la commande az aosm nsd publish.

Remplacer --atomic pour un graphique multi-helm NF

De nombreuses fonctions réseau complexes sont générées à partir de plusieurs graphiques helm. Ces NFs sont exprimées dans la version de définition de fonction réseau (NFDV) avec plusieurs applications de fonction réseau et sont installées avec plusieurs commandes helm install – une par graphique Helm.

Le processus de substitution de --atomic pour un NF multi helm est identique à celui d’un seul NF helm, en dehors de la modification apportée au modèle ARM.

Le NF multi helm fictif, Contoso-multi-helm, se compose de trois graphiques helm. Son NFDV a trois applications de fonction réseau. Une application de fonction réseau est mappée à un graphique Helm. Ces applications de fonction réseau ont une propriété de nom définie sur Contoso-one, Contoso-twoet Contoso-three respectivement. Voici un exemple d’extrait de code du NFDV définissant cette fonction réseau.

resource nfdv 'Microsoft.Hybridnetwork/publishers/networkfunctiondefinitiongroups/networkfunctiondefinitionversions@2023-09-01' = {
  parent: nfdg
  name: nfDefinitionVersion
  location: location
  properties: {
    deployParameters: string(loadJsonContent('deployParameters.json'))
    networkFunctionType: 'ContainerizedNetworkFunction'
    networkFunctionTemplate: {
      nfviType: 'AzureArcKubernetes'
      networkFunctionApplications: [
        {
          artifactType: 'HelmPackage'
          name: 'Contoso-one'
          ...
        },
        {
          artifactType: 'HelmPackage'
          name: 'Contoso-two'
          ...
        },
        {
          artifactType: 'HelmPackage'
          name: 'Contoso-three'
          ...
        }]
      }
    }
  }

Le paramètre --atomic peut être substitué pour chacune de ces applications de fonction réseau indépendamment. Voici un exemple de modèle BICEP NF qui remplace --atomic à false pour Contoso-one et Contoso-two, mais définit atomic la valeur true pour Contoso-three.

resource nfResource 'Microsoft.HybridNetwork/networkFunctions@2023-09-01' = [for (values, i) in configObject.deployParameters: {
  name: '${configObject.nfdgName}${i}'
  location: configObject.location
  identity: identityObject
  properties: {
    networkFunctionDefinitionVersionResourceReference: {
      id: nfdv.id
      idType: 'Open'
    }
    nfviType: 'AzureArcKubernetes'
    nfviId: (configObject.customLocationId == '') ? resourceGroupId : configObject.customLocationId
    allowSoftwareUpdate: true
    configurationType: 'Open'
    deploymentValues: string(values)
    roleOverrideValues: [
      '{"name":"Contoso-one","deployParametersMappingRuleProfile":{"helmMappingRuleProfile":{"options":{"installOptions":{"injectArtifactStoreDetails":"true", "atomic": "false"},"upgradeOptions":{"injectArtifactStoreDetails":"true","atomic": "false"}}}}}'
      '{"name":"Contoso-two","deployParametersMappingRuleProfile":{"helmMappingRuleProfile":{"options":{"installOptions":{"injectArtifactStoreDetails":"true", "atomic": "false"},"upgradeOptions":{"injectArtifactStoreDetails":"true","atomic": "false"}}}}}'
      '{"name":"Contoso-three","deployParametersMappingRuleProfile":{"helmMappingRuleProfile":{"options":{"installOptions":{"injectArtifactStoreDetails":"true", "atomic": "false"},"upgradeOptions":{"injectArtifactStoreDetails":"true","atomic": "false"}}}}}'
    ]}}]

Étapes suivantes

Vous pouvez maintenant réessayer le déploiement SNS. Vous pouvez soumettre à nouveau le déploiement via ARM, BICEP ou l’API REST AOSM. Vous pouvez également supprimer le SNS ayant échoué via la vue d’ensemble du SNS du portail Azure et redéployer après le guide de démarrage rapide de l’opérateur, en remplaçant les paramètres NF de démarrage rapide par les paramètres de votre fonction réseau. Les versions helm déployées sur le cluster Kubernetes ne seront pas supprimées en cas d’échec. Comment déboguer des échecs de déploiement SNS décrit un kit de ressources pour le débogage des échecs courants d’installation helm.