빠른 시작: Azure Arc에 기존 Kubernetes 클러스터 연결

Azure CLI 또는 Azure PowerShell 사용하여 기존 Kubernetes 클러스터를 Azure Arc에 연결하여 Azure Arc 지원 Kubernetes를 시작합니다.

클러스터를 Azure Arc에 연결하는 개념적 내용은 Azure Arc 지원 Kubernetes 에이전트 개요를 참조하세요.

필수 구성 요소

  • 활성 구독이 있는 Azure 계정. 체험 계정을 만듭니다.

  • Kubernetes 핵심 개념에 대한 기본적인 이해.

  • Azure CLI에 로그인하고 클러스터를 Azure Arc에 연결하는 데 사용할 수 있는 ID(사용자 또는 서비스 주체)입니다.

    중요

    • ID에는 Azure Arc 지원 Kubernetes 리소스 유형(Microsoft.Kubernetes/connectedClusters)에 대한 '읽기' 및 '쓰기' 권한이 있어야 합니다.
    • Kubernetes 클러스터 - Azure Arc 온보딩 기본 제공 역할을 이 ID에 사용할 수 있습니다. 이 역할은 클러스터를 Azure Arc에 연결하는 데 필요한 세분화된 권한만 있고 다른 클러스터 또는 다른 Azure 리소스를 업데이트, 삭제 또는 수정할 수 있는 권한이 없으므로 대규모 온보딩에 유용합니다.
  • Azure CLI를 설치하거나 최신 버전으로 업그레이드합니다.

  • 최신 버전의 connectedk8s Azure CLI 확장을 설치합니다.

    az extension add --name connectedk8s
    
  • 실행 중인 Kubernetes 클러스터. 클러스터가 없는 경우 이러한 옵션 중 하나를 사용하여 클러스터를 만들 수 있습니다.

    • Docker의 Kubernetes(KIND)

    • Mac 또는 Windows용 Docker를 사용하여 Kubernetes 클러스터 만들기

    • 클러스터 API를 사용하는 자체 관리되는 Kubernetes 클러스터

      참고

      클러스터에는 운영 체제 및 아키텍처 유형 linux/amd64의 노드가 하나 이상 있어야 합니다. linux/arm64 노드만 있는 클러스터는 아직 지원되지 않습니다.

  • 클러스터를 가리키는 kubeconfig 파일 및 컨텍스트입니다.

  • Helm 3을 설치합니다. Helm 3 버전이 < 3.7.0인지 확인합니다.

Azure Arc 지원 Kubernetes에 대한 공급자 등록

  1. 다음 명령을 입력합니다.

    az provider register --namespace Microsoft.Kubernetes
    az provider register --namespace Microsoft.KubernetesConfiguration
    az provider register --namespace Microsoft.ExtendedLocation
    
  2. 등록 프로세스를 모니터링합니다. 등록은 10분 정도 걸릴 수 있습니다.

    az provider show -n Microsoft.Kubernetes -o table
    az provider show -n Microsoft.KubernetesConfiguration -o table
    az provider show -n Microsoft.ExtendedLocation -o table
    

    등록되면 이러한 네임스페이스의 RegistrationState 상태가 Registered로 변경되는 것을 확인해야 합니다.

네트워크 요구 사항 충족

일반적으로 연결 요구 사항에는 다음과 같은 원칙이 포함됩니다.

  • 달리 지정하지 않는 한 모든 연결은 TCP입니다.
  • 모든 HTTP 연결은 공식적으로 서명되고 확인 가능한 인증서와 함께 HTTPS 및 SSL/TLS를 사용합니다.
  • 달리 지정하지 않는 한 모든 연결은 아웃바운드입니다.

프록시를 사용하려면 에이전트가 이 문서의 네트워크 요구 사항을 충족하는지 확인합니다.

중요

Azure Arc 에이전트가 작동하려면 함수에 대한 https://:443에서 다음 아웃바운드 URL이 필요합니다. *.servicebus.windows.net의 경우 방화벽 및 프록시에 대한 아웃바운드 액세스에 대해 websocket을 사용하도록 설정해야 합니다.

