Crossplane v1.x에서 v2로 업그레이드하기

Crossplane v2는 대부분의 v1 구성과 하위 호환성을 유지하면서 상당한 개선을 도입했어요. 이 가이드는 Crossplane v1.x에서 v2로 업그레이드하는 방법을 안내해요.

Crossplane v2의 새로운 기능(네임스페이스 스코프 리소스, 모든 Kubernetes 리소스 구성하기, 새로운 운영 워크플로)에 대해 알아보세요.

중요: Crossplane v2로는 마지막 v1.x 릴리스인 v1.20에서만 업그레이드하세요. 이전 버전을 실행 중이라면 먼저 v1.20으로 업그레이드하세요.

중요: Crossplane은 항상 한 번에 하나의 마이너 버전씩, 각각의 가장 최신 패치 버전을 사용해 업그레이드하세요.

예를 들어 v1.19에서 v2.1로 업그레이드하려면 먼저 v1.20, 그다음 v2.0으로 업그레이드한 후 마지막에 v2.1로 업그레이드해야 해요. 이 예시의 업그레이드 경로는 v1.19 → v1.20 → v2.0 → v2.1이에요.

참고: v1 클러스터 스코프 XR과 MR을 v2 네임스페이스 스타일로 마이그레이션하는 자동화된 도구는 아직 없어요. Crossplane v2로 업그레이드하고 새로운 네임스페이스 스코프 기능을 바로 사용할 수 있으며, 기존 v1 리소스는 변경 없이 계속 작동해요. 마이그레이션 도구 진행 상황은 crossplane/crossplane#6726을 참조하세요.

출처: 문서

본문

사전 요구 사항

업그레이드 전에 다음을 확인하세요:

• Crossplane v1.20 실행 중
• 더 이상 사용되지 않는 기능 미사용 (제거된 기능 참고)
• 모든 패키지가 완전한 이미지 이름을 사용
• Helm 버전 v3.2.0 이상

제거된 기능 (Removed features)

Crossplane v2는 다음의 폐기된 기능을 제거해요:

• 네이티브 패치 및 변환 컴포지션 (Native patch and transform composition)
• ControllerConfig 타입
• 외부 시크릿 저장소 (External secret stores)
• 복합 리소스 연결 세부정보 (Composite resource connection details)
• 기본 레지스트리 플래그 (Default registry flag)

팁: Crossplane CLI가 이 기능들을 찾아줄 수 있어요. v1.20 CLI로 컨트롤 플레인에 대해 crossplane beta upgrade check를 실행하면 아래의 모든 제거된 기능을 스캔하고 v2로 업그레이드 전에 주의가 필요한 리소스를 보고해요.

네이티브 패치 및 변환 컴포지션

• 폐기 시점: v1.17
• 대체: Composition Functions

Composition에서 spec.mode: Resources를 사용하고 있다면 업그레이드 전에 컴포지션 함수로 마이그레이션하세요.

마이그레이션 도움말: Crossplane v1.20 CLI를 사용해 Composition을 자동으로 변환하세요:

# Convert patch and transform to function pipelines
crossplane beta convert pipeline-composition old-composition.yaml -o new-composition.yaml

ControllerConfig 타입

• 폐기 시점: v1.11
• 대체: DeploymentRuntimeConfig

ControllerConfig 리소스를 DeploymentRuntimeConfig를 사용하도록 업데이트하세요.

마이그레이션 도움말: Crossplane v1.20 CLI를 사용해 ControllerConfig를 자동으로 변환하세요:

# Convert ControllerConfig to DeploymentRuntimeConfig
crossplane beta convert deployment-runtime controller-config.yaml -o deployment-runtime-config.yaml

외부 시크릿 저장소

• 상태: 알파 기능, 유지보수 안 됨

외부 시크릿 저장소를 사용한다면 업그레이드 전에 네이티브 Kubernetes 시크릿이나 External Secrets Operator로 마이그레이션하세요.

복합 리소스 연결 세부정보

• 제거됨: 복합 리소스는 더 이상 네이티브 연결 세부정보를 지원하지 않아요.

팁: 이것은 XR에만 영향을 주며 관리 리소스에는 영향을 주지 않아요.

관리 리소스(MR)는 모든 MR spec에서 writeConnectionSecretToRef 필드를 계속 지원해요.

연결 세부정보 컴포지션 가이드에 설명된 대로 직접 연결 세부정보 Secret을 구성해 이 기능을 재현할 수 있어요.

기본 레지스트리 플래그

• 제거됨: 기본 패키지 레지스트리용 --registry 플래그

이제 모든 패키지는 레지스트리 호스트 이름을 포함한 완전한 이름을 사용해야 해요. 패키지를 다음으로 확인하세요:

kubectl get pkg -o wide

업그레이드 전에 레지스트리 호스트 이름이 없는 패키지를 업데이트하세요. 예를 들어:

