แก้ไข

แชร์ผ่าน

Azure CLI Azure Operator Service Manager (AOSM) extension issues

  • บทความ

This document contains a list of common issues when using the Azure CLI AOSM extension to onboard Network Functions, and their resolutions.

Common issues

Publisher already exists in the region

Publisher names must be unique within an Azure region. If you see the following error, the publisher name you chose is already in use:

Message: A private publisher resource with the name 'nginx-publisher' already exists in the provided region.

To resolve this error:

If you own the publisher, it is in your tenant, and you wish to re-use it:

The publisher is defined in your AOSM CLI extension configuration file. The publisher_name and publisher_resource_group_name fields must match those of the existing publisher, and it must be in the tenant you are using for this deployment.

Change the publisher_resource_group_name in the config file so that it references the existing publisher, rerun the corresponding build command, then rerun the publish command.

You do not own the existing publisher:

Use a new publisher name.

Network Service Design (NSD) artifact upload failure

Artifact uploads using az aosm nsd publish command can fail on rare occasions. The error output in this case is

ValueError: Issue retrieving session url: {'errors': [{'code': 'UNAUTHORIZED', 'message': 'authentication required, visit https://aka.ms/acr/authorization for more information.', 'detail': [{'Type': 'repository', 'Name': 'contoso-nsd', 'Action': 'pull'}, {'Type': 'repository', 'Name': 'contoso-nsd', 'Action': 'push'}]}]}

To resolve this error:

Option 1. Confirm that you have the Contributor and AcrPush role assignments on the subscription you want to use. Assign them if you don't. If setting this role assignment isn't possible, run the az aosm nsd publish command with the --no-subscription-permissions parameter.

Option 2. If these permissions don't resolve the issue, run the following commands from the nsd-cli-output/artifacts folder created by the az aosm nsd build command:

  • Build the Network Function ARM Template from the BICEP file generated by the CLI
bicep build <nf-name>.bicep
  • Generate scope map token credentials from the Artifact Manifest created in the az aosm nsd publish command.

Important

You are required to use the Artifact Manifest created in the az aosm nsd publish command. The NF ARM template is only declared in that manifest hence only the scope map token generated by this manifest will allow you to push (or pull) the NF ARM template to the Artifact Store.

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'

oras login <aosm-managed-acr-name>.azurecr.io --username <username> --password <scope map token>
  • Use ORAS to upload the Network Function ARM template to the AOSM managed Azure Container Registry (ACR). The <arm-template-version> artifact tag must be in 1.0.0 format.
oras push <aosm-managed-acr-name>.azurecr.io/Contoso-nsd:<arm-template-version> ./nsd-cli-output/artifacts/<nf-name>.json

Cross-tenant copy failures

The Azure CLI AOSM Extension doesn't natively support cross-tenant image copies. However, it's possible to configure your CLI environment in a way that allows this functionality. The process is to set the default Azure subscription to the subscription that contains the source ACR, sign in to the source ACR, and then run all az aosm commands with the --subscription parameter, setting the value to the target subscription. The source and target subscriptions can be in different tenants.

az account set --subscription <source-acr-subscription>
az acr login --name <source-acr-name> -u <source-acr-username> -p <source-acr-password> --subscription <source-acr-subscription>
az aosm nfd publish --definition-type cnf --subscription <target-subscription>

Common misconfigurations

Site Network Service (SNS) deployment fails when Site and Network Service Design Version (NSDV) configuration don't match

SNS creation attempts fail if the nfvi property of the Site resource doesn't match the nfvisFromSite property of the NSDV. The error is

{
"statusMessage": "{\"status\":\"Failed\",\"error\":{\"code\":\"ResourceOperationFailure\",\"message\":\"The resource operation completed with terminal provisioning state 'Failed'.\",\"details\":[{\"code\":\"InvalidRequestContent\",\"message\":\"For NfviAlias = nfvi1, either NfviName = nsd-contoso_NFVI and NfviType = AzureCore does not match with site resource.\"}]}}",
}

