Azure CLI를 사용하여 클러스터 만들기 및 프로비전

아티클
10/01/2024

이 문서에서는 AzCLI(Azure 명령줄 인터페이스)를 사용하여 클러스터를 만드는 방법을 설명합니다. 또한 이 문서에서는 클러스터를 상태, 업데이트 또는 삭제하는 검사 방법을 보여줍니다.

필수 조건

네트워크 패브릭 컨트롤러 및 클러스터 관리자가 Azure 지역에 있는지 확인합니다.
Network Fabric이 성공적으로 프로비전되었는지 확인

API 가이드 및 메트릭

API 가이드는 리소스 공급자 및 리소스 모델과 API에 대한 정보를 제공합니다.

로깅 데이터에서 생성된 메트릭은 Azure Monitor 메트릭에서 사용할 수 있습니다.

제한 사항

명명 - 명명 규칙은 여기에서 찾을 수 있습니다.

클러스터 만들기

인프라 클러스터 리소스는 클러스터 관리자 내 플랫폼의 온-프레미스 배포를 나타냅니다. 다른 모든 플랫폼별 리소스는 해당 수명 주기에 따라 달라집니다.

이 온-프레미스 배포 전에 Network Fabric을 만들어야 합니다. 각 Operator Nexus 온-프레미스 인스턴스는 네트워크 패브릭과 일대일로 연결됩니다.

Azure CLI를 사용하여 클러스터를 만듭니다.

az networkcloud cluster create --name "$CLUSTER_NAME" --location "$LOCATION" \
  --extended-location name="$CL_NAME" type="CustomLocation" \
  --resource-group "$CLUSTER_RG" \
  --analytics-workspace-id "$LAW_ID" \
  --cluster-location "$CLUSTER_LOCATION" \
  --network-rack-id "$AGGR_RACK_RESOURCE_ID" \
  --rack-sku-id "$AGGR_RACK_SKU"\
  --rack-serial-number "$AGGR_RACK_SN" \
  --rack-location "$AGGR_RACK_LOCATION" \
  --bare-metal-machine-configuration-data "["$AGGR_RACK_BMM"]" \
  --storage-appliance-configuration-data '[{"adminCredentials":{"password":"$SA_PASS","username":"$SA_USER"},"rackSlot":1,"serialNumber":"$SA_SN","storageApplianceName":"$SA_NAME"}]' \
  --compute-rack-definitions '[{"networkRackId": "$COMPX_RACK_RESOURCE_ID", "rackSkuId": "$COMPX_RACK_SKU", "rackSerialNumber": "$COMPX_RACK_SN", "rackLocation": "$COMPX_RACK_LOCATION", "storageApplianceConfigurationData": [], "bareMetalMachineConfigurationData":[{"bmcCredentials": {"password":"$COMPX_SVRY_BMC_PASS", "username":"$COMPX_SVRY_BMC_USER"}, "bmcMacAddress":"$COMPX_SVRY_BMC_MAC", "bootMacAddress":"$COMPX_SVRY_BOOT_MAC", "machineDetails":"$COMPX_SVRY_SERVER_DETAILS", "machineName":"$COMPX_SVRY_SERVER_NAME"}]}]'\
  --managed-resource-group-configuration name="$MRG_NAME" location="$MRG_LOCATION" \
  --network fabric-id "$NF_ID" \
  --cluster-service-principal application-id="$SP_APP_ID" \
    password="$SP_PASS" principal-id="$SP_ID" tenant-id="$TENANT_ID" \
  --subscription "$SUBSCRIPTION_ID" \
  --secret-archive "{key-vault-id:$KVRESOURCE_ID, use-key-vault:true}" \
  --cluster-type "$CLUSTER_TYPE" --cluster-version "$CLUSTER_VERSION" \
  --tags $TAG_KEY1="$TAG_VALUE1" $TAG_KEY2="$TAG_VALUE2"

