클러스터 연결을 사용하여 Azure Arc 지원 Kubernetes 클러스터에 안전하게 연결합니다.

아티클
09/23/2024

클러스터 연결을 사용하면 방화벽에서 인바운드 포트를 사용하도록 설정하지 않고도 어디서나 Azure Arc 지원 Kubernetes 클러스터에 안전하게 연결할 수 있습니다.

Azure Arc 지원 Kubernetes 클러스터의 apiserver에 액세스하면 다음과 같은 시나리오를 사용할 수 있습니다.

대화형 디버깅 및 문제 해결.
사용자 지정 위치 및 그 위에 만들어진 기타 리소스에 대한 Azure 서비스에 대한 클러스터 액세스입니다.

시작하기 전에 클러스터 연결 기능의 개념적 개요를 검토합니다.

필수 조건

활성 구독이 있는 Azure 계정. 체험 계정을 만듭니다.
기존 Azure Arc 지원 Kubernetes 연결 클러스터.
- 아직 클러스터를 연결하지 않은 경우 빠른 시작을 사용합니다.
- 최신 버전으로 에이전트를 업그레이드합니다.
Arc 지원 Kubernetes에 대한 네트워크 요구 사항 사용
아웃바운드 액세스를 위해 다음 엔드포인트를 사용하도록 설정합니다.

엔드포인트 포트

*.servicebus.windows.net 443

guestnotificationservice.azure.com, *.guestnotificationservice.azure.com 443

참고 항목

*.servicebus.windows.net 와일드카드를 특정 엔드포인트로 변환하려면 \GET https://guestnotificationservice.azure.com/urls/allowlist?api-version=2020-01-01&location=<location> 명령을 사용합니다. 이 명령 내에서 <location> 자리 표시자에 대한 지역을 지정해야 합니다.

엔드포인트	포트
`*.servicebus.windows.net`	443
`guestnotificationservice.azure.com`, `*.guestnotificationservice.azure.com`	443

지역 엔드포인트의 지역 세그먼트를 가져오려면 Azure 지역 이름에서 모든 공백을 제거합니다. 예를 들어, 미국 동부 2 지역의 경우 지역 이름은 eastus2입니다.

예: *.<region>.arcdataservices.com은 미국 동부 2 지역에서 *.eastus2.arcdataservices.com여야 합니다.

모든 지역 목록을 보려면 다음 명령을 실행합니다.

az account list-locations -o table

Get-AzLocation | Format-Table

Azure CLI
Azure PowerShell

Azure CLI를 최신 버전으로 설치하거나 업데이트합니다.
최신 버전의 connectedk8s Azure CLI 확장을 설치합니다.
```
az extension add --name connectedk8s
```
connectedk8s 확장을 이미 설치한 경우 최신 버전의 확장으로 업데이트합니다.
```
az extension update --name connectedk8s
```

자리 표시자를 바꾸고 아래 명령을 실행하여 이 문서에 사용된 환경 변수를 설정합니다.

CLUSTER_NAME=<cluster-name>
RESOURCE_GROUP=<resource-group-name>
ARM_ID_CLUSTER=$(az connectedk8s show -n $CLUSTER_NAME -g $RESOURCE_GROUP --query id -o tsv)

Azure PowerShell 버전 6.6.0 이상을 설치합니다.

자리 표시자를 바꾸고 아래 명령을 실행하여 이 문서에 사용된 환경 변수를 설정합니다.

$CLUSTER_NAME = <cluster-name>
$RESOURCE_GROUP = <resource-group-name>
$ARM_ID_CLUSTER = (Get-AzConnectedKubernetes -ResourceGroupName $RESOURCE_GROUP -Name $CLUSTER_NAME).Id

인증 설정

기존 Arc 지원 클러스터에서 Microsoft Entra 인증 또는 서비스 계정 토큰을 사용하여 ClusterRoleBinding을 만듭니다.

