Freigeben über

Verwenden von Helm-Optionsparametern, um das Löschen bei einem Installationsfehler zu verhindern

  • Artikel

Bei SNS-Bereitstellungen (Site Network Service, Standortnetzwerkdienst) kann ein Fehler auftreten, da Helm von einer zugrunde liegenden NF-Bereitstellung (Netzwerkfunktion) nicht ordnungsgemäß installiert wird. Azure Operator Service Manager (AOSM) entfernt fehlerhafte Bereitstellungen standardmäßig aus dem Kubernetes-Zielcluster, um Ressourcen zu bewahren. Helm install-Fehler erfordern häufig, dass die Ressourcen auf dem Cluster beibehalten werden, um das Debuggen des Fehlers zu ermöglichen. In diesem Schrittanleitungsartikel wird beschrieben, wie Sie die NF-ARM-Vorlage bearbeiten, um dieses Verhalten außer Kraft zu setzen, indem Sie den Parameter helm install --atomic auf „false“ festlegen.

Voraussetzungen

  • Sie müssen Ihre NF mit der Azure CLI-AOSM-Erweiterung in AOSM integriert haben. In diesem Artikel wird auf die Ordnerstruktur und die Dateien verwiesen, die von der CLI ausgegeben werden, und es werden CLI-basierte Beispiele bereitgestellt.
  • Fehler bei der Helm-Installation können komplex sein. Das Debuggen erfordert neben dem Fachwissen zu Ihrer NF auch technische Kenntnisse zu verschiedenen Technologien.
  • Sie benötigen die Rollenzuweisung Contributor für die Ressourcengruppe, die den von AOSM verwalteten Artefaktspeicher enthält.
  • Eine geeignete IDE (beispielsweise Visual Studio Code)
  • ORAS-CLI

Wichtig

Es wird dringend empfohlen, zu testen, ob helm install für Ihr Helm-Paket in Ihrer mit Arc verbundenen Kubernetes-Zielumgebung erfolgreich ist, bevor Sie eine Bereitstellung mithilfe von AOSM ausführen.

Außerkraftsetzen von --atomic für eine NF mit einzelnem Helm-Chart

In diesem Abschnitt wird erläutert, wie Sie --atomic für eine NF außer Kraft setzen, die aus einem einzelnen Helm-Chart besteht.

Suchen und Bearbeiten der NF-BICEP-Vorlage

  1. Navigieren Sie zum Verzeichnis nsd-cli-output, öffnen Sie das Verzeichnis artifacts, und öffnen Sie die Datei <nf-arm-template>.bicep. <nf-arm-template> ist in der NSD-Eingabedatei der Azure CLI-AOSM-Erweiterung konfiguriert. Sie können bestätigen, dass Sie über die richtige Datei verfügen, indem Sie sie mit der folgenden Beispielvorlage für eine fiktive containerisierte Contoso-Netzwerkfunktion (Containerized Network Function, CNF) vergleichen.

    @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. Ermitteln Sie den Namen der Netzwerkfunktionsanwendung, indem Sie zum Verzeichnis cnf-cli-output navigieren, das Verzeichnis nfDefinition öffnen und den Wert aus dem einzigen Eintrag im Array „networkFunctionApplications“ in der nfdv-Ressource kopieren. Vergewissern Sie sich, dass Sie den richtigen Wert haben, indem Sie ihn mit dem folgenden BICEP-Codeschnipsel des fiktiven Contoso-Beispiels vergleichen. In diesem Fall lautet der Name der Netzwerkfunktionsanwendung 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. Bearbeiten Sie die Vorlage, um die Standardoption --atomic für die Helm-Installation außer Kraft zu setzen, indem Sie die folgende Konfiguration zu den nfResource-Eigenschaften in der NF-ARM-Vorlage hinzufügen:

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

  4. Vergewissern Sie sich, dass Sie diese Bearbeitung ordnungsgemäß vorgenommen haben, indem Sie einen Vergleich mit dem folgenden Codeschnipsel aus der Contoso-Beispiel-NF durchführen.

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"}}}}}'
    ]}}]

