Environment Configurations

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.

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

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.

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  # 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.

 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  # 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  # Removed for brevity

Use EnvironmentConfigs in a Composition

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

Crossplane sends the merged, in-memory environment to the composition function pipeline using the pipeline context. It writes the environment to the apiextensions.crossplane.io/environment context key.

Some composition functions can read the environment from the pipeline context and use it to compose resources.