Building a Deployment History of Four Revisions

한국어 원문으로 표시합니다.

목표

install, upgrade, 실패, rollback 까지 리비전 네 개를 직접 만들어 보고, Helm 이 그 역사를 클러스터 어디에 어떤 형태로 남기는지 확인합니다.

왜 중요한가

Helm 3 에는 클러스터에 상주하는 서버 컴포넌트가 없습니다. 그러면 "이 릴리스가 지금 몇 번째 판인지"는 어디에 있을까요 — 릴리스가 설치된 네임스페이스의 Secret 에 있습니다. 이름은 sh.helm.release.v1.<릴리스이름>.v<리비전> 이고 타입은 helm.sh/release.v1 이며, 그 안에 차트 메타데이터·렌더링된 매니페스트·values·상태가 압축되어 들어 있습니다. 리비전마다 시크릿이 하나씩 쌓이므로 배포 역사가 클러스터 자체에 남습니다. 여기서 반드시 몸으로 익혀야 할 두 가지가 있습니다. 첫째, 실패한 업그레이드도 리비전으로 남습니다 — 상태가 failed 로 기록되고 실물은 직전 상태 그대로 지켜집니다. 둘째, 롤백은 되돌리는 것이 아니라 새 리비전을 만드는 일입니다 — 리비전 2로 롤백하면 번호가 2로 돌아가는 것이 아니라 리비전 4가 새로 생깁니다. 리비전은 언제나 앞으로만 갑니다.

단계

/root/helm/rel/lab-app 에 차트를 하나 만들고(helm create lab-app 이면 충분합니다), 네임스페이스 helm-lab 에 릴리스 이름 lab-app 으로 설치하세요: helm install lab-app /root/helm/rel/lab-app -n helm-lab --create-namespace --set replicaCount=1. 이것이 리비전 1입니다. helm-lab 에 app.kubernetes.io/managed-by=Helm 라벨이 붙은 Deployment 가 하나 생겨야 합니다. 산출물 디렉터리 /root/helm/rel/out 도 미리 만드세요.
helm upgrade lab-app /root/helm/rel/lab-app -n helm-lab --set replicaCount=3 으로 리비전 2를 만드세요. 그다음 그 리비전에 적용된 사용자 값을 /root/helm/rel/out/rev2-values.json 에 저장하세요(helm get values lab-app -n helm-lab --revision 2 -o json). 파일은 올바른 JSON 이어야 하고 replicaCount 가 3이어야 합니다.
helm history lab-app -n helm-lab -o json > /root/helm/rel/out/history.json 으로 이력을 저장하세요. 리비전이 2개 이상이고, 각 항목에 chart·app_version·status 필드가 있어야 하며, 상태가 superseded 인 리비전이 최소 하나 있어야 합니다.
렌더링은 되지만 API 서버가 거부하는 업그레이드를 일부러 한 번 하세요: helm upgrade lab-app /root/helm/rel/lab-app -n helm-lab --set replicaCount=abc. replicas 는 정수여야 하므로 매니페스트가 거부됩니다. 표준 오류까지 포함해 출력을 /root/helm/rel/out/failed.txt 에 저장하세요(> /root/helm/rel/out/failed.txt 2>&1). 이것이 리비전 3이며 상태는 failed 로 남고, 실제 Deployment 의 spec.replicas 는 3 그대로여야 합니다. --atomic 은 붙이지 마세요 — 붙이면 자동 롤백되어 실패 리비전을 관찰할 수 없습니다.
helm rollback lab-app 2 -n helm-lab 으로 리비전 2의 상태로 되돌리세요. 이것이 리비전 4입니다. 이력의 최신 리비전 번호가 4 이상이고, 그 리비전의 설명에 rollback 이 들어가며, 상태는 deployed, 실제 Deployment 의 spec.replicas 는 3이어야 합니다.
helm get values lab-app -n helm-lab -a -o json > /root/helm/rel/out/all-values.json 과 helm get values lab-app -n helm-lab -o json > /root/helm/rel/out/user-values.json 을 각각 저장하세요. 전체 값 파일에는 최상위 키가 3개 이상이고 image 가 포함되어야 하며, 사용자 값 파일의 키 개수는 그보다 적어야 합니다.
kubectl get secret -n helm-lab -l owner=helm 으로 릴리스 시크릿을 확인하세요. 리비전 수만큼(4개 이상) 있고, 타입은 helm.sh/release.v1, 이름은 sh.helm.release.v1.lab-app.v<리비전> 형식이어야 합니다. 확인한 내용을 /root/helm/rel/out/storage-note.txt 에 한두 줄로 적으세요 — 릴리스 상태가 어느 네임스페이스의 어떤 오브젝트에 저장되는지가 들어가야 합니다.
/root/helm/rel/out/report.json 을 만드세요. 키는 네 개입니다. revisions 는 리비전마다 revision 과 status 를 담은 배열로 실제 이력 개수와 같아야 하고 status 가 failed 인 항목이 반드시 들어 있어야 합니다. current_revision 은 현재 최신 리비전 번호, rolled_back_to 는 2, deployed_replicas 는 현재 Deployment 의 spec.replicas 값입니다.