클러스터 작업을 위한 매개 변수

매개 변수 이름	설명
CLUSTER_NAME	클러스터의 리소스의 이름
위치	클러스터가 배포되는 Azure 지역
CL_NAME	Azure Portal의 클러스터 관리자 사용자 지정 위치
CLUSTER_RG	클러스터 리소스 그룹 이름
LAW_ID	클러스터에 대한 Log Analytics 작업 영역 ID
CLUSTER_LOCATION	클러스터의 로컬 이름
AGGR_RACK_RESOURCE_ID	Aggregator Rack용 RackID
AGGR_RACK_SKU	Aggregator Rack용 랙 SKU
AGGR_RACK_SN	Aggregator Rack의 랙 일련 번호
AGGR_RACK_LOCATION	Aggregator Rack의 랙 물리적 위치
AGGR_RACK_BMM	단일 랙 배포에만 사용되며 다중 랙에는 비어 있음
SA_NAME	스토리지 어플라이언스 디바이스 이름
SA_PASS	스토리지 어플라이언스 관리자 암호
SA_USER	스토리지 어플라이언스 관리 사용자
SA_SN	스토리지 어플라이언스 일련 번호
COMPX_RACK_RESOURCE_ID	CompX 랙용 RackID, compute-rack-definitions의 각 랙에 대해 반복
COMPX_RACK_SKU	CompX 랙용 랙 SKU, compute-rack-definitions의 각 랙에 대해 반복
COMPX_RACK_SN	CompX 랙용 랙 일련 번호, compute-rack-definitions의 각 랙에 대해 반복
COMPX_RACK_LOCATION	CompX 랙용 랙 물리적 위치, compute-rack-definitions의 각 랙에 대해 반복
COMPX_SVRY_BMC_PASS	CompX Rack ServerY BMC 암호; 컴퓨팅 랙 정의의 각 랙 및 랙의 각 서버에 대해 반복
COMPX_SVRY_BMC_USER	CompX Rack ServerY BMC 사용자; 컴퓨팅 랙 정의의 각 랙 및 랙의 각 서버에 대해 반복
COMPX_SVRY_BMC_MAC	CompX Rack ServerY BMC MAC 주소; 컴퓨팅 랙 정의의 각 랙 및 랙의 각 서버에 대해 반복
COMPX_SVRY_BOOT_MAC	CompX Rack ServerY 부팅 NIC MAC 주소; 컴퓨팅 랙 정의의 각 랙 및 랙의 각 서버에 대해 반복
COMPX_SVRY_SERVER_DETAILS	CompX Rack ServerY 세부 정보; 컴퓨팅 랙 정의의 각 랙 및 랙의 각 서버에 대해 반복
COMPX_SVRY_SERVER_NAME	CompX Rack ServerY 이름, compute-rack-definitions의 각 랙 및 랙의 각 서버에 대해 반복
MRG_NAME	클러스터 관리형 리소스 그룹 이름
MRG_LOCATION	클러스터 Azure 지역
NF_ID	네트워크 패브릭에 대한 참조
SP_APP_ID	서비스 주체 앱 ID
SP_PASS	서비스 주체 암호
SP_ID	서비스 주체 ID
TENANT_ID	구독 테넌트 ID
SUBSCRIPTION_ID	구독 ID
KV_RESOURCE_ID	Key Vault ID
CLUSTER_TYPE	클러스터 유형, 단일 또는 다중 랙
CLUSTER_VERSION	클러스터의 NC 버전
TAG_KEY1	Cluster Create에 전달할 선택적 tag1
TAG_VALUE1	Cluster Create에 전달할 선택적 tag1 값
TAG_KEY2	Cluster Create에 전달할 선택적 tag2
TAG_VALUE2	Cluster Create에 전달할 선택적 tag2 값

클러스터 ID

