거절당해 봐야 계약을 안다

한 줄 요약

CRD 의 값어치는 API 서버의 검증·기본값·RBAC·감사를 빌려 오는 데 있습니다. 무엇이든 받아 주는 클러스터에서는 그중 무엇도 확인할 수 없습니다.

왜 거절당해 봐야 하나

앞 모듈에서 CRD 로 플랫폼 API 를 만들었습니다. 그런데 그 실습이 도는 곳에는 API 서버의 능력이 없어서, 무엇을 넣어도 받아 주었습니다.

CRD 는 "API 서버가 이미 가진 능력을 내 타입에 빌려 준다" 는 물건입니다. 그 능력이란 이것입니다.

검증      스키마에 안 맞으면 거절한다기본값    빠진 값을 저장 시점에 채운다RBAC      다른 자원과 똑같이 권한을 건다감사      누가 언제 무엇을 바꿨는지 남는다watch     컨트롤러가 변화를 구독한다문서      kubectl explain 이 스키마를 읽어 준다

직접 API 를 만들면 이 여섯을 전부 다시 만들어야 합니다. 그런데 받아 주기만 하는 클러스터에서는 그중 무엇도 확인할 수 없었습니다.

조용히 지워지는 필드

구조적 스키마는 기본이 잘라내기입니다. properties 에 없는 필드는 저절로 지워집니다 — 막는 설정을 켠 것이 아닙니다. replicas 를 replica 로 잘못 쓰면 그 값이 사라지고 아무도 알려 주지 않습니다.

additionalProperties: false 를 쓰려다 물리는 자리이기도 합니다. properties 와 함께 쓸 수 없습니다(Forbidden: mutual exclusive). 쓸 필요가 없어서 막아 둔 것입니다.

반대로 x-kubernetes-preserve-unknown-fields: true 를 넣으면 잘라내기도 검증도 통째로 꺼집니다. 편하다고 넣는 순간 모든 담장이 사라집니다.

기본값은 누가 채우느냐가 다르다

스키마의 default    저장 시점에 채워져 kubectl get -o yaml 에 바로 보인다컨트롤러가 채움     한참 뒤에 나타난다. 그 사이에는 비어 있다

개발자가 확인했을 때 값이 있어야 무슨 일이 일어날지 압니다. 골든 패스는 여기서 만들어집니다.

실무에서 진짜 중요한 것

오타는 오류가 아니라 침묵으로 돌아옵니다. 구조적 스키마는 기본이 잘라내기라, replicas 를 replica 로 쓰면 값이 조용히 사라집니다. 플랫폼 API 를 낼 때는 kubectl get -o yaml 로 저장된 결과를 되읽어 보라고 안내문에 적어 두는 편이 낫습니다.

x-kubernetes-preserve-unknown-fields: true 는 마지막 수단입니다. 편하다고 넣는 순간 잘라내기도 검증도 통째로 꺼져서, 그 타입에 세워 둔 담장이 전부 사라집니다.

기본값은 컨트롤러가 아니라 스키마에 둡니다. 스키마의 default 는 저장 시점에 채워져 개발자가 바로 확인할 수 있지만, 컨트롤러가 채우면 그 사이에는 비어 있습니다. 골든 패스는 이 차이에서 만들어집니다.

다음 실습에서 이것들을 진짜 API 서버 위에서 직접 거절당해 가며 확인합니다.