Environment Configurations

This is an alpha feature. Crossplane may change or drop this feature at any time.

This feature was introduced in v1.11.

For more information read the Crossplane feature lifecycle.

On this page

This document is for an older version of Crossplane.

This document applies to Crossplane version v1.16 and not to the latest release v1.18.

A Crossplane EnvironmentConfig is a cluster scoped ConfigMap-like resource used by Compositions. Compositions can use the environment to store information from individual resources or to apply patches.

Crossplane supports multiple EnvironmentConfigs, each acting as a unique data store.

When Crossplane creates a composite resource, Crossplane merges all the EnvironmentConfigs referenced in the associated Composition and creates a unique in-memory environment for that composite resource.

The composite resource can read and write data to their unique in-memory environment.

Important

The in-memory environment is unique to each composite resource.
A composite resource can’t read data in another composite resource’s environment.

Enable EnvironmentConfigs

EnvironmentConfigs are an alpha feature. Alpha features aren’t enabled by default.

Enable EnvironmentConfig support by changing the Crossplane pod setting and enabling
--enable-environment-configs argument.

 1$ kubectl edit deployment crossplane --namespace crossplane-system
 2apiVersion: apps/v1
 3kind: Deployment
 4spec:
 5# Removed for brevity
 6  template:
 7    spec:
 8      containers:
 9      - args:
10        - core
11        - start
12        - --enable-environment-configs

Tip

The Crossplane install guide describes enabling feature flags like –enable-environment-configs with Helm.

Create an EnvironmentConfig

An EnvironmentConfig has a single object field, data.

An EnvironmentConfig supports any data inside the data field.

Here an example EnvironmentConfig.

 1apiVersion: apiextensions.crossplane.io/v1alpha1
 2kind: EnvironmentConfig
 3metadata:
 4  name: example-environment
 5data:
 6  locations:
 7    us: us-east-2
 8    eu: eu-north-1
 9  key1: value1
10  key2: value2
11  key3:
12    - item1
13    - item2

Select an EnvironmentConfig

Select the EnvironmentConfigs to use inside a Composition’s environment field.

The environmentConfigs field is a list of environments this Composition can use.

Select an environment by Reference or by Selector.

A Reference selects an environment by name.
The Selector selects an environment based on the Labels applied to the environment.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3metadata:
 4  name: example-composition
 5spec:
 6  environment:
 7    environmentConfigs:
 8    - type: Reference
 9      ref:
10        name: example-environment
11    - type: Selector
12      selector:
13        matchLabels:
14      # Removed for brevity

If a Composition uses multiple environmentConfigs Crossplane merges them together in the order they’re listed.

Note

If multiple environmentConfigs use the same key, the Composition uses the value of the last environment listed.

Select by name

Select an environment by name with type: Reference.

Define the ref object and the name matching the exact name of the environment.

For example, select the environmentConfig named example-environment

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3metadata:
 4  name: example-composition
 5spec:
 6  environment:
 7    environmentConfigs:
 8    - type: Reference
 9      ref:
10        name: example-environment

Select by label

Select an environment by labels with a type: Selector.

Define the selector object.

The matchLabels object contains a list of labels to match on.

Selecting a label requires matching both the label key and the value of key.

When matching the label’s value, provide an exact value with a type: Value and provide the value to match in the value field.

Crossplane can also match a label’s value based on an input in the composite resource. Use type: FromCompositeFieldPath and provide the field to match in the valueFromFieldPath field.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3metadata:
 4  name: example-composition
 5spec:
 6  environment:
 7    environmentConfigs:
 8    - type: Selector
 9      selector: 
10        matchLabels:
11          - key: my-label-key
12            type: Value
13            value: my-label-value
14          - key: my-label-key
15            type: FromCompositeFieldPath
16            valueFromFieldPath: spec.parameters.deploy
17  resources:
18  # Removed for brevity

Manage selector results

Selecting environments by labels may return more than one environment.
The Composition sorts all the results by the name of the environments and only uses the first environment in the sorted list.

Set the mode as mode: Multiple to return all matched environments. Use mode: Single to return a single environment.

Note

Sorting and the selection mode only applies to a single type: Selector.

This doesn’t change how Compositions merge multiple environmentConfigs.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3metadata:
 4  name: example-composition
 5spec:
 6  environment:
 7    environmentConfigs:
 8    - type: Selector
 9      selector:
10        mode: Multiple
11        matchLabels:
12          - key: my-label-key
13            type: Value
14            value: my-label-value
15          - key: my-label-key
16            type: FromCompositeFieldPath
17            valueFromFieldPath: spec.parameters.deploy
18    - type: Selector
19      selector:
20        mode: Single
21        matchLabels:
22          - key: my-other-label-key
23            type: Value
24            value: my-other-label-value
25          - key: my-other-label-key
26            type: FromCompositeFieldPath
27            valueFromFieldPath: spec.parameters.deploy