Erstellen der bearbeiteten ARM-Vorlage und Hochladen in den Artefaktspeicher

  1. Navigieren Sie zum Verzeichnis nsd-cli-output/artifacts, das mit dem Befehl az aosm nsd build erstellt wurde, und erstellen Sie die ARM-Vorlage für die Netzwerkfunktion auf der Grundlage der von der CLI generierten BICEP-Datei:

    bicep build <nf-name>.bicep

  2. Generieren Sie Bereichszuordnungstoken-Anmeldeinformationen auf der Grundlage des Artefaktmanifests, das im Befehl az aosm nsd publish erstellt wurde.

    Wichtig

    Sie müssen das im Befehl az aosm nsd publish erstellte Artefaktmanifest verwenden. Die NF-ARM-Vorlage wird nur in diesem Manifest deklariert, sodass es nur mit dem durch dieses Manifest generierten Bereichszuordnungstoken möglich ist, die NF-ARM-Vorlage an den Artefaktspeicher zu pushen (oder daraus zu pullen).

    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. Melden Sie sich bei der von AOSM verwalteten ACR-Instanz an. Den Namen der von AOSM verwalteten ACR-Instanz finden Sie im Azure-Portal in der Ressourcenübersicht des Artefaktspeichers. Den Benutzernamen und das Kennwort finden Sie in der Ausgabe des vorherigen Schritts.

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

  4. Verwenden Sie ORAS, um die ARM-Vorlage der Netzwerkfunktion in die von AOSM verwaltete ACR-Instanz (Azure Container Registry) hochzuladen. Das Artefakttag <arm-template-version> muss im Format 1.0.0 vorliegen. <arm-template-name> und <arm-template-version> müssen mit den Werten in dem im az aosm nsd publish-Befehl erstellten Artefaktmanifest übereinstimmen.

Außerkraftsetzen von --atomic für eine NF mit mehreren Helm-Charts

Viele komplexe NFs werden auf der Grundlage mehrerer Helm-Charts erstellt. Diese NFs werden in der Netzwerkfunktionsdefinitionsversion (NFDV) mit mehreren Netzwerkfunktionsanwendungen ausgedrückt und mit mehreren helm install-Befehlen installiert – eins pro Helm-Chart.

Der Prozess zum Außerkraftsetzen von --atomic für eine NF mit mehreren Helm-Charts ist identisch mit dem für eine NF mit einem Helm-Chart, abgesehen von der Bearbeitung, die an der ARM-Vorlage vorgenommen wurde.

Die fiktive NF mit mehreren Helm-Charts „Contoso-multi-helm“ besteht aus drei Helm-Charts. Ihre NFDV enthält drei Netzwerkfunktionsanwendungen. Eine Netzwerkfunktionsanwendung ist jeweils einem Helm-Chart zugeordnet. Diese Netzwerkfunktionsanwendungen verfügen über eine Namenseigenschaft, die auf Contoso-one, Contoso-two bzw. Contoso-three festgelegt ist. Hier ist ein Beispielcodeschnipsel der NFDV, der diese Netzwerkfunktion definiert:

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'
          ...
        }]
      }
    }
  }

Der --atomic-Parameter kann für jede dieser Netzwerkfunktionsanwendungen unabhängig voneinander außer Kraft gesetzt werden. Hier sehen Sie ein Beispiel für eine NF-BICEP-Vorlage, die --atomic für Contoso-one und Contoso-two auf false, aber atomic für Contoso-three auf „true“ festlegt.

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"}}}}}'
    ]}}]

Nächste Schritte

Sie können jetzt die SNS-Bereitstellung wiederholen. Sie können die Bereitstellung erneut über ARM, BICEP oder die AOSM-REST-API übermitteln. Sie können die fehlerhafte SNS-Bereitstellung auch über die SNS-Übersicht im Azure-Portal löschen und den SNS gemäß diesem Schnellstart erneut bereitstellen. Ersetzen Sie dabei die NF-Parameter des Schnellstarts durch die Parameter für Ihre Netzwerkfunktion. Die im Kubernetes-Cluster bereitgestellten Helm-Releases werden bei einem Fehler nicht entfernt. Unter Debuggen von SNS-Bereitstellungsfehlern wird ein Toolkit zum Debuggen allgemeiner Fehler bei der Helm-Installation beschrieben.