엔드포인트(DNS) 설명
https://management.azure.com 에이전트가 Azure에 연결하고 클러스터를 등록하는 데 필요합니다.
https://<region>.dp.kubernetesconfiguration.azure.com 에이전트가 상태를 푸시하고 구성 정보를 가져오기 위한 데이터 평면 엔드포인트.
https://login.microsoftonline.com
https://<region>.login.microsoft.com
login.windows.net
Azure Resource Manager 토큰을 가져오고 업데이트하는 데 필요합니다.
https://mcr.microsoft.com
https://*.data.mcr.microsoft.com
Azure Arc 에이전트의 컨테이너 이미지를 끌어오는 데 필요합니다.
https://gbl.his.arc.azure.com 시스템 할당 MSI(Managed Identity 증명서) 인증서를 끌어오기 위한 지역 엔드포인트를 가져오는 데 필요합니다.
https://*.his.arc.azure.com 시스템이 할당한 관리 ID 인증서를 가져오는 데 필요합니다.
https://k8connecthelm.azureedge.net az connectedk8s connect는 Helm 3를 사용하여 Kubernetes 클러스터에 Azure Arc 에이전트를 배포합니다. 이 엔드포인트는 에이전트 Helm 차트의 배포를 용이하게 하기 위해 Helm 클라이언트 다운로드에 필요합니다.
guestnotificationservice.azure.com
*.guestnotificationservice.azure.com
sts.windows.net
https://k8sconnectcsp.azureedge.net
클러스터 연결사용자 지정 위치 기반 시나리오의 경우.
*.servicebus.windows.net 클러스터 연결사용자 지정 위치 기반 시나리오의 경우.
https://graph.microsoft.com/ Azure RBAC가 구성된 경우 필수
*.arc.azure.net Azure Portal 연결된 클러스터를 관리합니다.

와일드카드를 *.servicebus.windows.net 특정 엔드포인트로 변환하려면 다음 명령을 사용합니다.

GET https://guestnotificationservice.azure.com/urls/allowlist?api-version=2020-01-01&location=<region>`. 

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

예: san-af-<region>-prod.azurewebsites.net 미국 동부 2 지역에 있어야 san-af-eastus2-prod.azurewebsites.net 합니다.

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

az account list-locations -o table

Azure Arc 기능 및 Azure Arc 지원 서비스에 대한 네트워크 요구 사항의 전체 목록은 Azure Arc 네트워크 요구 사항(통합)을 참조하세요.

리소스 그룹 만들기

다음 명령을 실행합니다.

az group create --name AzureArcTest --location EastUS --output table

출력:

Location    Name
----------  ------------
eastus      AzureArcTest

기존 Kubernetes 클러스터 연결

다음 명령을 실행합니다.

az connectedk8s connect --name AzureArcTest1 --resource-group AzureArcTest

참고

서비스 주체를 사용하여 Azure CLI에 로그인한 경우 클러스터에서 사용자 지정 위치 기능을 사용하도록 추가 매개 변수 를 설정해야 합니다.

출력:

Helm release deployment succeeded

    {
      "aadProfile": {
        "clientAppId": "",
        "serverAppId": "",
        "tenantId": ""
      },
      "agentPublicKeyCertificate": "xxxxxxxxxxxxxxxxxxx",
      "agentVersion": null,
      "connectivityStatus": "Connecting",
      "distribution": "gke",
      "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/AzureArcTest/providers/Microsoft.Kubernetes/connectedClusters/AzureArcTest1",
      "identity": {
        "principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "type": "SystemAssigned"
      },
      "infrastructure": "gcp",
      "kubernetesVersion": null,
      "lastConnectivityTime": null,
      "location": "eastus",
      "managedIdentityCertificateExpirationTime": null,
      "name": "AzureArcTest1",
      "offering": null,
      "provisioningState": "Succeeded",
      "resourceGroup": "AzureArcTest",
      "tags": {},
      "totalCoreCount": null,
      "totalNodeCount": null,
      "type": "Microsoft.Kubernetes/connectedClusters"
    }

위치 매개 변수가 지정되지 않은 위의 명령은 Azure Arc 사용 Kubernetes 리소스를 리소스 그룹과 동일한 위치에 만듭니다. Azure Arc 사용 Kubernetes 리소스를 다른 위치에 만들려면 az connectedk8s connect 명령을 실행할 때 --location <region> 또는 -l <region>을 지정합니다.