Microsoft Entra 엔터티와 연결된 objectId를 가져옵니다. 단일 사용자 계정을 사용하는 경우 Microsoft Entra 엔터티와 연결된 UPN(사용자 계정 이름)을 가져옵니다.
- Microsoft Entra 그룹 계정의 경우:
```
 AAD_ENTITY_ID=$(az ad signed-in-user show --query id -o tsv)
```
- Microsoft Entra 단일 사용자 계정의 경우:
```
AAD_ENTITY_ID=$(az ad signed-in-user show --query userPrincipalName -o tsv)
```
- Microsoft Entra 애플리케이션의 경우:
```
AAD_ENTITY_ID=$(az ad sp show --id <id> --query id -o tsv)
```
적절한 권한으로 엔터티에 권한을 부여합니다.
- 클러스터에서 권한 부여 확인을 위해 Kubernetes 네이티브 ClusterRoleBinding 또는 RoleBinding을 사용하는 경우 직접 액세스를 위해 클러스터의 apiserver를 가리키는 kubeconfig 파일을 사용하여 이 클러스터에 액세스해야 하는 Microsoft Entra 엔터티(서비스 주체 또는 사용자)에 매핑된 항목을 만들 수 있습니다. 예시:
```
kubectl create clusterrolebinding demo-user-binding --clusterrole cluster-admin --user=$AAD_ENTITY_ID
```
- 클러스터에서 권한 부여 확인을 위해 Azure RBAC를 사용하는 경우 Microsoft Entra 엔터티에 매핑되는 적용 가능한 Azure 역할 할당을 만들 수 있습니다. 예시:
```
az role assignment create --role "Azure Arc Kubernetes Viewer" --assignee $AAD_ENTITY_ID --scope $ARM_ID_CLUSTER
az role assignment create --role "Azure Arc Enabled Kubernetes Cluster User Role" --assignee $AAD_ENTITY_ID --scope $ARM_ID_CLUSTER
```

Microsoft Entra 엔터티와 연결된 objectId를 가져옵니다. 단일 사용자 계정을 사용하는 경우 Microsoft Entra 엔터티와 연결된 UPN(사용자 계정 이름)을 가져오게 됩니다.
- Microsoft Entra 그룹 계정의 경우:
```
$AAD_ENTITY_ID = (az ad signed-in-user show --query id -o tsv)
```
- Microsoft Entra 단일 사용자 계정의 경우:
```
$AAD_ENTITY_ID = (az ad signed-in-user show --query userPrincipalName -o tsv)
```
- Microsoft Entra 애플리케이션의 경우:
```
$AAD_ENTITY_ID = (az ad sp show --id <id> --query objectId -o tsv)
```
적절한 권한으로 엔터티에 권한을 부여합니다.
- 클러스터에서 권한 부여 확인을 위해 네이티브 Kubernetes ClusterRoleBinding 또는 RoleBinding을 사용하는 경우 직접 액세스를 위해 클러스터의 apiserver를 가리키는 kubeconfig 파일을 사용하여 이 클러스터에 액세스해야 하는 Microsoft Entra 엔터티(서비스 주체 또는 사용자)에 매핑된 항목을 만들 수 있습니다. 예시:
```
kubectl create clusterrolebinding demo-user-binding --clusterrole cluster-admin --user=$AAD_ENTITY_ID
```
- 클러스터에서 권한 부여 확인을 위해 Azure RBAC를 사용하는 경우 Microsoft Entra 엔터티에 매핑되는 적용 가능한 Azure 역할 할당을 만들 수 있습니다. 예시:
```
az role assignment create --role "Azure Arc Kubernetes Viewer" --assignee $AAD_ENTITY_ID --scope $ARM_ID_CLUSTER
az role assignment create --role "Azure Arc Enabled Kubernetes Cluster User Role" --assignee $AAD_ENTITY_ID --scope $ARM_ID_CLUSTER
```

서비스 계정 토큰 인증 옵션

Azure CLI
Azure PowerShell

Kubernetes 클러스터의 apiserver를 가리키는 kubeconfig 파일을 통해 이 명령을 실행하여 서비스 계정을 만듭니다. 이 예제에서는 기본 네임스페이스에 서비스 계정을 만들지만 default를 다른 네임스페이스로 대체할 수 있습니다.
```
kubectl create serviceaccount demo-user -n default
```
ClusterRoleBinding을 만들어 이 서비스 계정에 클러스터에 대한 적절한 권한을 부여합니다. 첫 번째 명령에서 다른 네임스페이스를 사용한 경우 여기에서 default를 대체합니다.
```
kubectl create clusterrolebinding demo-user-binding --clusterrole cluster-admin --serviceaccount default:demo-user
```

