11---
22title : Compositions
33weight : 30
4- aliases :
4+ aliases :
55 - composition
66 - composition-functions
77 - /knowledge-base/guides/composition-functions
88description : " Compositions are a template for creating Crossplane resources"
99---
1010
1111Compositions are a template for creating multiple managed resources as a single
12- object.
12+ object.
1313
1414A Composition _ composes_ individual managed resources together into a larger,
1515reusable, solution.
1616
1717An example Composition may combine a virtual machine, storage resources and
1818networking policies. A Composition template links all these individual
19- resources together.
19+ resources together.
2020
2121Here's an example Composition. When you create an
2222{{<hover label =" intro " line =" 8 " >}}AcmeBucket{{</hover >}} composite resource
@@ -57,12 +57,12 @@ Crossplane has four core components that users commonly mix up:
5757
5858* Compositions - This page. A template to define how to create resources.
5959* [Composite Resource Definition]({{<ref "./composite-resource-definitions">}})
60- (` XRD`) - A custom API specification.
60+ (` XRD`) - A custom API specification.
6161* [Composite Resource]({{<ref "./composite-resources">}}) (`XR`) - Created by
6262 using the custom API defined in a Composite Resource Definition. XRs use the
63- Composition template to create new managed resources.
63+ Composition template to create new managed resources.
6464* [Claims]({{<ref "./claims" >}}) (`XRC`) - Like a Composite Resource, but
65- with namespace scoping.
65+ with namespace scoping.
6666{{</expand >}}
6767
6868# # Create a Composition
@@ -83,8 +83,8 @@ resource (XR).
8383{{<hint "tip" >}}
8484The Crossplane community has built lots of functions that let you template
8585Crossplane resources using
86- [CUE](https://github.com/crossplane-contrib/function-cue),
87- [KCL](https://github.com/crossplane-contrib/function-kcl),
86+ [CUE](https://github.com/crossplane-contrib/function-cue),
87+ [KCL](https://github.com/crossplane-contrib/function-kcl),
8888Helm-like
8989[Go templates](https://github.com/crossplane-contrib/function-go-templating) or
9090legacy Crossplane
@@ -111,7 +111,7 @@ but the feature is no longer maintained. Crossplane doesn't accept new
111111
112112See the [CLI documentation]({{<ref "../cli/command-reference#beta-convert">}})
113113to learn how to use the `crossplane beta convert` command to convert a legacy
114- ` Resources` Composition to the `Pipeline` mode.
114+ ` Resources` Composition to the `Pipeline` mode.
115115{{< /hint >}}
116116
117117
@@ -134,7 +134,7 @@ kind: Function
134134metadata:
135135 name: function-patch-and-transform
136136spec:
137- package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.1.4
137+ package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2
138138` ` `
139139
140140{{< hint "tip" >}}
@@ -155,7 +155,7 @@ During the install a Function reports `INSTALLED` as `True` and `HEALTHY` as
155155` ` ` shell {copy-lines="1"}
156156kubectl get functions
157157NAME INSTALLED HEALTHY PACKAGE AGE
158- function-patch-and-transform True Unknown xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.1.4 10s
158+ function-patch-and-transform True Unknown xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2 10s
159159` ` `
160160
161161After the Function install completes and it's ready for use the `HEALTHY` status
@@ -174,36 +174,36 @@ composite resource owns.
174174Crossplane knows what Function to call when a composite resource changes by
175175looking at the Composition the composite resource uses.
176176
177- To use composition functions set the Composition
177+ To use composition functions set the Composition
178178{{<hover label="single" line="6">}}mode{{</hover>}} to
179179{{<hover label="single" line="6">}}Pipeline{{</hover>}}.
180180
181- Define a {{<hover label="single" line="7">}}pipeline{{</hover>}} of
182- {{<hover label="single" line="8">}}steps{{</hover>}}. Each
183- {{<hover label="single" line="8">}}step{{</hover>}} calls a Function.
181+ Define a {{<hover label="single" line="7">}}pipeline{{</hover>}} of
182+ {{<hover label="single" line="8">}}steps{{</hover>}}. Each
183+ {{<hover label="single" line="8">}}step{{</hover>}} calls a Function.
184184
185- Each {{<hover label="single" line="8">}}step{{</hover>}} uses a
185+ Each {{<hover label="single" line="8">}}step{{</hover>}} uses a
186186{{<hover label="single" line="9">}}functionRef{{</hover>}} to reference the
187- {{<hover label="single" line="10">}}name{{</hover>}} of the Function to call.
187+ {{<hover label="single" line="10">}}name{{</hover>}} of the Function to call.
188188
189189{{<hint "important" >}}
190- Compositions using {{<hover label="single" line="6">}}mode : Pipeline{{</hover>}}
191- can't specify resource templates with a `resources` field.
190+ Compositions using {{<hover label="single" line="6">}}mode : Pipeline{{</hover>}}
191+ can't specify resource templates with a `resources` field.
192192
193193Use function "Patch and Transform" to create resource templates.
194194{{< /hint >}}
195195
196196
197- Some Functions also allow you to specify an
198- {{<hover label="single" line="11">}}input{{</hover>}}.
197+ Some Functions also allow you to specify an
198+ {{<hover label="single" line="11">}}input{{</hover>}}.
199199The function defines the
200200{{<hover label="single" line="13">}}kind{{</hover>}} of input.
201201
202202This example uses
203203[Function Patch and Transform]({{<ref "../guides/function-patch-and-transform">}}).
204204Function Patch and Transform implements Crossplane resource
205- templates.
206- The input kind is {{<hover label="single" line="13">}}Resources{{</hover>}},
205+ templates.
206+ The input kind is {{<hover label="single" line="13">}}Resources{{</hover>}},
207207and it accepts {{<hover label="single" line="14">}}resources{{</hover>}} as input.
208208
209209` ` ` yaml {label="single",copy-lines="none"}
@@ -239,7 +239,7 @@ calls them all. It calls them in the order they appear in the pipeline.
239239Crossplane passes each Function in the pipeline the result of the previous
240240Function. This enables powerful combinations of Functions. In this example,
241241Crossplane calls {{<hover label="double" line="10">}}function-cue{{</hover>}} to
242- create an S3 bucket. Crossplane then passes the bucket to
242+ create an S3 bucket. Crossplane then passes the bucket to
243243{{<hover label="double" line="23">}}function-auto-ready{{</hover>}}, which marks the
244244composite resource as ready when the bucket becomes ready.
245245
@@ -272,22 +272,22 @@ spec:
272272
273273# ## Enable composite resources
274274
275- A Composition is only a template defining how to create managed
275+ A Composition is only a template defining how to create managed
276276resources. A Composition limits which Composite Resources can use this
277- template.
277+ template.
278278
279- A Composition's {{<hover label="typeref" line="6">}}compositeTypeRef{{</hover>}}
280- defines which Composite Resource type can use this Composition.
279+ A Composition's {{<hover label="typeref" line="6">}}compositeTypeRef{{</hover>}}
280+ defines which Composite Resource type can use this Composition.
281281
282282{{<hint "note" >}}
283- Read more about Composite Resources in the
284- [Composite Resources page]({{<ref "./composite-resources" >}}).
283+ Read more about Composite Resources in the
284+ [Composite Resources page]({{<ref "./composite-resources" >}}).
285285{{< /hint >}}
286286
287- Inside a Composition's
287+ Inside a Composition's
288288{{<hover label="typeref" line="5">}}spec{{</hover>}}
289- define the Composite Resource
290- {{<hover label="typeref" line="7">}}apiVersion{{</hover>}} and
289+ define the Composite Resource
290+ {{<hover label="typeref" line="7">}}apiVersion{{</hover>}} and
291291{{<hover label="typeref" line="8">}}kind{{</hover>}}
292292that the Composition allows to use this template.
293293
@@ -306,26 +306,26 @@ spec:
306306# ## Store connection details
307307
308308Some managed resources generate unique details like usernames, passwords, IP
309- addresses, ports or other connection details.
309+ addresses, ports or other connection details.
310310
311311When resources inside a Composition create connection details Crossplane creates
312312a Kubernetes secret object for each managed resource generating connection
313- details.
313+ details.
314314
315315{{<hint "note">}}
316- This section discusses creating Kubernetes secrets.
316+ This section discusses creating Kubernetes secrets.
317317Crossplane also supports using external secret stores like
318- [HashiCorp Vault](https://www.vaultproject.io/).
318+ [HashiCorp Vault](https://www.vaultproject.io/).
319319
320320Read the [external secrets store guide]({{<ref "../guides/vault-as-secret-store">}}) for more information on using Crossplane
321- with an external secret store.
321+ with an external secret store.
322322{{</hint >}}
323323
324324# ### Composite resource combined secret
325325
326326Crossplane can combine all the secrets generated by the resources inside a
327327Composition into a single Kubernetes secret and optionally copy the secret
328- object for claims.
328+ object for claims.
329329
330330Set the value of `writeConnectionSecretsToNamespace` to the namespace where
331331Crossplane should store the combined secret object.
@@ -344,7 +344,7 @@ spec:
344344
345345Inside the `spec` of each resource producing connection details, define the
346346` writeConnectionSecretToRef` , with a `namespace` and `name` of the secret object
347- for the resource.
347+ for the resource.
348348
349349If a `writeConnectionSecretToRef` isn't defined, Crossplane doesn't write any
350350keys to the secret.
@@ -389,10 +389,10 @@ Remember to create a unique name for each secret.
389389
390390# ### External secret stores
391391
392- Crossplane
393- [External Secret Stores]({{<ref "../guides/vault-as-secret-store" >}})
392+ Crossplane
393+ [External Secret Stores]({{<ref "../guides/vault-as-secret-store" >}})
394394write secrets and connection details to external secret stores like HashiCorp
395- Vault.
395+ Vault.
396396
397397{{<hint "important" >}}
398398External Secret Stores are an alpha feature.
@@ -403,7 +403,7 @@ Stores by default.
403403
404404Use `publishConnectionDetailsWithStoreConfigRef` in place of
405405` writeConnectionSecretsToNamespace` to define the `StoreConfig` to save
406- connection details to.
406+ connection details to.
407407
408408For example, using a `StoreConfig` with the `name` "vault," use
409409` publishConnectionDetailsWithStoreConfigRef.name` matching the
@@ -421,13 +421,13 @@ apiVersion: apiextensions.crossplane.io/v1
421421kind: Composition
422422# Removed for Brevity
423423spec:
424- publishConnectionDetailsWithStoreConfigRef:
424+ publishConnectionDetailsWithStoreConfigRef:
425425 name: vault
426426 # Removed for brevity
427427` ` `
428428
429429For more details read the
430- [External Secret Stores]({{<ref "../guides/vault-as-secret-store" >}})
430+ [External Secret Stores]({{<ref "../guides/vault-as-secret-store" >}})
431431integration guide.
432432
433433# # Test a composition
@@ -451,7 +451,7 @@ Running `crossplane render` requires [Docker](https://www.docker.com).
451451{{< /hint >}}
452452
453453Provide a composite resource, composition and composition functions to render
454- the output locally.
454+ the output locally.
455455
456456` ` ` shell
457457crossplane render xr.yaml composition.yaml functions.yaml
@@ -545,7 +545,7 @@ kind: Function
545545metadata:
546546 name: function-patch-and-transform
547547spec:
548- package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.1.4
548+ package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2
549549` ` `
550550{{</expand>}}
551551
@@ -576,7 +576,7 @@ metadata:
576576 annotations:
577577 render.crossplane.io/runtime: Development
578578spec:
579- package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.1.4
579+ package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2
580580` ` `
581581
582582{{<hint "tip">}}
@@ -616,18 +616,18 @@ xsqlinstances.aws.platformref.upbound.io XSQLInstance aws.platformref.upboun
616616` ` `
617617
618618The `XR-KIND` lists the Composite Resource `kind` that's allowed to use the
619- Composition template.
619+ Composition template.
620620The `XR-APIVERSION` lists the Composite Resource API versions allowed to use the
621- Composition template.
621+ Composition template.
622622
623623{{<hint "note" >}}
624624The output of `kubectl get composition` is different than `kubectl get
625- composite`.
625+ composite`.
626626
627627` kubectl get composition` lists all available Compositions.
628628
629629` kubectl get composite` lists all created Composite Resources and their related
630- Composition.
630+ Composition.
631631{{< /hint >}}
632632
633633# # Composition validation
@@ -657,18 +657,18 @@ If using `mode: Pipeline` (Composition Functions):
657657# ## Composition schema aware validation
658658
659659Crossplane also performs schema aware
660- validation of Compositions. Schema validation checks that `patches`,
661- ` readinessChecks` and `connectionDetails` are valid according to the resource
662- schemas. For example, checking that the source and destination fields of a patch
660+ validation of Compositions. Schema validation checks that `patches`,
661+ ` readinessChecks` and `connectionDetails` are valid according to the resource
662+ schemas. For example, checking that the source and destination fields of a patch
663663are valid according to the source and destination resource schema.
664664
665665{{<hint "note" >}}
666666Composition schema aware validation is a beta feature. Crossplane enables
667- beta features by default.
667+ beta features by default.
668668
669669Disable schema aware validation by setting the
670670` --enable-composition-webhook-schema-validation=false` flag on the Crossplane
671- pod.
671+ pod.
672672
673673The [Crossplane Pods]({{<ref "./pods#edit-the-deployment">}}) page has
674674more information on enabling Crossplane flags.
@@ -698,12 +698,12 @@ The following modes are available:
698698{{< /table >}}
699699
700700Change the validation mode for a Composition with the
701- {{<hover label="mode" line="5">}}crossplane.io/composition-schema-aware-validation-mode{{</hover>}}
701+ {{<hover label="mode" line="5">}}crossplane.io/composition-schema-aware-validation-mode{{</hover>}}
702702annotation.
703703
704704If not specified, the default mode is `warn`.
705705
706- For example, to enable `loose` mode checking set the annotation value to
706+ For example, to enable `loose` mode checking set the annotation value to
707707{{<hover label="mode" line="5">}}loose{{</hover>}}.
708708
709709` ` ` yaml {copy-lines="none",label="mode"}
@@ -827,7 +827,7 @@ Crossplane errors if stability isn't reached after 5 iterations.
827827A _composed_ resource is a resource created by a composite resource. Composed
828828resources are usually Crossplane managed resources (MRs), but they can be any
829829kind of Crossplane resource. For example a composite resource could also create
830- a ProviderConfig, or another kind of composite resource.
830+ a ProviderConfig, or another kind of composite resource.
831831<!-- vale write-good.Weasel = YES -->
832832{{</hint>}}
833833
@@ -986,4 +986,4 @@ context.
986986Crossplane can write context too. If you enable the alpha
987987[composition environment]({{<ref "environment-configs">}}) feature Crossplane
988988writes the environment to the top-level context field
989- ` apiextensions.crossplane.io/environment` .
989+ ` apiextensions.crossplane.io/environment` .
0 commit comments