Providers

Providers enable Crossplane to provision infrastructure on an external service. Providers create new Kubernetes APIs and map them to external APIs.

Providers are responsible for all aspects of connecting to non-Kubernetes resources. This includes authentication, making external API calls and providing Kubernetes Controller logic for any external resources.

Examples of providers include:

• Provider AWS
• Provider Azure
• Provider GCP
• Provider Kubernetes

Providers define every external resource they can create in Kubernetes as a Kubernetes API endpoint.
These endpoints are Managed Resources.

Install a Provider

Installing a provider creates new Kubernetes resources representing the Provider’s APIs. Installing a provider also creates a Provider pod that’s responsible for reconciling the Provider’s APIs into the Kubernetes cluster. Providers constantly watch the state of the desired managed resources and create any external resources that are missing.

Install a Provider with a Crossplane Provider object setting the spec.package value to the location of the provider package.

For example, to install the AWS Community Provider,

1apiVersion: pkg.crossplane.io/v1
2kind: Provider
3metadata:
4  name: provider-aws
5spec:
6  package: xpkg.crossplane.io/crossplane-contrib/provider-aws:v0.39.0

By default, the Provider pod installs in the same namespace as Crossplane (crossplane-system).

1apiVersion: meta.pkg.crossplane.io/v1
2kind: Provider
3metadata:
4  name: provider-aws
5spec:
6# Removed for brevity

Install with Helm

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

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

For example, to install the AWS Community Provider,

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

Install offline

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

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

Installation options

Providers support multiple configuration options to change installation related settings.

1apiVersion: pkg.crossplane.io/v1
2kind: Provider
3metadata:
4  name: provider-aws
5spec:
6  package: xpkg.crossplane.io/crossplane-contrib/provider-aws@sha256:ee6bece46dbb54cc3f0233961f5baac317fa4e4a81b41198bdc72fc472d113d0

Provider pull policy

Use a packagePullPolicy to define when Crossplane should download the Provider 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.

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

1apiVersion: pkg.crossplane.io/v1
2kind: Provider
3metadata:
4  name: provider-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 Provider upgrade behavior with a revisionActivationPolicy.

The revisionActivationPolicy options are:

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

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

1apiVersion: pkg.crossplane.io/v1
2kind: Provider
3metadata:
4  name: provider-aws
5spec:
6  revisionActivationPolicy: Manual
7# Removed for brevity

Package revision history limit

When Crossplane installs a different version of the same Provider package Crossplane creates a new revision.

By default Crossplane maintains one Inactive revision.

Change the number of revisions Crossplane maintains with a Provider 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: Provider
3metadata:
4  name: provider-aws
5spec:
6  revisionHistoryLimit: 10
7# Removed for brevity

Install a provider from a private registry

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

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

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: Provider
3metadata:
4  name: provider-aws
5spec:
6  packagePullSecrets: 
7    - name: example-secret
8# Removed for brevity

Ignore dependencies

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

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

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

1apiVersion: pkg.crossplane.io/v1
2kind: Provider
3metadata:
4  name: provider-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.

Ignore Crossplane version requirements

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

Crossplane can ignore the required version with ignoreCrossplaneConstraints.

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

1apiVersion: pkg.crossplane.io/v1
2kind: Provider
3metadata:
4  name: provider-aws
5spec:
6  ignoreCrossplaneConstraints: true
7# Removed for brevity

Manage dependencies

Providers packages may include dependencies on other packages including Configurations or other Providers.

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

For example, this installation of the Getting Started Configuration is HEALTHY: False.

1kubectl get providers
2NAME              INSTALLED   HEALTHY   PACKAGE                                           AGE
3provider-aws-s3   True        False     xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1   12s

To see more information on why the Provider isn’t HEALTHY use kubectl describe providerrevisions.

 1kubectl describe providerrevisions
 2Name:         provider-aws-s3-92206523fff4
 3API Version:  pkg.crossplane.io/v1
 4Kind:         ProviderRevision
 5Spec:
 6  Desired State:                  Active
 7  Image:                          xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1
 8  Revision:                       1
 9Status:
