자습서: Azure Arc 지원 Kubernetes 클러스터에서 GitOps를 사용하여 구성 배포

Important

이 자습서는 Flux v1을 사용하는 GitOps를 위한 것입니다. Flux v2가 포함된 GitOps는 이제 Azure Arc 지원 Kubernetes 및 AKS(Azure Kubernetes Service) 클러스터에서 사용할 수 있습니다. Flux v2가 포함된 GitOps용 자습서로 이동합니다. 가능한 한 빨리 Flux v2로 마이그레이션하는 것이 좋습니다.

2024년 1월 1일 이전에 만들어진 Flux v1 기반 클러스터 구성 리소스에 대한 지원은 2025년 5월 24일에 종료됩니다. 2024년 1월 1일부터 새로운 Flux v1 기반 클러스터 구성 리소스를 만들 수 없습니다.

이 자습서에서는 Azure Arc 지원 Kubernetes 클러스터에서 GitOps를 사용하여 구성을 적용합니다. 이 문서에서 배울 내용은 다음과 같습니다.

  • 예제 Git 리포지토리를 사용하여 Azure Arc 지원 Kubernetes 클러스터에 대한 구성을 만듭니다.
  • 구성이 성공적으로 만들어졌는지 확인합니다.
  • 프라이빗 Git 리포지토리에서 구성을 적용합니다.
  • Kubernetes 구성의 유효성을 검사합니다.

필수 조건

구성 만들기

이 문서에 사용된 예제 리포지토리는 클러스터 연산자의 가상 사용자를 중심으로 구성됩니다. 이 리포지토리의 매니페스트는 몇 가지 네임스페이스를 프로비저닝하고, 워크로드를 배포하고, 몇 가지 팀 특정 구성을 제공합니다. GitOps와 함께 이 리포지토리를 사용하면 클러스터에 다음 리소스가 만들어집니다.

  • 네임스페이스: cluster-config, team-a, team-b
  • 배포: arc-k8s-demo
  • ConfigMap: team-a/endpoints

config-agent는 새 구성 또는 업데이트된 구성에 대해 Azure를 폴링합니다. 이 작업에는 최대 5분이 소요됩니다.

프라이빗 리포지토리를 구성과 연결하는 경우 프라이빗 Git 리포지토리에서 구성 적용의 아래 단계를 완료해야 합니다.

Azure CLI 사용

k8s-configuration에 대한 Azure CLI 확장을 사용하여 연결된 클러스터를 예제 Git 리포지토리에 연결합니다.

  1. 이 구성의 이름을 cluster-config로 지정합니다.

  2. cluster-config 네임스페이스에 연산자를 배포하도록 에이전트에 지시합니다.

  3. 운영자 cluster-admin 권한 부여

    az k8s-configuration create --name cluster-config --cluster-name AzureArcTest1 --resource-group AzureArcTest --operator-instance-name cluster-config --operator-namespace cluster-config --repository-url https://github.com/Azure/arc-k8s-demo --scope cluster --cluster-type connectedClusters
    
    {
      "complianceStatus": {
      "complianceState": "Pending",
      "lastConfigApplied": "0001-01-01T00:00:00",
      "message": "{\"OperatorMessage\":null,\"ClusterState\":null}",
      "messageLevel": "3"
      },
      "configurationProtectedSettings": {},
      "enableHelmOperator": false,
      "helmOperatorProperties": null,
      "id": "/subscriptions/<sub id>/resourceGroups/<group name>/providers/Microsoft.Kubernetes/connectedClusters/<cluster name>/providers/Microsoft.KubernetesConfiguration/sourceControlConfigurations/cluster-config",
      "name": "cluster-config",
      "operatorInstanceName": "cluster-config",
      "operatorNamespace": "cluster-config",
      "operatorParams": "--git-readonly",
      "operatorScope": "cluster",
      "operatorType": "Flux",
      "provisioningState": "Succeeded",
      "repositoryPublicKey": "",
      "repositoryUrl": "https://github.com/Azure/arc-k8s-demo",
      "resourceGroup": "MyRG",
      "sshKnownHostsContents": "",
      "systemData": {
        "createdAt": "2020-11-24T21:22:01.542801+00:00",
        "createdBy": null,
        "createdByType": null,
        "lastModifiedAt": "2020-11-24T21:22:01.542801+00:00",
        "lastModifiedBy": null,
        "lastModifiedByType": null
      },
      "type": "Microsoft.KubernetesConfiguration/sourceControlConfigurations"
    }
    