In this example, the NSDV nfvisFromSite property contains:

    nfvisFromSite: {
      nfvi1: {
        name: 'nsd-contoso_NFVI1'
        type: 'AzureArcKubernetes'
      }

The Site resource nfvi property must match the name and type in the NSDV.

resource site 'Microsoft.HybridNetwork/sites@2023-09-01' = {
  name: 'contoso-site'
  location: 'eastus'
  properties: {
    nfvis : [
      {
        name: 'nsd-contoso_NFVI1'
        nfviType: 'AzureArcKubernetes'
        customLocationReference: {
          id: '<custom-location-arm-id>'
        }
      }
    ]
  }
}

The nfdvName in the Configuration Group Value (CGV) doesn't match the published Network Function Definition Version (NFDV)

Configuration group schemas generated by the Azure CLI AOSM Extension have a mandatory parameter called nfdvName. nfdvname is the name of the NFDV, which is a string in 1.0.0 format. It isn't the name of the Network Function (NF) or Network Function Definition Group (NFDG). The following example shows the correct usage.

{
    "nsd-contoso": {
        "nfdvName": "1.0.0",
        "deployParameters": [
            {}
        ],
        "customLocationId": "<custom-location-arm-id>",
        "managedIdentityId": "<managed-id-arm-id>"
    }
}

Incorrect CGV values property when exposing no parameters in a Configuration Group Schema (CGS)

Configuration group schemas generated by the Azure CLI AOSM Extension expose a deployParameters field that, by default, is an array of JSON objects. There are several reasons you might want to create a CGV with an empty deployParameters field:

  • You have no configuration exposed in the Configuration Group Schema and all values are set in the default values.yaml in the Helm chart.
  • You created a Configuration group schema that includes default values and you don't want to override them.

If you're creating a CGV with an empty deployParameters field, the field value must be an array containing an empty JSON object.

{
    "nsd-contoso": {
        "nfdv": "1.0.0",
        "deployParameters": [
            {}
        ],
        "customLocationId": "<custom-location-arm-id>",
        "managedIdentityId": "<managed-id-arm-id>"
    }
}

AOSM returns the following error message if the CGV contains an empty array (that is, []) instead of an array containing an empty object ([{}]).

{"code":"BadRequest","message":"NSDV ResourceElementTemplate (name: 'mco-nsdg', type: 'NetworkFunctionDefinition') expects at least one 'networkfunctions' resource in the associated template. Please use the type: 'ArmResourceDefinition' to install generic ARM resources."}

Mismatch between image property in helm charts and location in source ACR

The AOSM CLI requires that the images in your source registry are in the same repository structure as is written in your helm chart. For example, an image included in a helm chart as core/contoso-a:1.0.0 must be available in the source registry in a path that ends in core/contoso-a:1.0.0. Failure to upload the image to the correct path in the source registry causes az aosm nfd publish to fail with the following error.

Code: InvalidParameters
Message: Operation registries-cd9ad97d-f3a3-11ee-a728-6b163569f55a failed. Resource /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ContainerRegistry/registries/contoso Invalid message NotFound Not Found {"errors":[{"code":"MANIFEST_UNKNOWN","message":"manifest tagged by \"0.0.0-9\" is not found","detail":{"Tag":"0.0.0-9"}}]}

There are multiple solutions available.

  • Edit your helm chart, or pass in the image paths in values.yaml, and set the image paths to match the repository structure in your source registry.
  • Upload the images to your source registry such that the concatenation of "image_sources" in the cnf-input.jsonc file and the image path from the helm chart matches the uploaded location in the source registry.
  • The AOSM CLI stores metadata for the images it discovers in cnf-cli-output/artifacts/artifacts.json. The path the AOSM CLI searches in the source registry is <registry_name>/<registry_namespace>/<artifact_name>/<artifact_version>. You can manually edit this file so that the values match the image's location in your source ACR.

CGVs don't match CGS when parameter has null type

Currently, AOSM doesn't support null as a default value in deployParameters schema, which means that the default value null isn't allowed in Configuration Group Schemas either. To work around this issue, the AOSM CLI sets the default value for parameters of type null to be the string "null", which allows an NFDV to publish successfully.

When using the portal to create CGVs, your parameter autofills to have "null" as its value. If you don't change this value, the Portal shows an error message, saying: "New Configuration Group Value doesn't match the schema - please edit the values."

Screenshot of the portal where there's an error message because the configuration group values don't match the configuration group schema.

To fix this error, change "null" to null in the CGVs.

For example, originally we have the value "null":

"serviceAccount_name": "null",

Which must be changed to the value null.

"serviceAccount_name": null,