diff --git a/content/master/concepts/compositions.md b/content/master/concepts/compositions.md index 15a11ee7..8aa8c7e3 100644 --- a/content/master/concepts/compositions.md +++ b/content/master/concepts/compositions.md @@ -41,8 +41,8 @@ Optionally, Compositions also support: * [Modifying and patching](#changing-resource-fields) resource settings. * [Storing connection details](#storing-connection-details) and secrets generated by the managed resources. -* Using [Composition functions](#composition-functions) to allow custom - programs to run alongside the Composition. +* Using [Composition Functions](#use-composition-functions) to template + resources using custom programs. * Creating a [custom check of when a resource is ready](#resource-readiness-checks) to use. @@ -664,40 +664,59 @@ spec: The [EnvironmentConfigs]({{}}) page has more information on EnvironmentConfigs options and usage. -### Composition functions +### Use Composition Functions -Composition functions (`XFNs`) are containers executing any code you define. -Composition functions can read and write to any resource in the Composition -they're attached to. This allows composition functions to perform complex -operations to patch fields, determine if a resource is ready for use or notify -an external system about the details of resource. +Composition functions (or just Functions, for short) are custom programs that +template Crossplane resources. 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. {{}} -Composition functions are an alpha feature. Alpha features aren't enabled by -default. +Composition functions are a beta feature. {{< /hint >}} -To attach a composition function to a Composition define a -{{}}function{{}} inside the Composition -{{}}spec{{}}. +To use composition functions define a {{}}pipeline{{}} of steps inside the Composition {{}}spec{{}}. Each {{}}step{{}} calls a Function. You can't specify resource +templates using the `resources` field when you specify a pipeline of Functions. +You must set the Composition {{}}mode{{}} to +`Pipeline` to use Functions. -Provide a {{}}name{{}} for the function. -The {{}}type{{}} is always `Container`. -The {{}}container.image{{}} is the -location of the composition function container image. +Each {{}}step{{}} must specify the {{}}name{{}} of the Function to call. Some Functions +also allow you to specify an {{}}input{{}}. +Different Functions each have a different {{}}kind{{}} of input. + +This example uses Function Patch and Transform. Function Patch and Transform is +a Function that implements Crossplane resource templates. You can use Function +Patch and Transform to specify resource templates in a pipeline with other +Functions. ```yaml {label="xfn",copy-lines="none"} apiVersion: apiextensions.crossplane.io/v1 kind: Composition # Removed for Brevity spec: - resources: # Removed for Brevity - functions: - - name: rds-instance-password - type: Container - container: - image: xpkg.upbound.io/provider-aws-xfns/random-rds-password:v0.1.0 + 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" ``` Read the [composition functions]({{}}) page for @@ -1293,6 +1312,9 @@ Composition. When creating a Composition Crossplane automatically validates specific parameters in the Composition. +If using `mode: Resources`: + +* The `resources` field isn't empty. * All resources either use a `name` or don't. Compositions can't use both named and unnamed resources. * No duplicate resource names. @@ -1303,10 +1325,11 @@ parameters in the Composition. * Readiness checks using `matchString` aren't empty. * Readiness checks using `matchInteger` isn't `0`. * Readiness checks requiring a `fieldPath` value provide it. -* If using composition functions, all resources must have names. -* Composition function container field isn't empty. -* Composition function `type` is `container`. -* Composition function names are unique. + +If using `mode: Pipeline` (Composition Functions): + +* The `pipeline` field isn't empty. +* No duplicate step names. ### Resource schema validation