본문 바로가기
카테고리 없음

Kubernetes Custom Resource Definition(CRD) 실전 사용법

by valueinfo04 2025. 11. 12.

클라우드 환경에서 Kubernetes는 컨테이너 오케스트레이션의 핵심 플랫폼으로 자리 잡았습니다. 하지만 기본 제공 리소스(Pod, Service, Deployment 등)만으로는 모든 비즈니스 로직을 표현하기 어려운 경우가 많습니다. 이때 등장하는 개념이 바로 Custom Resource Definition(CRD)입니다.

CRD는 사용자 정의 리소스를 통해 쿠버네티스의 API를 확장하는 기능으로, 조직의 요구사항에 맞는 새로운 리소스를 직접 설계하고 관리할 수 있도록 돕습니다. 이 글에서는 2025년 기준으로 가장 최신의 CRD 실전 사용법을 단계별로 설명하며, 실제 운영 환경에서 적용 가능한 설정 팁과 주의사항까지 함께 다루겠습니다.

CRD의 개념과 역할

Custom Resource Definition(CRD)는 Kubernetes API 서버에 새로운 리소스 타입을 등록하는 기능입니다. 즉, 쿠버네티스가 기본적으로 인식하지 못하는 **사용자 정의 리소스(Custom Resource)**를 시스템 내에 정식 리소스로 추가해 사용할 수 있게 합니다.

예를 들어 “Application”, “Database”, “AlertPolicy” 같은 조직 맞춤 리소스를 생성하고, 이를 kubectl 명령어로 관리할 수 있습니다.

CRD를 활용하면 다음과 같은 이점이 있습니다.

✅ 조직별 비즈니스 로직을 쿠버네티스 리소스로 직접 표현 가능
✅ 쿠버네티스 네이티브 방식으로 선언형 관리(Declarative Management) 가능
✅ 외부 시스템 연동, 자동화, 모니터링 구조를 쉽게 통합 가능
✅ CI/CD 파이프라인과 자연스럽게 연동

즉, CRD는 단순한 확장 기능이 아니라 Kubernetes를 하나의 플랫폼 프레임워크로 발전시키는 핵심 요소입니다.

CRD 구성요소 이해하기

CRD는 YAML 형식으로 정의되며, 기본 구조는 아래와 같습니다.

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: applications.sample.io
spec:
  group: sample.io
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                name:
                  type: string
                replicas:
                  type: integer
  scope: Namespaced
  names:
    plural: applications
    singular: application
    kind: Application
    shortNames:
      - app

각 필드의 의미는 다음과 같습니다.

항목 설명
apiVersion CRD API 버전 (apiextensions.k8s.io/v1)
kind CRD 리소스 타입
metadata CRD 자체의 이름 및 메타데이터
spec.group API 그룹명 (예: sample.io)
spec.names 리소스의 명칭(plural, singular, kind 등)
spec.scope 네임스페이스 범위(Namespaced or Cluster)
versions 리소스 버전, 스키마 정의, 검증 규칙 등
openAPIV3Schema 리소스 스펙의 유효성 검증 규칙 정의

이 스키마를 통해 Kubernetes는 kubectl get applications 명령을 실행할 때 새로운 리소스를 인식하고 관리할 수 있게 됩니다.

실제 CRD 리소스 생성과 적용

1️⃣ CRD 정의 파일 생성
위에서 본 YAML 파일을 application-crd.yaml로 저장합니다.

2️⃣ CRD 생성 명령 실행

 
kubectl apply -f application-crd.yaml

이 명령으로 쿠버네티스 클러스터에 새로운 리소스 타입이 등록됩니다.

3️⃣ 리소스 확인

 
kubectl get crd

결과에 applications.sample.io가 표시되면 성공적으로 등록된 것입니다.

4️⃣ 사용자 정의 리소스 생성
CRD를 등록했으니 이제 실제 Custom Resource를 만들 수 있습니다.

 
apiVersion: sample.io/v1 kind: Application metadata: name: my-app spec: name: frontend replicas: 3

이 파일을 application.yaml로 저장한 뒤 다음 명령으로 생성합니다.

 
kubectl apply -f application.yaml

이제 kubectl get applications를 통해 직접 만든 Application 리소스를 조회할 수 있습니다.

Controller와 연동하여 동작 자동화

