Composition Revisions

이 가이드는 "Composition Revisions"를 사용해 Crossplane Composition의 변경을 만들고 롤백하는 방법을 설명해요. Crossplane과 Compositions에 대한 기본 지식을 가정해요.

출처: 문서

본문

Composition은 Crossplane이 Composite Resource(XR)를 어떻게 리컨사일해야 할지 구성해요. 다시 말해, XR을 만들면 선택된 Composition이 Crossplane이 어떤 리소스를 생성할지 결정해요.

예를 들어 조직의 공통 데이터베이스 구성인 Azure MySQL Server와 몇몇 방화벽 규칙을 나타내는 PlatformDB XR을 정의한다고 해볼게요. Composition은 MySQL 서버의 'base' 구성과 PlatformDB 구성이 확장하는 방화벽 규칙을 담고 있어요.

Composition은 그것을 사용하는 여러 XR과 연결돼요. 10개의 서로 다른 PlatformDB XR이 사용하는 big-platform-db라는 Composition을 정의할 수도 있어요. 셀프서비스 목적상 실제 PlatformDB XR과는 다른 팀이 Composition을 관리하는 경우가 흔해요. 예를 들어 플랫폼 팀 구성원이 Composition을 작성·유지하고, 개별 앱 팀이 그 Composition을 사용하는 PlatformDB XR을 만드는 식이에요.

각 Composition은 가변적(mutable)이에요 — 조직의 요구가 바뀌면 업데이트할 수 있어요. Composition Revisions 없이 Composition을 업데이트하는 것은 위험한 과정일 수 있어요. Crossplane은 Composition을 계속 사용해 실제 인프라(MySQL 서버와 방화벽 규칙)가 원하는 상태와 일치하도록 보장해요. 10개의 PlatformDB XR이 모두 big-platform-db Composition을 사용한다면, big-platform-db Composition을 업데이트하면 10개 XR 모두 즉시 업데이트돼요.

Composition Revisions는 XR이 자동 업데이트를 거부할 수 있게 해줘요. 대신 자신의 속도에 맞춰 XR을 최신 Composition 설정으로 업데이트할 수 있어요. 이를 통해 인프라 변경을 카나리(canary)로 진행하거나, 모든 XR을 롤백하지 않고 일부 XR만 이전 Composition 설정으로 롤백할 수 있어요.

Composition revisions 사용 (Using composition revisions)

Composition Revisions를 활성화하면 세 가지 일이 일어나요.

• Crossplane은 각 Composition 업데이트마다 CompositionRevision을 만들어요.
• Composite Resources는 어떤 CompositionRevision을 사용하는지 지정하는 spec.crossplane.compositionRevisionRef 필드를 갖게 돼요.
• Composite Resources는 Crossplane이 새 Composition Revision으로 업데이트하는 방식을 지정하는 spec.crossplane.compositionUpdatePolicy 필드를 갖게 돼요.

Composition을 편집할 때마다 Crossplane은 그 'revision'(고유한 상태)을 나타내는 CompositionRevision을 자동으로 만들어요. Crossplane은 각 리비전에 증가하는 리비전 번호를 할당해요. 이를 통해 CompositionRevision 사용자가 어떤 리비전이 '최신'인지 알 수 있어요.

kubectl로 어떤 리비전이 존재하는지 확인할 수 있어요.

# Find all revisions of the Composition named 'example'
kubectl get compositionrevision -l crossplane.io/composition-name=example

출력은 대략 다음과 같아요.

NAME              REVISION   AGE
example-18pdgs2   1          4m36s
example-2bgdr31   2          73s
example-xjrdmzz   3          61s

Composition은 시간이 지나면서 요구가 바뀌면 업데이트할 수 있는 가변 리소스예요. 각 CompositionRevision은 특정 시점의 그 요구를 담은 불변(immutable) 스냅샷이에요.

Composition Revisions를 활성화하든 안 하든 Crossplane은 기본적으로 같은 방식으로 동작해요. Composition Revisions를 활성화하면 모든 XR은 기본적으로 Automatic compositionUpdatePolicy를 사용해요. XR은 두 가지 업데이트 정책을 지원해요.

