Crossplane CLI 명령어 참조
Crossplane CLI 명령어 참조 (Command Reference)
이 문서는 crossplane CLI v2.5.0에 대한 참조 문서예요.
출처: 문서
본문
crossplane은 Crossplane과 상호작용하기 위한 명령줄 도구예요. 문제와 기능 요청은 https://github.com/crossplane/cli 에 보고해 주세요.
crossplane
사용법:
crossplane [flags]
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| -h | --help | 상황에 맞는 도움말 표시. |
| --config=PATH | crossplane CLI 구성 파일 경로. | |
| --verbose | 상세 로그 문구 출력. |
crossplane cluster
[BETA] Crossplane 클러스터를 검사해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
사용법:
crossplane cluster <하위명령> [flags]
crossplane cluster top
[BETA] Crossplane 관련 파드의 리소스(CPU/메모리) 사용량을 표시해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
cluster top 명령은 Crossplane 파드의 현재 리소스 사용량(CPU와 메모리)을 반환해요. kubectl top pods처럼 Metrics Server가 필요해요.
예시
crossplane-system 네임스페이스의 모든 Crossplane 파드 리소스 사용량 표시:
crossplane cluster top
default 네임스페이스의 모든 Crossplane 파드 리소스 사용량 표시:
crossplane cluster top -n default
결과 위에 모든 Crossplane 파드의 리소스 사용량 요약 추가:
crossplane cluster top -s
사용법:
crossplane cluster top [flags]
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| -s | --summary | 모든 Crossplane 파드의 요약 헤더 추가. |
| -n | --namespace="crossplane-system" | 특정 네임스페이스의 파드 표시. 기본값은 crossplane-system. |
| --as=STRING | 작업에 가장할(impersonate) 사용자 이름. 일반 사용자나 네임스페이스의 서비스 계정일 수 있음. | |
| --as-group=AS-GROUP | 작업에 가장할 그룹. 여러 그룹은 반복 지정. | |
| --as-uid=STRING | 작업에 가장할 UID. |
crossplane completions
셸(bash/zsh/fish) 완성(completion)을 생성해요. 이 명령을 source하면 로그인 셸에 대한 완성을 얻을 수 있어요. 예: source <(crossplane completions)
사용법:
crossplane completions [flags]
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| --uninstall | 완성 제거. |
crossplane composition
Crossplane Composition 작업을 해요.
사용법:
crossplane composition <하위명령> [flags]
crossplane composition convert
[BETA] Composition을 더 새로운 버전으로 변환해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
composition convert 명령은 Crossplane Composition을 다른 버전을 사용하거나 더 이상 지원되지 않는 기능에서 마이그레이션하도록 변환해요.
지원되는 변환:
- 네이티브 Compostion Environment → function-environment-configs
사용법:
crossplane composition convert <변환> <파일>
crossplane composition convert composition-environment
[BETA] Pipeline Composition을 function-environment-configs를 사용하도록 변환해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
composition convert composition-environment 명령은 Crossplane Composition이 네이티브 Compostion Environments(Croossplane 1.18에서 제거) 대신 function-environment-configs를 사용하도록 변환해요.
필요하면 crossplane-contrib/function-environment-configs를 사용하는 함수 파이프라인 단계를 추가해요. 기본적으로 함수 이름은 function-environment-configs이며 --function-environment-configs-ref로 재정의할 수 있어요.
예시
네이티브 Compostion Environment를 사용하는 기존 Pipeline 모드 Composition을 function-environment-configs로 변환:
crossplane composition convert composition-environment composition.yaml \
-o composition-environment.yaml
다른 functionRef를 사용하고 stdout으로 출력:
crossplane composition convert composition-environment composition.yaml \
--function-environment-configs-ref=local-function-environment-configs
stdin에서 Composition을 읽고 stdout으로 업데이트된 Composition 출력:
cat composition.yaml | crossplane composition convert composition-environment
사용법:
crossplane composition convert composition-environment [<파일>] [flags]
인수:
| 인수 | 설명 |
|---|---|
| [파일] | (선택) 변환할 Composition 파일 또는 stdin의 '-'. |
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| -o | --output-file=PATH | 생성된 Composition을 쓸 파일. 생략 시 stdout. |
| --function-environment-configs-ref="function-environment-configs" | 설치된 function-environment-configs Function의 이름. |
crossplane composition generate
[BETA] CompositeResourceDefinition(XRD)용 Composition을 생성해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
composition generate 명령은 CompositeResourceDefinition(XRD)용 Composition을 생성해요. 생성된 Composition은 function-auto-ready를 실행하는 단일 파이프라인 단계를 포함하며, 아직 없으면 이 함수가 프로젝트 의존성에 자동 추가돼요.
예시
XRD에서 Composition을 생성하고 프로젝트의 APIs 디렉터리 아래 XRD 옆에 저장:
crossplane composition generate apis/network/definition.yaml
커스텀 이름 접두사로 Composition 생성:
crossplane composition generate examples/network/network-aws.yaml --name aws
커스텀 복수형으로 Composition 생성 (자동 복수화가 틀릴 때 유용, 예: "postgres"):
crossplane composition generate examples/database/database.yaml --plural postgreses
생성된 Composition을 특정 경로에 작성:
crossplane composition generate apis/network/definition.yaml --path apis/network/composition.yaml
사용법:
crossplane composition generate <XRD경로> [flags]
인수:
| 인수 | 설명 |
|---|---|
| <XRD경로> | CompositeResourceDefinition(XRD) 파일 경로. |
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| --name=STRING | composition 이름 접두사. | |
| --plural=STRING | 참조된 kind의 커스텀 복수형. | |
| --path=STRING | 출력 파일. | |
| -f | --project-file="crossplane-project.yaml" | 프로젝트 정의 파일 경로. |
| --cache-dir=STRING | 캐시된 xpkg 패키지 내용 디렉터리. |
crossplane composition render
복합 리소스(XR)를 렌더링해요.
composition render 명령은 Composition이 어떤 리소스를 생성 또는 변경할지 보여줘요. 컴포지션을 로컬로 실행하고 결과를 출력하며, XR status의 변경사항도 출력해요. Crossplane 렌더 엔진을(Docker 컨테이너 또는 로컬 바이너리로) 실행해 실제 재조정기가 만들 것과 일치하는 고충실도 출력을 만들어요.
기본적으로 render는 XR의 status와 metadata.name만 출력해요. --include-full-xr(-x)를 사용하면 전체 XR spec과 metadata를 포함해요.
중요: 이 명령은 기본적으로 Docker를 사용해 컴포지션 함수와 Crossplane 렌더 엔진을 실행하므로 동작하는 Docker 설치가 필요해요. Docker 없이 렌더링하는 방법은 아래 함수 어노테이션과
--crossplane-binary옵션을 참고하세요.
함수 런타임 구성
기본적으로 render 명령은 Docker를 사용해 Compostion Functions를 풀고 실행해요. 각 Function에 다음 어노테이션을 추가해 실행 방식을 변경할 수 있어요:
| Annotation | 용도 |
|---|---|
| render.crossplane.io/runtime: "Development" | Docker 대신 로컬에서 실행 중인 Function에 연결. 예: 새 Function을 개발하거나 디버깅할 때. Function은 localhost:9443에서 수신 대기하고 --insecure 플래그로 실행해야 함. |
| render.crossplane.io/runtime-development-target: "dns:///example.org:7443" | localhost:9443이 아닌 곳에서 실행 중인 Function에 연결. 대상은 gRPC 대상 문법 사용 (예: dns:///example.org:7443 또는 example.org:7443). |
| render.crossplane.io/runtime-docker-cleanup: "Orphan" | 렌더링 후 Function의 Docker 컨테이너를 중지하지 않음. |
| render.crossplane.io/runtime-docker-name: "" | 주어진 이름으로 컨테이너를 생성하거나 재사용. 필요하면 컨테이너를 재시작. |
| render.crossplane.io/runtime-docker-pull-policy: "Always" | 로컬에 이미 있어도 Function의 패키지를 항상 풀. 다른 지원 값: Never, IfNotPresent. |
| render.crossplane.io/runtime-docker-publish-address: "0.0.0.0" | Docker가 Function 컨테이너 포트를 게시할 호스트 주소. 기본값 127.0.0.1 (localhost만). 0.0.0.0을 사용하면 모든 호스트 네트워크 인터페이스에 게시해 원격 머신에서 접근 가능. |
| render.crossplane.io/runtime-docker-target: "docker-host" | render CLI가 Function의 Docker 컨테이너에 연결할 주소. 미지정 시 publish 주소 사용. |
표준 DOCKER_HOST, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_TLS_VERIFY 환경 변수로 이 명령이 Docker 데몬에 연결하는 방식을 구성할 수 있어요. Docker 환경 변수 참조를 확인하세요.
프로젝트 지원
Crossplane Project( crossplane-project.yaml 프로젝트 메타데이터 파일이 있는 모든 디렉터리)에서 render를 실행할 때는 함수 파일 인수를 생략하고 프로젝트 메타데이터의 함수 의존성과 프로젝트의 내장 함수를 사용할 수 있어요.
함수 컨텍스트
--context-files와 --context-values 플래그는 각 Function의 context에 데이터를 전달해요. 컨텍스트는 JSON 형식 데이터예요.
함수 결과
Function이 상태를 가진 이벤트를 내보내면 --include-function-results(-r)를 사용해 렌더링된 리소스와 함께 출력하세요.
관측(모의) 리소스
--observed-resources(-o)는 모의 관리 리소스를 Function 파이프라인에 전달할 수 있게 해줘요. render는 이 입력을 Crossplane 클러스터에서 관측된 리소스처럼 취급하므로 Function이 이를 참조·조작할 수 있어요.
인수는 여러 리소스를 포함한 단일 YAML 파일이거나 YAML 파일 디렉터리일 수 있어요. 모의 리소스의 스키마는 검증되지 않으며 어떤 데이터도 포함할 수 있어요.
apiVersion: example.org/v1alpha1
kind: ComposedResource
metadata:
name: test-render-b
annotations:
crossplane.io/composition-resource-name: resource-b
spec:
coolerField: "I'm cooler!"
필수(추가) 리소스
필수 리소스는 Composition이 Composition의 일부가 아닌 클러스터의 Crossplane 객체를 요청할 수 있게 해줘요. --required-resources(-e)로 전달하며, 모의할 리소스의 YAML 파일 또는 YAML 파일 디렉터리예요. function-extra-resources 같은 Function이나 function-go-templating의 내장 지원과 함께 사용해요.
예시
새 XR 생성 시뮬레이션:
crossplane composition render xr.yaml composition.yaml functions.yaml
이미 존재하는 XR 업데이트 시뮬레이션:
crossplane composition render xr.yaml composition.yaml functions.yaml \
--observed-resources=existing-observed-resources.yaml
렌더링에 사용할 Crossplane 버전 고정:
crossplane composition render xr.yaml composition.yaml functions.yaml \
--crossplane-version=v2.3.0
Docker 대신 로컬 crossplane 바이너리 사용:
crossplane composition render xr.yaml composition.yaml functions.yaml \
--crossplane-binary=/usr/local/bin/crossplane
Function 파이프라인에 컨텍스트 값 전달:
crossplane composition render xr.yaml composition.yaml functions.yaml \
--context-values=apiextensions.crossplane.io/environment='{"key": "value"}'
파이프라인의 Function이 요청할 수 있는 필수 리소스 전달:
crossplane composition render xr.yaml composition.yaml functions.yaml \
--required-resources=required-resources.yaml
필요한 Function용 OpenAPI 스키마 전달:
crossplane composition render xr.yaml composition.yaml functions.yaml \
--required-schemas=schemas/
파이프라인의 Function에 자격 증명 전달:
crossplane composition render xr.yaml composition.yaml functions.yaml \
--function-credentials=credentials.yaml
원격 Docker 데몬용 함수 어노테이션 재정의:
DOCKER_HOST=tcp://192.168.1.100:2376 crossplane composition render xr.yaml composition.yaml functions.yaml \
-a render.crossplane.io/runtime-docker-publish-address=0.0.0.0 \
-a render.crossplane.io/runtime-docker-target=192.168.1.100
모든 함수를 개발 런타임으로 강제:
crossplane composition render xr.yaml composition.yaml functions.yaml \
-a render.crossplane.io/runtime=Development \
-a render.crossplane.io/runtime-development-target=localhost:9444
사용법:
crossplane composition render <XR> <Composition> [<functions>] [flags]
인수:
| 인수 | 설명 |
|---|---|
| 렌더링할 복합 리소스(XR)를 지정하는 YAML 파일. | |
| XR을 렌더링하는 데 사용할 Composition을 지정하는 YAML 파일. mode: Pipeline이어야 함. | |
| [functions] | (선택) XR 렌더링에 사용할 Compostion Functions를 지정하는 YAML 파일 또는 디렉터리. 프로젝트에서 실행할 때는 선택임. |
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| --crossplane-version=VERSION | 렌더링에 사용할 Crossplane 이미지 버전. 기본값은 최신 안정 버전. | |
| --crossplane-image=IMAGE | 렌더링용 전체 Crossplane Docker 이미지 참조 재정의. | |
| --crossplane-binary=PATH | Docker 대신 사용할 로컬 crossplane 바이너리 경로. | |
| --crossplane-docker-network=STRING | crossplane 컨테이너를 시작할 docker 네트워크. | |
| --context-files=KEY=VALUE;... | Function 파이프라인에 전달할 컨텍스트 키-값 쌍(쉼표 구분). 값은 JSON/YAML을 포함한 파일이어야 함. | |
| --context-values=KEY=VALUE;... | Function 파이프라인에 전달할 컨텍스트 키-값 쌍(쉼표 구분). 값은 JSON/YAML이어야 함. 키가 --context-files보다 우선. | |
| -r | --include-function-results | 렌더링된 출력에 kind: Result의 리소스로 Function의 정보/경고 메시지 포함. |
| -x | --include-full-xr | 렌더링된 출력에 입력 XR의 spec과 metadata 필드 직접 복사 포함. |
| -o | --observed-resources=PATH | 구성된 리소스의 관측 상태를 지정하는 YAML 파일 또는 디렉터리. |
| --extra-resources=PATH | 필수 리소스를 지정하는 YAML 파일 또는 디렉터리 (deprecated, --required-resources 사용). 인수를 반복해 여러 파일 지정. | |
| -e | --required-resources=PATH | Function 파이프라인에 전달할 필수 리소스를 지정하는 YAML 파일 또는 디렉터리. 인수를 반복해 여러 파일 지정. |
| -s | --required-schemas=DIR | OpenAPI v3 스키마( kubectl get --raw /openapi/v3/ 에서)를 지정하는 JSON 파일 디렉터리. |
| -c | --include-context | 렌더링된 출력에 kind: Context의 리소스로 컨텍스트 포함. |
| --function-credentials=PATH | XR 렌더링에 Function이 사용할 자격 증명을 지정하는 YAML 파일 또는 디렉터리. | |
| -a | --function-annotations=KEY=VALUE,... | 모든 함수의 함수 어노테이션 재정의. 인수를 반복해 여러 어노테이션 지정. |
| --cache-dir=STRING | 캐시된 xpkg 패키지 내용 디렉터리. | |
| --max-concurrency=8 | 내장 함수 빌드의 최대 동시성. | |
| -f | --project-file="crossplane-project.yaml" | 프로젝트 파일 경로. 선택. |
| --timeout=1m | 타임아웃까지 실행할 시간. | |
| --xrd=PATH | XR의 스키마와 속성을 정의하는 CompositeResourceDefinition(XRD)을 지정하는 YAML 파일. |
crossplane config
crossplane CLI 구성 파일을 보거나 업데이트해요.
config 명령은 crossplane CLI의 구성 파일을 관리해요. 구성 파일 위치는 우선순위 순서로:
- --config 플래그
- CROSSPLANE_CONFIG 환경 변수
- $XDG_CONFIG_HOME/crossplane/config.yaml (또는 ~/.config/crossplane/config.yaml)
예시
현재 유효 구성 표시:
crossplane config view
알파 명령 활성화:
crossplane config set features.enableAlpha true
생성된 Go 모델에 GetX/SetX 접근자 메서드 생성(기본 꺼짐) - 인터페이스와 제네릭으로 생성된 리소스에 도달 가능:
crossplane config set features.generateGoModelAccessors true
생성된 Go 모델에 runtime.Object 메서드와 패키지별 AddToScheme 헬퍼 생성(기본 꺼짐) - 생성된 타입을 runtime.Scheme에 등록 가능:
crossplane config set features.generateGoRuntimeObjects true
사용법:
crossplane config <하위명령> [flags]
crossplane config set
값을 설정하고 구성 파일에 기록해요.
사용법:
crossplane config set <키> <값>
인수:
| 인수 | 설명 |
|---|---|
| <키> | 설정할 키 (예: features.enableAlpha). |
| <값> | 지정할 값. |
crossplane config view
현재 유효 구성을 YAML로 출력해요.
사용법:
crossplane config view
crossplane dependency
[BETA] 컨트롤 플레인 Project의 의존성을 관리해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
사용법:
crossplane dependency <하위명령> [flags]
crossplane dependency add
[BETA] 현재 프로젝트에 의존성을 추가해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
dependency add 명령은 Crossplane Project 메타데이터 파일에 의존성을 추가하고 의존성 패키지의 CRD에 대한 언어 바인딩(스키마)을 생성해요.
의존성 유형
Project는 세 종류의 의존성을 지원해요:
- OCI 레지스트리의 Crossplane 패키지(xpkgs)
- HTTP(S) URL 또는 Git 저장소에서 가져온 임의의 CRD
- Kubernetes 코어 API
xpkg 의존성은 런타임 의존성(기본값) 또는 빌드 타임 의존성일 수 있어요. 런타임 의존성은 crossplane project build 또는 crossplane project run이 생성한 Configuration의 의존성이 되어 Configuraion과 함께 클러스터에 설치돼요. 빌드 타임 의존성은 스키마가 생성되지만 Configuration 의존성이 되지는 않아요. 빌드 타임 xpkg 의존성을 추가하려면 --api-only 플래그를 사용하세요.
비-xpkg 의존성은 항상 빌드 타임 의존성이에요.
예시
provider-aws-eks의 최신 세맨틱 버전을 조회해 CRD 스키마를 생성하고 런타임 의존성으로 프로젝트에 추가:
crossplane dependency add xpkg.crossplane.io/crossplane-contrib/provider-aws-eks
provider-gcp-storage의 v1.1.0보다 큰 최신 버전을 조회해 CRD 스키마를 생성하고 빌드 타임 전용 의존성으로 추가:
crossplane dependency add --api-only 'xpkg.crossplane.io/crossplane-contrib/provider-gcp-storage:>v1.1.0'
Kubernetes v1.33.0의 코어 리소스 스키마를 생성해 빌드 타임 의존성으로 추가:
crossplane dependency add k8s:v1.33.0
HTTP URL에서 특정 CRD 스키마를 생성해 빌드 타임 의존성으로 추가:
crossplane dependency add https://raw.githubusercontent.com/cert-manager/cert-manager/refs/heads/master/deploy/crds/cert-manager.io_certificaterequests.yaml
git 저장소의 특정 하위 디렉터리에서 CRD 스키마를 생성해 빌드 타임 의존성으로 추가:
crossplane dependency add https://github.com/kubernetes-sigs/cluster-api \
--git-ref=release-1.11 --git-path=config/crd/bases
사용법:
crossplane dependency add <패키지> [flags]
인수:
| 인수 | 설명 |
|---|---|
| <패키지> | 추가할 패키지 (xpkg OCI 참조, k8s:, git 저장소 URL, 또는 HTTP(S) URL). |
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| -f | --project-file="crossplane-project.yaml" | 프로젝트 정의 파일 경로. |
| --cache-dir=STRING | 캐시된 xpkg 패키지 내용 디렉터리. | |
| --api-only | xpkg 의존성을 API 전용(런타임 의존성 아님)으로 표시. | |
| --git-ref=STRING | CRD 의존성용 git ref (브랜치, 태그, 또는 커밋 SHA). | |
| --git-path=STRING | git 저장소의 CRD 경로. |
crossplane dependency clean-cache
[BETA] 의존성 캐시를 정리해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
clean-cache 명령은 로컬 캐시 디렉터리에서 캐시된 패키지 이미지를 모두 제거하고 생성된 스키마를 제거해요. 디스크 공간 확보, 스키마 재생성 강제, 손상된 캐시 항목 문제 해결에 도움이 돼요.
사용법:
crossplane dependency clean-cache [flags]
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| -f | --project-file="crossplane-project.yaml" | 프로젝트 정의 파일 경로. |
| --cache-dir=STRING | 캐시된 xpkg 패키지 내용 디렉터리. | |
| --keep-packages | 캐시된 xpkg 패키지 내용은 유지하고 생성된 스키마만 제거. |
crossplane dependency update-cache
[BETA] 현재 프로젝트의 의존성 캐시를 업데이트해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
dependency update-cache 명령은 현재 프로젝트의 로컬 의존성 캐시를 업데이트해요. 세맨틱 버전 제약을 특정 버전으로 재해석하고(가능하면 최신 버전을 가져와), 모든 의존성을 캐시하며, 필요하면 언어 바인딩(스키마)을 다시 생성해요.
사용법:
crossplane dependency update-cache [flags]
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| -f | --project-file="crossplane-project.yaml" | 프로젝트 정의 파일 경로. |
| --cache-dir=STRING | 캐시된 xpkg 패키지 내용 디렉터리. | |
| --git-token=STRING | git HTTPS 인증용 토큰. | |
| --git-username="x-access-token" | git HTTPS 인증용 사용자 이름. |
crossplane function
[BETA] 컨트롤 플레인 Project의 함수 작업을 해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
사용법:
crossplane function <하위명령> [flags]
crossplane function generate
[BETA] Composition용 Function을 생성해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
function generate 명령은 지정된 언어의 내장 함수를 프로젝트의 functions/ 디렉터리 아래에 생성해요. Composition 경로가 주어지면 idempotent하게 새 함수를 Composition 파이프라인의 끝에 추가해요.
지원 언어
--language / -l 플래그의 유효한 인수:
- go-templating (기본값)
- go
- kcl
- python
예시
functions/fn1에 기본 언어(go-templating)로 함수 생성:
crossplane function generate fn1
functions/fn2에 Python 함수 생성:
crossplane function generate fn2 --language python
functions/compose-cluster에 Go 함수를 생성해 주어진 Composition의 파이프라인 단계로 추가:
crossplane function generate compose-cluster apis/cluster/composition.yaml --language go
사용법:
crossplane function generate <이름> [<Composition경로>] [flags]
인수:
| 인수 | 설명 |
|---|---|
| <이름> | 생성할 함수의 이름. 유효한 DNS-1035 라벨이어야 함. |
| [Composition경로] | (선택) 파이프라인 단계를 추가할 Compostion YAML 파일 경로. |
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| -l | --language="go-templating" | 함수에 사용할 언어. |
| -f | --project-file="crossplane-project.yaml" | 프로젝트 정의 파일 경로. |
crossplane operation
[ALPHA] Crossplane Operation 작업을 해요.
참고: 알파 기능은 실험적이며 향후 릴리스에서 변경되거나 사라질 수 있어요.
사용법:
crossplane operation <하위명령> [flags]
crossplane operation render
[ALPHA] Operation을 렌더링해요.
참고: 알파 기능은 실험적이며 향후 릴리스에서 변경되거나 사라질 수 있어요.
operation render 명령은 Operation이 어떤 리소스를 생성 또는 변경할지 보여줘요. Operation을 로컬로 실행하고 결과를 출력해요. Crossplane 렌더 엔진을(Docker 컨테이너 또는 로컬 바이너리로) 실행해 실제 재조정기가 만들 것과 일치하는 고충실도 출력을 만들어요.
중요: 이 명령은 기본적으로 Docker를 사용해 Operation 함수와 Crossplane 렌더 엔진을 실행하므로 동작하는 Docker 설치가 필요해요. Docker 없이 렌더링하는 방법은 아래 함수 어노테이션과
--crossplane-binary옵션을 참고하세요.
함수 런타임 구성
기본적으로 render 명령은 Docker를 사용해 Operation Functions를 풀고 실행해요. 각 Function에 다음 어노테이션을 추가해 실행 방식을 변경할 수 있어요:
| Annotation | 용도 |
|---|---|
| render.crossplane.io/runtime: "Development" | Docker 대신 로컬에서 실행 중인 Function에 연결. 예: 새 Function을 개발하거나 디버깅할 때. Function은 localhost:9443에서 수신 대기하고 --insecure 플래그로 실행해야 함. |
| render.crossplane.io/runtime-development-target: "dns:///example.org:7443" | localhost:9443이 아닌 곳에서 실행 중인 Function에 연결. 대상은 gRPC 대상 문법 사용. |
| render.crossplane.io/runtime-docker-cleanup: "Orphan" | 렌더링 후 Function의 Docker 컨테이너를 중지하지 않음. |
| render.crossplane.io/runtime-docker-name: "" | 주어진 이름으로 컨테이너를 생성하거나 재사용. 필요하면 재시작. |
| render.crossplane.io/runtime-docker-pull-policy: "Always" | 로컬에 이미 있어도 항상 풀. 다른 지원 값: Never, IfNotPresent. |
| render.crossplane.io/runtime-docker-publish-address: "0.0.0.0" | Docker가 Function 컨테이너 포트를 게시할 호스트 주소. 기본 127.0.0.1. 0.0.0.0은 모든 호스트 네트워크 인터페이스에 게시. |
| render.crossplane.io/runtime-docker-target: "docker-host" | render CLI가 Function의 Docker 컨테이너에 연결할 주소. 미지정 시 publish 주소 사용. |
표준 DOCKER_HOST, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_TLS_VERIFY 환경 변수로 이 명령이 Docker 데몬에 연결하는 방식을 구성할 수 있어요.
프로젝트 지원
Crossplane Project에서 render를 실행할 때는 함수 파일 인수를 생략하고 프로젝트 메타데이터의 함수 의존성과 내장 함수를 사용할 수 있어요.
예시
Operation 렌더링:
crossplane operation render operation.yaml functions.yaml
렌더링에 사용할 Crossplane 버전 고정:
crossplane operation render operation.yaml functions.yaml \
--crossplane-version=v2.2.1
Docker 대신 로컬 crossplane 바이너리 사용:
crossplane operation render operation.yaml functions.yaml \
--crossplane-binary=/usr/local/bin/crossplane
함수 파이프라인에 컨텍스트 값 전달:
crossplane operation render operation.yaml functions.yaml \
--context-values=apiextensions.crossplane.io/environment='{"key": "value"}'
함수가 요청할 수 있는 필수 리소스 전달:
crossplane operation render operation.yaml functions.yaml \
--required-resources=required-resources.yaml
함수용 OpenAPI 스키마 전달:
crossplane operation render operation.yaml functions.yaml \
--required-schemas=schemas/
감시 리소스로 WatchOperation 렌더링:
crossplane operation render watchoperation.yaml functions.yaml \
--watched-resource=watched-configmap.yaml
함수에 자격 증명 전달:
crossplane operation render operation.yaml functions.yaml \
--function-credentials=credentials.yaml
출력에 함수 결과와 컨텍스트 포함:
crossplane operation render operation.yaml functions.yaml -r -c
원본 spec과 metadata로 전체 Operation 포함:
crossplane operation render operation.yaml functions.yaml -o
원격 Docker 데몬용 함수 어노테이션 재정의:
crossplane operation render operation.yaml functions.yaml \
-a render.crossplane.io/runtime-docker-publish-address=0.0.0.0 \
-a render.crossplane.io/runtime-docker-target=192.168.1.100
모든 함수에 커스텀 대상으로 개발 런타임 사용:
crossplane operation render operation.yaml functions.yaml \
-a render.crossplane.io/runtime=Development \
-a render.crossplane.io/runtime-development-target=localhost:9444
사용법:
crossplane operation render <Operation> [<functions>] [flags]
인수:
| 인수 | 설명 |
|---|---|
| 렌더링할 Operation을 지정하는 YAML 파일. | |
| [functions] | (선택) XR 렌더링에 사용할 Compostion Functions를 지정하는 YAML 파일 또는 디렉터리. 프로젝트에서 실행할 때는 선택임. |
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| --crossplane-version=VERSION | 렌더링에 사용할 Crossplane 이미지 버전. 기본값 최신 안정 버전. | |
| --crossplane-image=IMAGE | 렌더링용 전체 Crossplane Docker 이미지 참조 재정의. | |
| --crossplane-binary=PATH | Docker 대신 사용할 로컬 crossplane 바이너리 경로. | |
| --crossplane-docker-network=STRING | crossplane 컨테이너를 시작할 docker 네트워크. | |
| --context-files=KEY=VALUE;... | 함수 파이프라인에 전달할 컨텍스트 키-값 쌍(쉼표 구분). 값은 JSON을 포함한 파일이어야 함. | |
| --context-values=KEY=VALUE;... | 함수 파이프라인에 전달할 컨텍스트 키-값 쌍(쉼표 구분). 값은 JSON이어야 함. 키가 --context-files보다 우선. | |
| --function-credentials=PATH | 함수가 사용할 자격 증명을 지정하는 YAML 파일 또는 디렉터리. | |
| -a | --function-annotations=KEY=VALUE,... | 모든 함수의 함수 어노테이션 재정의. 반복 지정 가능. |
| -c | --include-context | 렌더링된 출력에 kind: Context의 리소스로 컨텍스트 포함. |
| -o | --include-full-operation | 렌더링된 출력에 입력 Operation의 spec과 metadata 직접 복사 포함. |
| -r | --include-function-results | 렌더링된 출력에 kind: Result의 리소스로 함수의 정보/경고 메시지 포함. |
| -e | --required-resources=PATH | 함수 파이프라인에 전달할 필수 리소스를 지정하는 YAML 파일 또는 디렉터리. 반복 지정 가능. |
| --required-schemas=DIR | 함수 파이프라인에 전달할 OpenAPI 스키마를 지정하는 JSON 파일 디렉터리. | |
| -w | --watched-resource=PATH | WatchOperation 렌더링용 감시 리소스를 지정하는 YAML 파일. 리소스는 필수 리소스에도 추가됨. |
| --cache-dir=STRING | 캐시된 xpkg 패키지 내용 디렉터리. | |
| --max-concurrency=8 | 내장 함수 빌드의 최대 동시성. | |
| -f | --project-file="crossplane-project.yaml" | 프로젝트 파일 경로. 선택. |
| --timeout=1m | 타임아웃까지 실행할 시간. |
crossplane project
[BETA] 컨트롤 플레인 Project 작업을 해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
사용법:
crossplane project <하위명령> [flags]
crossplane project build
[BETA] 프로젝트를 Crossplane 패키지로 빌드해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
project build 명령은 Crossplane Project를 xpkg 집합으로 빌드해요. 프로젝트의 각 내장 함수와 모든 것을 묶는 Configuraion 패키지를 빌드해요. 빌드 산출물은 모든 빌드된 패키지를 포함한 특별한 .xpkg 파일로, 프로젝트의 출력 디렉터리(기본 _output/)에 놓여요. project push 명령은 출력 파일의 패키지를 소비해 OCI 레지스트리에 푸시할 수 있어요.
build 명령은 crossplane-project.yaml의 spec.repository에서 빌드된 Configuraion의 저장소를 구성해요. 단일 빌드에 --repository로 재정의하세요.
중요: 저장소는 Composition의 내장 함수 참조에 사용되는 함수 이름에 영향을 미쳐요. 프로젝트를 빌드하고 푸시할 때 동일한 저장소를 지정해야 해요.
빌드는 crossplane dependency add와 crossplane dependency update-cache가 채운 의존성 캐시를 재사용해요. --cache-dir 또는 CROSSPLANE_XPKG_CACHE 환경 변수로 캐시 위치를 재정의하세요.
예시
현재 디렉터리의 프로젝트 빌드:
crossplane project build
저장소를 재정의해 프로젝트 빌드:
crossplane project build --repository=xpkg.crossplane.io/my-org/my-project
커스텀 출력 디렉터리로 프로젝트 빌드:
crossplane project build -o ./packages
사용법:
crossplane project build [flags]
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| -f | --project-file="crossplane-project.yaml" | 프로젝트 정의 경로. |
| --repository=STRING | 프로젝트 파일의 저장소 재정의. | |
| -o | --output-dir="_output" | 패키지용 출력 디렉터리. |
| --max-concurrency=8 | 최대 동시 함수 빌드 수. | |
| --cache-dir=STRING | 캐시된 xpkg 패키지 내용 디렉터리. |
crossplane project init
[BETA] 새 프로젝트를 초기화해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
project init 명령은 새 빈 Crossplane Project를 스캐폴딩해요. 최소한의 crossplane-project.yaml과 함께 DevEx 도구가 사용하는 표준 하위 디렉터리(apis, functions, examples, tests, operations)를 포함한 대상 디렉터리를 생성해요.
프로젝트 이름은 유효한 DNS-1035 라벨이어야 해요. 기본적으로 init 명령은 프로젝트 이름의 새 디렉터리를 생성해요. 다른 대상 디렉터리를 선택하려면 --directory(-d)를 사용하세요.
예시
./my-project/에 my-project라는 새 프로젝트 생성:
crossplane project init my-project
특정 디렉터리에 새 프로젝트 생성:
crossplane project init my-project --directory ./projects/new-project
사용법:
crossplane project init <이름> [flags]
인수:
| 인수 | 설명 |
|---|---|
| <이름> | 새 프로젝트의 이름. |
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| -d | --directory=STRING | 초기화할 디렉터리. 기본값은 프로젝트 이름. |
| -r | --registry="example.com/my-org" | 프로젝트 파일의 레지스트리 재정의. |
| --repository=STRING | 프로젝트 파일의 저장소 이름 재정의. 기본값은 프로젝트 이름. |
crossplane project push
[BETA] 빌드된 프로젝트를 OCI 레지스트리에 푸시해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
project push 명령은 crossplane project build가 생성한 xpkgs를 OCI 레지스트리에 푸시해요. 프로젝트에서 빌드한 Configuraion 패키지와 내장 함수 패키지를 모두 푸시해요. push 명령은 로컬 docker 구성의 레지스트리 자격 증명을 사용해요. 사설 레지스트리에 푸시하려면 먼저 docker login이 필요할 수 있어요.
기본적으로 명령은 crossplane-project.yaml에 지정된 저장소로 푸시하며 패키지 내용에서 생성된 태그를 사용해요. 둘 다 --repository와 --tag(-t)로 재정의할 수 있어요. 프로젝트의 기본 출력 대신 특정 패키지 파일을 푸시하려면 --package-file을 사용하세요.
중요: 저장소는 Composition의 내장 함수 참조에 사용되는 함수 이름에 영향을 미쳐요. 프로젝트를 빌드하고 푸시할 때 동일한 저장소를 지정해야 해요.
예시
저장소와 생성된 태그로 프로젝트 패키지 푸시:
crossplane project push
명시적 태그로 푸시:
crossplane project push --tag=v1.2.3
프로젝트 파일과 다른 저장소로 푸시:
crossplane project push --repository=xpkg.crossplane.io/my-org/my-project --tag=v1.2.3
사용법:
crossplane project push [flags]
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| -f | --project-file="crossplane-project.yaml" | 프로젝트 정의 경로. |
| --repository=STRING | 프로젝트 파일의 저장소 재정의. | |
| -t | --tag="" | 푸시할 패키지 태그. 기본값 시간 기반 semver 유사 태그. |
| --package-file=STRING | 푸시할 패키지 파일. 기본값 <저장소>/.xpkg. | |
| -o | --output-dir="_output" | 빌드된 패키지를 포함하는 디렉터리. |
| --max-concurrency=8 | 최대 동시 함수 푸시 수. | |
| --insecure-skip-tls-verify | [INSECURE] TLS 인증서 검증 건너뛰기. |
crossplane project run
[BETA] 프로젝트를 로컬 개발 컨트롤 플레인에서 빌드하고 실행해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
project run 명령은 Crossplane Project를 빌드하고 테스트용 로컬 개발 컨트롤 플레인에서 실행해요.
이 명령은:
- 프로젝트에 정의된 모든 내장 함수를 빌드
- KIND 클러스터에서 실행되는 로컬 개발 컨트롤 플레인과 패키지용 로컬 OCI 레지스트리를 생성(또는 재사용)
- 프로젝트 패키지를 로컬 OCI 레지스트리에 로드
- 컨트롤 플레인에 프로젝트 Configuraion 설치
- kubectl이 개발 컨트롤 플레인을 가리키도록 kubeconfig 업데이트
기본적으로 run은 프로젝트 이름으로 컨트롤 플레인 이름을 정해요. --control-plane-name으로 다른 이름을 선택할 수 있으며, 여러 프로젝트를 나란히 실행할 때 유용해요.
--crossplane-version 플래그를 지정하면 최신 안정 버전이 아닌 다른 Crossplane 버전을 사용할 수 있어요.
프로젝트 설치 주변에 적용할 리소스를 제공할 수 있어요:
--init-resources: Configuraion 설치 전에 하나 이상의 파일 적용 (ImageConfig 같은 것에 유용)--extra-resources: Configuraion과 그 의존성 설치 후 하나 이상의 파일 적용 (ProviderConfig 같은 것에 유용)
예시
기본 로컬 개발 컨트롤 플레인에서 프로젝트 빌드·실행:
crossplane project run
특정 이름의 컨트롤 플레인에서 실행 (없으면 생성):
crossplane project run --control-plane-name=my-dev-ctp
개발 컨트롤 플레인에 설치할 Crossplane 버전 고정:
crossplane project run --crossplane-version=v2.2.1
Configuraion 설치 전 imageconfig.yaml을, 후에 providerconfig.yaml 적용:
crossplane project run --init-resources=imageconfig.yaml --extra-resources=providerconfig.yaml
사용법:
crossplane project run [flags]
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| -f | --project-file="crossplane-project.yaml" | 프로젝트 정의 경로. |
| --repository=STRING | 저장소 재정의. | |
| --max-concurrency=8 | 최대 동시 빌드 수. | |
| --cache-dir=STRING | 캐시된 xpkg 패키지 내용 디렉터리. | |
| --control-plane-name=STRING | 개발 컨트롤 플레인 이름. 기본값 프로젝트 이름. | |
| --crossplane-version=STRING | 설치할 Crossplane 버전. | |
| --registry-dir=STRING | 로컬 레지스트리 이미지 디렉터리. | |
| --cluster-admin | Crossplane에 cluster-admin 역할 부여. | |
| --timeout=5m | 프로젝트 준비 대기 최대 시간. | |
| --init-resources=INIT-RESOURCES | 설치 전에 적용할 리소스. | |
| --extra-resources=EXTRA-RESOURCES | 설치 후에 적용할 리소스. |
crossplane project stop
[BETA] 로컬 개발 컨트롤 플레인을 내려요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
project stop 명령은 crossplane project run이 생성한 로컬 개발 컨트롤 플레인을 내려요. KIND 클러스터와 로컬 OCI 레지스트리를 모두 제거해요.
프로젝트 디렉터리에서 실행하면 stop 명령은 프로젝트 이름과 일치하는 컨트롤 플레인을 내려요. 프로젝트 디렉터리 밖에서 실행할 때는 --control-plane-name으로 내릴 컨트롤 플레인을 지정하세요. crossplane project run에 --registry-dir을 전달했다면 레지스트리 데이터를 정리하기 위해 crossplane project stop에도 전달하세요.
예시
현재 디렉터리 프로젝트의 개발 컨트롤 플레인 내리기:
crossplane project stop
이름으로 특정 로컬 개발 컨트롤 플레인 내리기:
crossplane project stop --control-plane-name=my-dev-cp
사용법:
crossplane project stop [flags]
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| -f | --project-file="crossplane-project.yaml" | 프로젝트 정의 경로. |
| --control-plane-name=STRING | 개발 컨트롤 플레인 이름. 기본값 프로젝트 이름. | |
| --registry-dir=STRING | 로컬 레지스트리 이미지 디렉터리. |
crossplane resource
[BETA] Crossplane 리소스 작업을 해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
사용법:
crossplane resource <하위명령> [flags]
crossplane resource trace
[BETA] 문제 해결을 위해 Crossplane 리소스를 추적해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
resource trace 명령은 Crossplane 리소스(Claim, Composite, 또는 Managed Resource)를 추적해 관계를 상세히 보여주고 Composition 문제 해결에 도움을 줘요.
이 명령은 리소스 유형과 리소스 이름이 필요해요:
crossplane resource trace <유형> <이름>
Kubernetes 스타일 / 입력도 동작해요: 예: crossplane resource trace example.crossplane.io/my-xr.
필요하면 kind를 TYPE[.VERSION][.GROUP] 형태로 더 지정할 수 있어요. 예: mykind.example.org 또는 mykind.v1alpha1.example.org.
기본적으로 crossplane resource trace는 ~/.kube/config의 Kubernetes 구성을 사용해요. KUBECONFIG 환경 변수로 재정의하세요.
출력 옵션
기본적으로 trace는 트리 형태로 터미널에 출력하며 Ready와 Status 메시지를 64자로 잘라요.
-o(--output)로 형식을 변경할 수 있어요: wide, json, yaml, 또는 dot(Graphviz 그래프).
wide 출력
--output=wide를 사용하면 64자를 넘어도 전체 Ready와 Status 메시지와 kind별 프린터 열을 출력해요.
Graphviz dot 출력
--output=dot을 사용해 텍스트 Graphviz dot 그래프를 출력해요. dot에 파이프해 이미지를 렌더링하세요:
crossplane resource trace cluster.aws.platformref.upbound.io platform-ref-aws -o dot | dot -Tpng -o graph.png
연결 시크릿 출력
--show-connection-secrets를 사용하면 다른 리소스와 함께 연결 시크릿 이름을 포함해요. 시크릿 값은 절대 출력되지 않아요. 출력에는 시크릿 이름과 네임스페이스가 포함돼요.
패키지 의존성 출력
--show-package-dependencies 플래그는 패키지 의존성 표시를 제어해요:
- unique (기본값): 필수 패키지를 한 번만 포함
- all: 같은 의존성을 필요로 하는 모든 패키지 표시
- none: 모든 패키지 의존성 숨김
패키지 리비전 출력
--show-package-revisions 플래그는 패키지 리비전 표시를 제어해요:
- active (기본값): 활성 리비전만 표시
- all: 비활성 리비전을 포함한 모든 리비전 표시
- none: 모든 리비전 숨김
예시
my-ns 네임스페이스의 my-res라는 MyKind 리소스 추적:
crossplane resource trace mykind my-res -n my-ns
my-ns 네임스페이스의 모든 MyKind 리소스 추적:
crossplane resource trace mykind -n my-ns
전체 오류, 조건 메시지, kind별 열이 있는 wide 형식:
crossplane resource trace mykind my-res -n my-ns -o wide
리소스와 함께 연결 시크릿 이름 표시:
crossplane resource trace mykind my-res -n my-ns --show-connection-secrets
Graphviz dot 그래프를 출력하고 dot에 파이프해 PNG 생성:
crossplane resource trace mykind my-res -n my-ns -o dot | dot -Tpng -o output.png
가져온 모든 리소스를 JSON으로 출력하고 jq에 파이프해 색상 적용:
crossplane resource trace mykind my-res -n my-ns -o json | jq
dot 그래프를 dot에 파이프하는 동안 디버그 로그를 stderr로 출력:
crossplane resource trace mykind my-res -n my-ns -o dot --verbose | dot -Tpng -o output.png
리소스를 삭제될 때까지 계속 감시:
crossplane resource trace mykind my-res -n my-ns --watch
사용법:
crossplane resource trace <kind> [<이름>] [flags]
인수:
| 인수 | 설명 |
|---|---|
| Crossplane 리소스의 kind, 'TYPE[.VERSION][.GROUP][/NAME]' 형식 허용. | |
| [이름] | (선택) 리소스 이름, 리소스에 포함되지 않았을 때. |
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| -c | --context="" | Kubernetes 컨텍스트. |
| -n | --namespace="" | 리소스 네임스페이스. |
| -o | --output="default" | 출력 형식: default, wide, json, dot, yaml 중 하나. |
| -s | --show-connection-secrets | 출력에 연결 시크릿 표시. |
| --show-package-dependencies="unique" | 출력에 패키지 의존성 표시: unique, all, none 중 하나. | |
| --show-package-revisions="active" | 출력에 패키지 리비전 표시: active, all, none 중 하나. | |
| --show-package-runtime-configs | 출력에 패키지 런타임 구성 표시. | |
| --concurrency=5 | 로드 동시성. | |
| -w | --watch | 리소스 삭제까지 변경 감시. |
| --as=STRING | 작업에 가장할 사용자 이름. | |
| --as-group=AS-GROUP | 작업에 가장할 그룹. 반복 지정 가능. | |
| --as-uid=STRING | 작업에 가장할 UID. |
crossplane resource validate
[BETA] Crossplane 리소스를 검증해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
resource validate 명령은 제공된 확장(XRD, CRD, Provider, Function, Configuraion)의 스키마에 대해 제공된 Crossplane 리소스를 검증해요. Kubernetes API 서버의 검증 라이브러리와 디버깅하기 어려운 Crossplane 문제의 흔한 원인인 미지의 필드 감지 같은 다른 검사를 사용해요.
validate 명령은 확장으로 제공된 Provider나 Configuraion을 다운로드하고 검증 전에 CRD를 로드해요. --cache-dir이 설정되지 않으면 ~/.crossplane/cache로 기본값이에요. --clean-cache로 스키마 다운로드 전에 캐시를 정리하세요.
모든 검증은 Crossplane 인스턴스나 컨트롤 플레인 없이 Kubernetes API 서버의 검증 라이브러리를 사용해 오프라인으로 이루어져요.
crossplane resource validate는 다음을 검증할 수 있어요:
- Provider 또는 XRD 스키마에 대한 관리 리소스 또는 복합 리소스
- crossplane composition render의 출력
- XRD의 Common Expression Language(CEL) 규칙
- 스키마 디렉터리에 대한 리소스
스키마에 대한 리소스 검증
Provider에 대해 검증할 때 명령은 Provider 패키지를 --cache-dir로 다운로드해요. validate가 Provider를 다운로드해 로컬에서 추출하므로 Kubernetes 클러스터나 Crossplane 파드 접근은 필요 없어요.
Provider 매니페스트 생성:
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: crossplane-contrib-provider-aws-iam
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-aws-iam:v2.0.0
검증할 관리 리소스 제공:
apiVersion: iam.aws.m.upbound.io/v1beta1
kind: AccessKey
metadata:
namespace: default
name: sample-access-key-0
spec:
forProvider:
userSelector:
matchLabels:
example-name: test-user-0
두 파일로 validate 실행:
crossplane resource validate provider.yaml managedResource.yaml
render 출력 검증
crossplane composition render의 출력을 validate에 파이프해 XR, Composition, Function을 포함한 완전한 Crossplane 리소스 파이프라인을 검증해요. render에 --include-full-xr을, validate에 -(stdin 읽기)를 사용하세요:
crossplane composition render xr.yaml composition.yaml func.yaml --include-full-xr | \
crossplane resource validate schemas.yaml -
Common Expression Language 규칙 검증
XRD는 x-kubernetes-validations를 통해 CEL로 검증 규칙을 정의할 수 있어요. validate는 이 규칙을 평가해요:
apiVersion: apiextensions.crossplane.io/v1
kind: CompositeResourceDefinition
metadata:
name: myxrs.example.crossplane.io
spec:
# ... versions[].schema.openAPIV3Schema:
# spec:
# x-kubernetes-validations:
# - rule: "self.minReplicas <= self.maxReplicas"
스키마 디렉터리에 대한 검증
validate는 검증에 사용할 스키마 YAML 파일 디렉터리도 받을 수 있어요. .yml 또는 .yaml 외의 확장자를 가진 파일은 무시해요.
schemas/
├── platform-ref-aws.yaml
├── providers/
│ └── provider-aws-iam.yaml
└── xrds/
└── xrd.yaml
crossplane resource validate schemas/ resources.yaml
예시
extensions.yaml의 확장에 대한 리소스 검증:
crossplane resource validate extensions.yaml resources.yaml
다른 디렉터리의 확장에 대한 디렉터리 리소스 검증:
crossplane resource validate crossplane.yaml,extensionsDir/ resourceDir/
검증 중 사용할 Crossplane 이미지 버전 고정:
crossplane resource validate extensions.yaml resources.yaml \
--crossplane-image=xpkg.crossplane.io/crossplane/crossplane:v1.20.0
성공 로그 줄 건너뛰기 (문제만 출력):
crossplane resource validate extensionsDir/ resourceDir/ --skip-success-results
jq, 스크립트, CI 시스템으로 파이프하기 위한 기계 판독 가능 결과(JSON 또는 YAML) 출력. 구조화된 페이로드는 리소스별 상태와 필드 수준 오류 세부정보를 포함해요:
crossplane resource validate extensionsDir/ resourceDir/ --output json | jq .
디렉터리의 확장에 대한 render 출력 검증:
crossplane composition render xr.yaml composition.yaml func.yaml --include-full-xr | \
crossplane resource validate extensionsDir/ -
커스텀 캐시 디렉터리 사용 및 스키마 다운로드 전 정리:
crossplane resource validate extensionsDir/ resourceDir/ --cache-dir .cache --clean-cache
사용법:
crossplane resource validate <확장출처> <리소스출처> [flags]
인수:
| 인수 | 설명 |
|---|---|
| <확장출처> | 파일, 디렉터리, 또는 표준 입력의 '-'의 쉼표 구분 목록. |
| <리소스출처> | 파일, 디렉터리, 또는 표준 입력의 '-'의 쉼표 구분 목록. |
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| --cache-dir="~/.crossplane/cache" | 다운로드된 스키마용 캐시 디렉터리의 절대 경로. | |
| --clean-cache | 패키지 스키마 다운로드 전에 캐시 디렉터리 정리. | |
| --crossplane-image="xpkg.crossplane.io/crossplane/crossplane:stable" | 내장 스키마 검증용 Crossplane 이미지 지정. | |
| --error-on-missing-schemas | 누락된 스키마가 있으면 0이 아닌 종료 코드 반환. | |
| -o | --output=text | 검증 결과 출력 형식 (text, json, yaml). |
| --skip-success-results | 성공 결과 출력 건너뛰기. | |
| --update-cache | 제약 조건을 만족하는 최신 버전을 다운로드해 캐시된 스키마 업데이트. 세맨틱 버전 제약을 쓰고 최신 버전을 얻고 싶을 때 유용하지만, 필요한 네트워크 호출 때문에 캐시 조회가 느려짐. |
crossplane version
현재 컨텍스트의 클라이언트와 서버 버전 정보를 출력해요.
사용법:
crossplane version [flags]
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| --client | true면 클라이언트 버전만 표시 (서버 불필요). | |
| --as=STRING | 작업에 가장할 사용자 이름. | |
| --as-group=AS-GROUP | 작업에 가장할 그룹. 반복 지정 가능. | |
| --as-uid=STRING | 작업에 가장할 UID. |
crossplane xpkg
Crossplane 패키지 작업을 해요.
Crossplane 패키지(xpkg)는 Crossplane 설치에 기능을 추가할 수 있게 해줘요. Crossplane은 Configuraion, Provider, Function 패키지를 지원해요.
패키지는 새 기능으로 Crossplane 컨트롤 플레인을 확장하는 데 필요한 모든 것을 담고 있는 의견 반영형(opinionated) OCI 이미지예요. 예를 들어 Provider 패키지를 설치하면 Crossplane이 새로운 종류의 관리 리소스(MR)를 지원하도록 확장돼요.
자세한 내용은 Crossplane 패키지 문서를 참조하세요.
사용법:
crossplane xpkg <하위명령> [flags]
crossplane xpkg batch
프로바이더 패키지 계열을 일괄 빌드하고 푸시해요.
사용법:
crossplane xpkg batch --family-base-image=STRING --provider-name=STRING --family-package-url-format=STRING [flags]
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| --family-base-image=STRING | 필수. 더 작은 프로바이더 패키지의 기반이 되는 계열 이미지. | |
| --provider-name=STRING | 필수. 더 작은 프로바이더 패키지 저장소용 프로바이더 이름 접두사(예: provider-aws). | |
| --family-package-url-format=STRING | 필수. 더 작은 프로바이더 패키지의 계열 패키지 URL 형식. '형식 지정자 %s'를 포함한 유효한 OCI 이미지 URL이어야 하며, -로 치환됨. | |
| --smaller-providers=monolith,... | 빌드·푸시할 더 작은 프로바이더 이름(예: ec2, eks, s3). | |
| --concurrency=0 | 동시 처리할 최대 패키지 수. 0은 제한 없음(모든 패키지 병렬 처리). | |
| --push-retry=3 | 프로바이더 패키지 푸시 실패 시 재시도 횟수. | |
| --platform=linux_amd64,linux_arm64,... | 패키지를 빌드할 플랫폼. 각 플랫폼은 _ 문법을 사용해야 함. 예: linux_arm64. | |
| -p | --provider-bin-root=STRING | 프로바이더 바이너리 경로 루트. 더 작은 프로바이더 바이너리는 이 폴더의 플랫폼 디렉터리 아래에 있어야 함. |
| -o | --output-dir=STRING | 패키지 출력 디렉터리 경로. |
| --store-packages=STORE-PACKAGES,... | --output-dir 옵션으로 지정한 패키지 출력 디렉터리 아래에 패키지가 있어야 하는 더 작은 프로바이더 이름. | |
| --package-metadata-template="./package/crossplane.yaml.tmpl" | 더 작은 프로바이더 메타데이터 템플릿. 템플릿 변수 {{ .Service }}와 {{ .Name }}은 항상 설정되며, --service-metadata와 --template-var로 선택 변수를 제공할 수 있음(후자가 키 충돌 시 우선). | |
| --template-var=KEY=VALUE;... | 지정된 템플릿용 더 작은 프로바이더 메타데이터 템플릿 변수. | |
| --service-metadata=STRING | 프로바이더별 템플릿 변수의 선택 YAML 파일. 최상위 키는 더 작은 프로바이더 이름(예: ec2, elb). 각 항목은 변수 이름에서 스칼라/목록으로의 맵이며, 값은 패키지 메타데이터 템플릿에 그대로 병합됨. 템플릿은 일반 헬퍼 toYAML과 indent를 사용할 수 있음. --template-var 전에 병합됨. | |
| --examples-group-override=KEY=VALUE;... | 더 작은 프로바이더의 예제 매니페스트 폴더 위치 재정의. | |
| --crd-group-override=KEY=VALUE;... | 더 작은 프로바이더의 CRD 폴더 위치 재정의. | |
| --package-repo-override=KEY=VALUE;... | 더 작은 프로바이더의 패키지 저장소 이름 재정의. | |
| -e | --examples-root="./examples" | 패키지 예제 디렉터리 경로. |
| --crd-root="./package/crds" | 패키지 CRD 디렉터리 경로. | |
| --ignore=IGNORE,... | 더 작은 프로바이더 패키지에서 제외할 경로. | |
| --build-only | 더 작은 프로바이더 패키지만 빌드하고 패키지 저장소에 푸시하지 않음. | |
| --provider-name-suffix-for-push=STRING | 푸시 시 프로바이더 이름에 추가할 접미사. 서비스 범위 이름 앞의 해당 프로바이더에 서비스 이름에 추가. 예: provider-family-aws-suffix, provider-aws-suffix-s3 |
crossplane xpkg build
새 패키지를 빌드해요.
xpkg build 명령은 로컬 파일 디렉터리에서 패키지 파일을 빌드해요. CLI가 YAML 파일 디렉터리를 결합해 Crossplane XPKG 스펙이 요구하는 어노테이션과 값을 적용하며 OCI 컨테이너 이미지로 패키징해요.
crossplane xpkg build는 Configuraion, Function, Provider 패키지 유형을 지원해요.
이 명령은 --package-root에서 .yml 또는 .yaml로 끝나는 파일을 재귀적으로 찾아 패키지로 결합하려 시도해요. 모든 YAML 파일은 apiVersion, kind, metadata, spec 필드가 있는 유효한 Kubernetes 매니페스트여야 해요.
파일 무시
--ignore를 사용해 빌드에서 제외할 glob의 쉼표 구분 목록을 제공하세요. 경로는 --package-root 기준이에요.
crossplane xpkg build --ignore="./test/*,kind-config.yaml"
패키지 이름 설정
기본적으로 build 명령은 metadata.name과 패키지 내용의 해시를 결합해 패키지 파일 이름을 구성하고 --package-root에 기록해요. --package-file(-o)로 위치와 파일 이름을 재정의하세요:
crossplane xpkg build -o /home/crossplane/example.xpkg
예제 포함
--examples-root(-e)로 패키지 사용법을 보여주는 YAML 파일을 포함하세요. 기본값은 ./examples이에요.
런타임 이미지 포함
Function과 Provider 패키지는 컨트롤러 컨테이너 이미지를 내장해요. Configuraion 패키지에는 런타임 이미지가 없어요.
참고:
--embed-runtime-image로 참조하는 이미지는 로컬 Docker 캐시에 있어야 해요.docker pull로 누락된 이미지를 다운로드하세요.
--embed-runtime-image-tarball을 사용하면 Docker 캐시의 이미지 대신 로컬 OCI 이미지 타르볼을 내장할 수 있어요.
예시
'package' 디렉터리의 파일에서 패키지 빌드:
crossplane xpkg build --package-root=package/
패키지가 프로바이더도 실행할 수 있도록 컨트롤러 OCI 이미지를 내장한 Provider 패키지 빌드:
crossplane xpkg build --embed-runtime-image=cc873e13cdc1
사용법:
crossplane xpkg build [flags]
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| --embed-runtime-image=NAME | 런타임으로 패키지에 내장할 OCI 이미지. | |
| --embed-runtime-image-tarball=PATH | 런타임으로 패키지에 내장할 OCI 이미지 타르볼. | |
| -e | --examples-root="./examples" | 패키지에 포함할 예제 YAML 파일 디렉터리. |
| --ignore=PATH,... | --package-root 기준, 패키지에서 제외할 쉼표 구분 파일 경로. Crossplane은 와일드카드 지원. 디렉터리는 제외할 수 없음. | |
| -o | --package-file=PATH | 패키지를 쓸 파일. 기본값은 --package-root의 생성된 파일 이름. |
| -f | --package-root="." | 패키지의 crossplane.yaml 파일을 포함하는 디렉터리. |
crossplane xpkg extract
패키지 내용을 Crossplane 캐시 호환 형식으로 추출해요. 기본적으로 원격 레지스트리에서 가져옵니다.
사용법:
crossplane xpkg extract [<패키지>] [flags]
인수:
| 인수 | 설명 |
|---|---|
| [패키지] | (선택) 추출할 패키지 이름. 완전한 OCI 이미지 태그이거나 --from-xpkg 사용 시 경로여야 함. |
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| --from-daemon | Docker 데몬에서 이미지 가져오기. | |
| --from-xpkg | 로컬 xpkg 파일 추출. 패키지를 지정하지 않으면 현재 디렉터리의 유일한 파일을 의미. | |
| -o | --output="out.gz" | 패키지 출력 파일. 확장자는 .gz여야 함. |
crossplane xpkg get-crds
패키지 의존성에서 CRD를 다운로드해요.
xpkg get-crds 명령은 Crossplane 패키지 의존성(프로바이더, 함수, 구성)에서 CRD를 다운로드하고 지정된 출력 디렉터리에 YAML 파일로 기록해요. --json-schema를 사용하면 CRD에서 OpenAPI v3 스키마를 추출해 YAML 언어 서버와 함께 사용하기에 적합한 JSON Schema 파일로 기록해요.
기본적으로 명령은 파일을 API 그룹과 버전으로 구성해요(예: <group>/<version>/<kind>.{yaml|json}). --flat을 사용하면 하위 폴더 없이 모든 파일을 출력 디렉터리에 직접 기록해요.
validate 명령과 같은 확장 출처를 받아요: crossplane.yaml 파일, 패키지 매니페스트를 포함한 디렉터리, 또는 Provider/Function/Configuraion 리소스.
예시
- 그룹별로 구성해 CRD 다운로드:
crossplane xpkg get-crds crossplane.yaml --output-dir ./crds
- 플랫 파일로 CRD 다운로드:
crossplane xpkg get-crds crossplane.yaml --output-dir ./crds --flat
- YAML 언어 서버용 JSON Schema 다운로드:
crossplane xpkg get-crds crossplane.yaml --output-dir ./schemas --json-schema
- 여러 출처에서 CRD 다운로드:
crossplane xpkg get-crds crossplane.yaml,providers/ --output-dir ./crds
- 캐시된 스키마 재다운로드 강제:
crossplane xpkg get-crds crossplane.yaml --output-dir ./crds --clean-cache
사용법:
crossplane xpkg get-crds <확장출처> [flags]
인수:
| 인수 | 설명 |
|---|---|
| <확장출처> | 파일, 디렉터리, 또는 표준 입력의 '-'의 쉼표 구분 목록. |
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| --cache-dir="~/.crossplane/cache" | 다운로드된 스키마를 보관하는 캐시 디렉터리의 절대 경로. | |
| --clean-cache | 패키지 스키마 다운로드 전에 캐시 디렉터리 정리. | |
| --crossplane-image=STRING | 내장 스키마 가져오기용 Crossplane 이미지 지정. | |
| --flat | 그룹과 버전별로 구성하는 대신 플랫 디렉터리에 파일 기록. | |
| --json-schema | CRD 대신 JSON Schema 파일 기록. YAML 언어 서버 통합에 유용. | |
| --no-cache | 캐싱 완전 비활성화. 명령이 매번 스키마를 저장 없이 다운로드. | |
| -o | --output-dir="." | CRD 또는 JSON Schema 파일을 받는 디렉터리. 기본값 현재 디렉터리. |
| --update-cache | 제약 조건을 만족하는 최신 버전을 다운로드해 캐시된 스키마 업데이트. |
crossplane xpkg init
템플릿에서 새 패키지를 초기화해요.
xpkg init 명령은 패키지를 빌드하는 데 사용할 수 있는 디렉터리를 초기화해요. 템플릿으로 디렉터리를 초기화하며, 어떤 Git 저장소든 템플릿으로 사용할 수 있어요.
템플릿으로 전체 Git URL 또는 다음 이름 중 하나를 지정하세요:
- configuration-template (https://github.com/crossplane/configuration-template)
- function-template-go (https://github.com/crossplane/function-template-go)
- function-template-python (https://github.com/crossplane/function-template-python)
- provider-template (https://github.com/crossplane/provider-template)
- provider-template-upjet (https://github.com/crossplane/upjet-provider-template)
NOTES.txt
init 명령은 디렉터리 초기화 후 템플릿 루트의 NOTES.txt 파일 내용을 출력해요. 템플릿 사용법 안내에 유용해요.
init.sh
init 명령은 템플릿 루트의 init.sh 파일을 (사용자 확인 후) 실행해요. 템플릿을 개인화하는 스크립트에 유용해요. -r(--run-init-script)를 전달하면 확인 없이 스크립트를 실행해요.
예시
function-example이라는 새 Go Compostion Function 초기화:
crossplane xpkg init function-example function-template-go
커스텀 템플릿에서 provider-example이라는 새 Provider 초기화:
crossplane xpkg init provider-example https://github.com/crossplane/provider-template-custom
새 Go Compostion Function을 초기화하고 확인이나 내용 표시 없이 init.sh 스크립트(있으면) 실행:
crossplane xpkg init function-example function-template-go --run-init-script
사용법:
crossplane xpkg init <이름> <템플릿> [flags]
인수:
| 인수 | 설명 |
|---|---|
| <이름> | 초기화할 새 패키지의 이름. |
| <템플릿> | 새 패키지 초기화에 사용할 템플릿 이름 또는 URL. |
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| -d | --directory="." | 초기화할 디렉터리. 존재하면 비어 있어야 함. |
| -r | --run-init-script | init.sh 스크립트가 있으면 확인 없이 실행. |
| -b | --ref-name=STRING | 템플릿 저장소에서 복제할 브랜치 또는 태그. |
crossplane xpkg install
컨트롤 플레인에 패키지를 설치해요.
xpkg install 명령은 Crossplane 컨트롤 플레인에 패키지를 설치해요. ~/.kube/config를 사용해 컨트롤 플레인에 연결하며, KUBECONFIG 환경 변수로 경로를 재정의할 수 있어요.
패키지 종류, 완전한 패키지 OCI 참조, 그리고 선택적으로 Crossplane 내부의 패키지 이름을 지정하세요:
crossplane xpkg install <종류> <패키지> [<이름>]
<종류>는 configuration, function, provider 중 하나예요.
중요: 패키지 참조는 완전해야 하며 레지스트리, 저장소, 태그를 포함해야 해요 (예: registry.example.com/package:v1.0.0).
패키지 설치 대기
기본적으로 명령은 Crossplane이 패키지를 수락하는 즉시 반환돼요. 다운로드나 설치 완료를 기다리지 않아요. 다운로드나 설치 문제를 조사하려면 kubectl describe <패키지>를 실행하세요.
--wait(-w)를 사용하면 패키지가 HEALTHY가 될 때까지 명령이 기다렸다가 반환돼요. 대기 시간이 패키지 정상화 전에 만료되면 명령이 오류를 반환해요.
수동 패키지 활성화 요구
-m(--manual-activation)을 전달하면 패키지의 revisionActivationPolicy를 Manual로 설정해 패키지의 자동 업그레이드를 방지해요.
사설 레지스트리 인증
사설 패키지 레지스트리에 인증하려면 --package-pull-secrets에 Kubernetes Secret 이름의 쉼표 구분 목록을 사용하세요.
중요: 시크릿은 Crossplane 파드와 같은 네임스페이스에 있어야 해요.
저장된 패키지 리비전 수 커스터마이즈
기본적으로 Crossplane은 로컬 패키지 캐시에 활성 리비전과 비활성 리비전 하나만 유지해요. -r(--revision-history-limit)로 저장된 리비전 수를 늘리세요.
예시
패키지 설치가 끝날 때까지 1분 대기 후 반환:
crossplane xpkg install provider xpkg.crossplane.io/crossplane-contrib/provider-aws-eks:v0.41.0 --wait=1m
커스텀 DeploymentRuntimeConfig를 사용해 function-eg라는 Function 설치:
crossplane xpkg install function xpkg.crossplane.io/crossplane/function-example:v0.1.4 function-eg \
--runtime-config=customconfig
사용법:
crossplane xpkg install <종류> <패키지> [<이름>] [flags]
인수:
| 인수 | 설명 |
|---|---|
| <종류> | 설치할 패키지 종류. 'provider', 'configuration', 'function' 중 하나. |
| <패키지> | 설치할 패키지. 레지스트리, 저장소, 태그를 포함해 완전해야 함. |
| [이름] | (선택) Crossplane API의 새 패키지 이름. 기본값은 패키지 저장소와 태그에서 파생. |
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| --runtime-config=NAME | 런타임 구성(예: DeploymentRuntimeConfig)으로 패키지 설치. | |
| -m | --manual-activation | 새 패키지의 첫 리비전을 수동으로 활성화하도록 요구. |
| --package-pull-secrets=NAME,... | 패키지 관리자가 레지스트리에서 패키지를 풀 때 사용할 시크릿의 쉼표 구분 목록. | |
| -r | --revision-history-limit=LIMIT | 가비지 컬렉션 전에 존재할 수 있는 패키지 리비전 수. |
| -w | --wait=0s | 반환 전에 패키지 설치를 기다릴 시간. 기본적으로 대기하지 않음. |
| --as=STRING | 작업에 가장할 사용자 이름. | |
| --as-group=AS-GROUP | 작업에 가장할 그룹. 반복 지정 가능. | |
| --as-uid=STRING | 작업에 가장할 UID. |
crossplane xpkg push
패키지를 레지스트리에 푸시해요.
xpkg push 명령은 Crossplane 패키지 파일을 OCI 레지스트리에 푸시해요. 패키지의 OCI 태그는 세맨틱 버전이어야 해요. push 명령은 로컬 docker 구성의 레지스트리 자격 증명을 사용해요. 사설 레지스트리에 푸시하려면 먼저 docker login이 필요할 수 있어요.
기본적으로 명령은 현재 디렉터리에서 단일 .xpkg 파일을 찾아 푸시해요. 여러 파일(예: 멀티 플랫폼 패키지)이나 특정 .xpkg 파일을 푸시하려면 -f(--package-files)를 사용하세요.
중요: 대상은 완전해야 하며 레지스트리, 저장소, 태그를 포함해야 해요 (예: registry.example.com/package:v1.0.0).
예시
멀티 플랫폼 패키지 푸시:
crossplane xpkg push -f function-amd64.xpkg,function-arm64.xpkg \
xpkg.crossplane.io/crossplane/function-example:v1.0.0
현재 디렉터리의 단일 xpkg 파일 푸시:
crossplane xpkg push xpkg.crossplane.io/crossplane/function-example:v1.0.0
Docker Hub로 푸시:
crossplane xpkg push docker.io/crossplane/function-example:v1.0.0
사용법:
crossplane xpkg push <대상> [flags]
인수:
| 인수 | 설명 |
|---|---|
| <대상> | 패키지를 푸시할 위치. 레지스트리, 저장소, 태그를 포함한 완전한 OCI 태그여야 함. |
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| -a | --oci-annotation=KEY=VALUE,... | key=value 형식으로 패키지에 추가할 OCI 매니페스트 어노테이션. 반복 가능. |
| --insecure-skip-tls-verify | [INSECURE] TLS 인증서 검증 건너뛰기. | |
| -f | --package-files=PATH | 푸시할 xpkg 파일의 쉼표 구분 목록. |
crossplane xpkg update
컨트롤 플레인의 패키지를 업데이트해요.
xpkg update 명령은 Crossplane 컨트롤 플레인의 패키지를 업데이트해요. ~/.kube/config를 사용해 컨트롤 플레인에 연결하며 KUBECONFIG 환경 변수로 경로를 재정의할 수 있어요.
패키지 종류, 새 완전한 패키지 OCI 참조, 그리고 선택적으로 Crossplane에 이미 설치된 패키지의 이름을 지정하세요:
crossplane xpkg update <종류> <패키지> [<이름>]
중요: 패키지 참조는 완전해야 하며 레지스트리, 저장소, 태그를 포함해야 해요 (예: registry.example.com/package:v1.0.0).
예시
function-eg라는 Function을 새 버전으로 업데이트:
crossplane xpkg update function xpkg.crossplane.io/crossplane/function-example:v0.1.5 function-eg
Provider를 최신 패치 버전으로 업데이트:
crossplane xpkg update provider xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v2.0.0
사용법:
crossplane xpkg update <종류> <패키지> [<이름>] [flags]
인수:
| 인수 | 설명 |
|---|---|
| <종류> | 업데이트할 패키지 종류. 'provider', 'configuration', 'function' 중 하나. |
| <패키지> | 업데이트할 패키지. 레지스트리, 저장소, 태그를 포함해 완전해야 함. |
| [이름] | (선택) Crossplane API에서 업데이트할 패키지 이름. 기본값은 패키지 저장소와 태그에서 파생. |
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| --as=STRING | 작업에 가장할 사용자 이름. | |
| --as-group=AS-GROUP | 작업에 가장할 그룹. 반복 지정 가능. | |
| --as-uid=STRING | 작업에 가장할 UID. |
crossplane xr
[ALPHA] Crossplane 복합 리소스(XR) 작업을 해요.
참고: 알파 기능은 실험적이며 향후 릴리스에서 변경되거나 사라질 수 있어요.
사용법:
crossplane xr <하위명령> [flags]
crossplane xr generate
[ALPHA] Claim에서 복합 리소스(XR)를 생성해요.
참고: 알파 기능은 실험적이며 향후 릴리스에서 변경되거나 사라질 수 있어요.
xr generate 명령은 Claim YAML에서 복합 리소스(XR)를 생성해요.
파일(또는 stdin)에서 Claim을 읽어 XR(같은 spec, 파생된 kind, 선택적 Claim 참조)을 만들고 결과를 stdout 또는 파일에 기록해요.
예시
claim.yaml에서 XR을 생성해 stdout에 출력 (kind는 X + Claim의 kind):
crossplane xr generate claim.yaml
claim.yaml에서 XR을 생성해 xr.yaml에 기록:
crossplane xr generate claim.yaml -o xr.yaml
명시적 이름으로 XR 생성 (기본 접미사나 Claim 이름 재정의):
crossplane xr generate claim.yaml --name my-xr
특정 kind로 XR 생성:
crossplane xr generate claim.yaml --kind MyCompositeResource
직접 연결된 XR 생성 (Claim 참조 없음, 이름 접미사 없음):
crossplane xr generate claim.yaml --direct
새 무작위 metadata.uid로 XR 생성:
crossplane xr generate claim.yaml --gen-uid
stdin에서 Claim 읽기:
cat claim.yaml | crossplane xr generate -
사용법:
crossplane xr generate [<파일>] [flags]
인수:
| 인수 | 설명 |
|---|---|
| [파일] | (선택) 변환할 Claim YAML 파일 또는 stdin의 '-'. |
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| -o | --output-file=PATH | 생성된 XR YAML을 쓸 파일. 기본값 stdout. |
| --name=NAME | XR에 사용할 이름. 비면 (direct 모드에서) Claim 이름 또는 (non-direct에서) 무작위 접미사를 붙인 Claim 이름. | |
| --kind=KIND | XR에 사용할 kind. 기본값은 Claim의 kind 앞에 'X'를 붙임 (예: Infra → XInfra). | |
| --direct | Claim 참조와 접미사 없는 직접 XR 생성. | |
| --gen-uid | 생성된 XR에 새 무작위 metadata.uid 설정. |
crossplane xr patch
[ALPHA] 복합 리소스(XR)를 패치해요.
참고: 알파 기능은 실험적이며 향후 릴리스에서 변경되거나 사라질 수 있어요.
xr patch 명령은 복합 리소스(XR)에 XR 수준 패치를 적용해요.
파일(또는 stdin)에서 XR을 읽어 요청된 패치를 적용하고 결과를 stdout 또는 파일에 기록해요. 패칭 플래그를 최소 하나 전달하세요. 현재 유일한 플래그는 --xrd이며, XRD의 openAPIV3Schema의 기본값을 XR에 적용해요. 향후 릴리스에서 더 많은 패칭 플래그가 추가돼요.
예시
XRD의 기본값을 XR에 적용:
crossplane xr patch xr.yaml --xrd xrd.yaml
stdin에서 XR 패치:
cat xr.yaml | crossplane xr patch - --xrd xrd.yaml
패치된 XR을 파일에 기록:
crossplane xr patch xr.yaml --xrd xrd.yaml -o patched.yaml
사용법:
crossplane xr patch [<파일>] [flags]
인수:
| 인수 | 설명 |
|---|---|
| [파일] | (선택) 패치할 XR YAML 파일 또는 stdin의 '-'. |
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| -o | --output-file=PATH | 패치된 XR YAML을 쓸 파일. 기본값 stdout. |
| --xrd=PATH | XR에 스키마 기본값을 제공하는 CompositeResourceDefinition(XRD)을 지정하는 YAML 파일. |
crossplane xrd
[BETA] Crossplane 복합 리소스 정의(XRD) 작업을 해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
사용법:
crossplane xrd <하위명령> [flags]
crossplane xrd convert
[BETA] XRD를 Kubernetes CRD로 변환해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
xrd convert 명령은 CompositeResourceDefinition(XRD)을 Crossplane이 내부적으로 파생하는 하나 이상의 CustomResourceDefinition으로 변환해요.
생성된 CRD 형태를 검사하거나, XRD를 이해하지 못하는 kubectl 기반 도구에 넣거나, Compostion 동작을 디버깅하는 데 유용해요.
출력은 자동 감지된 XRD 유형에 따라 달라져요:
- 네임스페이스 또는 클러스터 스코프 XRD: XR용 CRD 1개
- claimNames가 없는 레거시 XRD: XR용 CRD 1개
- claimNames가 있는 레거시 XRD: CRD 2개 (XR용 1개, Claim용 1개)
예시
XRD 파일을 변환해 CRD를 stdout에 출력 (레거시 XRD는 multi-doc YAML):
crossplane xrd convert xrd.yaml
단일 파일로 변환·작성 (레거시 XRD는 multi-doc YAML):
crossplane xrd convert xrd.yaml -o crds.yaml
CRD별 파일을 디렉터리로 분리 (각 <kind>.yaml 이름):
crossplane xrd convert xrd.yaml --output-dir ./crds/
stdin에서 XRD 읽기:
cat xrd.yaml | crossplane xrd convert -
XRD를 JSON Schema로 변환해 stdout에 출력:
crossplane xrd convert xrd.yaml --format=jsonschema
XRD를 디렉터리의 JSON Schema 파일로 변환:
crossplane xrd convert xrd.yaml --format=jsonschema --output-dir ./schemas/
사용법:
crossplane xrd convert [<파일>] [flags]
인수:
| 인수 | 설명 |
|---|---|
| [파일] | (선택) 변환할 XRD YAML 파일 또는 stdin의 '-'. |
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| -o | --output-file=PATH | 생성된 CRD YAML을 쓸 파일. 레거시 XRD는 multi-doc YAML 스트림(XR CRD + Claim CRD) 생성. |
| --output-dir=DIR | 생성된 CRD를 쓸 디렉터리. 각 CRD는 CRD 이름으로 된 별도 파일을 얻음. | |
| --format="crd" | CRD 대신 JSON Schema 파일 작성. YAML 언어 서버 통합에 유용. |
crossplane xrd generate
[BETA] 복합 리소스(XR) 또는 SimpleSchema 정의에서 XRD를 생성해요.
참고: 베타 기능은 향후 릴리스에서 변경될 수 있어요.
xrd generate 명령은 예제 복합 리소스(XR) 또는 SimpleSchema 문서에서 CompositeResourceDefinition(XRD)을 만들고 프로젝트의 APIs 디렉터리에 기록해요.
XR이 기본 입력 형식이며, SimpleSchema 정의에서 XRD를 생성하려면 --from simpleschema를 전달하세요.
예시
예제 복합 리소스(XR)에서 XRD를 생성해 프로젝트의 APIs 디렉터리에 저장:
crossplane xrd generate examples/cluster/example.yaml
특정 복수형으로 XRD 생성 (자동 복수화가 틀릴 때 유용, 예: "postgres"):
crossplane xrd generate examples/postgres/example.yaml --plural postgreses
XRD를 생성해 커스텀 경로에 저장:
crossplane xrd generate examples/postgres/example.yaml --path database/definition.yaml
SimpleSchema 문서에서 XRD 생성:
crossplane xrd generate apis/network/schema.yaml --from simpleschema
사용법:
crossplane xrd generate <XR경로> [flags]
인수:
| 인수 | 설명 |
|---|---|
| <XR경로> | XR 또는 XRC YAML 파일 경로. |
플래그:
| Short flag | Long flag | 설명 |
|---|---|---|
| --from="xr" | 입력 형식: xr 또는 simpleschema. | |
| --path=STRING | 출력 경로. | |
| --replace | 기존 정의 파일 교체. | |
| --plural=STRING | XRD의 커스텀 복수형. | |
| -f | --project-file="crossplane-project.yaml" | 프로젝트 정의 경로. |