Updates based on PR feedback

Signed-off-by: Pete Lumbis <pete@upbound.io>
crossplane · Sep 15, 2023 · d4d7edd · d4d7edd
1 parent ebd0a08
commit d4d7edd
Show file tree

Hide file tree

Showing 5 changed files with 67 additions and 76 deletions.
diff --git a/content/master/concepts/compositions.md b/content/master/concepts/compositions.md
@@ -550,16 +550,16 @@ spec:
 
 #### Patch with EnvironmentConfigs 
 
-Crossplane uses EnvironmentConfigs as an in-memory data store. Compositions can
-read and write from this data store as part of the patch process. 
+Crossplane uses EnvironmentConfigs to create in-memory data stores. Compositions 
+can read and write from this data store as part of the patch process. 
 
 {{<hint "important" >}}
 EnvironmentConfigs are an alpha feature. Alpha features aren't enabled by
 default. 
 {{< /hint >}}
 
  EnvironmentConfigs can predefine data that Compositions can use
- or a Composite Resource can write data to the EnvironmentConfig for other
+ or a Composite Resource can write data to their in-memory environment for other
  resources to read. 
 
 <!-- vale off -->
@@ -569,18 +569,17 @@ Read the [EnvironmentConfigs]({{<ref "./environment-configs" >}}) page for
 more information on using EnvironmentConfigs.
 {{< /hint >}}
 
-To apply a patch using EnvironmentConfigs, first define which EnvironmentConfig
+To apply a patch using EnvironmentConfigs, first define which EnvironmentConfigs
 to use with 
-{{<hover label="envselect"
-line="6">}}environment.environmentConfigs{{</hover>}}. 
+{{<hover label="envselect" line="6">}}environment.environmentConfigs{{</hover>}}. 
 
 <!-- vale Google.Quotes = NO -->
 <!-- vale gitlab.SentenceLength = NO -->
 <!-- ignore false positive -->
 Use either a
 [reference]({{<ref "./managed-resources#matching-by-name-reference" >}})
 or a [selector]({{<ref "./managed-resources#matching-by-selector" >}}) to
-identify the EnvironmentConfig to use.
+identify the EnvironmentConfigs to use.
 <!-- vale Google.Quotes = YES -->
 
 ```yaml {label="envselect",copy-lines="none"}
@@ -599,16 +598,16 @@ spec:
 <!-- 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 
+To patch the composite resource use
+{{< hover label="xrpatch" line="7">}}patches{{</hover>}} 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.  
+data from the in-memory environment to the composite resource.  
 Use the 
 {{< hover label="xrpatch" line="5">}}FromCompositeFieldPath{{</hover>}} to copy
-data from the composite resource to the EnvironmentConfig.
+data from the composite resource to the in-memory environment.
 
 ```yaml {label="xrpatch",copy-lines="none"}
 apiVersion: apiextensions.crossplane.io/v1
@@ -626,16 +625,16 @@ spec:
         toFieldPath: newEnvironmentKey
 ```
 
-Individual resources can use any data written to the EnvironmentConfig.
+Individual resources can use any data written to their in-memory environment.
 
 ##### Patch an individual resource
 To patch an individual resource, inside the 
-{{<hover label="envpatch" line="16">}}patches{{</hover>}} object of the 
+{{<hover label="envpatch" line="16">}}patches{{</hover>}} of the 
 resource, use 
 {{<hover label="envpatch" line="17">}}ToEnvironmentFieldPath{{</hover>}} to copy
-data from the resource to the EnvironmentConfig.  
+data from the resource to the in-memory environment.  
 Use {{<hover label="envpatch" line="20">}}FromEnvironmentFieldPath{{</hover>}}
-to copy data to the resource from the EnvironmentConfig.
+to copy data to the resource from the in-memory environment.
 
 ```yaml {label="envpatch",copy-lines="none"}
 apiVersion: apiextensions.crossplane.io/v1

diff --git a/content/master/concepts/environment-configs.md b/content/master/concepts/environment-configs.md
@@ -6,24 +6,25 @@ alphaVersion: "1.11"
 description: "Environment Configurations or EnvironmentConfigs are an in-memory datastore used in patching Compositions"
 ---
 
-A Crossplane EnvironmentConfig is an in-memory data store. Composition 
-patches can read from and write to an environment.
+A Crossplane EnvironmentConfig is a cluster scoped 
+[ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) used
+by Compositions. Compositions can use the environment to store information from
+individual resources or to apply [patches]({{<ref "patch-and-transform">}}).
 
 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.  
