기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # GitHub 작업을 사용하여 EKS 클러스터에서 Amazon EKS Auto Mode 활성화 *Urbija Goswami 및 Anugrah Lakra, Amazon Web Services* ## 요약 [Amazon Elastic Kubernetes Service(EKS) ](https://docs.aws.amazon.com/whitepapers/latest/overview-deployment-options/amazon-elastic-kubernetes-service.html)클러스터는 일반적으로 노드 그룹을 통해 컴퓨팅 리소스를 수동으로 관리해야 합니다. 이렇게 하면 다음에 대한 운영 오버헤드가 발생합니다. + 용량 계획 및 조정 결정 + 노드 프로비저닝 및 수명 주기 관리 + 다양한 워크로드 유형에서의 비용 최적화 + 인프라 유지 관리 및 업데이트 Amazon EKS [Auto Mode](https://docs.aws.amazon.com/eks/latest/userguide/automode.html)는 워크로드 수요에 따라 노드를 동적으로 프로비저닝하고 조정하여 컴퓨팅 리소스 관리를 자동화하므로 수동 노드 그룹 관리가 필요하지 않습니다. 그러나 많은 조직이 기존 클러스터와 새 클러스터에서 Amazon EKS Auto Mode를 일관되게 활성화하고 관리하는 데 어려움을 겪고 있습니다. 일반적인 문제는 다음과 같습니다. + 기존 노드 그룹에서의 복잡한 마이그레이션 프로세스 + 전환 중 서비스 중단 위험 + 신중한 용량 계획 및 테스트 필요 + 특정 [Amazon IAM](https://aws.amazon.com/iam/?trk=6a436c72-0178-4620-97ad-0220ccc59fd0&sc_channel=ps&ef_id=CjwKCAjw7vzOBhBxEiwAc7WNr57daOn9724PwXVGy7aBxG_uuEHktjCWJbcY1q1BrZBaApyi1sAb_BoCQj0QAvD_BwE:G:s&s_kwcid=AL!4422!3!795924581177!e!!g!!amazon%20iam!23523526050!193629723318&gad_campaignid=23523526050&gbraid=0AAAAADjHtp_aCwsziIR-n3ST_xwoCqAuc&gclid=CjwKCAjw7vzOBhBxEiwAc7WNr57daOn9724PwXVGy7aBxG_uuEHktjCWJbcY1q1BrZBaApyi1sAb_BoCQj0QAvD_BwE) 권한 및 구성에 대한 요구 사항 + 여러 팀 및 환경 간의 조정 이 패턴은 특정 AWS 리전의 EKS 클러스터에서 EKS Auto Mode를 활성화하는 [GitHub Actions](https://docs.github.com/en/actions) 워크플로를 구현합니다. 자동 모드를 활성화하기 전에 워크플로는 클러스터 상태(클러스터 구성, 노드 그룹, Helm 릴리스 및 사용자 지정 리소스)의 타임스탬프가 지정된 백업을 생성하여 [Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) 버킷에 업로드합니다. 자동 모드를 활성화한 후 워크플로는 이전 노드 그룹을 드레이닝 및 삭제하고, 클러스터 역할 권한을 업데이트하고, Karpenter 및 Cluster Autoscaler와 같은 이전 조정 구성 요소를 정리합니다. 워크플로는 기존 지속적 통합 및 지속적 전달/배포(CI/CD) 파이프라인과 통합할 수 있습니다. ## 사전 조건 및 제한 사항 **사전 조건 ** **1: 필수 ** + 워크플로를 실행하기 위한 [GitHub 계정](https://github.com/) 및 자체 GitHub 리포지토리 + 관리 권한이 있는 활성 [AWS 계정](https://aws.amazon.com/account/) **2. 로컬 도구 설치** + [Terraform](https://developer.hashicorp.com/terraform/install) 버전 1.13.0 이상 + 적절한 자격 증명으로 구성된 [GitHub CLI](https://cli.github.com/)(gh) + 클러스터 관리를 위해 구성된 [kubectl](https://docs.aws.amazon.com/eks/latest/userguide/install-kubectl.html) 및 [eksctl](https://docs.aws.amazon.com/eks/latest/eksctl/installation.html) **3. EKS 클러스터 요구 사항** + Kubernetes 버전 1.29 이상 + 엔드포인트 액세스 구성: + 퍼블릭 및 프라이빗 엔드포인트로 설정됨  + 또는 프라이빗 서브넷에 NAT Gateway가 있는 프라이빗 엔드포인트 + [EKS API](https://docs.aws.amazon.com/eks/latest/userguide/grant-k8s-access.html) 및 [ConfigMap](https://docs.aws.amazon.com/eks/latest/userguide/auth-configmap.html) 클러스터 액세스 활성화됨(AKS가 Auto Mode 노드를 동적으로 관리하고 마이그레이션 중에 적절한 클러스터 인증을 위해 aws-auth ConfigMap을 업데이트하는 데 필요) + 활성 [노드 그룹 또는 관리형 노드 풀](https://docs.aws.amazon.com/eks/latest/userguide/managed-node-groups.html) **4. IAM OIDC 구성 요구 사항** + 다음을 포함하는 GitHub의 IAM 역할 및 자격 증명 공급자: + GitHub OIDC에 대한 신뢰 정책 + 다음에 대한 권한: + EKS 클러스터 관리 + S3 버킷 액세스 + IAM 역할 관리 + EC2 네트워크 관리 + Terraform을 사용한 간단한 설정은 [iam.tf](https://github.com/aws-samples/sample-enable-eks-auto-mode-using-github-actions/blob/main/iam.tf) 코드를 참조하세요. Terraform 코드가 적용되면 IAM 역할(GitHubActionsEKSRole)이 생성됩니다. **제한 사항** + Kubernetes 버전 1.29 이상의 EKS 클러스터만 지원 + Karpenter 버전 1.1.0 이상만 지원 + 리전별 구현. 일부 AWS 서비스는 일부 AWS 리전에서 사용할 수 없습니다. 리전 가용성은 [리전별 AWS 서비스를](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/) 참조하세요. + 클러스터 엔드포인트 접근성 필요 + AWS 관리형 노드 그룹으로 제한됨 ## 아키텍처 **대상 기술 스택 ** 1. [https://docs.github.com/en/actions](https://docs.github.com/en/actions) 1. [https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html) 1. [https://docs.aws.amazon.com/whitepapers/latest/overview-deployment-options/amazon-elastic-kubernetes-service.html](https://docs.aws.amazon.com/whitepapers/latest/overview-deployment-options/amazon-elastic-kubernetes-service.html) 1. [https://aws.amazon.com/s3/](https://aws.amazon.com/s3/) **대상 아키텍처·** ![](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/images/pattern-img/e1fa4e49-96a5-42ae-9886-766298664db4/images/a2c46a84-3bf5-4f1e-8216-ab29b4ba894e.png) 1. GitHub 작업 워크플로는 사용자가 GitHub 리포지토리에서 트리거합니다. 1. GitHub 작업 워크플로는 OIDC를 사용하여 AWS 계정에서 필요한 변경을 수행하는 IAM 역할을 수임합니다. 또한 계정에 EKS Auto Node 역할이 있는지 확인하고 없는 경우 역할이 생성되고 필요한 정책이 연결됩니다. 1. Auto Mode를 활성화해야 하는 EKS 클러스터의 현재 상태 백업이 S3 버킷에 업로드됩니다. 1. 자동 모드를 활성화해야 하는 클러스터의 클러스터 역할이 검색되고 EKS Auto Mode에 없는 경우 추가 권한(AmazonEKSComputePolicy, AmazonEKSBlockStoragePolicy, AmazonEKSLoadBalancingPolicy, AmazonEKSNetworkingPolicy, AmazonEKSClusterPolicy)이 추가됩니다. 또한 마이그레이션 전 단계로 클러스터의 서브넷이 EKS Auto Mode 활성화를 위한 태그로 업데이트됩니다. 1. 워크플로는 EKS 클러스터에서 EKS Auto Mode를 활성화합니다. 1. 이전 노드 그룹이 식별되고 삭제됩니다. 사용자가 아래 선택적 설정 단계에 설명된 IAM 역할에 대한 권한을 부여하지 않은 경우이 작업은 건너뜁니다. 1. 조정 구성 요소(Karpenter 및 Cluster Autoscaler)도 이전에 있는 경우 제거됩니다. GitHub 작업 워크플로는 세 가지 주요 작업으로 구성됩니다. 1. `check-clusters`: 자동 모드가 활성화되지 않은 클러스터를 식별하고 IAM 정책 및 서브넷 태그를 업데이트합니다. 1. `backup-and-check`: 마이그레이션 전에 클러스터 상태를 백업합니다. 1. `gradual-migration` : 기존 노드 그룹을 점진적으로 드레이닝하고 이전 조정 구성 요소를 정리하면서 자동 모드를 활성화합니다. 또한 마이그레이션 후 클러스터의 상태를 최종 확인합니다. **참고** 노드 구성 백업이 필요하거나 EKS Auto Mode로 마이그레이션하는 동안 노드/노드 그룹을 삭제하려는 경우 terraform 코드를 사용하여 생성된 IAM 역할을 aws-auth ConfigMap에 추가할 수 있습니다. 노드 그룹 구성이 없으면 노드 그룹 구성을 볼 수 있습니다.  ## 도구 *AWS CLI:* [Command Line Interface(CLI)](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)는 명령줄 쉘에서 명령을 사용하여 서비스와 상호 작용할 수 있는 오픈 소스 도구입니다. 솔루션에서는 AWS 서비스에 대한 명령줄 인터페이스를 사용하여 자동화 프로세스 전반에 걸쳐 EKS 클러스터 구성 업데이트, IAM 역할 업데이트 및 쿼리 클러스터 상태를 실행합니다. *Amazon EKS:* [Amazon Elastic Kubernetes Service (Amazon EKS)](https://docs.aws.amazon.com/eks/latest/userguide/what-is-eks.html)는 자체 Kubernetes 컨트롤 플레인 또는 노드를 설치하거나 유지 관리할 필요 없이 Kubernetes를 실행하는 데 도움이 됩니다. 이 패턴에서 Amazon EKS는 Auto Mode가 활성화되어 특정 리전의 클러스터에서 컴퓨팅 프로비저닝 및 노드 조정을 자동화하는 대상 서비스입니다. *IAM:* [AWS Identity and Access Management(IAM)](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html)를 사용하면 사용자에 대해 인증 및 권한 부여를 제어함으로써 AWS 리소스에 대한 액세스를 안전하게 관리할 수 있습니다. 솔루션에서는 이를 사용하여 GitHub Actions가 OIDC 페더레이션을 통해 EKS 클러스터 구성을 수정할 수 있는 권한을 관리합니다. 또한이 솔루션은 클러스터 역할 권한을 수정하고 EKS 노드 역할을 생성하는 작업을 추가하여 EKS Auto Mode가 노드 풀의 일부로 실행되는 새 노드에서 보류 중인 포드를 예약할 수 있도록 합니다. *Amazon S3***:** [Amazon Simple Storage Service(S3)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html)는 원하는 양의 데이터를 저장, 보호 및 검색하는 데 도움이 되는 클라우드 기반 객체 스토리지 서비스입니다. 솔루션에서는 S3 버킷을 사용하여 EKS Auto Mode가 활성화되기 전에 클러스터의 타임스탬프가 지정된 백업을 저장하므로 재해 복구에 도움이 됩니다. **기타 도구:** *GitHub 작업:* [GitHub Actions](https://docs.github.com/en/actions)는 솔루션에서 EKS Auto Mode 활성화 워크플로를 자동화하는 데 사용되는 CI/CD 플랫폼입니다. 또한 OIDC를 통해 보안 인증을 제공하고 여러 클러스터에서 파이프라인 실행을 관리합니다.   *HashiCorp Terraform:* Terraform은 코드를 사용하여 클라우드 인프라 및 리소스를 프로비저닝하고 관리하는 데 도움이 되는 오픈 소스 코드형 인프라(IaC) 도구입니다. 당사의 솔루션은 terraform을 사용하여 IAM 역할 및 정책을 프로비저닝하고 안전한 GitHub Actions 통합을 위한 OIDC 공급자 구성을 추가합니다.  **코드 리포지토리** 이 패턴의 코드는 GitHub [Actions 리포지토리를 통해 GitHub EKS Auto Mode Enablement](https://github.com/aws-samples/sample-enable-eks-auto-mode-using-github-actions/tree/main)에서 사용할 수 있습니다. ## 모범 사례 + **보안**: + 최소 권한 원칙을 따르고 작업을 수행하는 데 필요한 최소 권한을 부여하세요. 자세한 내용은 [IAM 설명서의 최소 권한 부여 및 보안 모범 사례를 참조하세요.](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege.) 최소 필수 구성은 리포지토리의 [iam.tf](https://github.com/aws-samples/sample-enable-eks-auto-mode-using-github-actions/blob/main/iam.tf) 파일을 참조하세요.  + 권한 없는 워크플로 실행이 역할을 수임하지 못하도록 IAM 역할 신뢰 정책의 범위를 특정 GitHub 리포지토리 및 브랜치로 지정합니다.  + 마이그레이션을 시작하기 전에 EKS 컨트롤 플레인 로깅(API 서버, 감사, 인증자)을 활성화하면 자동 모드가 활성화된 후 예약 또는 인증 문제를 진단할 수 있습니다.  + [백업 스크립트](https://github.com/aws-samples/sample-enable-eks-auto-mode-using-github-actions/blob/main/scripts/backup-cluster-state.sh)의 모든 aws s3 cp 명령에 --sse AES256을 추가하여 클러스터 상태 백업에 서버 측 암호화를 적용합니다.  + **신뢰성**: + 먼저 비프로덕션 클러스터에 대해 워크플로를 테스트합니다. 프로덕션 클러스터를 마이그레이션하기 전에 Auto Mode 노드에서 워크로드가 올바르게 다시 예약되었는지 확인합니다.  + 자동 모드 활성화를 진행하기 전에 S3 백업이 성공적으로 완료되었고 유효한 클러스터 구성, 노드 그룹, Helm 릴리스 및 사용자 지정 리소스 데이터가 포함되어 있는지 확인합니다.  + Auto Mode를 활성화한 후 [Amazon CloudWatch Container Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ContainerInsights.html)를 사용하여 포드 예약 이벤트 및 노드 프로비저닝 지연 시간을 모니터링하여 문제를 조기에 감지합니다.  + **성능:** + Auto Mode 노드 풀 조정 패턴을 주기적으로 검토하고 워크로드 리소스 요청 및 제한을 조정하여 과다 프로비저닝 또는 예약 지연을 방지합니다. + **비용:** + EKS 클러스터 및 관련 리소스(IAM 역할, S3 백업 버킷, 서브넷)에 환경 및 소유권 메타데이터를 태그하여 비용 추적 및 운영 가시성을 지원합니다. 자세한 내용은 [AWS 리소스 태깅 설명서를](https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html.) 참조하세요. 마이그레이션 프로세스 중에 워크플로 파일을 편집하여 사용자 지정 태그를 추가할 수 있습니다.  + 자동 모드는 인스턴스 유형 및 조정 동작을 변경할 수 있으므로 자동 모드를 활성화한 후 컴퓨팅 비용의 변경 사항을 모니터링하도록 AWS Cost Explorer 알림을 설정합니다. 자세한 내용은 [AWS Cost Explorer 설명서를](https://docs.aws.amazon.com/cost-management/latest/userguide/ce-what-is.html.) 사용하여 비용 분석을 참조하세요.   + **작업**: + 워크플로 파일과 Terraform 구성을 버전 제어에 유지하고 리전, 역할 ARN 또는 S3 버킷 이름과 같은 환경별 재정의를 문서화합니다.    ## 에픽 ### 도구 SetUp | 작업 | 설명 | 필요한 기술 | | --- | --- | --- | | GitHub 리포지토리를 구성합니다. | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/enable-eks-auto-mode-using-github-actions.html) | AWS DevOps, 클라우드 아키텍트 | ### (선택 사항) IAM 역할 설정 | 작업 | 설명 | 필요한 기술 | | --- | --- | --- | | 백업 및 노드 그룹 삭제를 위한 IAM 설정 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/enable-eks-auto-mode-using-github-actions.html)
eksctl create iamidentitymapping \ --cluster $CLUSTER_NAME\ --region us-east-1 \ --arn arn:aws:iam::$ACCOUNT_ID:role/GitHubActionsEKSRole \ --group system:masters \ --username github-actions
**$CLUSTER\_NAME** 및 **$ACCOUNT\_ID**를 적절한 값으로 바꿉니다.[See the AWS documentation website for more details](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/enable-eks-auto-mode-using-github-actions.html)
CLUSTERS=$(aws eks list-clusters --region $AWS_REGION --query 'clusters[]' --output text)

