Kubernetes CRD란? Custom Resource Definition 구조와 동작 원리

Kubernetes CRD란? Custom Resource Definition 구조와 동작 원리 상세 정리

Kubernetes를 운영하다 보면 Deployment, Service, Pod, ConfigMap과 같은 기본 리소스 외에도 Gateway, HTTPRoute, Certificate, VerticalPodAutoscaler 등 다양한 리소스를 접하게 됩니다.

이 중 일부 리소스는 Kubernetes에 처음부터 내장되어 있는 것이 아니라, 별도의 API 또는 CRD(Custom Resource Definition)를 통해 Kubernetes API를 확장하여 제공됩니다.

CRD를 이해하면 Kubernetes에서 Controller와 Operator가 어떻게 동작하는지, 그리고 Rancher, Prometheus Operator, cert-manager 등 여러 Kubernetes 솔루션을 설치했을 때 왜 수많은 새로운 리소스가 생성되는지 이해하기 쉬워집니다.

핵심 개념:
CRD는 Kubernetes에 새로운 종류의 리소스를 정의하여 Kubernetes API를 확장하는 방법입니다.

1. Kubernetes 기본 리소스부터 이해하기

Kubernetes에는 기본적으로 다양한 API Resource가 존재합니다.

Pod
Deployment
StatefulSet
DaemonSet
Service
ConfigMap
Secret
Namespace
PersistentVolume
PersistentVolumeClaim
Job
CronJob
Node

예를 들어 Deployment를 생성할 때 다음과 같은 YAML을 작성합니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3

여기서 Kubernetes API Server는 kind: Deployment가 무엇인지 이미 알고 있습니다. Deployment가 Kubernetes API에 기본적으로 등록되어 있기 때문입니다.

2. Kubernetes에 없는 새로운 리소스가 필요하다면?

예를 들어 Kubernetes에서 다음과 같은 리소스를 직접 관리하고 싶다고 가정해 보겠습니다.

Database
Backup
Certificate
RedisCluster
Application
MonitoringRule

기본 Kubernetes에는 이러한 사용자 정의 리소스가 모두 존재하지 않습니다.

따라서 다음과 같이 작성한다고 해서 바로 사용할 수 있는 것은 아닙니다.

apiVersion: example.com/v1
kind: Database

metadata:
  name: production-db

spec:
  engine: postgresql
  version: "16"

API Server 입장에서는 Database라는 Resource Type이 등록되어 있지 않기 때문입니다.

이때 사용하는 것이 CRD(Custom Resource Definition)입니다.

3. CRD란?

CRD는 Custom Resource Definition의 약자로, Kubernetes API에 새로운 Resource Type을 추가하기 위한 기능입니다.

쉽게 표현하면 다음과 같습니다.

기본 Kubernetes

Pod
Deployment
Service
ConfigMap
Secret


CRD 설치 후

Pod
Deployment
Service
ConfigMap
Secret
Database
RedisCluster
Certificate
MyApplication
...

즉 Kubernetes 자체 소스 코드를 수정하지 않고도 새로운 Kubernetes API Resource를 추가할 수 있습니다.

4. CRD와 CR은 서로 다르다

CRD를 이해할 때 가장 많이 혼동하는 것이 CRD와 CR(Custom Resource)의 차이입니다.

구분	정식 명칭	역할
CRD	Custom Resource Definition	새로운 Resource의 구조와 종류를 정의
CR	Custom Resource	CRD를 기반으로 실제 생성된 Resource

쉽게 비교하면 다음과 같습니다.

CRD = 설계도 / 타입 정의

CR = 설계도를 이용해 생성한 실제 객체

예를 들어 다음과 같은 관계가 됩니다.

CRD
Database라는 Resource를 정의
        │
        ▼
Custom Resource
        │
        ├─ production-db
        ├─ development-db
        └─ test-db

5. CRD 동작 구조

전체 구조를 단순화하면 다음과 같습니다.

사용자
  │
  │ kubectl apply
  ▼
Kubernetes API Server
  │
  │
  ├───────────────┐
  │               │
  ▼               ▼
