From f02fd574126e6a6d94b12d5e8735f1f1c78fd359 Mon Sep 17 00:00:00 2001
From: Philippe Scorsolini <p.scorsolini@gmail.com>
Date: Tue, 5 Sep 2023 14:58:06 +0200
Subject: [PATCH 1/2] feat: optional environment label selector fieldpath

Co-authored-by: Pete Lumbis <pete@upbound.io>
Signed-off-by: Philippe Scorsolini <p.scorsolini@gmail.com>
---
 .../master/concepts/environment-configs.md    | 66 ++++++++++++++++++-
 1 file changed, 63 insertions(+), 3 deletions(-)

diff --git a/content/master/concepts/environment-configs.md b/content/master/concepts/environment-configs.md
index 74dc3f13f..85366028b 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
+{{<hover label="byLabel" line="16">}}valueFromFieldPath{{</hover>}}
+field doesn't exist in the composite resource at runtime.  
+Set the
+{{<hover label="byLabelOptional" line="17">}}fromFieldPathPolicy{{</hover>}}
+field to `Optional` to ignore fields that don't exist. 
+
+```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
+```
+
+Crossplane evaluates label selectors in order, so if a label set as optional
+isn't found, but if you already defined an explicit value for it, it uses that
+{{<hover label="byLabelOptionalDefault" line="16">}}default value{{</hover>}}
+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.  

From 8c9fa333c5022906d64cbe4bc993fa2f777b321d Mon Sep 17 00:00:00 2001
From: Philippe Scorsolini <p.scorsolini@gmail.com>
Date: Tue, 5 Sep 2023 20:08:12 +0200
Subject: [PATCH 2/2] chore: review

Signed-off-by: Philippe Scorsolini <p.scorsolini@gmail.com>
---
 .../master/concepts/environment-configs.md    | 22 +++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/content/master/concepts/environment-configs.md b/content/master/concepts/environment-configs.md
index 85366028b..4e6339e28 100644
--- a/content/master/concepts/environment-configs.md
+++ b/content/master/concepts/environment-configs.md
@@ -235,10 +235,18 @@ spec:
   # Removed for brevity
 ```
 
-Crossplane evaluates label selectors in order, so if a label set as optional
-isn't found, but if you already defined an explicit value for it, it uses that
-{{<hover label="byLabelOptionalDefault" line="16">}}default value{{</hover>}}
-instead.
+Set a default value for an optional label by setting the
+{{<hover label="byLabelOptionalDefault" line="15">}}value{{</hover>}} for the
+{{<hover label="byLabelOptionalDefault" line="14">}}key{{</hover>}} first, then
+define the
+{{<hover label="byLabelOptionalDefault" line="20">}}Optional{{</hover>}} label.
+
+For example, this Composition defines
+{{<hover label="byLabelOptionalDefault" line="16">}}value: my-default-value{{</hover>}}
+for the key {{<hover label="byLabelOptionalDefault" line="14">}}my-second-label-key{{</hover>}}.
+If the label
+{{<hover label="byLabelOptionalDefault" line="17">}}my-second-label-key{{</hover>}}
+exists, Crossplane uses the value from the label instead.
 
 ```yaml {label="byLabelOptionalDefault",copy-lines="all"}
 apiVersion: apiextensions.crossplane.io/v1
@@ -265,6 +273,12 @@ spec:
   # Removed for brevity
 ```
 
+{{<hint "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.
+{{< /hint >}}
 
 #### Manage selector results