Crossplane Docs · v1.20 · Configuration Packages (original) (raw)

This document is for an older version of Crossplane.

This document applies to Crossplane v1.20 and not to the latest release v2.3.

A Configuration package is anOCI container image containing a collection ofCompositions,Composite Resource Definitionsand any required Providers orFunctions.

Configuration packages make your Crossplane configuration fully portable.

Install a Configuration

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

Beginning with Crossplane version 1.20.0 Crossplane uses the crossplane-contrib GitHub 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 theGetting 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

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.packagesargument 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 asHarbor 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 withkubectl 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 packagerevisionHistoryLimit.

The revisionHistoryLimitfield is an integer. The default value is 1. Disable storing revisions by settingrevisionHistoryLimit to 0.

For example, to change the default setting and store 10 revisions userevisionHistoryLimit: 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.

The CrossplanepackagePullPolicy works like the Kubernetes container imageimage 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 thepackagePullPolicy: Alwaysconfiguration.

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

Control the Configuration upgrade behavior with arevisionActivationPolicy.

The revisionActivationPolicyoptions 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, setrevisionActivationPolicy: 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 toinstall 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 namedexample-secret configure apackagePullSecrets.

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

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 configureskipDependencyResolution: 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.

Sometimes, Crossplane requires dependency version downgrade 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.0 satisfies both conditions, Crossplane must downgrade package X to allow the installation of configuration B, which Crossplane disables 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, so this Crossplane disables this option by default. After enabling this option, the package manager automatically downgrades a package’s dependency version to the maximum valid version that satisfies the constraints.

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 you 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 withignoreCrossplaneConstraints.

For example, to install a Configuration package into an unsupported Crossplane version, configureignoreCrossplaneConstraints: 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 withkubectl 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 isHEALTHY: 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 usekubectl 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 aWarning with a message that the current version of Crossplane doesn’t meet the Configuration package requirements.

Create a Configuration

Crossplane Configuration packages areOCI 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 theCrossplane package specificationfor 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 namedcrossplane.yaml. Thecrossplane.yamlfile defines the requirements and name of the Configuration.

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

Configuration package uses themeta.pkg.crossplane.ioCrossplane API group.

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

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

Defining the crossplane object or required versions is optional.

 1$ cat crossplane.yaml
 2apiVersion: meta.pkg.crossplane.io/v1
 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 theCrossplane CLI commandcrossplane 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 a .xpkg file of the Configuration name and a SHA-256 hash of the package contents.

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

1apiVersion: meta.pkg.crossplane.io/v1
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