게이트를 어디에 둘 것인가

한 줄 요약

배포 파이프라인의 게이트는 소스가 아니라 렌더 결과에 걸어야 합니다. 클러스터에 들어가는 것은 파일이 아니라 렌더된 매니페스트이고, 게이트가 보지 않은 것은 막을 수 없기 때문입니다.

왜 렌더 결과인가

kustomize 오버레이 세 개짜리 저장소에서 흔히 이런 게이트를 봅니다.

grep -r "image:.*:latest" .   # latest 태그 금지

이 검사는 base 를 보고 통과합니다. 그런데 실제로 배포되는 것은 오버레이가 이미지를 덮은 결과이고, 그 결과에는 latest 가 들어 있을 수 있습니다. 반대도 성립합니다. base 에 latest 가 있어도 오버레이가 다이제스트로 덮으면 배포되는 것은 안전한데, 게이트는 빨간불을 켭니다.

두 경우 모두 게이트가 자기가 막으려는 대상을 보고 있지 않아서 생깁니다. 그래서 순서는 하나뿐입니다.

kustomize build overlays/prod   →   렌더 결과
        ↓
스키마 검증 · 정책 검사          →   이 결과를 검사한다
        ↓
0 이 아닌 종료 코드면 배포 중단

흐름 강조 재생 · 다시 보려면 해제 후 선택

1. 1렌더 결과를 만든다오버레이를 적용해 kustomize build 한 결과를 먼저 만든다. 클러스터에 들어가는 것은 소스 파일이 아니라 이 렌더 결과이므로 검사 대상도 이것이다.
2. 2검사 결과를 종료 코드로 옮긴다스키마 검증과 정책 검사를 렌더 결과에 돌리고, 위반이면 0 이 아닌 종료 코드로 배포를 중단한다. 본문은 결과를 화면에만 뿌리고 파이프라인은 초록불인 경우를 흔한 실패로 든다.
3. 3막아야 할 것을 실제로 넣어 본다latest 태그 같은 위반을 일부러 넣었을 때 빨간불이 켜지는지 확인한다. 통과하는 것만 확인한 게이트는 몇 달 동안 아무것도 지키지 않은 채 초록불을 낼 수 있다.

여기서 구분할 것 종료 코드로 막는 요령과 위반 시험은 본문의 서술을 따랐고, 연결한 문서는 본문이 쓰는 Kyverno 명령줄 도구의 개요일 뿐 그 규칙을 보증하지 않는다. 태그가 아니라 다이제스트로 고정해야 게이트를 통과한 그것과 클러스터에 들어간 그것이 같다고 말할 수 있다는 것이 본문의 짝이 되는 주장이다.

잠깐, 예측해 보세요 새로 만든 정책 게이트에 정상 매니페스트만 넣어 보니 초록불이 나왔다. 이것만으로 게이트가 동작한다고 말해도 될까?

설명 확인 · 채점 없는 자가 점검

부족하다. 본문은 막아야 할 것을 실제로 넣어 보고 빨간불이 켜지는지까지 확인하라고 한다. 통과하는 사례만 본 게이트는 아무것도 지키지 않으면서도 초록불을 낼 수 있다.

근거 문서

어떻게 동작하나

게이트는 종료 코드로 말해야 합니다

정책 도구를 돌려 놓고 결과를 화면에만 뿌리고 끝내는 파이프라인이 정말 많습니다. 로그에는 빨간 글씨가 있고 파이프라인은 초록불입니다. 게이트의 본체는 검사가 아니라 검사 결과를 종료 코드로 옮기는 것입니다.

if ! kyverno apply policy/require-pinned.yaml --resource "$RENDER"; then
  echo "정책 위반으로 배포를 막습니다"; exit 3
fi

그리고 게이트를 만들었으면 막아야 할 것을 실제로 넣어 보고 빨간불이 켜지는지 확인해야 합니다. 통과하는 것만 확인한 게이트는 몇 달 동안 아무것도 지키지 않은 채로 초록불을 냅니다.

태그가 아니라 다이제스트

checkout:1.4.0 은 이름이고 checkout@sha256:... 은 내용입니다. 태그는 다시 밀 수 있어서, 어제 검증한 것과 오늘 배포되는 것이 다를 수 있습니다. 다이제스트로 고정하면 "게이트를 통과한 그것" 과 "클러스터에 들어간 그것" 이 같다는 것을 말할 수 있습니다. 감사 추적이 성립하는 최소 조건입니다.

진행형 배포는 멈춤이 본체입니다

카나리를 setWeight: 10 → setWeight: 100 으로 적어 두면 그건 카나리가 아니라 조금 느린 전면 배포입니다. 가중치 사이에 pause 가 있어야 사람이나 분석이 판단할 자리가 생깁니다. 그리고 카나리만 따로 볼 수 있어야 판단할 근거가 생기므로, canaryService 와 stableService 를 나눠 둡니다.

블루/그린은 새 버전을 미리보기 통로로 확인한 뒤 트래픽을 전환하는 선택지입니다. autoPromotionEnabled: false 는 자동 승격을 막습니다. 하지만 미리보기 버전도 시작 작업이나 백그라운드 작업으로 데이터를 쓸 수 있습니다. 원장처럼 단일 writer가 필요한 서비스는 쓰기 제어·스키마 호환·복구 절차를 별도로 검증해야 합니다. 블루/그린이 동시 쓰기를 막는다는 뜻은 아닙니다.

