이 페이지 개선에 도움 주기

이 사용자 가이드에 기여하려면 모든 페이지의 오른쪽 창에 있는 GitHub에서 이 페이지 편집 링크를 선택합니다.

Argo CD 기능 관련 문제 해결

기능이 ACTIVE 상태이지만 애플리케이션이 동기화되지 않음

Argo CD 기능이 ACTIVE 상태를 표시하지만 애플리케이션이 동기화되지 않는 경우 기능 상태 및 애플리케이션 상태를 확인합니다.

기능 상태 확인:

EKS 콘솔 또는 AWS CLI를 사용하여 기능 상태 및 상태 문제를 볼 수 있습니다.

콘솔:

AWS CLI:

# View capability status and health
aws eks describe-capability \
  --region region-code \
  --cluster-name my-cluster \
  --capability-name my-argocd

# Look for issues in the health section

일반적인 원인:

애플리케이션 상태 확인:

# List applications
kubectl get application -n argocd

# View sync status
kubectl get application my-app -n argocd -o jsonpath='{.status.sync.status}'

# View application health
kubectl get application my-app -n argocd -o jsonpath='{.status.health}'

애플리케이션 조건 확인:

# Describe application to see detailed status
kubectl describe application my-app -n argocd

# View application health
kubectl get application my-app -n argocd -o jsonpath='{.status.health}'

애플리케이션이 '진행 중' 상태로 멈춤

애플리케이션에 Progressing이 표시되지만 Healthy에 도달하지 않는 경우 애플리케이션의 리소스 상태 및 이벤트를 확인합니다.

리소스 상태 확인:

# View application resources
kubectl get application my-app -n argocd -o jsonpath='{.status.resources}'

# Check for unhealthy resources
kubectl describe application my-app -n argocd | grep -A 10 "Health Status"

일반적인 원인:

대상 클러스터 구성 확인(다중 클러스터 설정의 경우):

# List registered clusters
kubectl get secret -n argocd -l argocd.argoproj.io/secret-type=cluster

# View cluster secret details
kubectl get secret cluster-secret-name -n argocd -o yaml

리포지토리 인증 실패

Argo CD가 Git 리포지토리에 액세스할 수 없는 경우 인증 구성을 확인합니다.

CodeCommit 리포지토리의 경우:

IAM 기능 역할에 CodeCommit 권한이 있는지 확인:

# View IAM policies
aws iam list-attached-role-policies --role-name my-argocd-capability-role
aws iam list-role-policies --role-name my-argocd-capability-role

# Get specific policy details
aws iam get-role-policy --role-name my-argocd-capability-role --policy-name policy-name
      

역할에는 리포지토리에 대한 codecommit:GitPull 권한이 필요합니다.

프라이빗 Git 리포지토리의 경우:

리포지토리 자격 증명이 올바르게 구성되었는지 확인:

# Check repository secret exists
kubectl get secret -n argocd repo-secret-name -o yaml

보안 암호에 올바른 인증 자격 증명(SSH 키, 토큰 또는 사용자 이름과 암호)이 포함되어 있는지 확인합니다.

Secrets Manager를 사용하는 리포지토리의 경우:

# Verify IAM Capability Role has Secrets Manager permissions
aws iam list-attached-role-policies --role-name my-argocd-capability-role

# Test secret retrieval
aws secretsmanager get-secret-value --secret-id arn:aws:secretsmanager:region-code:111122223333:secret:my-secret
      

다중 클러스터 배포 문제

애플리케이션이 원격 클러스터에 배포되지 않는 경우 클러스터 등록 및 액세스 구성을 확인합니다.

클러스터 등록 확인:

# List registered clusters
kubectl get secret -n argocd -l argocd.argoproj.io/secret-type=cluster

# Verify cluster secret format
kubectl get secret CLUSTER_SECRET_NAME -n argocd -o yaml

server 필드에 Kubernetes API URL이 아닌 EKS 클러스터 ARN이 포함되어 있는지 확인합니다.

대상 클러스터 액세스 항목 확인:

대상 클러스터에서 Argo CD 기능 역할에 액세스 항목이 있는지 확인합니다.

# List access entries (run on target cluster or use AWS CLI)
aws eks list-access-entries --cluster-name target-cluster

# Describe specific access entry
aws eks describe-access-entry \
  --cluster-name target-cluster \
  --principal-arn arn:aws:iam::111122223333:role/my-argocd-capability-role
      

교차 계정에 대한 IAM 권한 확인:

교차 계정 배포의 경우 Argo CD 기능 역할에 대상 클러스터의 액세스 항목이 있는지 확인합니다. 관리형 기능에서는 교차 계정 액세스에 대해 IAM 역할 수임이 아닌 EKS 액세스 항목을 사용합니다.

다중 클러스터 구성에 대한 자세한 내용은 대상 클러스터 등록 섹션을 참조하세요.

