Kubernetes Engine으로 쿠버네티스 클러스터 구축

Kubernetes Engine을 이용하여 쿠버네티스 클러스터를 생성하고 웹 서비스를 배포합니다.

기본 정보

• 예상 소요 시간: 30분
  
• 권장 운영 체제: macOS
• 사전 준비 사항
  • IAM 액세스 키

시나리오 소개

이 튜토리얼은 Kubernetes Engine을 사용해 카카오클라우드에서 쿠버네티스 클러스터를 생성하고, 클러스터에 웹 서비스를 배포하는 과정을 안내합니다. 예제 프로젝트의 컨테이너 이미지를 Container Registry에서 pull하여, 클러스터 내에 구성된 서비스로 배포하고 외부 접속을 위한 로드 밸런서를 설정합니다.

주요 내용은 다음과 같습니다.

• 쿠버네티스 클러스터 및 노드 풀 생성
• kubectl 및 인증 설정을 통한 클러스터 접근
• Container Registry 연동을 위한 시크릿 구성
• 예제 애플리케이션 배포 및 로드 밸런서 설정
• 퍼블릭 IP 연결을 통한 서비스 접속 확인

이 시나리오는 카카오클라우드 환경에서 쿠버네티스 기반의 배포 및 운영을 처음 시작하는 사용자를 위한 기본 구성 예제로 설계되었습니다.

시작하기 전에

1. 네트워크 환경 구축

카카오클라우드에서 컴퓨팅 환경을 구축하기 위해, 우선 네트워크 환경 설정이 필요합니다. 이를 위해, 다중 가용 영역에서 NAT 인스턴스를 이용한 네트워크 구축을 참조하여 쿠버네티스 클러스터 생성을 위한 네트워크 환경을 구축하세요. 이 문서는 private 서브넷에서도 인터넷에 안전하게 연결할 수 있도록 NAT 인스턴스 생성 방법을 설명합니다. 이 문서에서 설명하는 네트워크 설정은 다중 가용 영역에서 NAT 인스턴스를 이용한 네트워크 구축 문서에서 정한 값에 기반합니다.

2. 예제 프로젝트 컨테이너 이미지 배포

튜토리얼을 진행하기 위해서 예제 프로젝트를 사용합니다. 다음 문서 Container Registry를 이용한 이미지 저장 및 사용를 확인하여 예제 프로젝트의 컨테이너 이미지를 카카오클라우드 Container Registry에 배포합니다.

시작하기

Step 1. 쿠버네티스 클러스터 생성

Kubernetes Engine은 VPC 기반의 관리형 쿠버네티스 서비스입니다. 복잡한 수작업 클러스터 생성/관리 절차 없이 손쉽게 쿠버네티스 클러스터를 생성하고 관리할 수 있습니다. 이 단계에서는 카카오클라우드 콘솔에 로그인하여 서비스 구성에 필요한 리소스를 직접 생성합니다. 카카오클라우드에서는 콘솔을 통해 쉽게 쿠버네티스 클러스터를 생성하는 방법은 다음과 같습니다.

1. 카카오클라우드 콘솔 > Container Pack > Kubernetes Engine > 클러스터 목록 화면에서 [클러스터 생성] 버튼을 클릭합니다.

2. 아래 내용을 참조하여 생성할 클러스터 정보와 VPC를 설정합니다.

   구분	항목	설정/입력값
   기본 설정	클러스터 이름	tutorial
   	Kubernetes 버전	1.30
   클러스터 Network 설정	VPC	tutorial
   	서브넷	- main - {VPC_ID}_sn_1 - {VPC_ID}_sn_2 - {VPC_ID}_sn_6

3. 클러스터 목록 화면에서 [생성한 클러스터] > [노드 풀] 탭에서 [노드 풀 생성] 버튼을 클릭합니다.

4. 아래 내용을 참조하여 노드 풀을 생성합니다.

   노드 풀 유형	인스턴스 유형	볼륨	노드 수
   Virtual Machine	m2a.large	50	2

Step 2. kubectl로 쿠버네티스 API 호출