공용 Git 리포지토리 사용

매개 변수 형식
--repository-url http[s]://server/repo[.git]

SSH 및 Flux에서 만든 키를 사용하여 프라이빗 Git 리포지토리 사용

Flux에 의해 생성된 공개 키를 Git 서비스 공급자의 사용자 계정에 추가합니다. 사용자 계정 대신 키가 리포지토리에 추가되면 URL에서 user@ 대신 git@를 사용합니다.

자세한 내용은 프라이빗 Git 리포지토리에서 구성 적용 섹션으로 이동하세요.

매개 변수 형식 주의
--repository-url ssh://user@server/repo[.git] 또는 user@server:repo[.git] git@user@를 대체할 수 있습니다.

SSH 및 사용자 제공 키를 사용하여 프라이빗 Git 리포지토리 사용

프라이빗 키를 직접 또는 파일로 제공합니다. 키는 PEM 형식이어야 하며 줄 바꿈(\n)으로 끝나야 합니다.

Git 서비스 공급자의 사용자 계정에 연결된 공개 키를 추가합니다. 사용자 계정 대신 키가 리포지토리에 추가되면 user@ 대신 git@를 사용합니다.

자세한 내용은 프라이빗 Git 리포지토리에서 구성 적용 섹션으로 이동하세요.

매개 변수 형식 주의
--repository-url ssh://user@server/repo[.git] 또는 user@server:repo[.git] git@user@를 대체할 수 있습니다.
--ssh-private-key PEM 형식의 base64 인코딩 키 키 직접 제공
--ssh-private-key-file 로컬 파일의 전체 경로 PEM 형식 키를 포함하는 로컬 파일의 전체 경로를 제공합니다.

SSH 및 사용자가 제공한 알려진 호스트와 함께 프라이빗 Git 호스트 사용

Flux 연산자는 SSH 연결을 설정하기 전에 Git 리포지토리를 인증하기 위해 알려진 호스트 파일의 일반 Git 호스트 목록을 유지 관리합니다. 일반적이지 않은 Git 리포지토리 또는 사용자 자신의 Git 호스트를 사용하는 경우 Flux가 리포지트리를 식별할 수 있도록 호스트 키를 제공할 수 있습니다.

프라이빗 키와 마찬가지로 known_hosts 콘텐츠를 직접 또는 파일에 제공할 수 있습니다. 사용자 자신의 콘텐츠를 제공하는 경우 위의 SSH 키 시나리오 중 하나와 함께 known_hosts 콘텐츠 형식 사양을 사용합니다.

매개 변수 형식 주의
--repository-url ssh://user@server/repo[.git] 또는 user@server:repo[.git] git@user@를 대체할 수 있습니다.
--ssh-known-hosts base64로 인코딩됨 알려진 호스트 콘텐츠 직접 제공
--ssh-known-hosts-file 로컬 파일의 전체 경로 로컬 파일에 알려진 호스트 콘텐츠 제공

HTTPS를 사용하여 프라이빗 Git 리포지토리 사용

매개 변수 형식 주의
--repository-url https://server/repo[.git] 기본 인증을 사용하는 HTTPS
--https-user 원시 또는 base64로 인코딩됨 HTTPS 사용자 이름
--https-key 원시 또는 base64로 인코딩됨 HTTPS 개인용 액세스 토큰 또는 암호

참고 항목

  • Helm 연산자 차트 버전 1.2.0+는 HTTPS Helm 릴리스 프라이빗 인증을 지원합니다.
  • AKS 관리형 클러스터에는 HTTPS Helm 릴리스가 지원되지 않습니다.
  • 프록시를 통해 Git 리포지토리에 액세스하는 데 Flux가 필요한 경우 Azure Arc 에이전트를 프록시 설정으로 업데이트해야 합니다. 자세한 내용은 아웃바운드 프록시 서버를 사용하여 연결을 참조하세요.

추가 매개 변수

다음과 같은 선택적 매개 변수를 사용하여 구성을 사용자 지정합니다.

