crossplane
/
docs
mirror of https://github.com/crossplane/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
docs/content/v1.20/concepts/packages.md

18 KiB
Raw Permalink Blame History

title description altTitle weight
Configuration Packages Packages combine multiple Crossplane resources into a single, portable, OCI image. Crossplane Packages 200

A Configuration package is an OCI container image containing a collection of [Compositions]({{<ref "./compositions" >}}), [Composite Resource Definitions]({{<ref "./composite-resource-definitions" >}}) and any required [Providers]({{<ref "./providers">}}) or [Functions]({{<ref "./compositions" >}}).

Configuration packages make your Crossplane configuration fully portable.

{{<hint "important" >}} Crossplane [Providers]({{<ref "./providers">}}) and [Functions]({{<ref "./compositions">}}) are also Crossplane packages.

This document describes how to install and manage configuration packages.

Refer to the [Provider]({{<ref "./providers">}}) and [Composition Functions]({{<ref "./compositions">}}) chapters for details on their usage of packages. {{< /hint >}}

Install a Configuration

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

{{< hint "important" >}} 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]({{<ref "./pods">}}) {{< /hint >}}

For example to install the Getting Started Configuration,

apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: configuration-quickstart
spec:
  package: xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0

{{<hint "tip" >}} Crossplane supports installations with image digests instead of tags to get deterministic and repeatable installations.

apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: configuration-quickstart
spec:
  package: xpkg.crossplane.io/crossplane-contrib/configuration-quickstart@sha256:ef9795d146190637351a5c5848e0bab5e0c190fec7780f6c426fbffa0cb68358

{{< /hint >}}

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,

helm install crossplane \
crossplane-stable/crossplane \
--namespace crossplane-system \
--create-namespace \
--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{{}}.

kubectl get configurationrevisions
NAME                            HEALTHY   REVISION   IMAGE                                             STATE      DEP-FOUND   DEP-INSTALLED   AGE
platform-ref-aws-1735d56cd88d   True      2          xpkg.crossplane.io/crossplane-contrib/platform-ref-aws:v0.5.0   Active     2           2               46s
platform-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{{}}.

apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: platform-ref-aws
spec:
  revisionHistoryLimit: 10
# 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.

{{<hint "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. {{< /hint >}}

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

apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: platform-ref-aws
spec:
  packagePullPolicy: Always
# 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{{}}.

apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: platform-ref-aws
spec:
  revisionActivationPolicy: Manual
# 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.

{{<hint "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{{}}.

apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: platform-ref-aws
spec:
  packagePullSecrets:
    - name: example-secret
# 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{{}}.

{{< hint "warning" >}} Most Configurations include dependencies for the required Providers.

If a Configuration ignores dependencies, the required Providers must be manually installed. {{< /hint >}}

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

apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: platform-ref-aws
spec:
  skipDependencyResolution: true
# 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.0 satisfies both conditions, package X must be downgraded to allow the installation of configuration B which is disabled by default.

Automatic dependency version downgrades is also an alpha feature that can be enabled with the --enable-dependency-version-downgrades flag. 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.

{{<hint "note" >}} This configuration requires the --enable-dependency-version-upgrades flag. Please check the [configuration options]({{<ref "../software/install#customize-the-crossplane-helm-chart">}}) and [feature flags]({{<ref "../software/install#feature-flags">}}) are available in the [Crossplane Install]({{<ref "../software/install">}}) section for more details. {{}}

{{<hint "important" >}} Enabling automatic dependency downgrades may have unintended consequences, such as:

  1. CRDs missing in the downgraded version, possibly leaving orphaned MRs without controllers to reconcile them.
  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. {{}}

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{{}}.

apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: platform-ref-aws
spec:
  ignoreCrossplaneConstraints: true
# Removed for brevity

Verify a Configuration

Verify a Configuration with {{}}kubectl get configuration{{}}.

A working configuration reports Installed and Healthy as True.

kubectl get configuration
NAME               INSTALLED   HEALTHY   PACKAGE                                           AGE
platform-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.

kubectl get configuration
NAME               INSTALLED   HEALTHY   PACKAGE                                           AGE
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 {{}}kubectl describe configurationrevisions{{}}.

kubectl describe configurationrevision
Name:         platform-ref-aws-a30ad655c769
API Version:  pkg.crossplane.io/v1
Kind:         ConfigurationRevision
# Removed for brevity
Spec:
  Desired State:                  Active
  Image:                          xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0
  Revision:                       1
Status:
  Conditions:
    Last Transition Time:  2023-10-06T20:08:14Z
    Reason:                UnhealthyPackageRevision
    Status:                False
    Type:                  Healthy
  Controller Ref:
    Name:
Events:
  Type     Reason       Age                From                                              Message
  ----     ------       ----               ----                                              -------
  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.

{{<hint "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.

{{<hint "important" >}} The Crossplane CLI only supports a file named crossplane.yaml. {{< /hint >}}

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.

{{<hint "note" >}} Defining the {{}}crossplane{{}} object or required versions is optional. {{< /hint >}}

$ cat crossplane.yaml
apiVersion: meta.pkg.crossplane.io/v1alpha1
kind: Configuration
metadata:
  name: test-configuration
spec:
  dependsOn:
    - apiVersion: pkg.crossplane.io/v1
      kind: Provider
      package: xpkg.crossplane.io/crossplane-contrib/provider-aws
      version: ">=v0.36.0"
  crossplane:
    version: ">=v1.12.1-0"

Build the package

Create the package using the [Crossplane CLI]({{<ref "../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.

{{<hint "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.

apiVersion: meta.pkg.crossplane.io/v1alpha1
kind: Configuration
metadata:
  name: test-configuration
# 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:

crossplane xpkg build --package-root=test-directory --package-file=test-package.xpkg

ls -1 ./
test-directory
test-package.xpkg