애플리케이션 동기화 시간 증가

애플리케이션이 동기화되지만 예상보다 오래 걸리는 경우 다음 진단 단계를 사용하여 원인을 식별합니다.

마지막 동기화 시간 확인

애플리케이션이 마지막으로 동기화된 시간을 검토하여 지연을 확인합니다.

# View last sync time for all applications
kubectl get application -n argocd -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.operationState.finishedAt}{"\n"}{end}'

# View last sync time for a specific application
kubectl get application my-app -n argocd -o jsonpath='{.status.operationState.finishedAt}'

애플리케이션 조건 확인

조정 대기열 지연에 대한 애플리케이션 조건을 검토합니다.

# Check conditions on an application
kubectl get application my-app -n argocd -o jsonpath='{.status.conditions}'

targetRevision 구성 확인

targetRevision: HEAD를 사용하는 애플리케이션은 리포지토리에 대한 모든 커밋에서 매니페스트 캐시를 무효화하므로 동기화 시간이 느려집니다.

# List applications using HEAD as targetRevision
kubectl get application -n argocd -o jsonpath='{range .items[?(@.spec.source.targetRevision=="HEAD")]}{.metadata.name}{"\n"}{end}'

일반적인 원인

완화

애플리케이션이 반복적으로 동기화되거나 동기화되지 않음

애플리케이션이 동기화된 후 즉시 OutOfSync 상태가 되거나 동기화 루프에서 멈춘 경우, 원인은 일반적으로 Git에서 정의한 것과 클러스터에 존재하는 것 사이의 드리프트입니다. 기준 진단부터 시작합니다.

진단 정보 수집

# View current sync and health status
argocd app get my-app

# Show exact fields that differ between Git and live state
argocd app diff my-app

# Check whether the app has ever reached a stable state
argocd app history my-app
         

argocd app diff 명령은 가장 유용한 시작점입니다. 이 명령은 애플리케이션이 동기화되지 않은 것으로 보이게 만드는 필드를 정확하게 보여줍니다.

자체 관리형 인증서로 인해 드리프트 발생

cert-manager, OPA Gatekeeper, KEDA와 같은 컨트롤러는 런타임에 인증서를 생성합니다. 이러한 런타임 값은 Git에 있지 않으므로 Argo CD는 모든 조정에서 드리프트를 감지합니다.

증상은 다음과 같습니다.

이 문제를 해결하려면 영향을 받는 필드에 ignoreDifferences를 추가하고 동기화 옵션에서 RespectIgnoreDifferences를 활성화합니다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
spec:
  ignoreDifferences:
    - group: admissionregistration.k8s.io
      kind: ValidatingWebhookConfiguration
      jsonPointers:
        - /webhooks/0/clientConfig/caBundle
    - group: ""
      kind: Secret
      jsonPointers:
        - /data/tls.crt
        - /data/tls.key
  syncPolicy:
    syncOptions:
      - RespectIgnoreDifferences=true

자가 복구가 느린 시작 워크로드를 중단

selfHeal이 활성화되면 Argo CD는 드리프트를 감지할 때 애플리케이션을 다시 동기화합니다. 워크로드를 시작하는 데 30~60초가 걸리면 워크로드가 Healthy가 되기 전에 자가 복구가 트리거됩니다. prune을 활성화하면 부분적으로 시작된 리소스가 손상될 수 있습니다.

이를 해결하려면 먼저 기본 드리프트를 수정합니다(인증서 시나리오 참조). 드리프트가 원인이 아닌 경우 Git을 통해서만 관리하는 워크로드는 자가 복구를 비활성화하는 것이 좋습니다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
spec:
  syncPolicy:
    automated:
      selfHeal: false
      prune: false

ApplicationSet 또는 리소스 소유권 충돌

두 개의 애플리케이션 또는 ApplicationSet가 동일한 Kubernetes 리소스를 관리하는 경우 Argo CD에 SharedResourceWarning이 표시됩니다. 리소스가 안정 상태에 도달하지 않습니다. 이는 일반적으로 공유 리소스 이름의 범위가 환경 또는 클러스터별로 지정되지 않은 경우에 발생합니다.

이 문제를 해결하려면:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: my-appset
spec:
  syncPolicy:
    preserveResourcesOnDeletion: true

리소스 파이널라이저로 인한 삭제 중단

애플리케이션이 Terminating 상태에서 멈추거나 ‘삭제할 객체가 N개 남음’이 표시되면 모든 관리형 리소스가 삭제될 때까지 resources-finalizer.argocd.argoproj.io 파이널라이저가 제거를 차단합니다. 자체적으로 처리할 수 없는 파이널라이저가 있는 관리형 리소스는 삭제를 무기한 차단합니다.

확인하려면 삭제 타임스탬프가 있지만 제거되지 않은 리소스를 나열합니다.