매개 변수 설명
--enable-helm-operator Helm 차트 배포에 대한 지원을 사용하도록 설정하는 스위치.
--helm-operator-params Helm 연산자(사용 설정된 경우)에 대한 차트 값. 예: --set helm.versions=v3.
--helm-operator-chart-version Helm 연산자(사용 설정된 경우)에 대한 차트 버전. 버전 1.2.0+를 사용합니다. 기본값: '1.2.0'.
--operator-namespace 연산자 네임스페이스의 이름. 기본값: 'default'. 최대: 23자.
--operator-params 연산자에 대한 매개 변수. 작은따옴표 안에 지정해야 합니다. 예를 들어 --operator-params='--git-readonly --sync-garbage-collection --git-branch=main'

--operator-params에서 지원되는 옵션:

옵션 설명
--git-branch Kubernetes 매니페스트에 사용할 Git 리포지토리의 분기. 기본값은 'master'입니다. 최신 리포지토리에는 main이라는 루트 분기가 있으며, 이 경우 --git-branch=main을 설정해야 합니다.
--git-path Kubernetes 매니페스트를 찾는 Flux에 대한 Git 리포지토리 내의 상대 경로.
--git-readonly Git 리포지토리는 읽기 전용으로 간주됩니다. Flux는 여기에 쓰려 하지 않을 것입니다.
--manifest-generation 사용 설정된 경우 Flux는 .flux.yaml을 찾고 Kustomize 또는 기타 매니페스트 생성기를 실행합니다.
--git-poll-interval 새 커밋을 위해 Git 리포지토리를 폴링하는 기간. 기본값은 5m(5분)입니다.
--sync-garbage-collection 사용 설정된 경우 Flux는 만들었지만 더 이상 Git에 존재하지 않는 리소스를 삭제합니다.
--git-label 동기화 진행 상황을 추적하기 위한 레이블. Git 분기에 태그를 지정하는 데 사용됩니다. 기본값은 flux-sync입니다.
--git-user Git 커밋의 사용자 이름.
--git-email Git 커밋에 사용할 이메일.

Flux가 리포지토리에 쓰지 않도록 하고 --git-user 또는 --git-email이 설정되지 않은 경우 --git-readonly가 자동으로 설정됩니다.

자세한 내용은 Flux 설명서를 참조하세요.

참고 항목

Flux는 기본적으로 git 리포지토리의 master 분기에서 동기화됩니다. 그러나 최신 git 리포지토리에는 main이라는 루트 브랜치가 있으며 이 경우 --operator-params에서 --git-branch=main을 설정해야 합니다.

Azure Arc 지원 Kubernetes 리소스의 GitOps 탭에 있는 Azure Portal에서 구성을 만들 수 있습니다.

구성 유효성 검사

Azure CLI를 사용하여 구성이 성공적으로 만들어졌는지 확인합니다.

az k8s-configuration show --name cluster-config --cluster-name AzureArcTest1 --resource-group AzureArcTest --cluster-type connectedClusters

구성 리소스는 규정 준수 상태, 메시지 및 디버깅 정보로 업데이트됩니다.

{
  "complianceStatus": {
    "complianceState": "Installed",
    "lastConfigApplied": "2020-12-10T18:26:52.801000+00:00",
    "message": "...",
    "messageLevel": "Information"
  },
  "configurationProtectedSettings": {},
  "enableHelmOperator": false,
  "helmOperatorProperties": {
    "chartValues": "",
    "chartVersion": ""
  },
  "id": "/subscriptions/<sub id>/resourceGroups/AzureArcTest/providers/Microsoft.Kubernetes/connectedClusters/AzureArcTest1/providers/Microsoft.KubernetesConfiguration/sourceControlConfigurations/cluster-config",
  "name": "cluster-config",
  "operatorInstanceName": "cluster-config",
  "operatorNamespace": "cluster-config",
  "operatorParams": "--git-readonly",
  "operatorScope": "cluster",
  "operatorType": "Flux",
  "provisioningState": "Succeeded",
  "repositoryPublicKey": "...",
  "repositoryUrl": "git://github.com/Azure/arc-k8s-demo.git",
  "resourceGroup": "AzureArcTest",
  "sshKnownHostsContents": null,
  "systemData": {
    "createdAt": "2020-12-01T03:58:56.175674+00:00",
    "createdBy": null,
    "createdByType": null,
    "lastModifiedAt": "2020-12-10T18:30:56.881219+00:00",
    "lastModifiedBy": null,
    "lastModifiedByType": null
},
  "type": "Microsoft.KubernetesConfiguration/sourceControlConfigurations"
}