• ❌ crossplane-contrib/provider-aws-s3:v1.23.0
• ✅ xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.23.0

누가 업그레이드할 수 있나요 (Who can upgrade)

다음 기준을 충족하면 Crossplane v2로 업그레이드할 수 있어요:

• ✅ Crossplane v1.20 실행 중
• ✅ 네이티브 패치 및 변환 컴포지션 미사용
• ✅ ControllerConfig 리소스 미사용
• ✅ 외부 시크릿 저장소 미사용
• ✅ 모든 패키지가 완전한 이미지 이름을 사용

제거된 기능을 사용 중이라면 먼저 해당 기능에서 마이그레이션하세요.

업그레이드 접근법 (Upgrade approach)

권장 업그레이드 접근법:

• 업그레이드 준비
• Crossplane 코어 업그레이드
• 관리 리소스 활성화 정책 구성
• 프로바이더 업그레이드
• v2 기능 사용 시작

1. 업그레이드 준비

클러스터에서 제거된 기능을 검토하고 사용 중인 기능을 해결하세요. 각 제거된 기능 섹션에는 클러스터를 검사하는 명령과 리소스 변환을 돕는 마이그레이션 도구가 포함되어 있어요.

2. Crossplane 코어 업그레이드

Crossplane Helm 저장소를 추가하세요:

helm repo add crossplane-stable https://charts.crossplane.io/stable
helm repo update

Crossplane v2로 업그레이드하세요:

helm upgrade crossplane \
  --namespace crossplane-system \
  crossplane-stable/crossplane

업그레이드를 확인하세요:

kubectl get pods -n crossplane-system

3. 관리 리소스 활성화 정책 구성

Crossplane v2는 모든 관리 리소스(*)를 활성화하는 기본 MRAP을 자동으로 생성해요. v2 프로바이더를 설치하기 전에 클러스터 리소스 효율을 위해 이 정책을 선택적으로 커스터마이즈할 수 있어요.

사용 중인 관리 리소스를 확인하세요:

# See your managed resource types
kubectl get managed

선택적으로, 필요한 리소스만 활성화하는 대상 지정 MRAP으로 기본 MRAP을 교체하세요:

# Delete the default catch-all MRAP
kubectl delete mrap default

대상 지정 MRAP을 생성하세요:

apiVersion: apiextensions.crossplane.io/v1alpha1
kind: ManagedResourceActivationPolicy
metadata:
  name: my-resources
spec:
  activate:
  # Legacy cluster-scoped resources (existing v1 resources)
  - buckets.s3.aws.upbound.io
  - instances.ec2.aws.upbound.io

  # Modern namespaced resources (new v2 resources)
  - buckets.s3.aws.m.upbound.io
  - instances.ec2.aws.m.upbound.io

팁: s3.aws.upbound.io(레거시 클러스터 스코프)와 s3.aws.m.upbound.io(v2 네임스페이스 스코프)의 차이를 주목하세요. .m.은 모던 네임스페이스 스코프 관리 리소스를 나타내요.

4. 프로바이더 업그레이드

네임스페이스 스코프와 클러스터 스코프 관리 리소스를 모두 지원하는 버전으로 프로바이더를 업그레이드하세요:

# Check current provider versions
kubectl get providers

프로바이더 매니페스트를 v2 버전으로 업데이트하세요:

apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: crossplane-contrib-provider-aws-s3
spec:
  package: xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v2.0.0

참고: 프로바이더 v2 릴리스는 레거시 클러스터 스코프와 새로운 네임스페이스 스코프 관리 리소스를 모두 지원해요. 기존 클러스터 스코프 MR은 변경 없이 계속 작동해요.

5. v2 기능 사용 시작

업그레이드 후 Crossplane v2 기능을 사용하기 시작할 수 있어요:

• 네임스페이스 스코프 관리 리소스: 관리 리소스 시작 가이드 시도
• 컴포지션 함수: 컴포지션 시작 가이드 시도
• Operations: 운영 시작 가이드 탐색
• 관리 리소스 정의: MRD 가이드 참조

v2용 Composition 업데이트

기존 Composition은 최소한의 변경으로 Crossplane v2에서 작동해요. v2 관리 리소스는 v1 관리 리소스와 스키마적으로 동일해요. 다만 네임스페이스 스코프일 뿐이에요.

중요: 컨트롤 플레인에서 복합 리소스가 적극적으로 사용 중인 기존 Composition을 업데이트하지 마세요.

기존 XR이 사용 중인 라이브 Composition을 업데이트하면 리소스가 중단되거나 교체될 수 있어요. 아래 마이그레이션 접근법은 새 리소스용 새 Composition을 만들 때만 사용하세요.

Composition에서 v2 네임스페이스 스코프 관리 리소스를 사용하려면:

