자습서: ArgoCD에서 GitOps를 사용하여 애플리케이션 배포

2025-05-04

이 자습서에서는 Kubernetes 클러스터에서 GitOps를 사용하는 방법을 설명합니다. ArgoCD를 사용하는 GitOps는 Azure Arc 지원 Kubernetes 클러스터 또는 AKS(Azure Kubernetes Service) 클러스터에서 클러스터 확장 으로 사용하도록 설정됩니다. GitOps를 사용하면 Git 리포지토리를 클러스터 구성 및 애플리케이션 배포의 믿을 수 있는 원본으로 사용할 수 있습니다.

중요합니다

ArgoCD를 사용하는 GitOps는 현재 미리 보기로 제공됩니다. 베타, 미리 보기로 제공되거나 아직 일반 공급으로 릴리스되지 않은 Azure 기능에 적용되는 약관은 Microsoft Azure 미리 보기에 대한 추가 사용 약관을 참조하세요. 프로덕션 GitOps 확장 지원의 경우 Flux를 사용하여 GitOps 확장을 사용해 보세요.

팁 (조언)

이 자습서의 원본은 Git 리포지토리이지만 ArgoCD는 Helm 및 OCI(Open Container Initiative) 리포지토리와 같은 다른 일반적인 파일 원본을 지원합니다.

필수 조건

GitOps를 사용하여 애플리케이션을 배포하려면 Azure Arc 지원 Kubernetes 클러스터 또는 AKS 클러스터가 필요합니다.

Azure Arc 지원 Kubernetes 클러스터

작동 중인 Azure Arc 지원 Kubernetes 연결 클러스터.

Kubernetes 클러스터를 Azure Arc에 연결하는 방법을 알아보세요. 아웃바운드 프록시를 통해 연결해야 하는 경우 프록시 설정으로 Arc 에이전트를 설치해야 합니다.
Microsoft.Kubernetes/connectedClusters 리소스 종류에 대한 읽기 및 쓰기 권한.

Azure Kubernetes Service 클러스터

작동 중인 MSI 기반 AKS 클러스터

중요합니다

이 확장이 작동하려면 AKS 클러스터를 SPN(서비스 사용자 이름)이 아닌 MSI(관리 서비스 ID)로 만들어야 합니다. az aks create를 사용하여 만들어진 새 AKS 클러스터의 경우 클러스터는 기본적으로 MSI 기반입니다. SPN 기반 클러스터를 MSI로 변환하려면 az aks update -g $RESOURCE_GROUP -n $CLUSTER_NAME --enable-managed-identity실행합니다. 자세한 내용은 AKS에서 관리 ID 사용을 참조하세요.
Microsoft.ContainerService/managedClusters 리소스 종류에 대한 읽기 및 쓰기 권한.

두 클러스터 유형 모두에 공통

다음과 같은 리소스 종류에 대한 읽기 및 쓰기 권한.
- Microsoft.KubernetesConfiguration/extensions
Azure CLI 버전 2.15 이상 Azure CLI를 설치하거나 다음 명령을 사용하여 최신 버전으로 업데이트합니다.
```
az version
az upgrade
```
Kubernetes 명령줄 클라이언트 kubectl. Azure Cloud Shell을 사용하는 경우 kubectl 이미 설치되어 있습니다.

kubectl 명령을 사용하여 az aks install-cli을 로컬로 설치합니다.
```
az aks install-cli
```

다음 Azure 서비스 공급자 등록:

az provider register --namespace Microsoft.Kubernetes
az provider register --namespace Microsoft.ContainerService
az provider register --namespace Microsoft.KubernetesConfiguration

등록은 비동기식 프로세스이며 10분 이내에 완료되어야 합니다. 등록 프로세스를 모니터링하려면 다음 명령을 실행합니다.

az provider show -n Microsoft.KubernetesConfiguration -o table

Namespace                          RegistrationPolicy    RegistrationState
---------------------------------  --------------------  -------------------
Microsoft.KubernetesConfiguration  RegistrationRequired  Registered

버전 및 지역 지원

GitOps는 현재 Azure Arc 지원 Kubernetes가 지원하는 모든 지역에서 지원됩니다. GitOps는 현재 AKS가 지원하는 지역의 하위 집합에서 지원됩니다. GitOps 서비스에 정기적으로 새로운 지원 지역이 추가되고 있습니다.

네트워크 요구 사항

GitOps 에이전트가 작동하려면 포트 22(SSH) 또는 포트 443(HTTPS)의 리포지토리 원본에 대한 아웃바운드(송신) TCP가 필요합니다. 에이전트에 다음 아웃바운드 URL에 대한 액세스 권한도 필요합니다.

