Quickstart: 웹 앱 배포 및 데이터 저장

이 퀵스타트 튜토리얼은 eksctl을 사용해 Amazon EKS Auto Mode 클러스터에 2048 게임 샘플 애플리케이션을 배포하고 데이터를 영구 저장하는 단계를 안내합니다.

Amazon EKS Auto Mode는 블록 스토리지, 네트워킹, 로드 밸런싱, 컴퓨트 자동 확장 같은 일상 작업을 자동화해 클러스터 관리를 단순화합니다. 설정 중에 EC2 관리형 인스턴스로 노드 생성, 애플리케이션 로드 밸런서, EBS 볼륨을 처리해요. 요약하면, AWS 서비스와 매끄럽게 통합하는 데 필요한 커스텀 어노테이션이 있는 샘플 워크로드를 배포합니다.

출처: 문서

본문

이 튜토리얼에서 배울 내용

다음 eksctl 클러스터 템플릿을 사용해 자동 노드 프로비저닝을 위한 EKS Auto Mode로 클러스터를 구축합니다.

VPC 구성: 아래 eksctl 클러스터 템플릿을 사용하면 eksctl이 클러스터용 IPv4 Virtual Private Cloud(VPC)를 자동으로 생성합니다. 기본적으로 eksctl은 모든 네트워킹 요구를 해결하는 VPC를 구성하고 공용·프라이빗 엔드포인트도 만듭니다.
인스턴스 관리: EKS Auto Mode는 Kubernetes 애플리케이션의 수요에 따라 EKS 클러스터에서 노드를 동적으로 추가·제거합니다.
데이터 영속성: EKS Auto Mode의 블록 스토리지 기능을 사용해 Pod 재시작·실패 시나리오에서도 애플리케이션 데이터의 영속성을 보장합니다.
외부 앱 접근: EKS Auto Mode의 로드 밸런싱 기능을 사용해 Application Load Balancer(ALB)를 동적으로 프로비저닝합니다.

사전 조건

시작하기 전에 다음 작업을 수행했는지 확인하세요.

Amazon EKS용 환경 설정
최신 버전의 eksctl 설치

클러스터 구성

이 섹션에서는 동적 노드 프로비저닝을 위해 EKS Auto Mode를 사용하는 클러스터를 만듭니다.

cluster-config.yaml 파일을 만들고 다음 내용을 붙여 넣습니다. region-code를 유효한 리전(예: us-east-1)으로 바꾸세요.

apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: web-quickstart
  region:

autoModeConfig:
  enabled: true

이제 클러스터를 만들 준비가 되었습니다. cluster-config.yaml로 EKS 클러스터를 생성합니다.

eksctl create cluster -f cluster-config.yaml

Important: eksctl로 클러스터를 만들지 않으면 VPC 서브넷을 수동으로 태그해야 합니다.

IngressClass 생성

EKS Auto Mode용 Kubernetes IngressClass를 만듭니다. IngressClass는 EKS Auto Mode가 Ingress 리소스를 처리하는 방식을 정의합니다. 이 단계는 EKS Auto Mode의 로드 밸런싱 기능을 구성합니다. 애플리케이션용 Ingress 리소스를 만들 때 EKS Auto Mode는 이 IngressClass를 사용해 로드 밸런서를 자동으로 프로비저닝·관리하며, Kubernetes 애플리케이션을 AWS 로드 밸런싱 서비스와 통합합니다.

다음 yaml 파일을 ingressclass.yaml로 저장하세요.

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: alb
  annotations:
    ingressclass.kubernetes.io/is-default-class: "true"
spec:
  controller: eks.amazonaws.com/alb

IngressClass를 클러스터에 적용합니다.

kubectl apply -f ingressclass.yaml

2048 게임 샘플 애플리케이션 배포

이 섹션에서는 인기 있는 "2048 game"을 샘플 애플리케이션으로 클러스터에 배포하는 단계를 안내합니다. 제공된 매니페스트에는 Application Load Balancer(ALB)용 커스텀 어노테이션이 포함되어 있어요. 이 어노테이션들은 EKS가 수신 HTTP 트래픽을 "internet-facing"으로 처리하고, target type "ip"를 사용해 game-2048 네임스페이스의 적절한 서비스로 라우팅하도록 통합·지시합니다.

Note: 예시의 docker-2048 이미지는 x86_64 컨테이너 이미지이며 다른 아키텍처에서는 실행되지 않습니다.

--save-config 플래그로 game-2048이라는 Kubernetes 네임스페이스를 만듭니다.

kubectl create namespace game-2048 --save-config

다음 응답 출력이 보일 거예요.

namespace/game-2048 created

2048 Game Sample 애플리케이션을 배포합니다.