중요

경우에 따라 시간 제한 오류로 인해 배포가 실패할 수 있습니다. 이 문제를 해결하는 방법에 대한 자세한 내용은 문제 해결 가이드 를 참조하세요.

아웃바운드 프록시 서버를 사용하여 연결

클러스터가 아웃바운드 프록시 서버 뒤에 있는 경우 아웃바운드 프록시 서버를 통해 요청을 라우팅해야 합니다.

  1. 아웃바운드 프록시 서버를 사용하기 위해 Azure CLI에 필요한 환경 변수를 설정합니다.

    export HTTP_PROXY=<proxy-server-ip-address>:<port>
    export HTTPS_PROXY=<proxy-server-ip-address>:<port>
    export NO_PROXY=<cluster-apiserver-ip-address>:<port>
    
  2. 지정된 및 proxy-http 매개 변수를 사용하여 proxy-https connect 명령을 실행합니다. 프록시 서버가 HTTP 및 HTTPS 둘 다로 설정된 경우 HTTP 프록시 및 --proxy-https HTTPS 프록시에 사용해야 --proxy-http 합니다. 프록시 서버에서 HTTP만 사용하는 경우 두 매개 변수 모두에 해당 값을 사용할 수 있습니다.

    az connectedk8s connect --name <cluster-name> --resource-group <resource-group> --proxy-https https://<proxy-server-ip-address>:<port> --proxy-http http://<proxy-server-ip-address>:<port> --proxy-skip-range <excludedIP>,<excludedCIDR> --proxy-cert <path-to-cert-file>
    

참고

  • 클러스터 내 서비스 간 통신과 관련된 일부 네트워크 요청은 아웃바운드 통신을 위해 프록시 서버를 통해 라우팅되는 트래픽과 분리되어야 합니다. --proxy-skip-range 매개 변수를 사용하여 에이전트에서 이러한 엔드포인트로의 통신이 아웃바운드 프록시를 거치지 않도록 CIDR 범위와 엔드포인트를 쉼표로 구분하여 지정할 수 있습니다. 최소한 클러스터에 있는 서비스의 CIDR 범위는 이 매개 변수의 값으로 지정되어야 합니다. 예를 들어, kubectl get svc -A가 모든 서비스에 10.0.0.0/16 범위의 ClusterIP 값이 있는 서비스 목록을 반환한다고 가정해 보겠습니다. 그러면 --proxy-skip-range에 지정할 값은 10.0.0.0/16,kubernetes.default.svc,.svc.cluster.local,.svc입니다.
  • 대부분의 아웃바운드 프록시 환경에서 --proxy-http, --proxy-https--proxy-skip-range가 필요합니다. --proxy-cert는 프록시에서 예상되는 신뢰할 수 있는 인증서를 에이전트 Pod의 신뢰할 수 있는 인증서 저장소에 삽입해야 하는 경우에 필요합니다.
  • Websocket 연결을 허용하도록 아웃바운드 프록시를 구성해야 합니다.

프록시 서버 엔드포인트 입력 az connectedk8s connect 없이 신뢰할 수 있는 인증서만 제공해야 하는 아웃바운드 프록시 서버의 경우 지정된 입력으로만 --proxy-cert 실행할 수 있습니다. 신뢰할 수 있는 인증서가 여러 개 필요한 경우 매개 변수를 사용하여 --proxy-cert 결합된 인증서 체인을 단일 파일에 제공할 수 있습니다.

참고

  • --custom-ca-cert--proxy-cert의 별칭입니다. 두 매개 변수 중 하나를 서로 바꿔 사용할 수 있습니다. 동일한 명령에 두 매개 변수를 모두 전달하면 마지막으로 전달된 매개 변수가 표시됩니다.

매개 변수를 지정하여 --proxy-cert connect 명령을 실행합니다.

az connectedk8s connect --name <cluster-name> --resource-group <resource-group> --proxy-cert <path-to-cert-file>

클러스터 연결 확인

다음 명령을 실행합니다.

az connectedk8s list --resource-group AzureArcTest --output table

출력:

Name           Location    ResourceGroup
-------------  ----------  ---------------
AzureArcTest1  eastus      AzureArcTest

