Configuration 패키지

원문 보기 위키 갱신 2026.10.03

Configuration 패키지 (Configuration Packages)

Configuration 패키지는 Compositions, Composite Resource Definitions, 그리고 필요한 Provider나 Functions를 포함하는 OCI 컨테이너 이미지입니다.

출처: 문서

본문

Configuration 패키지는 Crossplane 구성을 완전히 이식 가능하게(portable) 만듭니다.

⚠️ 중요: Crossplane Provider와 Functions도 Crossplane 패키지입니다.

이 문서는 Configuration 패키지를 설치하고 관리하는 방법을 설명합니다. Provider와 Functions 장에서는 패키지 사용에 대한 자세한 내용을 다룹니다.

Configuration 설치하기 (Install a configuration)

spec.package 값을 configuration 패키지의 위치로 설정한 Crossplane Configuration 객체로 Configuration을 설치합니다. 예를 들어 Getting Started Configuration을 설치하려면:

apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: configuration-quickstart
spec:
  package: xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0

💡 Tip: Crossplane은 태그 대신 이미지 다이제스트(digest)를 사용한 설치도 지원해, 결정적이고 반복 가능한 설치를 제공합니다.

apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: configuration-quickstart
spec:
  package: xpkg.crossplane.io/crossplane-contrib/configuration-quickstart@sha256:ef9795d146190637351a5c5848e0bab5e0c190fec7780f6c426fbffa0cb68358

Crossplane은 Configuration에 나열된 Compositions, Composite Resource Definitions, Providers를 설치합니다.

Helm으로 설치하기 (Install with Helm)

Crossplane은 초기 Crossplane 설치 중에 Crossplane Helm 차트로 Configurations를 설치하는 것을 지원합니다. helm install과 함께 --set configuration.packages 인자를 사용하세요.

예를 들어, Getting Started configuration을 설치하려면:

$ helm install crossplane \
crossplane-stable/crossplane \
--namespace crossplane-system \
--create-namespace \
--set configuration.packages='{xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0}'

오프라인으로 설치하기 (Install offline)

Crossplane 패키지를 오프라인으로 설치하려면 Harbor 같은 로컬 컨테이너 레지스트리가 필요합니다. Crossplane은 컨테이너 레지스트리에서만 패키지를 설치하는 것을 지원해요. Kubernetes 볼륨에서 직접 패키지를 설치하는 것은 지원하지 않습니다.

설치 옵션 (Installation options)

Configurations는 configuration 패키지 관련 설정을 바꾸는 여러 옵션을 지원합니다.

Configuration 리비전 (Configuration revisions)

기존 Configuration의 새 버전을 설치하면 Crossplane은 새 configuration revision을 생성합니다. kubectl get configurationrevisions로 configuration revisions를 확인하세요.

$ kubectl get configurationrevisions
NAME                            HEALTHY   REVISION   IMAGE                                             STATE      DEP-FOUND   DEP-INSTALLED   AGE
platform-ref-aws-1735d56cd88d   True      2          xpkg.crossplane.io/crossplane-contrib/platform-ref-aws:v0.5.0   Active     2           2               46s
platform-ref-aws-3ac761211893   True      1          xpkg.crossplane.io/crossplane-contrib/platform-ref-aws:v0.4.1   Inactive                               5m13s

한 번에 하나의 revision만 활성(Active) 상태입니다. 활성 revision이 Compositions와 Composite Resource Definitions를 포함한 사용 가능한 리소스를 결정합니다. 기본적으로 Crossplane은 Inactive revision을 하나만 유지합니다.

Configuration 패키지의 revisionHistoryLimit로 Crossplane이 유지하는 revision 수를 변경할 수 있어요. revisionHistoryLimit 필드는 정수이며 기본값은 1입니다. revisionHistoryLimit를 0으로 설정하면 revision을 저장하지 않습니다. 예를 들어 기본 설정을 변경해 10개의 revision을 저장하려면 revisionHistoryLimit: 10을 사용하세요.

apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: platform-ref-aws
spec:
  revisionHistoryLimit: 10
