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

Address all warnings in content/master 

I tried to address them everywhere but there are literally thousands.

Signed-off-by: Nic Cope <nicc@rk0n.org>
This commit is contained in:
Nic Cope 2025-08-05 21:34:04 -07:00
parent 331c389ce9
commit 580593faea
27 changed files with 356 additions and 217 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
content/master/cli/_index.md
View File

@ -41,7 +41,7 @@ https://releases.crossplane.io/stable/current/bin
{{<hint "important" >}} {{<hint "important" >}}
<!-- vale write-good.Passive = NO --> <!-- vale write-good.Passive = NO -->
The CLI is named `crank` in the release repository. Download this file. The release repository names the CLI `crank`. Download this file.
<!-- vale write-good.Passive = YES --> <!-- vale write-good.Passive = YES -->
The `crossplane` binary is the Kubernetes Crossplane pod image. The `crossplane` binary is the Kubernetes Crossplane pod image.

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

@ -24,7 +24,11 @@ The following flags are available for all commands.
{{< /table >}} {{< /table >}}
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.Headings = NO -->
## version ## version
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.Headings = YES -->
The `crossplane version` command returns the version of Crossplane CLI The `crossplane version` command returns the version of Crossplane CLI
and the control plane. and the control plane.
@ -35,7 +39,9 @@ Client Version: v1.17.0
Server Version: v1.17.0 Server Version: v1.17.0
``` ```
<!-- vale Google.Headings = NO -->
## render ## render
<!-- vale Google.Headings = YES -->
The `crossplane render` command previews the output of a The `crossplane render` command previews the output of a
[composite resource]({{<ref "../composition/composite-resources">}}) after applying [composite resource]({{<ref "../composition/composite-resources">}}) after applying
@ -167,7 +173,7 @@ spec:
The schema of the resource isn't validated and may contain any data. The schema of the resource isn't validated and may contain any data.
### Mock Extra Resources ### Mock extra resources
Extra Resources allow a Composition to request Crossplane Objects on the cluster that aren't Extra Resources allow a Composition to request Crossplane Objects on the cluster that aren't
part of the Composition. The `--extra-resources` option points at a directory containing part of the Composition. The `--extra-resources` option points at a directory containing
@ -175,13 +181,17 @@ YAML manifests of resources to mock. Use Extra Resources in combination with a f
[function-extra-resources](https://github.com/crossplane-contrib/function-extra-resources) or the [function-extra-resources](https://github.com/crossplane-contrib/function-extra-resources) or the
built-in support in [function-go-templating](https://github.com/crossplane-contrib/function-go-templating?tab=readme-ov-file#extraresources). built-in support in [function-go-templating](https://github.com/crossplane-contrib/function-go-templating?tab=readme-ov-file#extraresources).
<!-- vale Google.Headings = NO -->
## xpkg ## xpkg
<!-- vale Google.Headings = YES -->
The `crossplane xpkg` commands create, install and update Crossplane The `crossplane xpkg` commands create, install and update Crossplane
[packages]({{<ref "../packages/configurations">}}) as well as enable authentication [packages]({{<ref "../packages/configurations">}}) and enable authentication
and publishing of Crossplane packages to a Crossplane package registry. and publishing of Crossplane packages to a Crossplane package registry.
<!-- vale Google.Headings = NO -->
### xpkg build ### xpkg build
<!-- vale Google.Headings = YES -->
Using `crossplane xpkg build` provides automation and simplification to build Using `crossplane xpkg build` provides automation and simplification to build
Crossplane packages. Crossplane packages.
@ -243,7 +253,7 @@ Include YAML files demonstrating how to use the package with `--examples-root`.
#### Include a runtime image #### Include a runtime image
Functions and Providers require YAML files describing their dependencies and Functions and Providers require YAML files describing their dependencies and
settings as well as a container image for their runtime. settings and a container image for their runtime.
Using `--embed-runtime-image-name` runs a specified image and Using `--embed-runtime-image-name` runs a specified image and
includes the image inside the function or provider package. includes the image inside the function or provider package.
@ -258,7 +268,9 @@ Use `docker pull` to download a missing image.
The `--embed-runtime-image-tarball` flag includes a local OCI image tarball The `--embed-runtime-image-tarball` flag includes a local OCI image tarball
inside the function or provider package. inside the function or provider package.
<!-- vale Google.Headings = NO -->
### xpkg init ### xpkg init
<!-- vale Google.Headings = YES -->
The `crossplane xpkg init` command populates the current directory with The `crossplane xpkg init` command populates the current directory with
files to build a package. files to build a package.
@ -279,14 +291,18 @@ The `<template>` value may be one of four well known templates:
Instead of a well known template the `<template>` value can be a git repository Instead of a well known template the `<template>` value can be a git repository
URL. URL.
<!-- vale Google.Headings = NO -->
#### NOTES.txt #### NOTES.txt
<!-- vale Google.Headings = YES -->
If the template repository contains a `NOTES.txt` file in its root directory, 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 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 terminal after populating the directory with the template files. This can be
useful for providing information about the template. useful for providing information about the template.
<!-- vale Google.Headings = NO -->
#### init.sh #### init.sh
<!-- vale Google.Headings = YES -->
If the template repository contains an `init.sh` file in its root directory, the If the template repository contains an `init.sh` file in its root directory, the
`crossplane xpkg init` command starts a dialog after populating the `crossplane xpkg init` command starts a dialog after populating the
@ -305,7 +321,9 @@ personalize the template.
{{< /table >}} {{< /table >}}
<!-- vale Google.Headings = NO -->
### xpkg install ### xpkg install
<!-- vale Google.Headings = YES -->
Download and install packages into Crossplane with `crossplane xpkg install`. Download and install packages into Crossplane with `crossplane xpkg install`.
@ -375,7 +393,9 @@ Read more about
[package revisions]({{< ref "../packages/configurations#configuration-revisions" >}}) [package revisions]({{< ref "../packages/configurations#configuration-revisions" >}})
in the package documentation. in the package documentation.
<!-- vale Google.Headings = NO -->
### xpkg login ### xpkg login
<!-- vale Google.Headings = YES -->
Use `xpkg login` to authenticate to registries that host Crossplane packages. Use `xpkg login` to authenticate to registries that host Crossplane packages.
@ -430,7 +450,9 @@ Authenticate to a registered organization in the Upbound Marketplace with the
For example, For example,
`crossplane xpkg login --account=Upbound --username=my-user --password -`. `crossplane xpkg login --account=Upbound --username=my-user --password -`.
<!-- vale Google.Headings = NO -->
### xpkg logout ### xpkg logout
<!-- vale Google.Headings = YES -->
Use `crossplane xpkg logout` to invalidate the current `crossplane xpkg login` Use `crossplane xpkg logout` to invalidate the current `crossplane xpkg login`
session. session.
@ -440,7 +462,9 @@ Using `crossplane xpkg logout` removes the `session` from the
`~/.crossplane/config.json` file, but doesn't delete the configuration file. `~/.crossplane/config.json` file, but doesn't delete the configuration file.
{{< /hint >}} {{< /hint >}}
<!-- vale Google.Headings = NO -->
### xpkg push ### xpkg push
<!-- vale Google.Headings = YES -->
Push a Crossplane package file to a package registry. Push a Crossplane package file to a package registry.
@ -478,7 +502,9 @@ DockerHub organization `crossplane-docs/my-package:v0.14.0` use:
| `-f` | `--package-files=PATH` | A comma-separated list of xpkg files to push. | | `-f` | `--package-files=PATH` | A comma-separated list of xpkg files to push. |
{{< /table >}} {{< /table >}}
<!-- vale Google.Headings = NO -->
### xpkg update ### xpkg update
<!-- vale Google.Headings = YES -->
The `crossplane xpkg update` command downloads and updates an existing package. The `crossplane xpkg update` command downloads and updates an existing package.
@ -499,7 +525,9 @@ For example, to update to the latest version of the
`crossplane xpkg update provider xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1` `crossplane xpkg update provider xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1`
<!-- vale Google.Headings = NO -->
## beta ## beta
<!-- vale Google.Headings = YES -->
Crossplane `beta` commands are experimental. These commands may change the Crossplane `beta` commands are experimental. These commands may change the
flags, options or outputs in future releases. flags, options or outputs in future releases.
@ -508,7 +536,9 @@ Crossplane maintainers may promote or remove commands under `beta` in future
releases. releases.
<!-- vale Google.Headings = NO -->
### beta convert ### beta convert
<!-- vale Google.Headings = YES -->
As Crossplane evolves, its APIs and resources may change. To help with the As Crossplane evolves, its APIs and resources may change. To help with the
migration to the new APIs and resources, the `crossplane beta convert` command migration to the new APIs and resources, the `crossplane beta convert` command
@ -547,7 +577,9 @@ By default the function name is "function-patch-and-transform."
{{< /table >}} {{< /table >}}
<!-- vale Google.Headings = NO -->
### beta top ### beta top
<!-- vale Google.Headings = YES -->
The command `crossplane beta top` shows CPU and memory usage of Crossplane The command `crossplane beta top` shows CPU and memory usage of Crossplane
related pods. related pods.
@ -591,7 +623,9 @@ running the `top` command may produce an error, for example,
`crossplane: error: error adding metrics to pod, check if metrics-server is running or wait until metrics are available for the pod: the server is currently unable to handle the request (get pods.metrics.k8s.io crossplane-contrib-provider-helm-b4cc4c2c8db3-6d787f9686-qzmz2)` `crossplane: error: error adding metrics to pod, check if metrics-server is running or wait until metrics are available for the pod: the server is currently unable to handle the request (get pods.metrics.k8s.io crossplane-contrib-provider-helm-b4cc4c2c8db3-6d787f9686-qzmz2)`
<!-- vale Google.Headings = NO -->
### beta trace ### beta trace
<!-- vale Google.Headings = YES -->
Use the `crossplane beta trace` command to display a visual relationship of Use the `crossplane beta trace` command to display a visual relationship of
Crossplane objects. The `trace` command supports XRs, compositions, Crossplane objects. The `trace` command supports XRs, compositions,
@ -826,7 +860,9 @@ Configuration/platform-ref-aws v0.9.0 True
# Removed for brevity # Removed for brevity
``` ```
<!-- vale Google.Headings = NO -->
### beta validate ### beta validate
<!-- vale Google.Headings = YES -->
The `crossplane beta validate` command validates The `crossplane beta validate` command validates
[compositions]({{<ref "../composition/compositions">}}) against provider or XRD [compositions]({{<ref "../composition/compositions">}}) against provider or XRD
@ -953,7 +989,9 @@ crossplane render xr.yaml composition.yaml function.yaml --include-full-xr | cro
Total 5 resources: 0 missing schemas, 4 success cases, 1 failure cases Total 5 resources: 0 missing schemas, 4 success cases, 1 failure cases
``` ```
<!-- vale Google.Headings = NO -->
#### Validate Common Expression Language rules #### Validate Common Expression Language rules
<!-- vale Google.Headings = YES -->
XRDs can define [validation rules](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#validation-rules) expressed in the Common Expression Language XRDs can define [validation rules](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#validation-rules) expressed in the Common Expression Language
([CEL](https://kubernetes.io/docs/reference/using-api/cel/)). ([CEL](https://kubernetes.io/docs/reference/using-api/cel/)).

24
content/master/composition/composite-resource-definitions.md
View File

@ -30,7 +30,11 @@ Crossplane XRDs are like
XRDs require fewer fields and add options related to Crossplane, like connection XRDs require fewer fields and add options related to Crossplane, like connection
secrets. secrets.
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.Headings = NO -->
## Creating a CompositeResourceDefinition ## Creating a CompositeResourceDefinition
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.Headings = YES -->
Creating a CompositeResourceDefinition consists of: Creating a CompositeResourceDefinition consists of:
* [Defining a custom API group](#xrd-groups). * [Defining a custom API group](#xrd-groups).
@ -88,7 +92,11 @@ recreate the XRD to change the
{{<hover label="xrd1" line="7">}}names{{</hover>}}. {{<hover label="xrd1" line="7">}}names{{</hover>}}.
{{</hint >}} {{</hint >}}
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.Headings = NO -->
### XRD groups ### XRD groups
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.Headings = YES -->
Groups define a collection of related API endpoints. The `group` can be any Groups define a collection of related API endpoints. The `group` can be any
value, but common convention is to map to a fully qualified domain name. value, but common convention is to map to a fully qualified domain name.
@ -98,7 +106,11 @@ Many XRDs may use the same `group` to create a logical collection of APIs.
<!-- vale write-good.Weasel = YES --> <!-- vale write-good.Weasel = YES -->
For example a `database` group may have a `relational` and `nosql` kinds. For example a `database` group may have a `relational` and `nosql` kinds.
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.Headings = NO -->
### XRD names ### XRD names
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.Headings = YES -->
The `names` field defines how to refer to this specific XRD. The `names` field defines how to refer to this specific XRD.
The required name fields are: The required name fields are:
@ -137,7 +149,11 @@ spec:
``` ```
{{</hint >}} {{</hint >}}
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.Headings = NO -->
### XRD versions ### XRD versions
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.Headings = YES -->
<!-- vale gitlab.SentenceLength = NO --> <!-- vale gitlab.SentenceLength = NO -->
The XRD `version` is like the The XRD `version` is like the
@ -567,7 +583,11 @@ spec:
# Removed for brevity # Removed for brevity
``` ```
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.Headings = NO -->
## Verify a CompositeResourceDefinition ## Verify a CompositeResourceDefinition
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.Headings = YES -->
Verify an XRD with `kubectl get compositeresourcedefinition` or the short form, Verify an XRD with `kubectl get compositeresourcedefinition` or the short form,
{{<hover label="getxrd" line="1">}}kubectl get xrd{{</hover>}}. {{<hover label="getxrd" line="1">}}kubectl get xrd{{</hover>}}.
@ -581,7 +601,11 @@ xdatabases.custom-api.example.org True True 22m
The `ESTABLISHED` field indicates Crossplane installed the Kubernetes custom The `ESTABLISHED` field indicates Crossplane installed the Kubernetes custom
resource definition for this XRD. resource definition for this XRD.
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.Headings = NO -->
### XRD conditions ### XRD conditions
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.Headings = YES -->
Crossplane uses a standard set of `Conditions` for XRDs. Crossplane uses a standard set of `Conditions` for XRDs.
View the conditions of a XRD under their `Status` with View the conditions of a XRD under their `Status` with
`kubectl describe xrd`. `kubectl describe xrd`.

8
content/master/composition/composite-resources.md
View File

@ -319,15 +319,17 @@ Spec:
### Composite resource conditions ### Composite resource conditions
<!-- vale Google.Colons = NO -->
A composite resource has two status conditions: Synced and Ready. A composite resource has two status conditions: Synced and Ready.
<!-- vale Google.Colons = YES -->
Crossplane sets the Synced status condition to True when it's able to Crossplane sets the Synced status condition to True when it's able to
successfully reconcile the composite resource. If Crossplane can't reconcile the successfully reconcile the composite resource. If Crossplane can't reconcile the
composite resource it'll report an error in the Synced condition. composite resource it reports an error in the Synced condition.
Crossplane sets the Ready status condition to True when the composite resource's Crossplane sets the Ready status condition to True when the composite resource's
composition function pipeline reports that all of its composed resources are composition function pipeline reports that all its composed resources are
ready. If a composed resource isn't ready Crossplane will report it in the ready. If a composed resource isn't ready Crossplane reports it in the
Ready condition. Ready condition.
## Composite resource labels ## Composite resource labels

65
content/master/composition/composition-revisions.md
View File

@ -3,33 +3,33 @@ title: Composition Revisions
weight: 35 weight: 35
--- ---
This guide discusses the use of "Composition Revisions" to safely make and roll This guide discusses the use of "Composition Revisions" to make and roll
back changes to a Crossplane [`Composition`][composition type]. It assumes back changes to a Crossplane [`Composition`][composition type]. It assumes
familiarity with Crossplane, and particularly with familiarity with Crossplane and
[Compositions]. [Compositions].
A `Composition` configures how Crossplane should reconcile a Composite Resource A `Composition` configures how Crossplane should reconcile a Composite Resource
(XR). Put otherwise, when you create an XR the selected `Composition` determines (XR). Put otherwise, when you create an XR the selected `Composition` determines
what resources Crossplane will create in response. Let's say for example that what resources Crossplane creates in response. For example,
you define a `PlatformDB` XR, which represents your organisation's common you define a `PlatformDB` XR, which represents your organisation's common
database configuration of an Azure MySQL Server and a few firewall rules. The database configuration of an Azure MySQL Server and some firewall rules. The
`Composition` contains the 'base' configuration for the MySQL server and the `Composition` contains the 'base' configuration for the MySQL server and the
firewall rules that are extended by the configuration for the `PlatformDB`. firewall rules that the `PlatformDB` configuration extends.
A `Composition` is associated with multiple XRs that make use of it. You might A `Composition` associates with multiple XRs that use it. You might
define a `Composition` named `big-platform-db` that's used by ten different define a `Composition` named `big-platform-db` that's used by ten different
`PlatformDB` XRs. Usually, in the interest of self-service, the `Composition` `PlatformDB` XRs. Often, in the interest of self-service, a different team manages the `Composition`
is managed by a different team from the actual `PlatformDB` XRs. For example than the actual `PlatformDB` XRs. For example
the `Composition` may be written and maintained by a platform team member, a platform team member may write and maintain the `Composition`,
while individual application teams create `PlatformDB` XRs that use said while individual app teams create `PlatformDB` XRs that use said
`Composition`. `Composition`.
Each `Composition` is mutable - you can update it as your organisation's needs Each `Composition` is mutable - you can update it as your organisation's needs
change. However, updating a `Composition` without Composition Revisions can be a change. Updating a `Composition` without Composition Revisions can be a
risky process. Crossplane constantly uses the `Composition` to ensure that your risky process. Crossplane constantly uses the `Composition` to ensure that your
actual infrastructure - your MySQL Servers and firewall rules - match your actual infrastructure - your MySQL Servers and firewall rules - match your
desired state. If you have 10 `PlatformDB` XRs all using the `big-platform-db` desired state. If you have 10 `PlatformDB` XRs all using the `big-platform-db`
`Composition`, all 10 of those XRs will be instantly updated in accordance with `Composition`, all 10 of those XRs are instantly updated following
any updates you make to the `big-platform-db` `Composition`. any updates you make to the `big-platform-db` `Composition`.
Composition Revisions allow XRs to opt out of automatic updates. Instead you can Composition Revisions allow XRs to opt out of automatic updates. Instead you can
@ -37,19 +37,19 @@ update your XRs to use the latest `Composition` settings at your own pace.
This enables you to [canary] changes to your infrastructure, or to roll back This enables you to [canary] changes to your infrastructure, or to roll back
some XRs to previous `Composition` settings without rolling back all XRs. some XRs to previous `Composition` settings without rolling back all XRs.
## Using Composition Revisions ## Using composition revisions
When Composition Revisions are enabled three things happen: When you enable Composition Revisions three things happen:
1. Crossplane creates a `CompositionRevision` for each `Composition` update. 1. Crossplane creates a `CompositionRevision` for each `Composition` update.
1. Composite Resources gain a `spec.crossplane.compositionRevisionRef` field that specifies 1. Composite Resources gain a `spec.crossplane.compositionRevisionRef` field that specifies
which `CompositionRevision` they use. which `CompositionRevision` they use.
1. Composite Resources gain a `spec.crossplane.compositionUpdatePolicy` field that 1. Composite Resources gain a `spec.crossplane.compositionUpdatePolicy` field that
specifies how they should be updated to new Composition Revisions. specifies how Crossplane should update them to new Composition Revisions.
Each time you edit a `Composition` Crossplane will automatically create a Each time you edit a `Composition` Crossplane automatically creates a
`CompositionRevision` that represents that 'revision' of the `Composition` - `CompositionRevision` that represents that 'revision' of the `Composition` -
that unique state. Each revision is allocated an increasing revision number. that unique state. Crossplane allocates each revision an increasing revision number.
This gives `CompositionRevision` consumers an idea about which revision is This gives `CompositionRevision` consumers an idea about which revision is
'newest'. 'newest'.
@ -71,19 +71,18 @@ example-xjrdmzz 3 61s
> A `Composition` is a mutable resource that you can update as your needs > A `Composition` is a mutable resource that you can update as your needs
> change over time. Each `CompositionRevision` is an immutable snapshot of those > change over time. Each `CompositionRevision` is an immutable snapshot of those
> needs at a particular point in time. > needs at a particular time.
Crossplane behaves the same way by default whether Composition Revisions are Crossplane behaves the same way by default whether you enable Composition Revisions or not. When you enable Composition Revisions all XRs
enabled or not. This is because when you enable Composition Revisions all XRs
default to the `Automatic` `compositionUpdatePolicy`. XRs support two update default to the `Automatic` `compositionUpdatePolicy`. XRs support two update
policies: policies:
* `Automatic`: Automatically use the latest `CompositionRevision`. (Default) * `Automatic`: Automatically use the latest `CompositionRevision`. (Default)
* `Manual`: Require manual intervention to change `CompositionRevision`. * `Manual`: Require manual intervention to change `CompositionRevision`.
The below XR uses the `Manual` policy. When this policy is used the XR will The below XR uses the `Manual` policy. When you use this policy the XR
select the latest `CompositionRevision` when it's first created, but must selects the latest `CompositionRevision` when it's first created, but must
manually be updated when you wish it to use another `CompositionRevision`. manually update it when you wish it to use another `CompositionRevision`.
```yaml ```yaml
apiVersion: example.org/v1alpha1 apiVersion: example.org/v1alpha1
@ -125,12 +124,12 @@ spec:
This tutorial discusses how CompositionRevisions work and how they manage Composite Resource This tutorial discusses how CompositionRevisions work and how they manage Composite Resource
(XR) updates. This starts with a `Composition` and `CompositeResourceDefinition` (XRD) that defines a `MyVPC` (XR) updates. This starts with a `Composition` and `CompositeResourceDefinition` (XRD) that defines a `MyVPC`
resource and continues with creating multiple XRs to observe different upgrade paths. Crossplane will resource and continues with creating multiple XRs to observe different upgrade paths. Crossplane
assign different CompositionRevisions to the created composite resources each time the composition is updated. assigns different CompositionRevisions to composite resources each time you update the composition.
### Preparation ### Preparation
#### Deploy Composition and XRD Examples #### Deploy composition and XRD examples
Apply the example Composition. Apply the example Composition.
```yaml ```yaml
@ -209,9 +208,9 @@ The label `dev` is automatically created from the Composition.
{{< /hint >}} {{< /hint >}}
### Create Composite Resources ### Create composite resources
This tutorial has four composite resources to cover different update policies and composition selection options. This tutorial has four composite resources to cover different update policies and composition selection options.
The default behavior is updating XRs to the latest revision of the Composition. However, this can be changed by setting The default behavior is updating XRs to the latest revision of the Composition. You can change this by setting
`compositionUpdatePolicy: Manual` in the XR. It's also possible to select the latest revision with a specific label `compositionUpdatePolicy: Manual` in the XR. It's also possible to select the latest revision with a specific label
with `compositionRevisionSelector.matchLabels` together with `compositionUpdatePolicy: Automatic`. with `compositionRevisionSelector.matchLabels` together with `compositionUpdatePolicy: Automatic`.
@ -310,11 +309,11 @@ vpc-staging False <none> Automatic map[c
The `vpc-staging` XR label doesn't match any existing Composition Revisions. The `vpc-staging` XR label doesn't match any existing Composition Revisions.
{{< /hint >}} {{< /hint >}}
### Create new Composition revisions ### Create new composition revisions
Crossplane creates a new CompositionRevision when a Composition is created or updated. Label and annotation changes will Crossplane creates a new CompositionRevision when you create or update a Composition. Label and annotation changes
also trigger a new CompositionRevision. also trigger a new CompositionRevision.
#### Update the Composition label #### Update the composition label
Update the `Composition` label to `channel: staging`: Update the `Composition` label to `channel: staging`:
```shell ```shell
kubectl label composition myvpcs.aws.example.upbound.io channel=staging --overwrite kubectl label composition myvpcs.aws.example.upbound.io channel=staging --overwrite
@ -355,7 +354,7 @@ vpc-staging True myvpcs.aws.example.upbound.io-727b3c8 Automatic map[c
`vpc-staging` now matches the label applied to Revision `revision:2`. `vpc-staging` now matches the label applied to Revision `revision:2`.
{{< /hint >}} {{< /hint >}}
#### Update Composition Spec and Label #### Update composition spec and label
Update the Composition to disable DNS support in the VPC and change the label from `staging` back to `dev`. Update the Composition to disable DNS support in the VPC and change the label from `staging` back to `dev`.
Apply the following changes to update the `Composition` spec and label: Apply the following changes to update the `Composition` spec and label:
@ -414,7 +413,7 @@ Changing the label and the spec values simultaneously is critical for deploying
{{< /hint >}} {{< /hint >}}
Verify Crossplane assigns the Composite Resources `vpc-auto` and `vpc-dev` to Composite `revision:3`. Verify Crossplane assigns the Composite Resources `vpc-auto` and `vpc-dev` to Composite `revision:3`.
`vpc-staging` is assigned to `revision:2`, and `vpc-man` is still assigned to the original `revision:1`: Crossplane assigns `vpc-staging` to `revision:2`, and still assigns `vpc-man` to the original `revision:1`:
```shell ```shell
kubectl get composite -o="custom-columns=NAME:.metadata.name,SYNCED:.status.conditions[0].status,REVISION:.spec.crossplane.compositionRevisionRef.name,POLICY:.spec.crossplane.compositionUpdatePolicy,MATCHLABEL:.spec.crossplane.compositionRevisionSelector.matchLabels" kubectl get composite -o="custom-columns=NAME:.metadata.name,SYNCED:.status.conditions[0].status,REVISION:.spec.crossplane.compositionRevisionRef.name,POLICY:.spec.crossplane.compositionUpdatePolicy,MATCHLABEL:.spec.crossplane.compositionRevisionSelector.matchLabels"

4
content/master/composition/compositions.md
View File

@ -62,7 +62,7 @@ You use two Crossplane types to create a new custom API:
* A Composition - This page. Configures how the XR creates other resources. * A Composition - This page. Configures how the XR creates other resources.
{{</expand >}} {{</expand >}}
## Create a Composition ## Create a composition
Creating a Composition consists of: Creating a Composition consists of:
* [Using composition functions](#use-a-function-in-a-composition) to define the * [Using composition functions](#use-a-function-in-a-composition) to define the
@ -492,7 +492,7 @@ the container, and `Orphan`, to leave it running.
running at the specified target. It uses running at the specified target. It uses
[gRPC target syntax](https://github.com/grpc/grpc/blob/v1.59.1/doc/naming.md). [gRPC target syntax](https://github.com/grpc/grpc/blob/v1.59.1/doc/naming.md).
## Verify a Composition ## Verify a composition
View all available Compositions with `kubectl get composition`. View all available Compositions with `kubectl get composition`.

33
content/master/composition/environment-configs.md
View File

@ -34,8 +34,10 @@ environment.
{{< /hint >}} {{< /hint >}}
<!-- vale Google.Headings = NO --> <!-- vale Google.Headings = NO -->
<!-- vale Microsoft.Headings = NO -->
## Create an EnvironmentConfig ## Create an EnvironmentConfig
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
<!-- vale Microsoft.Headings = YES -->
An {{<hover label="env1" line="2">}}EnvironmentConfig{{</hover>}} has a single An {{<hover label="env1" line="2">}}EnvironmentConfig{{</hover>}} has a single
object field, object field,
@ -63,27 +65,30 @@ data:
- item2 - item2
``` ```
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.Headings = NO -->
## Access EnvironmentConfigs ## Access EnvironmentConfigs
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.Headings = YES -->
`EnvironmentConfigs` can be accessed by [Composition Functions] supporting [Composition Functions] supporting
[extra-resources], for example [function-environment-configs] or [extra-resources], for example [function-environment-configs] or
[function-go-templating]. [function-go-templating].
## Migration from Alpha Composition Environment ## Migration from alpha composition environment
Crossplane (`<=v1.17`) natively supported selecting `EnvironmentConfigs`, Crossplane (`<=v1.17`) natively supported selecting `EnvironmentConfigs`,
merging them into an `in-memory environment` and patching between that, merging them into an `in-memory environment` and patching between that,
composed and composite resources. From `v1.18`, this native capability has been composed and composite resources. From `v1.18`, Crossplane removed this native capability, in favor of [Composition Functions].
removed, in favor of [Composition Functions].
Users that enabled Alpha Composition Environments Users that enabled Alpha Composition Environments
(`--enable-environment-configs`) and leveraged the native functionality (`--enable-environment-configs`) and leveraged the native features
(`spec.environment.patches`, `spec.environment.environmentConfigs` and (`spec.environment.patches`, `spec.environment.environmentConfigs` and
`*Environment` patches), will have to migrate to Composition Functions to `*Environment` patches), have to migrate to Composition Functions to
continue doing so. continue doing so.
Automated migration to `Pipeline` mode is available through `crossplane beta Automated migration to `Pipeline` mode is available through `crossplane beta
convert pipeline-composition`, which will move a composition using `Resource` convert pipeline-composition`, which moves a composition using `Resource`
mode, to [function-patch-and-transform] and, if needed, mode, to [function-patch-and-transform] and, if needed,
[function-environment-configs]. [function-environment-configs].
@ -96,8 +101,8 @@ migration.
Select the EnvironmentConfigs to use through [function-environment-configs]'s `Input`. Select the EnvironmentConfigs to use through [function-environment-configs]'s `Input`.
The `environmentConfigs` field is a list of `EnvironmentConfigs` we want The `environmentConfigs` field is a list of `EnvironmentConfigs` to
retrieved, merged and passed to the next step in the pipeline through the retrieve, merge and pass to the next step in the pipeline through the
[Context] at a well known key, `apiextensions.crossplane.io/environment`. [Context] at a well known key, `apiextensions.crossplane.io/environment`.
Select an environment by `Reference` or by `Selector`: Select an environment by `Reference` or by `Selector`:
@ -217,7 +222,7 @@ only uses the first environment in the sorted list.
Set the `selector.mode` to `Multiple` to return all matched EnvironmentConfigs. Set the `selector.mode` to `Multiple` to return all matched EnvironmentConfigs.
Use `mode: Single` to return a single environment, and error out if more than Use `mode: Single` to return a single environment, and error out if more than
one match is found. Crossplane finds one match.
Sorting and the selection mode only applies to a single `Selector`. Sorting and the selection mode only applies to a single `Selector`.
@ -347,7 +352,7 @@ the `key` first using a `Value` selector, then define the `Optional`
For example, the Composition below defines `value: my-default-value` for the key For example, the Composition below defines `value: my-default-value` for the key
`my-second-label-key`. If the Composite resource defines `my-second-label-key`. If the Composite resource defines
`spec.parameters.deploy`, [function-environment-configs] will use that instead. `spec.parameters.deploy`, [function-environment-configs] uses that instead.
```yaml {label="byLabelOptionalDefault",copy-lines="all"} ```yaml {label="byLabelOptionalDefault",copy-lines="all"}
apiVersion: apiextensions.crossplane.io/v1 apiVersion: apiextensions.crossplane.io/v1
@ -391,12 +396,12 @@ value.
## Patching with EnvironmentConfigs using function-patch-and-transform ## Patching with EnvironmentConfigs using function-patch-and-transform
`EnvironmentConfigs` selected as explained above, are then merged in an `EnvironmentConfigs` selected as explained earlier, are then merged in an
`in-memory environment` by [function-environment-configs] and passed to the `in-memory environment` by [function-environment-configs] and passed to the
next function in the pipeline at a well known key, next function in the pipeline at a well known key,
`apiextensions.crossplane.io/environment`. `apiextensions.crossplane.io/environment`.
[function-patch-and-transform] can be used to read or write data between the in-memory environment and You can use [function-patch-and-transform] to read or write data between the in-memory environment and
composite resource or individual composed resources. composite resource or individual composed resources.
{{<hint "tip" >}} {{<hint "tip" >}}
@ -442,7 +447,7 @@ spec:
Individual resources can use any data written to the in-memory environment. Individual resources can use any data written to the in-memory environment.
`CombineFromComposite` and `CombineToComposite` can be used to combine multiple You can use `CombineFromComposite` and `CombineToComposite` to combine multiple
values and write the result either to the in-memory environment or the values and write the result either to the in-memory environment or the
Composite resource, respectively. Composite resource, respectively.

2
content/master/get-started/get-started-with-managed-resources.md
View File

@ -139,7 +139,7 @@ kubectl create secret generic aws-secret \
{{<hint "important">}} {{<hint "important">}}
Crossplane providers don't have to store their credentials in a secret. They Crossplane providers don't have to store their credentials in a secret. They
can load their credentials from various sources. can load their credentials from multiple sources.
{{</hint>}} {{</hint>}}
Next, [configure the provider](#configure-the-provider) to use the credentials. Next, [configure the provider](#configure-the-provider) to use the credentials.

16
content/master/get-started/install.md
View File

@ -17,12 +17,20 @@ If you don't have a Kubernetes cluster create one locally with [Kind](https://ki
* An actively [supported Kubernetes version](https://kubernetes.io/releases/patch-releases/#support-period) * An actively [supported Kubernetes version](https://kubernetes.io/releases/patch-releases/#support-period)
* [Helm](https://helm.sh/docs/intro/install/) version `v3.2.0` or later * [Helm](https://helm.sh/docs/intro/install/) version `v3.2.0` or later
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.Headings = NO -->
## Install Crossplane ## Install Crossplane
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.Headings = YES -->
Install Crossplane using the _Helm chart_. Install Crossplane using the _Helm chart_.
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.Headings = NO -->
### Add the Crossplane Preview Helm repository ### Add the Crossplane Preview Helm repository
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.Headings = YES -->
Add the Crossplane preview repository with the `helm repo add` command. Add the Crossplane preview repository with the `helm repo add` command.
@ -36,7 +44,11 @@ local Helm chart cache with `helm repo update`.
helm repo update helm repo update
``` ```
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.Headings = NO -->
### Install the Crossplane Preview Helm chart ### Install the Crossplane Preview Helm chart
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.Headings = YES -->
Install the Crossplane Preview Helm chart with `helm install`. Install the Crossplane Preview Helm chart with `helm install`.
@ -66,7 +78,11 @@ crossplane-rbac-manager-86d9b5cf9f-2vc4s 1/1 Running 0 26m
## Installation options ## Installation options
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.Headings = NO -->
### Customize the Crossplane Helm chart ### Customize the Crossplane Helm chart
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.Headings = YES -->
Crossplane supports customizations at install time by configuring the Helm Crossplane supports customizations at install time by configuring the Helm
chart. chart.

48
content/master/guides/crossplane-with-argo-cd.md
View File

@ -1,11 +1,15 @@
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.HeadingAcronyms = NO -->
--- ---
title: Configuring Crossplane with Argo CD title: Configuring Crossplane with Argo CD
weight: 270 weight: 270
--- ---
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.HeadingAcronyms = YES -->
[Argo CD](https://argoproj.github.io/cd/) and [Crossplane](https://crossplane.io) [Argo CD](https://argoproj.github.io/cd/) and [Crossplane](https://crossplane.io)
are a great combination. Argo CD provides GitOps while Crossplane turns any Kubernetes are a great combination. Argo CD provides GitOps while Crossplane turns any Kubernetes
cluster into a Universal Control Plane for all of your resources. Configuration details are cluster into a Universal Control Plane for all your resources. Configuration details are
required in order for the two to work together properly. required in order for the two to work together properly.
This doc will help you understand these requirements. It is recommended to use This doc will help you understand these requirements. It is recommended to use
Argo CD version 2.4.8 or later with Crossplane. Argo CD version 2.4.8 or later with Crossplane.
@ -15,12 +19,16 @@ with those running in a Kubernetes cluster (GitOps). Argo CD has different ways
how it tracks resources. With Crossplane, you need to configure Argo CD how it tracks resources. With Crossplane, you need to configure Argo CD
to use Annotation based resource tracking. See the [Argo CD docs](https://argo-cd.readthedocs.io/en/latest/user-guide/resource_tracking/) for additional detail. to use Annotation based resource tracking. See the [Argo CD docs](https://argo-cd.readthedocs.io/en/latest/user-guide/resource_tracking/) for additional detail.
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.HeadingAcronyms = NO -->
### Configuring Argo CD with Crossplane ### Configuring Argo CD with Crossplane
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.HeadingAcronyms = YES -->
#### Set Resource Tracking Method #### Set resource tracking method
In order for Argo CD to correctly track Application resources that contain Crossplane related objects it needs In order for Argo CD to track Application resources that contain Crossplane related objects, configure it
to be configured to use the annotation mechanism. to use the annotation mechanism.
To configure it, edit the `argocd-cm` `ConfigMap` in the `argocd` `Namespace` as such: To configure it, edit the `argocd-cm` `ConfigMap` in the `argocd` `Namespace` as such:
```yaml ```yaml
@ -30,11 +38,11 @@ data:
application.resourceTrackingMethod: annotation application.resourceTrackingMethod: annotation
``` ```
#### Set Health Status #### Set health status
Argo CD has a built-in health assessment for Kubernetes resources. Some checks are supported by the community directly Argo CD has a built-in health assessment for Kubernetes resources. The community directly supports some checks
in Argo's [repository](https://github.com/argoproj/argo-cd/tree/master/resource_customizations). For example the `Provider` in Argo's [repository](https://github.com/argoproj/argo-cd/tree/master/resource_customizations). For example the `Provider`
from `pkg.crossplane.io` has already been declared which means there no further configuration needed. from `pkg.crossplane.io` already exists which means there no further configuration needed.
Argo CD also enable customising these checks per instance, and that's the mechanism used to provide support Argo CD also enable customising these checks per instance, and that's the mechanism used to provide support
of Provider's CRDs. of Provider's CRDs.
@ -180,13 +188,13 @@ data:
return health_status return health_status
``` ```
#### Set Resource Exclusion #### Set resource exclusion
Crossplane providers generates a `ProviderConfigUsage` for each of the managed resource (MR) it handles. This resource Crossplane providers generate a `ProviderConfigUsage` for each managed resource (MR) they handle. This resource
enable representing the relationship between MR and a ProviderConfig so that the controller can use it as finalizer when a enables representing the relationship between MR and a ProviderConfig so that the controller can use it as a finalizer when you delete a
ProviderConfig is deleted. End users of Crossplane aren't expected to interact with this resource. ProviderConfig. End users of Crossplane don't need to interact with this resource.
Argo CD UI reactivity can be impacted as the number of resource and types grow. To help keep this number low we A growing number of resources and types can impact Argo CD UI reactivity. To help keep this number low, Crossplane
recommend hiding all `ProviderConfigUsage` resources from Argo CD UI. recommend hiding all `ProviderConfigUsage` resources from Argo CD UI.
To configure resource exclusion edit the `argocd-cm` `ConfigMap` in the `argocd` `Namespace` as such: To configure resource exclusion edit the `argocd-cm` `ConfigMap` in the `argocd` `Namespace` as such:
@ -201,15 +209,19 @@ data:
- ProviderConfigUsage - ProviderConfigUsage
``` ```
The use of `"*"` as apiGroups will enable the mechanism for all Crossplane Providers. The use of `"*"` as apiGroups enables the mechanism for all Crossplane Providers.
#### Increase Kubernetes Client QPS <!-- vale Google.Headings = NO -->
<!-- vale Microsoft.HeadingAcronyms = NO -->
#### Increase Kubernetes client QPS
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.HeadingAcronyms = YES -->
As the number of CRDs grow on a control plane it will increase the amount of queries Argo CD Application Controller As the number of CRDs grow on a control plane it increases the amount of queries Argo CD Application Controller
needs to send to the Kubernetes API. If this is the case you can increase the rate limits of the Argo CD Kubernetes client. needs to send to the Kubernetes API. If this is the case you can increase the rate limits of the Argo CD Kubernetes client.
Set the environment variable `ARGOCD_K8S_CLIENT_QPS` to `300` for improved compatibility with a large number of CRDs. Set the environment variable `ARGOCD_K8S_CLIENT_QPS` to `300` for improved compatibility with multiple CRDs.
The default value of `ARGOCD_K8S_CLIENT_QPS` is 50, modifying the value will also update `ARGOCD_K8S_CLIENT_BURST` as it The default value of `ARGOCD_K8S_CLIENT_QPS` is 50, modifying the value also updates `ARGOCD_K8S_CLIENT_BURST` as it
is default to `ARGOCD_K8S_CLIENT_QPS` x 2. is default to `ARGOCD_K8S_CLIENT_QPS` x 2.

6
content/master/guides/extensions-release-process.md
View File

@ -5,7 +5,9 @@ description: "Configuring build pipelines for Crossplane extensions with GitHub
Actions" Actions"
--- ---
<!-- vale Google.Headings = NO -->
## Distributing Crossplane extensions ## Distributing Crossplane extensions
<!-- vale Google.Headings = YES -->
Crossplane provides a packaging specification for extending a Crossplane Crossplane provides a packaging specification for extending a Crossplane
instance with APIs and business logic for composing resources. instance with APIs and business logic for composing resources.
@ -112,7 +114,7 @@ The workflow generates a default version string if user input isn't provided.
See [branching conventions](#branching-conventions) for more details on tagging See [branching conventions](#branching-conventions) for more details on tagging
practices and optionally overriding the inferred git tag version. practices and optionally overriding the inferred git tag version.
## Common Configuration ## Common configuration
While the reusable workflows referenced in the quickstart guides are for While the reusable workflows referenced in the quickstart guides are for
convenience, users may choose to write their own custom GitHub Actions. convenience, users may choose to write their own custom GitHub Actions.
@ -248,7 +250,7 @@ Edit the following variables to define the target registry:
2. `XPKG_REG_ORGS_NO_PROMOTE` - for registries that don't use or infer 2. `XPKG_REG_ORGS_NO_PROMOTE` - for registries that don't use or infer
channel tags. channel tags.
For example, the following dual-pushes to `xpkg.crossplane.io` as well as For example, the following dual-pushes to `xpkg.crossplane.io` and
`index.docker.io`: `index.docker.io`:
```make ```make

2
content/master/guides/function-patch-and-transform.md
View File

@ -1,7 +1,7 @@
--- ---
title: Function Patch and Transform title: Function Patch and Transform
weight: 70 weight: 70
description: "A function that use patches and transforms to modify inputs from composite resources before creating managed resources" description: "A function that use patches and transforms to change inputs from composite resources before creating managed resources"
--- ---
Function Patch and Transform allows you to write a Composition that specifies Function Patch and Transform allows you to write a Composition that specifies

2
content/master/guides/metrics.md
View File

@ -1,7 +1,7 @@
--- ---
title: Metrics title: Metrics
weight: 60 weight: 60
description: "Metrics are essential for monitoring Crossplane's operations, helping to quickly identify and resolve potential issues." description: "Metrics are essential for monitoring Crossplane's operations, helping to identify and resolve potential issues."
--- ---
Crossplane produces [Prometheus style metrics](https://prometheus.io/docs/introduction/overview/#what-are-metrics) for effective monitoring and alerting in your environment. Crossplane produces [Prometheus style metrics](https://prometheus.io/docs/introduction/overview/#what-are-metrics) for effective monitoring and alerting in your environment.

18
content/master/guides/self-signed-ca-certs.md
View File

@ -1,24 +1,28 @@
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.HeadingAcronyms = NO -->
--- ---
title: Self-Signed CA Certs title: Self-signed CA certs
weight: 270 weight: 270
--- ---
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.HeadingAcronyms = YES -->
> Using self-signed certificates isn't advised in production, it's > Using self-signed certificates isn't advised in production, it's
recommended to only use self-signed certificates for testing. recommended to only use self-signed certificates for testing.
When Crossplane loads Configuration and Provider Packages from private When Crossplane loads Configuration and Provider Packages from private
registries, it must be configured to trust the CA and Intermediate certs. registries, you must configure it to trust the CA and Intermediate certs.
Crossplane needs to be installed via the Helm chart with the You need to install Crossplane via the Helm chart with the
`registryCaBundleConfig.name` and `registryCaBundleConfig.key` parameters `registryCaBundleConfig.name` and `registryCaBundleConfig.key` parameters
defined. See [Install Crossplane]({{<ref "../get-started/install" >}}). defined. See [Install Crossplane]({{<ref "../get-started/install" >}}).
## Configure ## Configure
1. Create a CA Bundle (A file containing your Root and Intermediate 1. Create a CA Bundle (A file containing your Root and Intermediate
certificates in a specific order). This can be done with any text editor or certificates in a specific order). You can do this with any text editor or
from the command line, so long as the resulting file contains all required crt from the command line, so long as the resulting file contains all required crt
files in the proper order. In many cases, this will be either a single files in the proper order. Often, this is either a single
self-signed Root CA crt file, or an Intermediate crt and Root crt file. The self-signed Root CA crt file, or an Intermediate crt and Root crt file. The
order of the crt files should be from lowest to highest in signing order. order of the crt files should be from lowest to highest in signing order.
For example, if you have a chain of two certificates below your Root For example, if you have a chain of two certificates below your Root
@ -39,7 +43,7 @@ kubectl -n [Crossplane system namespace] create cm ca-bundle-config \
`ca-bundle-config` and the `registryCaBundleConfig.key` parameter to `ca-bundle-config` and the `registryCaBundleConfig.key` parameter to
`ca-bundle`. `ca-bundle`.
> Providing Helm with parameter values is covered in the Helm docs, > The Helm docs cover providing Helm with parameter values,
[Helm install](https://helm.sh/docs/helm/helm_install/). An example block [Helm install](https://helm.sh/docs/helm/helm_install/). An example block
in an `override.yaml` file would look like this: in an `override.yaml` file would look like this:
``` ```

63
content/master/guides/troubleshoot-crossplane.md
View File

@ -2,22 +2,22 @@
title: Troubleshoot Crossplane title: Troubleshoot Crossplane
weight: 306 weight: 306
--- ---
## Requested Resource Not Found ## Requested resource not found
If you use the Crossplane CLI to install a `Provider` or If you use the Crossplane CLI to install a `Provider` or
`Configuration` (for example, `crossplane xpkg install provider `Configuration` (for example, `crossplane xpkg install provider
xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1`) and get `the server xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1`) and get `the server
could not find the requested resource` error, more often than not, that's an could not find the requested resource` error, more often than not, that's an
indicator that the Crossplane CLI you're using is outdated. In other words indicator that your Crossplane CLI needs updating. In other words
some Crossplane API has been graduated from alpha to beta or stable and the old Crossplane graduated some API from alpha to beta or stable and the old
plugin isn't aware of this change. plugin isn't aware of this change.
## Resource Status and Conditions ## Resource status and conditions
Most Crossplane resources have a `status` section that can represent the current Most Crossplane resources have a `status` section that can represent the current
state of that particular resource. Running `kubectl describe` against a state of that particular resource. Running `kubectl describe` against a
Crossplane resource will frequently give insightful information about its Crossplane resource frequently gives insightful information about its
condition. For example, to determine the status of a GCP `CloudSQLInstance` condition. For example, to determine the status of a GCP `CloudSQLInstance`
managed resource use `kubectl describe` for the resource. managed resource use `kubectl describe` for the resource.
@ -35,7 +35,7 @@ Most Crossplane resources set the `Ready` condition. `Ready` represents the
availability of the resource - whether it's creating, deleting, available, availability of the resource - whether it's creating, deleting, available,
unavailable, binding, etc. unavailable, binding, etc.
## Resource Events ## Resource events
Most Crossplane resources emit _events_ when something interesting happens. You Most Crossplane resources emit _events_ when something interesting happens. You
can see the events associated with a resource by running `kubectl describe` - can see the events associated with a resource by running `kubectl describe` -
@ -49,11 +49,15 @@ Events:
Warning CannotConnectToProvider 16s (x4 over 46s) managed/postgresqlserver.database.azure.crossplane.io cannot get referenced ProviderConfig: ProviderConfig.azure.crossplane.io "default" not found Warning CannotConnectToProvider 16s (x4 over 46s) managed/postgresqlserver.database.azure.crossplane.io cannot get referenced ProviderConfig: ProviderConfig.azure.crossplane.io "default" not found
``` ```
> Note that events are namespaced, while many Crossplane resources (XRs, etc) > Note that Kubernetes namespaces events, while most Crossplane resources (XRs, etc)
> are cluster scoped. Crossplane emits events for cluster scoped resources to > are cluster scoped. Crossplane emits events for cluster scoped resources to
> the 'default' namespace. > the 'default' namespace.
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.Headings = NO -->
## Crossplane Logs ## Crossplane Logs
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.Headings = YES -->
The next place to look to get more information or investigate a failure would be The next place to look to get more information or investigate a failure would be
in the Crossplane pod logs, which should be running in the `crossplane-system` in the Crossplane pod logs, which should be running in the `crossplane-system`
@ -63,16 +67,16 @@ namespace. To get the current Crossplane logs, run the following:
kubectl -n crossplane-system logs -lapp=crossplane kubectl -n crossplane-system logs -lapp=crossplane
``` ```
> Note that Crossplane emits few logs by default - events are typically the best > Note that Crossplane emits minimal logs by default - events are typically the best
> place to look for information about what Crossplane is doing. You may need to > place to look for information about what Crossplane is doing. You may need to
> restart Crossplane with the `--debug` flag if you can't find what you're > restart Crossplane with the `--debug` flag if you can't find what you're
> looking for. > looking for.
## Provider Logs ## Provider logs
Remember that much of Crossplane's functionality is provided by providers. You Remember that providers provide much of Crossplane's features. You
can use `kubectl logs` to view provider logs too. By convention, they also emit can use `kubectl logs` to view provider logs too. By convention, they also emit
few logs by default. minimal logs by default.
```shell ```shell
kubectl -n crossplane-system logs <name-of-provider-pod> kubectl -n crossplane-system logs <name-of-provider-pod>
@ -110,21 +114,21 @@ spec:
name: debug-config name: debug-config
``` ```
> Note that a reference to a `DeploymentRuntimeConfig` can be added to an already > Note that you can add a reference to a `DeploymentRuntimeConfig` to an already
> installed `Provider` and it will update its `Deployment` accordingly. > installed `Provider` and it updates its `Deployment` accordingly.
## Pausing Crossplane ## Pausing Crossplane
Sometimes, for example when you encounter a bug, it can be useful to pause Sometimes, for example when you encounter a bug, it can be useful to pause
Crossplane if you want to stop it from actively attempting to manage your Crossplane if you want to stop it from actively attempting to manage your
resources. To pause Crossplane without deleting all of its resources, run the resources. To pause Crossplane without deleting all its resources, run the
following command to scale down its deployment: following command to scale down its deployment:
```shell ```shell
kubectl -n crossplane-system scale --replicas=0 deployment/crossplane kubectl -n crossplane-system scale --replicas=0 deployment/crossplane
``` ```
Once you have been able to rectify the problem or smooth things out, you can After you have been able to rectify the problem or smooth things out, you can
unpause Crossplane by scaling its deployment back up: unpause Crossplane by scaling its deployment back up:
```shell ```shell
@ -133,10 +137,9 @@ kubectl -n crossplane-system scale --replicas=1 deployment/crossplane
## Pausing Providers ## Pausing Providers
Providers can also be paused when troubleshooting an issue or orchestrating a You can also pause Providers when troubleshooting an issue or orchestrating a
complex migration of resources. Creating and referencing a `DeploymentRuntimeConfig` is complex migration of resources. Creating and referencing a `DeploymentRuntimeConfig` is
the easiest way to scale down a provider, and the `DeploymentRuntimeConfig` can be the easiest way to scale down a provider, and you can change the `DeploymentRuntimeConfig` or remove the reference to scale it back up:
modified or the reference can be removed to scale it back up:
```yaml ```yaml
apiVersion: pkg.crossplane.io/v1beta1 apiVersion: pkg.crossplane.io/v1beta1
@ -162,23 +165,23 @@ spec:
name: scale-config name: scale-config
``` ```
> Note that a reference to a `DeploymentRuntimeConfig` can be added to an already > Note that you can add a reference to a `DeploymentRuntimeConfig` to an already
> installed `Provider` and it will update its `Deployment` accordingly. > installed `Provider` and it updates its `Deployment` accordingly.
## Deleting When a Resource Hangs ## Deleting when a resource hangs
The resources that Crossplane manages will automatically be cleaned up so as not The resources that Crossplane manages are automatically cleaned up so as not
to leave anything running behind. This is accomplished by using finalizers, but to leave anything running behind. Crossplane accomplishes this by using finalizers, but
in certain scenarios the finalizer can prevent the Kubernetes object from in certain scenarios the finalizer can prevent the Kubernetes object from
getting deleted. getting deleted.
To deal with this, we essentially want to patch the object to remove its To deal with this, patch the object to remove its
finalizer, which will then allow it to be deleted completely. Note that this finalizer, which then allows Kubernetes to delete it. Note that this
won't necessarily delete the external resource that Crossplane was managing, so doesn't necessarily delete the external resource that Crossplane was managing, so
you will want to go to your cloud provider's console and look there for any you want to go to your cloud provider's console and look there for any
lingering resources to clean up. lingering resources to clean up.
In general, a finalizer can be removed from an object with this command: In general, you can remove a finalizer from an object with this command:
```shell ```shell
kubectl patch <resource-type> <resource-name> -p '{"metadata":{"finalizers": []}}' --type=merge kubectl patch <resource-type> <resource-name> -p '{"metadata":{"finalizers": []}}' --type=merge
@ -191,9 +194,9 @@ For example, for a `CloudSQLInstance` managed resource (`database.gcp.crossplane
kubectl patch cloudsqlinstance my-db -p '{"metadata":{"finalizers": []}}' --type=merge kubectl patch cloudsqlinstance my-db -p '{"metadata":{"finalizers": []}}' --type=merge
``` ```
## Tips, Tricks, and Troubleshooting ## Tips, tricks, and troubleshooting
In this section we'll cover some common tips, tricks, and troubleshooting steps This section covers some common tips, tricks, and troubleshooting steps
for working with Composite Resources. If you're trying to track down why your for working with Composite Resources. If you're trying to track down why your
Composite Resources aren't working the [Troubleshooting][trouble-ref] page also Composite Resources aren't working the [Troubleshooting][trouble-ref] page also
has some useful information. has some useful information.

10
content/master/guides/uninstall-crossplane.md
View File

@ -10,7 +10,9 @@ in order.
This can leave cloud resources running, requiring manual deletion. This can leave cloud resources running, requiring manual deletion.
{{< /hint >}} {{< /hint >}}
<!-- vale Google.Headings = NO -->
## Ordered Crossplane uninstall ## Ordered Crossplane uninstall
<!-- vale Google.Headings = YES -->
Most Crossplane resources have dependencies on other Crossplane resources. Most Crossplane resources have dependencies on other Crossplane resources.
For example, a _managed resource_ is dependent on the _provider_. For example, a _managed resource_ is dependent on the _provider_.
@ -128,7 +130,9 @@ Use `kubectl delete` to remove the resources.
kubectl delete bucket.s3.aws.upbound.io/crossplane-bucket-867737b10 kubectl delete bucket.s3.aws.upbound.io/crossplane-bucket-867737b10
``` ```
<!-- vale Google.Headings = NO -->
### Remove Crossplane providers ### Remove Crossplane providers
<!-- vale Google.Headings = YES -->
List the installed _providers_ with `kubectl get providers`. List the installed _providers_ with `kubectl get providers`.
@ -144,7 +148,9 @@ Remove the installed _providers_ with `kubectl delete provider`.
kubectl delete provider crossplane-contrib-provider-aws kubectl delete provider crossplane-contrib-provider-aws
``` ```
## Uninstall the Crossplane deployment <!-- vale Google.Headings = NO -->
## Uninstall the Crossplane deployment
<!-- vale Google.Headings = YES -->
Uninstall Crossplane using Helm with `helm uninstall` Uninstall Crossplane using Helm with `helm uninstall`
@ -159,7 +165,9 @@ kubectl get pods -n crossplane-system
No resources found in crossplane-system namespace. No resources found in crossplane-system namespace.
``` ```
<!-- vale Google.Headings = NO -->
## Delete the Crossplane namespace ## Delete the Crossplane namespace
<!-- vale Google.Headings = YES -->
When Helm installs Crossplane it creates the `crossplane-system` namespace. Helm When Helm installs Crossplane it creates the `crossplane-system` namespace. Helm
doesn't uninstall this namespace with `helm uninstall`. doesn't uninstall this namespace with `helm uninstall`.

18
content/master/learn/_index.md
View File

@ -4,7 +4,7 @@ description: Learn more about Crossplane.
weight: 500 weight: 500
--- ---
If you have any questions, please drop us a note on [Crossplane Slack][join-crossplane-slack] or [contact us][contact-us]. If you have any questions, please post in [Crossplane Slack][join-crossplane-slack] or [contact the team][contact-us].
***Learn more about using Crossplane*** ***Learn more about using Crossplane***
- [Latest Design Docs](https://github.com/crossplane/crossplane/tree/main/design) - [Latest Design Docs](https://github.com/crossplane/crossplane/tree/main/design)
@ -12,7 +12,9 @@ If you have any questions, please drop us a note on [Crossplane Slack][join-cros
- [Crossplane Architecture](https://docs.google.com/document/d/1whncqdUeU2cATGEJhHvzXWC9xdK29Er45NJeoemxebo/edit?usp=sharing) - [Crossplane Architecture](https://docs.google.com/document/d/1whncqdUeU2cATGEJhHvzXWC9xdK29Er45NJeoemxebo/edit?usp=sharing)
- [GitLab deploys into multiple clouds from kubectl using Crossplane](https://about.gitlab.com/2019/05/20/gitlab-first-deployed-kubernetes-api-to-multiple-clouds/) - [GitLab deploys into multiple clouds from kubectl using Crossplane](https://about.gitlab.com/2019/05/20/gitlab-first-deployed-kubernetes-api-to-multiple-clouds/)
- [CNCF Talks & Community Presentations](https://www.youtube.com/playlist?list=PL510POnNVaaZJj9OG6PbgsZvgYbhwJRyE) - [CNCF Talks & Community Presentations](https://www.youtube.com/playlist?list=PL510POnNVaaZJj9OG6PbgsZvgYbhwJRyE)
<!-- vale write-good.Weasel = NO -->
- [Software Engineering Daily - Intro Podcast](https://softwareengineeringdaily.com/2019/01/02/crossplane-multicloud-control-plane-with-bassam-tabbara/) - [Software Engineering Daily - Intro Podcast](https://softwareengineeringdaily.com/2019/01/02/crossplane-multicloud-control-plane-with-bassam-tabbara/)
<!-- vale write-good.Weasel = YES -->
***Writing Kubernetes controllers to extend Crossplane*** ***Writing Kubernetes controllers to extend Crossplane***
- [Keep the Space Shuttle Flying: Writing Robust Operators](https://www.youtube.com/watch?v=uf97lOApOv8) - [Keep the Space Shuttle Flying: Writing Robust Operators](https://www.youtube.com/watch?v=uf97lOApOv8)
@ -21,14 +23,16 @@ If you have any questions, please drop us a note on [Crossplane Slack][join-cros
- [Contributor Guide](https://github.com/crossplane/crossplane/blob/main/CONTRIBUTING.md) - [Contributor Guide](https://github.com/crossplane/crossplane/blob/main/CONTRIBUTING.md)
***Join the growing Crossplane community and get involved*** ***Join the growing Crossplane community and get involved***
- Join our [Community Slack](https://slack.crossplane.io/)! - Join the [Community Slack](https://slack.crossplane.io/)!
- Submit an issue on [GitHub](https://github.com/crossplane/crossplane) - Submit an issue on [GitHub](https://github.com/crossplane/crossplane)
- Attend our biweekly [Community Meeting](https://github.com/crossplane/crossplane#get-involved) - Attend the biweekly [Community Meeting](https://github.com/crossplane/crossplane#get-involved)
- Join our biweekly live stream: [The Binding Status](https://github.com/crossplane/tbs) - Join the biweekly live stream: [The Binding Status](https://github.com/crossplane/tbs)
- Subscribe to our [YouTube Channel](https://www.youtube.com/channel/UC19FgzMBMqBro361HbE46Fw) - Subscribe to the [YouTube Channel](https://www.youtube.com/channel/UC19FgzMBMqBro361HbE46Fw)
<!-- vale Crossplane.Spelling = NO --> <!-- vale Crossplane.Spelling = NO -->
- Drop us a note on Twitter: [@crossplane_io](https://twitter.com/crossplane_io) - Follow on Twitter: [@crossplane_io](https://twitter.com/crossplane_io)
- Email us: [crossplane-info@lists.cncf.io](mailto:crossplane-info@lists.cncf.io) <!-- vale gitlab.SubstitutionWarning = NO -->
- email: [crossplane-info@lists.cncf.io](mailto:crossplane-info@lists.cncf.io)
<!-- vale gitlab.SubstitutionWarning = YES -->
<!-- vale Crossplane.Spelling = YES --> <!-- vale Crossplane.Spelling = YES -->
<!-- Named links --> <!-- Named links -->

46
content/master/learn/feature-lifecycle.md
View File

@ -5,56 +5,60 @@ weight: 309
indent: true indent: true
--- ---
# Feature Lifecycle # Feature lifecycle
Crossplane follows a similar feature lifecycle to [upstream Crossplane follows a similar feature lifecycle to [upstream
Kubernetes][kube-features]. All major new features must be added in alpha. Alpha Kubernetes][kube-features]. Crossplane adds all major new features in alpha. Alpha
features are expected to eventually graduate to beta, and then to general features graduate to beta, and then to general
availability (GA). Features that languish at alpha or beta may be subject to availability (GA). Features that languish at alpha or beta may be subject to
deprecation. deprecation.
## Alpha Features ## Alpha features
Alpha are off by default, and must be enabled by a feature flag, for example Alpha features are off by default, and you must enable them by a feature flag, for example
`--enable-composition-revisions`. API types pertaining to alpha features use a `--enable-composition-revisions`. API types for alpha features use a
`vNalphaN` style API version, like `v1alpha`. **Alpha features are subject to `vNalphaN` style API version, like `v1alpha`. **Alpha features are subject to
removal or breaking changes without notice**, and generally not considered ready removal or breaking changes without notice**, and aren't considered ready
for use in production. for use in production.
In some cases alpha features require fields be added to existing beta or GA Sometimes alpha features require Crossplane to add fields to existing beta or GA
<!-- vale alex.Condescending = NO --> <!-- vale alex.Condescending = NO -->
API types. In these cases fields must clearly be marked (for instance in their OpenAPI API types. In these cases you must mark fields (for instance in their OpenAPI
<!-- vale alex.Condescending = YES --> <!-- vale alex.Condescending = YES -->
schema) as alpha and subject to alpha API constraints (or lack thereof). schema) as alpha and subject to alpha API constraints (or lack thereof).
All alpha features should have an issue tracking their graduation to beta. All alpha features should have an issue tracking their graduation to beta.
## Beta Features ## Beta features
Beta features are on by default, but may be disabled by a feature flag. API Beta features are on by default, but you may disable them by a feature flag. API
types pertaining to beta features use a `vNbetaN` style API version, like types for beta features use a `vNbetaN` style API version, like
`v1beta1`. Beta features are considered to be well tested, and won't be `v1beta1`. Crossplane considers beta features to be well tested, and doesn't
removed completely without being marked deprecated for at least two releases. removed without Crossplane marking them deprecated for at least two releases.
The schema and/or semantics of objects may change in incompatible ways in a The schema and/or semantics of objects may change in incompatible ways in a
subsequent beta or stable release. When this happens, we will provide later beta or stable release. When this happens, the team provides
instructions for migrating to the next version. This may require deleting, instructions for migrating to the next version. This may require deleting,
editing, and recreating API objects. The editing process may require some editing, and recreating API objects. The editing process may require some
thought. This may require downtime for applications that rely on the feature. thought. This may require downtime for applications that rely on the feature.
In some cases beta features require fields be added to existing GA API types. In Sometimes beta features require Crossplane to add fields to existing GA API types. In
<!-- vale alex.Condescending = NO --> <!-- vale alex.Condescending = NO -->
these cases fields must clearly be marked (for instance in their OpenAPI schema) as beta these cases you must mark fields (for instance in their OpenAPI schema) as beta
<!-- vale alex.Condescending = YES --> <!-- vale alex.Condescending = YES -->
and subject to beta API constraints (or lack thereof). and subject to beta API constraints (or lack thereof).
All beta features should have an issue tracking their graduation to GA. All beta features should have an issue tracking their graduation to GA.
## GA Features <!-- vale Google.Headings = NO -->
<!-- vale Microsoft.HeadingAcronyms = NO -->
## GA features
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.HeadingAcronyms = YES -->
GA features are always enabled - they can't be disabled. API types pertaining GA features are always enabled - you can't disable them. API types pertaining
to GA features use `vN` style API versions, like `v1`. GA features are widely to GA features use `vN` style API versions, like `v1`. GA features are widely
used and thoroughly tested. They guarantee API stability - only backward used and well tested. They guarantee API stability - Crossplane only allows backward
compatible changes are allowed. compatible changes.
[kube-features]: https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/#feature-stages [kube-features]: https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/#feature-stages

68
content/master/learn/release-cycle.md
View File

@ -3,49 +3,48 @@ title: Release Cycle
weight: 308 weight: 308
--- ---
Starting with the v1.10.0 release, Crossplane is released on a quarterly (13 Starting with the v1.10.0 release, Crossplane releases on a quarterly (13
week) cadence. A cycle is comprised of three general stages: week) cadence. A cycle comprises three general stages:
- Weeks 1—11: [Active Development] - Weeks 1—11: [Active Development]
- Week 12: [Feature Freeze] - Week 12: [Feature Freeze]
- Week 13: [Code Freeze] - Week 13: [Code Freeze]
This results in four releases per year, with the most recent three releases This results in four releases per year, with the most recent three releases
being maintained at any given time. When a new release is cut, the fourth most under maintenance at any given time. When Crossplane cuts a new release, the fourth most
recent release reaches end of life (EOL). Users can expect any given release to recent release reaches end of life (EOL). Users can expect Crossplane to maintain any given release
be maintained for nine months. for nine months.
### Definition of maintenance ### Definition of maintenance
The Crossplane community defines maintenance in that relevant bug fixes that are The Crossplane community defines maintenance in that relevant bug fixes that
merged to the main development branch will be eligible to be backported to the merge to the main development branch are eligible for backporting to the
release branch of any currently maintained version, and patch releases will be release branch of any maintained version, and Crossplane cuts patch releases
cut appropriately. It's also possible that a fix may be merged directly to the appropriately. It's also possible that maintainers merge a fix directly to the
release branch if no longer applicable on the main development branch. release branch if no longer applicable on the main development branch.
Maintenance doesn't indicate any SLA on response time for user support in the Maintenance doesn't include any SLA on response time for user support in the
form of Slack messages or issues, but problems will be addressed on a best form of Slack messages or issues, but maintainers and contributors address problems on a best
effort basis by maintainers and contributors for currently maintained releases. effort basis for maintained releases.
### Patch releases ### Patch releases
_This policy is subject to change in the future._ _This policy is subject to change in the future._
Patch releases are cut for currently maintained minor versions on an as needed Crossplane cuts patch releases for maintained minor versions on an as needed
basis. Any critical backported fixes will be included in a patch release as basis. Crossplane includes any critical backported fixes in a patch release as
soon as possible after merge. soon as possible after merge.
### Pre-releases ### Pre-releases
_This policy is subject to change in the future._ _This policy is subject to change in the future._
Alpha, Beta, and RC releases are cut for an upcoming release on an as needed Crossplane cuts Alpha, Beta, and RC releases for an upcoming release on an as needed
basis. As a policy, at least one pre-release will be cut prior to any minor basis. As a policy, Crossplane cuts at least one pre-release before any minor
release. Pre-releases won't be made on release branches. release. Crossplane doesn't make pre-releases on release branches.
### Provider releases ### Provider releases
The Crossplane release cycle isn't required to be adhered to by any other Other Crossplane projects don't need to adhere to the Crossplane release cycle, but Crossplane encourages a similar cadence. Maintainers listed in
Crossplane projects, but a similar cadence is encouraged. Maintainers listed in
each repository's `OWNERS.md` file are responsible for determining and each repository's `OWNERS.md` file are responsible for determining and
publishing the release cycle for their project. publishing the release cycle for their project.
@ -55,32 +54,31 @@ The following stages are the main milestones in a Crossplane release.
### Active development ### Active development
During active development, any code that meets the requisite criteria (such as During active development, maintainers merge any code that meets the requisite criteria (such as
passing appropriate tests, approved by a maintainer, etc.) will be merged into passing appropriate tests, approved by a maintainer, etc.) into
the main development branch. At present, there is no requirement to formally the main development branch. At present, there is no need to formally
submit an enhancement proposal prior to the start of the release cycle, but submit an enhancement proposal before the start of the release cycle, but
contributors are encouraged to open an issue and gather feedback before starting Crossplane encourages contributors to open an issue and gather feedback before starting
work on a major implementation (see [CONTRIBUTING.md] for more information). work on a major implementation (see [CONTRIBUTING.md] for more information).
### Feature freeze ### Feature freeze
During feature freeze, no new functionality should be merged into the main During feature freeze, maintainers shouldn't merge new features into the main
development branch. Bug fixes, documentation changes, and non critical changes development branch. Maintainers may make bug fixes, documentation changes, and non critical changes. In the case that maintainers deem a new feature essential for a
may be made. In the case that a new feature is deemed absolutely necessary for a release, the Crossplane maintainers weigh the impact of the change and make
release, the Crossplane maintainers will weigh the impact of the change and make a decision on whether to include it.
a decision on whether it should be included.
### Code freeze ### Code freeze
During code freeze, there should be no changes merged to the main development During code freeze, there should be no changes merged to the main development
branch with the following exceptions: branch with the following exceptions:
- Fixes to a failing test that's deemed to be incorrectly testing - Fixes to a failing test that's deemed to be incorrectly testing
functionality. features.
- Documentation only changes. It's possible that a documentation freeze will be - Documentation only changes. It's possible that a documentation freeze is
implemented in the future, but it's not currently enforced. implemented in the future, but it's not enforced.
- Fixes to a critical bug that wasn't previously identified. Merging a bug fix - Fixes to a critical bug that wasn't identified before. Merging a bug fix
during code freeze requires application for and approval of an exception by during code freeze requires requesting and approval of an exception by
Crossplane maintainers. This process is currently informal, but may be Crossplane maintainers. This process is informal, but may be
formalized in the future. formalized in the future.
## Release dates ## Release dates

6
content/master/managed-resources/managed-resources.md
View File

@ -171,7 +171,7 @@ spec:
Matching a controller reference ensures that the matching resource has the same Matching a controller reference ensures that the matching resource has the same
Kubernetes controller reference. Kubernetes controller reference.
This is useful for matching a resource that's composed by the same composite Matching a controller reference is useful for matching a resource that's composed by the same composite
resource (XR). resource (XR).
{{<hint "note" >}} {{<hint "note" >}}
@ -206,7 +206,7 @@ doesn't apply the change. Crossplane never deletes a resource based on a
Crossplane behaves differently than other tools like Terraform. Terraform Crossplane behaves differently than other tools like Terraform. Terraform
deletes and recreates a resource to change an immutable field. Crossplane only deletes and recreates a resource to change an immutable field. Crossplane only
deletes an external resource if their corresponding managed deletes an external resource if their corresponding managed
resource object is deleted from Kubernetes. you delete the resource object from Kubernetes.
<!-- vale write-good.Passive = YES --> <!-- vale write-good.Passive = YES -->
{{< /hint >}} {{< /hint >}}
@ -615,7 +615,7 @@ that it might have leaked a resource.
{{<hint "note">}} {{<hint "note">}}
Providers don't remove the creation annotations. They use the timestamps to Providers don't remove the creation annotations. They use the timestamps to
determine which is most recent. It's normal for a managed resource to have determine which is most recent. It's normal for a managed resource to have
several creation annotations. multiple creation annotations.
{{</hint>}} {{</hint>}}
The provider knows it might have leaked a resource because it updates all the The provider knows it might have leaked a resource because it updates all the

4
content/master/managed-resources/usages.md
View File

@ -20,7 +20,7 @@ for the second one.
## Enable usages ## Enable usages
<!-- vale write-good.Passive = NO --> <!-- vale write-good.Passive = NO -->
Usages are a beta feature. Beta features are enabled by default. Usages are a beta feature. Crossplane enables beta features by default.
<!-- vale write-good.Passive = YES --> <!-- vale write-good.Passive = YES -->
Disable `Usage` support by Disable `Usage` support by
@ -270,7 +270,9 @@ spec:
name: my-prometheus-chart name: my-prometheus-chart
``` ```
<!-- vale Google.Headings = NO -->
## ClusterUsages ## ClusterUsages
<!-- vale Google.Headings = YES -->
Use a `ClusterUsage` to protect cluster scoped resources. Use a `ClusterUsage` to protect cluster scoped resources.

32
content/master/packages/configurations.md
View File

@ -25,7 +25,7 @@ Refer to the
details on their usage of packages. details on their usage of packages.
{{< /hint >}} {{< /hint >}}
## Install a Configuration ## Install a configuration
Install a Configuration with a Crossplane Install a Configuration with a Crossplane
{{<hover line="2" label="install">}}Configuration{{</hover>}} object by setting {{<hover line="2" label="install">}}Configuration{{</hover>}} object by setting
@ -69,7 +69,11 @@ spec:
Crossplane installs the Compositions, Composite Resource Definitions and Crossplane installs the Compositions, Composite Resource Definitions and
Providers listed in the Configuration. Providers listed in the Configuration.
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.Headings = NO -->
### Install with Helm ### Install with Helm
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.Headings = YES -->
Crossplane supports installing Configurations during an initial Crossplane Crossplane supports installing Configurations during an initial Crossplane
installation with the Crossplane Helm chart. installation with the Crossplane Helm chart.
@ -279,24 +283,24 @@ Crossplane can automatically upgrade a package's dependency version to the minim
valid version that satisfies all the constraints. It's an alpha feature that valid version that satisfies all the constraints. It's an alpha feature that
requires enabling with the `--enable-dependency-version-upgrades` flag. requires enabling with the `--enable-dependency-version-upgrades` flag.
In some cases, dependency version downgrade is required for proceeding with Sometimes, Crossplane requires dependency version downgrade for proceeding with
installations. Suppose configuration A, which depends on package X with the installations. Suppose configuration A, which depends on package X with the
constraint`>=v0.0.0`, is installed on the control plane. In this case, the package constraint`>=v0.0.0`, installs on the control plane. In this case, the package
manager installs the latest version of package X, such as `v3.0.0`. Later, you decide manager installs the latest version of package X, such as `v3.0.0`. Later, you decide
to install configuration B, which depends on package X with the constraint `<=v2.0.0`. to install configuration B, which depends on package X with the constraint `<=v2.0.0`.
Since version `v2.0.0`satisfies both conditions, package X must be downgraded to Since version `v2.0.0`satisfies both conditions, Crossplane must downgrade package X to
allow the installation of configuration B which is disabled by default. allow the installation of configuration B, which Crossplane disables by default.
For enabling automatic dependency version downgrades, there is a configuration For enabling automatic dependency version downgrades, there is a configuration
option as a helm value `packageManager.enableAutomaticDependencyDowngrade=true`. option as a helm value `packageManager.enableAutomaticDependencyDowngrade=true`.
Downgrading a package can cause unexpected behavior, therefore, this Downgrading a package can cause unexpected behavior, so this
option is disabled by default. After enabling this option, the package manager will Crossplane disables this option by default. After enabling this option, the package manager
automatically downgrade a package's dependency version to the maximum valid version automatically downgrades a package's dependency version to the maximum valid version
that satisfies the constraints. that satisfies the constraints.
{{<hint "note" >}} {{<hint "note" >}}
This configuration requires the `--enable-dependency-version-upgrades` flag. This configuration requires the `--enable-dependency-version-upgrades` flag.
Please check the Please see the
[configuration options]({{<ref "../get-started/install#customize-the-crossplane-helm-chart">}}) [configuration options]({{<ref "../get-started/install#customize-the-crossplane-helm-chart">}})
and and
[feature flags]({{<ref "../get-started/install#feature-flags">}}) [feature flags]({{<ref "../get-started/install#feature-flags">}})
@ -310,11 +314,15 @@ Enabling automatic dependency downgrades may have unintended consequences, such
1) CRDs missing in the downgraded version, possibly leaving orphaned MRs without 1) CRDs missing in the downgraded version, possibly leaving orphaned MRs without
controllers to reconcile them. controllers to reconcile them.
2) Loss of data if downgraded CRD versions omit fields that were set before. 2) Loss of data if downgraded CRD versions omit fields that you set before.
3) Changes in the CRD storage version, which may prevent package version update. 3) Changes in the CRD storage version, which may prevent package version update.
{{</hint >}} {{</hint >}}
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.Headings = NO -->
#### Ignore Crossplane version requirements #### Ignore Crossplane version requirements
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.Headings = YES -->
A Configuration package may require a specific or minimum Crossplane version A Configuration package may require a specific or minimum Crossplane version
before installing. By default, Crossplane doesn't install a Configuration if before installing. By default, Crossplane doesn't install a Configuration if
@ -338,7 +346,7 @@ spec:
``` ```
### Verify a Configuration ### Verify a configuration
Verify a Configuration with Verify a Configuration with
{{<hover label="verify" line="1">}}kubectl get configuration{{</hover >}}. {{<hover label="verify" line="1">}}kubectl get configuration{{</hover >}}.
@ -400,7 +408,7 @@ The {{<hover label="depend" line="18">}}Events{{</hover>}} show a
current version of Crossplane doesn't meet the Configuration package current version of Crossplane doesn't meet the Configuration package
requirements. requirements.
## Create a Configuration ## Create a configuration
Crossplane Configuration packages are Crossplane Configuration packages are
[OCI container images](https://opencontainers.org/) containing one or more YAML [OCI container images](https://opencontainers.org/) containing one or more YAML

2
content/master/packages/functions.md
View File

@ -22,7 +22,7 @@ Read the [composition]({{<ref "../composition/compositions">}}) documentation to
learn how to use functions in a composition. learn how to use functions in a composition.
{{</hint>}} {{</hint>}}
## Install a Function ## Install a function
Install a Function with a Crossplane Install a Function with a Crossplane
{{<hover label="install" line="2">}}Function{{</hover >}} object setting the {{<hover label="install" line="2">}}Function{{</hover >}} object setting the

8
content/master/packages/image-configs.md
View File

@ -91,12 +91,12 @@ Signature verification is an alpha feature and needs to be enabled with the
{{< /hint >}} {{< /hint >}}
You can use `ImageConfig` to configure signature verification for images. When You can use `ImageConfig` to configure signature verification for images. When
signature verification is enabled, the package manager verifies the signature of you enable signature verification, the package manager verifies the signature of
each image before pulling it. If the signature isn't valid, the package manager each image before pulling it. If the signature isn't valid, the package manager
rejects the package deployment. rejects the package deployment.
In the following example, the `ImageConfig` resource named `verify-acme-packages` In the following example, the `ImageConfig` resource named `verify-acme-packages`
is configured to verify the signature of images with the prefixes configures verification of the signature of images with the prefixes
`registry1.com/acme-co/configuration-foo` and `registry1.com/acme-co/configuration-foo` and
`registry1.com/acme-co/configuration-bar`. `registry1.com/acme-co/configuration-bar`.
@ -152,7 +152,7 @@ secret configuration, as described in the previous section.
### Checking the signature verification status ### Checking the signature verification status
When signature verification is enabled, the respective controller reports the When you enable signature verification, the respective controller reports the
verification status as a condition of type `Verified` on the package revision verification status as a condition of type `Verified` on the package revision
resources. This condition indicates whether the signature verification was resources. This condition indicates whether the signature verification was
successful, failed, skipped, or incomplete due to an error. successful, failed, skipped, or incomplete due to an error.
@ -209,6 +209,6 @@ verifying the signature of the image in the package revision.
If you can't see this condition on the package revision resource, namely If you can't see this condition on the package revision resource, namely
`ProviderRevision`, `ConfigurationRevision`, or `FunctionRevision`, ensure that `ProviderRevision`, `ConfigurationRevision`, or `FunctionRevision`, ensure that
the feature is enabled. you enable the feature.
<!-- vale write-good.Passive = YES --> <!-- vale write-good.Passive = YES -->

34
content/master/packages/providers.md
View File

@ -30,7 +30,7 @@ These endpoints are
<!-- vale write-good.Passive = YES --> <!-- vale write-good.Passive = YES -->
## Install a Provider ## Install a provider
Installing a provider creates new Kubernetes resources representing the Installing a provider creates new Kubernetes resources representing the
Provider's APIs. Installing a provider also creates a Provider pod that's Provider's APIs. Installing a provider also creates a Provider pod that's
@ -92,7 +92,11 @@ spec:
``` ```
{{</hint >}} {{</hint >}}
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.Headings = NO -->
### Install with Helm ### Install with Helm
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.Headings = YES -->
Crossplane supports installing Providers during an initial Crossplane Crossplane supports installing Providers during an initial Crossplane
installation with the Crossplane Helm chart. installation with the Crossplane Helm chart.
@ -303,24 +307,24 @@ Crossplane can automatically upgrade a package's dependency version to the minim
valid version that satisfies all the constraints. It's an alpha feature that valid version that satisfies all the constraints. It's an alpha feature that
requires enabling with the `--enable-dependency-version-upgrades` flag. requires enabling with the `--enable-dependency-version-upgrades` flag.
In some cases, dependency version downgrade is required for proceeding with Sometimes, Crossplane requires dependency version downgrade for proceeding with
installations. Suppose configuration A, which depends on package X with the installations. Suppose configuration A, which depends on package X with the
constraint`>=v0.0.0`, is installed on the control plane. In this case, the package constraint`>=v0.0.0`, installs on the control plane. In this case, the package
manager installs the latest version of package X, such as `v3.0.0`. Later, you decide manager installs the latest version of package X, such as `v3.0.0`. Later, you decide
to install configuration B, which depends on package X with the constraint `<=v2.0.0`. to install configuration B, which depends on package X with the constraint `<=v2.0.0`.
Since version `v2.0.0`satisfies both conditions, package X must be downgraded to Since version `v2.0.0`satisfies both conditions, Crossplane must downgrade package X to
allow the installation of configuration B which is disabled by default. allow the installation of configuration B, which Crossplane disables by default.
For enabling automatic dependency version downgrades, there is a configuration For enabling automatic dependency version downgrades, there is a configuration
option as a helm value `packageManager.enableAutomaticDependencyDowngrade=true`. option as a helm value `packageManager.enableAutomaticDependencyDowngrade=true`.
Downgrading a package can cause unexpected behavior, therefore, this Downgrading a package can cause unexpected behavior, so this
option is disabled by default. After enabling this option, the package manager will Crossplane disables this option by default. After enabling this option, the package manager
automatically downgrade a package's dependency version to the maximum valid version automatically downgrades a package's dependency version to the maximum valid version
that satisfies the constraints. that satisfies the constraints.
{{<hint "note" >}} {{<hint "note" >}}
This configuration requires the `--enable-dependency-version-upgrades` flag. This configuration requires the `--enable-dependency-version-upgrades` flag.
Please check the Please see the
[configuration options]({{<ref "../get-started/install#customize-the-crossplane-helm-chart">}}) [configuration options]({{<ref "../get-started/install#customize-the-crossplane-helm-chart">}})
and and
[feature flags]({{<ref "../get-started/install#feature-flags">}}) [feature flags]({{<ref "../get-started/install#feature-flags">}})
@ -334,11 +338,15 @@ Enabling automatic dependency downgrades may have unintended consequences, such
1) CRDs missing in the downgraded version, possibly leaving orphaned MRs without 1) CRDs missing in the downgraded version, possibly leaving orphaned MRs without
controllers to reconcile them. controllers to reconcile them.
2) Loss of data if downgraded CRD versions omit fields that were set before. 2) Loss of data if downgraded CRD versions omit fields that you set before.
3) Changes in the CRD storage version, which may prevent package version update. 3) Changes in the CRD storage version, which may prevent package version update.
{{</hint >}} {{</hint >}}
<!-- vale Google.Headings = NO -->
<!-- vale Microsoft.Headings = NO -->
#### Ignore Crossplane version requirements #### Ignore Crossplane version requirements
<!-- vale Google.Headings = YES -->
<!-- vale Microsoft.Headings = YES -->
A Provider package may require a specific or minimum Crossplane version before A Provider package may require a specific or minimum Crossplane version before
installing. By default, Crossplane doesn't install a Provider if the Crossplane installing. By default, Crossplane doesn't install a Provider if the Crossplane
@ -409,7 +417,7 @@ The {{<hover label="depend" line="17">}}Events{{</hover>}} show a
current version of Crossplane doesn't meet the Configuration package current version of Crossplane doesn't meet the Configuration package
requirements. requirements.
## Upgrade a Provider ## Upgrade a provider
To upgrade an existing Provider edit the installed Provider Package by either To upgrade an existing Provider edit the installed Provider Package by either
applying a new Provider manifest or with `kubectl edit providers`. applying a new Provider manifest or with `kubectl edit providers`.
@ -441,7 +449,7 @@ change the default value.
Only a single revision of a Provider is Only a single revision of a Provider is
{{<hover label="getPR" line="4">}}Active{{</hover>}} at a time. {{<hover label="getPR" line="4">}}Active{{</hover>}} at a time.
## Remove a Provider ## Remove a provider
Remove a Provider by deleting the Provider object with Remove a Provider by deleting the Provider object with
`kubectl delete provider`. `kubectl delete provider`.
@ -681,7 +689,7 @@ the runtime is working and overlay them on top of the values
in the runtime configuration. For example, it defaults the replica count in the runtime configuration. For example, it defaults the replica count
to 1 if not set and overrides the label selectors to make sure the Deployment to 1 if not set and overrides the label selectors to make sure the Deployment
and Service match. It also injects any necessary environment variables, and Service match. It also injects any necessary environment variables,
ports as well as volumes and volume mounts. ports and volumes and volume mounts.
The `Provider` or `Functions`'s `spec.runtimeConfigRef.name` field defaults The `Provider` or `Functions`'s `spec.runtimeConfigRef.name` field defaults
to value `default`, which means Crossplane uses the default runtime configuration to value `default`, which means Crossplane uses the default runtime configuration

4
content/master/whats-crossplane/_index.md
View File

@ -127,7 +127,7 @@ logic, and work in your preferred language.
{{<hint "important">}} {{<hint "important">}}
Composition functions are like configuration language plugins. Composition functions are like configuration language plugins.
Functions allow you to write your configuration in several languages, including Functions allow you to write your configuration in multiple languages, including
[YAML](https://yaml.org), [KCL](https://www.kcl-lang.io), [YAML](https://yaml.org), [KCL](https://www.kcl-lang.io),
[Python](https://python.org), and [Go](https://go.dev). [Python](https://python.org), and [Go](https://go.dev).
{{</hint>}} {{</hint>}}
@ -229,7 +229,7 @@ The Crossplane package manager lets you install new managed resources and
composition functions. composition functions.
You can also package any part of a control plane's configuration and install it You can also package any part of a control plane's configuration and install it
using the package manager. This allows you to deploy several control planes with using the package manager. This allows you to deploy multiple control planes with
identical capabilities - for example one control plane per region or per identical capabilities - for example one control plane per region or per
service. service.

4
utils/vale/styles/Crossplane/spelling-exceptions.txt
View File

@ -1,5 +1,6 @@
/tab /tab
/tabs /tabs
backporting
built-in built-in
call-outs call-outs
ClusterRoles` ClusterRoles`
@ -54,4 +55,5 @@ UpperCamelCase
UpperCamelCased UpperCamelCased
user-defined user-defined
v2 v2
version-specific version-specific
backporting