참고

실습 파드는 실습마다 새로 뜨므로 다른 실습에서 만든 차트나 릴리스는 남아 있지 않습니다. 차트도 네임스페이스도 여기서 처음부터 만듭니다 — 차트가 곧 재현 가능한 패키지라는 사실이 여기서 드러납니다.
helm history, helm get values, helm status 는 모두 -n 으로 네임스페이스를 줘야 합니다. Helm 은 릴리스를 네임스페이스 단위로 기억합니다.
-a(--all)를 붙이면 차트 기본값까지 병합된 최종 값이, 붙이지 않으면 사용자가 실제로 넘긴 값만 나옵니다. 장애 대응에서 "이건 기본값인가 사람이 넣은 값인가"를 가르는 것이 이 차이입니다.
기본 보관 리비전은 10개이며 --history-max 로 조절합니다. 시크릿이 무한히 쌓이지 않는 이유입니다.
흔한 실수 1: 4번에서 2>&1 없이 저장해 파일이 비는 것. 실패 메시지는 표준 오류로 나옵니다.
흔한 실수 2: 롤백하면 리비전 번호가 2로 돌아갈 거라 기대하는 것. 롤백은 리비전 2의 차트와 values 로 계산한 새 리비전을 만듭니다.

첫 설치로 리비전 1 만들기

/root/helm/rel/lab-app 에 차트를 하나 만들고(helm create lab-app 이면 충분합니다), 네임스페이스 helm-lab 에 릴리스 이름 lab-app 으로 설치하세요: helm install lab-app /root/helm/rel/lab-app -n helm-lab --create-namespace --set replicaCount=1. 이것이 리비전 1입니다. helm-lab 에 app.kubernetes.io/managed-by=Helm 라벨이 붙은 Deployment 가 하나 생겨야 합니다. 산출물 디렉터리 /root/helm/rel/out 도 미리 만드세요.

릴리스는 네임스페이스 단위로 기억됩니다. 없는 네임스페이스에 설치하려면 미리 만들거나 설치 옵션으로 함께 만들 수 있습니다. 복제 수는 1로 시작합니다.

업그레이드로 리비전 2 만들기

helm upgrade lab-app /root/helm/rel/lab-app -n helm-lab --set replicaCount=3 으로 리비전 2를 만드세요. 그다음 그 리비전에 적용된 사용자 값을 /root/helm/rel/out/rev2-values.json 에 저장하세요(helm get values lab-app -n helm-lab --revision 2 -o json). 파일은 올바른 JSON 이어야 하고 replicaCount 가 3이어야 합니다.

값 하나만 바꿔 다시 배포합니다. 그다음 그 리비전에 적용된 사용자 값을 JSON 으로 뽑아 저장하세요. 특정 리비전을 지목하는 옵션이 있습니다.

릴리스 이력을 JSON 으로 남기기