2024-07-01 API 버전부터 고객은 관리 ID를 클러스터에 할당할 수 있습니다. 시스템 할당 및 사용자 할당 관리 ID가 모두 지원됩니다.

다음 매개 변수를 제공하여 생성 또는 업데이트 작업 중에 관리 ID를 클러스터에 할당할 수 있습니다.

--mi-system-assigned - 시스템 할당 관리 ID를 사용하도록 설정합니다. 추가된 후에는 현재 API 호출을 통해서만 ID를 제거할 수 있습니다.
--mi-user-assigned - 추가할 사용자 할당 관리 ID의 공백으로 구분된 리소스 ID입니다. 추가된 후에는 현재 API 호출을 통해서만 ID를 제거할 수 있습니다.

Azure Resource Manager 템플릿 편집기를 사용하여 클러스터 만들기

클러스터를 만드는 다른 방법은 ARM 템플릿 편집기를 사용하는 것입니다.

이러한 방식으로 클러스터를 만들려면 템플릿 파일(cluster.jsonc) 및 매개 변수 파일(cluster.parameters.jsonc)을 제공해야 합니다. 다음 두 파일을 사용하여 8랙 2M16C SKU 클러스터에 대한 예제를 찾을 수 있습니다.

cluster.jsonc, cluster.parameters.jsonc

참고 항목

올바른 서식을 얻으려면 원시 코드 파일을 복사합니다. cluster.parameters.jsonc 파일 내의 값은 고객별 값이며 전체 목록이 아닐 수 있습니다. 특정 환경에 대한 값 필드를 업데이트합니다.

웹 브라우저에서 Azure Portal로 이동한 후 로그인합니다.
Azure Portal 검색 창에서 '사용자 지정 템플릿 배포'를 검색한 다음, 사용 가능한 서비스에서 선택합니다.
편집기에서 사용자 고유의 템플릿 만들기를 클릭합니다.
파일 로드를 클릭합니다. cluster.jsonc 템플릿 파일을 찾아 업로드합니다.
저장을 클릭합니다.
매개 변수 편집을 클릭합니다.
파일 로드를 클릭합니다. cluster.parameters.jsonc 매개 변수 파일을 찾아 업로드합니다.
저장을 클릭합니다.
올바른 구독을 선택합니다.
리소스 그룹을 검색하여 이미 존재하는지 확인합니다. 그렇지 않은 경우 새 리소스 그룹을 만듭니다.
모든 인스턴스 세부 정보가 올바른지 확인합니다.
검토 + 만들기를 클릭합니다.

클러스터 유효성 검사

Operator Nexus 클러스터가 성공적으로 만들어지면 구독 내에 AKS 클러스터가 만들어집니다. 클러스터 ID, 클러스터 프로비전 상태 및 배포 상태는 성공적인 cluster create의 결과로 반환됩니다.

클러스터 상태 보기:

az networkcloud cluster show --resource-group "$CLUSTER_RG" \
  --cluster-name "$CLUSTER_RESOURCE_NAME"

리소스의 provisioningState에 다음이 표시되면 클러스터 만들기가 완료된 것입니다. "provisioningState": "Succeeded"

클러스터 로그인

다음 위치에서 클러스터 생성 로그를 볼 수 있습니다.

Azure Portal Resource/ResourceGroup 활동 로그.
명령줄에 --debug 플래그가 전달된 Azure CLI.

클러스터 배포

클러스터를 만든 후 클러스터 배포 작업을 트리거할 수 있습니다. 클러스터 배포 작업은 부트스트랩 이미지를 만들고 클러스터를 배포합니다.

클러스터 배포는 클러스터 관리자에서 발생하는 일련의 이벤트를 시작합니다.

클러스터/랙 속성의 유효성 검사
임시 부트스트랩 클러스터의 부팅 가능한 이미지 생성(인프라 유효성 검사).
대상 부트스트랩 컴퓨터의 IPMI 인터페이스와 상호 작용합니다.
하드웨어 유효성 검사 수행
클러스터 배포 프로세스 모니터링.

