**이 페이지 개선에 도움 주기** 

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

# Argo CD 기능 관련 문제 해결
<a name="argocd-troubleshooting"></a>

**참고**  
EKS 기능은 완전관리형 기능이며, 클러스터 외부에서 실행됩니다. 사용자에게 컨트롤러 로그 또는 컨트롤러 네임스페이스에 대한 액세스 권한이 없습니다. 문제 해결은 기능 상태, 애플리케이션 상태 및 구성에 중점을 둡니다.

## 기능이 ACTIVE 상태이지만 애플리케이션이 동기화되지 않음
<a name="_capability_is_active_but_applications_are_not_syncing"></a>

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

 **기능 상태 확인**:

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

 **콘솔**:

1. https://console.aws.amazon.com/eks/home\#/clusters에서 Amazon EKS 콘솔을 엽니다.

1. 클러스터 이름을 선택하세요.

1. **관찰성** 탭을 선택합니다.

1. **클러스터 모니터링**을 선택합니다.

1. **기능** 탭을 선택하여 모든 기능의 상태를 보세요.

 **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
```

 **일반적인 원인:**
+  **리포지토리가 구성되지 않음**: Git 리포지토리가 Argo CD에 추가되지 않음
+  **인증 실패**: SSH 키, 토큰 또는 CodeCommit 자격 증명이 유효하지 않음
+  **애플리케이션이 생성되지 않음**: 클러스터에 애플리케이션 리소스가 없음
+  **동기화 정책**: 수동 동기화가 필요함(자동 동기화가 활성화되지 않음)
+  **IAM 권한**: CodeCommit 또는 Secrets Manager에 대한 권한이 누락됨

 **애플리케이션 상태 확인**:

```
# 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}'
```

## 애플리케이션이 '진행 중' 상태로 멈춤
<a name="_applications_stuck_in_progressing_state"></a>

애플리케이션에 `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"
```

 **일반적인 원인:**
+  **배포 준비되지 않음**: 포드 시작 실패 또는 준비 프로브 실패
+  **리소스 종속성**: 리소스에서 다른 리소스가 준비되기를 기다림
+  **이미지 풀 오류**: 컨테이너 이미지에 액세스할 수 없음
+  **리소스 부족**: 클러스터에서 포드에 대한 CPU 또는 메모리가 부족함

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

```
# 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
```

## 리포지토리 인증 실패
<a name="_repository_authentication_failures"></a>

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}}
```

## 다중 클러스터 배포 문제
<a name="_multi_cluster_deployment_issues"></a>

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

 **클러스터 등록 확인**:

```
# 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 액세스 항목을 사용합니다.

다중 클러스터 구성에 대한 자세한 내용은 [대상 클러스터 등록](argocd-register-clusters.md) 섹션을 참조하세요.

## 다음 단계
<a name="_next_steps"></a>
+  [Argo CD 고려 사항](argocd-considerations.md) - Argo CD 고려 사항 및 모범 사례
+  [Argo CD 작업](working-with-argocd.md) - Argo CD 애플리케이션 생성 및 관리
+  [대상 클러스터 등록](argocd-register-clusters.md) - 다중 클러스터 배포 구성
+  [EKS 기능 문제 해결](capabilities-troubleshooting.md) - 일반 기능 문제 해결 지침