helm history lab-app -n helm-lab -o json > /root/helm/rel/out/history.json 으로 이력을 저장하세요. 리비전이 2개 이상이고, 각 항목에 chart·app_version·status 필드가 있어야 하며, 상태가 superseded 인 리비전이 최소 하나 있어야 합니다.

이력에는 리비전마다 상태와 차트 정보가 들어 있습니다. 새 리비전이 뜨면 이전 리비전의 상태가 무엇으로 바뀌는지 확인하세요.

실패하는 업그레이드 만들기

렌더링은 되지만 API 서버가 거부하는 업그레이드를 일부러 한 번 하세요: helm upgrade lab-app /root/helm/rel/lab-app -n helm-lab --set replicaCount=abc. replicas 는 정수여야 하므로 매니페스트가 거부됩니다. 표준 오류까지 포함해 출력을 /root/helm/rel/out/failed.txt 에 저장하세요(> /root/helm/rel/out/failed.txt 2>&1). 이것이 리비전 3이며 상태는 failed 로 남고, 실제 Deployment 의 spec.replicas 는 3 그대로여야 합니다. --atomic 은 붙이지 마세요 — 붙이면 자동 롤백되어 실패 리비전을 관찰할 수 없습니다.

렌더링은 되지만 API 서버가 거부하는 값을 넣으면 됩니다. 복제 수 자리에 정수가 아닌 값을 넣어 보세요. 오류는 표준 오류로 나오므로 저장할 때 함께 받아야 합니다.

리비전 2로 롤백하기

helm rollback lab-app 2 -n helm-lab 으로 리비전 2의 상태로 되돌리세요. 이것이 리비전 4입니다. 이력의 최신 리비전 번호가 4 이상이고, 그 리비전의 설명에 rollback 이 들어가며, 상태는 deployed, 실제 Deployment 의 spec.replicas 는 3이어야 합니다.

롤백은 번호를 되돌리는 것이 아니라 새 리비전을 만드는 일입니다. 롤백 뒤 이력의 최신 번호와 실제 배포된 복제 수를 함께 확인하세요.

사용자 값과 전체 값 비교하기

helm get values lab-app -n helm-lab -a -o json > /root/helm/rel/out/all-values.json 과 helm get values lab-app -n helm-lab -o json > /root/helm/rel/out/user-values.json 을 각각 저장하세요. 전체 값 파일에는 최상위 키가 3개 이상이고 image 가 포함되어야 하며, 사용자 값 파일의 키 개수는 그보다 적어야 합니다.

같은 명령에 옵션 하나를 더 붙이면 차트 기본값까지 병합된 결과가 나옵니다. 두 결과의 키 개수가 달라야 정상입니다.

릴리스가 저장된 자리 확인하기

kubectl get secret -n helm-lab -l owner=helm 으로 릴리스 시크릿을 확인하세요. 리비전 수만큼(4개 이상) 있고, 타입은 helm.sh/release.v1, 이름은 sh.helm.release.v1.lab-app.v<리비전> 형식이어야 합니다. 확인한 내용을 /root/helm/rel/out/storage-note.txt 에 한두 줄로 적으세요 — 릴리스 상태가 어느 네임스페이스의 어떤 오브젝트에 저장되는지가 들어가야 합니다.

Helm 3 에는 클러스터 안에 상주하는 서버가 없습니다. 그렇다면 상태는 어디에 있을까요. 라벨로 걸러 보면 리비전 수만큼 보입니다.

수명주기 보고서 만들기

/root/helm/rel/out/report.json 을 만드세요. 키는 네 개입니다. revisions 는 리비전마다 revision 과 status 를 담은 배열로 실제 이력 개수와 같아야 하고 status 가 failed 인 항목이 반드시 들어 있어야 합니다. current_revision 은 현재 최신 리비전 번호, rolled_back_to 는 2, deployed_replicas 는 현재 Deployment 의 spec.replicas 값입니다.

이력과 실제 배포 상태에서 숫자를 뽑아 JSON 으로 정리합니다. 실패한 리비전을 빼면 안 되고, 숫자는 손으로 적지 말고 명령 출력에서 읽어 넣으세요.