Configuration Packages

This document is for an unreleased version of Crossplane.

This document applies to the Crossplane master branch and not to the latest release v1.16.

A Configuration package is an OCI container images containing a collection of Compositions, Composite Resource Definitions and any required Providers or Functions.

Configuration packages make your Crossplane configuration fully portable.


Crossplane Providers and Functions are also Crossplane packages.

This document describes how to install and manage configuration packages.

Refer to the Provider and Composition Functions chapters for details on their usage of packages.

Install a Configuration

Install a Configuration with a Crossplane Configuration object by setting the spec.package value to the location of the configuration package.


Beginning with Crossplane version 1.15.0 Crossplane uses the Upbound Marketplace Crossplane package registry at by default for downloading and installing packages.

Specify the full domain name with the package or change the default Crossplane registry with the --registry flag on the Crossplane pod

For example to install the Upbound AWS reference platform,

2kind: Configuration
4  name: platform-ref-aws
6  package:

Crossplane installs the Compositions, Composite Resource Definitions and Providers listed in the Configuration.

Install with Helm

Crossplane supports installing Configurations during an initial Crossplane installation with the Crossplane Helm chart.

Use the --set configuration.packages argument with helm install.

For example, to install the Upbound AWS reference platform,

1helm install crossplane \
2crossplane-stable/crossplane \
3--namespace crossplane-system \
4--create-namespace \
5--set configuration.packages='{}'

Install offline

Installing Crossplane packages offline requires a local container registry like Harbor to host the packages. Crossplane only supports installing packages from a container registry.

Crossplane doesn’t support installing packages directly from Kubernetes volumes.

Installation options

Configurations support multiple options to change configuration package related settings.

Configuration revisions

When installing a newer version of an existing Configuration Crossplane creates a new configuration revision.

View the configuration revisions with kubectl get configurationrevisions.

1kubectl get configurationrevisions
2NAME                            HEALTHY   REVISION   IMAGE                                             STATE      DEP-FOUND   DEP-INSTALLED   AGE
3platform-ref-aws-1735d56cd88d   True      2   Active     2           2               46s
4platform-ref-aws-3ac761211893   True      1   Inactive                               5m13s

Only a single revision is active at a time. The active revision determines the available resources, including Compositions and Composite Resource Definitions.

By default Crossplane keeps only a single Inactive revision.

Change the number of revisions Crossplane maintains with a Configuration package revisionHistoryLimit.

The revisionHistoryLimit field is an integer.
The default value is 1.
Disable storing revisions by setting revisionHistoryLimit to 0.

For example, to change the default setting and store 10 revisions use revisionHistoryLimit: 10.

2kind: Configuration
4  name: platform-ref-aws
6  revisionHistoryLimit: 10
7# Removed for brevity

Configuration package pull policy

Use a packagePullPolicy to define when Crossplane should download the Configuration package to the local Crossplane package cache.

The packagePullPolicy options are:

  • IfNotPresent - (default) Only download the package if it isn’t in the cache.
  • Always - Check for new packages every minute and download any matching package that isn’t in the cache.
  • Never - Never download the package. Packages are only installed from the local package cache.

The Crossplane packagePullPolicy works like the Kubernetes container image image pull policy.

Crossplane supports the use of tags and package digest hashes like Kubernetes images.

For example, to Always download a given Configuration package use the packagePullPolicy: Always configuration.

2kind: Configuration
4  name: platform-ref-aws
6  packagePullPolicy: Always
7# Removed for brevity

Revision activation policy

The Active package revision is the package controller actively reconciling resources.

By default Crossplane sets the most recently installed package revision as Active.

Control the Configuration upgrade behavior with a revisionActivationPolicy.

The revisionActivationPolicy options are:

  • Automatic - (default) Automatically activate the last installed configuration.
  • Manual - Don’t automatically activate a configuration.

For example, to change the upgrade behavior to require manual upgrades, set revisionActivationPolicy: Manual.

2kind: Configuration
4  name: platform-ref-aws
6  revisionActivationPolicy: Manual
7# Removed for brevity

Install a Configuration from a private registry

Like Kubernetes uses imagePullSecrets to install images from private registries, Crossplane uses packagePullSecrets to install Configuration packages from a private registry.

Use packagePullSecrets to provide a Kubernetes secret to use for authentication when downloading a Configuration package.

The Kubernetes secret must be in the same namespace as Crossplane.

The packagePullSecrets is a list of secrets.

For example, to use the secret named example-secret configure a packagePullSecrets.

2kind: Configuration
4  name: platform-ref-aws
6  packagePullSecrets: 
7    - name: example-secret
8# Removed for brevity

Ignore dependencies

By default Crossplane installs any dependencies listed in a Configuration package.

Crossplane can ignore a Configuration package’s dependencies with skipDependencyResolution.


