컴포지트 리소스 정의

원문 보기 위키 갱신 2026.10.03

컴포지트 리소스 정의 (Composite Resource Definitions / XRD)

컴포지트 리소스 정의(XRD)는 커스텀 API의 스키마를 정의해요. 사용자는 XRD가 정의한 API 스키마를 사용해 컴포지트 리소스(XR)를 만들어요. 컴포지트 리소스에 대한 자세한 내용은 composite resources 페이지를 읽어보세요.

출처: 문서

본문

XR, XRD, Composition이 뭘까요? 컴포지트 리소스(XR)는 커스텀 API예요. 새 커스텀 API를 만들려면 두 가지 Crossplane 타입을 사용해요.

Composite Resource Definition (XRD) — 이 페이지. XR의 스키마를 정의해요.
Composition — XR이 다른 리소스를 어떻게 생성하는지 구성해요.

Crossplane XRD는 Kubernetes 커스텀 리소스 정의(CRD)와 비슷해요. XRD는 필드가 더 적고, connection secrets 같은 Crossplane 관련 옵션이 추가돼 있어요.

CompositeResourceDefinition 만들기 (Creating a CompositeResourceDefinition)

CompositeResourceDefinition을 만드는 것은 다음으로 구성돼요.

커스텀 API 그룹 정의
커스텀 API 이름 정의
커스텀 API 스키마와 버전 정의
스코프 설정 (네임스페이스 또는 클러스터 스코프)

선택적으로 CompositeResourceDefinition은 컴포지트 리소스 기본값 설정도 지원해요.

CompositeResourceDefinition(XRD)은 Kubernetes 클러스터 안에 새 API 엔드포인트를 만들어요. 새 API를 만들려면 API group, name, version을 정의해야 해요.

apiVersion: apiextensions.crossplane.io/v2
kind: CompositeResourceDefinition
metadata:
  name: mydatabases.example.org
spec:
  scope: Namespaced
  group: example.org
  names:
    kind: XMyDatabase
    plural: mydatabases
  versions:
  - name: v1alpha1
  # Removed for brevity

XRD를 적용하면 Crossplane이 정의된 API와 일치하는 새 Kubernetes 커스텀 리소스 정의를 만들어요. 예를 들어 XRD mydatabases.example.org는 mydatabases.example.org라는 커스텀 리소스 정의를 만들어요.

kubectl api-resources
NAME                              SHORTNAMES   APIVERSION          NAMESPACED   KIND
mydatabases.example.org                        v1alpha1            true         mydatabases
# Removed for brevity

XRD의 group이나 names는 변경할 수 없어요. group이나 names를 바꾸려면 XRD를 삭제하고 다시 만들어야 해요.

XRD 그룹 (XRD groups)

그룹은 관련 API 엔드포인트의 모음을 정의해요. group은 어떤 값이든 될 수 있지만, 일반적으로 정규화된 도메인 이름(FQDN)에 매핑하는 것이 관례예요. 많은 XRD가 같은 group을 사용해 API의 논리적 모음을 만들 수 있어요. 예를 들어 database 그룹에 relational과 nosql kind가 있을 수 있어요.

XRD 이름 (XRD names)

names 필드는 이 특정 XRD를 어떻게 참조할지 정의해요. 필수 이름 필드는 다음과 같아요.

kind — 이 API를 호출할 때 사용할 kind 값. kind는 UpperCamelCase로 작성해요. Crossplane은 XRD kind를 X로 시작할 것을 권장하는데, 이는 커스텀 Crossplane API 정의임을 나타내기 위함이에요.
plural — API URL에 사용하는 복수 이름. plural 이름은 소문자여야 해요.

XRD metadata.name은 plural 이름 + .(점) + group 이어야 해요. 예를 들어 mydatabases.example.org는 plural 이름 mydatabases, ., group 이름 example.org로 구성돼요.

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: mydatabases.example.org
spec:
  group: example.org
  names:
    kind: XMyDatabase
    plural: mydatabases
    # Removed for brevity

