Configuration Packages

On this page

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

Configuration packages make your Crossplane configuration fully portable.

Important

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.

Important

Beginning with Crossplane version 1.20.0 Crossplane uses the crossplane-contrib Container Registry at xpkg.crossplane.io 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 Getting Started Configuration,

1apiVersion: pkg.crossplane.io/v1
2kind: Configuration
3metadata:
4  name: configuration-quickstart
5spec:
6  package: xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0

Tip

Crossplane supports installations with image digests instead of tags to get deterministic and repeatable installations.

1apiVersion: pkg.crossplane.io/v1
2kind: Configuration
3metadata:
4  name: configuration-quickstart
5spec:
6  package: xpkg.crossplane.io/crossplane-contrib/configuration-quickstart@sha256:ef9795d146190637351a5c5848e0bab5e0c190fec7780f6c426fbffa0cb68358

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 Getting Started Configuration,

1helm install crossplane \
2crossplane-stable/crossplane \
3--namespace crossplane-system \
4--create-namespace \
5--set configuration.packages='{xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0}'

Install offline

Installing Crossplane packages offline requires a local container registry, such as 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          xpkg.crossplane.io/crossplane-contrib/platform-ref-aws:v0.5.0   Active     2           2               46s
4platform-ref-aws-3ac761211893   True      1          xpkg.crossplane.io/crossplane-contrib/platform-ref-aws:v0.4.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.

1apiVersion: pkg.crossplane.io/v1
2kind: Configuration
3metadata:
4  name: platform-ref-aws
5spec:
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.

Tip

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.

1apiVersion: pkg.crossplane.io/v1
2kind: Configuration
3metadata:
4  name: platform-ref-aws
5spec:
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.

1apiVersion: pkg.crossplane.io/v1
2kind: Configuration
3metadata:
4  name: platform-ref-aws
5spec:
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.

Important

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.

1apiVersion: pkg.crossplane.io/v1
2kind: Configuration
3metadata:
4  name: platform-ref-aws
5spec:
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.

Warning

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.

1apiVersion: pkg.crossplane.io/v1
2kind: Configuration
3metadata:
4  name: platform-ref-aws
5spec:
6  skipDependencyResolution: true
7# Removed for brevity

Automatically update dependency versions

Crossplane can automatically upgrade a package’s dependency version to the minimum valid version that satisfies all the constraints. It’s an alpha feature that requires enabling with the --enable-dependency-version-upgrades flag.

In some cases, dependency version downgrade is required for proceeding with 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 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. Since version v2.0.0satisfies both conditions, package X must be downgraded to allow the installation of configuration B which is disabled by default.

For enabling automatic dependency version downgrades, there is a configuration option as a helm value packageManager.enableAutomaticDependencyDowngrade=true. Downgrading a package can cause unexpected behavior, therefore, this option is disabled by default. After enabling this option, the package manager will automatically downgrade a package’s dependency version to the maximum valid version that satisfies the constraints.

Note

This configuration requires the --enable-dependency-version-upgrades flag. Please check the configuration options and feature flags are available in the Crossplane Install section for more details.

Important

Enabling automatic dependency downgrades may have unintended consequences, such as:

CRDs missing in the downgraded version, possibly leaving orphaned MRs without controllers to reconcile them.
Loss of data if downgraded CRD versions omit fields that were set before.
Changes in the CRD storage version, which may prevent package version update.

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.

1apiVersion: pkg.crossplane.io/v1
2kind: Configuration
3metadata:
4  name: platform-ref-aws
5spec:
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      xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0   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 Getting Started Configuration is HEALTHY: False.

1kubectl get configuration
2NAME               INSTALLED   HEALTHY   PACKAGE                                           AGE
3platform-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 kubectl describe configurationrevisions.

 1kubectl describe configurationrevision
 2Name:         platform-ref-aws-a30ad655c769
 3API Version:  pkg.crossplane.io/v1
 4Kind:         ConfigurationRevision
 5# Removed for brevity
 6Spec:
 7  Desired State:                  Active
 8  Image:                          xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0
 9  Revision:                       1
10Status:
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:
18Events:
19  Type     Reason       Age                From                                              Message
20  ----     ------       ----               ----                                              -------
21  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 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.

Important

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.

Important

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

Configuration package uses the meta.pkg.crossplane.io 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.

Note

Defining the crossplane object or required versions is optional.

 1$ cat crossplane.yaml
 2apiVersion: meta.pkg.crossplane.io/v1alpha1
 3kind: Configuration
 4metadata:
 5  name: test-configuration
 6spec:
 7  dependsOn:
 8    - apiVersion: pkg.crossplane.io/v1
 9      kind: Provider
10      package: xpkg.crossplane.io/crossplane-contrib/provider-aws
11      version: ">=v0.36.0"
12  crossplane:
13    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.

Important

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 a .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.

1apiVersion: meta.pkg.crossplane.io/v1alpha1
2kind: Configuration
3metadata:
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 ./
2test-directory
3test-package.xpkg