구성을 만들거나 업데이트하면 몇 가지 상황이 발생합니다.

  1. Azure Arc config-agent는 새 구성 또는 업데이트된 구성(Microsoft.KubernetesConfiguration/sourceControlConfigurations)에 대해 Azure Resource Manager를 모니터링하고 새 Pending 구성을 확인합니다.
  2. config-agent는 구성 속성을 읽고 대상 네임스페이스를 만듭니다.
  3. Azure Arc controller-manager는 Kubernetes 서비스 계정을 만들고 적절한 권한(cluster 또는 namespace 범위)에 대한 ClusterRoleBinding 또는 RoleBinding에 매핑합니다. 그런 다음, flux의 인스턴스를 배포합니다.
  4. Flux 생성 키와 함께 SSH 옵션을 사용하는 경우 flux는 SSH 키를 생성하고 공개 키를 기록합니다.
  5. config-agent는 Azure의 구성 리소스에 상태를 다시 보고합니다.

프로비저닝 프로세스가 진행되는 동안 구성 리소스는 몇 가지 상태 변경을 거칩니다. 위의 az k8s-configuration show ... 명령을 사용하여 진행률을 모니터링합니다.

스테이지 변경 설명
complianceStatus->Pending 초기 및 진행 중인 상태를 나타냅니다.
complianceStatus ->Installed config-agent는 클러스터를 구성했고 오류 없이 flux를 배포했습니다.
complianceStatus ->Failed config-agentflux를 배포하는 동안 오류가 발생했습니다. 세부 정보는 complianceStatus.message 응답 본문에 제공됩니다.

프라이빗 Git 리포지토리에서 구성 적용

프라이빗 Git 리포지토리를 사용하는 경우 리포지토리에 SSH 공개 키를 구성해야 합니다. 사용자가 제공하거나 Flux에서 SSH 공개 키를 생성합니다. 특정 Git 리포지토리 또는 리포지토리에 대한 액세스 권한이 있는 Git 사용자에 대해 공개 키를 구성할 수 있습니다.

사용자 자신의 공개 키 가져오기

사용자 자신의 SSH 키를 생성한 경우에는 프라이빗 키와 공개 키가 이미 있습니다.

Azure CLI를 사용하여 공개 키 가져오기

Flux에서 키를 생성하는 경우 Azure CLI에서 다음을 사용합니다.

az k8s-configuration show --resource-group <resource group name> --cluster-name <connected cluster name> --name <configuration name> --cluster-type connectedClusters --query 'repositoryPublicKey' 
"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAREDACTED"

Azure Portal에서 공개 키 가져오기

Flux에서 키를 생성하는 경우 Azure Portal에서 다음을 수행합니다.

  1. Azure Portal에서 연결된 클러스터 리소스로 이동합니다.
  2. 리소스 페이지에서 "GitOps"를 선택하고 이 클러스터에 대한 구성 목록을 확인합니다.
  3. 프라이빗 Git 리포지토리를 사용하는 구성을 선택합니다.
  4. 열린 컨텍스트 창의 맨 아래에서 리포지토리 공개 키를 복사합니다.

GitHub를 사용하여 공개 키 추가

다음 옵션 중 하나를 사용합니다.

  • 옵션 1: 사용자 계정에 공개 키를 추가합니다(계정의 모든 리포지토리에 적용됨).

    1. GitHub를 열고 페이지 오른쪽 위 모서리에 있는 프로필 아이콘을 클릭합니다.
    2. 설정을 클릭합니다.
    3. SSH 및 GPG 키를 클릭합니다.
    4. 새 SSH 키를 클릭합니다.
    5. 제목을 제공합니다.
    6. 따옴표 없이 공개 키를 붙여넣습니다.
    7. SSH 키 추가를 클릭합니다.
  • 옵션 2: 공개 키를 Git 리포지토리에 배포 키로 추가합니다(이 리포지토리에만 적용됨).

    1. GitHub를 열고 리포지토리로 이동합니다.
    2. 설정을 클릭합니다.
    3. 키 배포를 클릭합니다.
    4. 키 배포 추가를 클릭합니다.
    5. 제목을 제공합니다.
    6. 쓰기 액세스 허용을 선택합니다.
    7. 따옴표 없이 공개 키를 붙여넣습니다.
    8. 키 추가를 클릭합니다.