엔드포인트(DNS)	설명
`https://management.azure.com`	에이전트가 Kubernetes 구성 서비스와 통신하는 데 필요합니다.
`https://<region>.dp.kubernetesconfiguration.azure.com`	에이전트가 상태를 푸시하고 구성 정보를 가져오기 위한 데이터 평면 엔드포인트. `<region>`(앞서 언급한 지원 지역)에 따라 다릅니다.
`https://login.microsoftonline.com`	Azure Resource Manager 토큰을 가져오고 업데이트하는 데 필요합니다.
`https://mcr.microsoft.com`	컨트롤러에 대한 컨테이너 이미지를 끌어오는 데 필요합니다.

CLI 확장 활성화

최신 k8s-configuration 및 k8s-extension CLI 확장 패키지를 설치합니다.

az extension add -n k8s-configuration
az extension add -n k8s-extension

이러한 패키지를 최신 버전으로 업데이트하려면 다음을 수행합니다.

az extension update -n k8s-configuration
az extension update -n k8s-extension

설치된 모든 Azure CLI 확장 및 버전 목록을 보려면 다음 명령을 사용합니다.

az extension list -o table

Experimental   ExtensionType   Name                   Path                                                       Preview   Version
-------------  --------------  -----------------      -----------------------------------------------------      --------  --------
False          whl             connectedk8s           C:\Users\somename\.azure\cliextensions\connectedk8s         False     1.10.7
False          whl             k8s-configuration      C:\Users\somename\.azure\cliextensions\k8s-configuration    False     2.2.0
False          whl             k8s-extension          C:\Users\somename\.azure\cliextensions\k8s-extension        False     1.6.4

ArgoCD(GitOps) 확장 만들기(간단한 설치)

GitOps ArgoCD 설치 는 HA(고가용성) 모드에서 다중 테넌트를 지원하고 워크로드 ID를 지원합니다.

중요합니다

HA 모드는 기본 구성이며 클러스터에서 3개의 노드를 설치할 수 있어야 합니다. 아래 명령은 단일 노드에 확장을 설치하기 위해 추가됩니다 --config deployWithHighAvailability=false .

이 명령은 클러스터 전체 액세스 권한이 있는 새 argocd 네임스페이스에 ArgoCD 구성 요소를 설치하는 가장 간단한 구성을 만듭니다. 클러스터 전체 액세스를 사용하면 클러스터의 ArgoCD configmap 구성에 나열된 네임스페이스에서 ArgoCD 앱 정의를 검색할 수 있습니다. 예: namespace1,namespace2

az k8s-extension create --resource-group <resource-group> --cluster-name <cluster-name> \
--cluster-type managedClusters \
--name argocd \
--extension-type Microsoft.ArgoCD \
--auto-upgrade false \
--release-train preview \
--version 0.0.7-preview \
--config deployWithHightAvailability=false \
--config namespaceInstall=false \
--config "config-maps.argocd-cmd-params-cm.data.application\.namespaces=namespace1,namespace2"

특정 네임스페이스에 대한 ArgoCD 액세스를 제한하려면 --config namespaceInstall=true와 함께 --target-namespace <namespace> 매개 변수를 활용합니다. 이 설치 명령은 새 <namespace> 네임스페이스를 만들고 해당 <namespace>에 ArgoCD 구성 요소를 설치합니다. 또한 설치 명령을 사용하면 동일한 클러스터에 ArgoCD의 여러 인스턴스를 설치할 수 있습니다. 이 구성의 ArgoCD 애플리케이션 정의는 네임스페이 <namespace> 스에서만 작동합니다.

워크로드 ID를 사용하여 GitOps(ArgoCD) 확장 만들기

프로덕션 사용에 권장되는 대체 설치 방법은 워크로드 ID입니다. 이 방법을 사용하면 Microsoft Entra ID ID를 사용하여 Git 리포지토리에서 비밀 또는 자격 증명을 관리할 필요 없이 Azure 리소스에 인증할 수 있습니다. 이 설치는 ArgoCD의 3.0.0-rc2 이상 OSS 버전에서 사용하도록 설정된 워크로드 ID 인증을 활용합니다.

중요합니다

HA 모드는 기본 구성이며 클러스터에서 3개의 노드를 설치할 수 있어야 합니다. --config deployWithHighAvailability=false를 추가하여 확장을 단일 노드에 설치합니다.

워크로드 ID를 사용하여 확장을 만들려면 먼저 다음 변수를 이 Bicep 템플릿의 고유한 값으로 바꿉니다.

var clusterName = '<aks-or-arc-cluster-name>'

var workloadIdentityClientId = 'replace-me##-##-###-###'
var ssoWorkloadIdentityClientId = 'replace-me##-##-###-###'