CRD 등록         CR 생성
                  │
                  ▼
                etcd
                  │
                  ▼
              Controller
                  │
                  ▼
            실제 작업 수행

CRD가 설치되면 Kubernetes API Server는 새로운 Resource Type을 인식할 수 있습니다.

이후 사용자는 일반 Kubernetes Resource처럼 kubectl을 이용하여 Custom Resource를 생성하고 조회하고 수정할 수 있습니다.

6. CRD YAML 구조

간단한 Database CRD를 예로 들어보겠습니다.

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition

metadata:
  name: databases.example.com

spec:

  group: example.com

  scope: Namespaced

  names:
    plural: databases
    singular: database
    kind: Database
    shortNames:
      - db

  versions:
    - name: v1
      served: true
      storage: true

      schema:
        openAPIV3Schema:
          type: object

          properties:

            spec:
              type: object

              properties:

                engine:
                  type: string

                version:
                  type: string

                storage:
                  type: string

처음 보면 복잡해 보이지만 각 항목을 나누어 보면 이해하기 어렵지 않습니다.

7. apiVersion과 kind

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition

이 YAML 자체가 Kubernetes의 CustomResourceDefinition 리소스라는 의미입니다.

즉 CRD 역시 Kubernetes API를 통해 관리되는 하나의 Resource입니다.

8. metadata.name 규칙

metadata:
  name: databases.example.com

CRD 이름은 일반적으로 다음 구조를 사용합니다.

plural.group

따라서:

plural = databases
group  = example.com

CRD name

databases.example.com

9. Group이란?

spec:
  group: example.com

Group은 Custom Resource가 속하는 API Group을 의미합니다.

기본 Kubernetes Resource도 API Group을 사용합니다.

Deployment

apps/v1


Role

rbac.authorization.k8s.io/v1


CRD

apiextensions.k8s.io/v1

Custom Resource 역시 동일한 방식으로 별도의 API Group을 사용할 수 있습니다.

example.com/v1

10. scope - Namespaced와 Cluster

CRD는 Resource의 Scope를 지정해야 합니다.

scope: Namespaced

또는:

scope: Cluster

Scope	설명	예시 개념
Namespaced	Namespace에 종속되는 Resource	Pod, Deployment와 유사
Cluster	Cluster 전체에서 관리되는 Resource	Node, Namespace와 유사

Namespaced CR이라면 다음처럼 Namespace별로 동일한 이름을 사용할 수도 있습니다.

Namespace: production
Database: postgresql


Namespace: development
Database: postgresql

11. names 설정

names:

  plural: databases

  singular: database

  kind: Database

  shortNames:
    - db

각 항목은 다음 역할을 합니다.

항목	의미
plural	복수 Resource 이름
singular	단수 Resource 이름
kind	YAML에서 사용하는 Kind
shortNames	kubectl에서 사용할 단축 이름

예를 들어 다음 명령을 사용할 수 있습니다.

kubectl get databases

kubectl get database

kubectl get db

12. versions 설정

versions:

- name: v1

  served: true

  storage: true

CRD도 API Version을 가질 수 있습니다.

example.com/v1

example.com/v1beta1

example.com/v2

served: true는 해당 Version을 API를 통해 제공한다는 의미이며, storage: true는 해당 Version을 etcd에 저장할 때 사용하는 Storage Version으로 지정한다는 의미입니다.

하나의 CRD에서 여러 Version을 제공할 수 있지만 storage: true는 하나의 Version에만 지정합니다.

13. OpenAPI Schema

CRD에서는 Custom Resource에 어떤 값을 사용할 수 있는지 Schema를 정의할 수 있습니다.

schema:

  openAPIV3Schema:

    type: object

    properties:

      spec:

        type: object

        properties:

          engine:
            type: string

          version:
            type: string

          replicas:
            type: integer

이 Schema를 이용하여 API Server가 Custom Resource의 입력값을 검증할 수 있습니다.

14. Validation을 추가할 수도 있다

예를 들어 Database Replica를 최소 1개에서 최대 10개까지만 허용하고 싶다면:

replicas:
  type: integer
  minimum: 1
  maximum: 10