Azure DevOps 리포지토리를 사용하여 공개 키 추가

SSH 키에 키를 추가하려면 다음 단계를 사용합니다.

  1. 오른쪽 위(프로필 이미지 옆)에 있는 사용자 설정에서 SSH 공개 키를 클릭합니다.
  2. + 새 키를 선택합니다.
  3. 이름을 제공합니다.
  4. 따옴표 없이 공개 키를 붙여넣습니다.
  5. 추가를 클릭합니다.

Kubernetes 구성의 유효성을 검사합니다.

config-agentflux 인스턴스를 설치한 후 Git 리포지토리에 보관된 리소스가 클러스터로 이동하기 시작해야 합니다. 다음 명령을 사용하여 네임스페이스, 배포 및 리소스가 만들어졌는지 확인합니다.

kubectl get ns --show-labels
NAME              STATUS   AGE    LABELS
azure-arc         Active   24h    <none>
cluster-config    Active   177m   <none>
default           Active   29h    <none>
itops             Active   177m   fluxcd.io/sync-gc-mark=sha256.9oYk8yEsRwWkR09n8eJCRNafckASgghAsUWgXWEQ9es,name=itops
kube-node-lease   Active   29h    <none>
kube-public       Active   29h    <none>
kube-system       Active   29h    <none>
team-a            Active   177m   fluxcd.io/sync-gc-mark=sha256.CS5boSi8kg_vyxfAeu7Das5harSy1i0gc2fodD7YDqA,name=team-a
team-b            Active   177m   fluxcd.io/sync-gc-mark=sha256.vF36thDIFnDDI2VEttBp5jgdxvEuaLmm7yT_cuA2UEw,name=team-b

team-a, team-b, itopscluster-config 네임스페이스가 만들어진 것을 확인할 수 있습니다.

구성 리소스의 지시에 따라 flux 연산자가 cluster-config 네임스페이스에 배치되었습니다.

kubectl -n cluster-config get deploy  -o wide
NAME             READY   UP-TO-DATE   AVAILABLE   AGE   CONTAINERS   IMAGES                         SELECTOR
cluster-config   1/1     1            1           3h    flux         docker.io/fluxcd/flux:1.16.0   instanceName=cluster-config,name=flux
memcached        1/1     1            1           3h    memcached    memcached:1.5.15               name=memcached

추가로 알아보기

다음을 사용하여 구성 리포지토리의 일부로 배포된 다른 리소스를 살펴볼 수 있습니다.

kubectl -n team-a get cm -o yaml
kubectl -n itops get all

리소스 정리

Azure CLI 또는 Azure Portal을 사용하여 구성을 삭제합니다. delete 명령을 실행하면 Azure에서 구성 리소스가 즉시 삭제됩니다. 클러스터에서 연결된 개체를 완전히 삭제하면 10분 이내에 삭제됩니다. 제거할 때 구성이 실패한 상태인 경우 연결된 개체를 완전히 삭제하는 데 최대 1시간이 걸릴 수 있습니다.

범위가 namespace인 구성이 삭제되면 Azure Arc는 기존 워크로드가 중단되는 것을 방지하기 위해 네임스페이스를 삭제하지 않습니다. 필요한 경우 kubectl을 사용하여 이 네임스페이스를 수동으로 삭제할 수 있습니다.

az k8s-configuration delete --name cluster-config --cluster-name AzureArcTest1 --resource-group AzureArcTest --cluster-type connectedClusters

참고 항목

추적된 Git 리포지토리에서 배포한 결과로 클러스터에 변경된 내용은 구성이 삭제될 때 삭제되지 않습니다.

다음 단계

GitOps를 통해 CI/CD를 구현하는 방법을 알아보려면 다음 자습서로 이동합니다.