참고

클러스터를 온보딩하면 클러스터 메타데이터(클러스터 버전, 에이전트 버전, 노드 수 등)가 Azure Portal의 Azure Arc 사용 Kubernetes 리소스에 대한 개요 페이지에 표시되는 데 약 5~10분이 걸립니다.

클러스터를 연결하는 동안 발생하는 문제 해결에 대한 도움말은 Azure Arc 지원 Kubernetes 클러스터에 대한 연결 문제 진단을 참조하세요.

Kubernetes용 Azure Arc 에이전트 보기

Azure Arc 지원 Kubernetes는 네임스페이스에 몇 가지 에이전트를 azure-arc 배포합니다.

  1. 이러한 배포 및 Pod는 다음을 사용하여 볼 수 있습니다.

    kubectl get deployments,pods -n azure-arc
    
  2. 모든 Pod가 Running 상태인지 확인합니다.

    출력:

     NAME                                        READY   UP-TO-DATE   AVAILABLE   AGE
     deployment.apps/cluster-metadata-operator   1/1     1            1           13d
     deployment.apps/clusterconnect-agent        1/1     1            1           13d
     deployment.apps/clusteridentityoperator     1/1     1            1           13d
     deployment.apps/config-agent                1/1     1            1           13d
     deployment.apps/controller-manager          1/1     1            1           13d
     deployment.apps/extension-manager           1/1     1            1           13d
     deployment.apps/flux-logs-agent             1/1     1            1           13d
     deployment.apps/kube-aad-proxy              1/1     1            1           13d
     deployment.apps/metrics-agent               1/1     1            1           13d
     deployment.apps/resource-sync-agent         1/1     1            1           13d
    
     NAME                                            READY   STATUS    RESTARTS   AGE
     pod/cluster-metadata-operator-9568b899c-2stjn   2/2     Running   0          13d
     pod/clusterconnect-agent-576758886d-vggmv       3/3     Running   0          13d
     pod/clusteridentityoperator-6f59466c87-mm96j    2/2     Running   0          13d
     pod/config-agent-7cbd6cb89f-9fdnt               2/2     Running   0          13d
     pod/controller-manager-df6d56db5-kxmfj          2/2     Running   0          13d
     pod/extension-manager-58c94c5b89-c6q72          2/2     Running   0          13d
     pod/flux-logs-agent-6db9687fcb-rmxww            1/1     Running   0          13d
     pod/kube-aad-proxy-67b87b9f55-bthqv             2/2     Running   0          13d
     pod/metrics-agent-575c565fd9-k5j2t              2/2     Running   0          13d
     pod/resource-sync-agent-6bbd8bcd86-x5bk5        2/2     Running   0          13d
    

이러한 에이전트에 대한 자세한 내용은 Azure Arc 지원 Kubernetes 에이전트 개요를 참조하세요.

리소스 정리

Azure CLI에서 다음 명령을 사용하여 Azure Arc 사용 Kubernetes 리소스, 모든 관련 구성 리소스 클러스터에서 실행되는 모든 에이전트를 삭제할 수 있습니다.

az connectedk8s delete --name AzureArcTest1 --resource-group AzureArcTest

삭제 프로세스가 실패하면 다음 명령을 사용하여 강제로 삭제합니다(확인 프롬프트를 무시하려는 경우 추가 -y ).

az connectedk8s delete -g AzureArcTest1 -n AzureArcTest --force

이전에 만든 리소스가 완전히 제거되지 않아 새 클러스터 배포를 만들 때 문제가 발생하는 경우에도 이 명령을 사용할 수 있습니다.

참고

Azure Portal 사용하여 Azure Arc 지원 Kubernetes 리소스를 삭제하면 연결된 구성 리소스가 제거되지만 클러스터에서 실행되는 에이전트는 제거되지 않습니다. 모범 사례는 Azure Portal 리소스를 삭제하는 대신 를 사용하여 az connectedk8s delete Azure Arc 지원 Kubernetes 리소스를 삭제하는 것입니다.

다음 단계

GitOps를 사용하여 연결된 Kubernetes 클러스터에 구성을 배포하는 방법을 알아보려면 다음 문서로 이동합니다.