쿠버네티스 커맨드 라인 도구인 kubectl으로 명령어를 실행하여 쿠버네티스 API를 호출합니다. 클러스터와의 모든 상호작용은 제어 영역에 있는 쿠버네티스 API 서버에 API 호출을 통해 수행됩니다.

kubectl 설치

kubectl을 사용하기 위해 먼저 설치를 진행합니다. 사용자 환경에 따라 설치를 진행해 주시기 바랍니다.

Mac

1. Homebrew 패키지 매니저를 이용하거나, curl 명령어를 이용하여 설치합니다.

   Homebrew 이용

   brew install kubectl

   curl 이용(Intel)

   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl"

   curl 이용(Apple Silicon)

   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl"

2. 설치가 정상적으로 되었는지 아래 명령어를 통해 확인합니다.

   버전 확인

   kubectl version --client

Linux(Ubuntu)

1. curl 명령어를 이용하여 설치합니다.

   curl 이용

   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

2. 설치가 정상적으로 되었는지 아래 명령어를 통해 확인합니다.

   버전 확인

   kubectl version --client

kubeconfig 파일 다운로드 및 설정

1. Kubernetes Engine에서 생성한 클러스터의 [kubectl 파일] 버튼을 클릭합니다.

2. 생성한 쿠버네티스 클러스터의 kubeconfig 파일을 kubeconfig 파일 팝업창에서 [kubeconfig 파일 다운로드] 버튼을 클릭해 다운로드합니다.

3. 클러스터에 대한 접근을 구성하기 위해 다운로드받은 kubeconfig 파일(.yaml)에서 users > user > exec > env 필드를 수정합니다. 액세스 키 ID와 보안 키 입력 필드에서 생성한 키 ID와 보안 키 값을 입력합니다.

   users:
   - name: ${클러스터 이름}-admin
   user:
       exec:
       apiVersion: client.authentication.k8s.io/v1beta1
       args: null
       command: kic-iam-auth
       env:
       - name: "OS_AUTH_URL"
         value: "https://iam.kakaocloud.com/identity/v3"
       - name: "OS_AUTH_TYPE"
         value: "v3applicationcredential"
       - name: "OS_APPLICATION_CREDENTIAL_ID"
         value: "${액세스 키 ID 입력}"
       - name: "OS_APPLICATION_CREDENTIAL_SECRET"
         value: "${보안 액세스 키 입력}"
       - name: "OS_REGION_NAME"
         value: "kr-central-2"

4. 기본적으로 kubectl은 $HOME/.kube/config 파일에 저장된 정보를 통해 클러스터에 접근합니다. 설정한 kubeconfig 파일을 $HOME/.kube/config 경로에 복사합니다.

   mkdir $HOME/.kube
   cp ${KUBECONFIG_FILE_PATH} $HOME/.kube/config

   환경변수	설명
   KUBECONFIG_FILE_PATH🖌︎	다운로드한 kubeconfig 파일 경로

   예시) cp ~/Downloads/kubeconfig-cluster.yaml ~/.kube/config

카카오클라우드 인증 클라이언트 다운로드 및 설정

카카오클라우드 인증 클라이언트를 다운로드한 뒤, 카카오클라우드 인증 클라이언트에 실행 권한을 부여합니다. 그 다음, 인증 클라이언트가 실행되는 경로로 이동합니다.

sudo chmod +x ${IAM_FILE_PATH}
mv ${IAM_FILE_PATH} /usr/local/bin

환경변수	설명
IAM_FILE_PATH🖌︎	설치한 인증 클라이언트 파일 경로

쿠버네티스 API 호출

kubectl을 통해 쿠버네티스 API를 호출할 수 있습니다. 다음 명령어를 입력하면 클러스터 내 생성된 노드 목록을 조회할 수 있습니다.

kubectl get nodes

Step 3. 쿠버네티스에 서비스 배포