서비스 계정 토큰을 만듭니다.

kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: demo-user-secret
  annotations:
    kubernetes.io/service-account.name: demo-user
type: kubernetes.io/service-account-token
EOF

TOKEN=$(kubectl get secret demo-user-secret -o jsonpath='{$.data.token}' | base64 -d | sed 's/$/\n/g')

콘솔에 출력할 토큰 가져오기
```
echo $TOKEN
```

Kubernetes 클러스터의 apiserver를 가리키는 kubeconfig 파일을 통해 이 명령을 실행하여 서비스 계정을 만듭니다. 이 예제에서는 기본 네임스페이스에 서비스 계정을 만들지만 default를 다른 네임스페이스로 대체할 수 있습니다.
```
kubectl create serviceaccount demo-user -n default
```
ClusterRoleBinding 또는 RoleBinding을 만들어 클러스터에서 이 서비스 계정에 적절한 권한을 부여합니다. 첫 번째 명령에서 다른 네임스페이스를 사용한 경우 여기에서 default를 대체합니다.
```
kubectl create clusterrolebinding demo-user-binding --clusterrole cluster-admin --serviceaccount default:demo-user
```

서비스 계정 토큰을 만듭니다. 다음 콘텐츠가 포함된 demo-user-secret.yaml 파일을 만듭니다.

apiVersion: v1
kind: Secret
metadata:
  name: demo-user-secret
  annotations:
    kubernetes.io/service-account.name: demo-user
type: kubernetes.io/service-account-token

그런 후에 다음 명령을 실행합니다.

kubectl apply -f demo-user-secret.yaml

$TOKEN = ([System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String((kubectl get secret demo-user-secret -o jsonpath='{$.data.token}'))))

콘솔에 출력할 토큰을 가져옵니다.
```
echo $TOKEN
```

클라이언트 디바이스에서 클러스터에 액세스

이제 다른 클라이언트에서 클러스터에 액세스할 수 있습니다. 다른 클라이언트 디바이스에서 다음 단계를 실행합니다.

Microsoft Entra 인증 또는 서비스 계정 토큰 인증을 사용하여 로그인합니다.
사용되는 인증 옵션에 따라 어디서든(클러스터를 둘러싼 방화벽 외부도 포함) 클러스터와 통신하는 데 필요한 클러스터 연결 kubeconfig를 가져옵니다.
- Microsoft Entra 인증을 사용하는 경우:
```
az connectedk8s proxy -n $CLUSTER_NAME -g $RESOURCE_GROUP
```
- 서비스 계정 토큰 인증을 사용하는 경우:
```
az connectedk8s proxy -n $CLUSTER_NAME -g $RESOURCE_GROUP --token $TOKEN
```
  참고 항목
  
  이 명령은 프록시를 열고 현재 셸을 차단합니다.
다른 셸 세션에서 kubectl을 사용하여 클러스터에 요청을 보냅니다.
```
kubectl get pods -A
```

이제 default 네임스페이스 아래의 모든 Pod 목록이 포함된 클러스터의 응답이 표시되어야 합니다.

알려진 제한 사항

az connectedk8s show를 사용하여 Arc 지원 Kubernetes 에이전트 버전을 확인합니다.

에이전트 버전 < 1.11.7
에이전트 버전 >= 1.11.7

Kubernetes 클러스터에 요청할 때 사용된 Microsoft Entra 엔터티가 200개가 넘는 그룹에 속하는 경우 다음 오류가 표시될 수 있습니다.

You must be logged in to the server (Error:Error while retrieving group info. Error:Overage claim (users with more than 200 group membership) is currently not supported.

이것은 알려진 제한 사항입니다. 이 오류가 발생하지 않도록 하려면 다음을 수행합니다.

200개가 넘는 그룹의 멤버일 가능성이 낮은 서비스 주체를 만듭니다.
az connectedk8s proxy 명령을 실행하기 전에 서비스 주체로 Azure CLI에 로그인합니다.

Kubernetes 클러스터에 요청할 때 사용된 Microsoft Entra 서비스 주체가 200개가 넘는 그룹에 속하는 경우 다음 오류가 표시될 수 있습니다.

Overage claim (users with more than 200 group membership) for SPN is currently not supported. For troubleshooting, please refer to aka.ms/overageclaimtroubleshoot