XRD 버전 (XRD versions)

XRD version은 Kubernetes의 API 버저닝과 같아요. 버전은 API가 얼마나 성숙하고 안정적인지 보여주며, API의 필드를 변경·추가·제거할 때 증가해요.

Crossplane은 특정 버전이나 특정 버전 명명 규칙을 요구하지 않지만, Kubernetes API 버저닝 가이드라인을 따르는 것을 강력히 권장해요.

v1alpha1 — 언제든 변경될 수 있는 새 API
v1beta1 — 안정적이라고 간주되는 기존 API. 파괴적 변경은 강력히 권장되지 않아요.
v1 — 파괴적 변경이 없는 안정적인 API

스키마 정의 (Define a schema)

schema는 파라미터의 이름, 파라미터의 데이터 타입, 그리고 필수/선택 여부를 정의해요.

모든 schema는 Kubernetes 커스텀 리소스 정의 OpenAPIv3 구조적 스키마를 따르며, API의 각 version은 고유한 schema를 가져요. 모든 XRD schema는 openAPIV3Schema에 대해 검증돼요. 스키마는 spec object의 properties를 가진 OpenAPI object예요.

spec.properties 안에 커스텀 API 정의가 있어요. 이 예에서 키 region은 string이에요.

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xdatabases.custom-api.example.org
spec:
  group: custom-api.example.org
  names:
    kind: xDatabase
    plural: xdatabases
  versions:
  - name: v1alpha1
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              region:
                type: string
    # Removed for brevity

이 API를 사용하는 컴포지트 리소스는 group/version과 kind를 참조해요. spec에는 문자열 값의 region 키가 있어요.

apiVersion: custom-api.example.org/v1alpha1
kind: xDatabase
metadata:
  name: my-composite-resource
spec:
  region: "US"

spec.properties 안에 정의된 커스텀 API는 OpenAPIv3 명세예요. Swagger 문서의 데이터 모델 페이지에 데이터 타입과 입력 제한을 사용한 예가 있어요. Kubernetes 문서에는 커스텀 API가 사용할 수 있는 특별 제한 집합이 나열돼 있어요.

XRD 스키마를 변경하거나 확장하려면 적용하려면 Crossplane 파드를 재시작해야 해요.

필수 필드 (Required fields)

기본적으로 스키마의 모든 필드는 선택 사항이에요. required 속성으로 파라미터를 필수로 정의해요.

이 예에서 XRD는 region과 size를 요구하고 name은 선택이에요.

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xdatabases.custom-api.example.org
spec:
  group: custom-api.example.org
  names:
    kind: xDatabase
    plural: xdatabases
  versions:
  - name: v1alpha1
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              region:
                type: string
              size:
                type: string
              name:
                type: string
            required:
              - region
              - size
    # Removed for brevity

OpenAPIv3 명세에 따르면 required 필드는 객체별로 적용돼요. 스키마에 여러 객체가 있으면 required 필드가 여러 개 필요할 수 있어요.

이 XRD는 두 객체를 정의해요.

최상위 spec 객체
두 번째 location 객체

spec 객체는 size와 location을 요구하고 name은 선택이에요. 필수 location 객체 안에서 country가 required이고 zone은 선택이에요.

# Removed for brevity
- name: v1alpha1
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              size:
                type: string
              name:
                type: string
              location:
                type: object
                properties:
                  country:
                    type: string
                  zone:
                    type: string
                required:
                  - country
            required:
              - size
              - location

Swagger "Describing Parameters" 문서에 더 많은 예가 있어요.

Crossplane 예약 필드 (Crossplane reserved fields)

Crossplane은 스키마에서 다음 필드를 허용하지 않아요.

spec.crossplane 객체 아래의 모든 필드
status.crossplane 객체 아래의 모든 필드
status.conditions

Crossplane은 예약 필드와 일치하는 어떤 필드도 무시해요.

