EKS Pistachio Cluster

EKS Pistachio Cluster

플레이스홀더 목록

이 문서는 다음 설정값을 사용하여 구성됨.

플레이스홀더	설명	예시
`pistachio`	리소스 접두사	pista, team1
`ap-southeast-1`	AWS 리전	ap-northeast-2
`1.35`	Kubernetes 버전	1.35
`t3.medium`	노드 인스턴스 유형	t3.medium
`pistachio-nodegroup-1`	노드그룹 이름	my-nodegroup-1
`team1/project`	ECR 리포지토리 이름	my-app-repo
`61203794945...`	ECR 이미지 URI	(AWS Account ID 포함)
`pistachio-db`	DB 식별자	my-db
`admin`	DB 마스터 사용자	admin
`password1234`	DB 마스터 암호	password1234

구성 프로세스

단계	작업	설명	도구/서비스
1	사전 준비	AWS CLI, kubectl, eksctl 설치 및 자격증명 설정	Terminal
2	EKS 클러스터 생성	VPC, 노드그룹(Private) 포함 클러스터 배포	eksctl
3	접속 설정	kubeconfig 업데이트 및 노드 상태 확인	AWS CLI / kubectl
4	워크로드 배포	애플리케이션 Deployment 및 Service 배포	kubectl
5	서비스 점검	로드밸런서 또는 포트포워딩을 통한 접속 확인	Browser / Terminal

--- 사전 설정

# kubectl 자동완성 (bash)
source <(kubectl completion bash)
echo 'source <(kubectl completion bash)' >> ~/.bashrc

# kubectl 별칭 설정
alias k=kubectl
complete -o default -F __start_kubectl k

클러스터 생성 (`pistachio`-cluster)

항목	값
클러스터 이름	`pistachio`-cluster
리전	`ap-southeast-1`
가용 영역	`ap-southeast-1a`, `ap-southeast-1b`
Kubernetes 버전	`1.35`
노드그룹 이름	`pistachio-nodegroup-1`
인스턴스 유형	`t3.medium`
노드 개수	`2` (min: `1`, max: `3`)
관리형 노드그룹	✅
OIDC	✅
ASG 권한	✅

eksctl 명령어

eksctl create cluster \
    --name pistachio-cluster \
    --region ap-southeast-1 \
    --zones ap-southeast-1a,ap-southeast-1b \
    --version 1.35 \
    --nodegroup-name pistachio-nodegroup-1 \
    --node-type t3.medium \
    --nodes 2 \
    --nodes-min 1 \
    --nodes-max 3 \
    --managed \
    --asg-access \
    --with-oidc

클러스터 관리

kubeconfig 설정

aws eks update-kubeconfig --region ap-southeast-1 --name pistachio-cluster

클러스터 확인

kubectl get nodes
kubectl get pods -A

클러스터 삭제

eksctl delete cluster --name pistachio-cluster --region ap-southeast-1

파드 배포

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 pistachio-repo \
    --region ap-southeast-1

리포지토리 삭제 (권장x)

aws ecr delete-repository \
    --repository-name pistachio-repo \
    --region ap-southeast-1 \
    --force

이미지 푸시

# 계정 ID 확인
export ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)

# ECR 로그인
aws ecr get-login-password --region ap-southeast-1 | docker login --username AWS --password-stdin $ACCOUNT_ID.dkr.ecr.ap-southeast-1.amazonaws.com

# 이미지 빌드 & 태그 (예: nginx 커스텀)
docker build -t pistachio-repo .
docker tag pistachio-repo:latest $ACCOUNT_ID.dkr.ecr.ap-southeast-1.amazonaws.com/pistachio-repo:latest

# 이미지 푸시
docker push $ACCOUNT_ID.dkr.ecr.ap-southeast-1.amazonaws.com/pistachio-repo:latest

이미지 확인

이름	명령어
이미지 목록	`aws ecr list-images --repository-name pistachio-repo --region ap-southeast-1`
이미지 상세 정보	`aws ecr describe-images --repository-name pistachio-repo --region ap-southeast-1`

Kubernetes 배포

위에서 푸시한 이미지를 사용하는 Deployment와 Service를 생성함.

# ECR 이미지 주소 변수 설정 (위에서 설정했다면 생략 가능)
export ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
export ECR_URI=$ACCOUNT_ID.dkr.ecr.ap-southeast-1.amazonaws.com/pistachio-repo:latest

# deployment.yaml 파일 생성
cat <<EOF > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: pista-web-deployment
  labels:
    app: pista-web
spec:
  replicas: 2
  selector:
    matchLabels:
      app: pista-web
  template:
    metadata:
      labels:
        app: pista-web
    spec:
      containers:
      - name: pista-web
        image: $ECR_URI
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: pista-web-service
spec:
  type: LoadBalancer
  selector:
    app: pista-web
  ports:
  - port: 80
    targetPort: 80
EOF

# 배포 적용
# (주의: envsubst가 없다면 $ECR_URI 부분을 직접 이미지 주소로 변경하여 저장 후 apply 하세요)
# envsubst 사용 시:
envsubst < deployment.yaml | kubectl apply -f -

# 또는 직접 파일을 수정한 경우:
kubectl apply -f deployment.yaml

