EnvironmentConfigs
크로스플레인의 EnvironmentConfig를 다루는 문서입니다. EnvironmentConfig는 Composition이 사용하는 클러스터 범위(cluster-scoped)의 강력한 타입을 가진 ConfigMap과 유사한 리소스입니다. Composition은 환경을 사용하여 개별 리소스의 정보를 저장하거나 패치를 적용할 수 있습니다.
출처: 문서
본문
이 기능은 v1.11에서 도입되었으며, v1.18에서 베타(beta) 상태로 승격되었습니다. 자세한 내용은 크로스플레인의 기능 수명주기(Crossplane feature lifecycle) 문서를 참고하세요.
크로스플레인 EnvironmentConfig는 클러스터 범위(cluster-scoped)의 강력한 타입(strongly typed)을 가진 ConfigMap과 유사한 리소스이며, Composition이 사용합니다. Composition은 환경을 사용하여 개별 리소스의 정보를 저장하거나 패치를 적용할 수 있습니다.
크로스플레인은 여러 EnvironmentConfigs를 지원하며, 각각은 고유한 데이터 저장소 역할을 합니다.
크로스플레인이 복합 리소스를 생성할 때, 연결된 Composition에서 참조하는 모든 EnvironmentConfigs를 병합하고 그 복합 리소스를 위한 고유한 인메모리 환경(environment)을 생성합니다.
복합 리소스는 자신의 고유한 인메모리 환경에서 데이터를 읽고 쓸 수 있습니다.
중요 인메모리 환경은 각 복합 리소스마다 고유합니다. 복합 리소스는 다른 복합 리소스의 환경에 있는 데이터를 읽을 수 없습니다.
EnvironmentConfig 생성하기 (Create an EnvironmentConfig)
EnvironmentConfig는 data라는 단일 객체 필드를 가집니다.
EnvironmentConfig는 data 필드 안의 모든 데이터를 지원합니다.
다음은 EnvironmentConfig 예시입니다.
apiVersion: apiextensions.crossplane.io/v1beta1
kind: EnvironmentConfig
metadata:
name: example-environment
data:
locations:
us: us-east-2
eu: eu-north-1
key1: value1
key2: value2
key3:
- item1
- item2
EnvironmentConfigs 접근하기 (Access EnvironmentConfigs)
extra-resources를 지원하는 Composition 함수(예: function-environment-configs 또는 function-go-templating)를 사용할 수 있습니다.
알파 Composition 환경에서의 마이그레이션 (Migration from alpha composition environment)
Alpha Composition Environments(--enable-environment-configs)를 활성화하고 네이티브 기능(spec.environment.patches, spec.environment.environmentConfigs, *Environment 패치)을 사용했던 사용자는 계속 사용하려면 Composition Functions로 마이그레이션해야 합니다.
Pipeline 모드로의 자동 마이그레이션은 crossplane beta convert pipeline-composition을 통해 가능합니다. 이 명령은 Resource 모드를 사용하는 Composition을 function-patch-and-transform으로, 필요하다면 function-environment-configs로 이동시킵니다.
수동 마이그레이션에 대한 자세한 내용은 function-environment-configs의 문서를 참고하세요.
function-environment-configs로 EnvironmentConfig 선택하기 (Select an EnvironmentConfig using function-environment-configs)
function-environment-configs의 Input을 통해 사용할 EnvironmentConfigs를 선택합니다.
environmentConfigs 필드는 가져와서 병합한 후 apiextensions.crossplane.io/environment라는 알려진 키로 Context를 통해 파이프라인의 다음 단계로 전달할 EnvironmentConfigs 목록입니다.
환경을 Reference 또는 Selector로 선택합니다.
- Reference — EnvironmentConfig를 이름으로 선택합니다.
- Selector — EnvironmentConfig를 라벨로 선택합니다.
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: example-composition
spec:
mode: Pipeline
pipeline:
- step: environmentConfigs
functionRef:
name: function-environment-configs
input:
apiVersion: environmentconfigs.fn.crossplane.io/v1beta1
kind: Input
spec:
environmentConfigs:
- type: Reference
ref:
name: example-environment
- type: Selector
selector:
matchLabels:
# Removed for brevity
# the environment will be passed to the next function in the pipeline
# as part of the context
# Next step consuming the merged environment removed for brevity...
Composition이 여러 EnvironmentConfigs를 사용하면 function-environment-configs는 나열된 순서대로 병합합니다.
이름으로 선택하기 (Select by name)
type: Reference로 EnvironmentConfig를 이름으로 선택합니다.
환경의 정확한 이름과 일치하도록 ref.name을 정의합니다.
예를 들어 example-environment라는 이름의 EnvironmentConfig를 선택하려면 다음과 같이 합니다.
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: example-composition
spec:
mode: Pipeline
pipeline:
- step: environmentConfigs
functionRef:
name: function-environment-configs
input:
apiVersion: environmentconfigs.fn.crossplane.io/v1beta1
kind: Input
spec:
environmentConfigs:
- type: Reference
ref:
name: example-environment
라벨로 선택하기 (Select by label)
type: Selector로 EnvironmentConfig를 라벨로 선택합니다.
selector.matchLabels를 Value 또는 FromCompositeFieldPath 유형의 선택자 목록으로 정의합니다.
라벨 값을 일치시킬 때 type: Value로 정확한 값을 제공하고 value 필드에 일치시킬 값을 제공합니다.
function-environment-configs는 복합 리소스의 입력을 기반으로 라벨 값을 일치시킬 수도 있습니다. type: FromCompositeFieldPath를 사용하고 valueFromFieldPath 필드에 일치시킬 필드를 제공합니다.
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: example-composition
spec:
mode: Pipeline
pipeline:
- step: environmentConfigs
functionRef:
name: function-environment-configs
input:
apiVersion: environmentconfigs.fn.crossplane.io/v1beta1
kind: Input
spec:
environmentConfigs:
- type: Selector
selector:
matchLabels:
- key: my-label-key
type: Value
value: my-label-value
- key: my-label-key
type: FromCompositeFieldPath
valueFromFieldPath: spec.parameters.deploy
# Removed for brevity
선택자 결과 관리하기 (Manage selector results)
라벨로 환경을 선택하면 둘 이상의 환경이 반환될 수 있습니다. function-environment-configs는 기본적으로 모든 결과를 이름별로 정렬하고 정렬된 목록의 첫 번째 환경만 사용합니다.
selector.mode를 Multiple로 설정하면 일치하는 모든 EnvironmentConfigs를 반환합니다. mode: Single을 사용하면 단일 환경을 반환하며, 크로스플레인이 둘 이상의 일치 항목을 찾으면 오류를 발생시킵니다.
정렬과 선택 모드는 단일 Selector에만 적용됩니다.
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: example-composition
spec:
mode: Pipeline
pipeline:
- step: environmentConfigs
functionRef:
name: function-environment-configs
input:
apiVersion: environmentconfigs.fn.crossplane.io/v1beta1
kind: Input
spec:
environmentConfigs:
- type: Selector
selector:
mode: Multiple
matchLabels:
- key: my-label-key
type: Value
value: my-label-value
- key: my-label-key
type: FromCompositeFieldPath
valueFromFieldPath: spec.parameters.deploy
- type: Selector
selector:
mode: Single
matchLabels:
- key: my-other-label-key
type: Value
value: my-other-label-value
- key: my-other-label-key
type: FromCompositeFieldPath
valueFromFieldPath: spec.parameters.deploy
mode: Multiple을 사용할 때 maxMatch로 반환할 EnvironmentConfigs 수를 제한하고 선택할 최대 수를 정의합니다.
minMatch를 사용하여 반환되는 환경의 최소 수를 정의합니다.
함수는 기본적으로 반환된 환경을 이름의 알파벳순으로 정렬합니다. sortByFieldPath로 다른 필드를 기준으로 환경을 정렬하고 정렬할 필드를 정의합니다.
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: example-composition
spec:
mode: Pipeline
pipeline:
- step: environmentConfigs
functionRef:
name: function-environment-configs
input:
apiVersion: environmentconfigs.fn.crossplane.io/v1beta1
kind: Input
spec:
environmentConfigs:
- type: Selector
selector:
mode: Multiple
maxMatch: 4
sortByFieldPath: metadata.annotations[sort.by/weight]
matchLabels:
- key: my-label-key
type: Value
value: my-label-value
- key: my-label-key
type: FromCompositeFieldPath
valueFromFieldPath: spec.parameters.deploy
matchLabels로 선택된 EnvironmentConfigs는 그 후 다른 모든 지정된 것들과 병합됩니다.
선택적 선택자 라벨 (Optional selector labels)
기본적으로 지정된 valueFromFieldPath 필드가 복합 리소스에 존재하지 않으면 크로스플레인은 오류를 발생시킵니다.
fromFieldPathPolicy를 Optional로 설정하면 필드가 존재하지 않을 때 무시합니다.
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: example-composition
spec:
mode: Pipeline
pipeline:
- step: environmentConfigs
functionRef:
name: function-environment-configs
input:
apiVersion: environmentconfigs.fn.crossplane.io/v1beta1
kind: Input
spec:
environmentConfigs:
- type: Selector
selector:
mode: Multiple
maxMatch: 4
sortByFieldPath: metadata.annotations[sort.by/weight]
matchLabels:
- key: my-label-key
type: Value
value: my-label-value
- key: my-label-key
type: FromCompositeFieldPath
valueFromFieldPath: spec.parameters.deploy
fromFieldPathPolicy: Optional
# Removed for brevity
먼저 Value 선택자로 key의 기본 value를 설정한 다음 Optional FromCompositeFieldPath를 정의하여 선택적 라벨의 기본값을 설정할 수 있습니다.
예를 들어, 아래 Composition은 키 my-second-label-key에 value: my-default-value를 정의합니다. 복합 리소스가 spec.parameters.deploy를 정의하면 function-environment-configs는 그것을 대신 사용합니다.
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: example-composition
spec:
mode: Pipeline
pipeline:
- step: environmentConfigs
functionRef:
name: function-environment-configs
input:
apiVersion: environmentconfigs.fn.crossplane.io/v1beta1
kind: Input
spec:
environmentConfigs:
- type: Selector
selector:
matchLabels:
- key: my-first-label-key
type: Value
value: my-label-value
- key: my-second-label-key
type: Value
value: my-default-value
- key: my-second-label-key
type: FromCompositeFieldPath
valueFromFieldPath: spec.parameters.deploy
fromFieldPathPolicy: Optional
# Removed for brevity
경고 function-environment-configs는 값을 순서대로 적용합니다. 마지막에 정의된 키의 값이 항상 우선합니다. 라벨 뒤에 기본값을 정의하면 항상 라벨 값을 덮어씁니다.
function-patch-and-transform으로 EnvironmentConfigs 패치하기 (Patching with EnvironmentConfigs using function-patch-and-transform)
앞서 설명한 대로 선택된 EnvironmentConfigs는 function-environment-configs에 의해 in-memory environment로 병합되고 apiextensions.crossplane.io/environment이라는 알려진 키로 파이프라인의 다음 함수에 전달됩니다.
function-patch-and-transform을 사용하여 인메모리 환경과 복합 리소스 또는 개별 composed resources 사이의 데이터를 읽거나 쓸 수 있습니다.
팁 Patch and Transform 함수는 환경을 사용하여 composed resources를 패치할 수 있습니다. EnvironmentConfig 패치 유형에 대해서는 Patch and Transform 함수 문서를 읽어 보세요.
복합 리소스와 환경 사이 패치 (Patch between Composite resource and environment)
복합 리소스와 환경 사이를 패치하려면 function-patch-and-transform의 Resources 입력에서 spec.environment.patches에 패치를 정의합니다.
ToCompositeFieldPath 패치 유형을 사용하여 인메모리 환경에서 복합 리소스로 데이터를 복사합니다. FromCompositeFieldPath를 사용하여 복합 리소스에서 인메모리 환경으로 데이터를 복사합니다.
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: example-composition
spec:
mode: Pipeline
pipeline:
# Removed for Brevity
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
environment:
patches:
- type: ToCompositeFieldPath
fromFieldPath: tags
toFieldPath: metadata.labels[envTag]
- type: FromCompositeFieldPath
fromFieldPath: metadata.name
toFieldPath: newEnvironmentKey
# Removed for Brevity
개별 리소스는 인메모리 환경에 기록된 모든 데이터를 사용할 수 있습니다.
CombineFromComposite와 CombineToComposite를 사용하여 여러 값을 결합하고 그 결과를 각각 인메모리 환경 또는 복합 리소스에 쓸 수 있습니다.
개별 리소스 패치 (Patch an individual resource)
개별 리소스와 인메모리 환경 사이를 패치하려면 리소스의 patches 안에서 ToEnvironmentFieldPath를 사용하여 리소스에서 인메모리 환경으로 데이터를 복사합니다. FromEnvironmentFieldPath를 사용하여 인메모리 환경에서 리소스로 데이터를 복사합니다.
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: example-composition
spec:
mode: Pipeline
pipeline:
# Removed for Brevity
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
# Removed for Brevity
resources:
- name: vpc
base:
apiVersion: ec2.aws.m.upbound.io/v1beta1
kind: VPC
spec:
forProvider:
cidrBlock: 172.16.0.0/16
patches:
- type: ToEnvironmentFieldPath
fromFieldPath: status.atProvider.id
toFieldPath: vpcId
- type: FromEnvironmentFieldPath
fromFieldPath: tags
toFieldPath: spec.forProvider.tags
팁 Patch and Transform 문서에 개별 리소스 패치에 대한 더 자세한 내용이 있습니다.