관리 리소스 정의

원문 보기 위키 갱신 2026.10.03

관리 리소스 정의 (Managed Resource Definitions / MRD)

이 기능은 v2에서 도입됐어요. 자세한 내용은 Crossplane 기능 수명주기를 읽어보세요.

Crossplane v2.0+ 는 관리 리소스 정의를 기본적으로 활성화해요. 이는 설치 중 Provider CRD를 자동으로 MRD로 변환해요. 이 동작을 비활성화하려면 Crossplane 설치 시 --enable-custom-to-managed-resource-conversion=false를 설정해요.

ManagedResourceDefinition(MRD)은 Kubernetes CustomResourceDefinitions(CRD)에 대한 가벼운 추상화로, 관리 리소스의 **선택적 활성화(selective activation)**를 가능하게 해요. MRD는 프로바이더가 100여 개의 CRD를 설치하는데 실제로는 한두 개만 필요한 문제를 해결해 API 서버 오버헤드를 줄이고 클러스터 성능을 개선해요.

출처: 문서

본문

CRD 스케일링 문제 (The CRD scaling problem)

대형 Crossplane Provider는 100개 이상의 관리 리소스 CRD를 설치할 수 있어요. 각 CRD는 약 3 MiB의 API 서버 메모리를 소비하고 클러스터 성능에 영향을 주는 API 엔드포인트를 만들어요.

메모리 압박 — 대형 Provider는 300+ MiB의 API 서버 메모리를 소비할 수 있어요.
느린 kubectl 작업 — kubectl get managed 같은 명령이 모든 커스텀 리소스 엔드포인트를 질의해야 해요.
API 서버 부하 증가 — CRD가 많을수록 서빙해야 할 API 엔드포인트가 많아져요.
불필요한 리소스 오버헤드 — 대부분의 사용자는 Provider 리소스의 일부만 필요해요.

MRD는 Provider가 리소스 정의를 제공하되, 명시적으로 필요할 때만 활성 CRD가 되도록 해 이 문제를 해결해요.

MRD가 동작하는 방식 (How MRDs work)

MRD는 CRD와 같은 스키마를 포함하지만 두 가지 핵심 필드를 추가해요.

connectionDetails — 리소스가 제공하는 연결 시크릿을 문서화
state — 기본 CRD가 존재하는지 제어 (Active 또는 Inactive)

MRD의 state가 Inactive면 클러스터에 CRD가 존재하지 않아요. 활성화하면 Crossplane이 해당 CRD를 만들고 Provider가 그 리소스의 인스턴스 관리를 시작할 수 있어요.

apiVersion: apiextensions.crossplane.io/v1alpha1
kind: ManagedResourceDefinition
metadata:
  name: buckets.s3.aws.m.crossplane.io
spec:
  group: s3.aws.m.crossplane.io
  names:
    kind: Bucket
    plural: buckets
  scope: Cluster
  versions:
  - name: v1alpha1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              forProvider:
                type: object
                properties:
                  region:
                    type: string
                  versioning:
                    type: boolean
  connectionDetails:
  - name: bucket-name
    description: The name of the created S3 bucket
  - name: region  
    description: The AWS region where the bucket was created
  state: Inactive  # Default state - no CRD created yet

주요 특성 (Key characteristics)

선택적 활성화 — 실제로 필요한 리소스에 대해서만 CRD 생성
성능 이점 — 비활성 MRD는 최소한의 클러스터 리소스만 소비
연결 상세 문서화 — 사용 가능한 연결 시크릿을 문서화하는 스키마
단방향 상태 전이 — MRD는 Inactive에서 Active로 갈 수 있지만 돌아갈 수 없어요.

MRD 상태 (MRD states)

Inactive 상태 (Inactive state)

state: Inactive(기본값)일 때:

클러스터에 CRD가 존재하지 않음
API 엔드포인트가 존재하지 않음
Provider가 이 리소스에 대한 컨트롤러를 시작하지 않음
최소한의 메모리와 CPU 오버헤드

spec:
  state: Inactive  # Default for all MRDs

Active 상태 (Active state)

state: Active일 때:

Crossplane이 해당 CRD를 생성
리소스용 API 엔드포인트가 사용 가능해짐
Provider가 인스턴스를 관리하는 컨트롤러를 시작
전통적인 관리 리소스와 같은 완전한 기능

spec:
  state: Active  # CRD will be created

MRD 상태 전이는 단방향이에요. MRD가 Active가 되면 Inactive로 돌아갈 수 없어요. 이는 기존 리소스가 있을 수 있는 CRD의 실수 삭제를 방지해요.

연결 상세 문서화 (Connection details documentation)

MRD는 관리 리소스가 제공하는 연결 상세를 문서화할 수 있어요. 이는 사용자가 테스트 리소스를 만들지 않고도 연결 시크릿에서 어떤 데이터를 쓸 수 있는지 이해하는 데 도움을 줘요.

spec:
  connectionDetails:
  - name: endpoint
    description: The RDS instance endpoint for database connections
  - name: port
    description: The port number for database connections  
  - name: username
    description: The master username for database access
  - name: password
    description: The auto-generated master password

