Compartir a través de

Uso de parámetros de opción de Helm para evitar la eliminación en caso de error de instalación

  • Artículo

Es posible que se produzca un error en las implementaciones del servicio de red de sitio (SNS) porque una implementación subyacente de la función de red (NF) no se puede instalar correctamente. Azure Operator Service Manager (AOSM) quita las implementaciones con errores del clúster de Kubernetes de destino de manera predeterminada para conservar los recursos. Los errores Helm install a menudo exigen que se conserven los recursos en el clúster para permitir la depuración del error. En este artículo de procedimientos se explica cómo editar la plantilla de ARM de la NF para invalidar este comportamiento al establecer el parámetro helm install --atomic en false.

Requisitos previos

  • Debe haber incorporado la NF a AOSM mediante la extensión AOSM de la CLI de Az. En este artículo se hace referencia a la estructura de carpetas y los archivos que genera la CLI y se proporcionan ejemplos basados en la CLI
  • Los errores de instalación de Helm pueden ser complejos. La depuración exige conocimientos técnicos de varias tecnologías además de conocimientos de dominio de la NF
  • Necesita las asignaciones de roles Contributor en la suscripción que contiene el Almacén de artefactos administrados de AOSM
  • Un IDE adecuado, como Visual Studio Code
  • La CLI de ORAS

Importante

Se recomienda encarecidamente que haya probado que una instancia de helm install del paquete de Helm se ejecuta correctamente en el entorno de Kubernetes conectado a Arc de destino antes de intentar una implementación mediante AOSM.

Invalidación de --atomic para una NDF con un único gráfico de Helm

En esta sección se explica cómo invalidar --atomic para una NF que consta de un único gráfico de Helm.

Búsqueda y edición de la plantilla BICEP de la NF

  1. Vaya al directorio nsd-cli-output, abra el directorio artifacts y abra el archivo <nf-arm-template>.bicep. <nf-arm-template> está configurado en el archivo de entrada NSD de la extensión AOSM de la CLI de Az. Puede confirmar que tiene el archivo correcto si lo compara con la siguiente plantilla de ejemplo para una función ficticia de red contenedorizada (CNF) Contoso.

    @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. Busque el nombre de la aplicación de función de red; para ello, vaya al directorio cnf-cli-output, abra el directorio nfDefinition y copie el valor de la única entrada de la matriz networkFunctionApplications en el recurso nfdv. Para confirmar que tiene el valor correcto, compárelo con el siguiente fragmento de código de BICEP del ejemplo ficticio de Contoso. En este caso, el nombre de la aplicación de función de red es 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. Edite la plantilla para invalidar la opción --atomic predeterminada de instalación de Helm y agregue la siguiente configuración a las propiedades nfResource en la plantilla de ARM de la NF:

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

  4. Para confirmar que ha realizado esta edición correctamente, compárela con el siguiente fragmento de código de la NF de ejemplo 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"}}}}}'
    ]}}]

Creación de la plantilla de ARM editada y carga en el Almacén de artefactos

  1. Vaya al directorio nsd-cli-output/artifacts creado por el comando az aosm nsd build y cree la plantilla de ARM de la función de red desde el archivo BICEP generado por la CLI.

    bicep build <nf-name>.bicep

  2. Genere credenciales de token de asignación de ámbito a partir del manifiesto de artefacto creado en el comando az aosm nsd publish.

    Importante

    Es obligatorio usar el manifiesto de artefacto creado en el comando az aosm nsd publish. La plantilla de ARM de la NF solo se declara en ese manifiesto, por lo que solo el token de asignación de ámbito generado por este manifiesto le permitirá insertar (o extraer) la plantilla de ARM de la NF en el Almacén de artefactos.

    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. Inicie sesión en la instancia de ACR administrada por AOSM. El nombre de la instancia de ACR administrada por AOSM se puede encontrar en la información general del recurso Almacén de artefactos en Azure Portal. El nombre de usuario y la contraseña se pueden encontrar en la salida del paso anterior.

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

  4. Use ORAS para cargar la plantilla de ARM de la función de red en la instancia de Azure Container Registry (ACR) administrada por AOSM. La etiqueta de artefacto <arm-template-version> debe tener el formato 1.0.0. <arm-template-name> y <arm-template-version> deben coincidir con los valores del manifiesto de artefacto creado en el comando az aosm nsd publish.

Invalidación de --atomic para una NDF con varios gráficos de Helm

Muchas NF complejas se crean a partir de varios gráficos de Helm. Estas FN se expresan en la versión de definición de función de red (NFDV) con varias aplicaciones de función de red y se instalan con varios comandos helm install, uno por cada gráfico de Helm.

El proceso para invalidar --atomic para una NF de varios gráficos de Helm es el mismo que para una NF de un solo gráfico de Helm, aparte de la edición realizada en la plantilla de ARM.

La NF de varios gráficos de Helm ficticia, Contoso-multi-helm, consta de tres gráficos de Helm. Su NFDV tiene tres aplicaciones de función de red. Una aplicación de función de red se asigna a un gráfico de Helm. Estas aplicaciones de función de red tienen una propiedad name establecida en Contoso-one, Contoso-twoy Contoso-three respectivamente. Este es un fragmento de código de ejemplo de la NFDV en la que se define esta función de red.

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

El parámetro --atomic se puede invalidar para cada una de estas aplicaciones de funciones de red de forma independiente. Este es un ejemplo de plantilla de BICEP de NF en el que se reemplaza --atomic por false para Contoso-one y Contoso-two, pero en el que se establece atomic en true para 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"}}}}}'
    ]}}]

Pasos siguientes

Ahora puede volver a intentar la implementación de SNS. Puede volver a enviar la implementación mediante ARM, BICEP o la API REST de AOSM. También puede eliminar el SNS con errores desde la información general de SNS de Azure Portal y repetir la implementación si sigue el inicio rápido del operador, y reemplaza los parámetros de la NF de inicio rápido por los parámetros de la función de red. Las versiones de Helm implementadas en el clúster de Kubernetes no se quitarán en caso de error. En Procedimiento para depurar errores de implementación de SNS se describe un kit de herramientas para depurar errores comunes de instalación de Helm.