Engine을 PostgreSQL과 MySQL만 허용하고 싶다면:

engine:
  type: string
  enum:
    - postgresql
    - mysql

이렇게 하면 잘못된 Custom Resource가 API Server에 등록되는 것을 방지할 수 있습니다.

15. CRD를 설치하면 어떻게 되는가?

CRD YAML을 적용합니다.

kubectl apply -f database-crd.yaml

CRD가 정상적으로 등록됐는지 확인합니다.

kubectl get crd

특정 CRD를 확인하려면:

kubectl get crd databases.example.com

상세 정보를 확인하려면:

kubectl describe crd databases.example.com

16. CRD 설치 전과 설치 후 차이

CRD 설치 전

kubectl get databases

error:
the server doesn't have a resource type "databases"

CRD 설치 후

kubectl get databases

NAME
production-db
development-db

즉 API Server가 Database라는 새로운 Resource를 이해하게 된 것입니다.

17. Custom Resource 생성하기

CRD를 설치했다면 실제 Custom Resource를 생성할 수 있습니다.

apiVersion: example.com/v1
kind: Database

metadata:
  name: production-db

spec:
  engine: postgresql
  version: "16"
  replicas: 3

적용합니다.

kubectl apply -f database.yaml

확인합니다.

kubectl get databases

또는 shortName을 지정했다면:

kubectl get db

18. 여기서 가장 중요한 부분 - CRD만 설치하면 Database가 생성될까?

아닙니다.

CRD를 설치하는 것은 Kubernetes에 새로운 Resource Type을 등록하는 것뿐입니다.

CRD 설치

"Database라는 Resource가 존재한다"
          │
          ▼
API Server가 이해함

하지만 실제 PostgreSQL을 설치하거나 Pod를 생성하는 작업은 CRD 자체가 수행하지 않습니다.

CRD는 정의이고 실제 동작은 일반적으로 Controller 또는 Operator가 수행합니다.

19. CRD와 Controller의 관계

전체 구조를 보면 다음과 같습니다.

                Kubernetes API Server
                         │
                         │
                 Custom Resource
                         │
                         ▼
                    Controller
                         │
                  Watch / Reconcile
                         │
                         ▼
              원하는 상태와 비교
                         │
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
        Pod           Service       ConfigMap

Controller는 API Server를 지속적으로 감시하면서 Custom Resource가 생성되거나 변경되었는지 확인합니다.

그리고 사용자가 정의한 Desired State와 실제 Kubernetes 상태인 Current State를 비교합니다.

20. Reconcile이란?

Kubernetes Controller를 이해하려면 Reconciliation Loop 개념을 알아야 합니다.

Desired State
사용자가 원하는 상태

        │
        ▼

Controller

        │
        ▼

Current State
현재 실제 상태

        │
        ▼

차이가 있는가?

        │
   ┌────┴────┐
   │         │
  YES       NO
   │         │
   ▼         ▼
상태 변경    유지

예를 들어 사용자가 다음과 같이 Database CR을 만들었다고 가정합니다.

spec:
  engine: postgresql
  replicas: 3

Controller는 이를 보고 실제 PostgreSQL 관련 Pod가 3개 존재하는지 확인합니다.

만약 2개밖에 없다면:

Desired State = 3

Current State = 2

Difference = 1

Controller
   ↓
Pod 추가 생성

Current State = 3

이러한 동작을 반복하는 것이 Kubernetes Controller의 핵심 원리입니다.

21. CRD + CR + Controller 관계

세 가지를 함께 보면 이해하기 쉽습니다.

CRD
│
│ "Database라는 리소스가 무엇인지 정의"
│
▼
Custom Resource
│
│ "PostgreSQL 3개를 만들어줘"
│
▼
Controller
│
│ CR 감시
│ Desired State 확인
│
▼
실제 Kubernetes Resource 생성
│
├─ StatefulSet
├─ Service
├─ Secret
├─ ConfigMap
└─ PVC

22. Operator란?

Operator는 CRD와 Controller 패턴을 이용하여 특정 애플리케이션이나 시스템의 운영 작업을 자동화하는 소프트웨어입니다.