CLUSTERS_NEEDING_AUTO_MODE=""

for cluster in $CLUSTERS; do
    
    
    AUTO_MODE=$(aws eks describe-cluster --name $cluster --region $AWS_REGION --query 'cluster.computeConfig.enabled' --output text 2>/dev/null || echo "false")
    
    if [ "$AUTO_MODE" != "True" ]; then
       
        CLUSTERS_NEEDING_AUTO_MODE="$CLUSTERS_NEEDING_AUTO_MODE $cluster"
        
        echo " Adding role access to cluster..."
        eksctl create iamidentitymapping \
          --cluster $cluster \
          --region $AWS_REGION \
          --arn $ROLE_ARN \
          --group system:masters\
          --username github-actions || echo "  ⚠️  Role mapping may already exist"
        
        echo "  ✅ Role access configured for $cluster"
done

**$AWS\_REGION** 및 **$ROLE\_ARN**을 각각 위에서 생성한 IAM 역할의 특정 리전 및 ARN으로 바꿉니다. | AWS DevOps, 클라우드 아키텍트 | ### 실행 및 검증 | 작업 | 설명 | 필요한 기술 | | --- | --- | --- | | GitHub 작업 워크플로를 트리거합니다. | 변경 사항이 기능, 기본 또는 개발 브랜치로 푸시되면 워크플로가 자동으로 트리거됩니다. GitHub UI를 통해 수동으로 트리거하려면: 1. GitHub 2의 리포지토리로 이동합니다. "작업" 탭 3을 클릭합니다. 워크플로(auto-mode-pipeline) 4를 선택합니다. “워크플로 실행” 버튼 5를 클릭합니다. 브랜치를 선택하고 "워크플로 실행"을 클릭합니다.
워크플로는 AWS CLI를 사용하여 마이그레이션된 각 클러스터의 컴퓨팅 구성을 쿼리하여 EKS Auto Mode가 성공적으로 활성화되었는지 확인하고 현재 컴퓨팅 설정을 테이블 형식으로 표시하여 마이그레이션 후 [확인을 ](https://github.com/aws-samples/sample-enable-eks-auto-mode-using-github-actions/blob/22b546b05630c63e5637928ad8a4f5947ad8fb33/.github/workflows/enable-eks-auto-mode.yml#L283)처리합니다. | AWS DevOps, 클라우드 아키텍트 | ### 다중 환경 배포 구성 | 작업 | 설명 | 필요한 기술 | | --- | --- | --- | | 다중 환경 배포 구현. | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/enable-eks-auto-mode-using-github-actions.html) | | ### 정리 | 작업 | 설명 | 필요한 기술 | | --- | --- | --- | | 리소스를 정리하십시오. | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/enable-eks-auto-mode-using-github-actions.html) | 일반 AWS, 클라우드 아키텍트 | ## 문제 해결 | 문제 | Solution | | --- | --- | | **인증 문제**

| • GitHub OIDC 공급자가 AWS IAM에서 올바르게 구성되었는지 확인
• git 보안 암호의 IAM 역할 ARN이 terraform(GitHubActionsEKSRole)으로 생성된 실제 역할과 일치하는지 확인합니다.
• GitHub 리포지토리에 필요한 보안 암호가 구성되어 있는지 확인합니다. AWS\_REGION 및 AWS\_ROLE\_ARN.
• AWS 리전 설정이 클러스터 위치와 일치하는지 확인 | | **권한 문제**

| • 로컬에서 IAM 역할 권한 테스트: bash aws sts assume-role --role-arn --role-session-name test-session aws eks list-clusters
• 역할에 eks:UpdateClusterConfig 및 eks:DescribeCluster 권한이 있는지 확인합니다. | | **클러스터 호환성**

| • EKS 클러스터가 Kubernetes 1.29 이상을 실행 중인지 확인: bash aws eks describe-cluster --name --query 'cluster.version'
• 자동 모드를 활성화하기 전에 클러스터가 ACTIVE 상태인지 확인 | | **워크플로 실패**
| • GitHub 작업 로그에서 특정 오류 메시지 확인
• .github/workflows/auto-mode-pipeline.yml에서 워크플로 파일 구문 확인
• 워크플로에서 환경 변수가 올바르게 설정되었는지 확인 | ## 관련 리소스 1. [시작하기 위한 EKS Auto Mode 공식 설명서](https://docs.aws.amazon.com/eks/latest/userguide/automode.html) 1. [클러스터 구성 CLI 설명서 업데이트](https://docs.aws.amazon.com/cli/latest/reference/eks/update-cluster-config.html) 1. [GitHub 작업에 대한 GitHub 보안 암호](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets) 1. [GitHub 작업 설명서](https://docs.github.com/en/actions)  1. [OIDC 페더레이션 설명서](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html)