Skip to content

Commit

Permalink
Update guidlines on envConfigs and patching to XRs
Browse files Browse the repository at this point in the history 
Signed-off-by: Pete Lumbis <pete@upbound.io>
  • Loading branch information
@plumbis
plumbis committed Sep 14, 2023
1 parent 0d34b4a commit ebd0a08
Show file tree
Hide file tree
Showing 6 changed files with 321 additions and 115 deletions.
51 changes: 44 additions & 7 deletions content/master/concepts/compositions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.


Expand Down Expand Up @@ -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).
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down
194 changes: 109 additions & 85 deletions content/master/concepts/environment-configs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
22 changes: 15 additions & 7 deletions content/master/concepts/patch-and-transform.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -118,7 +117,6 @@ spec:
name: my-example-claim-978mh-rv5nm
# Removed for brevity
```
{{< /expand >}}

## Reuse a patch

Expand Down Expand Up @@ -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 |
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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"}
Expand Down
Loading

0 comments on commit ebd0a08

Please sign in to comment.