Azure Arc 지원 Kubernetes 클러스터에 대한 플랫폼 문제 해결

아티클
11/01/2024

이 문서는 Azure Arc 지원 Kubernetes 연결, 권한 및 에이전트 문제에 대한 문제 해결 가이드를 제공합니다. 또한 Azure Arc 지원 Kubernetes 또는 AKS(Azure Kubernetes Service) 클러스터에서 사용할 수 있는 Azure GitOps에 대한 문제 해결 가이드를 제공합니다.

GitOps(Flux v2), Azure Monitor Container Insights, Open Service Mesh와 같은 확장과 관련된 문제를 해결하는 데 도움이 필요하면 Azure Arc 지원 Kubernetes 클러스터의 확장 문제 해결을 참조하세요.

Azure CLI

az connectedk8s 또는 az k8s-configuration CLI 명령을 사용하기 전에 Azure CLI가 올바른 Azure 구독에 대해 작동하도록 설정되어 있는지 확인합니다.

az account set --subscription 'subscriptionId'
az account show

와 같은 cli.azext_connectedk8s.custom: Failed to download and install kubectl오류가 표시되면 다시 실행하기 전에 실행 az aks install-cli --install-location ~/.azure/kubectl-client/kubectl az connectedk8s connect 합니다. 이 명령은 명령이 작동하는 데 필요한 kubectl 클라이언트를 설치합니다.

Azure Arc 에이전트

Azure Arc 지원 Kubernetes에 대한 모든 에이전트는 네임스페이스에서 azure-arc Pod로 배포됩니다. 모든 Pod가 실행되고 상태 검사를 통과해야 합니다.

먼저, Azure Arc Helm Chart 릴리스를 확인합니다.

$ helm --namespace default status azure-arc
NAME: azure-arc
LAST DEPLOYED: Fri Apr  3 11:13:10 2020
NAMESPACE: default
STATUS: deployed
REVISION: 5
TEST SUITE: None

Helm Chart 릴리스를 찾을 수 없거나 누락된 경우 다시 클러스터를 Azure Arc에 연결해 봅니다.

Helm 차트 릴리스가 STATUS: deployed과 함께 있는 경우 kubectl를 사용하여 에이전트의 상태를 확인합니다.

$ kubectl -n azure-arc get deployments,pods
NAME                                         READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/cluster-metadata-operator    1/1     1            1           3d19h
deployment.apps/clusterconnect-agent         1/1     1            1           3d19h
deployment.apps/clusteridentityoperator      1/1     1            1           3d19h
deployment.apps/config-agent                 1/1     1            1           3d19h
deployment.apps/controller-manager           1/1     1            1           3d19h
deployment.apps/extension-events-collector   1/1     1            1           3d19h
deployment.apps/extension-manager            1/1     1            1           3d19h
deployment.apps/flux-logs-agent              1/1     1            1           3d19h
deployment.apps/kube-aad-proxy               1/1     1            1           3d19h
deployment.apps/metrics-agent                1/1     1            1           3d19h
deployment.apps/resource-sync-agent          1/1     1            1           3d19h

NAME                                              READY   STATUS    RESTARTS        AGE
pod/cluster-metadata-operator-74747b975-9phtz     2/2     Running   0               3d19h
pod/clusterconnect-agent-cf4c7849c-88fmf          3/3     Running   0               3d19h
pod/clusteridentityoperator-79bdfd945f-pt2rv      2/2     Running   0               3d19h
pod/config-agent-67bcb94b7c-d67t8                 1/2     Running   0               3d19h
pod/controller-manager-559dd48b64-v6rmk           2/2     Running   0               3d19h
pod/extension-events-collector-85f4fbff69-55zmt   2/2     Running   0               3d19h
pod/extension-manager-7c7668446b-69gps            3/3     Running   0               3d19h
pod/flux-logs-agent-fc7c6c959-vgqvm               1/1     Running   0               3d19h
pod/kube-aad-proxy-84d668c44b-j457m               2/2     Running   0               3d19h
pod/metrics-agent-58fb8554df-5ll67                2/2     Running   0               3d19h
pod/resource-sync-agent-dbf5db848-c9lg8           2/2     Running   0               3d19h