온-프레미스 클러스터 배포:

az networkcloud cluster deploy \
  --name "$CLUSTER_NAME" \
  --resource-group "$CLUSTER_RG" \
  --subscription "$SUBSCRIPTION_ID" \
  --no-wait --debug

팁

az networkcloud cluster deploy 명령의 상태를 확인하려면 --debug 플래그를 사용하여 실행할 수 있습니다. 이렇게 하면 operationStatuses 리소스를 쿼리하는 데 사용되는 Azure-AsyncOperation 또는 Location 헤더를 가져올 수 있습니다. 자세한 단계는 클러스터 배포 실패 섹션을 참조하세요. 선택적으로 --no-wait 플래그를 사용하여 명령을 비동기적으로 실행할 수 있습니다.

하드웨어 유효성 검사를 통한 클러스터 배포

클러스터 배포 프로세스 중에 실행되는 단계 중 하나는 하드웨어 유효성 검사입니다. 하드웨어 유효성 검사 절차에서는 클러스터의 랙 정의를 통해 제공되는 컴퓨터에 대해 다양한 테스트 및 유효성 검사를 실행합니다. 이러한 검사 결과와 사용자가 건너뛴 컴퓨터를 기반으로 배포를 계속하는 데 필요한 임계값을 충족할 만큼 충분한 노드가 통과되었는지 및/또는 사용 가능한지 여부가 결정됩니다.

Important

하드웨어 유효성 검사 프로세스는 클러스터 만들 때 지정된 analyticsWorkspaceId에 결과를 기록합니다. 또한 클러스터 개체에 제공된 서비스 주체는 Log Analytics 작업 영역 데이터 수집 API에 대한 인증에 사용됩니다. 이 기능은 새 배포(녹색 필드) 중에만 표시됩니다. 기존 클러스터에는 소급하여 사용할 수 있는 로그가 없습니다.

기본적으로 하드웨어 유효성 검사 프로세스는 구성된 클러스터 analyticsWorkspaceId에 결과를 기록합니다. 그러나 Log Analytics 작업 영역 데이터 수집 및 스키마 평가의 특성으로 인해 몇 분 이상 걸릴 수 있는 수집 지연이 있을 수 있습니다. 이러한 이유로 Log Analytics 작업 영역에 결과를 쓰지 못하는 경우에도 클러스터 배포가 진행됩니다. 이 가능한 이벤트를 해결하는 데 도움이 되도록 중복성에 대한 결과도 클러스터 관리자 내에 기록됩니다.

제공된 클러스터 개체의 Log Analytics 작업 영역에 클러스터 이름이 접두사이고 접미사가 *_CL인 새 사용자 지정 테이블이 나타나야 합니다. LAW 리소스의 로그 섹션에서 새로운 *_CL 사용자 지정 로그 테이블에 대해 쿼리를 실행할 수 있습니다.

특정 운영 체제 미설치 컴퓨터를 건너뛰는 클러스터 배포 작업

하드웨어 유효성 검사 중에 건너뛰어야 하는 클러스터의 운영 체제 미설치 컴퓨터 이름을 나타내는 매개 변수를 배포 명령에 전달할 수 있습니다. 건너뛴 노드는 유효성 검사되지 않으며 노드 풀에 추가되지 않습니다. 또한 건너뛴 노드는 임계값 계산에 사용된 총계에 포함되지 않습니다.

az networkcloud cluster deploy \
  --name "$CLUSTER_NAME" \
  --resource-group "$CLUSTER_RG" \
  --subscription "$SUBSCRIPTION_ID" \
  --skip-validations-for-machines "$COMPX_SVRY_SERVER_NAME"

클러스터 배포 실패