kubectl get all -n my-namespace -o json | \
  jq '.items[] | select(.metadata.deletionTimestamp != null) | {name: .metadata.name, kind: .kind, finalizers: .metadata.finalizers}'

이 문제를 해결하려면:

kubectl patch resource-kind
            resource-name -n my-namespace \
  --type json -p '[{"op": "remove", "path": "/metadata/finalizers/0"}]'

실패한 동기화가 동일한 리비전으로 자동 재시도되지 않음

특정 리비전에 대한 동기화가 실패하면 Argo CD는 동일한 리비전을 자동 재시도하지 않습니다. 이는 일반적으로 중복 환경 변수 키로 인한 ComparisonError와 같은 매니페스트 결함 때문에 발생합니다.

다음과 같이 애플리케이션 상태를 확인합니다.

argocd app get my-app
# Look for: Operation: Sync  Phase: Failed  Revision: <sha>

이 문제를 해결하려면 Git 리포지토리에서 매니페스트 결함을 수정하고 새 커밋을 푸시합니다. 또는 수동 동기화를 트리거합니다.

argocd app sync my-app
         

모노레포 커밋 변동으로 광범위한 재생성 트리거

많은 애플리케이션이 동일한 리포지토리에서 HEAD를 추적하는 경우 해당 리포지토리에 대한 커밋은 모든 애플리케이션에 대해 HEAD를 변경합니다. 이렇게 하면 해당 파일이 변경되지 않았더라도 모든 애플리케이션에 대한 매니페스트 재생성이 트리거됩니다. targetRevision 및 캐싱에 대한 자세한 내용은 이 페이지의 '애플리케이션 동기화 시간 증가' 섹션을 참조하세요.

재생성 범위를 각 애플리케이션이 사용하는 파일로만 지정하려면 manifest-generate-paths 주석을 추가합니다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  annotations:
    argocd.argoproj.io/manifest-generate-paths: /apps/my-app
spec:
  source:
    repoURL: https://github.com/my-org/my-monorepo.git
    targetRevision: HEAD
    path: apps/my-app

이 주석을 사용하면 Argo CD는 지정된 경로의 파일이 변경될 때만 매니페스트를 다시 생성합니다. 애플리케이션 간에 사용되는 공유 라이브러리의 경우 세미콜론(;)으로 구분하여 여러 경로를 지정할 수 있습니다.

가능하면 HEAD 대신 targetRevision을 브랜치 이름 또는 태그에 고정합니다.

Kubernetes 기본 설정 및 변형 웹후크는 팬텀 diff를 유발합니다.

동기화 직후 애플리케이션이 OutOfSync를 표시하면 설정하지 않은 필드(예: terminationGracePeriodSeconds, dnsPolicy 또는 /spec/replicas)에서 diff를 확인합니다. Kubernetes API 서버 또는 변형 웹후크가 적용 시 해당 필드를 추가했습니다.

다른 컨트롤러에서 관리하는 필드(예: HPA가 규모 조정을 관리하는 경우의 /spec/replicas)에 대해 이 문제를 해결하려면 ignoreDifferences를 추가합니다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
spec:
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jsonPointers:
        - /spec/replicas
  syncPolicy:
    syncOptions:
      - RespectIgnoreDifferences=true

Kubernetes 기본 설정 또는 변형 웹후크에 의해 추가된 필드의 경우 애플리케이션에서 서버 측 diff를 활성화할 수 있습니다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  annotations:
    argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true

서버 측 diff는 리소스별 드라이런 적용을 수행하므로 Kubernetes API 서버의 부하가 증가합니다. 이를 광범위하게 활성화하기 전에 소수의 애플리케이션에서 테스트하세요.

높은 이탈률의 컨트롤러 소유 리소스

일부 컨트롤러는 수명이 짧은 또는 자주 업데이트되는 리소스를 대량으로 생성합니다. 예를 들어 Karpenter 노드 객체, Cilium 자격 증명 및 엔드포인트 객체, Kyverno 정책 보고서가 있습니다. 이러한 리소스가 대량의 감시 이벤트를 생성하고 동기화 이탈을 유발하는 경우 해당 리소스 유형을 제외하거나 감시 이벤트를 필터링하여 부하를 줄일 수 있습니다. 이러한 변경에는 인스턴스 수준 컨트롤러 구성이 필요합니다.

관리형 기능에서 AWS Support 사례를 개설하여 이러한 리소스 유형에 대한 리소스 제외 또는 감시 이벤트 필터링을 요청합니다.

모범 사례

AWS Support에 문의해야 하는 경우

다음과 같은 경우 AWS Support 사례를 개설합니다.

Support 사례에 영향을 받는 애플리케이션에 대한 argocd app get 및 argocd app diff의 출력을 포함합니다.

다음 단계