CRD — 새로운 API 리소스 정의

결론부터

CRD는 새로운 리소스의 API와 스키마를 정의하며, 그 리소스에 따라 작업하는 컨트롤러는 별도로 필요하다.

기본 리소스만으로 도메인의 선언을 표현하기 어려울 때 새 종류를 정의할 수 있다. CustomResourceDefinition(CRD)과 그 인스턴스인 Custom Resource(CR)를 만들면 API 서버에서 무엇이 달라지는지 살펴본다.

CRD — 새로운 리소스 만들기

“매일 새벽 3시에 백업” 같은 도메인 개념을 kubectl get backup으로 다루고 싶어도, 내장 kind에는 그런 종류가 없다. CRD(CustomResourceDefinition)는 API에 리소스 종류 자체를 등록하는 리소스다 — 등록하는 순간 kubectl·검증·etcd 저장까지 내장 리소스와 똑같이 동작한다.

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata: { name: backups.ops.example.com }   # 반드시 <복수형>.<그룹> 형식
spec:
  group: ops.example.com
  scope: Namespaced                      # Namespaced | Cluster
  names:
    { plural: backups, singular: backup, kind: Backup, shortNames: ["bk"] }
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              required: ["schedule"]
              properties:
                schedule: { type: string }
                retention: { type: integer, default: 7 }
      subresources: { status: {} }
      additionalPrinterColumns:          # kubectl get 의 출력 열을 정한다
        - { name: Schedule, type: string, jsonPath: .spec.schedule }

이 골격을 손으로 치지 않는다 — 시험 중에는 공식 CustomResourceDefinition 문서의 전체 예시를 복사해 이름·스키마만 깎아내는 게 정석이다.

CRD를 만들면 무슨 일이 생기나

kubectl apply -f backup-crd.yaml
kubectl wait --for=condition=Established \
  crd/backups.ops.example.com --timeout=60s
kubectl api-resources | grep backups
kubectl get --raw='/apis/ops.example.com/v1'
kubectl explain backup.spec              # ★ 스키마가 있으니 explain도 동작한다

apiVersion: ops.example.com/v1
kind: Backup
metadata:
  name: nightly
spec:
  schedule: "0 3 * * *"

CR까지 적용한 뒤 저장 여부와 조정 여부를 따로 판정한다.

kubectl apply -f backup.yaml
kubectl get backup nightly \
  -o jsonpath='{.metadata.uid}{"\t"}{.metadata.resourceVersion}{"\n"}'
kubectl get backup nightly \
  -o jsonpath='{.metadata.generation}{"\t"}{.status.conditions}{"\n"}'

CRD의 Established=True, discovery 응답, CR의 uid·resourceVersion은 각각 새 API 등록과 객체 저장을 증명한다. 여기까지 성공해도 백업 같은 실제 작업은 아직 증명되지 않는다. 그 결과는 컨트롤러가 기록한 status.conditions, 컨트롤러가 만든 하위 리소스, 컨트롤러 로그로 따로 확인해야 한다. CRD만 있는 예제에서 status가 비어 있는 것은 저장 실패가 아니라 조정할 컨트롤러가 없다는 경계다.

함정

CRD만 만들면 아무 일도 일어나지 않는다. 오브젝트는 etcd에 저장되지만, 그걸 보고 행동하는 컨트롤러가 없다. 그 컨트롤러가 곧 오퍼레이터다.

설치된 CRD 살펴보기

오퍼레이터를 설치하면 CRD가 한꺼번에 여러 개 생긴다. 어떤 종류가 생겼는지와 각 필드의 뜻은 문서를 찾기 전에 API 서버에 먼저 묻는다. CRD 스키마에 적힌 설명을 kubectl explain이 그대로 보여 준다.

kubectl get crd                                     # 전체 목록. 이름은 <복수형>.<그룹>
kubectl get crd | grep ops.example.com              # 그룹 이름으로 거른다
kubectl api-resources --api-group=ops.example.com   # 종류·단축 이름·네임스페이스 범위 여부
kubectl explain backup.spec                         # spec 아래 필드 목록
kubectl explain backup.spec.schedule                # 필드 하나의 문서
kubectl explain backup.spec --recursive             # 하위 필드를 트리로

• kubectl get crd는 종류의 정의를, kubectl get backup은 그 종류로 만든 오브젝트를 보여 준다.
• kubectl explain은 필드의 문서를, kubectl get backup nightly -o jsonpath='{.spec.schedule}'은 오브젝트에 든 값을 보여 준다.
• 결과를 남기라는 조건이면 명령 끝에 > 파일을 붙인다.

목록과 필드 문서를 파일로 저장하는 연습은 실전 과제에 있다.

CRD 다룰 때 주의점

함정 1

CRD를 지우면 그 종류의 CR이 전부 삭제된다. 데이터베이스 오퍼레이터라면 실제 데이터가 날아갈 수 있다.

함정 2

CR에 finalizer(삭제 전 정리 작업을 보장하는 표식)가 걸려 있고 오퍼레이터가 죽어 있으면 삭제가 영원히 끝나지 않는다. 오브젝트가 Terminating에 머문다.

kubectl patch backup nightly -p '{"metadata":{"finalizers":null}}' --type=merge

함정 3

CRD의 버전을 올릴 때 conversion webhook(옛 버전으로 저장된 오브젝트를 새 버전 모양으로 변환해 주는 외부 서비스)이 없으면 저장된 옛 버전 오브젝트를 읽지 못할 수 있다. 오퍼레이터 업그레이드 후 CR이 안 읽히면 이걸 의심한다 — 직접 만들 일은 없으니 이런 게 있다는 것만 알아 두면 된다.

요약

• CRD는 새로운 리소스의 API와 스키마를 정의하며, 그 리소스에 따라 작업하는 컨트롤러는 별도로 필요하다.
• CRD는 종류의 정의이고 CR은 그 종류로 생성한 실제 오브젝트다.
• CRD 삭제는 CR 삭제로 이어지므로 범위를 확인한다. 선언 실행은 Operator의 역할이다.