var url = 'https://<public-ip-for-argocd-ui>/'
var oidcConfig = '''
name: Azure
issuer: https://login.microsoftonline.com/<your-tenant-id>/v2.0
clientID: <same-value-as-ssoWorkloadIdentityClientId-above>
azure:
  useWorkloadIdentity: true
requestedIDTokenClaims:
  groups:
    essential: true
requestedScopes:
  - openid
  - profile
  - email
'''

var defaultPolicy = 'role:readonly'
var policy = '''
p, role:org-admin, applications, *, */*, allow
p, role:org-admin, clusters, get, *, allow
p, role:org-admin, repositories, get, *, allow
p, role:org-admin, repositories, create, *, allow
p, role:org-admin, repositories, update, *, allow
p, role:org-admin, repositories, delete, *, allow
g, replace-me##-argocd-ui-Microsoft Entra-group-admin-id, role:org-admin
'''

resource cluster 'Microsoft.ContainerService/managedClusters@2024-10-01' existing = {
  name: clusterName
}

resource extension 'Microsoft.KubernetesConfiguration/extensions@2023-05-01' = {
  name: 'argocd'
  scope: cluster
  properties: {
    extensionType: 'Microsoft.ArgoCD'
    autoUpgradeMinorVersion: false
    releaseTrain: 'preview'
    version: '0.0.7-preview'
    configurationSettings: {
      'workloadIdentity.enable': 'true'
      'workloadIdentity.clientId': workloadIdentityClientId
      'workloadIdentity.entraSSOClientId': ssoWorkloadIdentityClientId
      'config-maps.argocd-cm.data.oidc\\.config': oidcConfig
      'config-maps.argocd-cm.data.url': url
      'config-maps.argocd-rbac-cm.data.policy\\.default': defaultPolicy
      'config-maps.argocd-rbac-cm.data.policy\\.csv': policy
      'config-maps.argocd-cmd-params-cm.data.application\\.namespaces': 'default, argocd'
    }
  }
}

Bicep 템플릿은 다음 명령을 사용하여 만들 수 있습니다.

az deployment group create --resource-group <resource-group> --template-file <bicep-file>

매개 변수

clusterName 는 AKS 또는 Arc 지원 Kubernetes 클러스터의 이름입니다.

workloadIdentityClientId 및 ssoWorkloadIdentityClientId 워크로드 ID에 사용하려는 관리 ID의 클라이언트 ID입니다. ArgoCD ssoWorkloadIdentityClientId UI에 대한 인증에 사용되며 workloadIdentityClientId ArgoCD 구성 요소의 워크로드 ID에 사용됩니다. ssoWorkloadIdentityClientId의 일반 설정 및 구성에 대한 자세한 내용은 OIDC를 사용하여 Microsoft Entra ID 앱 등록 인증 을 방문하세요.

url 는 ArgoCD UI의 공용 IP입니다. 클러스터에 고객이 제공한 수신 컨트롤러가 이미 없는 한 공용 IP 또는 도메인 이름은 없습니다. 그렇다면 배포 후 인그레스 규칙을 ArgoCD UI에 추가해야 합니다.

oidcConfig - <your-tenant-id>를 Microsoft Entra ID의 테넌트 ID로 바꾸십시오. <same-value-as-ssoWorkloadIdentityClientId-above>를 ssoWorkloadIdentityClientId와 같은 값으로 바꾸다.

policy 변수는 argocd-rbac-cm configmap ArgoCD의 설정입니다. g, replace-me##-argocd-ui-entra-group-admin-id 는 관리자에게 ArgoCD UI에 대한 액세스 권한을 부여하는 Microsoft Entra 그룹 ID입니다. Microsoft Entra 그룹 ID는 Azure Portal의 Microsoft Entra ID > 그룹 > 이름 > 속성에서 찾을 수 있습니다. Microsoft Entra 그룹 ID 대신 Microsoft Entra 사용자 ID를 사용할 수 있습니다. Microsoft Entra 사용자 ID는 Azure 포털의 Microsoft Entra ID > 사용자 >사용자-이름> 속성에서 찾을 수 있습니다.

워크로드 ID 자격 증명 만들기

새 워크로드 ID 자격 증명을 설정하려면 다음 단계를 수행합니다.

AKS 클러스터 또는 Arc 지원 Kubernetes 클러스터에 대한 OIDC 발급자 URL을 검색합니다.
관리 ID 만들고 해당 클라이언트 ID 및 테넌트 ID를 기록해 둡니다.

AKS 클러스터 또는 Arc 지원 Kubernetes 클러스터에 대한 페더레이션 ID 자격 증명을 설정합니다. 다음은 그 예입니다.

# For source-controller
az identity federated-credential create --name ${FEDERATED_IDENTITY_CREDENTIAL_NAME} --identity-name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${RESOURCE_GROUP}" --issuer "${OIDC_ISSUER}" --subject system:serviceaccount:"argocd":"source-controller" --audience api://AzureADTokenExchange

