24 KiB
| title | weight | description |
|---|---|---|
| Providers | 5 | Providers connect Crossplane to external APIs |
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:
{{< hint "tip" >}} Find more providers in the Upbound Marketplace. {{< /hint >}}
Providers define every external resource they can create in Kubernetes as a
Kubernetes API endpoint.
These endpoints are
[Managed Resources]({{<ref "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,
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-aws
spec:
package: xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0
By default, the Provider pod installs in the same namespace as Crossplane
(crossplane-system).
{{<hint "note" >}} Providers are part of the {{}}pkg.crossplane.io{{}} group.
The {{}}meta.pkg.crossplane.io{{}} group is for creating Provider packages.
Instructions on building Providers are outside of the scope of this
document.
Read the Crossplane contributing
Provider Development Guide
for more information.
For information on the specification of Provider packages read the Crossplane Provider Package specification.
apiVersion: meta.pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-aws
spec:
# 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,
helm install crossplane \
crossplane-stable/crossplane \
--namespace crossplane-system \
--create-namespace \
--set provider.packages='{xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0}'
Install offline
Crossplane installs packages from a local package cache. By default the Crossplane package cache is an emptyDir volume.
Configure Crossplane to use a PersistentVolumeClaim to use a storage location containing the Provider image. Read more about configuring the Crossplane Pod settings in the [Crossplane install documentation]({{<ref "../software/install#customize-the-crossplane-helm-chart">}}).
Provide the name of the Provider's .xpkg file and set
{{}}packagePullPolicy: Never{{}}.
For example, to install a locally stored version of Provider AWS set the {{}}package{{}} to the local filename and set the Provider's {{}}packagePullPolicy: Never{{}}.
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: offline-provider-aws
spec:
package: provider-aws
packagePullPolicy: Never
Installation options
Providers support multiple configuration options to change installation related settings.
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.
{{<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 Provider package use the
{{}}packagePullPolicy: Always{{}}
configuration.
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-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 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{{}}.
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-aws
spec:
revisionActivationPolicy: Manual
# 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.
{{<hint "note" >}} Read the Provider upgrade section for more information on the use of package revisions. {{< /hint >}}
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{{}}.
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-aws
spec:
revisionHistoryLimit: 10
# 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.
{{<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: Provider
metadata:
name: provider-aws
spec:
packagePullSecrets:
- name: example-secret
# Removed for brevity
{{<hint "note" >}}
Configured packagePullSecrets aren't passed to any Provider package
dependencies.
{{< /hint >}}
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{{}}.
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-aws
spec:
skipDependencyResolution: true
# Removed for brevity
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{{}}.
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-aws
spec:
ignoreCrossplaneConstraints: true
# 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 Upbound AWS reference platform is
HEALTHY: False.
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
provider-aws-s3 True False xpkg.upbound.io/upbound/provider-aws-s3:v0.41.0 12s
To see more information on why the Provider isn't HEALTHY use
{{}}kubectl describe providerrevisions{{}}.
kubectl describe providerrevisions
Name: provider-aws-s3-92206523fff4
API Version: pkg.crossplane.io/v1
Kind: ProviderRevision
Spec:
Desired State: Active
Image: xpkg.upbound.io/upbound/provider-aws-s3:v0.41.0
Revision: 1
Status:
Conditions:
Last Transition Time: 2023-10-10T21:06:39Z
Reason: UnhealthyPackageRevision
Status: False
Type: Healthy
Controller Ref:
Name:
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning LintPackage 41s (x3 over 47s) packages/providerrevision.pkg.crossplane.io incompatible Crossplane version: package is not 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{{}}
kubectl get providerrevisions
NAME HEALTHY REVISION IMAGE STATE DEP-FOUND DEP-INSTALLED AGE
provider-aws-s3-dbc7f981d81f True 1 xpkg.upbound.io/upbound/provider-aws-s3:v0.37.0 Active 1 1 10d
provider-nop-552a394a8acc True 2 xpkg.upbound.io/crossplane-contrib/provider-nop:v0.3.0 Active 11d
provider-nop-7e62d2a1a709 True 1 xpkg.upbound.io/crossplane-contrib/provider-nop:v0.2.0 Inactive 13d
upbound-provider-family-aws-710d8cfe9f53 True 1 xpkg.upbound.io/upbound/provider-family-aws:v0.40.0 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.
{{< hint "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]({{<ref "/knowledge-base/guides/troubleshoot#deleting-when-a-resource-hangs" >}}). {{< /hint >}}
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.
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
crossplane-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.
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
crossplane-contrib-provider-aws True True xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0 88s
{{<hint "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. {{< /hint >}}
Provider conditions
Crossplane uses a standard set of Conditions for Providers.
View the conditions of a provider under their Status with
kubectl describe provider.
kubectl describe provider
Name: my-provider
API Version: pkg.crossplane.io/v1
Kind: Provider
# Removed for brevity
Status:
Conditions:
Reason: HealthyPackageRevision
Status: True
Type: Healthy
Reason: ActivePackageRevision
Status: True
Type: Installed
# 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.
Type: Installed
Status: False
Reason: InactivePackageRevision
ActivePackageRevision
The Provider Package is the current Package Revision, but Crossplane hasn't finished installing the Package Revision yet.
{{< hint "tip" >}} Providers stuck in this state are because of a problem with Package Revisions.
Use kubectl describe providerrevisions for more details.
{{< /hint >}}
Type: Installed
Status: True
Reason: ActivePackageRevision
HealthyPackageRevision
The Provider is fully installed and ready to use.
{{<hint "tip" >}}
Reason: HealthyPackageRevision is the normal state of a working Provider.
{{< /hint >}}
Type: Healthy
Status: True
Reason: HealthyPackageRevision
UnhealthyPackageRevision
There was an error installing the Provider Package Revision, preventing Crossplane from installing the Provider Package.
{{<hint "tip" >}}
Use kubectl describe providerrevisions for more details on why the Package
Revision failed.
{{< /hint >}}
Type: Healthy
Status: False
Reason: UnhealthyPackageRevision
UnknownPackageRevisionHealth
The status of the Provider Package Revision is Unknown. The Provider Package
Revision may be installing or has an issue.
{{<hint "tip" >}}
Use kubectl describe providerrevisions for more details on why the Package
Revision failed.
{{< /hint >}}
Type: Healthy
Status: Unknown
Reason: 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
tolerationon the Provider pod. -
Provider configurations that change settings used when communicating with an external provider. For example, cloud provider authentication.
{{<hint "important" >}}
Apply ControllerConfig objects to Providers.
Apply ProviderConfig objects to managed resources.
{{< /hint >}}
Controller configuration
{{< hint "important" >}}
The Crossplane community deprecated the ControllerConfig type in v1.11 to
announce that there are no further enhancements.
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 the Package Runtime Config which is a future replacement.
{{< /hint >}}
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{{}}.
apiVersion: aws.crossplane.io/v1beta1
kind: ProviderConfig
metadata:
name: aws-provider
spec:
credentials:
source: Secret
secretRef:
namespace: crossplane-system
name: aws-creds
key: creds
{{< hint "important" >}} Authentication configuration may be different across Providers.
Read the documentation on a specific Provider for instructions on configuring authentication for that Provider. {{< /hint >}}
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.
apiVersion: aws.crossplane.io/v1beta1
kind: ProviderConfig
metadata:
name: user-keys
spec:
credentials:
source: Secret
secretRef:
namespace: crossplane-system
name: my-key
key: secret-key
apiVersion: aws.crossplane.io/v1beta1
kind: ProviderConfig
metadata:
name: admin-keys
spec:
credentials:
source: Secret
secretRef:
namespace: crossplane-system
name: admin-key
key: admin-secret-key
Apply the ProviderConfig when creating a managed resource.
This creates an AWS {{}}Bucket{{< /hover >}} resource using the {{}}user-keys{{< /hover >}} ProviderConfig.
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
metadata:
name: user-bucket
spec:
forProvider:
region: us-east-2
providerConfigRef:
name: user-keys
This creates a second {{}}Bucket{{< /hover >}} resource using the {{}}admin-keys{{< /hover >}} ProviderConfig.
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
metadata:
name: user-bucket
spec:
forProvider:
region: us-east-2
providerConfigRef:
name: admin-keys