Most Configurations include dependencies for the required Providers.

If a Configuration ignores dependencies, the required Providers must be manually installed.

For example, to disable dependency resolution configure skipDependencyResolution: true.

2kind: Configuration
4  name: platform-ref-aws
6  skipDependencyResolution: true
7# Removed for brevity

Ignore Crossplane version requirements

A Configuration package may require a specific or minimum Crossplane version before installing. By default, Crossplane doesn’t install a Configuration if the Crossplane version doesn’t meet the required version.

Crossplane can ignore the required version with ignoreCrossplaneConstraints.

For example, to install a Configuration package into an unsupported Crossplane version, configure ignoreCrossplaneConstraints: true.

2kind: Configuration
4  name: platform-ref-aws
6  ignoreCrossplaneConstraints: true
7# Removed for brevity

Verify a Configuration

Verify a Configuration with kubectl get configuration.

A working configuration reports Installed and Healthy as True.

1kubectl get configuration
2NAME               INSTALLED   HEALTHY   PACKAGE                                           AGE
3platform-ref-aws   True        True   54s

Manage dependencies

Configuration packages may include dependencies on other packages including Functions, Providers or other Configurations.

If Crossplane can’t meet the dependencies of a Configuration the Configuration reports HEALTHY as False.

For example, this installation of the Upbound AWS reference platform is HEALTHY: False.

1kubectl get configuration
2NAME               INSTALLED   HEALTHY   PACKAGE                                           AGE
3platform-ref-aws   True        False   71s

To see more information on why the Configuration isn’t HEALTHY use kubectl describe configurationrevisions.

 1kubectl describe configurationrevision
 2Name:         platform-ref-aws-a30ad655c769
 3API Version:
 4Kind:         ConfigurationRevision
 5# Removed for brevity
 7  Desired State:                  Active
 8  Image:                
 9  Revision:                       1
11  Conditions:
12    Last Transition Time:  2023-10-06T20:08:14Z
13    Reason:                UnhealthyPackageRevision
14    Status:                False
15    Type:                  Healthy
16  Controller Ref:
17    Name:
19  Type     Reason       Age                From                                              Message
20  ----     ------       ----               ----                                              -------
21  Warning  LintPackage  29s (x2 over 29s)  packages/  incompatible Crossplane version: package is not compatible with Crossplane version (v1.12.0)

The Events show a Warning with a message that the current version of Crossplane doesn’t meet the Configuration package requirements.

Create a Configuration

Crossplane Configuration packages are OCI container images containing one or more YAML files.


Configuration packages are fully OCI compliant. Any tool that builds OCI images can build Configuration packages.

It’s strongly recommended to use the Crossplane command-line tool to provide error checking and formatting to Crossplane package builds.

Read the Crossplane package specification for package requirements when building packages with third-party tools.

A Configuration package requires a crossplane.yaml file and may include Composition and CompositeResourceDefinition files.

The crossplane.yaml file

To build a Configuration package using the Crossplane CLI, create a file named crossplane.yaml.
The crossplane.yaml file defines the requirements and name of the Configuration.

The Crossplane CLI only supports a file named crossplane.yaml.

Configuration package uses the Crossplane API group.

Specify any other Configurations, Functions or Providers in the dependsOn list.
Optionally, you can require a specific or minimum package version with the version option.

You can also define a specific or minimum version of Crossplane for this Configuration with the crossplane.version option.

Defining the crossplane object or required versions is optional.
 1$ cat crossplane.yaml
 3kind: Configuration
 5  name: test-configuration
 7  dependsOn:
 8    - provider:
 9      version: ">=v0.36.0"
10  crossplane:
11    version: ">=v1.12.1-0"

Build the package

Create the package using the Crossplane CLI command crossplane xpkg build --package-root=<directory>.

Where the <directory> is the directory containing the crossplane.yaml file and any Composition or CompositeResourceDefinition YAML files.

The CLI recursively searches for .yml or .yaml files in the directory to include in the package.


You must ignore any other YAML files with --ignore=<file_list>.
For example, crossplane xpkg build --package-root=test-directory --ignore=".tmp/*".

Including YAML files that aren’t Compositions or CompositeResourceDefinitions, including Claims isn’t supported.

By default, Crossplane creates an .xpkg file of the Configuration name and a SHA-256 hash of the package contents.

For example, a Configuration named test-configuration.
The Crossplane CLI builds a package named test-configuration-e8c244f6bf21.xpkg.

2kind: Configuration
4  name: test-configuration
5# Removed for brevity

Specify the output file with --package-file=<filename>.xpkg option.

For example, to build a package from a directory named test-directory and generate a package named test-package.xpkg in the current working directory, use the command:

1crossplane xpkg build --package-root=test-directory --package-file=test-package.xpkg
1ls -1 ./