• Automatic — 최신 CompositionRevision을 자동으로 사용. (기본값)
• Manual — CompositionRevision 변경에 수동 개입 필요.

아래 XR은 Manual 정책을 사용해요. 이 정책을 사용하면 XR은 처음 생성될 때 최신 CompositionRevision을 선택하지만, 다른 CompositionRevision을 사용하려면 수동으로 업데이트해야 해요.

apiVersion: example.org/v1alpha1
kind: PlatformDB
metadata:
  namespace: default
  name: example
spec:
  storageGB: 20
  crossplane:
    # The Manual policy specifies that you don't want this XR to update to the
    # latest CompositionRevision automatically.
    compositionUpdatePolicy: Manual
    compositionRef:
      name: example

Crossplane은 선택한 compositionUpdatePolicy와 관계없이 XR의 compositionRevisionRef를 생성 시점에 자동으로 설정해요. Manual 정책을 선택하면 XR이 다른 CompositionRevision을 사용하길 원할 때 compositionRevisionRef 필드를 직접 편집해야 해요.

apiVersion: example.org/v1alpha1
kind: PlatformDB
metadata:
  namespace: default
  name: example
spec:
  storageGB: 20
  crossplane:
    compositionUpdatePolicy: Manual
    compositionRef:
      name: example
    # Update the referenced CompositionRevision if and when you are ready.
    compositionRevisionRef:
      name: example-18pdg

전체 예시 (Complete example)

이 튜토리얼은 CompositionRevisions가 어떻게 동작하는지, 그리고 Composite Resource(XR) 업데이트를 어떻게 관리하는지 설명해요. MyVPC 리소스를 정의하는 Composition과 CompositeResourceDefinition(XRD)으로 시작해, 여러 XR을 만들어 서로 다른 업그레이드 경로를 관찰해요. 컴포지션을 업데이트할 때마다 Crossplane은 컴포지트 리소스에 다른 CompositionRevisions를 할당해요.

준비 (Preparation)

컴포지션과 XRD 예시 배포 (Deploy composition and XRD examples)

예시 Composition을 적용해요.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  labels:
    channel: dev
  name: myvpcs.aws.example.upbound.io
spec:
  compositeTypeRef:
    apiVersion: aws.example.upbound.io/v1alpha1
    kind: MyVPC
  mode: Pipeline
  pipeline:
  - step: patch-and-transform
    functionRef:
      name: function-patch-and-transform
    input:
      apiVersion: pt.fn.crossplane.io/v1beta1
      kind: Resources
      resources:
      - name: my-vpc
        base:
          apiVersion: ec2.aws.m.upbound.io/v1beta1
          kind: VPC
          spec:
            forProvider:
              region: us-west-1
              cidrBlock: 192.168.0.0/16
              enableDnsSupport: true
              enableDnsHostnames: true

예시 XRD를 적용해요.

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: myvpcs.aws.example.upbound.io
spec:
  group: aws.example.upbound.io
  names:
    kind: MyVPC
    plural: myvpcs
  versions:
  - name: v1alpha1
    served: true
    referenceable: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              id:
                type: string
                description: ID of this VPC that other objects will use to refer to it.
            required:
            - id

Crossplane이 Composition revision을 만들었는지 확인해요.

kubectl get compositionrevisions -o="custom-columns=NAME:.metadata.name,REVISION:.spec.revision,CHANNEL:.metadata.labels.channel"

예상 출력:

NAME                                    REVISION   CHANNEL
myvpcs.aws.example.upbound.io-ad265bc   1          dev

dev 라벨은 Composition에서 자동으로 생성돼요.

컴포지트 리소스 만들기 (Create composite resources)

이 튜토리얼은 서로 다른 업데이트 정책과 컴포지션 선택 옵션을 다루기 위해 네 개의 컴포지트 리소스를 사용해요. 기본 동작은 XR을 Composition의 최신 리비전으로 업데이트하는 것이에요. XR에서 compositionUpdatePolicy: Manual을 설정해 변경할 수 있어요. compositionUpdatePolicy: Automatic과 함께 compositionRevisionSelector.matchLabels로 특정 라벨이 있는 최신 리비전을 선택할 수도 있어요.