+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 
-EnvironmentConfig.
+in-memory environment.
 
 {{<hint "important" >}}
-EnvironmentConfigs are unique to each composite resource.  
-A composite resource can't read data in an EnvironmentConfig written by another
-composite resource.
+The in-memory environment is unique to each composite resource.  
+A composite resource can't read data in another composite resource's
+environment. 
 {{< /hint >}}
 
 ## Enable EnvironmentConfigs
@@ -93,7 +94,7 @@ data:
 ## Select an EnvironmentConfig
 <!-- vale Google.Headings = YES -->
 
-Select the EnvironmentConfig to use
+Select the EnvironmentConfigs to use
 inside a Composition's 
 {{<hover label="comp" line="6">}}environment{{</hover>}} field.
 
@@ -316,8 +317,8 @@ TODO: Add Policies
 
 ## Patching with EnvironmentConfigs
 
-When Crossplane creates a composite resource, Crossplane creates a unique copy  
-of the EnvironmentConfig for the composite resource. 
+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
@@ -330,19 +331,17 @@ Read about EnvironmentConfig patch types in the
 
 <!-- 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 
+##### Patch a composite resource
+To patch the composite resource use
+{{< hover label="xrpatch" line="7">}}patches{{</hover>}} 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.  
+data from the in-memory environment to the composite resource.  
 Use the 
 {{< hover label="xrpatch" line="5">}}FromCompositeFieldPath{{</hover>}} to copy
-data from the composite resource to the EnvironmentConfig.
+data from the composite resource to the in-memory environment.
 
 ```yaml {label="xrpatch",copy-lines="none"}
 apiVersion: apiextensions.crossplane.io/v1
@@ -360,17 +359,16 @@ spec:
         toFieldPath: newEnvironmentKey
 ```
 
-Individual resources can use any data written to the EnvironmentConfig.
+Individual resources can use any data written to the in-memory environment.
 
 ##### Patch an individual resource
-
 To patch an individual resource, inside the 
-{{<hover label="envpatch" line="16">}}patches{{</hover>}} object of the 
+{{<hover label="envpatch" line="16">}}patches{{</hover>}} of the 
 resource, use 
 {{<hover label="envpatch" line="17">}}ToEnvironmentFieldPath{{</hover>}} to copy
-data from the resource to the EnvironmentConfig.  
+data from the resource to the in-memory environment.  
 Use {{<hover label="envpatch" line="20">}}FromEnvironmentFieldPath{{</hover>}}
-to copy data to the resource from the EnvironmentConfig.
+to copy data to the resource from the in-memory environment.
 
 ```yaml {label="envpatch",copy-lines="none"}
 apiVersion: apiextensions.crossplane.io/v1

diff --git a/content/master/concepts/patch-and-transform.md b/content/master/concepts/patch-and-transform.md
@@ -1567,9 +1567,6 @@ 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
@@ -550,16 +550,16 @@ spec:
 
 #### Patch with EnvironmentConfigs 
 
-Crossplane uses EnvironmentConfigs as an in-memory data store. Compositions can
-read and write from this data store as part of the patch process. 
+Crossplane uses EnvironmentConfigs to create in-memory data stores. Compositions 
+can read and write from this data store as part of the patch process. 
 
 {{<hint "important" >}}
 EnvironmentConfigs are an alpha feature. Alpha features aren't enabled by
 default. 
 {{< /hint >}}
 
  EnvironmentConfigs can predefine data that Compositions can use
- or a Composite Resource can write data to the EnvironmentConfig for other
+ or a Composite Resource can write data to their in-memory environment for other
  resources to read. 
 
 <!-- vale off -->
@@ -569,18 +569,17 @@ Read the [EnvironmentConfigs]({{<ref "./environment-configs" >}}) page for
 more information on using EnvironmentConfigs.
 {{< /hint >}}
 
-To apply a patch using EnvironmentConfigs, first define which EnvironmentConfig
+To apply a patch using EnvironmentConfigs, first define which EnvironmentConfigs
 to use with 
-{{<hover label="envselect"
-line="6">}}environment.environmentConfigs{{</hover>}}. 
+{{<hover label="envselect" line="6">}}environment.environmentConfigs{{</hover>}}. 
 
 <!-- vale Google.Quotes = NO -->
 <!-- vale gitlab.SentenceLength = NO -->
 <!-- ignore false positive -->
 Use either a
 [reference]({{<ref "./managed-resources#matching-by-name-reference" >}})
 or a [selector]({{<ref "./managed-resources#matching-by-selector" >}}) to
-identify the EnvironmentConfig to use.
+identify the EnvironmentConfigs to use.
 <!-- vale Google.Quotes = YES -->
 
 ```yaml {label="envselect",copy-lines="none"}