원본 컨트롤러 또는 이미지 리플렉터 컨트롤러가 끌어올 리소스에 대한 워크로드 아이덴티티에 적절한 권한을 부여해야 합니다. 예를 들어, Azure Container Registry를 사용하는 경우 Container Registry Repository Reader (ABAC 사용 레지스트리의 경우) 또는 (ABAC가 아닌 레지스트리의 경우)가 적용되었는지 확인합니다.

워크로드 ID를 사용하여 프라이빗 ACR 레지스트리 또는 ACR 리포지토리에 연결

프라이빗 ACR 레지스트리 또는 ACR 리포지토리를 활용하려면 프라이빗 ACR 레지스트리에 연결하기 위한 공식 ArgoCD 설명서의 지침을 따릅니다. Pod 레이블 지정, 페더레이션 ID 자격 증명 생성하기 및 해당 가이드의 서비스 계정에 어노테이션 추가 단계는 확장에서 Bicep 배포를 통해 완료되었으며, 건너뛸 수 있습니다.

ArgoCD UI에 액세스

AKS 클러스터에 대한 기존 수신 컨트롤러가 없는 경우 LoadBalancer 서비스를 사용하여 ArgoCD UI를 직접 노출할 수 있습니다. 다음 명령은 포트 80 및 443에서 ArgoCD UI를 노출합니다.

kubectl -n argocd expose service argocd-server --type LoadBalancer --name argocd-server-lb --port 80 --target-port 8080

ArgoCD 애플리케이션 배포

ArgoCD 확장이 설치되었으므로 ArgoCD UI 또는 CLI를 사용하여 애플리케이션을 배포할 수 있습니다. 다음 예제에서는 kubectl apply를 사용하여 ArgoCD 애플리케이션 내에서 AKS 저장소를 argocd 네임스페이스의 기본 ArgoCD 프로젝트에 배포합니다.

kubectl apply -f - <<EOF
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: aks-store-demo
  namespace: argocd
spec:
  project: default
  source:    
      repoURL: https://github.com/Azure-Samples/aks-store-demo.git
      targetRevision: HEAD
      path: kustomize/overlays/dev
  syncPolicy:
      automated: {}
  destination:
      namespace: argocd
      server: https://kubernetes.default.svc
EOF

AKS 스토어 데모 애플리케이션이 pets 네임스페이스에 설치되었습니다. 다음 지침에 따라 애플리케이션 웹 페이지를 참조하세요. https가 아닌 http를 사용하여 IP 주소를 방문해야 합니다.

확장 구성 업데이트

다음 명령을 사용하여 설치 및 기타 확장 구성 설정 후에 ArgoCD 구성 맵을 업데이트할 수 있습니다.

az k8s-extension update --resource-group <resource-group> --cluster-name <cluster-name> --cluster-type <cluster-type> --name Microsoft.ArgoCD –-config "config-maps.argocd-cm.data.url='https://<public-ip-for-argocd-ui>/auth/callback'”

확장을 통해 ArgoCD configmap을 업데이트하는 것이 중요하므로 설정을 덮어쓰지 않습니다. bicep 템플릿을 적용하는 것은 구성을 업데이트하는 az cli 대체 방법입니다.

확장 삭제

다음 명령을 사용하여 확장을 삭제합니다.

az k8s-extension delete -g <resource-group> -c <cluster-name> -n argocd -t managedClusters --yes

다음 단계

Azure/AKS 리포지토리에 문제 및 기능 요청을 제출하고 설명 또는 제목에 "ArgoCD"라는 단어를 포함해야 합니다.
AKS-Platform 엔지니어링 코드 샘플을 살펴보고, OSS ArgoCD를 백스테이지와 Azure(CAPZ) 또는 크로스플레인을 위한 클러스터 API Provider와 함께 배포하십시오.

다음을 통해 공유

자습서: ArgoCD에서 GitOps를 사용하여 애플리케이션 배포

필수 조건

Azure Arc 지원 Kubernetes 클러스터

Azure Kubernetes Service 클러스터

두 클러스터 유형 모두에 공통

버전 및 지역 지원

네트워크 요구 사항

CLI 확장 활성화

ArgoCD(GitOps) 확장 만들기(간단한 설치)

워크로드 ID를 사용하여 GitOps(ArgoCD) 확장 만들기

매개 변수

워크로드 ID 자격 증명 만들기

워크로드 ID를 사용하여 프라이빗 ACR 레지스트리 또는 ACR 리포지토리에 연결

ArgoCD UI에 액세스

ArgoCD 애플리케이션 배포

확장 구성 업데이트

확장 삭제

다음 단계

피드백

추가 리소스