모든 Pod는 READY 열에 3/3 또는 2/2가 있으며 STATUS를 Running으로 표시해야 합니다. 로그를 가져오고 Error 또는 CrashLoopBackOff를 반환하는 Pod를 설명합니다. Pod가 Pending 상태에서 중단되면 클러스터 노드에 리소스가 부족할 수 있습니다. 클러스터를 스케일 업하면 이러한 pod가 Running 상태로 전환될 수 있습니다.

리소스 프로비저닝 실패/서비스 시간 제한 오류

이러한 오류가 표시되면 Azure 상태를 확인하여 Azure Arc 지원 Kubernetes 서비스의 상태에 영향을 미치는 활성 이벤트가 있는지 확인합니다. 그렇다면 서비스 이벤트가 해결될 때까지 기다린 다음, 연결된 기존 클러스터 리소스를 삭제한 후 다시 온보딩을 시도합니다. 서비스 이벤트가 없고 온보딩하는 동안 문제가 계속 발생하는 경우 문제를 조사할 수 있도록 지원 요청을 엽니다.

초과분 클레임 오류

초과분 클레임을 수신하는 경우 서비스 주체가 200가 넘는 Microsoft Entra 그룹에 속하지 않는지 확인합니다. 이 경우 200개가 넘는 그룹의 멤버가 아닌 다른 서비스 주체를 만들어 사용하거나 일부 그룹에서 원래 서비스 주체를 제거하고 다시 시도해야 합니다.

아웃바운드 트래픽에 대한 엔드포인트 https://<region>.obo.arc.azure.com:8084/를 허용하지 않고 아웃바운드 프록시 환경을 구성한 경우에도 초과분 클레임이 발생할 수 있습니다.

둘 다 적용되지 않으면 지원 요청을 열어 문제를 살펴볼 수 있습니다.

Kubernetes 클러스터를 Azure Arc에 연결할 때 발생하는 문제

클러스터를 Azure Arc에 연결하려면 Azure 구독에 대한 액세스 권한과 대상 클러스터에 대한 cluster-admin 액세스 권한이 필요합니다. 클러스터에 연결할 수 없거나 권한이 충분하지 않으면 클러스터를 Azure Arc에 연결할 수 없습니다. 클러스터 연결을 위한 필수 구성 요소를 모두 충족했는지 확인합니다.

팁

연결 문제를 해결하기 위한 시각적 가이드는 Arc 지원 Kubernetes 클러스터의 연결 문제 진단을 참조하세요.

DNS 확인 문제

클러스터의 DNS 확인과 관련된 문제에 대한 도움말은 DNS 확인 디버깅을 참조하세요.

아웃바운드 네트워크 연결 문제

클러스터의 아웃바운드 네트워크 연결 문제는 여러 가지 이유로 발생할 수 있습니다. 먼저 모든 네트워크 요구 사항이 충족되었는지 확인합니다.

연결 문제가 발생하고 클러스터가 아웃바운드 프록시 서버 뒤에 있는 경우 클러스터를 온보딩하는 동안 프록시 매개 변수를 전달하고 프록시가 올바르게 구성되었는지 확인합니다. 자세한 내용은 아웃바운드 프록시 서버를 사용하여 연결을 참조하세요.

다음과 유사한 오류가 표시될 수 있습니다.

An exception has occurred while trying to execute the cluster diagnostic checks in the cluster. Exception: Unable to pull cluster-diagnostic-checks helm chart from the registry 'mcr.microsoft.com/azurearck8s/helmchart/stable/clusterdiagnosticchecks:0.1.2': Error: failed to do request: Head "https://mcr.microsoft.com/v2/azurearck8s/helmchart/stable/clusterdiagnosticchecks/manifests/0.1.2": dial tcp xx.xx.xx.219:443: i/o timeout

이 오류는 https://k8connecthelm.azureedge.net 엔드포인트가 차단될 때 발생합니다. 네트워크에서 이 엔드포인트에 대한 연결을 허용하고 다른 네트워킹 요구 사항을 모두 충족하는지 확인합니다.