@@ -599,16 +598,16 @@ spec:
 <!-- 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 
+To patch the composite resource use
+{{< hover label="xrpatch" line="7">}}patches{{</hover>}} 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.  
+data from the in-memory environment to the composite resource.  
 Use the 
 {{< hover label="xrpatch" line="5">}}FromCompositeFieldPath{{</hover>}} to copy
-data from the composite resource to the EnvironmentConfig.
+data from the composite resource to the in-memory environment.
 
 ```yaml {label="xrpatch",copy-lines="none"}
 apiVersion: apiextensions.crossplane.io/v1
@@ -626,16 +625,16 @@ spec:
         toFieldPath: newEnvironmentKey
 ```
 
-Individual resources can use any data written to the EnvironmentConfig.
+Individual resources can use any data written to their in-memory environment.
 
 ##### Patch an individual resource
 To patch an individual resource, inside the 
-{{<hover label="envpatch" line="16">}}patches{{</hover>}} object of the 
+{{<hover label="envpatch" line="16">}}patches{{</hover>}} of the 
 resource, use 
 {{<hover label="envpatch" line="17">}}ToEnvironmentFieldPath{{</hover>}} to copy
-data from the resource to the EnvironmentConfig.  
+data from the resource to the in-memory environment.  
 Use {{<hover label="envpatch" line="20">}}FromEnvironmentFieldPath{{</hover>}}
-to copy data to the resource from the EnvironmentConfig.
+to copy data to the resource from the in-memory environment.
 
 ```yaml {label="envpatch",copy-lines="none"}
 apiVersion: apiextensions.crossplane.io/v1

diff --git a/content/v1.13/concepts/environment-configs.md b/content/v1.13/concepts/environment-configs.md
@@ -14,16 +14,17 @@ 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.  
+When Crossplane creates a composite resource, Crossplane merges all referenced
+EnvironmentConfigs and creates a unique in-memory environment
+for that composite resource.  
 
 The composite resource can read and write data to their unique 
-EnvironmentConfig.
+in-memory environment.
 
 {{<hint "important" >}}
-EnvironmentConfigs are unique to each composite resource.  
-A composite resource can't read data in an EnvironmentConfig written by another
-composite resource.
+The in-memory environment is unique to each composite resource.  
+A composite resource can't read data in another composite resource's
+environment. 
 {{< /hint >}}
 
 ## Enable EnvironmentConfigs
@@ -330,19 +331,17 @@ Read about EnvironmentConfig patch types in the
 
 <!-- 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 
+##### Patch a composite resource
+To patch the composite resource use
+{{< hover label="xrpatch" line="7">}}patches{{</hover>}} 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.  
+data from the in-memory environment to the composite resource.  
 Use the 
 {{< hover label="xrpatch" line="5">}}FromCompositeFieldPath{{</hover>}} to copy
-data from the composite resource to the EnvironmentConfig.
+data from the composite resource to the in-memory environment.
 
 ```yaml {label="xrpatch",copy-lines="none"}
 apiVersion: apiextensions.crossplane.io/v1
@@ -360,17 +359,16 @@ spec:
         toFieldPath: newEnvironmentKey
 ```
 
-Individual resources can use any data written to the EnvironmentConfig.
+Individual resources can use any data written to the in-memory environment.
 
 ##### Patch an individual resource
-
 To patch an individual resource, inside the 
-{{<hover label="envpatch" line="16">}}patches{{</hover>}} object of the 
+{{<hover label="envpatch" line="16">}}patches{{</hover>}} of the 
 resource, use 
 {{<hover label="envpatch" line="17">}}ToEnvironmentFieldPath{{</hover>}} to copy
-data from the resource to the EnvironmentConfig.  
+data from the resource to the in-memory environment.  
 Use {{<hover label="envpatch" line="20">}}FromEnvironmentFieldPath{{</hover>}}
-to copy data to the resource from the EnvironmentConfig.
+to copy data to the resource from the in-memory environment.
 
 ```yaml {label="envpatch",copy-lines="none"}
 apiVersion: apiextensions.crossplane.io/v1