손으로 고친 필드가 업그레이드에서 사라졌다

목표

클러스터에서 손으로 고친 값과 라벨이 helm upgrade 뒤에 어떻게 되는지 직접 만들어 확인하고, 이전 사용자 값을 이어받는 세 가지 옵션의 차이를 릴리스 기록으로 비교한다.

왜 중요한가

헬름 3 은 업그레이드할 때 옛 매니페스트·새 매니페스트·클러스터 실물 셋을 놓고 패치를 만든다. 이 규칙 하나로 현장에서 반복되는 두 가지 현상이 설명된다 — 장애 중에 kubectl scale 로 올려 둔 복제 수는 다음 배포에서 되돌아가고, 급히 붙여 둔 라벨은 그대로 남는다. 차트가 선언한 필드는 선언이 이기고, 차트가 모르는 필드는 건드리지 않기 때문이다. 여기에 값 쪽 규칙이 하나 더 있다. helm upgrade 는 기본적으로 이전 릴리스의 사용자 값을 이어받지 않는다. 그래서 배포 스크립트가 --set 을 하나 빠뜨리면 그 값은 조용히 차트 기본값으로 돌아간다. --reuse-values 는 이 문제를 풀지만 값이 릴리스 안에만 남아 저장소에서 보이지 않게 만든다. 어느 쪽을 쓸지는 취향이 아니라 '배포를 재현할 수 있는가' 로 정해야 하고, 그러려면 세 옵션이 실제로 무엇을 하는지 한 번 봐야 한다.

단계

1. /root/hc-upgrade/ledger 차트(이름 ledger, 버전 0.1.0)를 만드세요. values.yaml 은 replicas: 1, image: "registry.local/ledger:1.0.0", extraLabel: "" 세 값입니다. templates/deployment.yaml 은 이름이 <릴리스이름>-ledger 인 Deployment 이고, metadata.labels 에 app: ledger 를 두되 extraLabel 이 비어 있지 않을 때만 tier: <그 값> 을 더합니다. 릴리스 이름 books 로 설치한 뒤 helm get manifest books 를 /root/hc-upgrade/out/rev1-manifest.yaml 에 저장하세요.
2. kubectl 로 books-ledger Deployment 의 복제 수를 5 로 올리고 라벨 owner=ops 를 붙이세요. 그 상태를 /root/hc-upgrade/out/before-upgrade.json 에 {"replicas": …, "owner": …, "tier": …} 세 키의 JSON 으로 저장합니다(없는 라벨은 null).
3. 차트도 값도 전혀 바꾸지 않은 채 helm upgrade books /root/hc-upgrade/ledger 를 돌리세요. 그다음 같은 세 키의 JSON 을 /root/hc-upgrade/out/after-upgrade.json 에 저장하고, 손으로 고친 두 가지 중 무엇이 살아남고 무엇이 되돌아갔는지 확인하세요.
4. --set extraLabel=gold 로 업그레이드해 tier 라벨이 붙은 상태를 /root/hc-upgrade/out/label-added.json 에 저장하세요. 이어서 extraLabel 을 빈 문자열로 주어 다시 업그레이드해 tier 라벨이 사라진 상태를 /root/hc-upgrade/out/label-removed.json 에 저장합니다. 두 파일 모두 같은 세 키의 JSON 입니다. 이때 owner 라벨은 어떻게 되는지도 함께 보세요.
5. --set replicas=4 --set extraLabel=silver 로 업그레이드하고 helm get values books -o json 을 /root/hc-upgrade/out/values-1.json 에 저장하세요. 이어서 --set replicas=6 하나만 주고 다시 업그레이드한 뒤 같은 명령의 결과를 /root/hc-upgrade/out/values-2.json 에 저장하세요. extraLabel 이 어떻게 되는지가 답입니다.
6. 이전 릴리스의 사용자 값을 이어받으면서 --set extraLabel=bronze 만 더해 업그레이드하세요. helm get values books -o json 결과를 /root/hc-upgrade/out/values-reuse.json 에 저장합니다. replicas 는 앞 단계의 6 이 남고 extraLabel 은 bronze 여야 합니다.
7. 먼저 --set replicas=4 --set extraLabel=silver 로 업그레이드해 기준을 만드세요. 거기서 --set replicas=7 에 차트 기본값으로 되돌린 뒤 지난번 사용자 값을 다시 얹는 옵션을 붙여 업그레이드하고 결과를 /root/hc-upgrade/out/values-rtr.json 에 저장하세요. 이어서 --set replicas=9 에 지난번 값을 버리는 옵션을 붙여 업그레이드하고 결과를 /root/hc-upgrade/out/values-reset.json 에 저장하세요.
8. --set replicas=3 으로 서버 측 미리 보기를 돌려 출력을 /root/hc-upgrade/out/dryrun.yaml 에 저장하세요(릴리스는 바뀌지 않아야 합니다). 그다음 같은 값으로 --force 를 붙여 실제 업그레이드하고 그 뒤의 상태를 2단계와 같은 세 키의 JSON 으로 /root/hc-upgrade/out/after-force.json 에 저장하세요 — 손으로 붙인 owner 라벨이 어떻게 되는지 확인하세요. helm history books -o json 을 /root/hc-upgrade/out/history.json 에 저장하고, /root/hc-upgrade/out/merge-report.json 에 manual_scale_kept·manual_label_kept·chart_removed_label_deleted·default_upgrade_reuses_values·manual_label_survives_force 다섯 불리언과 final_replicas 숫자를 적으세요. 값은 앞 단계에서 저장한 파일들에서 읽습니다.

참고

• helm get values <릴리스> -o json 은 사용자가 준 값만, --all 은 차트 기본값까지 보여 준다
• kubectl get deploy <이름> -o json | jq '{...}' 로 필요한 필드만 뽑아 비교한다
• helm upgrade --dry-run=server 는 API 서버까지 보내 검증만 하고 릴리스를 만들지 않는다
• 흔한 실수: 장애 중 kubectl scale 로 올린 값을 다음 배포가 되돌린다
• 흔한 실수: 배포 스크립트에서 --set 하나를 빠뜨려 그 값만 기본값으로 돌아간다
• 공식 문서: https://helm.sh/docs/helm/helm_upgrade/ · https://helm.sh/docs/faq/changes_since_helm2/

단계 8개

1. 되돌려 볼 것을 먼저 배포한다
2. 클러스터에서 손으로 고친다
3. 차트를 하나도 안 바꾸고 업그레이드한다
4. 차트에서 뺀 필드는 클러스터에서도 지워진다
5. 업그레이드는 지난번 사용자 값을 버린다
6. 지난번 값을 이어받아 한 값만 바꾼다
7. 세 가지 이어받기 옵션을 나란히 놓는다
8. 미리 보고, 교체로 적용하고, 규칙을 정리한다