# Removed for brevity

Configuration 패키지 pull 정책 (Configuration package pull policy)

packagePullPolicy로 Crossplane이 Configuration 패키지를 언제 로컬 Crossplane 패키지 캐시로 다운로드할지 정의할 수 있습니다.

packagePullPolicy 옵션:

IfNotPresent - (기본값) 패키지가 캐시에 없을 때만 다운로드.
Always - 매분 새 패키지를 확인하고 캐시에 없는 일치하는 패키지를 다운로드.
Never - 패키지를 다운로드하지 않음. 로컬 패키지 캐시에서만 설치.

💡 Tip: Crossplane packagePullPolicy는 Kubernetes 컨테이너 이미지 pull policy와 유사하게 동작합니다. Crossplane은 Kubernetes 이미지와 마찬가지로 태그와 패키지 다이제스트 해시 사용을 지원합니다.

예를 들어, 주어진 Configuration 패키지를 Always 다운로드하려면 packagePullPolicy: Always 구성을 사용하세요.

apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: platform-ref-aws
spec:
  packagePullPolicy: Always
# Removed for brevity

Revision 활성화 정책 (Revision activation policy)

Active 패키지 revision은 리소스를 적극적으로 조정하는 패키지 컨트롤러입니다. 기본적으로 Crossplane은 가장 최근에 설치된 패키지 revision을 Active로 설정합니다.

revisionActivationPolicy로 Configuration 업그레이드 동작을 제어하세요. 옵션:

Automatic - (기본값) 마지막에 설치된 configuration을 자동으로 활성화.
Manual - configuration을 자동으로 활성화하지 않음.

예를 들어, 수동 업그레이드를 요구하도록 업그레이드 동작을 변경하려면 revisionActivationPolicy: Manual을 사용하세요.

apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: platform-ref-aws
spec:
  revisionActivationPolicy: Manual
# Removed for brevity

프라이빗 레지스트리에서 Configuration 설치하기 (Install from a private registry)

Kubernetes가 프라이빗 레지스트리에서 이미지를 설치할 때 imagePullSecrets를 사용하는 것처럼, Crossplane은 프라이빗 레지스트리에서 Configuration 패키지를 설치할 때 packagePullSecrets를 사용합니다. Configuration 패키지를 다운로드할 때 인증에 사용할 Kubernetes secret을 제공하려면 packagePullSecrets를 사용하세요.

⚠️ 중요: Kubernetes secret은 Crossplane과 동일한 네임스페이스에 있어야 합니다.

packagePullSecrets는 secrets 목록입니다. 예를 들어, example-secret이라는 secret을 사용하려면 packagePullSecrets를 구성하세요.

apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: platform-ref-aws
spec:
  packagePullSecrets:
    - name: example-secret
# Removed for brevity

의존성 무시하기 (Ignore dependencies)

기본적으로 Crossplane은 Configuration 패키지에 나열된 모든 의존성을 설치합니다. skipDependencyResolution으로 Configuration 패키지의 의존성을 무시할 수 있습니다.

⚠️ 경고: 대부분의 Configurations는 필요한 Providers용 의존성을 포함합니다. Configuration이 의존성을 무시하면 필요한 Providers를 수동으로 설치해야 해요.

예를 들어, 의존성 구성을 비활성화하려면 skipDependencyResolution: true를 사용하세요.

apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: platform-ref-aws
spec:
  skipDependencyResolution: true
# Removed for brevity

의존성 버전 자동 업데이트 (Automatically update dependency versions)

Crossplane은 패키지의 의존성 버전을 모든 제약 조건을 만족하는 최소 유효 버전으로 자동 업그레이드할 수 있습니다. --enable-dependency-version-upgrades 플래그로 활성화해야 하는 alpha 기능입니다.

