Delivering Golden-Path Conformance as a Diagnostic

목표

골든 패스 규칙을 값으로 정의하고, 그것을 실제로 판정하는 진단기를 만들어, 준수율을 세고 커밋 앞에 붙이는 데까지 한 번에 해 봅니다.

왜 중요한가

규칙을 어드미션에서만 막으면 개발자는 30분 뒤에야 1분이면 고칠 문제를 알게 되고, 전부 앞에서 막으면 사람들이 플랫폼을 우회합니다. 그래서 실무의 가드레일은 두 갈래로 배치됩니다. 어겼을 때 다른 사람에게 피해가 가는 규칙은 막고, 그 서비스 자신의 문제인 규칙은 알려 주기만 합니다. 그러려면 규칙에 식별자와 심각도와 고치는 법이 붙어 있어야 합니다. 그리고 진단기는 반드시 반대 방향으로도 시험해야 합니다. 아무것도 잡아내지 못하는 진단기는 준수율을 100% 로 보이게 만들어 없는 것보다 나쁩니다.

단계

1. /root/cnpa-devex/rules.json 에 규칙 다섯 개를 배열로 적으세요. 각 원소는 id, title, severity, fix 를 가집니다. PR001(이미지 태그 고정)과 PR002(리소스 요청 선언)는 severity 가 block, PR003(표준 라벨 app.kubernetes.io/name 과 app.kubernetes.io/part-of), PR004(readinessProbe), PR005(replicas 2 이상)는 warn 입니다. fix 는 8자 이상으로 씁니다.
2. /root/cnpa-devex/check-paved-road.sh 를 만들고 실행 권한을 주세요. 인자로 받은 매니페스트를 읽어 어긴 규칙 id 를 한 줄에 하나씩 출력합니다. 이 단계에서는 PR001 과 PR002 만 판정해도 됩니다. PR001 은 첫 컨테이너의 이미지에 태그가 없거나 태그가 latest 일 때, PR002 는 첫 컨테이너에 resources.requests.cpu 또는 resources.requests.memory 가 없을 때입니다.
3. 나머지 세 규칙을 채우세요. PR003 은 metadata.labels 에 app.kubernetes.io/name 또는 app.kubernetes.io/part-of 가 없을 때, PR004 는 첫 컨테이너에 readinessProbe 가 없을 때, PR005 는 spec.replicas 가 없거나 2 보다 작을 때입니다. 위반이 하나도 없으면 종료 코드 0, 하나라도 있으면 1 로 끝나야 합니다.
4. /root/cnpa-devex/services/checkout.yaml 에 다섯 규칙을 모두 지키는 Deployment checkout 을 작성하세요. 파일에는 Deployment 하나만 담습니다.
5. /root/cnpa-devex/services/reports.yaml 에 Deployment reports 를 작성하세요. PR001 과 PR005 만 어겨야 합니다. /root/cnpa-devex/services/billing.yaml 에는 Deployment billing 을 작성하되 PR004 만 어기게 하세요.
6. 진단기에 --json 모드를 추가하세요. check-paved-road.sh --json <파일> 은 {"file": "<받은 경로>", "violations": ["PR001", ...], "pass": true 또는 false} 형태의 JSON 한 덩어리를 출력합니다. pass 는 따옴표 없는 불리언이고, 위반이 없으면 violations 는 빈 배열입니다.
7. /root/cnpa-devex/services/ 의 매니페스트 전부에 진단기를 돌려 /root/cnpa-devex/adoption.json 을 만드세요. 키는 total(검사한 파일 수), passing(위반이 없는 파일 수), rate_pct(준수율, 소수 첫째 자리), by_rule(다섯 규칙 각각의 위반 파일 수, 0 인 규칙도 키를 둡니다)입니다.
8. /root/cnpa-devex/repo 에 git 저장소를 만들고 services/ 디렉터리를 두세요. .git/hooks/pre-commit 을 만들고 실행 권한을 주어, 스테이지에 올라온 services/*.yaml 을 진단기로 검사하게 하세요. block 규칙을 어긴 파일이 있으면 규칙 id 를 출력하고 0 이 아닌 코드로 끝나 커밋을 막고, warn 규칙만 어겼으면 안내만 출력하고 커밋을 통과시킵니다. 막힌 커밋을 한 번 시도해 그 출력을 /root/cnpa-devex/blocked-commit.txt 에 저장하세요.

참고

• yq 로 없는 값을 읽으면 문자열 null 이 나옵니다. 그것을 판정 조건으로 쓰면 됩니다.
• 점이 들어간 라벨 키는 .metadata.labels."app.kubernetes.io/name" 처럼 따옴표로 감쌉니다.
• 채점기는 자기가 만든 표본 매니페스트를 진단기에 물려 판정을 대조합니다. 규칙 id 는 지정된 이름 그대로 출력해야 합니다.
• 8단계의 훅은 학생 저장소가 아니라 그 사본에서 시험합니다. 저장소를 깨끗한 상태로 두지 않아도 됩니다.

규칙을 값으로 정의

/root/cnpa-devex/rules.json 에 규칙 다섯 개를 배열로 적으세요. 각 원소는 id, title, severity, fix 를 가집니다. PR001(이미지 태그 고정)과 PR002(리소스 요청 선언)는 severity 가 block, PR003(표준 라벨 app.kubernetes.io/name 과 app.kubernetes.io/part-of), PR004(readinessProbe), PR005(replicas 2 이상)는 warn 입니다. fix 는 8자 이상으로 씁니다.

규칙마다 식별자·제목·심각도·고치는 법이 필요합니다. 심각도는 '어겼을 때 다른 사람에게 피해가 가는가' 로 가릅니다.

진단기의 뼈대와 두 규칙

/root/cnpa-devex/check-paved-road.sh 를 만들고 실행 권한을 주세요. 인자로 받은 매니페스트를 읽어 어긴 규칙 id 를 한 줄에 하나씩 출력합니다. 이 단계에서는 PR001 과 PR002 만 판정해도 됩니다. PR001 은 첫 컨테이너의 이미지에 태그가 없거나 태그가 latest 일 때, PR002 는 첫 컨테이너에 resources.requests.cpu 또는 resources.requests.memory 가 없을 때입니다.

매니페스트 값은 yq 로 읽습니다. 없는 값은 문자열 null 로 나오므로 그것을 판정 조건으로 쓰면 됩니다. 실행 권한을 잊지 마세요.

다섯 규칙을 모두 판정

나머지 세 규칙을 채우세요. PR003 은 metadata.labels 에 app.kubernetes.io/name 또는 app.kubernetes.io/part-of 가 없을 때, PR004 는 첫 컨테이너에 readinessProbe 가 없을 때, PR005 는 spec.replicas 가 없거나 2 보다 작을 때입니다. 위반이 하나도 없으면 종료 코드 0, 하나라도 있으면 1 로 끝나야 합니다.

라벨은 점이 들어간 키라서 yq 에서 따옴표로 감싸야 합니다. 레플리카는 값이 없을 때와 1일 때를 모두 잡아야 합니다.

준수하는 표본

/root/cnpa-devex/services/checkout.yaml 에 다섯 규칙을 모두 지키는 Deployment checkout 을 작성하세요. 파일에는 Deployment 하나만 담습니다.

다섯 규칙을 모두 지키는 Deployment 하나를 만듭니다. 진단기가 아무것도 출력하지 않고 0 으로 끝나야 합니다.

일부러 어긴 표본

/root/cnpa-devex/services/reports.yaml 에 Deployment reports 를 작성하세요. PR001 과 PR005 만 어겨야 합니다. /root/cnpa-devex/services/billing.yaml 에는 Deployment billing 을 작성하되 PR004 만 어기게 하세요.

정확히 지정된 규칙만 어겨야 합니다. 다른 규칙까지 어기면 진단기가 옳아도 채점은 떨어집니다.

기계가 읽을 출력

진단기에 --json 모드를 추가하세요. check-paved-road.sh --json <파일> 은 {"file": "<받은 경로>", "violations": ["PR001", ...], "pass": true 또는 false} 형태의 JSON 한 덩어리를 출력합니다. pass 는 따옴표 없는 불리언이고, 위반이 없으면 violations 는 빈 배열입니다.

같은 판정을 JSON 한 덩어리로도 내보냅니다. pass 는 따옴표 없는 불리언이어야 하고, 위반이 없을 때 violations 는 빈 배열이어야 합니다.

준수율 계산

/root/cnpa-devex/services/ 의 매니페스트 전부에 진단기를 돌려 /root/cnpa-devex/adoption.json 을 만드세요. 키는 total(검사한 파일 수), passing(위반이 없는 파일 수), rate_pct(준수율, 소수 첫째 자리), by_rule(다섯 규칙 각각의 위반 파일 수, 0 인 규칙도 키를 둡니다)입니다.

서비스 디렉터리를 훑어 진단기를 돌리고 그 결과를 세면 됩니다. 숫자를 직접 적지 말고 계산한 값을 담으세요.

커밋 앞에 붙이기

/root/cnpa-devex/repo 에 git 저장소를 만들고 services/ 디렉터리를 두세요. .git/hooks/pre-commit 을 만들고 실행 권한을 주어, 스테이지에 올라온 services/*.yaml 을 진단기로 검사하게 하세요. block 규칙을 어긴 파일이 있으면 규칙 id 를 출력하고 0 이 아닌 코드로 끝나 커밋을 막고, warn 규칙만 어겼으면 안내만 출력하고 커밋을 통과시킵니다. 막힌 커밋을 한 번 시도해 그 출력을 /root/cnpa-devex/blocked-commit.txt 에 저장하세요.

훅은 실행 권한이 있어야 돕니다. 스테이지에 올라온 파일 목록은 git 이 알려 주고, 훅은 block 규칙일 때만 0 이 아닌 값으로 끝나야 합니다.