비동기 작업의 상태를 추적하려면 --debug 플래그를 사용하도록 설정하여 실행합니다. --debug를 지정하면 요청 진행률을 모니터링할 수 있습니다. 작업 상태 URL은 만들기 요청에 대한 HTTP 응답에서 Azure-AsyncOperation 또는 Location 헤더를 찾는 디버그 출력을 검사하여 찾을 수 있습니다. 헤더는 HTTP API 호출에 사용되는 OPERATION_ID 필드를 제공할 수 있습니다.

OPERATION_ID="12312312-1231-1231-1231-123123123123*99399E995..."
az rest -m GET -u "https://management.azure.com/subscriptions/${SUBSCRIPTION_ID}/providers/Microsoft.NetworkCloud/locations/${LOCATION}/operationStatuses/${OPERATION_ID}?api-version=2022-12-12-preview"

출력은 JSON 구조체 예와 유사합니다. 오류 코드가 HardwareValidationThresholdFailed이면 오류 메시지에 하드웨어 유효성 검사에 실패한 운영 체제 미설치 컴퓨터 목록이 포함됩니다(예: COMP0_SVR0_SERVER_NAME, COMP1_SVR1_SERVER_NAME). 이러한 이름은 자세한 내용을 위해 로그를 구문 분석하는 데 사용될 수 있습니다.

{
  "endTime": "2023-03-24T14:56:59.0510455Z",
  "error": {
    "code": "HardwareValidationThresholdFailed",
    "message": "HardwareValidationThresholdFailed error hardware validation threshold for cluster layout plan is not met for cluster $CLUSTER_NAME in namespace nc-system with listed failed devices $COMP0_SVR0_SERVER_NAME, $COMP1_SVR1_SERVER_NAME"
  },
  "id": "/subscriptions/$SUBSCRIPTION_ID/providers/Microsoft.NetworkCloud/locations/$LOCATION/operationStatuses/12312312-1231-1231-1231-123123123123*99399E995...",
  "name": "12312312-1231-1231-1231-123123123123*99399E995...",
  "resourceId": "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$CLUSTER_RESOURCE_GROUP/providers/Microsoft.NetworkCloud/clusters/$CLUSTER_NAME",
  "startTime": "2023-03-24T14:56:26.6442125Z",
  "status": "Failed"
}

다른 예는 Azure CLI를 사용하여 비동기 작업 추적 문서를 참조하세요.

클러스터 배포 유효성 검사

포털에서 또는 Azure CLI를 통해 클러스터 상태를 확인합니다.

az networkcloud cluster show --resource-group "$CLUSTER_RG" \
  --name "$CLUSTER_NAME"

detailedStatus가 Deploying으로 설정되고 detailedStatusMessage에 배포 진행률이 표시되면 클러스터 배포가 진행 중입니다. detailedStatusMessage에 표시되는 배포 진행률의 몇 가지 예는 Hardware validation is in progress.(클러스터가 하드웨어 유효성 검사를 통해 배포된 경우),Cluster is bootstrapping., KCP initialization in progress., Management plane deployment in progress., Cluster extension deployment in progress., waiting for "<rack-ids>" to be ready 등입니다.

detailedStatus가 Running으로 설정되고 trendyStatusMessage에 Cluster is up and running 메시지가 표시되면 클러스터 배포가 완료됩니다.

클러스터의 관리 버전을 확인합니다.

az k8s-extension list --cluster-name "$CLUSTER_NAME" --resource-group "$MRG_NAME" --cluster-type connectedClusters --query "[?name=='nc-platform-extension'].{name:name, extensionType:extensionType, releaseNamespace:scope.cluster.releaseNamespace,provisioningState:provisioningState,version:version}" -o table --subscription "$SUBSCRIPTION_ID"

클러스터 배포 로깅

다음 위치에서 클러스터 생성 로그를 볼 수 있습니다.

Azure Portal Resource/ResourceGroup 활동 로그.
명령줄에 --debug 플래그가 전달된 Azure CLI.

