EKS BLUE_PRINT
EKS BLUE_PRINT
목차
플레이스홀더 목록
이 문서를 사용하기 전에 다음 플레이스홀더를 실제 값으로 치환하여 사용함.
| 플레이스홀더 | 설명 | 예시 |
|---|---|---|
<REGION> | AWS 리전 | ap-northeast-2 |
<ACCOUNT_ID> | AWS 계정 ID | 123456789012 |
<CLUSTER_NAME> | EKS 클러스터 이름 | my-cluster |
<K8S_VERSION> | Kubernetes 버전 | 1.35 |
<NODE_TYPE> | 노드 인스턴스 유형 | t3.medium |
<NODEGROUP_NAME> | 노드그룹 이름 | my-nodegroup-1 |
<ECR_REPO_API> | ECR 리포지토리 이름 (API) | my-project/api |
<ECR_REPO_WEB> | ECR 리포지토리 이름 (Web) | my-project/web |
<DB_ID> | DB 식별자 | my-db |
<DB_USER> | DB 마스터 사용자 | admin |
<DB_PASSWORD> | DB 마스터 암호 | my-secret-password |
구성 프로세스
| 단계 | 작업 | 설명 | 도구/서비스 |
|---|---|---|---|
| 1 | 사전 준비 | AWS CLI, kubectl, eksctl 설치 및 자격증명 설정 | Terminal |
| 2 | EKS 클러스터 생성 | VPC, 노드그룹(Private) 포함 클러스터 배포 | eksctl |
| 3 | 접속 설정 | kubeconfig 업데이트 및 노드 상태 확인 | AWS CLI / kubectl |
| 4 | 워크로드 배포 | 애플리케이션 Deployment 및 Service 배포 | kubectl |
| 5 | 서비스 점검 | 로드밸런서 또는 포트포워딩을 통한 접속 확인 | Browser / Terminal |
--- 사전 요구사항
# eksctl 설치
brew install eksctl
# kubectl 설치
brew install kubectl
# AWS CLI 설정
aws configure
# kubectl 자동완성 (bash)
source <(kubectl completion bash)
echo 'source <(kubectl completion bash)' >> ~/.bashrc
# kubectl 자동완성 (zsh)
source <(kubectl completion zsh)
echo 'source <(kubectl completion zsh)' >> ~/.zshrc
# kubectl 별칭 설정
alias k=kubectl
complete -o default -F __start_kubectl k
템플릿
클러스터 생성 (<PREFIX>-cluster)
| 항목 | 값 |
|---|---|
| 클러스터 이름 | <PREFIX>-cluster |
| 리전 | <REGION> |
| 가용 영역 | <AZ1>, <AZ2> |
| Kubernetes 버전 | <K8S_VERSION> |
| 노드그룹 이름 | <NODEGROUP> |
| 인스턴스 유형 | <INSTANCE_TYPE> |
| 노드 개수 | <NODES> (min: <NODES_MIN>, max: <NODES_MAX>) |
| 관리형 노드그룹 | ✅ |
| OIDC | ✅ |
| ASG 권한 | ✅ |
eksctl 명령어
eksctl create cluster \
--name <PREFIX>-cluster \
--region <REGION> \
--zones <AZ1>,<AZ2> \
--version <K8S_VERSION> \
--nodegroup-name <NODEGROUP> \
--node-type <INSTANCE_TYPE> \
--nodes <NODES> \
--nodes-min <NODES_MIN> \
--nodes-max <NODES_MAX> \
--managed \
--asg-access \
--with-oidc
클러스터 관리
kubeconfig 설정
aws eks update-kubeconfig --region <REGION> --name <PREFIX>-cluster
클러스터 확인
kubectl get nodes
kubectl get pods -A
클러스터 삭제
eksctl delete cluster --name <PREFIX>-cluster --region <REGION>
파드 배포
Deployment 생성 (nginx 예시)
# nginx-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
labels:
app: nginx
spec:
replicas: 2
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:latest
ports:
- containerPort: 80
kubectl apply -f nginx-deployment.yaml
Service 생성 (LoadBalancer)
# nginx-service.yaml
apiVersion: v1
kind: Service
metadata:
name: nginx-service
spec:
type: LoadBalancer
selector:
app: nginx
ports:
- port: 80
targetPort: 80
kubectl apply -f nginx-service.yaml
배포 확인
# 파드 확인
kubectl get pods
# 서비스 확인 (EXTERNAL-IP 확인)
kubectl get svc nginx-service
# 파드 상세 정보
kubectl describe pod <POD_NAME>
# 파드 로그
kubectl logs <POD_NAME>
빠른 배포 (명령어)
# Deployment 생성
kubectl create deployment nginx --image=nginx --replicas=2
# Service 노출
kubectl expose deployment nginx --port=80 --type=LoadBalancer
# 확인
kubectl get all
ECR 연동
리포지토리 생성
aws ecr create-repository \
--repository-name <PREFIX>-repo \
--region <REGION>
리포지토리 삭제 (권장x)
aws ecr delete-repository \
--repository-name <PREFIX>-repo \
--region <REGION> \
--force
이미지 푸시
# 계정 ID 확인
export ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
# ECR 로그인
aws ecr get-login-password --region <REGION> | docker login --username AWS --password-stdin $ACCOUNT_ID.dkr.ecr.<REGION>.amazonaws.com
# 이미지 빌드 & 태그
docker build -t <PREFIX>-repo .
docker tag <PREFIX>-repo:latest $ACCOUNT_ID.dkr.ecr.<REGION>.amazonaws.com/<PREFIX>-repo:latest
# 이미지 푸시
docker push $ACCOUNT_ID.dkr.ecr.<REGION>.amazonaws.com/<PREFIX>-repo:latest
이미지 확인
| 이름 | 명령어 |
|---|---|
| 이미지 목록 | aws ecr list-images --repository-name <PREFIX>-repo --region <REGION> |
| 이미지 상세 정보 | aws ecr describe-images --repository-name <PREFIX>-repo --region <REGION> |
Kubernetes 배포
kubectl set image deployment/nginx-deployment nginx=$ACCOUNT_ID.dkr.ecr.<REGION>.amazonaws.com/<PREFIX>-repo:latest
리소스 정리
1. Kubernetes 리소스 삭제
kubectl delete service nginx-service
kubectl delete deployment nginx-deployment
2. ECR 리포지토리 삭제
aws ecr delete-repository \
--repository-name <PREFIX>-repo \
--region <REGION> \
--force
3. 클러스터 삭제
eksctl delete cluster --name <PREFIX>-cluster --region <REGION>
옵션 설명
| 옵션 | 설명 |
|---|---|
--managed | EKS 관리형 노드그룹 사용 (권장) |
--asg-access | Auto Scaling Group 권한 추가, 오토스케일링 사용 시 필요 |
--with-oidc | OIDC 프로바이더 활성화, IAM 역할 연동 시 필요 |
--nodes-min/max | 노드 오토스케일링 범위 설정 |
트러블슈팅
EIP 한도 초과
에러: The maximum number of addresses has been reached
# 1. EIP 현황 확인
aws ec2 describe-addresses --region <REGION> --query 'Addresses[*].[PublicIp,AssociationId,AllocationId]' --output table
# 2. 미사용 EIP 해제 (AssociationId가 None인 것)
aws ec2 release-address --allocation-id <ALLOCATION_ID> --region <REGION>
CloudFormation 스택 충돌
에러: Stack [eksctl-xxx-cluster] already exists
# 1. TerminationProtection 비활성화
aws cloudformation update-termination-protection --no-enable-termination-protection --stack-name eksctl-<PREFIX>-cluster-cluster --region <REGION>
# 2. 스택 삭제
aws cloudformation delete-stack --stack-name eksctl-<PREFIX>-cluster-cluster --region <REGION>
# 3. 삭제 완료 대기
aws cloudformation wait stack-delete-complete --stack-name eksctl-<PREFIX>-cluster-cluster --region <REGION>