When using mode: Multiple limit the number of returned environments with maxMatch and define the maximum number of environments returned.

Use minMatch and define the minimum number of environments returned.

The Composition sorts the returned environments alphabetically by name. Sort the environments on a different field with sortByFieldPath and define the field to sort by.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3metadata:
 4  name: example-composition
 5spec:
 6  environment:
 7    environmentConfigs:
 8    - type: Selector
 9      selector:
10        mode: Multiple
11        maxMatch: 4
12        sortByFieldPath: metadata.annotations[sort.by/weight]
13        matchLabels:
14          - key: my-label-key
15            type: Value
16            value: my-label-value
17          - key: my-label-key
18            type: FromCompositeFieldPath
19            valueFromFieldPath: spec.parameters.deploy

The environments selected by matchLabels are then merged into any other environments listed in the environmentConfigs.

Optional selector labels

By default, Crossplane issues an error if a valueFromFieldPath field doesn’t exist in the composite resource.

Add fromFieldPathPolicy as Optional to ignore a field if it doesn’t exist.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3metadata:
 4  name: example-composition
 5spec:
 6  environment:
 7    environmentConfigs:
 8      - type: Selector
 9        selector:
10          matchLabels:
11            - key: my-first-label-key
12              type: Value
13              value: my-first-label-value
14            - key: my-second-label-key
15              type: FromCompositeFieldPath
16              valueFromFieldPath: spec.parameters.deploy
17              fromFieldPathPolicy: Optional
18  resources:
19  # Removed for brevity

Set a default value for an optional label by setting the default value for the key first, then define the Optional label.

For example, this Composition defines value: my-default-value for the key my-second-label-key. If the label my-second-label-key exists, Crossplane uses the value from the label instead.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3metadata:
 4  name: example-composition
 5spec:
 6  environment:
 7    environmentConfigs:
 8      - type: Selector
 9        selector:
10          matchLabels:
11            - key: my-first-label-key
12              type: Value
13              value: my-label-value
14            - key: my-second-label-key
15              type: Value
16              value: my-default-value
17            - key: my-second-label-key
18              type: FromCompositeFieldPath
19              valueFromFieldPath: spec.parameters.deploy
20              fromFieldPathPolicy: Optional
21  resources:
22  # Removed for brevity

Warning

Crossplane applies values in order. The value of the last key defined always takes precedence.

Defining the default value after the label always overwrites the label value.

Patching with EnvironmentConfigs

When Crossplane creates or updates a composite resource, Crossplane merges all the specified EnvironmentConfigs into an in-memory environment.

The composite resource can read or write data between the EnvironmentConfig and composite resource or between the EnvironmentConfig and individual resources defined inside the composite resource.

Tip

Read about EnvironmentConfig patch types in the Patch and Transform documentation.

Patch a composite resource

To patch the composite resource use patches inside of the environment.

Use the ToCompositeFieldPath to copy data from the in-memory environment to the composite resource.
Use the FromCompositeFieldPath to copy data from the composite resource to the in-memory environment.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3# Removed for Brevity
 4spec:
 5  environment:
 6  # Removed for Brevity
 7      patches:
 8      - type: ToCompositeFieldPath
 9        fromFieldPath: tags
10        toFieldPath: metadata.labels[envTag]
11      - type: FromCompositeFieldPath
12        fromFieldPath: metadata.name
13        toFieldPath: newEnvironmentKey

Individual resources can use any data written to the in-memory environment.

Patch an individual resource

To patch an individual resource, inside the patches of the resource, use ToEnvironmentFieldPath to copy data from the resource to the in-memory environment.
Use FromEnvironmentFieldPath to copy data to the resource from the in-memory environment.

 1apiVersion: apiextensions.crossplane.io/v1
 2kind: Composition
 3# Removed for Brevity
 4spec:
 5  environment:
 6  # Removed for Brevity
 7  resources:
 8  # Removed for Brevity
 9    - name: vpc
10      base:
11        apiVersion: ec2.aws.upbound.io/v1beta1
12        kind: VPC
13        spec:
14          forProvider:
15            cidrBlock: 172.16.0.0/16
16      patches:
17        - type: ToEnvironmentFieldPath
18          fromFieldPath: status.atProvider.id
19          toFieldPath: vpcId
20        - type: FromEnvironmentFieldPath
21          fromFieldPath: tags
22          toFieldPath: spec.forProvider.tags

The Patch and Transform documentation has more information on patching individual resources.