스키마 서빙과 참조 (Serve and reference a schema)

스키마를 사용하려면 served: true와 referenceable: true여야 해요.

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xdatabases.custom-api.example.org
spec:
  group: custom-api.example.org
  names:
    kind: xDatabase
    plural: xdatabases
  versions:
  - name: v1alpha1
    served: true
    referenceable: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              region:
                type: string

컴포지트 리소스는 served: true로 설정된 어떤 스키마 버전이든 사용할 수 있어요. Kubernetes는 served: false로 설정된 스키마 버전을 사용하는 컴포지트 리소스를 거부해요.

스키마 버전을 served: false로 설정하면 더 오래된 스키마를 쓰는 사용자에게 오류가 발생해요. 이는 오래된 스키마 버전을 삭제하기 전에 사용자를 식별하고 업그레이드하는 효과적인 방법이 될 수 있어요.

referenceable: true 필드는 Compositions가 사용하는 스키마 버전을 나타내요. referenceable인 버전은 하나만 존재할 수 있어요.

referenceable: true인 버전을 변경하려면 그 XRD를 참조하는 모든 Compositions의 compositeTypeRef.apiVersion을 업데이트해야 해요.

여러 스키마 버전 (Multiple schema versions)

Crossplane은 여러 versions 정의를 지원하지만, 각 버전의 스키마는 기존 필드를 변경할 수 없어요(소위 "파괴적 변경"을 해서는 안 됨). 버전 간 파괴적 스키마 변경은 conversion webhooks를 사용해야 해요. 새 버전은 새 선택적 파라미터를 정의할 수 있지만, 새 필수 필드는 "파괴적 변경"이에요.

Crossplane XRD는 버저닝에 Kubernetes 커스텀 리소스 정의를 사용해요. 버전과 파괴적 변경에 대한 배경은 Kubernetes 문서의 versions in CustomResourceDefinitions를 읽어보세요. Crossplane은 파괴적 스키마 변경을 완전히 새로운 XRD로 구현할 것을 권장해요.

XRD에서 API의 새 버전을 만들려면 versions 목록에 새 name을 추가해요.

예를 들어 이 XRD 버전 v1alpha1은 region 필드만 있어요. 두 번째 버전 v1은 region과 size를 모두 갖도록 API를 확장해요.

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xdatabases.custom-api.example.org
spec:
  group: custom-api.example.org
  names:
    kind: xDatabase
    plural: xdatabases
  versions:
  - name: v1alpha1
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              region:
                type: string
  - name: v1
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              region:
                type: string
              size:
                type: string

XRD 스키마를 변경하거나 확장하려면 적용하려면 Crossplane 파드를 재시작해야 해요.

XRD 스코프 (XRD scope)

scope 필드는 이 XRD에서 만든 컴포지트 리소스가 네임스페이스에 존재하는지, 클러스터 스코프에 존재하는지 결정해요.

apiVersion: apiextensions.crossplane.io/v2
kind: CompositeResourceDefinition
metadata:
  name: mydatabases.example.org
spec:
  scope: Namespaced
  # Removed for brevity

scope 필드가 지원하는 세 가지 값:

Namespaced — (v2에서 기본값) 컴포지트 리소스가 네임스페이스에 존재하며 같은 네임스페이스의 리소스만 컴포즈할 수 있어요.
Cluster — 컴포지트 리소스가 클러스터 스코프이고, 어떤 네임스페이스나 클러스터 스코프의 리소스든 컴포즈할 수 있어요.
LegacyCluster — 클레임(claims, v1 호환 모드)을 지원하는 클러스터 스코프.

대부분의 XRD는 Namespaced 스코프를 사용해야 해요. 이는 더 나은 보안 격리를 제공하고 표준 Kubernetes 패턴을 따르기 때문이에요. Cluster 스코프는 RBAC나 클러스터 구성 같은 플랫폼 수준 리소스에만 사용하세요.

Scale 서브리소스 (Scale subresource)