단순하게 표현하면:

CRD
+
Custom Resource
+
Controller
+
운영 로직
=
Operator

Operator는 단순한 Resource 생성뿐 아니라 다음과 같은 복잡한 운영 작업도 자동화할 수 있습니다.

Application 설치

Scale Out / Scale In

Backup

Restore

Failover

Upgrade

Configuration 변경

Health Check

장애 복구

23. CRD와 Operator 차이

구분	CRD	Operator
역할	Custom Resource 정의	Custom Resource를 실제로 제어
API 확장	O	CRD를 활용
실제 작업 수행	X	O
Controller 포함	X	일반적으로 O
운영 자동화	직접 수행하지 않음	가능

24. 실제 Kubernetes에서 CRD가 사용되는 사례

실제 Kubernetes 생태계에서는 CRD가 매우 광범위하게 사용됩니다.

솔루션	CRD 활용 예
Prometheus Operator	Prometheus, ServiceMonitor, PodMonitor 등
cert-manager	Certificate, Issuer, ClusterIssuer 등
Argo CD	Application, ApplicationSet 등
Istio	VirtualService, DestinationRule 등
Vertical Pod Autoscaler	VerticalPodAutoscaler
다양한 Database Operator	Database Cluster 및 Backup 관련 Custom Resource

25. Gateway API와 CRD를 이해할 때 주의할 점

Gateway API를 공부할 때도 CRD라는 용어를 자주 접하게 됩니다.

대표적인 Gateway API Resource는 다음과 같습니다.

GatewayClass
Gateway
HTTPRoute
GRPCRoute
ReferenceGrant

Gateway API 구현 환경에서는 이러한 API Resource를 제공하기 위한 정의가 클러스터에 설치되며, NGINX Gateway Fabric과 같은 Controller가 해당 Resource를 감시하여 실제 네트워크 구성을 수행합니다.

Gateway API Resource
       │
       ▼
NGINX Gateway Fabric
Controller
       │
       ▼
NGINX Data Plane
       │
       ▼
Service
       │
       ▼
Pod

따라서 CRD와 Controller의 역할을 분리해서 이해하는 것이 중요합니다.

26. VPA에서도 CRD가 사용된다

Vertical Pod Autoscaler를 설치하면 다음과 같은 Custom Resource를 사용할 수 있습니다.

apiVersion: autoscaling.k8s.io/v1
kind: VerticalPodAutoscaler

즉 VPA는 Kubernetes 기본 HPA와 달리 관련 CRD 및 Controller를 별도로 설치하여 사용하는 구조입니다.

VPA CRD
   │
   ▼
VerticalPodAutoscaler CR
   │
   ▼
VPA Controller Components
   │
   ├─ Recommender
   ├─ Updater
   └─ Admission Controller

27. 현재 Cluster의 CRD 확인하기

현재 Kubernetes Cluster에 설치된 모든 CRD는 다음 명령으로 확인할 수 있습니다.

kubectl get crd

CRD가 많다면 특정 문자열로 검색할 수 있습니다.

kubectl get crd | grep gateway

kubectl get crd | grep prometheus

kubectl get crd | grep cert

kubectl get crd | grep autoscaling

28. CRD 상세 정보 확인

kubectl describe crd CRD_NAME

전체 YAML을 확인하려면:

kubectl get crd CRD_NAME -o yaml

이를 통해 다음 정보를 확인할 수 있습니다.

Group
Version
Kind
Plural
Scope
Schema
Status
Stored Version
Printer Columns

29. Kubernetes API Resource 전체 확인

CRD뿐 아니라 현재 Cluster에서 사용할 수 있는 모든 API Resource는 다음 명령으로 확인할 수 있습니다.

kubectl api-resources

예를 들어:

NAME          SHORTNAMES   APIVERSION              NAMESPACED   KIND

pods          po           v1                      true         Pod

deployments   deploy       apps/v1                 true         Deployment

databases     db           example.com/v1          true         Database

여기서 Custom Resource도 일반 Kubernetes Resource와 동일하게 표시됩니다.

