diff --git a/content/master/concepts/environment-configs.md b/content/master/concepts/environment-configs.md index 74dc3f13f..a16724f15 100644 --- a/content/master/concepts/environment-configs.md +++ b/content/master/concepts/environment-configs.md @@ -196,16 +196,76 @@ spec: - type: Selector selector: matchLabels: - - key: my-label-key + - key: my-first-label-key type: Value - value: my-label-value - - key: my-label-key + value: my-first-label-value + - key: my-second-label-key type: FromCompositeFieldPath valueFromFieldPath: spec.parameters.deploy resources: # Removed for brevity ``` +By default, Crossplane errors out if a +{{}}valueFromFieldPath{{}} +field doesn't exist in the composite resource at runtime. You can change this +behavior by setting the +{{}}fromFieldPathPolicy{{}} +field to `Optional`, resulting in the key being ignored if not found instead. + +```yaml {label="byLabelOptional",copy-lines="all"} +apiVersion: apiextensions.crossplane.io/v1 +kind: Composition +metadata: + name: example-composition +spec: + environment: + environmentConfigs: + - type: Selector + selector: + matchLabels: + - key: my-first-label-key + type: Value + value: my-first-label-value + - key: my-second-label-key + type: FromCompositeFieldPath + valueFromFieldPath: spec.parameters.deploy + fromFieldPathPolicy: Optional + resources: + # Removed for brevity +``` + +Label selectors are evaluated in order, so if a label set as optional is not +found, but an explicit value for it was defined already, the +{{}}default value{{}} +is used instead. + +```yaml {label="byLabelOptionalDefault",copy-lines="all"} +apiVersion: apiextensions.crossplane.io/v1 +kind: Composition +metadata: + name: example-composition +spec: + environment: + 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 + resources: + # Removed for brevity +``` + + #### Manage selector results Selecting environments by labels may return more than one environment.