Providers

On this page

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:

Tip

Find more providers in the Upbound Marketplace.

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

Note

Instructions on building your own Provider are outside of the scope of this document. Read the Crossplane contributing Provider Development Guide for more information.

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.upbound.io/crossplane-contrib/provider-aws:v0.39.0

Tip

Providers are Crossplane Packages. Read more about Packages in the Packages documentation.

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

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.upbound.io/crossplane-contrib/provider-aws:v0.39.0}'

Install from a private repository

Installing a Provider from a private package repository requires a Kubernetes secret object. The Provider uses the secret with the packagePullSecrets option.

1apiVersion: pkg.crossplane.io/v1
2kind: Provider
3metadata:
4  name: private-provider
5spec:
6  package: private-repo.example.org/providers/my-provider
7  packagePullSecrets:
8    - name: my-secret

Note

The Kubernetes secret object the Provider uses must be in the same namespace as the Crossplane pod.

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.

Remove a Provider

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

Warning

Removing a Provider without first removing the Provider’s managed resources may abandon the resources. The external resources aren’t deleted.

If you remove the Provider first, you must manually delete external resources through your cloud provider. Managed resources must be manually deleted by removing their finalizers.

For more information on deleting abandoned resources read the Crossplane troubleshooting guide.

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.upbound.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.upbound.io/crossplane-contrib/provider-aws:v0.39.0   88s

Important

Some Providers install hundreds of Kubernetes Custom Resource Definitions (CRDs). This can create significant strain on undersized API Servers, impacting Provider install times.

The Crossplane community has more details on scaling CRDs.

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.

Tip

Providers stuck in this state are because of a problem with Package Revisions.

Use kubectl describe providerrevisions for more details.

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

HealthyPackageRevision

The Provider is fully installed and ready to use.

Tip

Reason: HealthyPackageRevision is the normal state of a working Provider.

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

UnhealthyPackageRevision

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

Tip

Use kubectl describe providerrevisions for more details on why the Package Revision failed.

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.

Tip

Use kubectl describe providerrevisions for more details on why the Package Revision failed.

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, Pod toleration.
Provider configurations that change settings used when communicating with an external provider. For example, cloud provider authentication.

Important

Apply ControllerConfig objects to Providers.

Apply ProviderConfig objects to managed resources.

Controller configuration

Important

The Crossplane community deprecated the ControllerConfig type in v1.11 to indicate that no further enhancements will be made to it. Applying a Controller configuration generates a deprecation warning.

Controller configurations are still supported until there is a replacement type in a future Crossplane version. You can read more about the design of Package Runtime Config which will replace it in the future.

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.

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

Important

Authentication configuration may be different across Providers.

Read the documentation on a specific Provider for instructions on configuring authentication for that Provider.

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