10  Conditions:
11    Last Transition Time:  2023-10-10T21:06:39Z
12    Reason:                UnhealthyPackageRevision
13    Status:                False
14    Type:                  Healthy
15  Controller Ref:
16    Name:
17Events:
18  Type     Reason             Age                From                                         Message
19  ----     ------             ----               ----                                         -------
20  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 Events show a Warning with a message that the current version of Crossplane doesn’t meet the Configuration package requirements.

Upgrade a Provider

To upgrade an existing Provider edit the installed Provider Package by either applying a new Provider manifest or with kubectl edit providers.

Update the version number in the Provider’s spec.package and apply the change. Crossplane installs the new image and creates a new ProviderRevision.

The ProviderRevision allows Crossplane to store deprecated Provider CRDs without removing them until you decide.

View the ProviderRevisions with kubectl get providerrevisions

1kubectl get providerrevisions
2NAME                                       HEALTHY   REVISION   IMAGE                                                    STATE      DEP-FOUND   DEP-INSTALLED   AGE
3provider-aws-s3-dbc7f981d81f               True      1          xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1           Active     1           1               10d
4provider-nop-552a394a8acc                  True      2          xpkg.crossplane.io/crossplane-contrib/provider-nop:v0.3.0   Active                                 11d
5provider-nop-7e62d2a1a709                  True      1          xpkg.crossplane.io/crossplane-contrib/provider-nop:v0.2.0   Inactive                               13d
6crossplane-contrib-provider-family-aws-710d8cfe9f53   True      1          xpkg.crossplane.io/crossplane-contrib/provider-family-aws:v1.21.1        Active                                 10d

By default Crossplane keeps a single Inactive Provider.

Read the revision history limit section to change the default value.

Only a single revision of a Provider is Active at a time.

Remove a Provider

Remove a Provider by deleting the Provider object with kubectl delete provider.

Verify a Provider

Providers install their own APIs representing the managed resources they support. Providers may also create Deployments, Service Accounts or RBAC configuration.

View the status of a Provider with

kubectl get providers

During the install a Provider report INSTALLED as True and HEALTHY as Unknown.

1kubectl get providers
2NAME                              INSTALLED   HEALTHY   PACKAGE                                                   AGE
3crossplane-contrib-provider-aws   True        Unknown   xpkg.crossplane.io/crossplane-contrib/provider-aws:v0.39.0   63s

After the Provider install completes and it’s ready for use the HEALTHY status reports True.

1kubectl get providers
2NAME                              INSTALLED   HEALTHY   PACKAGE                                                   AGE
3crossplane-contrib-provider-aws   True        True      xpkg.crossplane.io/crossplane-contrib/provider-aws:v0.39.0   88s

Provider conditions

Crossplane uses a standard set of Conditions for Providers.
View the conditions of a provider under their Status with kubectl describe provider.

 1kubectl describe provider
 2Name:         my-provider
 3API Version:  pkg.crossplane.io/v1
 4Kind:         Provider
 5# Removed for brevity
 6Status:
 7  Conditions:
 8    Reason:      HealthyPackageRevision
 9    Status:      True
10    Type:        Healthy
11    Reason:      ActivePackageRevision
12    Status:      True
13    Type:        Installed
14# Removed for brevity

Types

Provider Conditions support two Types:

• Type: Installed - the Provider package installed but isn’t ready for use.
• Type: Healthy - The Provider package is ready to use.

Reasons

Each Reason relates to a specific Type and Status. Crossplane uses the following Reasons for Provider Conditions.

InactivePackageRevision

Reason: InactivePackageRevision indicates the Provider Package is using an inactive Provider Package Revision.

1Type: Installed
2Status: False
3Reason: InactivePackageRevision

ActivePackageRevision

The Provider Package is the current Package Revision, but Crossplane hasn’t finished installing the Package Revision yet.

