NHN Cloud NKS(Kubernetes) 구성 방법: NCR 이미지 등록부터 배포·롤링 업데이트까지

NHN Cloud에서 쿠버네티스(NKS)로 웹 서버를 올리는 최소 흐름은 “컨테이너 이미지를 NCR에 올리고, 그 이미지를 3개 파드로 배포한 뒤, 로드밸런서와 롤링 업데이트로 운영”하는 것이다. 이 글은 클러스터 생성부터 이미지 2.0 업데이트까지 한 번에 따라 할 수 있게 정리했다. 화면 캡처는 2023년 12월 콘솔 기준이므로 메뉴 위치와 버전 항목은 현재와 다를 수 있다.

전체 구성은 어떻게 되나?

구성 요소는 세 가지다. 컨테이너가 실제로 도는 NKS 클러스터(워커 노드 3대), 이미지를 저장하고 버전을 관리하는 NCR(NHN Container Registry), 그리고 kubectl과 docker를 설치해 두고 클러스터를 조작할 관리용 인스턴스(예제 이름 kube-mgmt)다. 클러스터 생성에는 대상 프로젝트에서 Infrastructure ADMIN, Infrastructure LoadBalancer ADMIN, Infrastructure NKS ADMIN 중 하나 이상의 권한이 필요하다.1

NCR 활성화와 API 보안키는 어떻게 준비하나?

콘솔 상단의 서비스 선택에서 Container 그룹의 NCR을 활성화하면 왼쪽 메뉴의 Container 아래에 NCR이 추가된다.

NHN Cloud 콘솔 서비스 선택 화면의 Container 그룹에서 NKS, NCR, NCS 항목
서비스 선택 > Container 그룹
NHN Cloud 콘솔 왼쪽 메뉴 Container 하위에 NCR이 추가된 모습
활성화 후 왼쪽 메뉴에 NCR 추가

도커에서 NCR에 로그인하려면 User Access Key와 Secret Key가 필요하며, 콘솔 계정 메뉴의 API 보안 설정에서 만든다.2 꼭 알아둘 점은 세 가지다.

  • 키 ID는 NHN Cloud ID당, IAM ID당 각각 5개까지 만들 수 있다.2
  • Secret Key는 분실하면 다시 볼 수 없어 재발급해야 한다. 생성 직후 안전한 곳에 보관한다.2
  • 공식 문서는 User Access Key를 90일마다 교체하도록 권장한다.2 키를 글·저장소·스크린샷에 노출하지 않는다.

NKS 클러스터는 어떤 값으로 만드나?

Container > NHN Kubernetes Service(NKS)에서 클러스터 생성을 누르고 아래처럼 입력했다. 클러스터 이름은 32자 이내의 영문 소문자·숫자·하이픈만 쓸 수 있고 소문자로 시작해야 한다.1

항목 예제 값 비고
클러스터 이름 kube-cluster 이름 규칙 위 참고
Kubernetes 버전 v1.25.4 (당시) 지금은 콘솔에 표시되는 지원 버전 중에서 선택
노드 이미지 Ubuntu Server 20.04 LTS 당시 콘솔 화면 기준
인스턴스 타입 m2.c1m2 (vCPU 1, RAM 2GB) 실습용 최소 사양
노드 수 3 파드 3개를 분산 배포
블록 스토리지 HDD 60GB 키 페어는 기존 것 또는 새로 생성(.pem)
NKS 클러스터 생성 정보 확인 화면: 이름, 버전, 인스턴스 타입, 노드 수, 스토리지, 네트워크
클러스터 생성 정보 확인(2023-12 콘솔)

공식 문서 기준 클러스터 생성에는 약 10분이 걸리고, 목록의 작업 상태가 초록색이 되면 완료다.1 네트워크 CIDR을 직접 지정한다면 /24보다 큰 블록(/26 등)은 쓸 수 없고 VPC 서브넷·파드·서비스 네트워크가 서로 겹치면 안 된다.1

