컴포지트 리소스
컴포지트 리소스 (Composite Resources / XR)
컴포지트 리소스(composite resource, XR)는 여러 Kubernetes 리소스의 집합을 하나의 Kubernetes 객체로 표현한 것이에요. 사용자가 CompositeResourceDefinition에 정의된 커스텀 API에 접근하면 Crossplane이 컴포지트 리소스를 만들어요.
출처: 문서
본문
컴포지트 리소스는 Kubernetes 리소스들의 컴포지트(복합체)예요. Composition은 그 리소스들을 어떻게 조합할지 정의해요.
XR, XRD, Composition이 뭘까요? 컴포지트 리소스(XR)는 커스텀 API예요. 새 커스텀 API를 만들려면 두 가지 Crossplane 타입을 사용해요.
- Composite Resource Definition (XRD) — XR의 스키마를 정의해요.
- Composition — XR이 다른 리소스를 어떻게 생성하는지 구성해요.
컴포지트 리소스 만들기 (Create composite resources)
컴포지트 리소스를 만들려면 Composition과 CompositeResourceDefinition(XRD)이 필요해요. Composition은 만들 리소스 집합을 정의하고, XRD는 사용자가 그 리소스 집합을 요청할 때 호출하는 커스텀 API를 정의해요.
flowchart TD
user(["User"])
xr("Composite Resource (XR)")
xrd("Composite Resource Definition (XRD)")
comp("Composition")
cda("Composed Resource A")
cdb("Composed Resource B")
cdc("Composed Resource C")
xrd -.defines.-> xr
comp [email protected]> xr
user --creates--> xr
xr compose-a@--composes-->cda
xr compose-b@--composes-->cdb
xr compose-c@--composes-->cdc
XRD는 컴포지트 리소스를 만드는 데 쓰는 API를 정의해요. 예를 들어 이 CompositeResourceDefinition은 mydatabases.example.org라는 커스텀 API 엔드포인트를 만들어요.
apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
name: mydatabases.example.org
spec:
group: example.org
names:
kind: MyDatabase
plural: mydatabases
# Removed for brevity
사용자가 커스텀 API mydatabases.example.org를 호출하면, Crossplane은 Composition의 compositeTypeRef를 바탕으로 사용할 Composition을 고르게 돼요.
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: my-composition
spec:
compositeTypeRef:
apiVersion: example.org/v1alpha1
kind: MyDatabase
# Removed for brevity
Composition의 compositeTypeRef는 XRD의 group과 kind를 일치시켜요. Crossplane은 일치하는 Composition에 정의된 리소스를 만들고, 그것들을 하나의 composite 리소스로 표현해요.
kubectl get composite
NAME SYNCED READY COMPOSITION AGE
my-composite-resource True True my-composition 4s
Composition 선택 (Composition selection)
컴포지트 리소스가 사용할 특정 Composition을 compositionRef로 선택할 수 있어요.
선택한 Composition은
compositeTypeRef로 컴포지트 리소스가 사용할 수 있도록 허용되어 있어야 해요.compositeTypeRef필드에 대한 자세한 내용은 Composition 문서의 Enable Composite Resources 섹션을 읽어보세요.
apiVersion: example.org/v1alpha1
kind: MyDatabase
metadata:
namespace: default
name: my-composite-resource
spec:
crossplane:
compositionRef:
name: my-other-composition
# Removed for brevity
컴포지트 리소스는 정확한 이름 대신 라벨 기반으로 Composition을 선택할 수도 있는데, compositionSelector를 사용해요. matchLabels 섹션 안에 일치시킬 Composition 라벨을 하나 이상 제공해요.
apiVersion: example.org/v1alpha1
kind: MyDatabase
metadata:
namespace: default
name: my-composite-resource
spec:
crossplane:
compositionSelector:
matchLabels:
environment: production
# Removed for brevity
Composition 리비전 정책 (Composition revision policy)
Crossplane은 Composition의 변경을 Composition revisions로 추적해요. 컴포지트 리소스는 compositionUpdatePolicy를 사용해 더 새로운 Composition 리비전을 수동 또는 자동으로 참조할 수 있어요.
기본 compositionUpdatePolicy는 Automatic이에요. 컴포지트 리소스는 자동으로 최신 Composition 리비전을 사용해요. Manual로 변경하면 컴포지트 리소스가 자동으로 업그레이드되지 않게 할 수 있어요.
apiVersion: example.org/v1alpha1
kind: MyDatabase
metadata:
namespace: default
name: my-composite-resource
spec:
crossplane:
compositionUpdatePolicy: Manual
# Removed for brevity
Composition 리비전 선택 (Composition revision selection)
Crossplane은 Composition의 변경을 Composition revisions로 기록해요. 컴포지트 리소스는 특정 Composition 리비전을 선택할 수 있어요.
compositionRevisionRef로 이름으로 특정 Composition 리비전을 선택해요. 예를 들어 원하는 Composition 리비전의 이름을 사용해요.
apiVersion: example.org/v1alpha1
kind: MyDatabase
metadata:
namespace: default
name: my-composite-resource
spec:
crossplane:
compositionUpdatePolicy: Manual
compositionRevisionRef:
name: my-composition-b5aa1eb
# Removed for brevity
Composition 리비전 이름은 kubectl get compositionrevision으로 찾을 수 있어요.
kubectl get compositionrevision
NAME REVISION XR-KIND XR-APIVERSION AGE
my-composition-5c976ad 1 mydatabases example.org/v1alpha1 65m
my-composition-b5aa1eb 2 mydatabases example.org/v1alpha1 64m
컴포지트 리소스는 정확한 이름 대신 라벨 기반으로 Composition 리비전을 선택할 수도 있는데, compositionRevisionSelector를 사용해요. matchLabels 섹션 안에 일치시킬 Composition 리비전 라벨을 하나 이상 제공해요.
apiVersion: example.org/v1alpha1
kind: MyDatabase
metadata:
namespace: default
name: my-composite-resource
spec:
crossplane:
compositionRevisionSelector:
matchLabels:
channel: dev
# Removed for brevity
컴포지트 리소스 일시 중지 (Pausing composite resources)
Crossplane은 컴포지트 리소스 일시 중지를 지원해요. 일시 중지된 컴포지트 리소스는 외부 리소스를 확인하거나 변경하지 않아요. crossplane.io/paused 어노테이션을 적용하면 컴포지트 리소스를 일시 중지할 수 있어요.
apiVersion: example.org/v1alpha1
kind: MyDatabase
metadata:
namespace: default
name: my-composite-resource
annotations:
crossplane.io/paused: "true"
spec:
# Removed for brevity
리소스별 폴링 주기 (Per-resource poll interval)
crossplane.io/poll-interval 어노테이션은 특정 컴포지트 리소스의 기본 --poll-interval을 재정의해요. 이 어노테이션은 유효한 Go duration 문자열을 허용해요.
apiVersion: example.org/v1alpha1
kind: MyDatabase
metadata:
namespace: default
name: my-composite-resource
annotations:
crossplane.io/poll-interval: "24h"
spec:
# Removed for brevity
동작과 검증에 대한 자세한 내용은 관리 리소스 폴링 주기 어노테이션 문서를 읽어보세요.
즉시 리컨사일 촉발 (Triggering immediate reconciliation)
crossplane.io/reconcile-requested-at 어노테이션은 값이 변경될 때 즉시 리컨사일을 촉발해요. 타임스탬프 같은 어떤 값으로든 어노테이션을 설정하면 리컨사일이 촉발돼요.
apiVersion: example.org/v1alpha1
kind: MyDatabase
metadata:
namespace: default
name: my-composite-resource
annotations:
crossplane.io/reconcile-requested-at: "2024-01-15T10:30:00Z"
spec:
# Removed for brevity
리컨사일러는 처리된 토큰을 status.lastHandledReconcileAt에 기록해요. 자세한 내용은 관리 리소스 리컨사일 요청 어노테이션 문서를 읽어보세요.
컴포지트 리소스 검증 (Verify composite resources)
kubectl get composite로 Crossplane이 만든 모든 컴포지트 리소스를 볼 수 있어요.
kubectl get composite
NAME SYNCED READY COMPOSITION AGE
my-composite-resource True True my-composition 4s
특정 커스텀 API 엔드포인트의 리소스만 보려면 그 API로 kubectl get을 해요.
kubectl get mydatabases
NAME SYNCED READY COMPOSITION AGE
my-composite-resource True True my-composition 12m
kubectl describe composite로 연결된 Composition Ref와 Resource Refs에 생성된 고유 리소스들을 볼 수 있어요.
kubectl describe composite my-composite-resource
Name: my-composite-resource
Namespace: default
API Version: example.org/v1alpha1
Kind: MyDatabase
Spec:
Composition Ref:
Name: my-composition
Composition Revision Ref:
Name: my-composition-cf2d3a7
Composition Update Policy: Automatic
Resource Refs:
API Version: s3.aws.m.upbound.io/v1beta1
Kind: Bucket
Name: my-composite-resource-fmrks
API Version: dynamodb.aws.m.upbound.io/v1beta1
Kind: Table
Name: my-composite-resource-wnr9t
# Removed for brevity
컴포지트 리소스 조건 (Composite resource conditions)
컴포지트 리소스에는 Synced와 Ready 두 가지 상태 조건이 있어요.
- Crossplane은 컴포지트 리소스를 성공적으로 리컨사일할 수 있으면 Synced 조건을 True로 설정해요. 리컨사일할 수 없으면 Synced 조건에 오류를 보고해요.
- Crossplane은 컴포지트 리소스의 컴포지션 함수 파이프라인이 모든 컴포즈드 리소스가 준비됐다고 보고하면 Ready 조건을 True로 설정해요. 컴포즈드 리소스가 준비되지 않으면 Ready 조건에 그 사실을 보고해요.
컴포지트 리소스 라벨 (Composite resource labels)
Crossplane은 컴포즈드 리소스에 다른 Crossplane 컴포넌트와의 관계를 보여주는 라벨을 추가해요.
Crossplane은 모든 컴포즈드 리소스에 crossplane.io/composite 라벨을 추가해요. 이 라벨은 컴포지트의 이름과 일치해요. Crossplane은 컴포지트가 만든 모든 리소스에 컴포지트 라벨을 적용해, 리소스와 이를 소유한 컴포지트 리소스 사이에 참조를 만들어요.
kubectl describe mydatabase.example.org/my-database-x9rx9
Name: my-database2-x9rx9
Namespace: default
Labels: crossplane.io/composite=my-database-x9rx9