1Type: Installed
2Status: True
3Reason: ActivePackageRevision

HealthyPackageRevision

The Provider is fully installed and ready to use.

1Type: Healthy
2Status: True
3Reason: HealthyPackageRevision

UnhealthyPackageRevision

There was an error installing the Provider Package Revision, preventing Crossplane from installing the Provider Package.

1Type: Healthy
2Status: False
3Reason: UnhealthyPackageRevision

UnknownPackageRevisionHealth

The status of the Provider Package Revision is Unknown. The Provider Package Revision may be installing or has an issue.

1Type: Healthy
2Status: Unknown
3Reason: UnknownPackageRevisionHealth

Configure a Provider

Providers have two different types of configurations:

• Controller configurations that change the settings of the Provider pod running inside the Kubernetes cluster. For example, setting a toleration on the Provider pod.

• Provider configurations that change settings used when communicating with an external provider. For example, cloud provider authentication.

Controller configuration

Applying a Crossplane ControllerConfig to a Provider changes the settings of the Provider’s pod. The Crossplane ControllerConfig schema defines the supported set of ControllerConfig settings.

The most common use case for ControllerConfigs are providing args to a Provider’s pod enabling optional services. For example, enabling external secret stores for a Provider.

Each Provider determines their supported set of args.

Runtime configuration

Runtime configuration is a generalized mechanism for configuring the runtime for Crossplane packages with a runtime, namely Providers and Functions. It replaces the deprecated ControllerConfig type and is available in v1.14+.

With its default configuration, Crossplane uses Kubernetes Deployments to deploy runtime for packages, more specifically, a controller for a Provider or a gRPC server for a Function. It’s possible to configure the runtime manifest by applying a DeploymentRuntimeConfig and referencing it in the Provider or Function object.

As an example, to enable the external secret stores alpha feature for a Provider by adding the --enable-external-secret-stores argument to the controller, one can apply the following:

 1apiVersion: pkg.crossplane.io/v1
 2kind: Provider
 3metadata:
 4  name: provider-gcp-iam
 5spec:
 6  package: xpkg.crossplane.io/crossplane-contrib/provider-gcp-iam:v1
 7  runtimeConfigRef:
 8    name: enable-ess
 9---
10apiVersion: pkg.crossplane.io/v1beta1
11kind: DeploymentRuntimeConfig
12metadata:
13  name: enable-ess
14spec:
15  deploymentTemplate:
16    spec:
17      selector: {}
18      template:
19        spec:
20          containers:
21            - name: package-runtime
22              args:
23                - --enable-external-secret-stores

Please note that the packages manager uses package-runtime as the name of the runtime container. When you use a different container name, the package manager introduces it as a sidecar container instead of modifying the package runtime container.

The package manager is opinionated about some fields to ensure

the runtime is working and overlay them on top of the values in the runtime configuration. For example, it defaults the replica count to 1 if not set and overrides the label selectors to make sure the Deployment and Service match. It also injects any necessary environment variables, ports as well as volumes and volume mounts.

The Provider or Functions’s spec.runtimeConfigRef.name field defaults to value default, which means Crossplane uses the default runtime configuration if not specified. Crossplane ensures there is always a default runtime

configuration in the cluster, but won’t change it if it already exists. This

allows users to customize the default runtime configuration to their needs.

 1apiVersion: pkg.crossplane.io/v1beta1
 2kind: DeploymentRuntimeConfig
 3metadata:
 4  name: multi-replicas
 5spec:
 6  deploymentTemplate:
 7    spec:
 8      replicas: 2
 9      selector: {}
10      template: {}

Configuring runtime deployment spec

Using the Deployment spec provided in the DeploymentRuntimeConfig as a base, the package manager builds the Deployment spec for the package runtime with the following rules:

• Injects the package runtime container as the first container in the containers array, with name package-runtime.
• If not provided, defaults with the following:
  • spec.replicas as 1.
  • Image pull policy as IfNotPresent.
  • Pod Security Context as:

    1runAsNonRoot: true
    2runAsUser: 2000
    3runAsGroup: 2000
    
  • Security Context for the runtime container as:

    1allowPrivilegeEscalation: false
    2privileged: false
    3runAsGroup: 2000
    4runAsNonRoot: true
    5runAsUser: 2000
    
• Applies the following:
  • Sets metadata.namespace as Crossplane namespace.
  • Sets metadata.ownerReferences such that the deployment owned by the package revision.
  • Sets spec.selectors using generated labels.
  • Sets spec.serviceAccount with the created Service Account.
  • Adds pull secrets provided in the Package spec as image pull secrets, spec.packagePullSecrets.
  • Sets the Image Pull Policy with the value provided in the Package spec, spec.packagePullPolicy.
  • Adds necessary Ports to the runtime container.
  • Adds necessary Environments to the runtime container.
  • Mounts TLS secrets by adding necessary Volumes, Volume Mounts and Environments to the runtime container.

Configuring metadata of runtime resources

DeploymentRuntimeConfig also enables configuring the following metadata of Runtime resources, namely Deployment, ServiceAccount and Service:

• name
• labels
• annotations

The following example shows how to configure the name of the ServiceAccount and the labels of the Deployment:

 1apiVersion: pkg.crossplane.io/v1beta1
 2kind: DeploymentRuntimeConfig
 3metadata:
 4  name: my-runtime-config
 5spec:
 6  deploymentTemplate:
 7    metadata:
 8      labels:
 9        my-label: my-value
10  serviceAccountTemplate:
11    metadata:
12      name: my-service-account

Provider configuration

The ProviderConfig determines settings the Provider uses communicating to the external provider. Each Provider determines available settings of their ProviderConfig.

Provider authentication is usually configured with a ProviderConfig. For example, to use basic key-pair authentication with Provider AWS a ProviderConfig spec defines the credentials and that the Provider pod should look in the Kubernetes Secrets objects and use the key named aws-creds.

 1apiVersion: aws.crossplane.io/v1beta1
 2kind: ProviderConfig
 3metadata:
 4  name: aws-provider
 5spec:
 6  credentials:
 7    source: Secret
 8    secretRef:
 9      namespace: crossplane-system
10      name: aws-creds
11      key: creds

ProviderConfig objects apply to individual Managed Resources. A single Provider can authenticate with multiple users or accounts through ProviderConfigs.

Each account’s credentials tie to a unique ProviderConfig. When creating a managed resource, attach the desired ProviderConfig.

For example, two AWS ProviderConfigs, named user-keys and admin-keys use different Kubernetes secrets.

 1apiVersion: aws.crossplane.io/v1beta1
 2kind: ProviderConfig
 3metadata:
 4  name: user-keys
 5spec:
 6  credentials:
 7    source: Secret
 8    secretRef:
 9      namespace: crossplane-system
10      name: my-key
11      key: secret-key

 1apiVersion: aws.crossplane.io/v1beta1
 2kind: ProviderConfig
 3metadata:
 4  name: admin-keys
 5spec:
 6  credentials:
 7    source: Secret
 8    secretRef:
 9      namespace: crossplane-system
10      name: admin-key
11      key: admin-secret-key

Apply the ProviderConfig when creating a managed resource.

This creates an AWS Bucket resource using the user-keys ProviderConfig.

1apiVersion: s3.aws.upbound.io/v1beta1
2kind: Bucket
3metadata:
4  name: user-bucket
5spec:
6  forProvider:
7    region: us-east-2
8  providerConfigRef:
9    name: user-keys

This creates a second Bucket resource using the admin-keys ProviderConfig.

1apiVersion: s3.aws.upbound.io/v1beta1
2kind: Bucket
3metadata:
4  name: user-bucket
5spec:
6  forProvider:
7    region: us-east-2
8  providerConfigRef:
9    name: admin-keys