• API 그룹을 .crossplane.io에서 .m.crossplane.io로 업데이트
• API 버전 확인 - v2 네임스페이스 스코프 프로바이더는 종종 API 버전을 v1beta1로 리셋해요

예를 들어 provider-aws-s3:v2.0.0에는 두 개의 Bucket MR이 있어요:

• apiVersion: s3.aws.upbound.io/v1beta2 - 레거시, 클러스터 스코프
• apiVersion: s3.aws.m.upbound.io/v1beta1 - 네임스페이스 스코프

spec.forProvider와 status.atProvider 필드는 스키마적으로 동일해요.

팁: 사용 가능한 MR API 버전을 보려면 kubectl get mrds를 사용하세요.

참고: 모든 프로바이더가 .crossplane.io 도메인을 사용하지는 않아요. 예를 들어 provider-aws-s3는 역사적 이유로 .upbound.io 도메인을 사용해요. 네임스페이스 스코프 리소스의 일반적인 패턴은 기존 도메인에 .m을 추가하는 것이에요: ``은 m.이 되죠 (예: upbound.io → m.upbound.io, crossplane.io → m.crossplane.io).

이전 (v1 클러스터 스코프):

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: my-app
spec:
  compositeTypeRef:
    apiVersion: example.crossplane.io/v1
    kind: XBucket
  mode: Pipeline
  pipeline:
  - step: create-bucket
    functionRef:
      name: crossplane-contrib-function-go-templating
    input:
      apiVersion: gotemplating.fn.crossplane.io/v1beta1
      kind: GoTemplate
      source: Inline
      inline:
        template: |
          apiVersion: s3.aws.upbound.io/v1beta2
          kind: Bucket
          metadata:
            name: {{ .observed.composite.resource.metadata.name }}
          spec:
            forProvider:
              region: us-east-2

이후 (v2 네임스페이스 스코프):

apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: my-app
spec:
  compositeTypeRef:
    apiVersion: example.crossplane.io/v1
    kind: Bucket
  mode: Pipeline
  pipeline:
  - step: create-bucket
    functionRef:
      name: crossplane-contrib-function-go-templating
    input:
      apiVersion: gotemplating.fn.crossplane.io/v1beta1
      kind: GoTemplate
      source: Inline
      inline:
        template: |
          apiVersion: s3.aws.m.upbound.io/v1beta1  # Added .m, reset to v1beta1
          kind: Bucket
          metadata:
            name: {{ .observed.composite.resource.metadata.name }}
          spec:
            forProvider:
              region: us-east-2

팁: Composition에서의 네임스페이스 처리:

• 네임스페이스 스코프 XR: 템플릿에서 metadata.namespace를 지정하지 마세요. Crossplane은 템플릿 네임스페이스를 무시하고 XR의 네임스페이스를 사용해요.
• 모던 클러스터 스코프 XR (scope: Cluster): 어떤 네임스페이스의 리소스든 구성할 수 있어요. 대상 네임스페이스를 지정하려면 템플릿에 metadata.namespace를 포함하세요.
• 레거시 클러스터 스코프 XR (scope: LegacyCluster): 네임스페이스 스코프 리소스를 구성할 수 없어요.

레거시 리소스 동작 (Legacy resource behavior)

기존 v1 리소스는 Crossplane v2에서 계속 작동해요:

• 레거시 클러스터 스코프 XR: Claim 지원 계속 동작
• 레거시 클러스터 스코프 MR: 변경 없이 계속 작동
• 기존 Composition: 레거시 XR과 함께 계속 작동

이 리소스들은 내부적으로 LegacyCluster 스코프를 사용하며 완전한 하위 호환성을 유지해요.

예를 들어 기존 v1 스타일 XRD는 Claim과 함께 계속 작동해요:

apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
  name: xdatabases.example.crossplane.io
spec:
  # v1 XRDs default to LegacyCluster scope (shown explicitly)
  scope: LegacyCluster
  group: example.crossplane.io
  names:
    kind: XDatabase
    plural: xdatabases
  claimNames:
    kind: Database
    plural: databases
  # schema definition...

사용자는 이전과 동일하게 작동하는 Claim을 만들 수 있어요:

apiVersion: example.crossplane.io/v1
kind: Database
metadata:
  name: my-database
  namespace: production
spec:
  engine: postgres
  size: large

다음 단계 (Next steps)

업그레이드 후:

• 네임스페이스 스코프 리소스 탐색: 네임스페이스에서 XR과 MR 생성 시도
• 앱 Composition 구축: v2의 모든 Kubernetes 리소스 구성 능력 사용
• Operations 시도: 운영 워크플로 실험
• 마이그레이션 계획: 어떤 기존 리소스를 v2 패턴으로 마이그레이션할지 고려

v2의 새로운 점에 대해 더 읽고 업데이트된 컴포지션 문서를 탐색하세요.

더 알아보기 (Learn more)

• Crossplane 업그레이드하기
• Crossplane 릴리스 주기