기본 업데이트 정책 (Default update policy)

compositionUpdatePolicy가 정의되지 않은 XR을 만들어요. 업데이트 정책은 기본적으로 Automatic이에요.

apiVersion: aws.example.upbound.io/v1alpha1
kind: MyVPC
metadata:
  namespace: default
  name: vpc-auto
spec:
  id: vpc-auto

예상 출력:

myvpc.aws.example.upbound.io/vpc-auto created

수동 업데이트 정책 (Manual update policy)

compositionUpdatePolicy: Manual과 compositionRevisionRef가 있는 Composite Resource를 만들어요.

apiVersion: aws.example.upbound.io/v1alpha1
kind: MyVPC
metadata:
  namespace: default
  name: vpc-man
spec:
  id: vpc-man
  crossplane:
    compositionUpdatePolicy: Manual
    compositionRevisionRef:
      name: myvpcs.aws.example.upbound.io-ad265bc

예상 출력:

myvpc.aws.example.upbound.io/vpc-man created

셀렉터 사용 (Using a selector)

channel: dev의 compositionRevisionSelector가 있는 XR을 만들어요.

apiVersion: aws.example.upbound.io/v1alpha1
kind:  MyVPC
metadata:
  namespace: default
  name: vpc-dev
spec:
  id: vpc-dev
  crossplane:
    compositionRevisionSelector:
      matchLabels:
        channel: dev

예상 출력:

myvpc.aws.example.upbound.io/vpc-dev created

channel: staging의 compositionRevisionSelector가 있는 XR을 만들어요.

apiVersion: aws.example.upbound.io/v1alpha1
kind: MyVPC
metadata:
  namespace: default
  name: vpc-staging
spec:
  id: vpc-staging
  crossplane:
    compositionRevisionSelector:
      matchLabels:
        channel: staging

예상 출력:

myvpc.aws.example.upbound.io/vpc-staging created

channel: staging 라벨이 있는 Composite Resource에 REVISION이 없는지 확인해요. 다른 모든 XR은 생성된 Composition Revision과 일치하는 REVISION을 가져요.

kubectl get composite -o="custom-columns=NAME:.metadata.name,SYNCED:.status.conditions[0].status,REVISION:.spec.crossplane.compositionRevisionRef.name,POLICY:.spec.crossplane.compositionUpdatePolicy,MATCHLABEL:.spec.crossplane.compositionRevisionSelector.matchLabels"

예상 출력:

NAME          SYNCED   REVISION                                POLICY      MATCHLABEL
vpc-auto      True     myvpcs.aws.example.upbound.io-ad265bc   Automatic   
vpc-dev       True     myvpcs.aws.example.upbound.io-ad265bc   Automatic   map[channel:dev]
vpc-man       True     myvpcs.aws.example.upbound.io-ad265bc   Manual      
vpc-staging   False                                      Automatic   map[channel:staging]

vpc-staging XR 라벨은 기존 Composition Revisions와 일치하지 않아요.

새 Composition revisions 만들기 (Create new composition revisions)

Composition을 만들거나 업데이트하면 Crossplane은 새 CompositionRevision을 만들어요. 라벨과 어노테이션 변경도 새 CompositionRevision을 촉발해요.

컴포지션 라벨 업데이트 (Update the composition label)

Composition 라벨을 channel: staging으로 업데이트해요.

kubectl label composition myvpcs.aws.example.upbound.io channel=staging --overwrite

예상 출력:

composition.apiextensions.crossplane.io/myvpcs.aws.example.upbound.io labeled

Crossplane이 새 Composition revision을 만드는지 확인해요.

kubectl get compositionrevisions -o="custom-columns=NAME:.metadata.name,REVISION:.spec.revision,CHANNEL:.metadata.labels.channel"

예상 출력:

NAME                                    REVISION   CHANNEL
myvpcs.aws.example.upbound.io-727b3c8   2          staging
myvpcs.aws.example.upbound.io-ad265bc   1          dev

Crossplane이 Composite Resources vpc-auto와 vpc-staging을 Composite revision:2에 할당하는지 확인해요. XR vpc-man과 vpc-dev는 여전히 원래 revision:1에 할당돼 있어요.