CRD만으로는 리소스를 정의할 수 있을 뿐, 동작을 제어하지는 못합니다. 리소스 생성·변경 이벤트에 반응하여 동작하는 Controller(컨트롤러)를 구현하면 완전한 기능 확장이 가능합니다.

Controller는 일반적으로 Go 언어 기반의 Operator Framework로 작성되며, Custom Resource 상태를 감시하고 대응하는 로직을 수행합니다.

예를 들어 “Application” 리소스가 생성되면 자동으로 Deployment와 Service를 생성하도록 구성할 수 있습니다.

💡 구현 흐름 요약:

  1. CRD 정의 (Application 리소스 설계)
  2. Controller 코드 작성 (Go, Python 등)
  3. 클러스터에 Controller Pod 배포
  4. Custom Resource 생성 시 자동 반응

Controller는 Kubernetes의 Reconciliation Loop 구조를 따르며, 상태가 실제 클러스터와 일치하지 않으면 지속적으로 조정(reconcile)합니다.

CRD 버전 관리와 업그레이드

운영 환경에서는 CRD 버전 관리가 매우 중요합니다.
API 구조나 필드가 바뀌면 하위 호환성을 고려해야 하며, versions 필드에 여러 버전을 등록하여 점진적으로 이전할 수 있습니다.

예시:

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

served는 해당 버전이 클라이언트 요청을 처리할 수 있음을 의미하고,
storage는 etcd에 저장되는 기본 버전을 지정합니다.

✅ 버전 업그레이드 팁

  • 기존 필드 삭제보다는 deprecated로 표시 후 유지
  • 신규 필드는 기본값을 설정하여 호환성 확보
  • CRD 마이그레이션 테스트 환경 구축

운영 환경에서의 CRD 관리 팁

  • 유효성 검사(Validation)
    openAPIV3Schema로 스펙을 엄격히 검증해야 합니다. 잘못된 값이 들어오면 배포 전단에서 차단됩니다.
  • 기본값 설정(Defaulting)
    x-kubernetes-default를 통해 필드 기본값을 정의하면 운영 중 실수를 줄일 수 있습니다.
  • 상태(Status) 관리
    Controller가 리소스의 상태를 갱신해주면, 사용자는 kubectl get 명령만으로 실행 상태를 파악할 수 있습니다.
  • 권한 제어(RBAC)
    CRD 리소스도 Role, ClusterRole을 통해 접근을 제어해야 합니다.
    관리자, 개발자, 자동화 봇 등 사용자 그룹별로 권한을 세분화하는 것이 안정적입니다.
  • 모니터링 및 로깅
    Controller 로그 및 CRD 이벤트를 중앙화된 로깅 시스템(예: Loki, ELK Stack)과 연동해 관리하면 문제 추적이 용이합니다.

자주 발생하는 문제와 해결법

문제 상황원인해결 방법
문제 상황 원인 해결 방법
CRD 등록은 됐지만 리소스 생성 불가 apiVersion 오타 또는 group 불일치 YAML 정의의 group과 apiVersion을 일치시킴
Controller가 동작하지 않음 RBAC 권한 부족 Controller의 ServiceAccount에 적절한 Role 부여
CRD 업데이트 실패 필드 타입 변경 불가 새로운 버전 추가 후 점진적 이전 전략 적용
리소스 삭제 시 연관 객체 남음 Finalizer 미처리 Controller에서 Finalizer 해제 로직 추가
Validation 불일치 스키마 정의 누락 openAPIV3Schema 필드에 타입 명시

마치며

Kubernetes CRD는 조직의 요구에 맞게 쿠버네티스를 확장할 수 있는 강력한 도구입니다. 표준 리소스만으로 해결할 수 없던 문제를 선언형 방식으로 해결하고, Controller와 결합하면 완전한 자동화 시스템을 구축할 수 있습니다.

CRD를 제대로 활용하면 개발팀과 운영팀이 동일한 인터페이스에서 협업할 수 있으며, 인프라 관리의 복잡도를 낮추고 플랫폼 수준의 일관성을 유지할 수 있습니다. 지금 바로 여러분의 환경에서 CRD를 정의하고, 쿠버네티스를 여러분의 조직만의 플랫폼으로 발전시켜보시기 바랍니다.

저작자표시 비영리 변경금지 (새창열림)

티스토리툴바