XRD는 컴포지트 리소스에 Kubernetes scale 서브리소스를 노출할 수 있어요. 이를 통해 kubectl scale, Horizontal Pod Autoscaler, KEDA가 컴포지트 리소스를 제어할 수 있게 돼요. 전체 워크스루는 Scalable Composition을 참고하세요.

컴포지트 리소스 기본값 설정 (Set composite resource defaults)

XRD는 컴포지트 리소스의 기본 파라미터를 설정할 수 있어요.

defaultCompositionRef

여러 Composition이 같은 XRD를 참조할 수 있어요. 하나 이상의 Composition이 같은 XRD를 참조하면 컴포지트 리소스는 어떤 Composition을 사용할지 선택해야 해요. XRD는 defaultCompositionRef 값으로 사용할 기본 Composition을 정의할 수 있어요.

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xdatabases.custom-api.example.org
spec:
  defaultCompositionRef:
    name: myComposition
  group: custom-api.example.org
  names:
  # Removed for brevity
  versions:
  # Removed for brevity

defaultCompositionUpdatePolicy

Composition에 대한 변경은 새 Composition 리비전을 생성해요. 기본적으로 모든 컴포지트 리소스는 업데이트된 Composition 리비전을 사용해요. XRD defaultCompositionUpdatePolicy를 Manual로 설정하면 컴포지트 리소스가 새 리비전을 자동으로 사용하지 못하게 할 수 있어요. 기본값은 defaultCompositionUpdatePolicy: Automatic이에요.

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xdatabases.custom-api.example.org
spec:
  defaultCompositionUpdatePolicy: Manual
  group: custom-api.example.org
  names:
  # Removed for brevity
  versions:
  # Removed for brevity

enforcedCompositionRef

모든 컴포지트 리소스가 특정 Composition을 사용하도록 강제하려면 XRD에서 enforcedCompositionRef 설정을 사용해요. 이 XRD를 사용하는 모든 컴포지트 리소스가 myComposition을 쓰도록 하려면 enforcedCompositionRef.name: myComposition을 설정해요.

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xdatabases.custom-api.example.org
spec:
  enforcedCompositionRef:
    name: myComposition
  group: custom-api.example.org
  names:
  # Removed for brevity
  versions:
  # Removed for brevity

CompositeResourceDefinition 검증 (Verify a CompositeResourceDefinition)

kubectl get compositeresourcedefinition 또는 짧은 형식 kubectl get xrd로 XRD를 검증해요.

kubectl get xrd
NAME                                ESTABLISHED   OFFERED   AGE
xdatabases.custom-api.example.org   True          True      22m

ESTABLISHED 필드는 Crossplane이 이 XRD에 대한 Kubernetes 커스텀 리소스 정의를 설치했음을 나타내요.

XRD 조건 (XRD conditions)

Crossplane은 XRD에 표준 Conditions 집합을 사용해요. XRD의 조건은 kubectl describe xrd로 Status 아래에서 볼 수 있어요.

kubectl describe xrd
Name:         xpostgresqlinstances.database.starter.org
API Version:  apiextensions.crossplane.io/v1
Kind:         CompositeResourceDefinition
# Removed for brevity
Status:
  Conditions:
    Reason:                WatchingCompositeResource
    Status:                True
    Type:                  Established
# Removed for brevity

WatchingCompositeResource — Reason: WatchingCompositeResource는 Crossplane이 컴포지트 리소스와 관련된 새 Kubernetes 커스텀 리소스 정의를 정의했고, 새 컴포지트 리소스 생성을 감시하고 있음을 나타내요.

Type: Established
Status: True
Reason: WatchingCompositeResource

TerminatingCompositeResource — Reason: TerminatingCompositeResource는 Crossplane이 컴포지트 리소스와 관련된 커스텀 리소스 정의를 삭제하고 컴포지트 리소스 컨트롤러를 종료하고 있음을 나타내요.

Type: Established
Status: False
Reason: TerminatingCompositeResource