MSI 인증서를 검색할 수 없음

MSI 인증서 검색 문제는 일반적으로 네트워크 문제로 인해 발생합니다. 모든 네트워크 요구 사항이 충족되었는지 확인한 다음, 다시 시도합니다.

클러스터 권한 부족

제공된 kubeconfig 파일에 Azure Arc 에이전트를 설치할 수 있는 충분한 권한이 없는 경우 Azure CLI 명령은 오류(Error: list: failed to list: secrets is forbidden: User "myuser" cannot list resource "secrets" in API group "" at the cluster scope)를 반환합니다.

이 문제를 해결하려면 클러스터를 Azure Arc에 연결하는 사용자에게 할당된 cluster-admin 역할이 있는지 확인합니다.

OpenShift 클러스터를 Azure Arc에 연결할 수 없음

OpenShift 클러스터를 Azure Arc에 연결할 때 az connectedk8s connect가 시간 초과되어 실패하는 경우:

OpenShift 클러스터가 버전 필수 구성 요소(4.5.41+ 또는 4.6.35+ 또는 4.7.18+)를 충족하는지 확인합니다.

az connectedk8s connnect를 실행하기 전에 클러스터에서 다음 명령을 실행합니다.

oc adm policy add-scc-to-user privileged system:serviceaccount:azure-arc:azure-arc-kube-aad-proxy-sa

설치 시간 초과

Kubernetes 클러스터를 Azure Arc 지원 Kubernetes에 연결하려면 클러스터에 Azure Arc 에이전트를 설치해야 합니다. 클러스터가 저속 인터넷 연결을 통해 실행되는 경우 에이전트에 대한 컨테이너 이미지 풀링은 Azure CLI 시간 제한보다 오래 걸릴 수 있습니다.

Helm 시간 초과 오류

오류 Unable to install helm release: Error: UPGRADE Failed: time out waiting for the condition이 표시할 수 있습니다. 이 문제를 해결하려면 다음 단계를 시도합니다.

다음 명령을 실행합니다.
```
kubectl get pods -n azure-arc
```

clusterconnect-agent 또는 config-agent Pod가 crashloopbackoff를 표시하는지 또는 일부 컨테이너가 실행되고 있지 않은지 확인합니다.

NAME                                        READY   STATUS             RESTARTS   AGE
cluster-metadata-operator-664bc5f4d-chgkl   2/2     Running            0          4m14s
clusterconnect-agent-7cb8b565c7-wklsh       2/3     CrashLoopBackOff   0          1m15s
clusteridentityoperator-76d645d8bf-5qx5c    2/2     Running            0          4m15s
config-agent-65d5df564f-lffqm               1/2     CrashLoopBackOff   0          1m14s

azure-identity-certificate가 없는 경우 시스템 할당 관리 ID가 설치되지 않았습니다.
```
kubectl get secret -n azure-arc -o yaml | grep name:
```
```
name: azure-identity-certificate
```
이 문제를 해결하려면 az connectedk8s delete 명령을 실행하고 다시 설치하여 Arc 배포를 삭제해 봅니다. 문제가 계속 발생하면 프록시 설정에 문제가 있을 수 있습니다. 이 경우 프록시를 통해 클러스터를 Azure Arc에 연결하여 프록시를 통해 클러스터를 Arc에 연결해 봅니다. 또한 모든 네트워크 필수 구성 요소가 충족되었는지 확인합니다.
clusterconnect-agent 및 config-agent Pod가 실행 중이지만 kube-aad-proxy Pod가 누락된 경우 Pod 보안 정책을 확인합니다. 이 포드는 관리자 권한이 없지만 호스트 경로를 탑재할 수 있는 권한이 필요한 azure-arc-kube-aad-proxy-sa 서비스 계정을 사용합니다.
kube-aad-proxy 포드가 ContainerCreating 상태에서 멈추면 kube-aad-proxy 인증서가 클러스터에 다운로드되었는지 확인합니다.
```
kubectl get secret -n azure-arc -o yaml | grep name:
```
```
name: kube-aad-proxy-certificate
```
인증서가 누락된 경우 배포를 삭제하고 클러스터에 다른 이름을 사용하여 온보딩을 다시 시도합니다. 문제가 계속되면 지원 요청을 엽니다.

