From ebd0a08ee08cc4d1940adddf5aadcf0e1f052cfa Mon Sep 17 00:00:00 2001
From: Pete Lumbis <pete@upbound.io>
Date: Thu, 14 Sep 2023 15:59:00 -0400
Subject: [PATCH] Update guidlines on envConfigs and patching to XRs

Signed-off-by: Pete Lumbis <pete@upbound.io>
---
 content/master/concepts/compositions.md       |  51 ++++-
 .../master/concepts/environment-configs.md    | 194 ++++++++++--------
 .../master/concepts/patch-and-transform.md    |  22 +-
 content/v1.13/concepts/compositions.md        |  36 +++-
 content/v1.13/concepts/environment-configs.md | 114 +++++++++-
 content/v1.13/concepts/patch-and-transform.md |  19 +-
 6 files changed, 321 insertions(+), 115 deletions(-)

diff --git a/content/master/concepts/compositions.md b/content/master/concepts/compositions.md
index f72043996..2d346dde6 100644
--- a/content/master/concepts/compositions.md
+++ b/content/master/concepts/compositions.md
@@ -135,7 +135,7 @@ the external resource name.
 #### Template a ProviderConfig
 
 Compositions can define a ProviderConfig like it defines managed resources.
-Generating a ProviderConfig can provide unique credentials to
+Generating a ProviderConfig may be useful in providing unique credentials to
 each deployment.
 
 
@@ -240,7 +240,8 @@ Composition, the resources defined by the
 the EKS {{<hover label="xcluster" line="13">}}cluster{{</hover >}}. 
 
 {{<hint "note" >}}