kubectl get composite -o="custom-columns=NAME:.metadata.name,SYNCED:.status.conditions[0].status,REVISION:.spec.crossplane.compositionRevisionRef.name,POLICY:.spec.crossplane.compositionUpdatePolicy,MATCHLABEL:.spec.crossplane.compositionRevisionSelector.matchLabels"

예상 출력:

NAME          SYNCED   REVISION                                POLICY      MATCHLABEL
vpc-auto      True     myvpcs.aws.example.upbound.io-727b3c8   Automatic   
vpc-dev       True     myvpcs.aws.example.upbound.io-ad265bc   Automatic   map[channel:dev]
vpc-man       True     myvpcs.aws.example.upbound.io-ad265bc   Manual      
vpc-staging   True     myvpcs.aws.example.upbound.io-727b3c8   Automatic   map[channel:staging]

vpc-auto는 항상 최신 Revision을 사용해요. vpc-staging은 이제 revision:2에 적용된 라벨과 일치해요.

컴포지션 spec과 라벨 업데이트 (Update composition spec and label)

VPC에서 DNS 지원을 비활성화하고 라벨을 staging에서 dev로 다시 변경하도록 Composition을 업데이트해요.

Composition spec과 라벨을 업데이트하려면 다음 변경을 적용해요.

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  labels:
    channel: dev
  name: myvpcs.aws.example.upbound.io
spec:
  compositeTypeRef:
    apiVersion: aws.example.upbound.io/v1alpha1
    kind: MyVPC
  mode: Pipeline
  pipeline:
  - step: patch-and-transform
    functionRef:
      name: function-patch-and-transform
    input:
      apiVersion: pt.fn.crossplane.io/v1beta1
      kind: Resources
      resources:
      - name: my-vpc
        base:
          apiVersion: ec2.aws.m.upbound.io/v1beta1
          kind: VPC
          spec:
            forProvider:
              region: us-west-1
              cidrBlock: 192.168.0.0/16
              enableDnsSupport: false
              enableDnsHostnames: true

예상 출력:

composition.apiextensions.crossplane.io/myvpcs.aws.example.upbound.io configured

Crossplane이 새 Composition revision을 만드는지 확인해요.

kubectl get compositionrevisions -o="custom-columns=NAME:.metadata.name,REVISION:.spec.revision,CHANNEL:.metadata.labels.channel"

예상 출력:

NAME                                    REVISION   CHANNEL
myvpcs.aws.example.upbound.io-727b3c8   2          staging
myvpcs.aws.example.upbound.io-ad265bc   1          dev
myvpcs.aws.example.upbound.io-f81c553   3          dev

dev 채널에 새 변경을 배포하려면 라벨과 spec 값을 동시에 변경하는 것이 중요해요. Crossplane이 Composite Resources vpc-auto와 vpc-dev를 Composite revision:3에 할당하는지 확인해요. Crossplane은 vpc-staging을 revision:2에 할당하고, vpc-man은 여전히 원래 revision:1에 할당해요.

kubectl get composite -o="custom-columns=NAME:.metadata.name,SYNCED:.status.conditions[0].status,REVISION:.spec.crossplane.compositionRevisionRef.name,POLICY:.spec.crossplane.compositionUpdatePolicy,MATCHLABEL:.spec.crossplane.compositionRevisionSelector.matchLabels"

예상 출력:

NAME          SYNCED   REVISION                                POLICY      MATCHLABEL
vpc-auto      True     myvpcs.aws.example.upbound.io-f81c553   Automatic   
vpc-dev       True     myvpcs.aws.example.upbound.io-f81c553   Automatic   map[channel:dev]
vpc-man       True     myvpcs.aws.example.upbound.io-ad265bc   Manual      
vpc-staging   True     myvpcs.aws.example.upbound.io-727b3c8   Automatic   map[channel:staging]

vpc-dev는 revision:3에 적용된 업데이트된 라벨과 일치해요. vpc-staging은 revision:2에 적용된 라벨과 일치해요.

더 알아보기 (Learn more)

• Compositions
• Composite Resources (XR)
• Composite Resource Definitions (XRD)