Helm 옵션 매개 변수를 사용하여 설치 실패 시 삭제 방지

아티클
05/24/2024

기본 NF(네트워크 기능) 배포가 올바르게 설치되지 않아 SNS(사이트 네트워크 서비스) 배포가 실패할 수 있습니다. AOSM(Azure Operator Service Manager)은 기본적으로 대상 Kubernetes 클러스터에서 실패한 배포를 제거하여 리소스를 보존합니다. Helm install 오류가 발생하면 오류를 디버깅할 수 있도록 리소스가 클러스터에 유지되어야 하는 경우가 많습니다. 이 방법 문서에서는 helm install --atomic 매개 변수를 false로 설정하여 이 동작을 재정의하도록 NF ARM 템플릿을 편집하는 방법을 다룹니다.

필수 조건

Az CLI AOSM 확장을 사용하여 NF를 AOSM에 온보딩해야 합니다. 이 문서에서는 CLI의 폴더 구조와 파일 출력을 참조하고 CLI 기반 예를 제공합니다.
Helm 설치 실패는 복잡할 수 있습니다. 디버깅에는 NF에 대한 도메인 지식 외에도 여러 기술에 대한 기술적 지식이 필요합니다.
- Helm에 대한 실무 지식
- Kubernetes 및 kubectl 명령에 대한 실무 지식
- Azure Container Registry로 아티팩트 끌어오기 및 푸시에 대한 실무 지식
AOSM 관리 아티팩트 저장소가 포함된 리소스 그룹에 대해 Contributor 역할 할당이 필요합니다.
Visual Studio Code와 같은 적합한 IDE
ORAS CLI

Important

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 디렉터리를 열고 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 명령으로 만들어진 아티팩트 매니페스트에서 범위 맵 토큰 자격 증명을 만듭니다.

Important

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를 사용하여 AOSM 관리 ACR(Azure Container Registry)에 네트워크 기능 ARM 템플릿을 업로드합니다. <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 차트당 하나씩)으로 설치됩니다.

다중 Helm NF에 대해 --atomic를 재정의하는 프로세스는 ARM 템플릿에 대한 편집 내용을 제외하면 단일 Helm NF의 경우와 동일합니다.

가상의 다중 Helm NF인 Contoso-multi-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 매개 변수는 이러한 네트워크 기능 애플리케이션 각각에 대해 독립적으로 재정의될 수 있습니다. 다음은 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를 삭제하고 운영자 빠른 시작에 따라 다시 배포하여 빠른 시작 NF 매개 변수를 네트워크 기능에 대한 매개 변수로 바꿀 수도 있습니다. Kubernetes 클러스터에 배포된 Helm 릴리스는 실패 시 제거되지 않습니다. SNS 배포 실패를 디버그하는 방법에서는 일반적인 Helm 설치 실패를 디버깅하기 위한 도구 키트를 설명합니다.

다음을 통해 공유

Helm 옵션 매개 변수를 사용하여 설치 실패 시 삭제 방지

필수 조건

단일 Helm 차트 NF에 대해 `--atomic` 재정의

NF BICEP 템플릿 찾기 및 편집

편집된 ARM 템플릿을 빌드하고 아티팩트 저장소에 업로드합니다.

다중 Helm 차트 NF의 경우 `--atomic` 재정의

다음 단계

피드백

추가 리소스

다음을 통해 공유

Helm 옵션 매개 변수를 사용하여 설치 실패 시 삭제 방지

필수 조건

단일 Helm 차트 NF에 대해 --atomic 재정의

NF BICEP 템플릿 찾기 및 편집

편집된 ARM 템플릿을 빌드하고 아티팩트 저장소에 업로드합니다.

다중 Helm 차트 NF의 경우 --atomic 재정의

다음 단계

피드백

추가 리소스

단일 Helm 차트 NF에 대해 `--atomic` 재정의

다중 Helm 차트 NF의 경우 `--atomic` 재정의