30. CRD가 어느 API Group에 속하는지 확인하기

kubectl api-resources --api-group=example.com

API Version 전체를 확인하려면:

kubectl api-versions

31. 특정 CRD로 생성된 CR 확인하기

예를 들어 Database라는 Custom Resource가 있다면 다음과 같이 조회할 수 있습니다.

kubectl get databases

모든 Namespace에서 조회하려면:

kubectl get databases -A

상세 정보:

kubectl describe database production-db -n production

YAML 확인:

kubectl get database production-db -n production -o yaml

32. Spec과 Status의 차이

Custom Resource에서도 Kubernetes의 일반적인 Resource 패턴과 마찬가지로 spec과 status를 구분하여 사용하는 경우가 많습니다.

항목	의미
spec	사용자가 원하는 상태, 즉 Desired State
status	Controller가 관찰한 현재 상태, 즉 Observed State

예를 들어:

spec:

  replicas: 3

  version: "16"


status:

  readyReplicas: 3

  state: Running

이를 해석하면:

사용자 요구

PostgreSQL 16
Replica 3개
        │
        ▼
      spec


실제 상태

Ready Replica 3개
Running
        │
        ▼
      status

33. Status Subresource

CRD에서는 status를 별도의 Subresource로 활성화할 수 있습니다.

subresources:
  status: {}

이렇게 구성하면 Controller가 Resource의 Spec을 직접 변경하지 않고 Status 영역을 별도로 업데이트하는 구조를 만들 수 있습니다.

34. Scale Subresource

Custom Resource가 Replica 개념을 가지고 있다면 Scale Subresource를 정의할 수도 있습니다.

subresources:

  scale:

    specReplicasPath: .spec.replicas

    statusReplicasPath: .status.replicas

    labelSelectorPath: .status.labelSelector

이를 통해 Custom Resource를 Kubernetes의 Scaling 메커니즘과 연동할 수 있습니다.

35. CRD는 어디에 저장되는가?

CRD와 CR 역시 다른 Kubernetes Resource와 마찬가지로 API Server를 통해 관리되며, 최종 상태 데이터는 Kubernetes의 저장소인 etcd에 저장됩니다.

kubectl
   │
   ▼
API Server
   │
   ▼
CRD / CR
   │
   ▼
etcd

따라서 etcd 백업은 Kubernetes 기본 Resource뿐 아니라 Custom Resource의 상태를 보호하는 측면에서도 중요합니다.

36. CRD를 삭제하면 어떻게 될까?

CRD는 일반 Resource보다 삭제 시 주의가 필요합니다.

kubectl delete crd databases.example.com

CRD를 삭제하면 해당 CRD에 의해 정의된 Custom Resource 역시 더 이상 API를 통해 사용할 수 없으며, 관련 Custom Resource 데이터가 함께 삭제될 수 있습니다.

운영 환경에서는 CRD를 단순히 사용하지 않는다는 이유로 삭제하면 안 됩니다.
해당 CRD를 사용하는 Operator, Controller, Application 및 Custom Resource 존재 여부를 먼저 확인해야 합니다.

37. Controller를 먼저 삭제하면 어떻게 될까?

Controller가 없어져도 CRD와 Custom Resource가 즉시 사라지는 것은 아닙니다.

CRD 존재
   │
CR 존재
   │
Controller 없음
   │
   ▼
API Resource 조회 가능

하지만

Reconciliation 동작 안 함

즉 Resource는 존재하지만 해당 Resource를 보고 실제 작업을 수행하는 Controller가 없기 때문에 자동화된 운영 동작이 멈출 수 있습니다.

이 차이는 CRD 장애 분석에서 매우 중요합니다.

38. CRD는 Namespace마다 설치하는가?

아닙니다.

CRD 자체는 Cluster Scope Resource입니다. 따라서 CRD는 Kubernetes Cluster 전체에 한 번 등록됩니다.

Cluster

CRD
databases.example.com
        │
        ├──────────────┐
        │              │
        ▼              ▼
Namespace A        Namespace B
Database CR       Database CR

