Helm のオプションパラメーターを使用してインストールエラー時の削除を防ぐ

[アーティクル]
05/27/2024

基盤となるネットワーク機能 (NF) のデプロイが Helm インストールに失敗したことが原因で、サイトネットワークサービス (SNS) のデプロイが失敗する場合があります。 Azure Operator Service Manager (AOSM) は、リソースを保持するために、失敗したデプロイをターゲットとなる Kubernetes クラスターから既定で削除します。 Helm install エラーでは、多くの場合、そのエラーをデバッグできるようにリソースをクラスター上に保持する必要があります。このハウツー記事では、NF ARM テンプレートを編集し、helm install --atomic パラメーターを false に設定することでこの動作をオーバーライドする方法について説明します。

前提条件

Az CLI AOSM 拡張機能を使用して NF を AOSM にオンボードしておく必要があります。この記事では、CLI によって出力されるフォルダー構造とファイルを参照し、CLI ベースの例を示します
Helm インストールのエラーは複雑な場合があります。デバッグには、NF のドメインに関する知識に加えて、いくつかのテクノロジに関する技術的な知識が必要です
- Helm に関する実用的な知識
- Kubernetes と kubectl コマンドに関する実用的な知識
- Azure Container Registry に対する成果物のプルとプッシュに関する実用的な知識
AOSM マネージド成果物ストア含むリソースグループに Contributor ロールを割り当てる必要があります
Visual Studio Code などの適切な IDE
ORAS CLI

重要

AOSM を使用したデプロイメントを試行する前に、ターゲットの Arc 接続された Kubernetes 環境で Helm パッケージの helm install が成功することをテストすることを強くお勧めします。

単一 Helm Chart NF の `--atomic` をオーバーライドする

このセクションでは、単一の Helm Chart で構成される NF の --atomic をオーバーライドする方法について説明します。

NF BICEP テンプレートを見つけて編集する

nsd-cli-output ディレクトリに移動し、artifacts ディレクトリを開き、<nf-arm-template>.bicep ファイルを開きます。 <nf-arm-template> は、Az AOSM CLI 拡張機能の NSD 入力ファイルで構成されます。次の架空の Contoso のコンテナー化ネットワーク機能 (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)
  }
}]

cnf-cli-output ディレクトリに移動し、nfDefinition ディレクトリを開き、nfdv リソースの networkFunctionApplications 配列内の唯一のエントリから値をコピーして、ネットワーク機能アプリケーション名を見つけます。次の架空の Contoso のサンプル BICEP スニペットと比較して、適切な値があることを確認します。この場合、ネットワーク機能アプリケーション名は 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'

テンプレートを編集して、NF ARM テンプレートの nfResource プロパティに次の構成を追加することで、既定の Helm インストールの --atomic オプションをオーバーライドします。

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

Contoso のサンプル NF の次のスニペットと比較して、この編集が適切に行われたことを確認します。

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

編集した ARM テンプレートをビルドして成果物ストアにアップロードする

az aosm nsd build コマンドによって作成された nsd-cli-output/artifacts ディレクトリに移動し、CLI によって生成された BICEP ファイルからネットワーク機能 ARM テンプレートをビルドします。
```
bicep build <nf-name>.bicep
```
az aosm nsd publish コマンドで作成した成果物マニフェストからスコープマップトークンの資格情報を生成します。

重要

az aosm nsd publish コマンドで作成した成果物マニフェストを使用する必要があります。 NF ARM テンプレートはそのマニフェスト内でのみ宣言されているため、このマニフェストによって生成されたスコープマップトークンのみが NF ARM テンプレートを成果物ストアにプッシュ (またはプル) できます。
```
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'
```
AOSM マネージド ACR にサインインします。 AOSM マネージド ACR 名は、Azure portal 成果物ストアリソースの概要にあります。ユーザー名とパスワードは、前の手順の出力で確認できます。
```
oras login <aosm-managed-acr-name>.azurecr.io --username <username> --password <scope map token>
```
ORAS を使用して、ネットワーク機能 ARM テンプレートを AOSM マネージド Azure Container Registry (ACR) にアップロードします。 <arm-template-version> 成果物タグは、1.0.0 形式である必要があります。 <arm-template-name> と <arm-template-version> は、az aosm nsd publish コマンドで作成された成果物マニフェストの値と一致する必要があります。

マルチ Helm Chart NF の `--atomic` をオーバーライドする

多くの複雑な NF は、複数の Helm Chart から構築されます。これらの NF は、複数のネットワーク機能アプリケーションを含むネットワーク機能定義バージョン (NFDV) で表現されており、複数の helm install コマンド (Helm Chart ごとに 1 つ) でインストールされます。

マルチ Helm NF の --atomic をオーバーライドするプロセスは、ARM テンプレートに対して行われる編集を除けば、単一の Helm NF の場合と同じです。

架空のマルチ Helm NF である Contoso-multi-helm は、3 つの Helm Chart で構成されています。その NFDV には 3 つのネットワーク機能アプリケーションが含まれます。 1 つのネットワーク機能アプリケーションが 1 つの Helm Chart にマップされます。これらのネットワーク機能アプリケーションの name プロパティは、それぞれ Contoso-one、Contoso-two、および Contoso-three に設定されています。このネットワーク機能を定義する NFDV のスニペットの例を次に示します。

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

--atomic パラメーターは、これらのネットワーク機能アプリケーションごとに個別にオーバーライドできます。 Contoso-one と Contoso-two では --atomic を false にオーバーライドしますが、Contoso-three では atomic を true に設定する NF BICEP テンプレートの例を次に示します。

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

次のステップ

これで、SNS デプロイを再試行できるようになりました。 ARM、BICEP、または AOSM REST API を使用して、デプロイを再度送信できます。また、Azure portal の SNS の概要を通じて失敗した SNS を削除し、「Operator のクイックスタート」に従って再デプロイすることもできます。クイックスタートの NF パラメーターを自身のネットワーク機能のパラメーターに置き換えてください。 Kubernetes クラスターにデプロイされた Helm リリースは、エラーが発生しても削除されません。「SNS デプロイエラーをデバッグする方法」では、一般的な Helm インストールのエラーをデバッグするためのツールキットについて説明しています。

次の方法で共有

Helm のオプションパラメーターを使用してインストールエラー時の削除を防ぐ

前提条件

単一 Helm Chart NF の `--atomic` をオーバーライドする

NF BICEP テンプレートを見つけて編集する

編集した ARM テンプレートをビルドして成果物ストアにアップロードする

マルチ Helm Chart NF の `--atomic` をオーバーライドする

次のステップ

フィードバック

その他のリソース

次の方法で共有

Helm のオプション パラメーターを使用してインストール エラー時の削除を防ぐ

前提条件

単一 Helm Chart NF の --atomic をオーバーライドする

NF BICEP テンプレートを見つけて編集する

編集した ARM テンプレートをビルドして成果物ストアにアップロードする

マルチ Helm Chart NF の --atomic をオーバーライドする

次のステップ

フィードバック

その他のリソース

Helm のオプションパラメーターを使用してインストールエラー時の削除を防ぐ

単一 Helm Chart NF の `--atomic` をオーバーライドする

マルチ Helm Chart NF の `--atomic` をオーバーライドする