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

Update explanation of --enable-dependency-version-downgrades flag 

Signed-off-by: Jared Watts <jbw976@gmail.com>
This commit is contained in:
Jared Watts 2025-05-14 17:02:05 +01:00
parent 2b6b6b1296
commit 18683f21c4
No known key found for this signature in database
GPG Key ID: 0467EEAE3B6EC0D2
2 changed files with 164 additions and 164 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -5,44 +5,44 @@ altTitle: "Crossplane Packages"
weight: 200 weight: 200
--- ---
A _Configuration_ package is an A _Configuration_ package is an
[OCI container image](https://opencontainers.org/) containing a collection of [OCI container image](https://opencontainers.org/) containing a collection of
[Compositions]({{<ref "./compositions" >}}), [Compositions]({{<ref "./compositions" >}}),
[Composite Resource Definitions]({{<ref "./composite-resource-definitions" >}}) [Composite Resource Definitions]({{<ref "./composite-resource-definitions" >}})
and any required [Providers]({{<ref "./providers">}}) or and any required [Providers]({{<ref "./providers">}}) or
[Functions]({{<ref "./compositions" >}}). [Functions]({{<ref "./compositions" >}}).
Configuration packages make your Crossplane configuration fully portable. Configuration packages make your Crossplane configuration fully portable.
{{<hint "important" >}} {{<hint "important" >}}
Crossplane [Providers]({{<ref "./providers">}}) and Crossplane [Providers]({{<ref "./providers">}}) and
[Functions]({{<ref "./compositions">}}) are also Crossplane packages. [Functions]({{<ref "./compositions">}}) are also Crossplane packages.
This document describes how to install and manage configuration packages. This document describes how to install and manage configuration packages.
Refer to the Refer to the
[Provider]({{<ref "./providers">}}) and [Provider]({{<ref "./providers">}}) and
[Composition Functions]({{<ref "./compositions">}}) chapters for [Composition Functions]({{<ref "./compositions">}}) chapters for
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
the {{<hover line="6" label="install">}}spec.package{{</hover>}} value to the the {{<hover line="6" label="install">}}spec.package{{</hover>}} value to the
location of the configuration package. location of the configuration package.
{{< hint "important" >}} {{< hint "important" >}}
Beginning with Crossplane version 1.20.0 Crossplane uses the [crossplane-contrib](https://github.com/orgs/crossplane-contrib/packages) GitHub Container Registry at `xpkg.crossplane.io` by default for downloading and Beginning with Crossplane version 1.20.0 Crossplane uses the [crossplane-contrib](https://github.com/orgs/crossplane-contrib/packages) GitHub Container Registry at `xpkg.crossplane.io` by default for downloading and
installing packages. installing packages.
Specify the full domain name with the `package` or change the default Crossplane Specify the full domain name with the `package` or change the default Crossplane
registry with the `--registry` flag on the [Crossplane pod]({{<ref "./pods">}}) registry with the `--registry` flag on the [Crossplane pod]({{<ref "./pods">}})
{{< /hint >}} {{< /hint >}}
For example to install the For example to install the
[Getting Started Configuration](https://github.com/crossplane-contrib/configuration-quickstart), [Getting Started Configuration](https://github.com/crossplane-contrib/configuration-quickstart),
```yaml {label="install"} ```yaml {label="install"}
apiVersion: pkg.crossplane.io/v1 apiVersion: pkg.crossplane.io/v1
@ -68,7 +68,7 @@ spec:
{{< /hint >}} {{< /hint >}}
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.
### Install with Helm ### Install with Helm
@ -93,7 +93,7 @@ crossplane-stable/crossplane \
Installing Crossplane packages offline requires a local container registry, such as Installing Crossplane packages offline requires a local container registry, such as
[Harbor](https://goharbor.io/) to host the packages. Crossplane only [Harbor](https://goharbor.io/) to host the packages. Crossplane only
supports installing packages from a container registry. supports installing packages from a container registry.
Crossplane doesn't support installing packages directly from Kubernetes Crossplane doesn't support installing packages directly from Kubernetes
volumes. volumes.
@ -101,15 +101,15 @@ volumes.
### Installation options ### Installation options
Configurations support multiple options to change configuration package related Configurations support multiple options to change configuration package related
settings. settings.
#### Configuration revisions #### Configuration revisions
When installing a newer version of an existing Configuration Crossplane creates When installing a newer version of an existing Configuration Crossplane creates
a new configuration revision. a new configuration revision.
View the configuration revisions with View the configuration revisions with
{{<hover label="rev" line="1">}}kubectl get configurationrevisions{{</hover>}}. {{<hover label="rev" line="1">}}kubectl get configurationrevisions{{</hover>}}.
```shell {label="rev",copy-lines="1"} ```shell {label="rev",copy-lines="1"}
@ -120,20 +120,20 @@ platform-ref-aws-3ac761211893 True 1 xpkg.crossplane.io/crosspla
``` ```
Only a single revision is active at a time. The active revision determines the Only a single revision is active at a time. The active revision determines the
available resources, including Compositions and Composite Resource Definitions. available resources, including Compositions and Composite Resource Definitions.
By default Crossplane keeps only a single _Inactive_ revision. By default Crossplane keeps only a single _Inactive_ revision.
Change the number of revisions Crossplane maintains with a Configuration package Change the number of revisions Crossplane maintains with a Configuration package
{{<hover label="revHistory" line="6">}}revisionHistoryLimit{{</hover>}}. {{<hover label="revHistory" line="6">}}revisionHistoryLimit{{</hover>}}.
The {{<hover label="revHistory" line="6">}}revisionHistoryLimit{{</hover>}} The {{<hover label="revHistory" line="6">}}revisionHistoryLimit{{</hover>}}
field is an integer. field is an integer.
The default value is `1`. The default value is `1`.
Disable storing revisions by setting Disable storing revisions by setting
{{<hover label="revHistory" line="6">}}revisionHistoryLimit{{</hover>}} to `0`. {{<hover label="revHistory" line="6">}}revisionHistoryLimit{{</hover>}} to `0`.
For example, to change the default setting and store 10 revisions use For example, to change the default setting and store 10 revisions use
{{<hover label="revHistory" line="6">}}revisionHistoryLimit: 10{{</hover>}}. {{<hover label="revHistory" line="6">}}revisionHistoryLimit: 10{{</hover>}}.
```yaml {label="revHistory"} ```yaml {label="revHistory"}
@ -152,26 +152,26 @@ Use a {{<hover label="pullpolicy" line="6">}}packagePullPolicy{{</hover>}} to
define when Crossplane should download the Configuration package to the local define when Crossplane should download the Configuration package to the local
Crossplane package cache. Crossplane package cache.
The `packagePullPolicy` options are: The `packagePullPolicy` options are:
* `IfNotPresent` - (**default**) Only download the package if it isn't in the cache. * `IfNotPresent` - (**default**) Only download the package if it isn't in the cache.
* `Always` - Check for new packages every minute and download any matching * `Always` - Check for new packages every minute and download any matching
package that isn't in the cache. package that isn't in the cache.
* `Never` - Never download the package. Packages are only installed from the * `Never` - Never download the package. Packages are only installed from the
local package cache. local package cache.
{{<hint "tip" >}} {{<hint "tip" >}}
The Crossplane The Crossplane
{{<hover label="pullpolicy" line="6">}}packagePullPolicy{{</hover>}} works {{<hover label="pullpolicy" line="6">}}packagePullPolicy{{</hover>}} works
like the Kubernetes container image like the Kubernetes container image
[image pull policy](https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy). [image pull policy](https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy).
Crossplane supports the use of tags and package digest hashes like Crossplane supports the use of tags and package digest hashes like
Kubernetes images. Kubernetes images.
{{< /hint >}} {{< /hint >}}
For example, to `Always` download a given Configuration package use the For example, to `Always` download a given Configuration package use the
{{<hover label="pullpolicy" line="6">}}packagePullPolicy: Always{{</hover>}} {{<hover label="pullpolicy" line="6">}}packagePullPolicy: Always{{</hover>}}
configuration. configuration.
```yaml {label="pullpolicy",copy-lines="6"} ```yaml {label="pullpolicy",copy-lines="6"}
apiVersion: pkg.crossplane.io/v1 apiVersion: pkg.crossplane.io/v1
@ -186,20 +186,20 @@ spec:
#### Revision activation policy #### Revision activation policy
The `Active` package revision The `Active` package revision
is the package controller actively reconciling resources. is the package controller actively reconciling resources.
By default Crossplane sets the most recently installed package revision as By default Crossplane sets the most recently installed package revision as
`Active`. `Active`.
Control the Configuration upgrade behavior with a Control the Configuration upgrade behavior with a
{{<hover label="revision" line="6">}}revisionActivationPolicy{{</hover>}}. {{<hover label="revision" line="6">}}revisionActivationPolicy{{</hover>}}.
The {{<hover label="revision" line="6">}}revisionActivationPolicy{{</hover>}} The {{<hover label="revision" line="6">}}revisionActivationPolicy{{</hover>}}
options are: options are:
* `Automatic` - (**default**) Automatically activate the last installed configuration. * `Automatic` - (**default**) Automatically activate the last installed configuration.
* `Manual` - Don't automatically activate a configuration. * `Manual` - Don't automatically activate a configuration.
For example, to change the upgrade behavior to require manual upgrades, set For example, to change the upgrade behavior to require manual upgrades, set
{{<hover label="revision" line="6">}}revisionActivationPolicy: Manual{{</hover>}}. {{<hover label="revision" line="6">}}revisionActivationPolicy: Manual{{</hover>}}.
```yaml {label="revision"} ```yaml {label="revision"}
@ -215,14 +215,14 @@ spec:
#### Install a Configuration from a private registry #### Install a Configuration from a private registry
Like Kubernetes uses `imagePullSecrets` to Like Kubernetes uses `imagePullSecrets` to
[install images from private registries](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/), [install images from private registries](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/),
Crossplane uses `packagePullSecrets` to install Configuration packages from a Crossplane uses `packagePullSecrets` to install Configuration packages from a
private registry. private registry.
Use {{<hover label="pps" line="6">}}packagePullSecrets{{</hover>}} to provide a Use {{<hover label="pps" line="6">}}packagePullSecrets{{</hover>}} to provide a
Kubernetes secret to use for authentication when downloading a Configuration Kubernetes secret to use for authentication when downloading a Configuration
package. package.
{{<hint "important" >}} {{<hint "important" >}}
The Kubernetes secret must be in the same namespace as Crossplane. The Kubernetes secret must be in the same namespace as Crossplane.
@ -232,7 +232,7 @@ The {{<hover label="pps" line="6">}}packagePullSecrets{{</hover>}} is a list of
secrets. secrets.
For example, to use the secret named For example, to use the secret named
{{<hover label="pps" line="6">}}example-secret{{</hover>}} configure a {{<hover label="pps" line="6">}}example-secret{{</hover>}} configure a
{{<hover label="pps" line="6">}}packagePullSecrets{{</hover>}}. {{<hover label="pps" line="6">}}packagePullSecrets{{</hover>}}.
```yaml {label="pps"} ```yaml {label="pps"}
@ -241,7 +241,7 @@ kind: Configuration
metadata: metadata:
name: platform-ref-aws name: platform-ref-aws
spec: spec:
packagePullSecrets: packagePullSecrets:
- name: example-secret - name: example-secret
# Removed for brevity # Removed for brevity
``` ```
@ -249,19 +249,19 @@ spec:
#### Ignore dependencies #### Ignore dependencies
By default Crossplane installs any [dependencies](#manage-dependencies) listed By default Crossplane installs any [dependencies](#manage-dependencies) listed
in a Configuration package. in a Configuration package.
Crossplane can ignore a Configuration package's dependencies with Crossplane can ignore a Configuration package's dependencies with
{{<hover label="pkgDep" line="6" >}}skipDependencyResolution{{</hover>}}. {{<hover label="pkgDep" line="6" >}}skipDependencyResolution{{</hover>}}.
{{< hint "warning" >}} {{< hint "warning" >}}
Most Configurations include dependencies for the required Providers. Most Configurations include dependencies for the required Providers.
If a Configuration ignores dependencies, the required Providers must be If a Configuration ignores dependencies, the required Providers must be
manually installed. manually installed.
{{< /hint >}} {{< /hint >}}
For example, to disable dependency resolution configure For example, to disable dependency resolution configure
{{<hover label="pkgDep" line="6" >}}skipDependencyResolution: true{{</hover>}}. {{<hover label="pkgDep" line="6" >}}skipDependencyResolution: true{{</hover>}}.
```yaml {label="pkgDep"} ```yaml {label="pkgDep"}
@ -285,15 +285,15 @@ 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`, is installed 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, package X must be downgraded to
allow the installation of configuration B which is disabled by default. allow the installation of configuration B which is disabled by default.
For enabling automatic dependency version downgrades, there is a configuration Automatic dependency version downgrades is also an alpha feature that can be
option as a helm value `packageManager.enableAutomaticDependencyDowngrade=true`. enabled with the `--enable-dependency-version-downgrades` flag. Downgrading a
Downgrading a package can cause unexpected behavior, therefore, this package can cause unexpected behavior, therefore, this option is disabled by
option is disabled by default. After enabling this option, the package manager will default. After enabling this option, the package manager will automatically
automatically downgrade a package's dependency version to the maximum valid version downgrade a package's dependency version to the maximum valid version that
that satisfies the constraints. 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.
@ -309,7 +309,7 @@ section for more details.
{{<hint "important" >}} {{<hint "important" >}}
Enabling automatic dependency downgrades may have unintended consequences, such as: Enabling automatic dependency downgrades may have unintended consequences, such as:
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 were 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.
@ -317,15 +317,15 @@ controllers to reconcile them.
#### Ignore Crossplane version requirements #### Ignore Crossplane version requirements
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
the Crossplane version doesn't meet the required version. the Crossplane version doesn't meet the required version.
Crossplane can ignore the required version with Crossplane can ignore the required version with
{{<hover label="xpVer" line="6">}}ignoreCrossplaneConstraints{{</hover>}}. {{<hover label="xpVer" line="6">}}ignoreCrossplaneConstraints{{</hover>}}.
For example, to install a Configuration package into an unsupported Crossplane For example, to install a Configuration package into an unsupported Crossplane
version, configure version, configure
{{<hover label="xpVer" line="6">}}ignoreCrossplaneConstraints: true{{</hover>}}. {{<hover label="xpVer" line="6">}}ignoreCrossplaneConstraints: true{{</hover>}}.
```yaml {label="xpVer"} ```yaml {label="xpVer"}
@ -341,7 +341,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 >}}.
A working configuration reports `Installed` and `Healthy` as `True`. A working configuration reports `Installed` and `Healthy` as `True`.
@ -355,10 +355,10 @@ platform-ref-aws True True xpkg.crossplane.io/crossplane-contrib/c
### Manage dependencies ### Manage dependencies
Configuration packages may include dependencies on other packages including Configuration packages may include dependencies on other packages including
Functions, Providers or other Configurations. Functions, Providers or other Configurations.
If Crossplane can't meet the dependencies of a Configuration the Configuration If Crossplane can't meet the dependencies of a Configuration the Configuration
reports `HEALTHY` as `False`. reports `HEALTHY` as `False`.
For example, this installation of the Getting Started Configuration is For example, this installation of the Getting Started Configuration is
`HEALTHY: False`. `HEALTHY: False`.
@ -369,7 +369,7 @@ NAME INSTALLED HEALTHY PACKAGE
platform-ref-aws True False xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0 71s platform-ref-aws True False xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0 71s
``` ```
To see more information on why the Configuration isn't `HEALTHY` use To see more information on why the Configuration isn't `HEALTHY` use
{{<hover label="depend" line="1">}}kubectl describe configurationrevisions{{</hover>}}. {{<hover label="depend" line="1">}}kubectl describe configurationrevisions{{</hover>}}.
```yaml {copy-lines="1",label="depend"} ```yaml {copy-lines="1",label="depend"}
@ -396,64 +396,64 @@ Events:
Warning LintPackage 29s (x2 over 29s) packages/configurationrevision.pkg.crossplane.io incompatible Crossplane version: package isn't compatible with Crossplane version (v1.12.0) Warning LintPackage 29s (x2 over 29s) packages/configurationrevision.pkg.crossplane.io incompatible Crossplane version: package isn't compatible with Crossplane version (v1.12.0)
``` ```
The {{<hover label="depend" line="18">}}Events{{</hover>}} show a The {{<hover label="depend" line="18">}}Events{{</hover>}} show a
{{<hover label="depend" line="21">}}Warning{{</hover>}} with a message that the {{<hover label="depend" line="21">}}Warning{{</hover>}} with a message that the
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
files. files.
{{<hint "important" >}} {{<hint "important" >}}
Configuration packages are fully OCI compliant. Any tool that builds OCI images Configuration packages are fully OCI compliant. Any tool that builds OCI images
can build Configuration packages. can build Configuration packages.
It's strongly recommended to use the Crossplane command-line tool to It's strongly recommended to use the Crossplane command-line tool to
provide error checking and formatting to Crossplane package builds. provide error checking and formatting to Crossplane package builds.
Read the Read the
[Crossplane package specification](https://github.com/crossplane/crossplane/blob/main/contributing/specifications/xpkg.md) [Crossplane package specification](https://github.com/crossplane/crossplane/blob/main/contributing/specifications/xpkg.md)
for package requirements when building packages with third-party tools. for package requirements when building packages with third-party tools.
{{</hint >}} {{</hint >}}
A Configuration package requires a `crossplane.yaml` file and may include A Configuration package requires a `crossplane.yaml` file and may include
Composition and CompositeResourceDefinition files. Composition and CompositeResourceDefinition files.
<!-- vale Google.Headings = NO --> <!-- vale Google.Headings = NO -->
### The crossplane.yaml file ### The crossplane.yaml file
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
To build a Configuration package using the Crossplane CLI, create a file To build a Configuration package using the Crossplane CLI, create a file
named named
{{<hover label="cfgMeta" line="1">}}crossplane.yaml{{</hover>}}. {{<hover label="cfgMeta" line="1">}}crossplane.yaml{{</hover>}}.
The The
{{<hover label="cfgMeta" line="1">}}crossplane.yaml{{</hover>}} {{<hover label="cfgMeta" line="1">}}crossplane.yaml{{</hover>}}
file defines the requirements and name of the file defines the requirements and name of the
Configuration. Configuration.
{{<hint "important" >}} {{<hint "important" >}}
The Crossplane CLI only supports a file named `crossplane.yaml`. The Crossplane CLI only supports a file named `crossplane.yaml`.
{{< /hint >}} {{< /hint >}}
Configuration package uses the Configuration package uses the
{{<hover label="cfgMeta" line="2">}}meta.pkg.crossplane.io{{</hover>}} {{<hover label="cfgMeta" line="2">}}meta.pkg.crossplane.io{{</hover>}}
Crossplane API group. Crossplane API group.
Specify any other Configurations, Functions or Providers in the Specify any other Configurations, Functions or Providers in the
{{<hover label="cfgMeta" line="7">}}dependsOn{{</hover>}} list. {{<hover label="cfgMeta" line="7">}}dependsOn{{</hover>}} list.
Optionally, you can require a specific or minimum package version with the Optionally, you can require a specific or minimum package version with the
{{<hover label="cfgMeta" line="9">}}version{{</hover>}} option. {{<hover label="cfgMeta" line="9">}}version{{</hover>}} option.
You can also define a specific or minimum version of Crossplane for this You can also define a specific or minimum version of Crossplane for this
Configuration with the Configuration with the
{{<hover label="cfgMeta" line="11">}}crossplane.version{{</hover>}} option. {{<hover label="cfgMeta" line="11">}}crossplane.version{{</hover>}} option.
{{<hint "note" >}} {{<hint "note" >}}
Defining the {{<hover label="cfgMeta" line="10">}}crossplane{{</hover>}} object Defining the {{<hover label="cfgMeta" line="10">}}crossplane{{</hover>}} object
or required versions is optional. or required versions is optional.
{{< /hint >}} {{< /hint >}}
```yaml {label="cfgMeta",copy-lines="all"} ```yaml {label="cfgMeta",copy-lines="all"}
@ -474,8 +474,8 @@ spec:
### Build the package ### Build the package
Create the package using the Create the package using the
[Crossplane CLI]({{<ref "../cli">}}) command [Crossplane CLI]({{<ref "../cli">}}) command
`crossplane xpkg build --package-root=<directory>`. `crossplane xpkg build --package-root=<directory>`.
Where the `<directory>` is the directory containing the `crossplane.yaml` file Where the `<directory>` is the directory containing the `crossplane.yaml` file
@ -485,19 +485,19 @@ The CLI recursively searches for `.yml` or `.yaml` files in the directory to
include in the package. include in the package.
{{<hint "important" >}} {{<hint "important" >}}
You must ignore any other YAML files with `--ignore=<file_list>`. You must ignore any other YAML files with `--ignore=<file_list>`.
For For
example, `crossplane xpkg build --package-root=test-directory --ignore=".tmp/*"`. example, `crossplane xpkg build --package-root=test-directory --ignore=".tmp/*"`.
Including YAML files that aren't Compositions or CompositeResourceDefinitions, Including YAML files that aren't Compositions or CompositeResourceDefinitions,
including Claims isn't supported. including Claims isn't supported.
{{</hint >}} {{</hint >}}
By default, Crossplane creates a `.xpkg` file of the Configuration name and By default, Crossplane creates a `.xpkg` file of the Configuration name and
a SHA-256 hash of the package contents. a SHA-256 hash of the package contents.
For example, a {{<hover label="xpkgName" line="2">}}Configuration{{</hover>}} For example, a {{<hover label="xpkgName" line="2">}}Configuration{{</hover>}}
named {{<hover label="xpkgName" line="4">}}test-configuration{{</hover>}}. named {{<hover label="xpkgName" line="4">}}test-configuration{{</hover>}}.
The The
Crossplane CLI builds a package named `test-configuration-e8c244f6bf21.xpkg`. Crossplane CLI builds a package named `test-configuration-e8c244f6bf21.xpkg`.

134
content/master/concepts/providers.md
View File

@ -24,7 +24,7 @@ Examples of providers include:
<!-- vale write-good.Passive = NO --> <!-- vale write-good.Passive = NO -->
<!-- "are Managed" isn't passive in this context --> <!-- "are Managed" isn't passive in this context -->
Providers define every external resource they can create in Kubernetes as a Providers define every external resource they can create in Kubernetes as a
Kubernetes API endpoint. Kubernetes API endpoint.
These endpoints are These endpoints are
[_Managed Resources_]({{<ref "managed-resources" >}}). [_Managed Resources_]({{<ref "managed-resources" >}}).
<!-- vale write-good.Passive = YES --> <!-- vale write-good.Passive = YES -->
@ -32,10 +32,10 @@ These endpoints are
## 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
responsible for reconciling the Provider's APIs into the Kubernetes cluster. responsible for reconciling the Provider's APIs into the Kubernetes cluster.
Providers constantly watch the state of the desired managed resources and create Providers constantly watch the state of the desired managed resources and create
any external resources that are missing. any external resources that are missing.
Install a Provider with a Crossplane Install a Provider with a Crossplane
@ -45,7 +45,7 @@ location of the provider package.
{{< hint "important" >}} {{< hint "important" >}}
Beginning with Crossplane version 1.20.0 Crossplane uses the [crossplane-contrib](https://github.com/orgs/crossplane-contrib/packages) GitHub Container Registry at `xpkg.crossplane.io` by default for downloading and Beginning with Crossplane version 1.20.0 Crossplane uses the [crossplane-contrib](https://github.com/orgs/crossplane-contrib/packages) GitHub Container Registry at `xpkg.crossplane.io` by default for downloading and
installing packages. installing packages.
Specify the full domain name with the `package` or change the default Crossplane Specify the full domain name with the `package` or change the default Crossplane
registry with the `--registry` flag on the [Crossplane pod]({{<ref "./pods">}}) registry with the `--registry` flag on the [Crossplane pod]({{<ref "./pods">}})
@ -67,19 +67,19 @@ By default, the Provider pod installs in the same namespace as Crossplane
(`crossplane-system`). (`crossplane-system`).
{{<hint "note" >}} {{<hint "note" >}}
Providers are part of the Providers are part of the
{{<hover label="install" line="1">}}pkg.crossplane.io{{</hover>}} group. {{<hover label="install" line="1">}}pkg.crossplane.io{{</hover>}} group.
The {{<hover label="meta-pkg" line="1">}}meta.pkg.crossplane.io{{</hover>}} The {{<hover label="meta-pkg" line="1">}}meta.pkg.crossplane.io{{</hover>}}
group is for creating Provider packages. group is for creating Provider packages.
Instructions on building Providers are outside of the scope of this Instructions on building Providers are outside of the scope of this
document. document.
Read the Crossplane contributing Read the Crossplane contributing
[Provider Development Guide](https://github.com/crossplane/crossplane/blob/main/contributing/guide-provider-development.md) [Provider Development Guide](https://github.com/crossplane/crossplane/blob/main/contributing/guide-provider-development.md)
for more information. for more information.
For information on the specification of Provider packages read the For information on the specification of Provider packages read the
[Crossplane Provider Package specification](https://github.com/crossplane/crossplane/blob/main/contributing/specifications/xpkg.md#provider-package-requirements). [Crossplane Provider Package specification](https://github.com/crossplane/crossplane/blob/main/contributing/specifications/xpkg.md#provider-package-requirements).
```yaml {label="meta-pkg"} ```yaml {label="meta-pkg"}
@ -113,9 +113,9 @@ crossplane-stable/crossplane \
### Install offline ### Install offline
Installing Crossplane Providers offline requires a local container registry like Installing Crossplane Providers offline requires a local container registry like
[Harbor](https://goharbor.io/) to host Provider packages. Crossplane only [Harbor](https://goharbor.io/) to host Provider packages. Crossplane only
supports installing Provider packages from a container registry. supports installing Provider packages from a container registry.
Crossplane doesn't support installing Provider packages directly from Kubernetes Crossplane doesn't support installing Provider packages directly from Kubernetes
volumes. volumes.
@ -123,11 +123,11 @@ volumes.
### Installation options ### Installation options
Providers support multiple configuration options to change installation related Providers support multiple configuration options to change installation related
settings. settings.
{{<hint "tip" >}} {{<hint "tip" >}}
Crossplane supports installations with image digests instead of tags to get deterministic Crossplane supports installations with image digests instead of tags to get deterministic
and repeatable installations. and repeatable installations.
```yaml {label="digest"} ```yaml {label="digest"}
apiVersion: pkg.crossplane.io/v1 apiVersion: pkg.crossplane.io/v1
@ -145,26 +145,26 @@ Use a {{<hover label="pullpolicy" line="6">}}packagePullPolicy{{</hover>}} to
define when Crossplane should download the Provider package to the local define when Crossplane should download the Provider package to the local
Crossplane package cache. Crossplane package cache.
The `packagePullPolicy` options are: The `packagePullPolicy` options are:
* `IfNotPresent` - (**default**) Only download the package if it isn't in the cache. * `IfNotPresent` - (**default**) Only download the package if it isn't in the cache.
* `Always` - Check for new packages every minute and download any matching * `Always` - Check for new packages every minute and download any matching
package that isn't in the cache. package that isn't in the cache.
* `Never` - Never download the package. Packages are only installed from the * `Never` - Never download the package. Packages are only installed from the
local package cache. local package cache.
{{<hint "tip" >}} {{<hint "tip" >}}
The Crossplane The Crossplane
{{<hover label="pullpolicy" line="6">}}packagePullPolicy{{</hover>}} works {{<hover label="pullpolicy" line="6">}}packagePullPolicy{{</hover>}} works
like the Kubernetes container image like the Kubernetes container image
[image pull policy](https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy). [image pull policy](https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy).
Crossplane supports the use of tags and package digest hashes like Crossplane supports the use of tags and package digest hashes like
Kubernetes images. Kubernetes images.
{{< /hint >}} {{< /hint >}}
For example, to `Always` download a given Provider package use the For example, to `Always` download a given Provider package use the
{{<hover label="pullpolicy" line="6">}}packagePullPolicy: Always{{</hover>}} {{<hover label="pullpolicy" line="6">}}packagePullPolicy: Always{{</hover>}}
configuration. configuration.
```yaml {label="pullpolicy",copy-lines="6"} ```yaml {label="pullpolicy",copy-lines="6"}
apiVersion: pkg.crossplane.io/v1 apiVersion: pkg.crossplane.io/v1
@ -179,20 +179,20 @@ spec:
#### Revision activation policy #### Revision activation policy
The `Active` package revision The `Active` package revision
is the package controller actively reconciling resources. is the package controller actively reconciling resources.
By default Crossplane sets the most recently installed package revision as By default Crossplane sets the most recently installed package revision as
`Active`. `Active`.
Control the Provider upgrade behavior with a Control the Provider upgrade behavior with a
{{<hover label="revision" line="6">}}revisionActivationPolicy{{</hover>}}. {{<hover label="revision" line="6">}}revisionActivationPolicy{{</hover>}}.
The {{<hover label="revision" line="6">}}revisionActivationPolicy{{</hover>}} The {{<hover label="revision" line="6">}}revisionActivationPolicy{{</hover>}}
options are: options are:
* `Automatic` - (**default**) Automatically activate the last installed Provider. * `Automatic` - (**default**) Automatically activate the last installed Provider.
* `Manual` - Don't automatically activate a Provider. * `Manual` - Don't automatically activate a Provider.
For example, to change the upgrade behavior to require manual upgrades, set For example, to change the upgrade behavior to require manual upgrades, set
{{<hover label="revision" line="6">}}revisionActivationPolicy: Manual{{</hover>}}. {{<hover label="revision" line="6">}}revisionActivationPolicy: Manual{{</hover>}}.
```yaml {label="revision"} ```yaml {label="revision"}
@ -207,26 +207,26 @@ spec:
#### Package revision history limit #### Package revision history limit
When Crossplane installs a different version of the same Provider package When Crossplane installs a different version of the same Provider package
Crossplane creates a new _revision_. Crossplane creates a new _revision_.
By default Crossplane maintains one _Inactive_ revision. By default Crossplane maintains one _Inactive_ revision.
{{<hint "note" >}} {{<hint "note" >}}
Read the [Provider upgrade](#upgrade-a-provider) section for Read the [Provider upgrade](#upgrade-a-provider) section for
more information on the use of package revisions. more information on the use of package revisions.
{{< /hint >}} {{< /hint >}}
Change the number of revisions Crossplane maintains with a Provider Package Change the number of revisions Crossplane maintains with a Provider Package
{{<hover label="revHistoryLimit" line="6">}}revisionHistoryLimit{{</hover>}}. {{<hover label="revHistoryLimit" line="6">}}revisionHistoryLimit{{</hover>}}.
The {{<hover label="revHistoryLimit" line="6">}}revisionHistoryLimit{{</hover>}} The {{<hover label="revHistoryLimit" line="6">}}revisionHistoryLimit{{</hover>}}
field is an integer. field is an integer.
The default value is `1`. The default value is `1`.
Disable storing revisions by setting Disable storing revisions by setting
{{<hover label="revHistoryLimit" line="6">}}revisionHistoryLimit{{</hover>}} to `0`. {{<hover label="revHistoryLimit" line="6">}}revisionHistoryLimit{{</hover>}} to `0`.
For example, to change the default setting and store 10 revisions use For example, to change the default setting and store 10 revisions use
{{<hover label="revHistoryLimit" line="6">}}revisionHistoryLimit: 10{{</hover>}}. {{<hover label="revHistoryLimit" line="6">}}revisionHistoryLimit: 10{{</hover>}}.
```yaml {label="revHistoryLimit"} ```yaml {label="revHistoryLimit"}
@ -241,13 +241,13 @@ spec:
#### Install a provider from a private registry #### Install a provider from a private registry
Like Kubernetes uses `imagePullSecrets` to Like Kubernetes uses `imagePullSecrets` to
[install images from private registries](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/), [install images from private registries](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/),
Crossplane uses `packagePullSecrets` to install Provider packages from a private Crossplane uses `packagePullSecrets` to install Provider packages from a private
registry. registry.
Use {{<hover label="pps" line="6">}}packagePullSecrets{{</hover>}} to provide a Use {{<hover label="pps" line="6">}}packagePullSecrets{{</hover>}} to provide a
Kubernetes secret to use for authentication when downloading a Provider package. Kubernetes secret to use for authentication when downloading a Provider package.
{{<hint "important" >}} {{<hint "important" >}}
The Kubernetes secret must be in the same namespace as Crossplane. The Kubernetes secret must be in the same namespace as Crossplane.
@ -257,7 +257,7 @@ The {{<hover label="pps" line="6">}}packagePullSecrets{{</hover>}} is a list of
secrets. secrets.
For example, to use the secret named For example, to use the secret named
{{<hover label="pps" line="6">}}example-secret{{</hover>}} configure a {{<hover label="pps" line="6">}}example-secret{{</hover>}} configure a
{{<hover label="pps" line="6">}}packagePullSecrets{{</hover>}}. {{<hover label="pps" line="6">}}packagePullSecrets{{</hover>}}.
```yaml {label="pps"} ```yaml {label="pps"}
@ -266,25 +266,25 @@ kind: Provider
metadata: metadata:
name: provider-aws name: provider-aws
spec: spec:
packagePullSecrets: packagePullSecrets:
- name: example-secret - name: example-secret
# Removed for brevity # Removed for brevity
``` ```
{{<hint "note" >}} {{<hint "note" >}}
Configured `packagePullSecrets` aren't passed to any Provider package Configured `packagePullSecrets` aren't passed to any Provider package
dependencies. dependencies.
{{< /hint >}} {{< /hint >}}
#### Ignore dependencies #### Ignore dependencies
By default Crossplane installs any [dependencies](#manage-dependencies) listed By default Crossplane installs any [dependencies](#manage-dependencies) listed
in a Provider package. in a Provider package.
Crossplane can ignore a Provider package's dependencies with Crossplane can ignore a Provider package's dependencies with
{{<hover label="pkgDep" line="6" >}}skipDependencyResolution{{</hover>}}. {{<hover label="pkgDep" line="6" >}}skipDependencyResolution{{</hover>}}.
For example, to disable dependency resolution configure For example, to disable dependency resolution configure
{{<hover label="pkgDep" line="6" >}}skipDependencyResolution: true{{</hover>}}. {{<hover label="pkgDep" line="6" >}}skipDependencyResolution: true{{</hover>}}.
```yaml {label="pkgDep"} ```yaml {label="pkgDep"}
@ -308,15 +308,15 @@ 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`, is installed 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, package X must be downgraded to
allow the installation of configuration B which is disabled by default. allow the installation of configuration B which is disabled by default.
For enabling automatic dependency version downgrades, there is a configuration Automatic dependency version downgrades is also an alpha feature that can be
option as a helm value `packageManager.enableAutomaticDependencyDowngrade=true`. enabled with the `--enable-dependency-version-downgrades` flag. Downgrading a
Downgrading a package can cause unexpected behavior, therefore, this package can cause unexpected behavior, therefore, this option is disabled by
option is disabled by default. After enabling this option, the package manager will default. After enabling this option, the package manager will automatically
automatically downgrade a package's dependency version to the maximum valid version downgrade a package's dependency version to the maximum valid version that
that satisfies the constraints. 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.
@ -342,13 +342,13 @@ controllers to reconcile them.
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
version doesn't meet the required version. version doesn't meet the required version.
Crossplane can ignore the required version with Crossplane can ignore the required version with
{{<hover label="xpVer" line="6">}}ignoreCrossplaneConstraints{{</hover>}}. {{<hover label="xpVer" line="6">}}ignoreCrossplaneConstraints{{</hover>}}.
For example, to install a Provider package into an unsupported Crossplane For example, to install a Provider package into an unsupported Crossplane
version, configure version, configure
{{<hover label="xpVer" line="6">}}ignoreCrossplaneConstraints: true{{</hover>}}. {{<hover label="xpVer" line="6">}}ignoreCrossplaneConstraints: true{{</hover>}}.
```yaml {label="xpVer"} ```yaml {label="xpVer"}
@ -364,10 +364,10 @@ spec:
### Manage dependencies ### Manage dependencies
Providers packages may include dependencies on other packages including Providers packages may include dependencies on other packages including
Configurations or other Providers. Configurations or other Providers.
If Crossplane can't meet the dependencies of a Provider package the Provider If Crossplane can't meet the dependencies of a Provider package the Provider
reports `HEALTHY` as `False`. reports `HEALTHY` as `False`.
For example, this installation of the Getting Started Configuration is For example, this installation of the Getting Started Configuration is
`HEALTHY: False`. `HEALTHY: False`.
@ -404,9 +404,9 @@ Events:
Warning LintPackage 41s (x3 over 47s) packages/providerrevision.pkg.crossplane.io incompatible Crossplane version: package isn't compatible with Crossplane version (v1.10.0) Warning LintPackage 41s (x3 over 47s) packages/providerrevision.pkg.crossplane.io incompatible Crossplane version: package isn't compatible with Crossplane version (v1.10.0)
``` ```
The {{<hover label="depend" line="17">}}Events{{</hover>}} show a The {{<hover label="depend" line="17">}}Events{{</hover>}} show a
{{<hover label="depend" line="20">}}Warning{{</hover>}} with a message that the {{<hover label="depend" line="20">}}Warning{{</hover>}} with a message that the
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
@ -420,7 +420,7 @@ Crossplane installs the new image and creates a new `ProviderRevision`.
The `ProviderRevision` allows Crossplane to store deprecated Provider CRDs The `ProviderRevision` allows Crossplane to store deprecated Provider CRDs
without removing them until you decide. without removing them until you decide.
View the `ProviderRevisions` with View the `ProviderRevisions` with
{{<hover label="getPR" line="1">}}kubectl get providerrevisions{{</hover>}} {{<hover label="getPR" line="1">}}kubectl get providerrevisions{{</hover>}}
```shell {label="getPR",copy-lines="1"} ```shell {label="getPR",copy-lines="1"}
@ -436,14 +436,14 @@ By default Crossplane keeps a single
{{<hover label="getPR" line="5">}}Inactive{{</hover>}} Provider. {{<hover label="getPR" line="5">}}Inactive{{</hover>}} Provider.
Read the [revision history limit](#package-revision-history-limit) section to Read the [revision history limit](#package-revision-history-limit) section to
change the default value. 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`.
{{< hint "warning" >}} {{< hint "warning" >}}
@ -495,7 +495,7 @@ The Crossplane community has more
### Provider conditions ### Provider conditions
Crossplane uses a standard set of `Conditions` for Providers. Crossplane uses a standard set of `Conditions` for Providers.
View the conditions of a provider under their `Status` with View the conditions of a provider under their `Status` with
`kubectl describe provider`. `kubectl describe provider`.
@ -622,7 +622,7 @@ Providers have two different types of configurations:
an external provider. For example, cloud provider authentication. an external provider. For example, cloud provider authentication.
{{<hint "important" >}} {{<hint "important" >}}
Apply `ControllerConfig` objects to Providers. Apply `ControllerConfig` objects to Providers.
Apply `ProviderConfig` objects to managed resources. Apply `ProviderConfig` objects to managed resources.
{{< /hint >}} {{< /hint >}}