API를 통해 클러스터 ID 업데이트

CLI를 통해 클러스터 관리 ID를 할당할 수 있습니다. ID의 할당 해제는 API 호출을 통해 수행할 수 있습니다. <APIVersion> API 버전 2024-07-01 이상입니다.

모든 관리 ID를 제거하려면 다음을 실행합니다.

az rest --method PATCH --url /subscriptions/$SUB_ID/resourceGroups/$CLUSTER_RG/providers/Microsoft.NetworkCloud/clusters/$CLUSTER_NAME?api-version=<APIVersion> --body "{\"identity\":{\"type\":\"None\"}}"

사용자 할당 및 시스템 할당 관리 ID가 모두 추가된 경우 다음을 업데이트하여 사용자 할당을 type SystemAssigned제거할 수 있습니다.

az rest --method PATCH --url /subscriptions/$SUB_ID/resourceGroups/$CLUSTER_RG/providers/Microsoft.NetworkCloud/clusters/$CLUSTER_NAME?api-version=<APIVersion> --body @~/uai-body.json

요청 본문(uai-body.json) 예제:

{
  "identity": {
      "type": "SystemAssigned"
  }
}

사용자 할당 및 시스템 할당 관리 ID가 모두 추가된 경우 다음을 업데이트 type UserAssigned하여 시스템 할당을 제거할 수 있습니다.

az rest --method PATCH --url /subscriptions/$SUB_ID/resourceGroups/$CLUSTER_RG/providers/Microsoft.NetworkCloud/clusters/$CLUSTER_NAME?api-version=<APIVersion> --body @~/uai-body.json

요청 본문(uai-body.json) 예제:

{
  "identity": {
      "type": "UserAssigned",
  	"userAssignedIdentities": {
  		"/subscriptions/$SUB_ID/resourceGroups/$UAI_RESOURCE_GROUP/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$UAI_NAME": {}
  	}
  }
}

여러 사용자 할당 관리 ID가 추가된 경우 다음을 실행하여 해당 ID 중 하나를 제거할 수 있습니다.

az rest --method PATCH --url /subscriptions/$SUB_ID/resourceGroups/$CLUSTER_RG/providers/Microsoft.NetworkCloud/clusters/$CLUSTER_NAME?api-version=<APIVersion> --body @~/uai-body.json

요청 본문(uai-body.json) 예제:

{
  "identity": {
      "type": "UserAssigned",
  	"userAssignedIdentities": {
  		"/subscriptions/$SUB_ID/resourceGroups/$UAI_RESOURCE_GROUP/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$UAI_NAME": null
  	}
  }
}

클러스터 삭제

클러스터를 삭제하면 Azure의 리소스와 온-프레미스 환경에 있는 클러스터가 삭제됩니다.

참고 항목

클러스터에 테넌트 리소스가 있는 경우 해당 리소스가 삭제될 때까지 클러스터가 삭제되지 않습니다.

az networkcloud cluster delete --name "$CLUSTER_NAME" --resource-group "$CLUSTER_RG"

다음을 통해 공유

Azure CLI를 사용하여 클러스터 만들기 및 프로비전

필수 조건

API 가이드 및 메트릭

제한 사항

클러스터 만들기

Azure CLI를 사용하여 클러스터를 만듭니다.

클러스터 작업을 위한 매개 변수

클러스터 ID

Azure Resource Manager 템플릿 편집기를 사용하여 클러스터 만들기

클러스터 유효성 검사

클러스터 로그인

클러스터 배포

하드웨어 유효성 검사를 통한 클러스터 배포

특정 운영 체제 미설치 컴퓨터를 건너뛰는 클러스터 배포 작업

클러스터 배포 실패

클러스터 배포 유효성 검사

클러스터 배포 로깅

API를 통해 클러스터 ID 업데이트

클러스터 삭제

피드백

추가 리소스