때로는 설치를 진행하기 위해 Crossplane이 의존성 버전 다운그레이드가 필요할 수 있습니다. 제어 플레인에 패키지 X를 >=v0.0.0 제약으로 의존하는 configuration A를 설치한다고 가정해 보세요. 이 경우 패키지 매니저는 패키지 X의 최신 버전(예: v3.0.0)을 설치합니다. 나중에 패키지 X를 <=v2.0.0으로 의존하는 configuration B를 설치하기로 결정하면, 패키지 매니저는 패키지 X를 v3.0.0에서 <=v2.0.0을 만족하는 최대 유효 버전으로 다운그레이드합니다.

자동 의존성 버전 다운그레이드를 활성화하려면 Helm 값으로 packageManager.enableAutomaticDependencyDowngrade=true라는 configuration 옵션이 있습니다. 패키지 다운그레이드는 예기치 않은 동작을 유발할 수 있으므로, Crossplane은 이 옵션을 기본적으로 비활성화합니다. 이 옵션을 활성화하면 패키지 매니저는 패키지의 의존성 버전을 제약 조건을 만족하는 최대 유효 버전으로 자동 다운그레이드합니다.

📝 참고: 이 configuration은 --enable-dependency-version-upgrades 플래그가 필요합니다. configuration options과 feature flags는 Crossplane Install 섹션에서 자세히 확인할 수 있어요.

⚠️ 중요: 자동 의존성 다운그레이드를 활성화하면 의도하지 않은 결과가 발생할 수 있습니다.

다운그레이드된 버전에 CRD가 없어, 조정할 컨트롤러 없이 고아가 된 MR이 남을 수 있음.

다운그레이드된 CRD 버전이 이전에 설정한 필드를 생략하면 데이터 손실이 발생할 수 있음.

CRD 저장(storage) 버전 변경으로 패키지 버전 업데이트가 방지될 수 있음.

Crossplane 버전 요구 사항 무시하기 (Ignore Crossplane version requirements)

Configuration 패키지는 설치 전에 특정 또는 최소 Crossplane 버전을 요구할 수 있습니다. 기본적으로 Crossplane은 버전이 요구 사항을 충족하지 않으면 Configuration을 설치하지 않습니다. ignoreCrossplaneConstraints로 요구 버전을 무시할 수 있습니다.

예를 들어, 지원되지 않는 Crossplane 버전에 Configuration 패키지를 설치하려면 ignoreCrossplaneConstraints: true를 구성하세요.

apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: platform-ref-aws
spec:
  ignoreCrossplaneConstraints: true
# Removed for brevity

Configuration 검증하기 (Verify a configuration)

kubectl get configuration로 Configuration을 검증합니다. 작동하는 configuration은 Installed와 Healthy를 True로 보고합니다.

$ kubectl get configuration
NAME               INSTALLED   HEALTHY   PACKAGE                                           AGE
platform-ref-aws   True        True      xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0   54s

의존성 관리하기 (Manage dependencies)

Configuration 패키지에는 Functions, Providers 또는 다른 Configurations를 포함한 다른 패키지에 대한 의존성이 포함될 수 있습니다. Crossplane이 Configuration의 의존성을 충족할 수 없으면 Configuration은 HEALTHY를 False로 보고합니다.

예를 들어, 이 Getting Started Configuration 설치의 HEALTHY는 False입니다.

$ kubectl get configuration
NAME               INSTALLED   HEALTHY   PACKAGE                                           AGE
platform-ref-aws   True        False     xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0   71s

Configuration이 왜 HEALTHY가 아닌지 더 자세한 정보를 보려면 kubectl describe configurationrevisions를 사용하세요.

$ kubectl describe configurationrevision
Name:         platform-ref-aws-a30ad655c769
API Version:  pkg.crossplane.io/v1
Kind:         ConfigurationRevision
# Removed for brevity
Spec:
  Desired State:                  Active
  Image:                          xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0
  Revision:                       1
Status:
  Conditions:
    Last Transition Time:  2023-10-06T20:08:14Z
    Reason:                UnhealthyPackageRevision
    Status:                False
    Type:                  Healthy
  Controller Ref:
    Name:
Events:
  Type     Reason       Age                From                                              Message
  ----     ------       ----               ----                                              -------
  Warning  LintPackage  29s (x2 over 29s)  packages/configurationrevision.pkg.crossplane.io  incompatible Crossplane version: package isn't compatible with Crossplane version (v1.12.0)