연결 상세는 현재 스키마 전용 기능이에요. 대부분의 Provider는 아직 MRD에서 connectionDetails 필드를 채우지 않지만, 이 구조는 향후 구현을 위해 제공돼요.

MRD로 작업하기 (Working with MRDs)

MRD 보기 (Viewing MRDs)

클러스터의 모든 MRD 나열:

kubectl get managedresourcedefinitions

MRD 상세 보기:

kubectl describe mrd buckets.s3.aws.m.crossplane.io

MRD 상태 확인 (Checking MRD status)

MRD는 수명주기에 대한 상태 정보를 제공해요.

status:
  conditions:
  - type: Established
    status: "False"
    reason: InactiveManagedResource
    message: "ManagedResourceDefinition is inactive"

상태 조건:

Established: False, Reason: InactiveManagedResource — MRD가 비활성, CRD가 생성되지 않음
Established: Unknown, Reason: PendingManagedResource — Crossplane이 CRD를 생성 중
Established: True, Reason: EstablishedManagedResource — CRD가 존재하고 준비됨
Healthy: True, Reason: Running — MRD 컨트롤러가 동작 중
Healthy: Unknown, Reason: EncounteredErrors — MRD 컨트롤러에 문제 발생

MRD 수동 활성화 (Manually activating MRDs)

MRD의 상태를 변경해 수동으로 활성화할 수 있어요.

kubectl patch mrd buckets.s3.aws.m.crossplane.io --type='merge' \
  -p='{"spec":{"state":"Active"}}'

권장하는 방법은 체계적인 활성화를 위해 ManagedResourceActivationPolicies를 사용하는 것이에요.

Provider가 MRD와 협력하는 방식 (How providers work with MRDs)

Crossplane v2.0+ 는 Provider의 나이나 원래 형식과 관계없이 패키지 설치 중 모든 Provider CRD를 MRD로 자동 변환해요. Provider의 safe-start 능력이 기본 MRD 상태를 결정해요.

safe-start 능력이 있는 Providers

MRD가 기본적으로 state: Inactive로 시작
ManagedResourceActivationPolicies를 통한 선택적 활성화 지원
미사용 리소스의 리소스 오버헤드 감소
Provider가 모든 CRD가 활성화되지 않아도 시작 가능

# Provider package metadata
apiVersion: meta.pkg.crossplane.io/v1
kind: Provider
spec:
  capabilities:
  - safe-start

Crossplane은 능력에 퍼지 매칭(fuzzy matching)을 사용하므로 safe-start, safe_start, safestart, SafeStart 모두 safe-start 능력과 일치해요.

safe-start 능력이 없는 Providers

MRD가 기본적으로 state: Active로 시작 (레거시 동작)
하위 호환성을 위해 모든 CRD가 사용 가능해짐
전통적인 Provider와 같은 전체 리소스 오버헤드

MRD 문제 해결 (Troubleshooting MRDs)

MRD는 존재하지만 CRD가 나타나지 않음

증상: MRD는 있지만 kubectl get이 "no resources found"를 표시.

원인: MRD가 Inactive 상태

해결책: ManagedResourceActivationPolicy를 사용하거나 상태를 수동으로 패치해 MRD를 활성화

# Check MRD state
kubectl get mrd  -o jsonpath='{.spec.state}'

# Activate if needed
kubectl patch mrd  --type='merge' -p='{"spec":{"state":"Active"}}'

MRD 활성화 실패

증상: MRD 상태가 Active인데 Established 조건이 False로 남음

원인: 스키마 문제나 충돌로 CRD 생성 실패

해결책: MRD 이벤트와 상태에서 오류 상세 확인

kubectl describe mrd

문제 해결을 위한 다른 상태 조건:

Established: False, Reason: BlockedManagedResourceActivationPolicy — 활성화 정책 문제로 차단됨
Established: False, Reason: TerminatingManagedResource — Crossplane이 MRD를 삭제 중

볼 수 있는 일반적인 이벤트:

Normal CreateCustomResourceDefinition — CRD 생성 성공
Normal UpdateCustomResourceDefinition — CRD 업데이트 성공
Warning CreateCustomResourceDefinition — CRD 생성 실패
Warning UpdateCustomResourceDefinition — CRD 업데이트 실패
Warning Reconcile — 일반 리컨사일 오류

일반적인 문제:

MRD의 잘못된 OpenAPI 스키마
기존 리소스와 CRD 이름 충돌
Crossplane의 부족한 RBAC 권한

Provider가 활성화를 지원하지 않음

증상: Provider가 MRD 상태와 무관하게 모든 컨트롤러를 시작

원인: Provider가 후기 활성화(late activation) 지원을 구현하지 않음

해결책: Provider 능력을 확인하고 호환되는 Provider 버전 사용

# Check if provider supports late activation
kubectl get providerrevision  \
  -o jsonpath='{.status.capabilities}'

safe-start 능력을 찾아보세요.

다음 단계 (Next steps)

체계적인 리소스 활성화를 위한 ManagedResourceActivationPolicies 알아보기
실용적 구현을 위한 disabling unused managed resources 가이드 보기
완전한 MRD 스키마 문서를 위한 API reference 확인

관리 리소스 정의