관리용 인스턴스에 docker와 kubectl은 어떻게 설치하나?

Compute > Instance에서 Ubuntu 인스턴스 하나(예: kube-mgmt, t2.c1m1, 디스크 20GB)를 만들고 플로팅 IP와 SSH(22번 포트) 접속 허용 보안 그룹을 붙인다. 접속 허용 범위는 가급적 본인 IP로 좁히는 것이 안전하다. 접속 후 docker부터 설치한다. 도커 공식 문서는 Ubuntu 22.04·24.04 등을 지원 대상으로 안내하며, docker-ce 패키지를 공식 apt 저장소에서 설치하라고 한다. 배포판의 docker.io가 깔려 있으면 충돌할 수 있어 먼저 제거한다.3

# 1) docker-ce 설치는 Docker 공식 문서의 Ubuntu apt 저장소 절차를 따른다
#    (docker.io 등 배포판 패키지가 깔려 있다면 먼저 제거)
# 2) 설치 확인
sudo docker run hello-world
sudo docker version

kubectl은 클러스터 버전과 마이너 버전 한 단계 이내의 것을 쓰라는 것이 쿠버네티스 문서의 권고다.4 아래 명령은 최신 stable을 받으므로, 클러스터가 그보다 두 단계 이상 낮다면 stable.txt 대신 클러스터와 맞는 버전을 지정해 내려받는다.

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
kubectl version --client

kubeconfig로 클러스터에 어떻게 연결하나?

NKS 클러스터 목록의 kubeconfig 파일 열 다운로드 버튼(또는 클러스터 선택 후 하단의 설정 파일 버튼)으로 파일을 받는다.1 이 파일에는 클러스터 접속 인증 정보가 들어 있어 사실상 비밀번호와 같다. 외부에 공유하지 말고 권한을 600으로 제한한다. 설정 전에는 kubectl get nodes가 아무 노드도 보여주지 않는다.

mkdir -p ~/.kube
vi ~/.kube/config      # 콘솔에서 받은 kubeconfig 내용을 붙여넣기
chmod 600 ~/.kube/config
kubectl get nodes      # 워커 노드 3대가 Ready 인지 확인

NCR에 이미지를 만들어 올리려면?

Container > NCR > 관리에서 레지스트리 생성을 눌러 이름(예: kube-ncr)을 입력하면 목록에 레지스트리 주소가 표시된다.2

NCR 레지스트리 생성 팝업: 이름 kube-ncr, Public URI 사용, 용도 일반
레지스트리 생성(이름 kube-ncr)

이미지 이름은 소문자·숫자와 -, _, /, .만 쓸 수 있고, 레지스트리 주소를 포함한 전체 저장소 이름은 255자, 태그는 128자 이내여야 한다.2 태그는 {레지스트리 주소}/{이미지 이름}:{태그} 형식이다. 원문은 실행 중인 컨테이너를 docker commit으로 이미지화했지만, 재현성을 위해 Dockerfile로 빌드하는 편이 일반적으로 더 낫다. 아래 주소는 예시이므로 본인 레지스트리 주소로 바꾼다.

# index.html 의 제목을 "container_nginx 1.0" 으로 바꿔 둔 뒤
cat > Dockerfile <<'EOF'
FROM nginx:stable
COPY index.html /usr/share/nginx/html/index.html
EOF

docker build -t example-kr1-registry.container.nhncloud.com/kube-ncr/ncr-nginx:1.0 .
docker run -d --name web-test -p 80:80 example-kr1-registry.container.nhncloud.com/kube-ncr/ncr-nginx:1.0
curl localhost        # 변경한 제목이 보이면 정상

로그인할 때 사용자명에는 User Access Key, 비밀번호에는 Secret Key를 입력한다. 로그인 토큰은 최대 12시간 유효하므로 오래 지나 push가 거부되면 다시 로그인한다.2

