你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 Helm 的相关配置参数以防止在安装失败时删除

2025-06-05

站点网络服务 (SNS) 部署可能会失败，因为基础网络功能 (NF) 部署无法正确进行 helm 安装。默认情况下，Azure作员服务管理器（AOSM）从目标 Kubernetes 群集中删除失败的部署以保留资源。 Helm install 故障通常要求资源保留在群集上，以便调试故障。本 How-To 文章介绍如何通过将参数设置为 helm install --atomic false 来编辑 NF ARM 模板以替代此行为。

先决条件

必须已使用 Az CLI AOSM 扩展将 NF 登录到 AOSM。本文引用 CLI 输出的文件夹结构和文件，并提供基于 CLI 的示例
Helm 安装失败可能很复杂。调试除了需要 NF 的领域知识外，还需要几种技术的技术知识
- Helm 的工作知识
- Kubernetes 和 kubectl 命令的实践知识
- 将项目拉取和推送到 Azure 容器注册表的实践知识
需要在包含 AOSM 管理的项目存储的资源组上拥有Contributor角色分配
合适的 IDE，如 Visual Studio Code
ORAS CLI

重要

强烈建议在尝试使用 AOSM 进行部署之前，先确保您 Helm 包中的 helm install 能在目标 Arc 连接的 Kubernetes 环境中成功运行。

替代单一 helm 图表 NF 的 `--atomic`

本节介绍如何替代由单一 helm 图表组成的 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 目录以及从资源中 networkFunctionApplications 数组 nfdv 中唯一条目复制值来查找网络函数应用程序名称。通过与以下虚构 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 模板中的 --atomic 属性，编辑模板以替代默认的 helm 安装 nfResource 选项：

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 模板并将其上传到制品库

导航到 nsd-cli-output/artifacts 命令创建的 az aosm nsd build 目录，并从 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。可以在 Azure 门户 Artifact Store 资源概述中找到 AOSM 托管 ACR 名称。用户名和密码可以在上一步的输出中找到。
```
oras login <aosm-managed-acr-name>.azurecr.io --username <username> --password <scope map token>
```
使用 ORAS 将网络功能 ARM 模板上传到 AOSM 管理的 Azure 容器注册表 (ACR)。 <arm-template-version> 项目标记必须为 1.0.0 格式。 <arm-template-name>和<arm-template-version>必须与az aosm nsd publish命令中创建的项目清单中的值匹配。

替代多 helm 图表 NF 的 `--atomic`

许多复杂的 NF 是由多个 helm 图表构建的。这些 NF 在具有多个网络功能应用的网络功能定义版本 (NFDV) 中表示，并安装有多个 helm install 命令 - 每个 helm 图表一个。

除了对 ARM 模板进行编辑外，多 helm NF 与单一 helm NF 替代 --atomic 的进程相同。

虚构的多 helm NF，Contoso 多 helm，由三个 helm 图表组成。其 NFDV 有三个网络功能应用程序。一个网络功能应用映射到一个 helm 图表。这些网络功能应用程序的名称属性分别设置为 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 参数。此为 NF Bicep 文件示例，它为 --atomic 和 false 重写了 Contoso-one 为 Contoso-two，但为 atomic 设置 Contoso-three 为 true。

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 门户 SNS 概述删除失败的 SNS，并按照运营商快速启动进行重新部署，将快速启动 NF 参数替换为网络功能的参数。部署到 Kubernetes 群集的 helm 版本不会在失败时移除。如何调试 SNS 部署失败描述了用于调试常见 helm 安装失败的工具包。

通过