다만 CRD에서 scope: Namespaced로 정의했다면 그 CRD를 이용해 생성하는 Custom Resource는 Namespace에 속하게 됩니다.

39. CRD와 ConfigMap 차이

구분	CRD	ConfigMap
목적	새로운 Kubernetes API Resource 정의	애플리케이션 설정 저장
API 확장	가능	불가능
Schema 정의	가능	일반적인 Key/Value 데이터
Controller 연동	주요 활용 방식	가능하지만 주목적은 설정 저장
Custom Kind 생성	가능	불가능

40. CRD와 기본 Kubernetes Resource 차이

구분	기본 Resource	Custom Resource
예시	Pod, Deployment, Service	Certificate, ServiceMonitor 등
API 정의	Kubernetes에 기본 제공	CRD 등을 통해 확장
API Server 관리	O	O
kubectl 사용	O	O
etcd 저장	O	O
Controller 필요성	Resource에 따라 기본 Controller 존재	실제 자동화 동작에는 별도 Controller가 필요한 경우가 많음

41. CRD 장애 확인 방법

Operator나 Controller 기반 솔루션에 문제가 발생했다면 다음 순서로 확인하면 좋습니다.

1. CRD 존재 확인

kubectl get crd


2. Custom Resource 확인

kubectl get RESOURCE -A


3. CR 상세 확인

kubectl describe RESOURCE NAME -n NAMESPACE


4. Controller Pod 확인

kubectl get pods -A


5. Controller 로그 확인

kubectl logs CONTROLLER_POD -n NAMESPACE


6. Event 확인

kubectl get events -n NAMESPACE --sort-by=.lastTimestamp

42. CRD가 정상인데 기능이 동작하지 않는 경우

CRD가 존재한다고 해서 해당 기능이 정상이라는 의미는 아닙니다.

CRD 정상
   │
   ▼
CR 정상
   │
   ▼
Controller 정상?
   │
   ├─ NO → 기능 동작 안 함
   │
   └─ YES
        │
        ▼
Reconcile 정상?
        │
        ▼
실제 Resource 정상?

따라서 CRD 기반 시스템 장애를 확인할 때는 CRD → CR → Controller → 실제 Resource 순서로 확인하는 것이 좋습니다.

43. CRD와 Helm의 관계

Helm Chart로 Operator나 Kubernetes 솔루션을 설치하면 CRD가 함께 설치되는 경우가 많습니다.

Helm Install
     │
     ├─ CRD
     ├─ Controller Deployment
     ├─ ServiceAccount
     ├─ ClusterRole
     ├─ ClusterRoleBinding
     ├─ Service
     └─ ConfigMap

따라서 Helm으로 애플리케이션을 제거할 때도 CRD가 자동으로 삭제되는지 여부를 반드시 확인해야 합니다.

특히 CRD에는 실제 Custom Resource 데이터가 존재할 수 있기 때문에 일부 Chart에서는 데이터 보호를 위해 CRD를 일반 Resource와 다르게 관리합니다.

44. CRD를 수정할 때 주의할 점

운영 중인 CRD를 직접 수정하는 것은 신중해야 합니다.

특히 다음 항목을 변경할 경우 영향도를 확인해야 합니다.

Schema

Version

Storage Version

Required Field

Validation Rule

Default Value

Conversion

Scope

이미 기존 Custom Resource가 저장되어 있다면 새로운 Schema와 기존 데이터 사이의 호환성 문제가 발생할 수 있습니다.

45. CRD Version Upgrade

솔루션을 업그레이드하면 CRD Version이 변경되는 경우가 있습니다.

기존

example.com/v1beta1


신규

example.com/v1

이 경우 단순히 YAML의 apiVersion만 변경하는 문제가 아닐 수 있습니다.

CRD는 여러 Version을 동시에 제공할 수 있으며, 필요한 경우 Conversion Webhook을 이용하여 Version 간 변환을 처리할 수도 있습니다.

v1beta1
   │
   ▼
Conversion
   │
   ▼
v1

46. CRD의 장점

Kubernetes API 확장

Kubernetes Core를 직접 수정하지 않고 새로운 Resource Type을 추가할 수 있습니다.