docker login example-kr1-registry.container.nhncloud.com
# Username: User Access Key ID
# Password: Secret Access Key
docker push example-kr1-registry.container.nhncloud.com/kube-ncr/ncr-nginx:1.0
NCR 콘솔의 kube-ncr/ncr_nginx 아티팩트 목록에 push한 이미지가 표시된 모습
push 후 NCR 아티팩트 목록 확인

이미지를 3개 파드로 배포하고 외부에 공개하려면?

비공개 레지스트리 이미지를 당겨오려면 파드가 인증 정보를 가져야 한다. 쿠버네티스는 kubernetes.io/dockerconfigjson 타입 Secret을 만들어 imagePullSecrets로 참조하는 방식을 안내하며, docker login 후 생성된 config.json을 그대로 쓰는 방법도 문서에 있다. 단 Secret의 값은 base64일 뿐 암호화가 아니므로 접근 권한(RBAC) 제한이 필요하다.5

kubectl create secret generic regcred \
  --from-file=.dockerconfigjson=$HOME/.docker/config.json \
  --type=kubernetes.io/dockerconfigjson
kubectl get secret regcred

다음은 Deployment 매니페스트다. 파일명은 ncr-nginx-deployment.yaml로 저장한다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ncr-nginx-deployment
  labels:
    app: ncr-nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: ncr-nginx
  template:
    metadata:
      labels:
        app: ncr-nginx
    spec:
      containers:
      - name: ncr-webserver
        image: example-kr1-registry.container.nhncloud.com/kube-ncr/ncr-nginx:1.0
        ports:
        - containerPort: 80
      imagePullSecrets:
      - name: regcred

적용한 뒤 type=LoadBalancer 서비스를 만들면 클라우드 제공자가 외부 로드밸런서를 붙여 준다. 외부 IP가 할당되기 전에는 EXTERNAL-IP가 pending으로 보일 수 있다. 3개 파드로 트래픽이 분산되므로, 브라우저에서 외부 IP에 접속해 1.0 페이지를 확인한다.6

kubectl apply -f ncr-nginx-deployment.yaml
kubectl get pods
kubectl expose deployment ncr-nginx-deployment --name=ncr-nginx-lb \
  --port=80 --target-port=80 --type=LoadBalancer
kubectl get services -o wide    # EXTERNAL-IP 가 할당될 때까지 대기

무중단으로 업데이트하고 되돌리려면?

이미지를 2.0으로 빌드해 push한 뒤 kubectl set image로 교체한다. Deployment의 기본 전략은 RollingUpdate(maxSurge 25%, maxUnavailable 25%)이며, 3개 파드 기준으로 새 파드를 하나씩 올리면서 기존 파드를 내리므로 서비스가 끊기지 않는다. 문제가 생기면 rollout undo로 이전 리비전으로 돌아간다.7

# 2.0 이미지를 빌드·push 한 뒤
kubectl set image deployment/ncr-nginx-deployment ncr-webserver=example-kr1-registry.container.nhncloud.com/kube-ncr/ncr-nginx:2.0
kubectl rollout status deployment/ncr-nginx-deployment
kubectl rollout history deployment/ncr-nginx-deployment
# 문제가 있으면 직전 버전으로 복귀
kubectl rollout undo deployment/ncr-nginx-deployment

실습이 끝나면 비용이 계속 나가지 않도록 LoadBalancer 서비스, 클러스터, 관리용 인스턴스, 플로팅 IP를 정리하고 사용하지 않는 API 보안키도 삭제한다. 클러스터 삭제에는 약 5분이 걸린다.1

  1. NHN Cloud 문서 – NKS 사용자 가이드
  2. NHN Cloud 문서 – NCR 사용자 가이드
  3. Docker Docs – Install Docker Engine on Ubuntu
  4. Kubernetes 문서 – Install and Set Up kubectl on Linux
  5. Kubernetes 문서 – Pull an Image from a Private Registry
  6. Kubernetes 문서 – Service
  7. Kubernetes 문서 – Deployments