共用方式為

Azure CLI Azure 運算子服務管理員 (AOSM) 延伸模組問題

  • 發行項

本文件包含使用 Azure CLI AOSM 延伸模組將網路功能上線時所發生的常見問題清單，及其解決方法。

常見問題

發行者已存在於區域中

發行者名稱在 Azure 區域內必須是唯一的。 如果您看到下列錯誤，表示您選擇的發行者名稱已在使用中：

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

若要解決此錯誤：

如果您擁有發行者，它位於您的租用戶中，且您想要重複使用它：

發行者定義於您的 AOSM CLI 延伸模組設定檔中。 publisher_name 和 publisher_resource_group_name 欄位必須符合現有發行者的資料，而且必須位於您在此部署中所使用的租用戶中。

變更設定檔中的 publisher_resource_group_name，使其參考現有的發行者，重新執行對應的 build 命令，然後重新執行 publish 命令。

您未擁有現有的發行者：

使用新的發行者名稱。

網路服務設計 (NSD) 成品上傳失敗

使用 az aosm nsd publish 命令的成品上傳在極少數情況下可能會失敗。 在此情況下，錯誤輸出為

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

若要解決此錯誤：

選項 1。 確認您在要使用的訂用帳戶上具有 Contributor 和 AcrPush 角色指派。 如果您沒有，請指派這些角色。 如果無法設定此角色指派，請使用 az aosm nsd publish 命令搭配 --no-subscription-permissions 參數。

選項 2。 如果這些權限無法解決問題，請從 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'

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 格式。
oras push <aosm-managed-acr-name>.azurecr.io/Contoso-nsd:<arm-template-version> ./nsd-cli-output/artifacts/<nf-name>.json

跨租用戶複製失敗

Azure CLI AOSM 延伸模組不提供跨租用戶映像複本的原生支援。 不過，您可以透過允許這項功能的方式設定 CLI 環境。 此程序是將預設 Azure 訂用帳戶設定為含有來源 ACR 的訂用帳戶、登入來源 ACR，然後使用 --subscription 參數執行所有 az aosm 命令，將該值設定為目標訂用帳戶。 來源和目標訂用帳戶可以位於不同的租用戶。

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>

常見錯誤設定

網站和網路服務設計版本 (NSDV) 設定不相符時，網站網路服務 (SNS) 部署會失敗

如果網站資源的 nfvi 屬性不符合 NSDV 的 nfvisFromSite 屬性，SNS 建立嘗試會失敗。 錯誤碼為

{
"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.\"}]}}",
}

在此範例中，NSDV nfvisFromSite 屬性包含：

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

網站資源 nfvi 屬性必須符合 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>'
        }
      }
    ]
  }
}

設定群組值 (CGV) 中的 nfdvName 不符合已發佈的網路功能定義版本 (NFDV)

Azure CLI AOSM 延伸模組所產生的設定群組結構描述具有稱為 nfdvName 的必要參數。 nfdvname 是 NFDV 的名稱，為格式 1.0.0 的字串。 它不是網路功能 (NF) 或網路功能定義群組 (NFDG) 的名稱。 下列範例顯示正確的使用方式。

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

設定群組結構描述 (CGS) 公開任何參數時，CGV 值屬性不正確

Azure CLI AOSM 延伸模組產生的設定設定群組結構描述會公開 deployParameters 欄位，該欄位預設為 JSON 物件陣列。 您可能會因為下列幾個原因而想要建立含有空白 deployParameters 欄位的 CGV：

  • 設定群組結構描述未公開任何設定，且所有值都在 Helm 圖表的預設 values.yaml 中設定。
  • 您已建立包含預設值的設定群組結構描述，且不想覆寫它們。

如果您要建立含有空白 deployParameters 欄位的 CGV，則該欄位值必須是包含空白 JSON 物件的陣列。

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

如果 CGV 包含空陣列 (也就是 [])，而不是含有空物件 ([{}]) 的陣列，則 AOSM 會傳回下列錯誤訊息。

{"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."}

helm 圖表中的映像屬性與來源 ACR 中的位置不符

AOSM CLI 要求來源登錄中的映像位於 helm 圖表中寫入的相同存放庫結構。 例如，helm 圖表以 core/contoso-a:1.0.0 所含的映像必須位於來源登錄中結尾為 core/contoso-a:1.0.0 的路徑。 無法將映像上傳至來源登錄中的正確路徑會導致 az aosm nfd publish 失敗並顯示下列錯誤。

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

有多個可用的解決方案。

  • 編輯您的 helm 圖表，或在 values.yaml 中傳入映像路徑，並設定映像路徑以符合來源登錄中的存放庫結構。
  • 將映像上傳至來源登錄，使 cnf-input.jsonc 檔案中的 "image_sources" 串連在一起，且 helm 圖表中的映像路徑符合來源登錄中上傳位置。
  • AOSM CLI 會儲存 cnf-cli-output/artifacts/artifacts.json 中探索到的映像中繼資料。 AOSM CLI 在來源登錄中搜尋的路徑為 <registry_name>/<registry_namespace>/<artifact_name>/<artifact_version>。 您可以手動編輯此檔案，讓值符合來源 ACR 中的映像位置。

當參數具有 Null 類型時，CGV 不符合 CGS

目前，AOSM 不支援 null 作為 deployParameters 結構描述中的預設值，這表示設定群組結構描述也不允許預設值 null。 為了解決此問題，AOSM CLI 會將 null 類型的參數預設值設定為字串 "null"，讓 NFDV 可以成功發佈。

使用入口網站建立 CGV 時，您的參數會自動填入 "null" 作為其值。 如果您未變更此值，入口網站會顯示錯誤訊息，指出：「新的設定群組值不符合結構描述 - 請編輯值」。

此螢幕擷取畫面顯示入口網站中的錯誤訊息，因為設定群組值不符合設定群組結構描述。

若要修正此錯誤，請將 CGV 中的 "null" 變更為 null。

例如，我們原本有值 "null"：

"serviceAccount_name": "null",

必須變更為值 null。

"serviceAccount_name": null,