현장에서 만나는 모습

한 조직에서 카나리 분석이 계속 통과했는데 장애가 났습니다. 원인은 분석 템플릿 이름을 오타 낸 것이었습니다. Rollout 은 없는 템플릿을 참조하고 있었고, 그 사실은 승격 직전에야 드러났습니다. 그래서 "참조한 템플릿이 실제로 있는가" 는 배포 전에 확인할 항목입니다.

또 하나 자주 보는 것은 Argo CD Application 의 목적지 네임스페이스와 매니페스트가 렌더되는 네임스페이스가 어긋나 있는 경우입니다. 동기화는 성공하고 초록불이 뜨는데 아무 데도 반영되지 않습니다.

초록불이 거짓말하는 자리

앞에서 본 두 사례(없는 분석 템플릿, 어긋난 목적지 네임스페이스)에는 공통점이 있다. 동기화는 성공했는데 아무 일도 일어나지 않았다는 것이다. GitOps 에서 초록불이 뜻하는 것은 "git 과 클러스터가 같다" 이지 "서비스가 정상이다" 가 아니다. 이 둘을 헷갈리면 화면만 보고 안심하게 된다.

초록불이 거짓말하는 자리는 몇 군데로 정해져 있다.

아무것도 안 만들어졌는데 같다고 한다. 매니페스트가 렌더된 결과가 비어 있으면 "관리할 것이 없으니 차이도 없다" 가 되어 동기화가 성공한다. 오버레이 경로를 잘못 적었거나 선택자가 아무것도 안 고르는 경우다. 관리 대상 개수를 함께 보는 것이 이것을 잡는 가장 값싼 방법이다.

적용됐지만 컨트롤러가 거부했다. 오브젝트는 만들어졌으므로 git 과 클러스터는 같지만, 그 오브젝트를 읽는 컨트롤러가 값을 거부하고 상태에만 오류를 적어 둔다. Rollout·Certificate·ExternalSecret 처럼 다른 컨트롤러가 처리하는 것이 여기 해당한다. 그래서 건강 판정을 오브젝트 존재가 아니라 상태 필드로 하는 설정이 필요하다.

무시 규칙이 진짜 차이까지 덮는다. 자동 확장이 복제 수를 바꾸는 것을 차이로 보지 않으려고 무시 규칙을 넣는데, 그 범위가 넓으면 사람이 손으로 바꾼 것까지 함께 덮인다. 그때부터 그 필드는 GitOps 밖에 있다.

그래서 초록불 옆에 다른 신호를 하나 더 둔다. 마지막으로 동기화한 커밋이 무엇인지, 그리고 지금 도는 이미지의 태그가 무엇인지다. 둘이 기대와 다르면 초록불과 무관하게 무언가 잘못된 것이고, 이 대조는 몇 초면 끝난다.

흐름 강조 재생 · 다시 보려면 해제 후 선택

1. 1렌더 결과가 비어 있다오버레이 경로를 잘못 적었거나 선택자가 아무것도 고르지 않으면 관리할 것이 없으니 차이도 없다고 계산되어 동기화가 성공한다. 관리 대상 개수를 함께 보면 값싸게 잡힌다.
2. 2오브젝트는 있는데 컨트롤러가 거부한다Rollout, Certificate, ExternalSecret 처럼 다른 컨트롤러가 처리하는 오브젝트는 만들어졌어도 값을 거부하고 상태에만 오류를 적을 수 있다. 건강 판정을 오브젝트 존재가 아니라 상태 필드로 한다.
3. 3무시 규칙이 진짜 차이까지 덮는다자동 확장이 바꾸는 복제 수를 차이로 보지 않으려고 넣은 규칙의 범위가 넓으면 사람이 손으로 바꾼 것까지 덮인다. 그때부터 그 필드는 GitOps 밖에 있다.

여기서 구분할 것 초록불 옆에 신호를 하나 더 둔다. 마지막으로 동기화한 커밋과 지금 도는 이미지의 태그를 기대값과 대조하면 몇 초면 끝난다. 이 세 자리와 보조 신호는 본문의 서술이 근거이고 연결한 문서는 차이 계산과 무시 규칙의 개념 설명이다.

잠깐, 예측해 보세요 자동 확장이 복제 수를 바꾸는 Deployment 에 replicas 가 속한 spec 전체를 무시하는 넓은 규칙을 넣어 두었다. 누군가 손으로 replicas 를 0 으로 바꾸면 Argo CD 화면에는 어떻게 보일 수 있을까?

설명 확인 · 채점 없는 자가 점검

차이로 드러나지 않고 Synced 로 남을 수 있다. 본문은 무시 범위가 넓으면 사람의 수동 변경까지 덮인다고 말한다. 무시 규칙은 자동 확장이 실제로 바꾸는 필드로 좁혀야 그 필드의 수동 변경을 놓치지 않는다.

근거 문서

다음 실습에서 할 것

base 와 운영 오버레이를 만들고, 렌더 결과에 정책 게이트를 걸고, 그 게이트가 위반을 실제로 막는지 확인한 뒤, 카나리와 블루/그린을 각각 어떤 서비스에 붙일지 정합니다.