Events의 Warning 메시지는 현재 Crossplane 버전이 Configuration 패키지 요구 사항을 충족하지 않는다는 것을 보여줍니다.

Configuration 만들기 (Create a configuration)

Crossplane Configuration 패키지는 하나 이상의 YAML 파일을 포함하는 OCI 컨테이너 이미지입니다.

⚠️ 중요: Configuration 패키지는 완전히 OCI 호환입니다. OCI 이미지를 빌드하는 모든 도구가 Configuration 패키지를 빌드할 수 있어요.

Crossplane 패키지 빌드에 오류 검사와 포맷팅을 제공하는 Crossplane 명령줄 도구를 사용하는 것을 강력히 권장합니다. 타사 도구로 패키지를 빌드할 때 패키지 요구 사항은 Crossplane 패키지 사양을 참고하세요.

Configuration 패키지는 crossplane.yaml 파일을 요구하며 Composition과 CompositeResourceDefinition 파일을 포함할 수 있습니다.

crossplane.yaml 파일

Crossplane CLI로 Configuration 패키지를 빌드하려면 crossplane.yaml이라는 파일을 만드세요. crossplane.yaml 파일은 Configuration의 요구 사항과 이름을 정의합니다.

⚠️ 중요: Crossplane CLI는 crossplane.yaml이라는 이름의 파일만 지원합니다.

Configuration 패키지는 meta.pkg.crossplane.io Crossplane API 그룹을 사용합니다. dependsOn 목록에 다른 Configurations, Functions 또는 Providers를 지정하세요. 선택적으로 version 옵션으로 특정 또는 최소 패키지 버전을 요구할 수 있습니다. crossplane.version 옵션으로 이 Configuration에 대한 특정 또는 최소 Crossplane 버전을 정의할 수도 있습니다.

📝 참고: crossplane 객체나 요구 버전을 정의하는 것은 선택 사항입니다.

$ cat crossplane.yaml
apiVersion: meta.pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: test-configuration
spec:
  dependsOn:
    - apiVersion: pkg.crossplane.io/v1
      kind: Provider
      package: xpkg.crossplane.io/crossplane-contrib/provider-aws
      version: ">=v0.36.0"
  crossplane:
    version: ">=v1.12.1-0"

패키지 빌드하기 (Build the package)

Crossplane CLI 명령 crossplane xpkg build --package-root=로 패키지를 만듭니다. 여기서 <package-root>는 crossplane.yaml 파일과 어떤 Composition 또는 CompositeResourceDefinition YAML 파일이 들어 있는 디렉터리입니다. CLI는 디렉터리에서 .yml 또는 .yaml 파일을 재귀적으로 검색해 패키지에 포함합니다.

⚠️ 중요: 다른 YAML 파일은 --ignore=로 무시해야 합니다. 예를 들어, crossplane xpkg build --package-root=test-directory --ignore=".tmp/*"처럼 사용하세요. Compositions나 CompositeResourceDefinitions가 아닌 YAML 파일을 포함하는 것은 지원되지 않아요.

기본적으로 Crossplane은 Configuration 이름과 패키지 내용의 SHA-256 해시로 .xpkg 파일을 만듭니다. 예를 들어, test-configuration이라는 Configuration이 있다면 Crossplane CLI는 test-configuration-e8c244f6bf21.xpkg라는 패키지를 빌드합니다.

apiVersion: meta.pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: test-configuration
# Removed for brevity

--package-file=.xpkg 옵션으로 출력 파일을 지정하세요. 예를 들어, test-directory라는 디렉터리에서 패키지를 빌드하고 현재 작업 디렉터리에 test-package.xpkg라는 패키지를 생성하려면:

$ crossplane xpkg build --package-root=test-directory --package-file=test-package.xpkg

$ ls -1 ./
test-directory
test-package.xpkg

더 알아보기 (Learn more)

Provider 패키지 - Provider 설치와 관리
Composition - 리소스 합성 이해하기