kubectl apply -n game-2048 -f https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.8.0/docs/examples/2048/2048_full.yaml

이 매니페스트는 game-2048 네임스페이스에 Kubernetes Deployment, Service, Ingress를 설정해 클러스터 내 game-2048 애플리케이션을 배포·노출하는 데 필요한 리소스를 만듭니다. 포트 80에서 배포를 노출하는 service-2048 서비스와 수신 HTTP 트래픽 라우팅 규칙과 internet-facing Application Load Balancer(ALB) 어노테이션을 정의하는 ingress-2048 Ingress 리소스를 생성합니다.

다음 응답 출력이 보일 거예요.

namespace/game-2048 configured
deployment.apps/deployment-2048 created
service/service-2048 created
ingress.networking.k8s.io/ingress-2048 created

다음 명령을 실행해 game-2048 네임스페이스의 Ingress 리소스를 가져옵니다.

kubectl get ingress -n game-2048

다음 응답 출력이 보일 거예요.

NAME           CLASS   HOSTS   ADDRESS                                                                    PORTS   AGE
ingress-2048   alb     *       k8s-game2048-ingress2-eb379a0f83-378466616.region-code.elb.amazonaws.com   80      31s

다음 단계를 시작하기 전에 Application Load Balancer(ALB)가 프로비저닝되는 데 몇 분 기다려야 합니다.

웹 브라우저를 열고 이전 단계의 ADDRESS를 입력해 웹 애플리케이션에 접근합니다. 예:

k8s-game2048-ingress2-eb379a0f83-378466616.region-code.elb.amazonaws.com

브라우저에서 2048 게임이 보일 거예요. 플레이해 보세요!

Amazon EKS Auto Mode로 데이터 영구 저장

이제 2048 게임이 Amazon EKS 클러스터에서 실행되고 있으므로, Amazon EKS Auto Mode의 블록 스토리지 기능을 사용해 게임 데이터가 안전하게 영구 저장되도록 할 차례입니다.

storage-class.yaml 파일을 만듭니다.

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: auto-ebs-sc
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: ebs.csi.eks.amazonaws.com
volumeBindingMode: WaitForFirstConsumer
parameters:
  type: gp3
  encrypted: "true"

StorageClass를 적용합니다.

kubectl apply -f storage-class.yaml

게임 데이터용 스토리지를 요청할 Persistent Volume Claim(PVC)을 만듭니다. ebs-pvc.yaml 파일을 만들고 다음 내용을 추가합니다.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: game-data-pvc
  namespace: game-2048
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: auto-ebs-sc

PVC를 클러스터에 적용합니다.

kubectl apply -f ebs-pvc.yaml

다음 응답 출력이 보일 거예요.

persistentvolumeclaim/game-data-pvc created

이제 2048 게임 배포를 업데이트해 이 PVC를 데이터 저장에 사용해야 합니다. 다음 배포는 게임 데이터 저장용 PVC를 사용하도록 구성되어 있어요. ebs-deployment.yaml 파일을 만들고 다음 내용을 추가합니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  namespace: game-2048
  name: deployment-2048
spec:
  replicas: 3  # Adjust the number of replicas as needed
  selector:
    matchLabels:
      app.kubernetes.io/name: app-2048
  template:
    metadata:
      labels:
        app.kubernetes.io/name: app-2048
    spec:
      containers:
        - name: app-2048
          image: public.ecr.aws/l6m2t8p7/docker-2048:latest
          imagePullPolicy: Always
          ports:
            - containerPort: 80
          volumeMounts:
            - name: game-data
              mountPath: /var/lib/2048
      volumes:
        - name: game-data
          persistentVolumeClaim:
            claimName: game-data-pvc

업데이트된 배포를 적용합니다.

kubectl apply -f ebs-deployment.yaml

다음 응답 출력이 보일 거예요.

deployment.apps/deployment-2048 configured

이 단계들로 클러스터의 2048 게임은 Amazon EKS Auto Mode의 블록 스토리지 기능을 사용해 데이터를 영구 저장하도록 설정됩니다. 이렇게 하면 Pod나 노드가 실패해도 게임 진행 상황과 데이터가 안전합니다.

이 튜토리얼이 마음에 들었다면 피드백을 보내 알려주세요. 더 많은 사용 사례별 퀵스타트 튜토리얼을 제공할 수 있게 됩니다.

정리(Clean up)

향후 비용 발생을 피하려면 VPC 네트워크를 포함해 이 가이드에서 만든 모든 리소스를 삭제하기 위해 연결된 CloudFormation 스택을 수동으로 삭제해야 합니다.

CloudFormation 스택을 삭제합니다.

eksctl delete cluster -f ./cluster-config.yaml

더 알아보기 (Learn more)

공식 문서