-This abbreviated example is from the Upbound [AWS Reference Platform](https://github.com/upbound/platform-ref-aws).
+This abbreviated example is from the Upbound 
+[AWS Reference Platform](https://github.com/upbound/platform-ref-aws).
 
 View the complete Compositions in the reference platform's 
 [package directory](https://github.com/upbound/platform-ref-aws/blob/main/package/cluster/composition.yaml).
@@ -445,9 +446,10 @@ Most Compositions require customizing the fields of the resources. This can
 include applying unique passwords, modifying where to deploy resources,
 or applying labels or annotations. 
 
-The primary method to change resources is using a resource [patch and transform]({{<ref "./patch-and-transform" >}}). Patch and transforms allow
-matching specific input fields, modifying them and applying them to the managed
-resource. 
+The primary method to change resources is using a resource 
+[patch and transform]({{<ref "./patch-and-transform" >}}). Patch and transforms 
+allow matching specific input fields, modifying them and applying them to the 
+managed resource. 
 
 {{<hint "important" >}}
 The details of creating patch and transforms and their options are in the 
@@ -594,7 +596,41 @@ spec:
   # Removed for Brevity
 ```
 
-Inside the {{<hover label="envpatch" line="16">}}patches{{</hover>}} of the 
+<!-- these two sections are duplicated in the environment-configs doc --> 
+
+##### Patch a composite resource
+To patch the composite resource use the 
+{{< hover label="xrpatch" line="7">}}patches{{</hover>}} object inside of the 
+{{< hover label="xrpatch" line="5">}}environment{{</hover>}}.
+
+Use the 
+{{< hover label="xrpatch" line="5">}}ToCompositeFieldPath{{</hover>}} to copy
+data from the EnvironmentConfig to the composite resource.  
+Use the 
+{{< hover label="xrpatch" line="5">}}FromCompositeFieldPath{{</hover>}} to copy
+data from the composite resource to the EnvironmentConfig.
+
+```yaml {label="xrpatch",copy-lines="none"}
+apiVersion: apiextensions.crossplane.io/v1
+kind: Composition
+# Removed for Brevity
+spec:
+  environment:
+  # Removed for Brevity
+      patches:
+      - type: ToCompositeFieldPath
+        fromFieldPath: tags
+        toFieldPath: metadata.labels[envTag]
+      - type: FromCompositeFieldPath
+        fromFieldPath: metadata.name
+        toFieldPath: newEnvironmentKey
+```
+
+Individual resources can use any data written to the EnvironmentConfig.
+
+##### Patch an individual resource
+To patch an individual resource, inside the 
+{{<hover label="envpatch" line="16">}}patches{{</hover>}} object of the 
 resource, use 
 {{<hover label="envpatch" line="17">}}ToEnvironmentFieldPath{{</hover>}} to copy
 data from the resource to the EnvironmentConfig.  
@@ -890,7 +926,8 @@ Read the
 for more information on restricting secret keys.
 {{< /hint >}}
 
-For more information on connection secrets read the [Connection Secrets knowledge base article]({{<ref "/knowledge-base/guides/connection-details">}}).
+For more information on connection secrets read the 
+[Connection Secrets knowledge base article]({{<ref "/knowledge-base/guides/connection-details">}}).
 
 {{<hint "warning">}}
 You can't change the 
diff --git a/content/master/concepts/environment-configs.md b/content/master/concepts/environment-configs.md
index 4e6339e28..cb845dae5 100644
--- a/content/master/concepts/environment-configs.md
+++ b/content/master/concepts/environment-configs.md
@@ -12,6 +12,20 @@ patches can read from and write to an environment.
 Crossplane supports multiple EnvironmentConfigs, each acting as a unique
 data store. 
 
+A Composition defines access to one or more EnvironmentConfigs.  
+
+When Crossplane creates a composite resource, Crossplane creates a unique copy
+of the defined EnvironmentConfigs for that composite resource.  
+
+The composite resource can read and write data to their unique 
+EnvironmentConfig.
+
+{{<hint "important" >}}
+EnvironmentConfigs are unique to each composite resource.  
+A composite resource can't read data in an EnvironmentConfig written by another
+composite resource.
+{{< /hint >}}
+
 ## Enable EnvironmentConfigs
 EnvironmentConfigs are an alpha feature. Alpha features aren't enabled by
 default.
@@ -75,20 +89,17 @@ data:
     - item2
 ```
 
-## Patching with EnvironmentConfigs
+<!-- vale Google.Headings = NO -->
+## Select an EnvironmentConfig
+<!-- vale Google.Headings = YES -->
 
-To patch data from or to an EnvironmentConfig, reference the EnvironmentConfig
+Select the EnvironmentConfig to use
 inside a Composition's 
 {{<hover label="comp" line="6">}}environment{{</hover>}} field.
 
 The {{<hover label="comp" line="7">}}environmentConfigs{{</hover>}} field is a
 list of environments this Composition can use. 
 
-{{<hint "tip" >}}
-Read about EnvironmentConfig patch types in the 
-[Patch and Transform]({{<ref "./patch-and-transform">}}) documentation.
-{{< /hint >}}
-
 Select an environment by 
 {{<hover label="comp" line="8">}}Reference{{</hover>}} or 
 by 
@@ -196,90 +207,16 @@ spec:
     - type: Selector
       selector: 
         matchLabels:
-          - key: my-first-label-key
+          - key: my-label-key
             type: Value
-            value: my-first-label-value
-          - key: my-second-label-key
+            value: my-label-value
+          - key: my-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
-```
-
-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
-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
-```
-
-{{<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
 
 Selecting environments by labels may return more than one environment.  
@@ -371,7 +308,94 @@ The environments selected by
 {{<hover label="maxMatch" line="18">}}matchLabels{{</hover>}} are then merged
 into any other environments listed in the 
 {{<hover label="maxMatch" line="7">}}environmentConfigs{{</hover>}}.
+
 <!--
 TODO: Add Policies
-TODO: Add webhook validations
 -->
+
+
+## Patching with EnvironmentConfigs
+
+When Crossplane creates a composite resource, Crossplane creates a unique copy  
+of the EnvironmentConfig for the composite resource. 
+
+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. 
+
+{{<hint "tip" >}}
+Read about EnvironmentConfig patch types in the 
+[Patch and Transform]({{<ref "./patch-and-transform">}}) documentation.
+{{< /hint >}}
+
+<!-- these two sections are duplicated in the compositions doc --> 
+
+### Patching a composite resource
+
+To patch a composite resource use the 
+{{< hover label="xrpatch" line="7">}}patches{{</hover>}} object inside of a
+Composition's 
+{{< hover label="xrpatch" line="5">}}environment{{</hover>}}.
+
+Use the 
+{{< hover label="xrpatch" line="5">}}ToCompositeFieldPath{{</hover>}} to copy
+data from the EnvironmentConfig to the composite resource.  
+Use the 
+{{< hover label="xrpatch" line="5">}}FromCompositeFieldPath{{</hover>}} to copy
+data from the composite resource to the EnvironmentConfig.
+
+```yaml {label="xrpatch",copy-lines="none"}
+apiVersion: apiextensions.crossplane.io/v1
+kind: Composition
+# Removed for Brevity
+spec:
+  environment:
+  # Removed for Brevity
+      patches:
+      - type: ToCompositeFieldPath
+        fromFieldPath: tags
+        toFieldPath: metadata.labels[envTag]
+      - type: FromCompositeFieldPath
+        fromFieldPath: metadata.name
+        toFieldPath: newEnvironmentKey
+```
+
+Individual resources can use any data written to the EnvironmentConfig.
+
+##### Patch an individual resource
+
+To patch an individual resource, inside the 
+{{<hover label="envpatch" line="16">}}patches{{</hover>}} object of the 
+resource, use 
+{{<hover label="envpatch" line="17">}}ToEnvironmentFieldPath{{</hover>}} to copy
+data from the resource to the EnvironmentConfig.  
+Use {{<hover label="envpatch" line="20">}}FromEnvironmentFieldPath{{</hover>}}
+to copy data to the resource from the EnvironmentConfig.
+
+```yaml {label="envpatch",copy-lines="none"}
+apiVersion: apiextensions.crossplane.io/v1
+kind: Composition
+# Removed for Brevity
+spec:
+  environment:
+  # Removed for Brevity
+  resources:
+  # Removed for Brevity
+    - name: vpc
+      base:
+        apiVersion: ec2.aws.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
+```
+
+The [Patch and Transform]({{<ref "./patch-and-transform">}}) documentation has
+more information on patching individual resources.
\ No newline at end of file
diff --git a/content/master/concepts/patch-and-transform.md b/content/master/concepts/patch-and-transform.md
index e9da99f12..d6fcf5612 100644
--- a/content/master/concepts/patch-and-transform.md
+++ b/content/master/concepts/patch-and-transform.md
@@ -81,8 +81,7 @@ object, including the `metadata`, `spec` or `status` fields.
 Field selectors can be a string matching a field name or an array index, in
 brackets. Field names may use a `.` character to select child elements.
 
-
-{{< expand "Example field selectors" >}}
+#### Example field selectors
 Here are some example selectors from a composite resource object.
 {{<table "table" >}}
 | Selector | Selected element | 
@@ -118,7 +117,6 @@ spec:
     name: my-example-claim-978mh-rv5nm
   # Removed for brevity
 ```
-{{< /expand >}}
 
 ## Reuse a patch
 
@@ -297,6 +295,17 @@ Labels:       crossplane.io/composite=my-example-claim-jp7rx
 Crossplane supports multiple patch types, each using a different source for data
 and applying the patch to a different location. 
 
+{{<hint "important" >}}
+
+This section describes patches applied to individual resources inside a
+Composition.  
+
+For information about applying patches to an entire composite resource with a
+Composition's `environment.patches` read the 
+[Environment Configurations]({{<ref "environment-configs" >}}) documentation.
+
+{{< /hint >}}
+
 Summary of Crossplane patches
 {{< table "table table-hover" >}}
 | Patch Type | Data Source | Data Destination | 
@@ -797,10 +806,6 @@ For example, use the desired
 apply it as the environment's
 {{<hover label="toEnvField" line="14">}}key1{{</hover>}}.
 
-{{< hint "important" >}}
-The environment's key must already exist. Patches can't create new environment
-keys. 
-{{< /hint >}}
 
 ```yaml {label="toEnvField",copy-lines="9-11"}
 apiVersion: apiextensions.crossplane.io/v1
@@ -1562,6 +1567,9 @@ converts the input based on one of the following conversion types:
 * `ToSha1` - Create a SHA-1 hash of the input string.
 * `ToSha256` - Create a SHA-256 hash of the input string.
 * `ToSha512` - Create a SHA-512 hash of the input string.
+* `ToSha512` - Create a SHA-512 hash of the input string.
+* `ToAdler32` - Create an Adler32 hash of the input string.
+* `ToSha512` - Create a SHA-512 hash of the input string. 
 * `ToAdler32` - Create an Adler32 hash of the input string.
 
 ```yaml {label="stringConvert"}
diff --git a/content/v1.13/concepts/compositions.md b/content/v1.13/concepts/compositions.md
index 7cce82ad8..7a48285fd 100644
--- a/content/v1.13/concepts/compositions.md
+++ b/content/v1.13/concepts/compositions.md
@@ -596,7 +596,41 @@ spec:
   # Removed for Brevity
 ```
 
-Inside the {{<hover label="envpatch" line="16">}}patches{{</hover>}} of the 
+<!-- these two sections are duplicated in the environment-configs doc --> 
+
+##### Patch a composite resource
+To patch the composite resource use the 
+{{< hover label="xrpatch" line="7">}}patches{{</hover>}} object inside of the 
+{{< hover label="xrpatch" line="5">}}environment{{</hover>}}.
+
+Use the 
+{{< hover label="xrpatch" line="5">}}ToCompositeFieldPath{{</hover>}} to copy
+data from the EnvironmentConfig to the composite resource.  
+Use the 
+{{< hover label="xrpatch" line="5">}}FromCompositeFieldPath{{</hover>}} to copy
+data from the composite resource to the EnvironmentConfig.
+
+```yaml {label="xrpatch",copy-lines="none"}
+apiVersion: apiextensions.crossplane.io/v1
+kind: Composition
+# Removed for Brevity
+spec:
+  environment:
+  # Removed for Brevity
+      patches:
+      - type: ToCompositeFieldPath
+        fromFieldPath: tags
+        toFieldPath: metadata.labels[envTag]
+      - type: FromCompositeFieldPath
+        fromFieldPath: metadata.name
+        toFieldPath: newEnvironmentKey
+```
+
+Individual resources can use any data written to the EnvironmentConfig.
+
+##### Patch an individual resource
+To patch an individual resource, inside the 
+{{<hover label="envpatch" line="16">}}patches{{</hover>}} object of the 
 resource, use 
 {{<hover label="envpatch" line="17">}}ToEnvironmentFieldPath{{</hover>}} to copy
 data from the resource to the EnvironmentConfig.  
diff --git a/content/v1.13/concepts/environment-configs.md b/content/v1.13/concepts/environment-configs.md
index 74dc3f13f..cb845dae5 100644
--- a/content/v1.13/concepts/environment-configs.md
+++ b/content/v1.13/concepts/environment-configs.md
@@ -12,6 +12,20 @@ patches can read from and write to an environment.
 Crossplane supports multiple EnvironmentConfigs, each acting as a unique
 data store. 
 
+A Composition defines access to one or more EnvironmentConfigs.  
+
+When Crossplane creates a composite resource, Crossplane creates a unique copy
+of the defined EnvironmentConfigs for that composite resource.  
+
+The composite resource can read and write data to their unique 
+EnvironmentConfig.
+
+{{<hint "important" >}}
+EnvironmentConfigs are unique to each composite resource.  
+A composite resource can't read data in an EnvironmentConfig written by another
+composite resource.
+{{< /hint >}}
+
 ## Enable EnvironmentConfigs
 EnvironmentConfigs are an alpha feature. Alpha features aren't enabled by
 default.
@@ -75,20 +89,17 @@ data:
     - item2
 ```
 
-## Patching with EnvironmentConfigs
+<!-- vale Google.Headings = NO -->
+## Select an EnvironmentConfig
+<!-- vale Google.Headings = YES -->
 
-To patch data from or to an EnvironmentConfig, reference the EnvironmentConfig
+Select the EnvironmentConfig to use
 inside a Composition's 
 {{<hover label="comp" line="6">}}environment{{</hover>}} field.
 
 The {{<hover label="comp" line="7">}}environmentConfigs{{</hover>}} field is a
 list of environments this Composition can use. 
 
-{{<hint "tip" >}}
-Read about EnvironmentConfig patch types in the 
-[Patch and Transform]({{<ref "./patch-and-transform">}}) documentation.
-{{< /hint >}}
-
 Select an environment by 
 {{<hover label="comp" line="8">}}Reference{{</hover>}} or 
 by 
@@ -297,7 +308,94 @@ The environments selected by
 {{<hover label="maxMatch" line="18">}}matchLabels{{</hover>}} are then merged
 into any other environments listed in the 
 {{<hover label="maxMatch" line="7">}}environmentConfigs{{</hover>}}.
+
 <!--
 TODO: Add Policies
-TODO: Add webhook validations
 -->
+
+
+## Patching with EnvironmentConfigs
+
+When Crossplane creates a composite resource, Crossplane creates a unique copy  
+of the EnvironmentConfig for the composite resource. 
+
+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. 
+
+{{<hint "tip" >}}
+Read about EnvironmentConfig patch types in the 
+[Patch and Transform]({{<ref "./patch-and-transform">}}) documentation.
+{{< /hint >}}
+
+<!-- these two sections are duplicated in the compositions doc --> 
+
+### Patching a composite resource
+
+To patch a composite resource use the 
+{{< hover label="xrpatch" line="7">}}patches{{</hover>}} object inside of a
+Composition's 
+{{< hover label="xrpatch" line="5">}}environment{{</hover>}}.
+
+Use the 
+{{< hover label="xrpatch" line="5">}}ToCompositeFieldPath{{</hover>}} to copy
+data from the EnvironmentConfig to the composite resource.  
+Use the 
+{{< hover label="xrpatch" line="5">}}FromCompositeFieldPath{{</hover>}} to copy
+data from the composite resource to the EnvironmentConfig.
+
+```yaml {label="xrpatch",copy-lines="none"}
+apiVersion: apiextensions.crossplane.io/v1
+kind: Composition
+# Removed for Brevity
+spec:
+  environment:
+  # Removed for Brevity
+      patches:
+      - type: ToCompositeFieldPath
+        fromFieldPath: tags
+        toFieldPath: metadata.labels[envTag]
+      - type: FromCompositeFieldPath
+        fromFieldPath: metadata.name
+        toFieldPath: newEnvironmentKey
+```
+
+Individual resources can use any data written to the EnvironmentConfig.
+
+##### Patch an individual resource
+
+To patch an individual resource, inside the 
+{{<hover label="envpatch" line="16">}}patches{{</hover>}} object of the 
+resource, use 
+{{<hover label="envpatch" line="17">}}ToEnvironmentFieldPath{{</hover>}} to copy
+data from the resource to the EnvironmentConfig.  
+Use {{<hover label="envpatch" line="20">}}FromEnvironmentFieldPath{{</hover>}}
+to copy data to the resource from the EnvironmentConfig.
+
+```yaml {label="envpatch",copy-lines="none"}
+apiVersion: apiextensions.crossplane.io/v1
+kind: Composition
+# Removed for Brevity
+spec:
+  environment:
+  # Removed for Brevity
+  resources:
+  # Removed for Brevity
+    - name: vpc
+      base:
+        apiVersion: ec2.aws.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
+```
+
+The [Patch and Transform]({{<ref "./patch-and-transform">}}) documentation has
+more information on patching individual resources.
\ No newline at end of file
diff --git a/content/v1.13/concepts/patch-and-transform.md b/content/v1.13/concepts/patch-and-transform.md
index 410290f5d..45e2d5e81 100644
--- a/content/v1.13/concepts/patch-and-transform.md
+++ b/content/v1.13/concepts/patch-and-transform.md
@@ -81,8 +81,7 @@ object, including the `metadata`, `spec` or `status` fields.
 Field selectors can be a string matching a field name or an array index, in
 brackets. Field names may use a `.` character to select child elements.
 
-
-{{< expand "Example field selectors" >}}
+#### Example field selectors
 Here are some example selectors from a composite resource object.
 {{<table "table" >}}
 | Selector | Selected element | 
@@ -118,7 +117,6 @@ spec:
     name: my-example-claim-978mh-rv5nm
   # Removed for brevity
 ```
-{{< /expand >}}
 
 ## Reuse a patch
 
@@ -297,6 +295,17 @@ Labels:       crossplane.io/composite=my-example-claim-jp7rx
 Crossplane supports multiple patch types, each using a different source for data
 and applying the patch to a different location. 
 
+{{<hint "important" >}}
+
+This section describes patches applied to individual resources inside a
+Composition.  
+
+For information about applying patches to an entire composite resource with a
+Composition's `environment.patches` read the 
+[Environment Configurations]({{<ref "environment-configs" >}}) documentation.
+
+{{< /hint >}}
+
 Summary of Crossplane patches
 {{< table "table table-hover" >}}
 | Patch Type | Data Source | Data Destination | 
@@ -797,10 +806,6 @@ For example, use the desired
 apply it as the environment's
 {{<hover label="toEnvField" line="14">}}key1{{</hover>}}.
 
-{{< hint "important" >}}
-The environment's key must already exist. Patches can't create new environment
-keys. 
-{{< /hint >}}
 
 ```yaml {label="toEnvField",copy-lines="9-11"}
 apiVersion: apiextensions.crossplane.io/v1