1. 비공개 Container Registry에서 이미지를 pull하기 위해서는 인증이 필요합니다. 인증을 위한보안 키를 생성합니다.

   Container Registry 인증 시크릿 생성

   kubectl create secret docker-registry kc-cr-secret \
   --docker-server=${PROJECT_NAME}.kr-central-2.kcr.dev \
   --docker-username=${ACCESS_KEY} \
   --docker-password=${ACCESS_SECRET_KEY}

   환경변수	설명
   PROJECT_NAME🖌︎	카카오클라우드 콘솔의 프로젝트 이름
   ACCESS_KEY🖌︎	액세스 키
   ACCESS_SECRET_KEY🖌︎	보안 액세스 키

2. 예제 프로젝트의 서버를 배포합니다.

   서버 배포

   cat <<EOF | kubectl create -f-
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: server-deployment
   spec:
     replicas: 2
     selector:
       matchLabels:
         app: server
     template:
       metadata:
         labels:
           app: server
       spec:
         containers:
         - name: server
           image: ${PROJECT_NAME}.kr-central-2.kcr.dev/${CONTAINER_REPOSITORY_NAME}/kakaocloud-library-server:latest
           env:
           - name: PROFILE
             value: "local"
           ports:
           - containerPort: 8080
         imagePullSecrets:
         - name: kc-cr-secret
   EOF

   환경변수	설명
   PROJECT_NAME🖌︎	Container Registry를 생성한 카카오클라우드 콘솔의 프로젝트 이름
   CONTAINER_REPOSITORY_NAME🖌︎	Container Registry에서 생성한 리포지토리의 이름

3. 예제 프로젝트 서버에 접속하기 위한 서비스를 배포합니다.

   서버 service 배포

   cat <<EOF | kubectl create -f-
   apiVersion: v1
   kind: Service
   metadata:
     name: server-service
   spec:
     type: ClusterIP
     selector:
       app: server
     ports:
     - protocol: TCP
       port: 8080
       targetPort: 8080
   EOF

4. 예제 프로젝트의 클라이언트를 배포합니다.

   클라이언트 deployment 배포

   cat <<EOF | kubectl create -f-
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: client-deployment
   spec:
     replicas: 2
     selector:
       matchLabels:
         app: client
     template:
       metadata:
         labels:
           app: client
       spec:
         containers:
         - name: client
           image: ${PROJECT_NAME}.kr-central-2.kcr.dev/${CONTAINER_REPOSITORY_NAME}/kakaocloud-library-client:latest
           env:
           - name: SERVER_ENDPOINT
             value: "http://server-service.default.svc.cluster.local:8080"
           ports:
           - containerPort: 80
         imagePullSecrets:
         - name: kc-cr-secret
   EOF

   환경변수	설명
   PROJECT_NAME🖌︎	Container Registry를 생성한 카카오클라우드 콘솔의 프로젝트 이름
   CONTAINER_REPOSITORY_NAME🖌︎	Container Registry에서 생성한 리포지토리의 이름

5. 예제 프로젝트 클라이언트에 접속하기 위한 서비스를 배포합니다. 서비스는 LoadBalancer 유형으로 생성합니다.

   클라이언트 service 배포

   cat <<EOF | kubectl create -f-
   apiVersion: v1
   kind: Service
   metadata:
     name: client-service
   spec:
     type: LoadBalancer
     selector:
       app: client
     ports:
     - protocol: TCP
       port: 80
       targetPort: 80
   EOF

Step 4. 콘솔에서 로드 밸런서 설정

예제 프로젝트 클라이언트의 service를 LoadBalancer 유형으로 배포하면서, 카카오클라우드 콘솔에서 Load Balancer 서비스의 로드 밸런서 목록에도 추가된 것을 확인할 수 있습니다. 로드 밸런서 목록 > [⋮] 버튼 > [퍼블릭 IP 연결] 버튼을 클릭해 외부에서 서비스에 접근할 수 있게 만들 수 있습니다.

Step 5. 서비스 접속 확인

브라우저에서 등록한 퍼블릭 IP로 접속하여 서비스를 확인합니다. 정상적으로 연결된 경우, '카카오클라우드 도서관' 서비스 화면을 볼 수 있습니다.