Note: 노드그룹이 ECR 이미지를 가져오지 못하 ImagePullBackOff 에러가 발생하면, 노드 IAM 역할에 AmazonEC2ContainerRegistryReadOnly 정책이 있는지 확인함.

리소스 정리

모든 리소스를 삭제하여 비용 발생을 방지함.

1. Kubernetes 리소스 삭제

LoadBalancer(ELB) 삭제를 위해 Service를 먼저 삭제해야 함.

# 서비스 및 배포 삭제
kubectl delete service nginx-service
kubectl delete deployment nginx-deployment

# pista-web 서비스 및 배포 삭제
kubectl delete service pista-web-service
kubectl delete deployment pista-web-deployment

2. ECR 리포지토리 삭제

이미지가 남아있으면 삭제가 안 되므로 --force 옵션을 사용함.

aws ecr delete-repository \
    --repository-name pistachio-repo \
    --region ap-southeast-1 \
    --force

3. 클러스터 삭제

CloudFormation 스택을 포함하여 모든 인프라를 제거함.

eksctl delete cluster --name pistachio-cluster --region ap-southeast-1

트러블슈팅

EIP 한도 초과

에러: The maximum number of addresses has been reached

# 1. EIP 현황 확인
aws ec2 describe-addresses --region ap-southeast-1 --query 'Addresses[*].[PublicIp,AssociationId,AllocationId]' --output table

# 2. 미사용 EIP 해제 (AssociationId가 None인 것)
aws ec2 release-address --allocation-id <ALLOCATION_ID> --region ap-southeast-1

CloudFormation 스택 충돌

에러: Stack [eksctl-pistachio-cluster-cluster] already exists

# 1. TerminationProtection 비활성화
aws cloudformation update-termination-protection --no-enable-termination-protection --stack-name eksctl-pistachio-cluster-cluster --region ap-southeast-1

# 2. 스택 삭제
aws cloudformation delete-stack --stack-name eksctl-pistachio-cluster-cluster --region ap-southeast-1

# 3. 삭제 완료 대기
aws cloudformation wait stack-delete-complete --stack-name eksctl-pistachio-cluster-cluster --region ap-southeast-1

CloudFormation 스택 삭제 실패 (VPC)

에러: DELETE_FAILED - The following resource(s) failed to delete: [VPC]

원인: VPC 내 ENI 등 리소스가 남아있어 삭제 불가

# 스택 강제 삭제
aws cloudformation delete-stack \
    --stack-name eksctl-pistachio-cluster-cluster \
    --region ap-southeast-1 \
    --deletion-mode FORCE_DELETE_STACK

# 삭제 완료 대기
aws cloudformation wait stack-delete-complete \
    --stack-name eksctl-pistachio-cluster-cluster \
    --region ap-southeast-1

EKS Pistachio Cluster

목차

플레이스홀더 목록

구성 프로세스

클러스터 생성 (`pistachio`-cluster)

eksctl 명령어

클러스터 관리

kubeconfig 설정

클러스터 확인

클러스터 삭제

파드 배포

Deployment 생성 (nginx 예시)

Service 생성 (LoadBalancer)

배포 확인

빠른 배포 (명령어)

ECR 연동

리포지토리 생성

리포지토리 삭제 (권장x)

이미지 푸시

이미지 확인

Kubernetes 배포

리소스 정리

1. Kubernetes 리소스 삭제

2. ECR 리포지토리 삭제

3. 클러스터 삭제

트러블슈팅

EIP 한도 초과

CloudFormation 스택 충돌

CloudFormation 스택 삭제 실패 (VPC)

관련 문서

그래프 뷰

목차​

플레이스홀더 목록​

구성 프로세스​

클러스터 생성 (pistachio-cluster)​

eksctl 명령어​

클러스터 관리​

kubeconfig 설정​

클러스터 확인​

클러스터 삭제​

파드 배포​

Deployment 생성 (nginx 예시)​

Service 생성 (LoadBalancer)​

배포 확인​

빠른 배포 (명령어)​

ECR 연동​

리포지토리 생성​

리포지토리 삭제 (권장x)​

이미지 푸시​

이미지 확인​

Kubernetes 배포​

리소스 정리​

1. Kubernetes 리소스 삭제​

2. ECR 리포지토리 삭제​

3. 클러스터 삭제​

트러블슈팅​

EIP 한도 초과​

CloudFormation 스택 충돌​

CloudFormation 스택 삭제 실패 (VPC)​

관련 문서​

그래프 뷰

목차

플레이스홀더 목록

구성 프로세스

클러스터 생성 (`pistachio`-cluster)

eksctl 명령어

클러스터 관리

kubeconfig 설정

클러스터 확인

클러스터 삭제

파드 배포

Deployment 생성 (nginx 예시)

Service 생성 (LoadBalancer)

배포 확인

빠른 배포 (명령어)

ECR 연동

리포지토리 생성

리포지토리 삭제 (권장x)

이미지 푸시

이미지 확인

Kubernetes 배포

리소스 정리

1. Kubernetes 리소스 삭제

2. ECR 리포지토리 삭제

3. 클러스터 삭제

트러블슈팅

EIP 한도 초과

CloudFormation 스택 충돌

CloudFormation 스택 삭제 실패 (VPC)

관련 문서