crossplane
/
docs
mirror of https://github.com/crossplane/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #799 from negz/its-happening-dot-gif 

Promote composition functions to v1
This commit is contained in:
Nic Cope 2024-08-23 12:41:19 -07:00 committed by GitHub
parent 9ad499b858 dd01aa1141
commit cc113034d4
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
42 changed files with 3785 additions and 4959 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

373
content/master/cli/command-reference.md
View File

@ -32,6 +32,135 @@ Client Version: v1.16.0
Server Version: v1.16.0
```
## render
The `crossplane render` command previews the output of a
[composite resource]({{<ref "../concepts/composite-resources">}}) after applying
any [composition functions]({{<ref "../concepts/compositions">}}).
{{< hint "important" >}}
The `crossplane render` command requires you to use composition functions.
{{< /hint >}}
The `crossplane render` command connects to the locally running Docker
Engine to pull and run composition functions.
{{<hint "important">}}
Running `crossplane render` requires [Docker](https://www.docker.com/).
{{< /hint >}}
Provide a composite resource, composition and composition function YAML
definition with the command to render the output locally.
For example,
`crossplane render xr.yaml composition.yaml function.yaml`
The output includes the original composite resource followed by the generated
managed resources.
{{<expand "An example render output" >}}
```yaml
---
apiVersion: nopexample.org/v1
kind: XBucket
metadata:
name: test-xrender
status:
bucketRegion: us-east-2
---
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
metadata:
annotations:
crossplane.io/composition-resource-name: my-bucket
generateName: test-xrender-
labels:
crossplane.io/composite: test-xrender
ownerReferences:
- apiVersion: nopexample.org/v1
blockOwnerDeletion: true
controller: true
kind: XBucket
name: test-xrender
uid: ""
spec:
forProvider:
region: us-east-2
```
{{< /expand >}}
### Flags
{{< table "table table-sm table-striped">}}
| Short flag | Long flag | Description |
| ------------ | ------------- | ------------------------------ |
| | `--context-files=<key>=<file>,<key>=<file>` | A comma separated list of files to load for function "contexts." |
| | `--context-values=<key>=<value>,<key>=<value>` | A comma separated list of key-value pairs to load for function "contexts." |
| `-r` | `--include-function-results` | Include the "results" or events from the function. |
| `-o` | `--observed-resources=<directory or file>` |
Provide artificial managed resource data to the function.
|
| `-x` | `--include-full-xr` | Include a copy of the input Composite Resource spec and metadata fields in the rendered output. |
| | `--timeout=` | Amount of time to wait for a function to finish. (Default 1 minute) |
{{< /table >}}
The `crossplane render` command relies on standard
[Docker environmental variables](https://docs.docker.com/engine/reference/commandline/cli/#environment-variables)
to connect to the local Docker Engine and run composition functions.
### Provide function context
The `--context-files` and `--context-values` flags can provide data
to a function's `context`.
The context is JSON formatted data.
### Include function results
If a function produces Kubernetes events with statuses use the
`--include-function-results` to print them along with the managed resource
outputs.
### Include the composite resource
Composition functions can only change the `status` field of a composite
resource. By default, the `crossplane render` command only prints the
`status` field with `metadata.name`.
Use `--include-full-xr` to print the full composite resource,
including the `spec` and `metadata` fields.
### Mock managed resources
Provide mocked, or artificial data representing a managed resource with
`--observed-resources`. The `crossplane render` command treats the
provided inputs as if they were resources in a Crossplane cluster.
A function can reference and manipulate the included resource as part of
running the function.
The `observed-resources` may be a single YAML file with multiple resources or a
directory of YAML files representing multiple resources.
Inside the YAML file include an
{{<hover label="apiVersion" line="1">}}apiVersion{{</hover>}},
{{<hover label="apiVersion" line="2">}}kind{{</hover>}},
{{<hover label="apiVersion" line="3">}}metadata{{</hover>}} and
{{<hover label="apiVersion" line="7">}}spec{{</hover>}}.
```yaml {label="apiVersion"}
apiVersion: example.org/v1alpha1
kind: ComposedResource
metadata:
name: test-render-b
annotations:
crossplane.io/composition-resource-name: resource-b
spec:
coolerField: "I'm cooler!"
```
The schema of the resource isn't validated and may contain any data.
## xpkg
The `crossplane xpkg` commands create, install and update Crossplane
@ -51,7 +180,7 @@ The CLI applies the required annotations and values to meet the
The `crossplane` CLI supports building
[configuration]({{< ref "../concepts/packages" >}}),
[function]({{<ref "../concepts/composition-functions">}}) and
[function]({{<ref "../concepts/compositions">}}) and
[provider]({{<ref "../concepts/providers" >}}) package types.
@ -117,6 +246,52 @@ Use `docker pull` to download a missing image.
The `--embed-runtime-image-tarball` flag includes a local OCI image tarball
inside the function or provider package.
### xpkg init
The `crossplane xpkg init` command populates the current directory with
files to build a package.
Provide a name to use for the package and the package template to start from
with the command
`crossplane xpkg init <name> <template>`
The `<name>` input isn't used. Crossplane reserves the `<name>` for future releases.
The `<template>` value may be one of four well known templates:
* `configuration-template` - A template to build a Crossplane [Configuration]({{<ref "../concepts/packages">}}) from the [crossplane/configuration-template](https://github.com/crossplane/configuration-template) repository.
* `function-template-go` - A template to build Crossplane Go [composition functions]({{<ref "../concepts/compositions">}}) from the [crossplane/function-template-go](https://github.com/crossplane/function-template-go) repository.
* `function-template-python` - A template to build Crossplane Python [composition functions]({{<ref "../concepts/compositions">}}) from the [crossplane/function-template-python](https://github.com/crossplane/function-template-go) repository.
* `provider-template` - A template to build a basic Crossplane provider from the [Crossplane/provider-template](https://github.com/crossplane/provider-template) repository.
* `provider-template-upjet` - A template for building [Upjet](https://github.com/crossplane/upjet) based Crossplane providers from existing Terraform providers. Copies from the [upbound/upjet-provider-template](https://github.com/upbound/upjet-provider-template) repository.
Instead of a well known template the `<template>` value can be a git repository
URL.
#### NOTES.txt
If the template repository contains a `NOTES.txt` file in its root directory,
the `crossplane xpkg init` command prints the contents of the file to the
terminal after populating the directory with the template files. This can be
useful for providing information about the template.
#### init.sh
If the template repository contains an `init.sh` file in its root directory, the
`crossplane xpkg init` command starts a dialog after populating the
directory with the template files. The dialog prompts the user if they want
to view or run the script. Use the initialization script to automatically
personalize the template.
#### Flags
{{< table "table table-sm table-striped">}}
| Short flag | Long flag | Description |
| ------------ | ----------------------- | ------------------------------ |
| `-b` | `--ref-name` | The branch or tag to clone from the template repository. |
| `-d` | `--directory` | The directory to create and load the template files into. Uses the current directory by default. |
| `-r` | `--run-init-script` | Run the init.sh script without prompting, if it exists. |
<!-- vale Crossplane.Spelling = YES -->
{{< /table >}}
### xpkg install
@ -341,9 +516,8 @@ converts a Crossplane resource to a new version or kind.
Use the `crossplane beta convert` command to convert an existing
[ControllerConfig]({{<ref "../concepts/providers#controller-configuration">}})
to a [DeploymentRuntimeConfig]({{<ref "../concepts/providers#runtime-configuration">}})
or a Composition using [patch and transforms]({{<ref "../concepts/patch-and-transform">}})
to a
[Composition pipeline function]({{< ref "../concepts/compositions#use-composition-functions" >}}).
or a legacy Composition using `mode: Resources` to a
[Composition pipeline function]({{< ref "../concepts/compositions" >}}).
Provide the `crossplane beta convert` command the conversion type, the input
file and optionally, an output file. By default the command writes the output to
@ -373,138 +547,6 @@ By default the function name is "function-patch-and-transform."
{{< /table >}}
### beta render
The `crossplane beta render` command previews the output of a
[composite resource]({{<ref "../concepts/composite-resources">}}) after applying
any [composition functions]({{<ref "../concepts/composition-functions">}}).
{{< hint "important" >}}
The `crossplane beta render` command doesn't apply
[patch and transform composition patches]({{<ref "../concepts/patch-and-transform">}}).
The command only supports function "patch and transforms."
{{< /hint >}}
The `crossplane beta render` command connects to the locally running Docker
Engine to pull and run composition functions.
{{<hint "important">}}
Running `crossplane beta render` requires [Docker](https://www.docker.com/).
{{< /hint >}}
Provide a composite resource, composition and composition function YAML
definition with the command to render the output locally.
For example,
`crossplane beta render xr.yaml composition.yaml function.yaml`
The output includes the original composite resource followed by the generated
managed resources.
{{<expand "An example render output" >}}
```yaml
---
apiVersion: nopexample.org/v1
kind: XBucket
metadata:
name: test-xrender
status:
bucketRegion: us-east-2
---
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
metadata:
annotations:
crossplane.io/composition-resource-name: my-bucket
generateName: test-xrender-
labels:
crossplane.io/composite: test-xrender
ownerReferences:
- apiVersion: nopexample.org/v1
blockOwnerDeletion: true
controller: true
kind: XBucket
name: test-xrender
uid: ""
spec:
forProvider:
region: us-east-2
```
{{< /expand >}}
#### Flags
{{< table "table table-sm table-striped">}}
| Short flag | Long flag | Description |
| ------------ | ------------- | ------------------------------ |
| | `--context-files=<key>=<file>,<key>=<file>` | A comma separated list of files to load for function "contexts." |
| | `--context-values=<key>=<value>,<key>=<value>` | A comma separated list of key-value pairs to load for function "contexts." |
| `-r` | `--include-function-results` | Include the "results" or events from the function. |
| `-o` | `--observed-resources=<directory or file>` |
Provide artificial managed resource data to the function.
|
| `-x` | `--include-full-xr` | Include a copy of the input Composite Resource spec and metadata fields in the rendered output. |
| | `--timeout=` | Amount of time to wait for a function to finish. |
{{< /table >}}
The `crossplane beta render` command relies on standard
[Docker environmental variables](https://docs.docker.com/engine/reference/commandline/cli/#environment-variables)
to connect to the local Docker engine and run composition functions.
#### Provide function context
The `--context-files` and `--context-values` flags can provide data
to a function's `context`.
The context is JSON formatted data.
#### Include function results
If a function produces Kubernetes events with statuses use the
`--include-function-results` to print them along with the managed resource
outputs.
#### Include the composite resource
Composition functions can only change the `status` field of a composite
resource. By default, the `crossplane beta render` command only prints the
`status` field with `metadata.name`.
Use `--include-full-xr` to print the full composite resource,
including the `spec` and `metadata` fields.
#### Mock managed resources
Provide mocked, or artificial data representing a managed resource with
`--observed-resources`. The `crossplane beta render` command treats the
provided inputs as if they were resources in a Crossplane cluster.
A function can reference and manipulate the included resource as part of
running the function.
The `observed-resources` may be a single YAML file with multiple resources or a
directory of YAML files representing multiple resources.
Inside the YAML file include an
{{<hover label="apiVersion" line="1">}}apiVersion{{</hover>}},
{{<hover label="apiVersion" line="2">}}kind{{</hover>}},
{{<hover label="apiVersion" line="3">}}metadata{{</hover>}} and
{{<hover label="apiVersion" line="7">}}spec{{</hover>}}.
```yaml {label="apiVersion"}
apiVersion: example.org/v1alpha1
kind: ComposedResource
metadata:
name: test-render-b
annotations:
crossplane.io/composition-resource-name: resource-b
spec:
coolerField: "I'm cooler!"
```
The schema of the resource isn't validated and may contain any data.
### beta top
The command `crossplane beta top` shows CPU and memory usage of Crossplane
@ -837,7 +879,7 @@ scenarios:
- Validate a managed resource or composite resource
[against a Provider or XRD schema](#validate-resources-against-a-schema).
- Use the output of `crossplane beta render` as [validation input](#validate-render-command-output).
- Use the output of `crossplane render` as [validation input](#validate-render-command-output).
- Validate an [XRD against Kubernetes Common Expression Language](#validate-common-expression-language-rules)
(CEL) rules.
- Validate resources against a [directory of schemas](#validate-against-a-directory-of-schemas).
@ -933,16 +975,16 @@ Total 1 resources: 0 missing schemas, 1 success case, 0 failure cases
#### Validate render command output
You can pipe the output of `crossplane beta render` into
You can pipe the output of `crossplane render` into
`crossplane beta validate` to validate complete Crossplane resource pipelines,
including XRs, compositions and composition functions.
Use the `--include-full-xr` command with `crossplane beta render` and the `-`
Use the `--include-full-xr` command with `crossplane render` and the `-`
option with `crossplane beta validate` to pipe the output from
`crossplane beta render` to the input of `crossplane beta validate`.
`crossplane render` to the input of `crossplane beta validate`.
```shell {copy-lines="1"}
crossplane beta render xr.yaml composition.yaml function.yaml --include-full-xr | crossplane beta validate schemas.yaml -
crossplane render xr.yaml composition.yaml function.yaml --include-full-xr | crossplane beta validate schemas.yaml -
[x] schema validation error example.crossplane.io/v1beta1, Kind=XR, example : status.conditions[0].lastTransitionTime: Invalid value: "null": status.conditions[0].lastTransitionTime in body must be of type string: "null"
[x] schema validation error example.crossplane.io/v1beta1, Kind=XR, example : spec: Required value
[✓] iam.aws.upbound.io/v1beta1, Kind=AccessKey, sample-access-key-0 validated successfully
@ -1015,7 +1057,7 @@ Total 1 resources: 0 missing schemas, 0 success cases, 1 failure cases
#### Validate against a directory of schemas
The `crossplane beta render` command can validate a directory of YAML files.
The `crossplane render` command can validate a directory of YAML files.
The command only processes `.yaml` and `.yml` files, while ignoring all other
file types.
@ -1051,51 +1093,4 @@ crossplane beta validate schema resources.yaml
Total 5 resources: 0 missing schemas, 4 success cases, 1 failure cases
```
### beta xpkg init
The `crossplane beta xpkg init` command populates the current directory with
files to build a package.
Provide a name to use for the package and the package template to start from
with the command
`crossplane beta xpkg init <name> <template>`
The `<name>` input isn't used. Crossplane reserves the `<name>` for future releases.
The `<template>` value may be one of four well known templates:
* `configuration-template` - A template to build a Crossplane [Configuration]({{<ref "../concepts/packages">}}) from the [crossplane/configuration-template](https://github.com/crossplane/configuration-template) repository.
* `function-template-go` - A template to build Crossplane Go [composition functions]({{<ref "../concepts/composition-functions">}}) from the [crossplane/function-template-go](https://github.com/crossplane/function-template-go) repository.
* `function-template-python` - A template to build Crossplane Python [composition functions]({{<ref "../concepts/composition-functions">}}) from the [crossplane/function-template-python](https://github.com/crossplane/function-template-go) repository.
* `provider-template` - A template to build a basic Crossplane provider from the [Crossplane/provider-template](https://github.com/crossplane/provider-template) repository.
* `provider-template-upjet` - A template for building [Upjet](https://github.com/crossplane/upjet) based Crossplane providers from existing Terraform providers. Copies from the [upbound/upjet-provider-template](https://github.com/upbound/upjet-provider-template) repository.
Instead of a well known template the `<template>` value can be a git repository
URL.
#### NOTES.txt
If the template repository contains a `NOTES.txt` file in its root directory,
the `crossplane beta xpkg init` command prints the contents of the file to the
terminal after populating the directory with the template files. This can be
useful for providing information about the template.
#### init.sh
If the template repository contains an `init.sh` file in its root directory, the
`crossplane beta xpkg init` command starts a dialog after populating the
directory with the template files. The dialog prompts the user if they want
to view or run the script. Use the initialization script to automatically
personalize the template.
#### Flags
{{< table "table table-sm table-striped">}}
| Short flag | Long flag | Description |
| ------------ | ----------------------- | ------------------------------ |
| `-b` | `--ref-name` | The branch or tag to clone from the template repository. |
| `-d` | `--directory` | The directory to create and load the template files into. Uses the current directory by default. |
| `-r` | `--run-init-script` | Run the init.sh script without prompting, if it exists. |
<!-- vale Crossplane.Spelling = YES -->
{{< /table >}}

10
content/master/concepts/_index.md
View File

@ -55,16 +55,6 @@ building and managing external resources through Kubernetes.
Composite Resource. Platform users create Claims in their unique namespace,
isolating their resources from other teams in other namespaces.
* [**Composition Functions**]({{<ref "./composition-functions">}}) are custom
programs, written your programming language of choice, to apply logic and
loops before or after Crossplane creates resources.
* [**Patches and Transforms**]({{<ref "./patch-and-transform">}}) allow platform
engineers to use user inputs to their custom API and change how Crossplane
creates resources. Patches and transforms allow for flexible and
abstract inputs like `big` or `encrypted` to have specific meanings when
creating the actual managed resources.
* [**EnvironmentConfigs**]({{<ref "./environment-configs">}}) are an in-memory
data store, like a Kubernetes ConfigMap. EnvironmentConfigs are useful for
custom resource mapping or storing and retrieving data across Claims and

4
content/master/concepts/composite-resource-definitions.md
View File

@ -413,7 +413,7 @@ field indicates which version of the schema Compositions use. Only one
version can be `referenceable`.
{{< hint "note" >}}
Changing which version is `referenceable:true` requires [updating the `compositeTypeRef.apiVersion`]({{<ref "./compositions#enabling-composite-resources" >}})
Changing which version is `referenceable:true` requires [updating the `compositeTypeRef.apiVersion`]({{<ref "./compositions#enable-composite-resources" >}})
of any Compositions referencing that XRD.
{{< /hint >}}
@ -582,7 +582,7 @@ key names listed in the Composition's `connectionDetails`.
An XRD ignores any keys listed that aren't created by a managed resource.
For more information read the
[Composition documentation]({{<ref "./compositions#storing-connection-details">}}).
[Composition documentation]({{<ref "./compositions#store-connection-details">}}).
{{< /hint >}}

29
content/master/concepts/composite-resources.md
View File

@ -133,16 +133,27 @@ kind: Composition
metadata:
name: my-composition
spec:
resources:
- name: database
base:
# Removed for brevity
patches:
- fromFieldPath: metadata.annotations
toFieldPath: metadata.annotations
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: database
base:
# Removed for brevity
patches:
- fromFieldPath: metadata.annotations
toFieldPath: metadata.annotations
```
For more information on patching resources refer to the [Patch and Transform]({{<ref "./patch-and-transform">}}) documentation.
For more information on using `function-patch-and-transform` to patch
resources refer to the
[Function Patch and Transform]({{<ref "../guides/function-patch-and-transform">}})
documentation.
### Composition selection
@ -152,7 +163,7 @@ Select a specific Composition for a composite resource to use with
{{<hint "important">}}
The selected Composition must allow the composite resource to use it with a
`compositeTypeRef`. Read more about the `compositeTypeRef` field in the
[Enabling Composite Resources]({{<ref "./compositions#enabling-composite-resources">}})
[Enable Composite Resources]({{<ref "./compositions#enable-composite-resources">}})
section of the Composition documentation.
{{< /hint >}}