CryptoHash 모듈 오류

Kubernetes 클러스터를 Azure Arc 플랫폼에 온보딩하려고 하면 로컬 환경(예: 클라이언트 콘솔)에서 다음 오류 메시지를 반환할 수 있습니다.

Cannot load native module 'Crypto.Hash._MD5'

경우에 따라 Azure CLI 또는 Azure PowerShell을 통해 확장 connectedk8s 및 k8s-configuration를 추가할 때 종속 모듈이 성공적으로 다운로드되지 않습니다. 이 문제를 해결하려면 로컬 환경에서 확장을 수동으로 제거한 다음, 추가합니다.

확장을 제거하려면 다음을 사용합니다.

az extension remove --name connectedk8s
az extension remove --name k8s-configuration

확장을 추가하려면 다음을 사용합니다.

az extension add --name connectedk8s
az extension add --name k8s-configuration

클러스터 연결 문제

클러스터가 아웃바운드 프록시 또는 방화벽 뒤에 있는 경우 특히 클러스터 연결 기능에 필요한 *.servicebus.windows.net에 대해 websocket 연결을 사용하는지 확인합니다. 또한 클러스터 연결을 사용하는 데 문제가 발생하는 경우 최신 버전의 connectedk8s Azure CLI 확장을 사용하고 있는지 확인합니다.

clusterconnect-agent 및 kube-aad-proxy Pod가 누락된 경우 클러스터에서 클러스터 연결 기능을 사용하지 않도록 설정할 수 있습니다. 이 az connectedk8s proxy 경우 클러스터를 사용하여 세션을 설정하지 못하면 오류 읽기가 표시 될 수 있습니다. Cannot connect to the hybrid connection because no agent is connected in the target arc resource.

이 오류를 해결하려면 클러스터에서 클러스터 연결 기능을 사용하도록 설정합니다.

az connectedk8s enable-features --features cluster-connect -n $CLUSTER_NAME -g $RESOURCE_GROUP

자세한 내용은 클러스터 연결을 사용하여 Azure Arc 지원 Kubernetes 클러스터에 안전하게 연결을 참조하세요.

서비스 주체를 사용하여 사용자 지정 위치 사용

클러스터를 Azure Arc에 연결하거나 기존 클러스터에서 사용자 지정 위치를 사용하도록 설정하는 경우 다음과 같은 경고가 표시될 수 있습니다.

Unable to fetch oid of 'custom-locations' app. Proceeding without enabling the feature. Insufficient privileges to complete the operation.

이 경고는 서비스 주체를 사용하여 Azure에 로그인하는데 서비스 주체에 필요한 권한이 없는 경우에 발생합니다. 이 오류를 방지하려면 다음 단계를 수행합니다.

사용자 계정을 사용하여 Azure CLI에 로그인합니다. Azure Arc 서비스에서 사용하는 Microsoft Entra 애플리케이션의 개체 ID를 검색합니다.
```
az ad sp show --id bc313c14-388c-4e7d-a58e-70017303ee3b --query objectId -o tsv
```
서비스 주체를 사용하여 Azure CLI에 로그인합니다. 이전 단계의 <objectId> 값을 사용하여 클러스터에서 사용자 지정 위치를 사용하도록 설정합니다.
- 클러스터를 Arc에 연결할 때 사용자 지정 위치를 사용하도록 설정하려면 az connectedk8s connect -n <cluster-name> -g <resource-group-name> --custom-locations-oid <objectId>를 실행합니다.
- 기존 Azure Arc 지원 Kubernetes 클러스터에서 사용자 지정 위치를 사용하도록 설정하려면 az connectedk8s enable-features -n <cluster-name> -g <resource-group-name> --custom-locations-oid <objectId> --features cluster-connect custom-locations을 실행합니다.

다음 단계

연결 문제를 진단하는 방법을 시각적으로 살펴봅니다.
클러스터 확장과 관련된 문제 해결 팁을 확인합니다.

다음을 통해 공유