kubectl과 동일하게 관리 가능

kubectl get
kubectl describe
kubectl apply
kubectl delete

기존 Kubernetes 관리 방식과 동일하게 사용할 수 있습니다.

선언적 관리

사용자가 원하는 상태를 YAML의 spec에 선언하고 Controller가 실제 상태를 맞추는 Kubernetes 방식의 운영 자동화를 구현할 수 있습니다.

Operator 구현 가능

Database, Monitoring, Backup, Network 등 복잡한 시스템 운영 로직을 Kubernetes 내부에 구현할 수 있습니다.

47. CRD의 단점 및 주의사항

CRD만으로 실제 기능이 구현되는 것은 아니다

CRD는 API 정의 역할을 담당하며, 실제 자동화 기능에는 Controller가 필요합니다.

CRD가 많아지면 관리가 복잡해진다

Rancher나 여러 Operator를 사용하는 Cluster에서는 수십 개에서 수백 개의 CRD가 설치될 수 있습니다.

버전 호환성을 확인해야 한다

Kubernetes Version과 Operator, CRD Version 사이의 호환성을 확인해야 합니다.

CRD 삭제 위험

CRD 삭제는 해당 Custom Resource 데이터에 영향을 줄 수 있기 때문에 일반적인 Deployment 삭제보다 훨씬 신중해야 합니다.

48. CRD 핵심 구조 한눈에 보기

┌──────────────────────────────────────┐
│          Kubernetes Cluster          │
│                                      │
│  CRD                                 │
│  "Database라는 Resource를 정의"      │
│                │                     │
│                ▼                     │
│  Custom Resource                     │
│                                      │
│  Database: production-db             │
│  spec:                               │
│    engine: postgresql                │
│    replicas: 3                       │
│                │                     │
│                ▼                     │
│  Controller / Operator               │
│                │                     │
│         Watch & Reconcile            │
│                │                     │
│                ▼                     │
│  ┌──────────┬─────────┬───────────┐  │
│  │StatefulSet│ Service │    PVC    │  │
│  └──────────┴─────────┴───────────┘  │
│                                      │
└──────────────────────────────────────┘

49. CRD를 한 문장으로 정리하면

CRD(Custom Resource Definition)는 Kubernetes API에 사용자가 원하는 새로운 Resource Type을 정의하여 추가하는 기능이며, CRD로 정의된 실제 객체가 Custom Resource이고, 이를 감시하여 실제 작업을 수행하는 것이 Controller 또는 Operator이다.

즉 다음 세 가지를 구분해서 기억하면 됩니다.

CRD
= 무엇을 만들 수 있는지 정의


CR
= 사용자가 무엇을 원하는지 선언


Controller / Operator
= 실제로 원하는 상태를 만들어주는 프로그램

50. 결론

Kubernetes CRD는 Kubernetes를 단순한 Container Orchestration 플랫폼에서 다양한 시스템을 선언적으로 관리할 수 있는 확장 가능한 플랫폼으로 만들어주는 핵심 기능 중 하나입니다.

기본 Kubernetes에서는 Pod, Deployment, Service 등의 Resource를 제공하지만, CRD를 사용하면 Database, Certificate, MonitoringRule 등 새로운 Resource를 Kubernetes API에 추가할 수 있습니다.

다만 CRD 자체가 애플리케이션을 생성하거나 운영하는 것은 아닙니다. CRD는 새로운 Resource의 구조를 정의하고, 사용자가 생성한 Custom Resource를 Controller 또는 Operator가 감시하여 실제 Kubernetes Resource를 생성하거나 변경합니다.

따라서 Kubernetes의 확장 기능을 이해하려면 다음 관계를 가장 먼저 이해하는 것이 중요합니다.

CRD
 ↓
Custom Resource
 ↓
Controller / Operator
 ↓
Reconciliation
 ↓
실제 Kubernetes Resource

Rancher, Prometheus Operator, cert-manager, VPA, 각종 Database Operator 등 실제 운영 환경에서 사용하는 많은 Kubernetes 솔루션이 이러한 CRD와 Controller 패턴을 활용하고 있습니다.