745
content/master/concepts/composition-functions.md
View File

@ -1,745 +0,0 @@
---
title: Composition Functions
state: beta
alphaVersion: "1.11"
betaVersion: "1.14"
weight: 80
description: "Composition Functions allow you to template resources using general-purpose programming languages"
aliases:
- /knowledge-base/guides/composition-functions
---
Composition functions (or just functions, for short) are custom programs that
template Crossplane resources. Crossplane calls composition functions to
determine what resources it should create when you create a composite resource
(XR). You can write a function to template resources using a general purpose
programming language like Go or Python. Using a general purpose programming
language allows a Function to use more advanced logic to template resources,
like loops and conditionals.
You can build a function using general purpose programming languages such as Go
or Python. The Crossplane community has also built functions that let you
template Crossplane resources using [CUE](https://cuelang.org), Helm-like
[Go templates](https://pkg.go.dev/text/template) or
[Patch and Transforms]({{<ref "./patch-and-transform">}}).
## Install a composition function
Installing a Function creates a function pod. Crossplane sends requests to this
pod to ask it what resources to create when you create a composite resource.
Install a Function with a Crossplane
{{<hover label="install" line="2">}}Function{{</hover >}} object setting the
{{<hover label="install" line="6">}}spec.package{{</hover >}} value to the
location of the function package.
For example, to install [Function Patch and Transform](https://github.com/crossplane-contrib/function-patch-and-transform),
```yaml {label="install"}
apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
name: function-patch-and-transform
spec:
package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4
```
{{< hint "tip" >}}
Functions are Crossplane Packages. Read more about Packages in the
[Packages documentation]({{<ref "packages" >}}).
{{< /hint >}}
By default, the Function pod installs in the same namespace as Crossplane
(`crossplane-system`).
## Verify a composition function
View the status of a Function with `kubectl get functions`
During the install a Function reports `INSTALLED` as `True` and `HEALTHY` as
`Unknown`.
```shell {copy-lines="1"}
kubectl get functions
NAME INSTALLED HEALTHY PACKAGE AGE
function-patch-and-transform True Unknown xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4 10s
```
After the Function install completes and it's ready for use the `HEALTHY` status
reports `True`.
## Use a function in a composition
Crossplane calls a Function to determine what resources it should create when
you create a composite resource. The Function also tells Crossplane what to do
with these resources when you update or delete a composite resource.
When Crossplane calls a Function it sends it the current state of the composite
resource. It also sends it the current state of any managed resources the
composite resource owns.
Crossplane knows what Function to call when a composite resource changes by
looking at the Composition the composite resource uses.
{{<expand "Confused about Composite Resources and Compositions?" >}}
Crossplane has four core components that users commonly mix up:
* [Composition]({{<ref "./compositions">}}) - A template to define how to create
resources.
* [CompositeResourceDefinition]({{<ref "./composite-resource-definitions">}})
(`XRD`) - A custom API specification.
* [Composite Resource]({{<ref "./composite-resources">}}) (`XR`) - Created by
using the custom API defined in a CompositeResourceDefinition. XRs use the
Composition template to create new managed resources.
* [Claim]({{<ref "./claims" >}}) (`XRC`) - Like a Composite Resource, but with
namespace scoping.
{{</expand >}}
To use composition functions set the Composition
{{<hover label="single" line="6">}}mode{{</hover>}} to
{{<hover label="single" line="6">}}Pipeline{{</hover>}}.
Define a {{<hover label="single" line="7">}}pipeline{{</hover>}} of
{{<hover label="single" line="8">}}steps{{</hover>}}. Each
{{<hover label="single" line="8">}}step{{</hover>}} calls a Function.
Each {{<hover label="single" line="8">}}step{{</hover>}} uses a
{{<hover label="single" line="9">}}functionRef{{</hover>}} to reference the
{{<hover label="single" line="10">}}name{{</hover>}} of the Function to call.
{{<hint "important" >}}
Compositions using {{<hover label="single" line="6">}}mode: Pipeline{{</hover>}}
can't specify resource templates with a `resources` field.
Use function "Patch and Transform" to create resource templates.
{{< /hint >}}
Some Functions also allow you to specify an
{{<hover label="single" line="11">}}input{{</hover>}}.
The function defines the
{{<hover label="single" line="13">}}kind{{</hover>}} of input.
This example uses
[Function Patch and Transform](https://github.com/crossplane-contrib/function-patch-and-transform).
Function Patch and Transform implements Crossplane resource
templates.
The input kind is {{<hover label="single" line="13">}}Resources{{</hover>}},
and it accepts [Patch and Transform]({{<ref "./patch-and-transform">}})
{{<hover label="single" line="14">}}resources{{</hover>}} as input.
```yaml {label="single",copy-lines="none"}
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
# Removed for Brevity
spec:
# Removed for Brevity
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: storage-bucket
base:
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
spec:
forProvider:
region: "us-east-2"
```
## Use a pipeline of functions in a composition
Crossplane can ask more than one Function what to do when a composite resource
changes. When a Composition has a pipeline of two or more steps, Crossplane
calls them all. It calls them in the order they appear in the pipeline.
Crossplane passes each Function in the pipeline the result of the previous
Function. This enables powerful combinations of Functions. In this example,
Crossplane calls {{<hover label="double" line="10">}}function-cue{{</hover>}} to
create an S3 bucket. Crossplane then passes the bucket to
{{<hover label="double" line="23">}}function-auto-ready{{</hover>}}, which marks the
composite resource as ready when the bucket becomes ready.
```yaml {label="double",copy-lines="none"}
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
# Removed for Brevity
spec:
# Removed for Brevity
mode: Pipeline
pipeline:
- step: cue-export-resources
functionRef:
name: function-cue
input:
apiVersion: cue.fn.crossplane.io/v1beta1
kind: CUEInput
name: storage-bucket
export:
target: Resources
value: |
apiVersion: "s3.aws.upbound.io/v1beta1"
kind: "Bucket"
spec: forProvider: region: "us-east-2"
- step: automatically-detect-readiness
functionRef:
name: function-auto-ready
```
## Test a composition that uses functions
You can preview the output of any composition that uses composition functions
using the Crossplane CLI. You don't need a Crossplane control plane to do
this. The Crossplane CLI uses Docker Engine to run functions.
{{<hint "tip">}}
See the [Crossplane CLI docs]({{<ref "../cli">}}) to
learn how to install and use the Crossplane CLI.
{{< /hint >}}
{{<hint "important">}}
Running `crossplane beta render` requires [Docker](https://www.docker.com).
{{< /hint >}}
Provide a composite resource, composition and composition functions to render
the output locally.
```shell
crossplane beta render xr.yaml composition.yaml functions.yaml
```
`crossplane beta render` prints resources as YAML to stdout. It prints the
composite resource first, followed by the resources the composition functions
created.
```yaml
---
apiVersion: example.crossplane.io/v1
kind: XBucket
metadata:
name: example-render
---
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
metadata:
annotations:
crossplane.io/composition-resource-name: storage-bucket
generateName: example-render-
labels:
crossplane.io/composite: example-render
ownerReferences:
- apiVersion: example.crossplane.io/v1
blockOwnerDeletion: true
controller: true
kind: XBucket
name: example-render
uid: ""
spec:
forProvider:
region: us-east-2
```
{{<expand "The xr.yaml, composition.yaml and function.yaml files used in the example">}}
You can recreate the output below by running `crossplane beta render` with
these files.
The `xr.yaml` file contains the composite resource to render:
```yaml
apiVersion: example.crossplane.io/v1
kind: XBucket
metadata:
name: example-render
spec:
bucketRegion: us-east-2
```
The `composition.yaml` file contains the Composition to use to render the
composite resource:
```yaml
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: example-render
spec:
compositeTypeRef:
apiVersion: example.crossplane.io/v1
kind: XBucket
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: storage-bucket
base:
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
patches:
- type: FromCompositeFieldPath
fromFieldPath: spec.bucketRegion
toFieldPath: spec.forProvider.region
```
The `functions.yaml` file contains the Functions the Composition references in
its pipeline steps:
```yaml
---
apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
name: function-patch-and-transform
spec:
package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4
```
{{</expand>}}
The Crossplane CLI uses Docker Engine to run functions. You can change how the
Crossplane CLI runs a function by adding an annotation in `functions.yaml`. Add
the `render.crossplane.io/runtime` annotation to a Function to change how it's
run.
`crossplane beta render` supports two `render.crossplane.io/runtime` values:
* `Docker` (the default) connects to Docker Engine. It uses Docker to pull and
run a function runtime.
* `Development` connects to a function runtime you have run manually.
When you use the {{<hover label="development" line="6">}}Development{{</hover>}}
runtime the Crossplane CLI ignores the Function's {{<hover label="development"
line="8">}}package{{</hover>}}. Instead it expects you to make sure the function
is listening on localhost port 9443. The function must be listening without gRPC
transport security. Most function SDKs let you run a function with the
`--insecure` flag to disable transport security. For example you can run a Go
function locally using `go run . --insecure`.
```yaml {label="development"}
apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
name: function-patch-and-transform
annotations:
render.crossplane.io/runtime: Development
spec:
package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4
```
{{<hint "tip">}}
Use the `Development` runtime when you
[write a composition function](#write-a-composition-function) to test your
function end-to-end.
{{</hint>}}
`crossplane beta render` also supports the following Function annotations. These
annotations affect how it runs Functions:
* `render.crossplane.io/runtime-docker-cleanup` - When using the `Docker`
runtime this annotation specifies whether the CLI should stop the function
container after it calls the function. It supports the values `Stop`, to stop
the container, and `Orphan`, to leave it running.
* `render.crossplane.io/runtime-docker-pull-policy` - When using the `Docker`
runtime this annotation specifies when the CLI should pull the Function's
package. It supports the values `Always`, `Never`, and `IfNotPresent`.
* `render.crossplane.io/runtime-development-target` - When using the
`Development` runtime this annotation tells the CLI to connect to a Function
running at the specified target. It uses
[gRPC target syntax](https://github.com/grpc/grpc/blob/v1.59.1/doc/naming.md).
## Write a composition function
Composition functions let you replace complicated Compositions with code written
in your programming language of choice. Crossplane has tools, software
development kits (SDKs) and templates to help you write a function.
<!-- vale write-good.Passive = NO -->
Here's an example of a tiny, hello world function. This example is written in
[Go](https://go.dev).
<!-- vale write-good.Passive = YES -->
```go
func (f *Function) RunFunction(_ context.Context, req *fnv1beta1.RunFunctionRequest) (*fnv1beta1.RunFunctionResponse, error) {
rsp := response.To(req, response.DefaultTTL)
response.Normal(rsp, "Hello world!")
return rsp, nil
}
```
<!-- vale write-good.Passive = NO -->
Some composition functions are designed to be used with any kind of
composite resource.
<!-- vale write-good.Passive = YES -->
[Function Patch and Transform](https://github.com/crossplane-contrib/function-patch-and-transform)
and
[Function Auto Ready](https://github.com/crossplane-contrib/function-auto-ready)
work with any kind of composite resource.
Another common pattern is to write a composition function specific to one kind
of composite resource. The function contains all the logic needed to tell
Crossplane what resources to create when you create a composite resource. When
you write a composition function like this, your Composition can be small. It
just tells Crossplane what function to run when you create, update, or delete a
composite resource.
This Composition tells Crossplane to call {{<hover label="dedicated"
line="13">}}function-xr-xbucket{{</hover>}} whenever you create, update, or
delete an {{<hover label="dedicated" line="8">}}XBucket{{</hover>}} composite
resource. `function-xr-xbucket` is hard coded to handle `XBucket` composite
resources.
```yaml {label="dedicated"}
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: example-bucket-function
spec:
compositeTypeRef:
apiVersion: example.crossplane.io/v1
kind: XBucket
mode: Pipeline
pipeline:
- step: handle-xbucket-xr
functionRef:
name: function-xr-xbucket
```
To write a composition function, you:
1. Create the function from a template.
1. Edit the template to add the function's logic.
1. [Test the function](#test-a-composition-that-uses-functions).
1. Build the function, and push it to a package registry.
You use the [Crossplane CLI]({{<ref "../cli">}}) to
create, test, build, and push a function. For example,
```shell {copy-lines=none}
# Create the function from a template.
crossplane beta xpkg init function-example function-template-go
Initialized package "function-example" in directory "/home/negz/control/negz/function-example" from https://github.com/crossplane/function-template-go/tree/91a1a5eed21964ff98966d72cc6db6f089ad63f4 (main)
$ ls
Dockerfile fn.go fn_test.go go.mod go.sum input LICENSE main.go package README.md renovate.json
# Edit the template to add your function's logic
$ vim fn.go
# Build the function.
$ docker build . --quiet --tag runtime
sha256:2c31b0f7a34b34ba5b0b2dacc94c360d18aca1b99f56ca4f40a1f26535a7c1c4
# Package the function.
$ crossplane xpkg build -f package --embed-runtime-image=runtime
# Test the function.
$ go run . --insecure
$ crossplane beta render xr.yaml composition.yaml functions.yaml
# Push the function package to xpkg.upbound.io.
$ crossplane xpkg push -f package/*.xpkg crossplane-contrib/function-example:v0.1.0
```
{{<hint "tip">}}
Crossplane has
[language specific guides]({{<ref "../guides">}}) to writing
a composition function. Refer to the guide for your preferred language for a
more detailed guide to writing a function.
{{</hint>}}
When you're writing a composition function it's useful to know how composition
functions work. Read the next section to learn
[how composition functions work](#how-composition-functions-work).
## How composition functions work
Each composition function is actually a [gRPC](https://grpc.io) server. gRPC is
a high performance, open source remote procedure call (RPC) framework. When you
[install a function](#install-a-composition-function) Crossplane deploys the
function as a gRPC server. Crossplane encrypts and authenticates all gRPC
communication.
You don't have to be a gRPC expert to write a function. Crossplane's function
SDKs setup gRPC for you. It's useful to understand how Crossplane calls your
function though, and how your function should respond.
```mermaid
sequenceDiagram
User->>+API Server: Create composite resource
Crossplane Pod->>+API Server: Observe composite resource
Crossplane Pod->>+Function Pod: gRPC RunFunctionRequest
Function Pod->>+Crossplane Pod: gRPC RunFunctionResponse
loop Extra resources needed?
Crossplane Pod->>+API Server: Get Extra resources
Crossplane Pod->>+Function Pod: gRPC RunFunctionRequest
Function Pod->>+Crossplane Pod: gRPC RunFunctionResponse
end
Crossplane Pod->>+API Server: Apply desired composed resources
```
When you create, update, or delete a composite resource that uses composition
functions Crossplane calls each function in the order they appear in the
Composition's pipeline. Crossplane calls each function by sending it a gRPC
RunFunctionRequest. The function must respond with a gRPC RunFunctionResponse.
{{<hint "tip">}}
You can find detailed schemas for the RunFunctionRequest and RunFunctionResponse
RPCs in the [Buf Schema Registry](https://buf.build/crossplane/crossplane/docs/main:apiextensions.fn.proto.v1beta1).
{{</hint>}}
When Crossplane calls a function the first time it includes four important
things in the RunFunctionRequest.
1. The __observed state__ of the composite resource, and any composed resources.
1. The __desired state__ of the composite resource, and any composed resources.
1. The function's __input__.
1. The function pipeline's __context__.
A function's main job is to update the __desired state__ and return it to
Crossplane. It does this by returning a RunFunctionResponse.
Most composition functions read the observed state of the composite resource,
and use it to add composed resources to the desired state. This tells Crossplane
which composed resources it should create or update.
If the function needs __extra resources__ to determine the desired state it can
request any cluster-scoped resource Crossplane already has access to, either by
by name or labels through the returned RunFunctionResponse. Crossplane then
calls the function again including the requested __extra resources__ and the
__context__ returned by the Function itself alongside the same __input__,
__observed__ and __desired state__ of the previous RunFunctionRequest. Functions
can iteratively request __extra resources__ if needed, but to avoid endlessly
looping Crossplane limits the number of iterations to 5. Crossplane considers
the function satisfied as soon as the __extra resources__ requests become
stable, so the Function returns the same exact request two times in a row.
Crossplane errors if stability isn't reached after 5 iterations.
{{<hint "tip">}}
<!-- vale write-good.Weasel = NO -->
<!-- Disable Weasel to say "usually", which is correct in this context. -->
A _composed_ resource is a resource created by a composite resource. Composed
resources are usually Crossplane managed resources (MRs), but they can be any
kind of Crossplane resource. For example a composite resource could also create
a ProviderConfig, or another kind of composite resource.
<!-- vale write-good.Weasel = YES -->
{{</hint>}}
### Observed state
When you create a composite resource like this one, Crossplane _observes_ it and
sends it to the composition function as part of the observed state.
```yaml
apiVersion: example.crossplane.io/v1
kind: XBucket
metadata:
name: example-render
spec:
bucketRegion: us-east-2
```
If any composed resources already exist, Crossplane observes them and sends them
to your function as part of the observed state.
Crossplane also observes the connection details of your composite resource and
any composed resources. It sends them to your function as part of the observed
state.
Crossplane observes the composite resource and any composed resources once,
right before it starts calling the functions in the pipeline. This means that
Crossplane sends every function in the pipeline the same observed state.
### Desired state
Desired state is the set of the changes the function pipeline wants to make to
the composite resource and any composed resources. When a function adds composed
resources to the desired state Crossplane creates them.
A function can change:
* The `status` of the composite resource.
* The `metadata` and `spec` of any composed resource.
A function can also change the connection details and readiness of the composite
resource. A function indicates that the composite resource is ready by telling
Crossplane whether its composed resources are ready. When the function pipeline
tells Crossplane that all composed resources are ready, Crossplane marks the
composite resource as ready.
A function can't change:
* The `metadata` or `spec` of the composite resource.
* The `status` of any composed resource.
* The connection details of any composed resource.
A pipeline of functions _accumulates_ desired state. This means that each
function builds upon the desired state of previous functions in the pipeline.
Crossplane sends a function the desired state accumulated by all previous
functions in the pipeline. The function adds to or updates the desired state and
then passes it on. When the last function in the pipeline has run, Crossplane
applies the desired state it returns.
{{<hint "important">}}
A function __must__ copy all desired state from its RunFunctionRequest to its
RunFunctionResponse. If a function adds a resource to its desired state the next
function must copy it to its desired state. If it doesn't, Crossplane doesn't
apply the resource. If the resource exists, Crossplane deletes it.
A function can _intentionally_ choose not to copy parts of the desired state.
For example a function may choose not to copy a desired resource to prevent that
resource from existing.
Most function SDKs handle copying desired state automatically.
{{</hint>}}
A function should only add the fields it cares about to the desired state. It
should add these fields every time Crossplane calls it. If a function adds a
field to the desired state once, but doesn't add it the next time it's called,
Crossplane deletes the field. The same is true for composed resources. If a
function adds a composed resource to the desired state, but doesn't add it the
next time it's called, Crossplane deletes the composed resource.
{{<hint "tip">}}
Crossplane uses
[server side apply](https://kubernetes.io/docs/reference/using-api/server-side-apply/)
to apply the desired state returned by a function pipeline. In server side apply
terminology, the desired state is a _fully specified intent_.
{{</hint>}}
For example, if all a function wants is to make sure an S3 bucket in region
`us-east-2` exists, it should add this resource to its desired composed
resources.
```yaml
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
spec:
forProvider:
region: us-east-2
```
Even if the Bucket already exists and has other `spec` fields, or a `status`,
`name`, `labels`, etc the function should omit them. The function should only
include the fields it has an opinion about. Crossplane takes care of applying
the fields the function cares about, merging them with the existing Bucket.
{{<hint "tip">}}
Composition functions don't actually use YAML for desired and observed
resources. This example uses YAML for illustration purposes only.
{{</hint>}}
### Function input
If a Composition includes {{<hover label="input" line="14">}}input{{</hover>}}
Crossplane sends it to the function. Input is a useful way to provide extra
configuration to a function. Supporting input is optional. Not all functions
support input.
```yaml {label="input",copy-lines="none"}
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: example-render
spec:
compositeTypeRef:
apiVersion: example.crossplane.io/v1
kind: XBucket
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: storage-bucket
base:
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
patches:
- type: FromCompositeFieldPath
fromFieldPath: spec.bucketRegion
toFieldPath: spec.forProvider.region
```
{{<hint "important">}}
Crossplane doesn't validate function input. It's a good idea for a function to
validate its own input.
{{</hint>}}
### Function pipeline context
Sometimes two functions in a pipeline want to share information with each other
that isn't desired state. Functions can use context for this. Any function can
write to the pipeline context. Crossplane passes the context to all following
functions. When Crossplane has called all functions it discards the pipeline
context.
Crossplane can write context too. If you enable the alpha
[composition environment]({{<ref "environment-configs">}}) feature Crossplane
writes the environment to the top-level context field
`apiextensions.crossplane.io/environment`.
## Disable composition functions
Crossplane enables composition functions by default. Disable support for
composition functions by disabling the beta feature flag in Crossplane with
`helm install --args`.
```shell
helm install crossplane --namespace crossplane-system crossplane-stable/crossplane \
--create-namespace \
--set "args='{--enable-composition-functions=false}'"
```
The preceding Helm command installs Crossplane with the composition functions
feature flag disabled. Confirm you have disabled composition functions by
looking for a log line:
```shell {copy-lines="1"}
kubectl -n crossplane-system logs -l app=crossplane
{"level":"info","ts":1674535093.36186,"logger":"crossplane","msg":"Beta feature enabled","flag":"EnableBetaCompositionFunctions"}
```
If you don't see the log line emitted when Crossplane starts, you have disabled
composition functions.
## Disable extra resources
Crossplane enables __extra resources__ by default, allowing Functions to get access
to any cluster-scoped resource Crossplane already has access to. Disable support
for __extra resources__, while keeping composition functions enabled, by disabling
the beta feature flag in Crossplane with `helm install --args`.
```shell
helm install crossplane --namespace crossplane-system crossplane-stable/crossplane \
--create-namespace \
--set "args='{--enable-composition-functions-extra-resources=false}'"
```
The preceding Helm command installs Crossplane with the extra resources
feature flag disabled. Confirm you have disabled composition functions by
looking for a log line:
```shell {copy-lines="1"}
kubectl -n crossplane-system logs -l app=crossplane
{"level":"info","ts":1674535093.36186,"logger":"crossplane","msg":"Beta feature enabled","flag":"EnableBetaCompositionFunctionsExtraResources"}
```
If you don't see the log line emitted when Crossplane starts, you have disabled
__extra resources__ for composition functions, which means requests by functions for __extra
resources__ are just ignored.

60
content/master/concepts/composition-revisions.md
View File

@ -170,17 +170,25 @@ spec:
compositeTypeRef:
apiVersion: aws.example.upbound.io/v1alpha1
kind: MyVPC
resources:
- base:
apiVersion: ec2.aws.upbound.io/v1beta1
kind: VPC
spec:
forProvider:
region: us-west-1
cidrBlock: 192.168.0.0/16
enableDnsSupport: true
enableDnsHostnames: true
name: my-vcp
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: my-vpc
base:
apiVersion: ec2.aws.upbound.io/v1beta1
kind: VPC
spec:
forProvider:
region: us-west-1
cidrBlock: 192.168.0.0/16
enableDnsSupport: true
enableDnsHostnames: true
```
Apply the example XRD.
@ -382,17 +390,25 @@ spec:
compositeTypeRef:
apiVersion: aws.example.upbound.io/v1alpha1
kind: MyVPC
resources:
- base:
apiVersion: ec2.aws.upbound.io/v1beta1
kind: VPC
spec:
forProvider:
region: us-west-1
cidrBlock: 192.168.0.0/16
enableDnsSupport: false
enableDnsHostnames: true
name: my-vcp
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: my-vpc
base:
apiVersion: ec2.aws.upbound.io/v1beta1
kind: VPC
spec:
forProvider:
region: us-west-1
cidrBlock: 192.168.0.0/16
enableDnsSupport: false
enableDnsHostnames: true
```
Expected Output:

1706
content/master/concepts/compositions.md
View File

File diff suppressed because it is too large Load Diff

366
content/master/concepts/connection-details.md
View File

@ -9,8 +9,8 @@ Using connection details in Crossplane requires the following components:
* Defining the `writeConnectionSecretsToNamespace` value in the [Composition]({{<ref "/master/concepts/compositions#composite-resource-combined-secret">}}).
* Define the `writeConnectionSecretToRef` name and namespace for each resource in the
[Composition]({{<ref "/master/concepts/compositions#composed-resource-secrets">}}).
* Define the list of secret keys produced by each composed resource with `connectionDetails` in the
[Composition]({{<ref "/master/concepts/compositions#define-secret-keys">}}).
* Define the list of secret keys produced by each composed resource with in the
[Composition]({{<ref "/master/concepts/compositions">}}).
* Optionally, define the `connectionSecretKeys` in a
[CompositeResourceDefinition]({{<ref "/master/concepts/composite-resource-definitions#manage-connection-secrets">}}).
@ -63,74 +63,96 @@ spec:
compositeTypeRef:
apiVersion: example.org/v1alpha1
kind: XSecretTest
resources:
- name: key
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: AccessKey
spec:
forProvider:
userSelector:
matchControllerRef: true
writeConnectionSecretToRef:
namespace: docs
name: key1
connectionDetails:
- fromConnectionSecretKey: username
- fromConnectionSecretKey: password
- fromConnectionSecretKey: attribute.secret
- fromConnectionSecretKey: attribute.ses_smtp_password_v4
patches:
- fromFieldPath: "metadata.uid"
toFieldPath: "spec.writeConnectionSecretToRef.name"
transforms:
- type: string
string:
fmt: "%s-secret1"
- name: user
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: User
spec:
forProvider: {}
- name: user2
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: User
metadata:
labels:
docs.crossplane.io: user
spec:
forProvider: {}
- name: key2
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: AccessKey
spec:
forProvider:
userSelector:
matchLabels:
docs.crossplane.io: user
writeConnectionSecretToRef:
namespace: docs
name: key2
connectionDetails:
- name: key2-user
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: key
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: AccessKey
spec:
forProvider:
userSelector:
matchControllerRef: true
writeConnectionSecretToRef:
namespace: docs
name: key1
connectionDetails:
- name: user
type: FromConnectionSecretKey
fromConnectionSecretKey: username
- name: key2-password
- name: password
type: FromConnectionSecretKey
fromConnectionSecretKey: password
- name: key2-secret
- name: key
type: FromConnectionSecretKey
fromConnectionSecretKey: attribute.secret
- name: key2-smtp
- name: smtp
type: FromConnectionSecretKey
fromConnectionSecretKey: attribute.ses_smtp_password_v4
patches:
- fromFieldPath: "metadata.uid"
toFieldPath: "spec.writeConnectionSecretToRef.name"
transforms:
- type: string
string:
fmt: "%s-secret2"
```
patches:
- fromFieldPath: "metadata.uid"
toFieldPath: "spec.writeConnectionSecretToRef.name"
transforms:
- type: string
string:
type: Format
fmt: "%s-secret1"
- name: user
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: User
spec:
forProvider: {}
- name: user2
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: User
metadata:
labels:
docs.crossplane.io: user
spec:
forProvider: {}
- name: key2
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: AccessKey
spec:
forProvider:
userSelector:
matchLabels:
docs.crossplane.io: user
writeConnectionSecretToRef:
namespace: docs
name: key2
connectionDetails:
- name: key2-user
type: FromConnectionSecretKey
fromConnectionSecretKey: username
- name: key2-password
type: FromConnectionSecretKey
fromConnectionSecretKey: password
- name: key2-secret
type: FromConnectionSecretKey
fromConnectionSecretKey: attribute.secret
- name: key2-smtp
type: FromConnectionSecretKey
fromConnectionSecretKey: attribute.ses_smtp_password_v4
patches:
- fromFieldPath: "metadata.uid"
toFieldPath: "spec.writeConnectionSecretToRef.name"
transforms:
- type: string
string:
type: Format
fmt: "%s-secret2"
`` `
{{</expand >}}
{{<expand "Reference CompositeResourceDefinition" >}}
@ -284,28 +306,36 @@ apiVersion: apiextensions.crossplane.io/v1
kind: Composition
spec:
writeConnectionSecretsToNamespace: other-namespace
resources:
- name: key1
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: AccessKey
spec:
forProvider:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key1-secret
- name: key2
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: AccessKey
spec:
forProvider:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key2-secret
# Removed for brevity
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: key1
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: AccessKey
spec:
forProvider:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key1-secret
- name: key2
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: AccessKey
spec:
forProvider:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key2-secret
# Removed for brevity
```
After applying a Claim, view the Kubernetes secrets to see three secret objects
@ -364,23 +394,39 @@ apiVersion: apiextensions.crossplane.io/v1
kind: Composition
spec:
writeConnectionSecretsToNamespace: other-namespace
resources:
- name: key
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: AccessKey
spec:
forProvider:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key1
connectionDetails:
- fromConnectionSecretKey: username
- fromConnectionSecretKey: password
- fromConnectionSecretKey: attribute.secret
- fromConnectionSecretKey: attribute.ses_smtp_password_v4
# Removed for brevity
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: key
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: AccessKey
spec:
forProvider:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key1
connectionDetails:
- name: user
type: FromConnectionSecretKey
fromConnectionSecretKey: username
- name: password
type: FromConnectionSecretKey
fromConnectionSecretKey: password
- name: key
type: FromConnectionSecretKey
fromConnectionSecretKey: attribute.secret
- name: smtp
type: FromConnectionSecretKey
fromConnectionSecretKey: attribute.ses_smtp_password_v4
# Removed for brevity
```
After applying a Claim the composite resource secret object contains the list of
@ -418,28 +464,39 @@ apiVersion: apiextensions.crossplane.io/v1
kind: Composition
spec:
writeConnectionSecretsToNamespace: other-namespace
resources:
- name: key
base:
kind: AccessKey
spec:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key1
connectionDetails:
- fromConnectionSecretKey: username
- name: key2
base:
kind: AccessKey
spec:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key2
connectionDetails:
- name: key2-user
fromConnectionSecretKey: username
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: key
base:
kind: AccessKey
spec:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key1
connectionDetails:
- name: user
type: FromConnectionSecretKey
fromConnectionSecretKey: username
- name: key2
base:
kind: AccessKey
spec:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key2
connectionDetails:
- name: key2-user
type: FromConnectionSecretKey
fromConnectionSecretKey: username
```
The secret object contains both keys,
@ -548,28 +605,39 @@ apiVersion: apiextensions.crossplane.io/v1
kind: Composition
spec:
writeConnectionSecretsToNamespace: other-namespace
resources:
- name: key
base:
kind: AccessKey
spec:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key1
connectionDetails:
- fromConnectionSecretKey: username
- name: key2
base:
kind: AccessKey
spec:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key2
connectionDetails:
- name: key2-user
fromConnectionSecretKey: username
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: key
base:
kind: AccessKey
spec:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key1
connectionDetails:
- name: user
type: FromConnectionSecretKey
fromConnectionSecretKey: username
- name: key2
base:
kind: AccessKey
spec:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key2
connectionDetails:
- name: key2-user
type: FromConnectionSecretKey
fromConnectionSecretKey: username
```
If a Claim uses a secret, it's stored in the same namespace as the Claim with

103
content/master/concepts/environment-configs.md
View File

@ -3,7 +3,7 @@ title: Environment Configurations
weight: 75
state: alpha
alphaVersion: "1.11"
description: "Environment Configurations or EnvironmentConfigs are an in-memory datastore used in patching Compositions"
description: "Environment Configurations or EnvironmentConfigs are an in-memory datastore used in Compositions"
---
<!--
@ -13,9 +13,8 @@ TODO: Add Policies
A Crossplane EnvironmentConfig is a cluster scoped
[ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/)-like
resource used
by Compositions. Compositions can use the environment to store information from
individual resources or to apply [patches]({{<ref "patch-and-transform">}}).
resource used by Compositions. Compositions can use the environment to store
information from individual resources or to apply patches.
Crossplane supports multiple EnvironmentConfigs, each acting as a unique
data store.
@ -220,7 +219,6 @@ spec:
- key: my-label-key
type: FromCompositeFieldPath
valueFromFieldPath: spec.parameters.deploy
resources:
# Removed for brevity
```
@ -347,7 +345,6 @@ spec:
type: FromCompositeFieldPath
valueFromFieldPath: spec.parameters.deploy
fromFieldPathPolicy: Optional
resources:
# Removed for brevity
```
@ -386,7 +383,6 @@ spec:
type: FromCompositeFieldPath
valueFromFieldPath: spec.parameters.deploy
fromFieldPathPolicy: Optional
resources:
# Removed for brevity
```
@ -397,87 +393,22 @@ Defining the default value _after_ the label always overwrites the label
value.
{{< /hint >}}
## Patching with EnvironmentConfigs
## Use EnvironmentConfigs in a Composition
When Crossplane creates or updates a composite resource, Crossplane
merges all the specified EnvironmentConfigs into an in-memory environment.
When Crossplane creates or updates a composite resource, it 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
defined inside the composite resource.
Crossplane sends the merged, in-memory environment to the composition function
pipeline using the
[pipeline context]({{<ref "./compositions#function-pipeline-context">}}).
It writes the environment to the `apiextensions.crossplane.io/environment`
context key.
Some composition functions can read the environment from the pipeline context
and use it to compose resources.
{{<hint "tip" >}}
Read about EnvironmentConfig patch types in the
[Patch and Transform]({{<ref "./patch-and-transform">}}) documentation.
The Patch and Transform function can use the environment to patch composed
resources. Read about EnvironmentConfig patch types in the
[Patch and Transform function documentation]({{<ref "../guides/function-patch-and-transform">}}).
{{< /hint >}}
<!-- these two sections are duplicated in the compositions doc with different header depths -->
### 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 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 in-memory environment.
```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 in-memory environment.
### Patch an individual resource
To patch an individual resource, inside 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 in-memory environment.
Use {{<hover label="envpatch" line="20">}}FromEnvironmentFieldPath{{</hover>}}
to copy data to the resource from the in-memory environment.
```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.
<!-- End duplicated content -->

100
content/master/concepts/managed-resources.md
View File

@ -183,12 +183,6 @@ spec:
Matching by selector is the most flexible matching method.
{{<hint "note" >}}
The [Compositions]({{<ref "./compositions">}}) section covers the
`matchControllerRef` selector.
{{</hint >}}
Use `matchLabels` to match the labels applied to a resource. For example, this
Subnet resource only matches VPC resources with the label
`my-label: label-value`.
@ -204,6 +198,100 @@ spec:
my-label: label-value
```
##### Matching by controller reference
Matching a controller reference ensures that the matching resource is part of
the same composite resource.
{{<hint "note" >}}
Learn more about composite resources in the
[Composite Resources]({{<ref "./composite-resources">}}) section.
{{</hint >}}
Matching only a controller reference simplifies the matching process without
requiring labels or more information.
For example, creating an AWS `InternetGateway` requires a `VPC`.
The `InternetGateway` could match a label, but every VPC created by this
Composition shares the same label.
Using `matchControllerRef` matches only the VPC created in the same composite
resource that created the `InternetGateway`.
```yaml {label="controller1",copy-lines="none"}
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- base:
apiVersion: ec2.aws.upbound.io/v1beta1
kind: VPC
name: my-vpc
spec:
forProvider:
# Removed for brevity
- base:
apiVersion: ec2.aws.upbound.io/v1beta1
kind: InternetGateway
name: my-gateway
spec:
forProvider:
vpcIdSelector:
matchControllerRef: true
```
Resources can match both labels and a controller reference to match a specific
resource in the larger composite resource.
For example, this Composition creates two `VPC` resources, but the
`InternetGateway` must match only one.
Applying a `label` to the second `VPC` allows the `InternetGateway` to match the
label `type: internet` and only match objects in the same composite resource
with `matchControllerRef`.
```yaml {label="controller2",copy-lines="none"}
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: my-first-vpc
base:
apiVersion: ec2.aws.upbound.io/v1beta1
kind: VPC
metadata:
labels:
type: backend
spec:
forProvider:
# Removed for brevity
- name: my-second-vpc
base:
apiVersion: ec2.aws.upbound.io/v1beta1
kind: VPC
metadata:
labels:
type: internet
spec:
forProvider:
# Removed for brevity
- name: my-gateway
base:
apiVersion: ec2.aws.upbound.io/v1beta1
kind: InternetGateway
spec:
forProvider:
vpcIdSelector:
matchControllerRef: true
matchLabels:
type: internet
```
{{<hint "note" >}}
These examples use Function Patch and Transform. Learn more about functions and
Compositions in the [Compositions]({{<ref "./compositions">}}) section.
{{</hint >}}
#### Immutable fields

6
content/master/concepts/packages.md
View File

@ -10,19 +10,19 @@ A _Configuration_ package is an
[Compositions]({{<ref "./compositions" >}}),
[Composite Resource Definitions]({{<ref "./composite-resource-definitions" >}})
and any required [Providers]({{<ref "./providers">}}) or
[Functions]({{<ref "./composition-functions" >}}).
[Functions]({{<ref "./compositions" >}}).
Configuration packages make your Crossplane configuration fully portable.
{{<hint "important" >}}
Crossplane [Providers]({{<ref "./providers">}}) and
[Functions]({{<ref "./composition-functions">}}) are also Crossplane packages.
[Functions]({{<ref "./compositions">}}) are also Crossplane packages.
This document describes how to install and manage configuration packages.
Refer to the
[Provider]({{<ref "./providers">}}) and
[Composition Functions]({{<ref "./composition-functions">}}) chapters for
[Composition Functions]({{<ref "./compositions">}}) chapters for
details on their usage of packages.
{{< /hint >}}

1726
content/master/concepts/patch-and-transform.md
View File

File diff suppressed because it is too large Load Diff

2
content/master/concepts/server-side-apply.md
View File

@ -58,7 +58,7 @@ feature flag together with composition functions.
When you use composition functions, Crossplane uses server side apply to sync
composite resources with composed resources. Read more about this in the
[composition functions documentation]({{<ref "./composition-functions#how-composition-functions-work">}}).
[composition functions documentation]({{<ref "./compositions#how-composition-functions-work">}}).
```mermaid
graph LR

58
content/master/concepts/usages.md
View File

@ -228,9 +228,9 @@ for the long exponential backoff durations of the Kubernetes garbage collector.
A typical use case for Usages is to define a deletion ordering between the
resources in a Composition. The Usages support
[matching controller reference]({{<ref "./compositions#match-a-controller-reference" >}})
[matching controller reference]({{<ref "./managed-resources#matching-by-controller-reference" >}})
in selectors to ensures that the matching resource is in the same composite
resource in the same way as [cross-resource referencing]({{<ref "./compositions#cross-resource-references" >}}).
resource in the same way as [cross-resource referencing]({{<ref "./managed-resources#referencing-other-resources" >}}).
The following example shows a Composition that defines a deletion ordering
between a `Cluster` and a `Release` resource. The `Usage` blocks deletion of
@ -240,33 +240,41 @@ the `Cluster` resource until the `Release` resource is successfully deleted.
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
spec:
resources:
- name: cluster
base:
apiVersion: container.gcp.upbound.io/v1beta1
kind: Cluster
# Removed for brevity
- name: release
base:
apiVersion: helm.crossplane.io/v1beta1
kind: Release
# Removed for brevity
- name: release-uses-cluster
base:
apiVersion: apiextensions.crossplane.io/v1alpha1
kind: Usage
spec:
replayDeletion: true
of:
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: cluster
base:
apiVersion: container.gcp.upbound.io/v1beta1
kind: Cluster
resourceSelector:
matchControllerRef: true
by:
# Removed for brevity
- name: release
base:
apiVersion: helm.crossplane.io/v1beta1
kind: Release
resourceSelector:
matchControllerRef: true
# Removed for brevity
- name: release-uses-cluster
base:
apiVersion: apiextensions.crossplane.io/v1alpha1
kind: Usage
spec:
replayDeletion: true
of:
apiVersion: container.gcp.upbound.io/v1beta1
kind: Cluster
resourceSelector:
matchControllerRef: true
by:
apiVersion: helm.crossplane.io/v1beta1
kind: Release
resourceSelector:
matchControllerRef: true
```
{{<hint "tip" >}}

22
content/master/getting-started/introduction.md
View File

@ -225,7 +225,7 @@ metadata:
spec:
compositeTypeRef:
apiVersion: test.example.org/v1alpha1
kind: myComputeResource
kind: MyComputeResource
# Removed for brevity
```
@ -235,9 +235,9 @@ label="comp" line="8">}}kind{{< /hover >}}.
```yaml {label="xr"}
apiVersion: test.example.org/v1alpha1
kind: myComputeResource
kind: MyComputeResource
metadata:
name: myResource
name: my-resource
spec:
storage: "large"
```
@ -310,7 +310,7 @@ to define the _Composite Resource_ {{<hover label="xr2" line="6" >}}spec{{</hove
spec:
group: test.example.org
names:
kind: myComputeResource
kind: MyComputeResource
versions:
- name: v1alpha1
schema:
@ -322,9 +322,9 @@ A _Composite Resource_ based on this _Composite Resource Definition_ looks like
```yaml {label="xr2"}
# Composite Resource (XR)
apiVersion: test.example.org/v1alpha1
kind: myComputeResource
kind: MyComputeResource
metadata:
name: myResource
name: my-resource
spec:
storage: "large"
```
@ -355,7 +355,7 @@ or {{<hover label="specVersions" line="21" >}}large{{< /hover >}}.
spec:
group: test.example.org
names:
kind: myComputeResource
kind: MyComputeResource
versions:
- name: v1alpha1
served: true
@ -392,7 +392,7 @@ allows the creation of _Claims_ of `kind: computeClaim`.
spec:
group: test.example.org
names:
kind: myComputeResource
kind: MyComputeResource
claimNames:
kind: computeClaim
# Removed for brevity
@ -431,7 +431,7 @@ _Composite Resources_.
spec:
group: test.example.org
names:
kind: myComputeResource
kind: MyComputeResource
claimNames:
kind: computeClaim
# Removed for brevity
@ -477,9 +477,9 @@ The _Composite Resource Definition_ defines the
```yaml {label="xr-claim"}
# Composite Resource (XR)
apiVersion: test.example.org/v1alpha1
kind: myComputeResource
kind: MyComputeResource
metadata:
name: myResource
name: my-resource
spec:
storage: "large"
```

144
content/master/getting-started/provider-aws-part-2.md
View File

@ -308,10 +308,9 @@ with a template describing what infrastructure to deploy. Crossplane calls this
template a _Composition_.
The {{<hover label="comp" line="3">}}Composition{{</hover>}} defines all the
cloud resources to deploy.
Each entry in the template
is a full resource definitions, defining all the resource settings and metadata
like labels and annotations.
cloud resources to deploy. Each entry in the template is a full resource
definition, defining all the resource settings and metadata like labels and
annotations.
This template creates an AWS
{{<hover label="comp" line="13">}}S3{{</hover>}}
@ -319,13 +318,24 @@ This template creates an AWS
{{<hover label="comp" line="33">}}DynamoDB{{</hover>}}
{{<hover label="comp" line="34">}}Table{{</hover>}}.
Crossplane uses {{<hover label="comp" line="19">}}patches{{</hover>}} to apply
the user's input to the resource template.
This Composition takes the user's
{{<hover label="comp" line="21">}}location{{</hover>}} input and uses it as the
{{<hover label="comp" line="16">}}region{{</hover>}} used in the individual
resource.
{{<hint "important" >}}
This Composition uses an array of resource templates. You can patch each
template with data copied from the custom API. Crossplane calls this a _Patch
and Transform_ Composition.
You don't have to use Patch and Transform. Crossplane supports a variety of
alternatives, including Go Templating and CUE. You can also write a function in
Go or Python to template your resources.
Read the [Composition documentation]({{<ref "../concepts/compositions">}}) for
more information on configuring Compositions and all the available options.
{{< /hint >}}
Apply this Composition to your cluster.
```yaml {label="comp",copy-lines="all"}
@ -335,51 +345,59 @@ kind: Composition
metadata:
name: dynamo-with-bucket
spec:
resources:
- name: s3Bucket
base:
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
metadata:
name: crossplane-quickstart-bucket
spec:
forProvider:
region: us-east-2
providerConfigRef:
name: default
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.region"
transforms:
- type: map
map:
EU: "eu-north-1"
US: "us-east-2"
- name: dynamoDB
base:
apiVersion: dynamodb.aws.upbound.io/v1beta1
kind: Table
metadata:
name: crossplane-quickstart-database
spec:
forProvider:
region: "us-east-2"
writeCapacity: 1
readCapacity: 1
attribute:
- name: S3ID
type: S
hashKey: S3ID
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.region"
transforms:
- type: map
map:
EU: "eu-north-1"
US: "us-east-2"
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: s3Bucket
base:
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
metadata:
name: crossplane-quickstart-bucket
spec:
forProvider:
region: us-east-2
providerConfigRef:
name: default
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.region"
transforms:
- type: map
map:
EU: "eu-north-1"
US: "us-east-2"
- name: dynamoDB
base:
apiVersion: dynamodb.aws.upbound.io/v1beta1
kind: Table
metadata:
name: crossplane-quickstart-database
spec:
forProvider:
region: "us-east-2"
writeCapacity: 1
readCapacity: 1
attribute:
- name: S3ID
type: S
hashKey: S3ID
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.region"
transforms:
- type: map
map:
EU: "eu-north-1"
US: "us-east-2"
compositeTypeRef:
apiVersion: database.example.com/v1alpha1
kind: NoSQL
@ -389,14 +407,32 @@ EOF
The {{<hover label="comp" line="52">}}compositeTypeRef{{</hover >}} defines
which custom APIs can use this template to create resources.
A Composition uses a pipeline of _composition functions_ to define the cloud
resources to deploy. This template uses
{{<hover label="comp" line="10">}}function-patch-and-transform{{</hover>}}.
You must install the function before you can use it in a Composition.
Apply this Function to install `function-patch-and-transform`:
```yaml {label="install"}
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
name: function-patch-and-transform
spec:
package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4
EOF
```
{{<hint "tip" >}}
Read the [Composition documentation]({{<ref "../concepts/compositions">}}) for
more information on configuring Compositions and all the available options.
Read the
[Patch and Transform documentation]({{<ref "../concepts/patch-and-transform">}})
for more information on how Crossplane uses patches to map user inputs to
Composition resource templates.
[Patch and Transform function documentation]({{<ref "../guides/function-patch-and-transform">}})
for more information on how it uses patches to map user inputs to Composition
resource templates.
{{< /hint >}}
View the Composition with `kubectl get composition`

277
content/master/getting-started/provider-azure-part-2.md
View File

@ -295,13 +295,24 @@ This template creates an Azure
{{<hover label="comp" line="90">}}VirtualNetwork{{</hover>}} and
{{<hover label="comp" line="110">}}ResourceGroup{{</hover>}}.
Crossplane uses {{<hover label="comp" line="34">}}patches{{</hover>}} to apply
the user's input to the resource template.
This Composition takes the user's
{{<hover label="comp" line="36">}}location{{</hover>}} input and uses it as the
{{<hover label="comp" line="37">}}location{{</hover>}} used in the individual
resource.
{{<hint "important" >}}
This Composition uses an array of resource templates. You can patch each
template with data copied from the custom API. Crossplane calls this a _Patch
and Transform_ Composition.
You don't have to use Patch and Transform. Crossplane supports a variety of
alternatives, including Go Templating and CUE. You can also write a function in
Go or Python to template your resources.
Read the [Composition documentation]({{<ref "../concepts/compositions">}}) for
more information on configuring Compositions and all the available options.
{{< /hint >}}
Apply this Composition to your cluster.
```yaml {label="comp",copy-lines="all"}
@ -311,122 +322,130 @@ kind: Composition
metadata:
name: crossplane-quickstart-vm-with-network
spec:
resources:
- name: quickstart-vm
base:
apiVersion: compute.azure.upbound.io/v1beta1
kind: LinuxVirtualMachine
spec:
forProvider:
adminUsername: adminuser
adminSshKey:
- publicKey: ssh-rsa
AAAAB3NzaC1yc2EAAAADAQABAAABAQC+wWK73dCr+jgQOAxNsHAnNNNMEMWOHYEccp6wJm2gotpr9katuF/ZAdou5AaW1C61slRkHRkpRRX9FA9CYBiitZgvCCz+3nWNN7l/Up54Zps/pHWGZLHNJZRYyAB6j5yVLMVHIHriY49d/GZTZVNB8GoJv9Gakwc/fuEZYYl4YDFiGMBP///TzlI4jhiJzjKnEvqPFki5p2ZRJqcbCiF4pJrxUQR/RXqVFQdbRLZgYfJ8xGB878RENq3yQ39d8dVOkq4edbkzwcUmwwwkYVPIoDGsYLaRHnG+To7FvMeyO7xDVQkMKzopTQV8AuKpyvpqu0a9pWOMaiCyDytO7GGN
example@docs.crossplane.io
username: adminuser
location: "Central US"
osDisk:
- caching: ReadWrite
storageAccountType: Standard_LRS
resourceGroupNameSelector:
matchControllerRef: true
size: Standard_B1ms
sourceImageReference:
- offer: debian-11
publisher: Debian
sku: 11-backports-gen2
version: latest
networkInterfaceIdsSelector:
matchControllerRef: true
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "Sweden Central"
US: "Central US"
- name: quickstart-nic
base:
apiVersion: network.azure.upbound.io/v1beta1
kind: NetworkInterface
spec:
forProvider:
ipConfiguration:
- name: crossplane-quickstart-configuration
privateIpAddressAllocation: Dynamic
subnetIdSelector:
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: quickstart-vm
base:
apiVersion: compute.azure.upbound.io/v1beta1
kind: LinuxVirtualMachine
spec:
forProvider:
adminUsername: adminuser
adminSshKey:
- publicKey: ssh-rsa
AAAAB3NzaC1yc2EAAAADAQABAAABAQC+wWK73dCr+jgQOAxNsHAnNNNMEMWOHYEccp6wJm2gotpr9katuF/ZAdou5AaW1C61slRkHRkpRRX9FA9CYBiitZgvCCz+3nWNN7l/Up54Zps/pHWGZLHNJZRYyAB6j5yVLMVHIHriY49d/GZTZVNB8GoJv9Gakwc/fuEZYYl4YDFiGMBP///TzlI4jhiJzjKnEvqPFki5p2ZRJqcbCiF4pJrxUQR/RXqVFQdbRLZgYfJ8xGB878RENq3yQ39d8dVOkq4edbkzwcUmwwwkYVPIoDGsYLaRHnG+To7FvMeyO7xDVQkMKzopTQV8AuKpyvpqu0a9pWOMaiCyDytO7GGN
example@docs.crossplane.io
username: adminuser
location: "Central US"
osDisk:
- caching: ReadWrite
storageAccountType: Standard_LRS
resourceGroupNameSelector:
matchControllerRef: true
location: "Central US"
resourceGroupNameSelector:
matchControllerRef: true
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "Sweden Central"
US: "Central US"
- name: quickstart-subnet
base:
apiVersion: network.azure.upbound.io/v1beta1
kind: Subnet
spec:
forProvider:
addressPrefixes:
- 10.0.1.0/24
virtualNetworkNameSelector:
matchControllerRef: true
resourceGroupNameSelector:
matchControllerRef: true
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "Sweden Central"
US: "Central US"
- name: quickstart-network
base:
apiVersion: network.azure.upbound.io/v1beta1
kind: VirtualNetwork
spec:
forProvider:
addressSpace:
- 10.0.0.0/16
location: "Central US"
resourceGroupNameSelector:
matchControllerRef: true
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "Sweden Central"
US: "Central US"
- name: crossplane-resourcegroup
base:
apiVersion: azure.upbound.io/v1beta1
kind: ResourceGroup
spec:
forProvider:
location: Central US
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "Sweden Central"
US: "Central US"
size: Standard_B1ms
sourceImageReference:
- offer: debian-11
publisher: Debian
sku: 11-backports-gen2
version: latest
networkInterfaceIdsSelector:
matchControllerRef: true
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "Sweden Central"
US: "Central US"
- name: quickstart-nic
base:
apiVersion: network.azure.upbound.io/v1beta1
kind: NetworkInterface
spec:
forProvider:
ipConfiguration:
- name: crossplane-quickstart-configuration
privateIpAddressAllocation: Dynamic
subnetIdSelector:
matchControllerRef: true
location: "Central US"
resourceGroupNameSelector:
matchControllerRef: true
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "Sweden Central"
US: "Central US"
- name: quickstart-subnet
base:
apiVersion: network.azure.upbound.io/v1beta1
kind: Subnet
spec:
forProvider:
addressPrefixes:
- 10.0.1.0/24
virtualNetworkNameSelector:
matchControllerRef: true
resourceGroupNameSelector:
matchControllerRef: true
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "Sweden Central"
US: "Central US"
- name: quickstart-network
base:
apiVersion: network.azure.upbound.io/v1beta1
kind: VirtualNetwork
spec:
forProvider:
addressSpace:
- 10.0.0.0/16
location: "Central US"
resourceGroupNameSelector:
matchControllerRef: true
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "Sweden Central"
US: "Central US"
- name: crossplane-resourcegroup
base:
apiVersion: azure.upbound.io/v1beta1
kind: ResourceGroup
spec:
forProvider:
location: Central US
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "Sweden Central"
US: "Central US"
compositeTypeRef:
apiVersion: compute.example.com/v1alpha1
kind: VirtualMachine
@ -436,14 +455,32 @@ EOF
The {{<hover label="comp" line="52">}}compositeTypeRef{{</hover >}} defines
which custom APIs can use this template to create resources.
A Composition uses a pipeline of _composition functions_ to define the cloud
resources to deploy. This template uses
{{<hover label="comp" line="10">}}function-patch-and-transform{{</hover>}}.
You must install the function before you can use it in a Composition.
Apply this Function to install `function-patch-and-transform`:
```yaml {label="install"}
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
name: function-patch-and-transform
spec:
package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4
EOF
```
{{<hint "tip" >}}
Read the [Composition documentation]({{<ref "../concepts/compositions">}}) for
more information on configuring Compositions and all the available options.
Read the
[Patch and Transform documentation]({{<ref "../concepts/patch-and-transform">}})
for more information on how Crossplane uses patches to map user inputs to
Composition resource templates.
[Patch and Transform function documentation]({{<ref "../guides/function-patch-and-transform">}})
for more information on how it uses patches to map user inputs to Composition
resource templates.
{{< /hint >}}
View the Composition with `kubectl get composition`

113
content/master/getting-started/provider-gcp-part-2.md
View File

@ -337,13 +337,24 @@ This template creates a GCP
{{<hover label="comp" line="25">}}PubSub{{</hover>}}
{{<hover label="comp" line="26">}}Topic{{</hover>}}.
Crossplane uses {{<hover label="comp" line="15">}}patches{{</hover>}} to apply
the user's input to the resource template.
This Composition takes the user's
{{<hover label="comp" line="16">}}location{{</hover>}} input and uses it as the
{{<hover label="comp" line="14">}}location{{</hover>}} used in the individual
resource.
{{<hint "important" >}}
This Composition uses an array of resource templates. You can patch each
template with data copied from the custom API. Crossplane calls this a _Patch
and Transform_ Composition.
You don't have to use Patch and Transform. Crossplane supports a variety of
alternatives, including Go Templating and CUE. You can also write a function in
Go or Python to template your resources.
Read the [Composition documentation]({{<ref "../concepts/compositions">}}) for
more information on configuring Compositions and all the available options.
{{< /hint >}}
Apply this Composition to your cluster.
```yaml {label="comp",copy-lines="all"}
@ -353,39 +364,47 @@ kind: Composition
metadata:
name: topic-with-bucket
spec:
resources:
- name: crossplane-quickstart-bucket
base:
apiVersion: storage.gcp.upbound.io/v1beta1
kind: Bucket
spec:
forProvider:
location: "US"
patches:
- fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "EU"
US: "US"
- name: crossplane-quickstart-topic
base:
apiVersion: pubsub.gcp.upbound.io/v1beta1
kind: Topic
spec:
forProvider:
messageStoragePolicy:
- allowedPersistenceRegions:
- "us-central1"
patches:
- fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.messageStoragePolicy[0].allowedPersistenceRegions[0]"
transforms:
- type: map
map:
EU: "europe-central2"
US: "us-central1"
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: crossplane-quickstart-bucket
base:
apiVersion: storage.gcp.upbound.io/v1beta1
kind: Bucket
spec:
forProvider:
location: "US"
patches:
- fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "EU"
US: "US"
- name: crossplane-quickstart-topic
base:
apiVersion: pubsub.gcp.upbound.io/v1beta1
kind: Topic
spec:
forProvider:
messageStoragePolicy:
- allowedPersistenceRegions:
- "us-central1"
patches:
- fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.messageStoragePolicy[0].allowedPersistenceRegions[0]"
transforms:
- type: map
map:
EU: "europe-central2"
US: "us-central1"
compositeTypeRef:
apiVersion: queue.example.com/v1alpha1
kind: PubSub
@ -395,14 +414,32 @@ EOF
The {{<hover label="comp" line="40">}}compositeTypeRef{{</hover >}} defines
which custom APIs can use this template to create resources.
A Composition uses a pipeline of _composition functions_ to define the cloud
resources to deploy. This template uses
{{<hover label="comp" line="10">}}function-patch-and-transform{{</hover>}}.
You must install the function before you can use it in a Composition.
Apply this Function to install `function-patch-and-transform`:
```yaml {label="install"}
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
name: function-patch-and-transform
spec:
package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4
EOF
```
{{<hint "tip" >}}
Read the [Composition documentation]({{<ref "../concepts/compositions">}}) for
more information on configuring Compositions and all the available options.
Read the
[Patch and Transform documentation]({{<ref "../concepts/patch-and-transform">}})
for more information on how Crossplane uses patches to map user inputs to
Composition resource templates.
[Patch and Transform function documentation]({{<ref "../guides/function-patch-and-transform">}})
for more information on how it uses patches to map user inputs to Composition
resource templates.
{{< /hint >}}
View the Composition with `kubectl get composition`

2086
content/master/guides/function-patch-and-transform.md Normal file
View File

File diff suppressed because it is too large Load Diff

68
content/master/guides/vault-as-secret-store.md
View File

@ -411,35 +411,47 @@ spec:
compositeTypeRef:
apiVersion: ess.example.org/v1alpha1
kind: CompositeESSInstance
resources:
- name: serviceaccount
base:
apiVersion: iam.gcp.crossplane.io/v1alpha1
kind: ServiceAccount
metadata:
name: ess-test-sa
spec:
forProvider:
displayName: a service account to test ess
- name: serviceaccountkey
base:
apiVersion: iam.gcp.crossplane.io/v1alpha1
kind: ServiceAccountKey
spec:
forProvider:
serviceAccountSelector:
matchControllerRef: true
publishConnectionDetailsTo:
name: ess-mr-conn
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: serviceaccount
base:
apiVersion: iam.gcp.crossplane.io/v1alpha1
kind: ServiceAccount
metadata:
labels:
environment: development
team: backend
configRef:
name: vault
connectionDetails:
- fromConnectionSecretKey: publicKey
- fromConnectionSecretKey: publicKeyType" | kubectl apply -f -
name: ess-test-sa
spec:
forProvider:
displayName: a service account to test ess
- name: serviceaccountkey
base:
apiVersion: iam.gcp.crossplane.io/v1alpha1
kind: ServiceAccountKey
spec:
forProvider:
serviceAccountSelector:
matchControllerRef: true
publishConnectionDetailsTo:
name: ess-mr-conn
metadata:
labels:
environment: development
team: backend
configRef:
name: vault
connectionDetails:
- name: publicKey
type: FromConnectionSecretKey
fromConnectionSecretKey: publicKey
- name: publicKey
type: FromConnectionSecretKey
fromConnectionSecretKey: publicKeyType" | kubectl apply -f -
```
### Create a Claim

71
content/master/guides/write-a-composition-function-in-go.md
View File

@ -1,8 +1,5 @@
---
title: Write a Composition Function in Go
state: beta
alphaVersion: "1.11"
betaVersion: "1.14"
weight: 80
description: "Composition functions allow you to template resources using Go"
---
@ -11,7 +8,7 @@ Composition functions (or just functions, for short) are custom programs that
template Crossplane resources. Crossplane calls composition functions to
determine what resources it should create when you create a composite resource
(XR). Read the
[concepts]({{<ref "../concepts/composition-functions" >}})
[concepts]({{<ref "../concepts/compositions" >}})
page to learn more about composition functions.
You can write a function to template resources using a general purpose
@ -22,7 +19,7 @@ conditionals. This guide explains how to write a composition function in
{{< hint "important" >}}
It helps to be familiar with
[how composition functions work]({{<ref "../concepts/composition-functions#how-composition-functions-work" >}})
[how composition functions work]({{<ref "../concepts/compositions#how-composition-functions-work" >}})
before following this guide.
{{< /hint >}}
@ -79,17 +76,17 @@ build or test a composition function.
## Initialize the function from a template
Use the `crossplane beta xpkg init` command to initialize a new function. When
Use the `crossplane xpkg init` command to initialize a new function. When
you run this command it initializes your function using
[a GitHub repository](https://github.com/crossplane/function-template-go)
as a template.
```shell {copy-lines=1}
crossplane beta xpkg init function-xbuckets function-template-go -d function-xbuckets
crossplane xpkg init function-xbuckets function-template-go -d function-xbuckets
Initialized package "function-xbuckets" in directory "/home/negz/control/negz/function-xbuckets" from https://github.com/crossplane/function-template-go/tree/91a1a5eed21964ff98966d72cc6db6f089ad63f4 (main)
```
The `crossplane beta init xpkg` command creates a directory named
The `crossplane xpkg init` command creates a directory named
`function-xbuckets`. When you run the command the new directory should look like
this:
@ -111,7 +108,7 @@ some other files in the template:
<!--
This tip talks about future plans for Crossplane.
-->
In v1.14 of the Crossplane CLI `crossplane beta xpkg init` just clones a
In v1.14 of the Crossplane CLI `crossplane xpkg init` just clones a
template GitHub repository. A future CLI release will automate tasks like
replacing the template name with the new function's name. See Crossplane issue
[#4941](https://github.com/crossplane/crossplane/issues/4941) for details.
@ -134,7 +131,7 @@ should delete the `input` and `package/input` directories.
The `input` directory defines a Go struct that a function can use to take input,
using the `input` field from a Composition. The
[composition functions]({{<ref "../concepts/composition-functions" >}})
[composition functions]({{<ref "../concepts/compositions" >}})
documentation explains how to pass an input to a composition function.
The `package/input` directory contains an OpenAPI schema generated from the
@ -163,7 +160,7 @@ method in `fn.go`. When you first open the file it contains a "hello world"
function.
```go {label="hello-world"}
func (f *Function) RunFunction(_ context.Context, req *fnv1beta1.RunFunctionRequest) (*fnv1beta1.RunFunctionResponse, error) {
func (f *Function) RunFunction(_ context.Context, req *fnv1.RunFunctionRequest) (*fnv1.RunFunctionResponse, error) {
f.log.Info("Running Function", "tag", req.GetMeta().GetTag())
rsp := response.To(req, response.DefaultTTL)
@ -190,13 +187,13 @@ The function tells Crossplane what resources it should compose by returning a
Crossplane generates the `RunFunctionRequest` and `RunFunctionResponse` structs
using [Protocol Buffers](http://protobuf.dev). You can find detailed schemas for
`RunFunctionRequest` and `RunFunctionResponse` in the
[Buf Schema Registry](https://buf.build/crossplane/crossplane/docs/main:apiextensions.fn.proto.v1beta1).
[Buf Schema Registry](https://buf.build/crossplane/crossplane/docs/main:apiextensions.fn.proto.v1).
{{</hint>}}
Edit the `RunFunction` method to replace it with this code.
```go {hl_lines="4-56"}
func (f *Function) RunFunction(_ context.Context, req *fnv1beta1.RunFunctionRequest) (*fnv1beta1.RunFunctionResponse, error) {
func (f *Function) RunFunction(_ context.Context, req *fnv1.RunFunctionRequest) (*fnv1.RunFunctionResponse, error) {
rsp := response.To(req, response.DefaultTTL)
xr, err := request.GetObservedCompositeResource(req)
@ -274,7 +271,7 @@ import (
"github.com/crossplane/function-sdk-go/errors"
"github.com/crossplane/function-sdk-go/logging"
fnv1beta1 "github.com/crossplane/function-sdk-go/proto/v1beta1"
fnv1 "github.com/crossplane/function-sdk-go/proto/v1"
"github.com/crossplane/function-sdk-go/request"
"github.com/crossplane/function-sdk-go/resource"
"github.com/crossplane/function-sdk-go/resource/composed"
@ -283,14 +280,14 @@ import (
// Function returns whatever response you ask it to.
type Function struct {
fnv1beta1.UnimplementedFunctionRunnerServiceServer
fnv1.UnimplementedFunctionRunnerServiceServer
log logging.Logger
}
// RunFunction observes an XBuckets composite resource (XR). It adds an S3
// bucket to the desired state for every entry in the XR's spec.names array.
func (f *Function) RunFunction(_ context.Context, req *fnv1beta1.RunFunctionRequest) (*fnv1beta1.RunFunctionResponse, error) {
func (f *Function) RunFunction(_ context.Context, req *fnv1.RunFunctionRequest) (*fnv1.RunFunctionResponse, error) {
f.log.Info("Running Function", "tag", req.GetMeta().GetTag())
// Create a response to the request. This copies the desired state and
@ -428,8 +425,8 @@ for the SDK.
## Test the function end-to-end
Test your function by adding unit tests, and by using the `crossplane beta
render` command.
Test your function by adding unit tests, and by using the `crossplane render`
command.
Go has rich support for unit testing. When you initialize a function from the
template it adds some unit tests to `fn_test.go`. These tests follow Go's
@ -456,17 +453,17 @@ import (
"github.com/crossplane/crossplane-runtime/pkg/logging"
fnv1beta1 "github.com/crossplane/function-sdk-go/proto/v1beta1"
fnv1 "github.com/crossplane/function-sdk-go/proto/v1"
"github.com/crossplane/function-sdk-go/resource"
)
func TestRunFunction(t *testing.T) {
type args struct {
ctx context.Context
req *fnv1beta1.RunFunctionRequest
req *fnv1.RunFunctionRequest
}
type want struct {
rsp *fnv1beta1.RunFunctionResponse
rsp *fnv1.RunFunctionResponse
err error
}
@ -478,9 +475,9 @@ func TestRunFunction(t *testing.T) {
"AddTwoBuckets": {
reason: "The Function should add two buckets to the desired composed resources",
args: args{
req: &fnv1beta1.RunFunctionRequest{
Observed: &fnv1beta1.State{
Composite: &fnv1beta1.Resource{
req: &fnv1.RunFunctionRequest{
Observed: &fnv1.State{
Composite: &fnv1.Resource{
// MustStructJSON is a handy way to provide mock
// resources.
Resource: resource.MustStructJSON(`{
@ -502,10 +499,10 @@ func TestRunFunction(t *testing.T) {
},
},
want: want{
rsp: &fnv1beta1.RunFunctionResponse{
Meta: &fnv1beta1.ResponseMeta{Ttl: durationpb.New(60 * time.Second)},
Desired: &fnv1beta1.State{
Resources: map[string]*fnv1beta1.Resource{
rsp: &fnv1.RunFunctionResponse{
Meta: &fnv1.ResponseMeta{Ttl: durationpb.New(60 * time.Second)},
Desired: &fnv1.State{
Resources: map[string]*fnv1.Resource{
"xbuckets-test-bucket-a": {Resource: resource.MustStructJSON(`{
"apiVersion": "s3.aws.upbound.io/v1beta1",
"kind": "Bucket",
@ -582,7 +579,7 @@ Expand the following block to see example files.
{{<expand "The xr.yaml, composition.yaml and function.yaml files">}}
You can recreate the output below using by running `crossplane beta render` with
You can recreate the output below using by running `crossplane render` with
these files.
The `xr.yaml` file contains the composite resource to render:
@ -627,7 +624,7 @@ The `functions.yaml` file contains the Functions the Composition references in
its pipeline steps:
```yaml
apiVersion: pkg.crossplane.io/v1beta1
apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
name: function-xbuckets
@ -642,12 +639,12 @@ spec:
The Function in `functions.yaml` uses the
{{<hover label="development" line="6">}}Development{{</hover>}}
runtime. This tells `crossplane beta render` that your function is running
runtime. This tells `crossplane render` that your function is running
locally. It connects to your locally running function instead of using Docker to
pull and run the function.
```yaml {label="development"}
apiVersion: pkg.crossplane.io/v1beta1
apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
name: function-xbuckets
@ -667,10 +664,10 @@ to run without encryption or authentication. Only use it during testing and
development.
{{</hint>}}
In a separate terminal, run `crossplane beta render`.
In a separate terminal, run `crossplane render`.
```shell
crossplane beta render xr.yaml composition.yaml functions.yaml
crossplane render xr.yaml composition.yaml functions.yaml
```
This command calls your function. In the terminal where your function is running
@ -682,7 +679,7 @@ go run . --insecure --debug
2023-10-31T16:17:32.159-0700 INFO function-xbuckets/fn.go:125 Added desired buckets {"xr-version": "example.crossplane.io/v1", "xr-kind": "XBuckets", "xr-name": "example-buckets", "region": "us-east-2", "count": 3}
```
The `crossplane beta render` command prints the desired resources the function
The `crossplane render` command prints the desired resources the function
returns.
```yaml
@ -740,7 +737,7 @@ spec:
{{<hint "tip">}}
Read the composition functions documentation to learn more about
[testing composition functions]({{< ref "../concepts/composition-functions#test-a-composition-that-uses-functions" >}}).
[testing composition functions]({{< ref "../concepts/compositions#test-a-composition" >}}).
{{</hint>}}
## Build and push the function to a package registry
@ -757,7 +754,7 @@ then pushing all the packages to a single tag in the registry.
Pushing your function to a registry allows you to use your function in a
Crossplane control plane. See the
[composition functions documentation]({{<ref "../concepts/composition-functions" >}}).
[composition functions documentation]({{<ref "../concepts/compositions" >}}).
to learn how to use a function in a control plane.
Use Docker to build a runtime for each platform.

81
content/master/guides/write-a-composition-function-in-python.md
View File

@ -1,8 +1,5 @@
---
title: Write a Composition Function in Python
state: beta
alphaVersion: "1.11"
betaVersion: "1.14"
weight: 81
description: "Composition functions allow you to template resources using Python"
---
@ -11,7 +8,7 @@ Composition functions (or just functions, for short) are custom programs that
template Crossplane resources. Crossplane calls composition functions to
determine what resources it should create when you create a composite resource
(XR). Read the
[concepts]({{<ref "../concepts/composition-functions" >}})
[concepts]({{<ref "../concepts/compositions" >}})
page to learn more about composition functions.
You can write a function to template resources using a general purpose
@ -22,7 +19,7 @@ conditionals. This guide explains how to write a composition function in
{{< hint "important" >}}
It helps to be familiar with
[how composition functions work]({{<ref "../concepts/composition-functions#how-composition-functions-work" >}})
[how composition functions work]({{<ref "../concepts/compositions#how-composition-functions-work" >}})
before following this guide.
{{< /hint >}}
@ -80,17 +77,17 @@ build or test a composition function.
## Initialize the function from a template
Use the `crossplane beta xpkg init` command to initialize a new function. When
Use the `crossplane xpkg init` command to initialize a new function. When
you run this command it initializes your function using
[a GitHub repository](https://github.com/crossplane/function-template-python)
as a template.
```shell {copy-lines=1}
crossplane beta xpkg init function-xbuckets https://github.com/crossplane/function-template-python -d function-xbuckets
crossplane xpkg init function-xbuckets https://github.com/crossplane/function-template-python -d function-xbuckets
Initialized package "function-xbuckets" in directory "/home/negz/control/negz/function-xbuckets" from https://github.com/crossplane/function-template-python/tree/bfed6923ab4c8e7adeed70f41138645fc7d38111 (main)
```
The `crossplane beta init xpkg` command creates a directory named
The `crossplane xpkg init` command creates a directory named
`function-xbuckets`. When you run the command the new directory should look like
this:
@ -118,7 +115,7 @@ know about some other files in the template:
<!--
This tip talks about future plans for Crossplane.
-->
In v1.14 of the Crossplane CLI `crossplane beta xpkg init` just clones a
In v1.14 of the Crossplane CLI `crossplane xpkg init` just clones a
template GitHub repository. A future CLI release will automate tasks like
replacing the template name with the new function's name. See Crossplane issue
[#4941](https://github.com/crossplane/crossplane/issues/4941) for details.
@ -132,7 +129,7 @@ The `package/input` directory defines the OpenAPI schema for the a function's
input. The function in this guide doesn't accept an input. Delete the
`package/input` directory.
The [composition functions]({{<ref "../concepts/composition-functions" >}})
The [composition functions]({{<ref "../concepts/compositions" >}})
documentation explains composition function inputs.
{{<hint "tip">}}
@ -151,7 +148,7 @@ method in `function/fn.py`. When you first open the file it contains a "hello
world" function.
```python {label="hello-world"}
async def RunFunction(self, req: fnv1beta1.RunFunctionRequest, _: grpc.aio.ServicerContext) -> fnv1beta1.RunFunctionResponse:
async def RunFunction(self, req: fnv1.RunFunctionRequest, _: grpc.aio.ServicerContext) -> fnv1.RunFunctionResponse:
log = self.log.bind(tag=req.meta.tag)
log.info("Running function")
@ -178,7 +175,7 @@ The function tells Crossplane what resources it should compose by returning a
Edit the `RunFunction` method to replace it with this code.
```python {hl_lines="7-28"}
async def RunFunction(self, req: fnv1beta1.RunFunctionRequest, _: grpc.aio.ServicerContext) -> fnv1beta1.RunFunctionResponse:
async def RunFunction(self, req: fnv1.RunFunctionRequest, _: grpc.aio.ServicerContext) -> fnv1.RunFunctionResponse:
log = self.log.bind(tag=req.meta.tag)
log.info("Running function")
@ -219,11 +216,11 @@ commentary explaining the function's logic.
import grpc
from crossplane.function import logging, response
from crossplane.function.proto.v1beta1 import run_function_pb2 as fnv1beta1
from crossplane.function.proto.v1beta1 import run_function_pb2_grpc as grpcv1beta1
from crossplane.function.proto.v1 import run_function_pb2 as fnv1
from crossplane.function.proto.v1 import run_function_pb2_grpc as grpcv1
class FunctionRunner(grpcv1beta1.FunctionRunnerService):
class FunctionRunner(grpcv1.FunctionRunnerService):
"""A FunctionRunner handles gRPC RunFunctionRequests."""
def __init__(self):
@ -231,8 +228,8 @@ class FunctionRunner(grpcv1beta1.FunctionRunnerService):
self.log = logging.get_logger()
async def RunFunction(
self, req: fnv1beta1.RunFunctionRequest, _: grpc.aio.ServicerContext
) -> fnv1beta1.RunFunctionResponse:
self, req: fnv1.RunFunctionRequest, _: grpc.aio.ServicerContext
) -> fnv1.RunFunctionResponse:
"""Run the function."""
# Create a logger for this request.
log = self.log.bind(tag=req.meta.tag)
@ -257,7 +254,7 @@ class FunctionRunner(grpcv1beta1.FunctionRunnerService):
# the key and mutate its value as if it did exist.
#
# The below code works because accessing the xbuckets-{name} key
# automatically creates a new, empty fnv1beta1.Resource message. The
# automatically creates a new, empty fnv1.Resource message. The
# Resource message has a resource field containing an empty Struct
# object that can be populated from a dictionary by calling update.
#
@ -308,7 +305,7 @@ Read [the Python Function SDK documentation](https://crossplane.github.io/functi
The Python SDK automatically generates the `RunFunctionRequest` and
`RunFunctionResponse` Python objects from a
[Protocol Buffers](https://protobuf.dev) schema. You can see the schema in the
[Buf Schema Registry](https://buf.build/crossplane/crossplane/docs/main:apiextensions.fn.proto.v1beta1).
[Buf Schema Registry](https://buf.build/crossplane/crossplane/docs/main:apiextensions.fn.proto.v1).
The fields of the generated Python objects behave similarly to builtin Python
types like dictionaries and lists. Be aware that there are some differences.
@ -321,7 +318,7 @@ Instead of adding a new resource like this:
```python
resource = {"apiVersion": "example.org/v1", "kind": "Composed", ...}
rsp.desired.resources["new-resource"] = fnv1beta1.Resource(resource=resource)
rsp.desired.resources["new-resource"] = fnv1.Resource(resource=resource)
```
Pretend it already exists and mutate it, like this:
@ -338,8 +335,8 @@ for further details.
## Test the function end-to-end
Test your function by adding unit tests, and by using the `crossplane beta
render` command.
Test your function by adding unit tests, and by using the `crossplane render`
command.
When you initialize a function from the
template it adds some unit tests to `tests/test_fn.py`. These tests use the
@ -355,7 +352,7 @@ import dataclasses
import unittest
from crossplane.function import logging, resource
from crossplane.function.proto.v1beta1 import run_function_pb2 as fnv1beta1
from crossplane.function.proto.v1 import run_function_pb2 as fnv1
from google.protobuf import duration_pb2 as durationpb
from google.protobuf import json_format
from google.protobuf import struct_pb2 as structpb
@ -372,15 +369,15 @@ class TestFunctionRunner(unittest.IsolatedAsyncioTestCase):
@dataclasses.dataclass
class TestCase:
reason: str
req: fnv1beta1.RunFunctionRequest
want: fnv1beta1.RunFunctionResponse
req: fnv1.RunFunctionRequest
want: fnv1.RunFunctionResponse
cases = [
TestCase(
reason="The function should compose two S3 buckets.",
req=fnv1beta1.RunFunctionRequest(
observed=fnv1beta1.State(
composite=fnv1beta1.Resource(
req=fnv1.RunFunctionRequest(
observed=fnv1.State(
composite=fnv1.Resource(
resource=resource.dict_to_struct(
{
"apiVersion": "example.crossplane.io/v1alpha1",
@ -395,11 +392,11 @@ class TestFunctionRunner(unittest.IsolatedAsyncioTestCase):
)
)
),
want=fnv1beta1.RunFunctionResponse(
meta=fnv1beta1.ResponseMeta(ttl=durationpb.Duration(seconds=60)),
desired=fnv1beta1.State(
want=fnv1.RunFunctionResponse(
meta=fnv1.ResponseMeta(ttl=durationpb.Duration(seconds=60)),
desired=fnv1.State(
resources={
"xbuckets-test-bucket-a": fnv1beta1.Resource(
"xbuckets-test-bucket-a": fnv1.Resource(
resource=resource.dict_to_struct(
{
"apiVersion": "s3.aws.upbound.io/v1beta1",
@ -415,7 +412,7 @@ class TestFunctionRunner(unittest.IsolatedAsyncioTestCase):
}
)
),
"xbuckets-test-bucket-b": fnv1beta1.Resource(
"xbuckets-test-bucket-b": fnv1.Resource(
resource=resource.dict_to_struct(
{
"apiVersion": "s3.aws.upbound.io/v1beta1",
@ -482,7 +479,7 @@ Expand the following block to see example files.
{{<expand "The xr.yaml, composition.yaml and function.yaml files">}}
You can recreate the output below using by running `crossplane beta render` with
You can recreate the output below using by running `crossplane render` with
these files.
The `xr.yaml` file contains the composite resource to render:
@ -527,7 +524,7 @@ The `functions.yaml` file contains the Functions the Composition references in
its pipeline steps:
```yaml
apiVersion: pkg.crossplane.io/v1beta1
apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
name: function-xbuckets
@ -542,12 +539,12 @@ spec:
The Function in `functions.yaml` uses the
{{<hover label="development" line="6">}}Development{{</hover>}}
runtime. This tells `crossplane beta render` that your function is running
runtime. This tells `crossplane render` that your function is running
locally. It connects to your locally running function instead of using Docker to
pull and run the function.
```yaml {label="development"}
apiVersion: pkg.crossplane.io/v1beta1
apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
name: function-xbuckets
@ -566,10 +563,10 @@ hatch run development
Only use it during testing and development.
{{</hint>}}
In a separate terminal, run `crossplane beta render`.
In a separate terminal, run `crossplane render`.
```shell
crossplane beta render xr.yaml composition.yaml functions.yaml
crossplane render xr.yaml composition.yaml functions.yaml
```
This command calls your function. In the terminal where your function is running
@ -581,7 +578,7 @@ hatch run development
2024-01-11T22:12:58.153792Z [info ] Added desired buckets count=3 filename=fn.py lineno=68 region=us-east-2 tag=
```
The `crossplane beta render` command prints the desired resources the function
The `crossplane render` command prints the desired resources the function
returns.
```yaml
@ -639,7 +636,7 @@ spec:
{{<hint "tip">}}
Read the composition functions documentation to learn more about
[testing composition functions]({{< ref "../concepts/composition-functions#test-a-composition-that-uses-functions" >}}).
[testing composition functions]({{< ref "../concepts/compositions#test-a-composition" >}}).
{{</hint>}}
## Build and push the function to a package registry
@ -656,7 +653,7 @@ then pushing all the packages to a single tag in the registry.
Pushing your function to a registry allows you to use your function in a
Crossplane control plane. See the
[composition functions documentation]({{<ref "../concepts/composition-functions" >}}).
[composition functions documentation]({{<ref "../concepts/compositions" >}}).
to learn how to use a function in a control plane.
Use Docker to build a runtime for each platform.

31
content/master/release-notes/1.15.0.md
View File

@ -1,31 +0,0 @@
---
title: v1.15.0
released: November 15, 2023
weight: 10
---
The v1.15.0 release is a quarterly Crossplane release.
Read the
[Crossplane announcement blog](https://blog.crossplane.io/crossplane-v1-15/).
### 🎉 Highlights
<!-- vale write-good.Weasel = NO -->
* The default [Crossplane package registry]({{<ref "../concepts/packages#install-a-configuration">}}) is now `xpkg.upbound.io`.
* New CLI [top]({{<ref "../cli/command-reference#beta-top">}}) command to view CPU
and memory usage.
* Expanding the CLI [trace]({{<ref "../cli/command-reference#beta-trace">}}) command to
provide more details on package dependencies, types and revisions.
* Support in the [xpkg init]({{<ref "../cli/command-reference#beta-xpkg-init">}}) command
to support a `NOTES.txt` file and initialization scripts.
* A new [migrate]({{<ref "../cli/command-reference#beta-convert">}}) command to help
migrations from existing API kinds to future versions.
<!--more-->
### 🚨 Warnings and breaking changes
* The default package registry changed from `index.docker.io` to `xpkg.upbound.io`.
* Removed RBAC manager `--manage` flag.
<!-- vale write-good.Weasel = YES -->

9
content/master/release-notes/_index.md
View File

@ -1,9 +0,0 @@
---
title: Release Notes
weight: 600
description: "Crossplane release notes"
product: "Release Notes"
cascade:
releaseNotes: true
---

63
content/master/release-notes/docs.md
View File

@ -1,63 +0,0 @@
---
title: Docs Changelog
weight: 999
---
Changes and notable docs updates.
<!---
new: 🎉
changed/fixed: 🏗️
removed: 🗑️
moved: 🗺️
-->
## March 14, 2024
### Removed content 🗑️
Removed information on installing Crossplane
[Providers]({{<ref "../concepts/providers#install-offline">}}) and
[Packages]({{<ref "../concepts/packages#install-offline">}}) offline using
the local package cache. Installing via the local package cache isn't intended
to be user facing and the recommended offline install method is with a private
registry.
## February 22, 2024
### Updated content 🏗️
* New [Crossplane upgrade]({{<ref "../software/upgrade">}}) documentation.
* Added notes to the [managed resources]({{<ref "../concepts/managed-resources" >}})
page that Crossplane can't delete paused resources.
* Upgrade the AWS quickstart to use the new "no fork" Upjet provider version 1.1.0
* Add links to the quickstart guides to the different authentication methods for
the provider.
* Expanded `crossplane beta validate` [command reference]({{<ref "../cli/command-reference#beta-validate">}}).
* Documentation for the new [server side apply]({{<ref "../concepts/server-side-apply" >}}) alpha feature.
### 🔨 Docs fixes
<!-- vale Google.WordList = NO -->
<!-- allow "check" -->
* Fixed [an issue](https://github.com/crossplane/docs/pull/718) where mermaid
diagrams didn't display the right colors across light and dark modes.
* Added support for a "[you are here](https://github.com/crossplane/docs/pull/716)"
feature for doc page table of contents.
* Fixed the color of check marks (✔️) in dark mode.
<!-- vale Google.WordList = YES -->
## February 15, 2024
<!-- ### New features 🎉 -->
### Updated content 🏗️
* New content for [v1.15.0 release]({{<ref "./1.15.0.md" >}}).
### Removed content 🗑️
* Removed end of support v1.12 documentation. Content
[archived on GitHub](https://github.com/crossplane/docs/releases/tag/v1.12-archive).
### 🔨 Docs fixes
* Fixed issues related to displaying tables in dark mode.

2
content/v1.14/concepts/connection-details.md
View File

@ -10,7 +10,7 @@ Using connection details in Crossplane requires the following components:
* Define the `writeConnectionSecretToRef` name and namespace for each resource in the
[Composition]({{<ref "/master/concepts/compositions#composed-resource-secrets">}}).
* Define the list of secret keys produced by each composed resource with `connectionDetails` in the
[Composition]({{<ref "/master/concepts/compositions#define-secret-keys">}}).
[Composition]({{<ref "./compositions#define-secret-keys">}}).
* Optionally, define the `connectionSecretKeys` in a
[CompositeResourceDefinition]({{<ref "/master/concepts/composite-resource-definitions#manage-connection-secrets">}}).

130
content/v1.14/release-notes/1.14.0.md
View File

@ -1,130 +0,0 @@
---
title: v1.14.0
released: November, 1, 2023
weight: 10
---
The v1.14.0 release is a quarterly Crossplane release.
Read the
[Crossplane announcement blog](https://blog.crossplane.io/crossplane-v1-14/).
### 🎉 Highlights
<!-- vale write-good.Weasel = NO -->
* [Composition functions]({{< ref "../concepts/composition-functions">}}) promoted to `v1beta1`.
* A new [Provider DeploymentRuntimeConfig]({{<ref "../concepts/providers#controller-configuration">}}) to eventually replace the deprecated `ControllerConfig`.
* New [Crossplane CLI]({{<ref "../cli" >}}) for troubleshooting and package management.
* Support for ordered deletion with [Usages]({{<ref "../concepts/usages">}}).
* Alpha support for [real time composition]({{<ref "../concepts/pods#enable-real-time-compositions">}})
<!--more-->
### 🚨 Warnings and breaking changes
* Crossplane Helm images have moved from `index.docker.io` to `xpkg.upbound.io`.
Images are still published to `index.docker.io` but is moving to only publish on
`xpkg.upbound.io` in a future release.
* Changes to TLS certificates. Existing users of external secret stores need to
manually update their TLS certificates. Read [Crossplane issue #4565](https://github.com/crossplane/crossplane/pull/4656) for more information.
* Removed Vault support for External Secret Stores. Crossplane
suggests using the [ESS Plugins]({{<ref "../guides/vault-as-secret-store">}}) as a replacement.
* Removed the `controllerConfigRef` from the Configuration package
and package revision APIs.
* The introduction of the new [Crossplane CLI]({{<ref "../cli" >}}) deprecates
the existing `kubectl crossplane` plugin.
* The `v1beta1` implementation of Composition Functions is incompatible with
existing `v1alpha1` functions.
### 💡 New features
What's new in v1.14.0
#### Crossplane CLI
Crossplane v1.14 introduces a rebuilt [Crossplane CLI]({{<ref "../cli" >}}).
The Crossplane CLI provides features to help troubleshoot Crossplane resources,
build and publish Crossplane packages and locally test composition functions.
Read the [CLI documentation]({{<ref "../cli" >}}) for information on installing
and the full set of
supported features.
#### Real time Compositions
This release adds the alpha feature "real time compositions" to Crossplane.
Real time compositions allow Kubernetes to immediately notify Crossplane of
changes to composed resources. Crossplane doesn't need to poll resources to
determine their state.
Real time compositions dramatically speed up the time Crossplane reacts to
changes or failures of managed resources.
The real time compositions feature is an alpha feature and isn't enabled by default.
The [Crossplane pods]({{<ref "../concepts/pods#enable-real-time-compositions">}})
documentation has more information about real time compositions.
#### Ordered resource deletion
Crossplane introduces a new `usages` type to prevent resources from
deletion or to ensure deletion happens in the correct order.
A `Usages` defines a dependency mapping between a resource and any dependencies.
Crossplane can't delete the parent resource until after deleting the child
resource.
A `usage` also allow Crossplane to prevent accidental deletion of a resource.
The `usage` feature is an alpha feature and isn't enabled by default.
The [Usages]({{<ref "../concepts/usages">}}) documentation provides information
on enabling and configuring Usages.
### 🏗️ Notable changes
#### Composition functions
v1.14 promotes composition functions to `v1beta1` with a new, more scalable
architecture for running functions.
Crossplane v1.14 includes CLI tooling, templates, SDKs, and documentation for
building functions.
Several new functions available for the new architecture,
including
[function patch and transform](https://github.com/crossplane-contrib/function-patch-and-transform),
[function Go templating](https://github.com/crossplane-contrib/function-go-templating),
and
[function cue](https://github.com/crossplane-contrib/function-cue).
#### Management policies enabled by default
Managed resource "[management policies]({{<ref "../concepts/managed-resources#managementpolicies">}})" moved to beta and are now enabled by
default.
<!-- vale write-good.Passive = NO -->
#### Object has been modified warnings
<!-- vale write-good.Passive = YES -->
Crossplane changed the behavior causing the event message
<!-- vale off -->
> cannot patch object: Operation cannot be fulfilled on compositenetworks.gcp.platformref.crossplane.io "test-network-d6xjh": the object has been modified; please apply your changes to the latest version and try again`
<!-- vale on -->
#### Adding extra objects during Crossplane install
The Crossplane Helm chart now supports an `extraObjects: []` array to install
other Kubernetes objects during the Crossplane install.
#### Support for pausing other Crossplane objects
The Crossplane annotation `crossplane.io/paused` is now supported in Claims,
Composites, Configurations, Functions and Provider objects.
<!-- vale write-good.Weasel = YES -->

17
content/v1.14/release-notes/1.14.1.md
View File

@ -1,17 +0,0 @@
---
title: v1.14.1
released: November, 14, 2023
weight: 11
---
The v1.14.1 release fixes an issue with the Crossplane CLI discovered
after the v1.14.0 release.
### 🐛 Bug fixes
* Resolves an issue with `crossplane xpkg` pushing a two packages, one with
`--` appended. [#4980](https://github.com/crossplane/crossplane/issues/4980)
* The Protobuf schema now automatically publishes to the
[Buf Schema registry](https://buf.build/crossplane/crossplane).
<!--more-->

29
content/v1.14/release-notes/1.14.2.md
View File

@ -1,29 +0,0 @@
---
title: v1.14.2
released: November, 21, 2023
weight: 11
---
The v1.14.2 fixes an issue where Crossplane incorrectly deletes a Provider
ServiceAccount when using a custom ServiceAccount name in a
DeploymentRuntimeConfig or ControllerConfig.
### 🐛 Bug fixes
* Resolves an issue where Crossplane deletes a ServiceAccount and may cause
"Unauthorized" errors in a Provider pod.
Issue [#5017](https://github.com/crossplane/crossplane/issues/5017).
* Improves Crossplane's handling of package deactivation when there are a
large number of objects managed by Crossplane.
PR [#5044](https://github.com/crossplane/crossplane/pull/5044).
* Corrects the use of the service name in conversion webhooks.
PR [#5108](https://github.com/crossplane/crossplane/pull/5018).
### 🚀 Improvements
* Prevent an unnecessary wait condition in Compositions.
[#5034](https://github.com/crossplane/crossplane/pull/5034)
### 🔒 Security updates
* Updates Docker includes to resolve
[multiple CVEs](https://github.com/advisories/GHSA-jq35-85cj-fj4p).
<!--more-->

13
content/v1.14/release-notes/1.14.3.md
View File

@ -1,13 +0,0 @@
---
title: v1.14.3
released: November, 24, 2023
---
The v1.14.3 corrects an accidental behavior change in v1.14.0 that changed
the order Crossplane applies patches when using environment patches.
### 🐛 Bug fixes
* Correct patch ordering. Issue [#5050](https://github.com/crossplane/crossplane/issues/5050)
<!--more-->

25
content/v1.14/release-notes/1.14.4.md
View File

@ -1,25 +0,0 @@
---
title: v1.14.4
released: December, 12, 2023
---
Version 1.14.4 creates a **breaking change** for users of `environmentConfigs`
selectors. Before, if there are no matches by the selector in `Single` mode,
Crossplane ignores the patch. Now Crossplane issues an error.
To use the older behavior in v1.14.4 and later use mode `Multiple`.
### 🐛 Bug fixes
* Sets RBAC for Crossplane to access finalizers with the
`OwnerReferencePermissionEnforcement` Kubernetes admission controller enabled.
PR [#5088](https://github.com/crossplane/crossplane/pull/5088).
* Reduces the number of events generated by `SyncPackage` and
`InstallPackageRevision`. PR [#5066](https://github.com/crossplane/crossplane/pull/5066)
### 🚨 Behavior changes
* Changes the behavior of `environmentConfigs`
[selector policies]({{<ref "../concepts/environment-configs#manage-selector-results">}}).
* Introduces a new `minMatch` option for `environmentConfig` selector policies.
<!--more-->

9
content/v1.14/release-notes/_index.md
View File

@ -1,9 +0,0 @@
---
title: Release Notes
weight: 20
description: "Crossplane release notes"
product: "Release Notes"
cascade:
releaseNotes: true
---

52
content/v1.14/release-notes/docs.md
View File

@ -1,52 +0,0 @@
---
title: Docs Changelog
weight: 999
---
Changes and notable docs updates.
<!---
new: 🎉
changed/fixed: 🏗️
removed: 🗑️
moved: 🗺️
-->
## March 14, 2024
### Removed content 🗑️
Removed information on installing Crossplane
[Providers]({{<ref "../concepts/providers#install-offline">}}) and
[Packages]({{<ref "../concepts/packages#install-offline">}}) offline using
the local package cache. Installing via the local package cache isn't intended
to be user facing and the recommended offline install method is with a private
registry.
## December 1, 2023
### New features 🎉
* Added [API documentation]({{<ref "../api">}}) for Crossplane core types.
## November 30, 2023
### New features 🎉
* Added RSS support for Crossplane release notes.
## November 1, 2023
### New content 🎉
* Created the v1.14 release documentation.
* New [CLI]({{<ref "../cli">}}) documentation.
* New [release notes]({{<ref "../release-notes">}}) section.
* [Usages]({{<ref "../concepts/usages">}}) Crossplane type.
### Updated content 🏗️
* Rewritten [packages]({{<ref "../concepts/packages">}}) section focused on Crossplane configuration packages.
* Expanded [providers]({{<ref "../concepts/providers">}}) content related to using Provider packages.
* Major updates to [Composition Functions]({{<ref "../concepts/composition-functions" >}}), moving them to `v1beta1`.
### Removed content 🗑️
* Removed end of support v1.11 documentation. Content archived on GitHub.

2
content/v1.15/concepts/connection-details.md
View File

@ -10,7 +10,7 @@ Using connection details in Crossplane requires the following components:
* Define the `writeConnectionSecretToRef` name and namespace for each resource in the
[Composition]({{<ref "/master/concepts/compositions#composed-resource-secrets">}}).
* Define the list of secret keys produced by each composed resource with `connectionDetails` in the
[Composition]({{<ref "/master/concepts/compositions#define-secret-keys">}}).
[Composition]({{<ref "./compositions#define-secret-keys">}}).
* Optionally, define the `connectionSecretKeys` in a
[CompositeResourceDefinition]({{<ref "/master/concepts/composite-resource-definitions#manage-connection-secrets">}}).

31
content/v1.15/release-notes/1.15.0.md
View File

@ -1,31 +0,0 @@
---
title: v1.15.0
released: November 15, 2023
weight: 10
---
The v1.15.0 release is a quarterly Crossplane release.
Read the
[Crossplane announcement blog](https://blog.crossplane.io/crossplane-v1-15/).
### 🎉 Highlights
<!-- vale write-good.Weasel = NO -->
* The default [Crossplane package registry]({{<ref "../concepts/packages#install-a-configuration">}}) is now `xpkg.upbound.io`.
* New CLI [top]({{<ref "../cli/command-reference#beta-top">}}) command to view CPU
and memory usage.
* Expanding the CLI [trace]({{<ref "../cli/command-reference#beta-trace">}}) command to
provide more details on package dependencies, types and revisions.
* Support in the [xpkg init]({{<ref "../cli/command-reference#beta-xpkg-init">}}) command
to support a `NOTES.txt` file and initialization scripts.
* A new [migrate]({{<ref "../cli/command-reference#beta-convert">}}) command to help
migrations from existing API kinds to future versions.
<!--more-->
### 🚨 Warnings and breaking changes
* The default package registry changed from `index.docker.io` to `xpkg.upbound.io`.
* Removed RBAC manager `--manage` flag.
<!-- vale write-good.Weasel = YES -->

9
content/v1.15/release-notes/_index.md
View File

@ -1,9 +0,0 @@
---
title: Release Notes
weight: 600
description: "Crossplane release notes"
product: "Release Notes"
cascade:
releaseNotes: true
---

63
content/v1.15/release-notes/docs.md
View File

@ -1,63 +0,0 @@
---
title: Docs Changelog
weight: 999
---
Changes and notable docs updates.
<!---
new: 🎉
changed/fixed: 🏗️
removed: 🗑️
moved: 🗺️
-->
## March 14, 2024
### Removed content 🗑️
Removed information on installing Crossplane
[Providers]({{<ref "../concepts/providers#install-offline">}}) and
[Packages]({{<ref "../concepts/packages#install-offline">}}) offline using
the local package cache. Installing via the local package cache isn't intended
to be user facing and the recommended offline install method is with a private
registry.
## February 22, 2024
### Updated content 🏗️
* New [Crossplane upgrade]({{<ref "../software/upgrade">}}) documentation.
* Added notes to the [managed resources]({{<ref "../concepts/managed-resources" >}})
page that Crossplane can't delete paused resources.
* Upgrade the AWS quickstart to use the new "no fork" Upjet provider version 1.1.0
* Add links to the quickstart guides to the different authentication methods for
the provider.
* Expanded `crossplane beta validate` [command reference]({{<ref "../cli/command-reference#beta-validate">}}).
* Documentation for the new [server side apply]({{<ref "../concepts/server-side-apply" >}}) alpha feature.
### 🔨 Docs fixes
<!-- vale Google.WordList = NO -->
<!-- allow "check" -->
* Fixed [an issue](https://github.com/crossplane/docs/pull/718) where mermaid
diagrams didn't display the right colors across light and dark modes.
* Added support for a "[you are here](https://github.com/crossplane/docs/pull/716)"
feature for doc page table of contents.
* Fixed the color of check marks (✔️) in dark mode.
<!-- vale Google.WordList = YES -->
## February 15, 2024
<!-- ### New features 🎉 -->
### Updated content 🏗️
* New content for [v1.15.0 release]({{<ref "./1.15.0.md" >}}).
### Removed content 🗑️
* Removed end of support v1.12 documentation. Content
[archived on GitHub](https://github.com/crossplane/docs/releases/tag/v1.12-archive).
### 🔨 Docs fixes
* Fixed issues related to displaying tables in dark mode.

2
content/v1.16/concepts/connection-details.md
View File

@ -10,7 +10,7 @@ Using connection details in Crossplane requires the following components:
* Define the `writeConnectionSecretToRef` name and namespace for each resource in the
[Composition]({{<ref "/master/concepts/compositions#composed-resource-secrets">}}).
* Define the list of secret keys produced by each composed resource with `connectionDetails` in the
[Composition]({{<ref "/master/concepts/compositions#define-secret-keys">}}).
[Composition]({{<ref "./compositions#define-secret-keys">}}).
* Optionally, define the `connectionSecretKeys` in a
[CompositeResourceDefinition]({{<ref "/master/concepts/composite-resource-definitions#manage-connection-secrets">}}).

31
content/v1.16/release-notes/1.15.0.md
View File

@ -1,31 +0,0 @@
---
title: v1.15.0
released: November 15, 2023
weight: 10
---
The v1.15.0 release is a quarterly Crossplane release.
Read the
[Crossplane announcement blog](https://blog.crossplane.io/crossplane-v1-15/).
### 🎉 Highlights
<!-- vale write-good.Weasel = NO -->
* The default [Crossplane package registry]({{<ref "../concepts/packages#install-a-configuration">}}) is now `xpkg.upbound.io`.
* New CLI [top]({{<ref "../cli/command-reference#beta-top">}}) command to view CPU
and memory usage.
* Expanding the CLI [trace]({{<ref "../cli/command-reference#beta-trace">}}) command to
provide more details on package dependencies, types and revisions.
* Support in the [xpkg init]({{<ref "../cli/command-reference#beta-xpkg-init">}}) command
to support a `NOTES.txt` file and initialization scripts.
* A new [migrate]({{<ref "../cli/command-reference#beta-convert">}}) command to help
migrations from existing API kinds to future versions.
<!--more-->
### 🚨 Warnings and breaking changes
* The default package registry changed from `index.docker.io` to `xpkg.upbound.io`.
* Removed RBAC manager `--manage` flag.
<!-- vale write-good.Weasel = YES -->

9
content/v1.16/release-notes/_index.md
View File

@ -1,9 +0,0 @@
---
title: Release Notes
weight: 600
description: "Crossplane release notes"
product: "Release Notes"
cascade:
releaseNotes: true
---

63
content/v1.16/release-notes/docs.md
View File

@ -1,63 +0,0 @@
---
title: Docs Changelog
weight: 999
---
Changes and notable docs updates.
<!---
new: 🎉
changed/fixed: 🏗️
removed: 🗑️
moved: 🗺️
-->
## March 14, 2024
### Removed content 🗑️
Removed information on installing Crossplane
[Providers]({{<ref "../concepts/providers#install-offline">}}) and
[Packages]({{<ref "../concepts/packages#install-offline">}}) offline using
the local package cache. Installing via the local package cache isn't intended
to be user facing and the recommended offline install method is with a private
registry.
## February 22, 2024
### Updated content 🏗️
* New [Crossplane upgrade]({{<ref "../software/upgrade">}}) documentation.
* Added notes to the [managed resources]({{<ref "../concepts/managed-resources" >}})
page that Crossplane can't delete paused resources.
* Upgrade the AWS quickstart to use the new "no fork" Upjet provider version 1.1.0
* Add links to the quickstart guides to the different authentication methods for
the provider.
* Expanded `crossplane beta validate` [command reference]({{<ref "../cli/command-reference#beta-validate">}}).
* Documentation for the new [server side apply]({{<ref "../concepts/server-side-apply" >}}) alpha feature.
### 🔨 Docs fixes
<!-- vale Google.WordList = NO -->
<!-- allow "check" -->
* Fixed [an issue](https://github.com/crossplane/docs/pull/718) where mermaid
diagrams didn't display the right colors across light and dark modes.
* Added support for a "[you are here](https://github.com/crossplane/docs/pull/716)"
feature for doc page table of contents.
* Fixed the color of check marks (✔️) in dark mode.
<!-- vale Google.WordList = YES -->
## February 15, 2024
<!-- ### New features 🎉 -->
### Updated content 🏗️
* New content for [v1.15.0 release]({{<ref "./1.15.0.md" >}}).
### Removed content 🗑️
* Removed end of support v1.12 documentation. Content
[archived on GitHub](https://github.com/crossplane/docs/releases/tag/v1.12-archive).
### 🔨 Docs fixes
* Fixed issues related to displaying tables in dark mode.

4
utils/vale/styles/Crossplane/crossplane-words.txt
View File

@ -21,6 +21,7 @@ crossplane-edit
crossplane-view
crossplane.yaml
Crossplane's
CUE
definition.yaml
deletionPolicy
DeploymentRuntimeConfig
@ -34,8 +35,10 @@ FromCompositeFieldPath
FromEnvironmentFieldPath
fromFieldPath
HealthyPackageRevision
Helm-like
InactivePackageRevision
initProvider
KCL
LateInitialize
managementPolicies
MR
@ -50,6 +53,7 @@ StoreConfig
StoreConfigs
ToCompositeFieldPath
ToEnvironmentFieldPath
toFieldPath
TrimPrefix
TrimSuffix
UnhealthyPackageRevision