crossplane
/
docs
mirror of https://github.com/crossplane/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updates the ControllerConfig deprecation warning (#548)

This commit is contained in:
Jean du Plessis 2023-09-14 16:14:55 +02:00 committed by GitHub
parent 44f6912a6e
commit daaa7ec019
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 251 additions and 210 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
content/master/concepts/providers.md
View File

@ -5,7 +5,7 @@ description: "Providers connect Crossplane to external APIs"
--- ---
Providers enable Crossplane to provision infrastructure on an Providers enable Crossplane to provision infrastructure on an
external service. Providers create new Kubernetes APIs and map them to external external service. Providers create new Kubernetes APIs and map them to external
APIs. APIs.
Providers are responsible for all aspects of connecting to non-Kubernetes Providers are responsible for all aspects of connecting to non-Kubernetes
@ -15,6 +15,7 @@ providing
logic for any external resources. logic for any external resources.
Examples of providers include: Examples of providers include:
* [Provider AWS](https://github.com/upbound/provider-aws) * [Provider AWS](https://github.com/upbound/provider-aws)
* [Provider Azure](https://github.com/upbound/provider-azure) * [Provider Azure](https://github.com/upbound/provider-azure)
* [Provider GCP](https://github.com/upbound/provider-gcp) * [Provider GCP](https://github.com/upbound/provider-gcp)
@ -27,7 +28,7 @@ Find more providers in the [Upbound Marketplace](https://marketplace.upbound.io)
<!-- vale write-good.Passive = NO --> <!-- vale write-good.Passive = NO -->
<!-- "are Managed" isn't passive in this context --> <!-- "are Managed" isn't passive in this context -->
Providers define every external resource they can create in Kubernetes as a Providers define every external resource they can create in Kubernetes as a
Kubernetes API endpoint. These endpoints are Kubernetes API endpoint. These endpoints are
[_Managed Resources_]({{<ref "managed-resources" >}}). [_Managed Resources_]({{<ref "managed-resources" >}}).
<!-- vale write-good.Passive = YES --> <!-- vale write-good.Passive = YES -->
@ -42,14 +43,14 @@ for more information.
Installing a provider creates a Provider pod that's responsible for installing Installing a provider creates a Provider pod that's responsible for installing
the Provider's APIs into the Kubernetes cluster. Providers constantly watch the the Provider's APIs into the Kubernetes cluster. Providers constantly watch the
state of the desired managed resources and create any external resources that state of the desired managed resources and create any external resources that
are missing. are missing.
Install a Provider with a Crossplane Install a Provider with a Crossplane
{{<hover label="install" line="2">}}Provider{{</hover >}} object setting the {{<hover label="install" line="2">}}Provider{{</hover >}} object setting the
{{<hover label="install" line="6">}}spec.package{{</hover >}} value to the {{<hover label="install" line="6">}}spec.package{{</hover >}} value to the
location of the provider package. location of the provider package.
For example, to install the For example, to install the
[AWS Community Provider](https://github.com/crossplane-contrib/provider-aws), [AWS Community Provider](https://github.com/crossplane-contrib/provider-aws),
```yaml {label="install"} ```yaml {label="install"}
@ -71,12 +72,12 @@ By default, the Provider pod installs in the same namespace as Crossplane
### Install with Helm ### Install with Helm
Crossplane supports installing Providers during an initial Crossplane Crossplane supports installing Providers during an initial Crossplane
installation with the Crossplane Helm chart. installation with the Crossplane Helm chart.
Use the Use the
{{<hover label="helm" line="5" >}}--set provider.packages{{</hover >}} {{<hover label="helm" line="5" >}}--set provider.packages{{</hover >}}
argument with `helm install`. argument with `helm install`.
For example, to install the AWS Community Provider, For example, to install the AWS Community Provider,
@ -92,7 +93,7 @@ crossplane-stable/crossplane \
Installing a Provider from a private package repository requires a Installing a Provider from a private package repository requires a
Kubernetes secret object. The Provider uses the secret with the Kubernetes secret object. The Provider uses the secret with the
{{<hover label="pps" line="7" >}}packagePullSecrets{{</hover>}} option. {{<hover label="pps" line="7" >}}packagePullSecrets{{</hover>}} option.
```yaml {label="pps"} ```yaml {label="pps"}
apiVersion: pkg.crossplane.io/v1 apiVersion: pkg.crossplane.io/v1
@ -115,31 +116,31 @@ the Crossplane pod.
To upgrade an existing Provider edit the installed Provider Package by either To upgrade an existing Provider edit the installed Provider Package by either
applying a new Provider manifest or with `kubectl edit providers`. applying a new Provider manifest or with `kubectl edit providers`.
Update the version number in the Provider's `spec.package` and apply the change. Update the version number in the Provider's `spec.package` and apply the change.
Crossplane installs the new image and creates a new `ProviderRevision`. Crossplane installs the new image and creates a new `ProviderRevision`.
## Remove a Provider ## Remove a Provider
Remove a Provider by deleting the Provider object with `kubectl delete Remove a Provider by deleting the Provider object with `kubectl delete
provider`. provider`.
{{< hint "warning" >}} {{< hint "warning" >}}
Removing a Provider without first removing the Provider's managed resources Removing a Provider without first removing the Provider's managed resources
may abandon the resources. The external resources aren't deleted. may abandon the resources. The external resources aren't deleted.
If you remove the Provider first, you must manually delete external resources If you remove the Provider first, you must manually delete external resources
through your cloud provider. Managed resources must be manually deleted by through your cloud provider. Managed resources must be manually deleted by
removing their finalizers. 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" >}}). For more information on deleting abandoned resources read the [Crossplane troubleshooting guide]({{<ref "/knowledge-base/guides/troubleshoot#deleting-when-a-resource-hangs" >}}).
{{< /hint >}} {{< /hint >}}
## Verify a Provider ## Verify a Provider
Providers install their own APIs representing the managed resources they support. Providers install their own APIs representing the managed resources they support.
Providers may also create Deployments, Service Accounts or RBAC configuration. Providers may also create Deployments, Service Accounts or RBAC configuration.
View the status of a Provider with View the status of a Provider with
`kubectl get providers` `kubectl get providers`
@ -164,16 +165,17 @@ crossplane-contrib-provider-aws True True xpkg.upbound.io/crosspla
{{<hint "important" >}} {{<hint "important" >}}
Some Providers install hundreds of Kubernetes Custom Resource Definitions (`CRDs`). Some Providers install hundreds of Kubernetes Custom Resource Definitions (`CRDs`).
This can create significant strain on undersized API Servers, impacting Provider This can create significant strain on undersized API Servers, impacting Provider
install times. install times.
The Crossplane community has more The Crossplane community has more
[details on scaling CRDs](https://github.com/crossplane/crossplane/blob/master/design/one-pager-crd-scaling.md). [details on scaling CRDs](https://github.com/crossplane/crossplane/blob/master/design/one-pager-crd-scaling.md).
{{< /hint >}} {{< /hint >}}
### Provider conditions ### Provider conditions
Crossplane uses a standard set of `Conditions` for Providers. Crossplane uses a standard set of `Conditions` for Providers.
View the conditions of a provider under their `Status` with View the conditions of a provider under their `Status` with
`kubectl describe provider`. `kubectl describe provider`.
```yaml ```yaml
kubectl describe provider kubectl describe provider
@ -193,17 +195,21 @@ Status:
``` ```
#### Types #### Types
Provider `Conditions` support two `Types`: Provider `Conditions` support two `Types`:
* `Type: Installed` - the Provider package installed but isn't ready for use. * `Type: Installed` - the Provider package installed but isn't ready for use.
* `Type: Healthy` - The Provider package is ready to use. * `Type: Healthy` - The Provider package is ready to use.
#### Reasons #### Reasons
Each `Reason` relates to a specific `Type` and `Status`. Crossplane uses the Each `Reason` relates to a specific `Type` and `Status`. Crossplane uses the
following `Reasons` for Provider `Conditions`. following `Reasons` for Provider `Conditions`.
<!-- vale Google.Headings = NO --> <!-- vale Google.Headings = NO -->
##### InactivePackageRevision ##### InactivePackageRevision
`Reason: InactivePackageRevision` indicates the Provider Package is using an
`Reason: InactivePackageRevision` indicates the Provider Package is using an
inactive Provider Package Revision. inactive Provider Package Revision.
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
@ -217,10 +223,10 @@ Reason: InactivePackageRevision
##### ActivePackageRevision ##### ActivePackageRevision
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
The Provider Package is the current Package Revision, but Crossplane hasn't The Provider Package is the current Package Revision, but Crossplane hasn't
finished installing the Package Revision yet. finished installing the Package Revision yet.
{{< hint "tip" >}} {{< hint "tip" >}}
Providers stuck in this state are because of a problem with Package Revisions. Providers stuck in this state are because of a problem with Package Revisions.
Use `kubectl describe providerrevisions` for more details. Use `kubectl describe providerrevisions` for more details.
{{< /hint >}} {{< /hint >}}
@ -233,6 +239,7 @@ Reason: ActivePackageRevision
<!-- vale Google.Headings = NO --> <!-- vale Google.Headings = NO -->
##### HealthyPackageRevision ##### HealthyPackageRevision
The Provider is fully installed and ready to use. The Provider is fully installed and ready to use.
{{<hint "tip" >}} {{<hint "tip" >}}
@ -251,7 +258,7 @@ Reason: HealthyPackageRevision
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
There was an error installing the Provider Package Revision, preventing There was an error installing the Provider Package Revision, preventing
Crossplane from installing the Provider Package. Crossplane from installing the Provider Package.
{{<hint "tip" >}} {{<hint "tip" >}}
Use `kubectl describe providerrevisions` for more details on why the Package Use `kubectl describe providerrevisions` for more details on why the Package
@ -267,9 +274,8 @@ Reason: UnhealthyPackageRevision
##### UnknownPackageRevisionHealth ##### UnknownPackageRevisionHealth
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
The status of the Provider Package Revision is `Unknown`. The Provider Package The status of the Provider Package Revision is `Unknown`. The Provider Package
Revision may be installing or has an issue. Revision may be installing or has an issue.
{{<hint "tip" >}} {{<hint "tip" >}}
Use `kubectl describe providerrevisions` for more details on why the Package Use `kubectl describe providerrevisions` for more details on why the Package
@ -285,10 +291,11 @@ Reason: UnknownPackageRevisionHealth
## Configure a Provider ## Configure a Provider
Providers have two different types of configurations: Providers have two different types of configurations:
* _Controller configurations_ that change the settings of the Provider pod * _Controller configurations_ that change the settings of the Provider pod
running inside the Kubernetes cluster. For example, Pod `toleration`. running inside the Kubernetes cluster. For example, Pod `toleration`.
* _Provider configurations_ that change settings used when communicating with * _Provider configurations_ that change settings used when communicating with
an external provider. For example, cloud provider authentication. an external provider. For example, cloud provider authentication.
{{<hint "important" >}} {{<hint "important" >}}
Apply `ControllerConfig` objects to Providers. Apply `ControllerConfig` objects to Providers.
@ -296,22 +303,27 @@ Apply `ControllerConfig` objects to Providers.
Apply `ProviderConfig` objects to managed resources. Apply `ProviderConfig` objects to managed resources.
{{< /hint >}} {{< /hint >}}
### Controller configuration ### Controller configuration
{{< hint "important" >}} {{< hint "important" >}}
The Crossplane community deprecated the `ControllerConfig` type in v1.11. The Crossplane community deprecated the `ControllerConfig` type in v1.11 to
Applying a Controller configuration generates a deprecation warning. 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 Controller configurations are still supported until there is a replacement type
in a future Crossplane version. in a future Crossplane version. You can read more about the design of
[Package Runtime Config](https://github.com/crossplane/crossplane/blob/master/design/one-pager-package-runtime-config.md)
which will replace it in the future.
{{< /hint >}} {{< /hint >}}
Applying a Crossplane `ControllerConfig` to a Provider changes the settings of Applying a Crossplane `ControllerConfig` to a Provider changes the settings of
the Provider's pod. The the Provider's pod. The
[Crossplane ControllerConfig schema](https://doc.crds.dev/github.com/crossplane/crossplane/pkg.crossplane.io/ControllerConfig/v1alpha1) [Crossplane ControllerConfig schema](https://doc.crds.dev/github.com/crossplane/crossplane/pkg.crossplane.io/ControllerConfig/v1alpha1)
defines the supported set of ControllerConfig settings. defines the supported set of ControllerConfig settings.
The most common use case for ControllerConfigs are providing `args` to a The most common use case for ControllerConfigs are providing `args` to a
Provider's pod enabling optional services. For example, enabling Provider's pod enabling optional services. For example, enabling
[external secret stores](https://docs.crossplane.io/knowledge-base/integrations/vault-as-secret-store/#enable-external-secret-stores-in-the-provider) [external secret stores](https://docs.crossplane.io/knowledge-base/integrations/vault-as-secret-store/#enable-external-secret-stores-in-the-provider)
for a Provider. for a Provider.
@ -320,20 +332,20 @@ Each Provider determines their supported set of `args`.
### Provider configuration ### Provider configuration
The `ProviderConfig` determines settings the Provider uses communicating to the The `ProviderConfig` determines settings the Provider uses communicating to the
external provider. Each Provider determines available settings of their external provider. Each Provider determines available settings of their
`ProviderConfig`. `ProviderConfig`.
<!-- vale write-good.Weasel = NO --> <!-- vale write-good.Weasel = NO -->
<!-- allow "usually" --> <!-- allow "usually" -->
Provider authentication is usually configured with a `ProviderConfig`. For Provider authentication is usually configured with a `ProviderConfig`. For
example, to use basic key-pair authentication with Provider AWS a example, to use basic key-pair authentication with Provider AWS a
{{<hover label="providerconfig" line="2" >}}ProviderConfig{{</hover >}} {{<hover label="providerconfig" line="2" >}}ProviderConfig{{</hover >}}
{{<hover label="providerconfig" line="5" >}}spec{{</hover >}} {{<hover label="providerconfig" line="5" >}}spec{{</hover >}}
defines the defines the
{{<hover label="providerconfig" line="6" >}}credentials{{</hover >}} and that {{<hover label="providerconfig" line="6" >}}credentials{{</hover >}} and that
the Provider pod should look in the Kubernetes the Provider pod should look in the Kubernetes
{{<hover label="providerconfig" line="7" >}}Secrets{{</hover >}} objects and use {{<hover label="providerconfig" line="7" >}}Secrets{{</hover >}} objects and use
the key named the key named
{{<hover label="providerconfig" line="10" >}}aws-creds{{</hover >}}. {{<hover label="providerconfig" line="10" >}}aws-creds{{</hover >}}.
<!-- vale write-good.Weasel = YES --> <!-- vale write-good.Weasel = YES -->
```yaml {label="providerconfig"} ```yaml {label="providerconfig"}
@ -351,23 +363,23 @@ spec:
``` ```
{{< hint "important" >}} {{< hint "important" >}}
Authentication configuration may be different across Providers. Authentication configuration may be different across Providers.
Read the documentation on a specific Provider for instructions on configuring Read the documentation on a specific Provider for instructions on configuring
authentication for that Provider. authentication for that Provider.
{{< /hint >}} {{< /hint >}}
<!-- vale write-good.TooWordy = NO --> <!-- vale write-good.TooWordy = NO -->
<!-- allow multiple --> <!-- allow multiple -->
ProviderConfig objects apply to individual Managed Resources. A single ProviderConfig objects apply to individual Managed Resources. A single
Provider can authenticate with multiple users or accounts through Provider can authenticate with multiple users or accounts through
ProviderConfigs. ProviderConfigs.
<!-- vale write-good.TooWordy = YES --> <!-- vale write-good.TooWordy = YES -->
Each account's credentials tie to a unique ProviderConfig. When creating a Each account's credentials tie to a unique ProviderConfig. When creating a
managed resource, attach the desired ProviderConfig. managed resource, attach the desired ProviderConfig.
For example, two AWS ProviderConfigs, named For example, two AWS ProviderConfigs, named
{{<hover label="user" line="4">}}user-keys{{</hover >}} and {{<hover label="user" line="4">}}user-keys{{</hover >}} and
{{<hover label="admin" line="4">}}admin-keys{{</hover >}} {{<hover label="admin" line="4">}}admin-keys{{</hover >}}
use different Kubernetes secrets. use different Kubernetes secrets.
@ -403,7 +415,7 @@ spec:
Apply the ProviderConfig when creating a managed resource. Apply the ProviderConfig when creating a managed resource.
This creates an AWS {{<hover label="user-bucket" line="2" >}}Bucket{{< /hover >}} This creates an AWS {{<hover label="user-bucket" line="2" >}}Bucket{{< /hover >}}
resource using the resource using the
{{<hover label="user-bucket" line="9" >}}user-keys{{< /hover >}} ProviderConfig. {{<hover label="user-bucket" line="9" >}}user-keys{{< /hover >}} ProviderConfig.
```yaml {label="user-bucket"} ```yaml {label="user-bucket"}
@ -419,7 +431,7 @@ spec:
``` ```
This creates a second {{<hover label="admin-bucket" line="2" >}}Bucket{{< /hover >}} This creates a second {{<hover label="admin-bucket" line="2" >}}Bucket{{< /hover >}}
resource using the resource using the
{{<hover label="admin-bucket" line="9" >}}admin-keys{{< /hover >}} ProviderConfig. {{<hover label="admin-bucket" line="9" >}}admin-keys{{< /hover >}} ProviderConfig.
```yaml {label="admin-bucket"} ```yaml {label="admin-bucket"}
@ -433,4 +445,3 @@ spec:
providerConfigRef: providerConfigRef:
name: admin-keys name: admin-keys
``` ```

114
content/v1.11/concepts/providers.md
View File

@ -4,7 +4,7 @@ weight: 101
--- ---
Providers enable Crossplane to provision infrastructure on an Providers enable Crossplane to provision infrastructure on an
external service. Providers create new Kubernetes APIs and map them to external external service. Providers create new Kubernetes APIs and map them to external
APIs. APIs.
Providers are responsible for all aspects of connecting to non-Kubernetes Providers are responsible for all aspects of connecting to non-Kubernetes
@ -14,6 +14,7 @@ providing
logic for any external resources. logic for any external resources.
Examples of providers include: Examples of providers include:
* [Provider AWS](https://github.com/upbound/provider-aws) * [Provider AWS](https://github.com/upbound/provider-aws)
* [Provider Azure](https://github.com/upbound/provider-azure) * [Provider Azure](https://github.com/upbound/provider-azure)
* [Provider GCP](https://github.com/upbound/provider-gcp) * [Provider GCP](https://github.com/upbound/provider-gcp)
@ -26,7 +27,7 @@ Find more providers in the [Upbound Marketplace](https://marketplace.upbound.io)
<!-- vale write-good.Passive = NO --> <!-- vale write-good.Passive = NO -->
<!-- "are Managed" isn't passive in this context --> <!-- "are Managed" isn't passive in this context -->
Providers define every external resource they can create in Kubernetes as a Providers define every external resource they can create in Kubernetes as a
Kubernetes API endpoint. These endpoints are Kubernetes API endpoint. These endpoints are
[_Managed Resources_]({{<ref "managed-resources" >}}). [_Managed Resources_]({{<ref "managed-resources" >}}).
<!-- vale write-good.Passive = YES --> <!-- vale write-good.Passive = YES -->
@ -42,14 +43,14 @@ for more information.
Installing a provider creates a Provider pod that's responsible for installing Installing a provider creates a Provider pod that's responsible for installing
the Provider's APIs into the Kubernetes cluster. Providers constantly watch the the Provider's APIs into the Kubernetes cluster. Providers constantly watch the
state of the desired managed resources and create any external resources that state of the desired managed resources and create any external resources that
are missing. are missing.
Install a Provider with a Crossplane Install a Provider with a Crossplane
{{<hover label="install" line="2">}}Provider{{</hover >}} object setting the {{<hover label="install" line="2">}}Provider{{</hover >}} object setting the
{{<hover label="install" line="6">}}spec.package{{</hover >}} value to the {{<hover label="install" line="6">}}spec.package{{</hover >}} value to the
location of the provider package. location of the provider package.
For example, to install the For example, to install the
[AWS Community Provider](https://github.com/crossplane-contrib/provider-aws), [AWS Community Provider](https://github.com/crossplane-contrib/provider-aws),
```yaml {label="install"} ```yaml {label="install"}
@ -71,12 +72,12 @@ By default, the Provider pod installs in the same namespace as Crossplane
### Install with Helm ### Install with Helm
Crossplane supports installing Providers during an initial Crossplane Crossplane supports installing Providers during an initial Crossplane
installation with the Crossplane Helm chart. installation with the Crossplane Helm chart.
Use the Use the
{{<hover label="helm" line="5" >}}--set provider.packages{{</hover >}} {{<hover label="helm" line="5" >}}--set provider.packages{{</hover >}}
argument with `helm install`. argument with `helm install`.
For example, to install the AWS Community Provider, For example, to install the AWS Community Provider,
@ -92,7 +93,7 @@ crossplane-stable/crossplane \
Installing a Provider from a private package repository requires a Installing a Provider from a private package repository requires a
Kubernetes secret object. The Provider uses the secret with the Kubernetes secret object. The Provider uses the secret with the
{{<hover label="pps" line="7" >}}packagePullSecrets{{</hover>}} option. {{<hover label="pps" line="7" >}}packagePullSecrets{{</hover>}} option.
```yaml {label="pps"} ```yaml {label="pps"}
apiVersion: pkg.crossplane.io/v1 apiVersion: pkg.crossplane.io/v1
@ -115,32 +116,32 @@ the Crossplane pod.
To upgrade an existing Provider edit the installed Provider Package by either To upgrade an existing Provider edit the installed Provider Package by either
applying a new Provider manifest or with `kubectl edit providers`. applying a new Provider manifest or with `kubectl edit providers`.
Update the version number in the Provider's `spec.package` and apply the change. Update the version number in the Provider's `spec.package` and apply the change.
Crossplane installs the new image and creates a new `ProviderRevision`. Crossplane installs the new image and creates a new `ProviderRevision`.
## Remove a Provider ## Remove a Provider
Remove a Provider by deleting the Provider object with `kubectl delete Remove a Provider by deleting the Provider object with `kubectl delete
provider`. provider`.
{{< hint "warning" >}} {{< hint "warning" >}}
Removing a Provider without first removing the Provider's managed resources Removing a Provider without first removing the Provider's managed resources
may abandon the resources. The external resources aren't deleted. may abandon the resources. The external resources aren't deleted.
If you remove the Provider first, you must manually delete external resources If you remove the Provider first, you must manually delete external resources
through your cloud provider. Managed resources must be manually deleted by through your cloud provider. Managed resources must be manually deleted by
removing their finalizers. removing their finalizers.
For more information on deleting abandoned resources read the [Crossplane For more information on deleting abandoned resources read the [Crossplane
troubleshooting guide]({{<ref "/knowledge-base/guides/troubleshoot#deleting-when-a-resource-hangs" >}}). troubleshooting guide]({{<ref "/knowledge-base/guides/troubleshoot#deleting-when-a-resource-hangs" >}}).
{{< /hint >}} {{< /hint >}}
## Verify a Provider ## Verify a Provider
Providers install their own APIs representing the managed resources they support. Providers install their own APIs representing the managed resources they support.
Providers may also create Deployments, Service Accounts or RBAC configuration. Providers may also create Deployments, Service Accounts or RBAC configuration.
View the status of a Provider with View the status of a Provider with
`kubectl get providers` `kubectl get providers`
@ -165,16 +166,17 @@ crossplane-contrib-provider-aws True True xpkg.upbound.io/crosspla
{{<hint "important" >}} {{<hint "important" >}}
Some Providers install hundreds of Kubernetes Custom Resource Definitions (`CRDs`). Some Providers install hundreds of Kubernetes Custom Resource Definitions (`CRDs`).
This can create significant strain on undersized API Servers, impacting Provider This can create significant strain on undersized API Servers, impacting Provider
install times. install times.
The Crossplane community has more The Crossplane community has more
[details on scaling CRDs](https://github.com/crossplane/crossplane/blob/master/design/one-pager-crd-scaling.md). [details on scaling CRDs](https://github.com/crossplane/crossplane/blob/master/design/one-pager-crd-scaling.md).
{{< /hint >}} {{< /hint >}}
### Provider conditions ### Provider conditions
Crossplane uses a standard set of `Conditions` for Providers. Crossplane uses a standard set of `Conditions` for Providers.
View the conditions of a provider under their `Status` with View the conditions of a provider under their `Status` with
`kubectl describe provider`. `kubectl describe provider`.
```yaml ```yaml
kubectl describe provider kubectl describe provider
@ -194,17 +196,21 @@ Status:
``` ```
#### Types #### Types
Provider `Conditions` support two `Types`: Provider `Conditions` support two `Types`:
* `Type: Installed` - the Provider package installed but isn't ready for use. * `Type: Installed` - the Provider package installed but isn't ready for use.
* `Type: Healthy` - The Provider package is ready to use. * `Type: Healthy` - The Provider package is ready to use.
#### Reasons #### Reasons
Each `Reason` relates to a specific `Type` and `Status`. Crossplane uses the Each `Reason` relates to a specific `Type` and `Status`. Crossplane uses the
following `Reasons` for Provider `Conditions`. following `Reasons` for Provider `Conditions`.
<!-- vale Google.Headings = NO --> <!-- vale Google.Headings = NO -->
##### InactivePackageRevision ##### InactivePackageRevision
`Reason: InactivePackageRevision` indicates the Provider Package is using an
`Reason: InactivePackageRevision` indicates the Provider Package is using an
inactive Provider Package Revision. inactive Provider Package Revision.
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
@ -218,10 +224,10 @@ Reason: InactivePackageRevision
##### ActivePackageRevision ##### ActivePackageRevision
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
The Provider Package is the current Package Revision, but Crossplane hasn't The Provider Package is the current Package Revision, but Crossplane hasn't
finished installing the Package Revision yet. finished installing the Package Revision yet.
{{< hint "tip" >}} {{< hint "tip" >}}
Providers stuck in this state are because of a problem with Package Revisions. Providers stuck in this state are because of a problem with Package Revisions.
Use `kubectl describe providerrevisions` for more details. Use `kubectl describe providerrevisions` for more details.
{{< /hint >}} {{< /hint >}}
@ -234,6 +240,7 @@ Reason: ActivePackageRevision
<!-- vale Google.Headings = NO --> <!-- vale Google.Headings = NO -->
##### HealthyPackageRevision ##### HealthyPackageRevision
The Provider is fully installed and ready to use. The Provider is fully installed and ready to use.
{{<hint "tip" >}} {{<hint "tip" >}}
@ -252,7 +259,7 @@ Reason: HealthyPackageRevision
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
There was an error installing the Provider Package Revision, preventing There was an error installing the Provider Package Revision, preventing
Crossplane from installing the Provider Package. Crossplane from installing the Provider Package.
{{<hint "tip" >}} {{<hint "tip" >}}
Use `kubectl describe providerrevisions` for more details on why the Package Use `kubectl describe providerrevisions` for more details on why the Package
@ -268,9 +275,8 @@ Reason: UnhealthyPackageRevision
##### UnknownPackageRevisionHealth ##### UnknownPackageRevisionHealth
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
The status of the Provider Package Revision is `Unknown`. The Provider Package The status of the Provider Package Revision is `Unknown`. The Provider Package
Revision may be installing or has an issue. Revision may be installing or has an issue.
{{<hint "tip" >}} {{<hint "tip" >}}
Use `kubectl describe providerrevisions` for more details on why the Package Use `kubectl describe providerrevisions` for more details on why the Package
@ -286,10 +292,11 @@ Reason: UnknownPackageRevisionHealth
## Configure a Provider ## Configure a Provider
Providers have two different types of configurations: Providers have two different types of configurations:
* _Controller configurations_ that change the settings of the Provider pod * _Controller configurations_ that change the settings of the Provider pod
running inside the Kubernetes cluster. For example, Pod `toleration`. running inside the Kubernetes cluster. For example, Pod `toleration`.
* _Provider configurations_ that change settings used when communicating with * _Provider configurations_ that change settings used when communicating with
an external provider. For example, cloud provider authentication. an external provider. For example, cloud provider authentication.
{{<hint "important" >}} {{<hint "important" >}}
Apply `ControllerConfig` objects to Providers. Apply `ControllerConfig` objects to Providers.
@ -297,22 +304,26 @@ Apply `ControllerConfig` objects to Providers.
Apply `ProviderConfig` objects to managed resources. Apply `ProviderConfig` objects to managed resources.
{{< /hint >}} {{< /hint >}}
### Controller configuration ### Controller configuration
{{< hint "important" >}} {{< hint "important" >}}
The Crossplane community deprecated the `ControllerConfig` type in v1.11. The Crossplane community deprecated the `ControllerConfig` type in v1.11 to
Applying a Controller configuration generates a deprecation warning. 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 Controller configurations are still supported until there is a replacement type
in a future Crossplane version. in a future Crossplane version. You can read more about the design of
[Package Runtime Config](https://github.com/crossplane/crossplane/blob/master/design/one-pager-package-runtime-config.md)
which will replace it in the future.
{{< /hint >}} {{< /hint >}}
Applying a Crossplane `ControllerConfig` to a Provider changes the settings of Applying a Crossplane `ControllerConfig` to a Provider changes the settings of
the Provider's pod. The the Provider's pod. The
[Crossplane ControllerConfig schema](https://doc.crds.dev/github.com/crossplane/crossplane/pkg.crossplane.io/ControllerConfig/v1alpha1) [Crossplane ControllerConfig schema](https://doc.crds.dev/github.com/crossplane/crossplane/pkg.crossplane.io/ControllerConfig/v1alpha1)
defines the supported set of ControllerConfig settings. defines the supported set of ControllerConfig settings.
The most common use-case for ControllerConfigs are providing `args` to a The most common use-case for ControllerConfigs are providing `args` to a
Provider's pod enabling optional services. For example, enabling Provider's pod enabling optional services. For example, enabling
[external secret stores](https://docs.crossplane.io/knowledge-base/integrations/vault-as-secret-store/#enable-external-secret-stores-in-the-provider) [external secret stores](https://docs.crossplane.io/knowledge-base/integrations/vault-as-secret-store/#enable-external-secret-stores-in-the-provider)
for a Provider. for a Provider.
@ -321,20 +332,20 @@ Each Provider determines their supported set of `args`.
### Provider configuration ### Provider configuration
The `ProviderConfig` determines settings the Provider uses communicating to the The `ProviderConfig` determines settings the Provider uses communicating to the
external provider. Each Provider determines available settings of their external provider. Each Provider determines available settings of their
`ProviderConfig`. `ProviderConfig`.
<!-- vale write-good.Weasel = NO --> <!-- vale write-good.Weasel = NO -->
<!-- allow "usually" --> <!-- allow "usually" -->
Provider authentication is usually configured with a `ProviderConfig`. For Provider authentication is usually configured with a `ProviderConfig`. For
example, to use basic key-pair authentication with Provider AWS a example, to use basic key-pair authentication with Provider AWS a
{{<hover label="providerconfig" line="2" >}}ProviderConfig{{</hover >}} {{<hover label="providerconfig" line="2" >}}ProviderConfig{{</hover >}}
{{<hover label="providerconfig" line="5" >}}spec{{</hover >}} {{<hover label="providerconfig" line="5" >}}spec{{</hover >}}
defines the defines the
{{<hover label="providerconfig" line="6" >}}credentials{{</hover >}} and that {{<hover label="providerconfig" line="6" >}}credentials{{</hover >}} and that
the Provider pod should look in the Kubernetes the Provider pod should look in the Kubernetes
{{<hover label="providerconfig" line="7" >}}Secrets{{</hover >}} objects and use {{<hover label="providerconfig" line="7" >}}Secrets{{</hover >}} objects and use
the key named the key named
{{<hover label="providerconfig" line="10" >}}aws-creds{{</hover >}}. {{<hover label="providerconfig" line="10" >}}aws-creds{{</hover >}}.
<!-- vale write-good.Weasel = YES --> <!-- vale write-good.Weasel = YES -->
```yaml {label="providerconfig"} ```yaml {label="providerconfig"}
@ -352,23 +363,23 @@ spec:
``` ```
{{< hint "important" >}} {{< hint "important" >}}
Authentication configuration may be different across Providers. Authentication configuration may be different across Providers.
Read the documentation on a specific Provider for instructions on configuring Read the documentation on a specific Provider for instructions on configuring
authentication for that Provider. authentication for that Provider.
{{< /hint >}} {{< /hint >}}
<!-- vale write-good.TooWordy = NO --> <!-- vale write-good.TooWordy = NO -->
<!-- allow multiple --> <!-- allow multiple -->
ProviderConfig objects apply to individual Managed Resources. A single ProviderConfig objects apply to individual Managed Resources. A single
Provider can authenticate with multiple users or accounts through Provider can authenticate with multiple users or accounts through
ProviderConfigs. ProviderConfigs.
<!-- vale write-good.TooWordy = YES --> <!-- vale write-good.TooWordy = YES -->
Each account's credentials tie to a unique ProviderConfig. When creating a Each account's credentials tie to a unique ProviderConfig. When creating a
managed resource, attach the desired ProviderConfig. managed resource, attach the desired ProviderConfig.
For example, two AWS ProviderConfigs, named For example, two AWS ProviderConfigs, named
{{<hover label="user" line="4">}}user-keys{{</hover >}} and {{<hover label="user" line="4">}}user-keys{{</hover >}} and
{{<hover label="admin" line="4">}}admin-keys{{</hover >}} {{<hover label="admin" line="4">}}admin-keys{{</hover >}}
use different Kubernetes secrets. use different Kubernetes secrets.
@ -404,7 +415,7 @@ spec:
Apply the ProviderConfig when creating a managed resource. Apply the ProviderConfig when creating a managed resource.
This creates an AWS {{<hover label="user-bucket" line="2" >}}Bucket{{< /hover >}} This creates an AWS {{<hover label="user-bucket" line="2" >}}Bucket{{< /hover >}}
resource using the resource using the
{{<hover label="user-bucket" line="9" >}}user-keys{{< /hover >}} ProviderConfig. {{<hover label="user-bucket" line="9" >}}user-keys{{< /hover >}} ProviderConfig.
```yaml {label="user-bucket"} ```yaml {label="user-bucket"}
@ -420,7 +431,7 @@ spec:
``` ```
This creates a second {{<hover label="admin-bucket" line="2" >}}Bucket{{< /hover >}} This creates a second {{<hover label="admin-bucket" line="2" >}}Bucket{{< /hover >}}
resource using the resource using the
{{<hover label="admin-bucket" line="9" >}}admin-keys{{< /hover >}} ProviderConfig. {{<hover label="admin-bucket" line="9" >}}admin-keys{{< /hover >}} ProviderConfig.
```yaml {label="admin-bucket"} ```yaml {label="admin-bucket"}
@ -434,4 +445,3 @@ spec:
providerConfigRef: providerConfigRef:
name: admin-keys name: admin-keys
``` ```

118
content/v1.12/concepts/providers.md
View File

@ -4,7 +4,7 @@ weight: 101
--- ---
Providers enable Crossplane to provision infrastructure on an Providers enable Crossplane to provision infrastructure on an
external service. Providers create new Kubernetes APIs and map them to external external service. Providers create new Kubernetes APIs and map them to external
APIs. APIs.
Providers are responsible for all aspects of connecting to non-Kubernetes Providers are responsible for all aspects of connecting to non-Kubernetes
@ -14,6 +14,7 @@ providing
logic for any external resources. logic for any external resources.
Examples of providers include: Examples of providers include:
* [Provider AWS](https://github.com/upbound/provider-aws) * [Provider AWS](https://github.com/upbound/provider-aws)
* [Provider Azure](https://github.com/upbound/provider-azure) * [Provider Azure](https://github.com/upbound/provider-azure)
* [Provider GCP](https://github.com/upbound/provider-gcp) * [Provider GCP](https://github.com/upbound/provider-gcp)
@ -26,7 +27,7 @@ Find more providers in the [Upbound Marketplace](https://marketplace.upbound.io)
<!-- vale write-good.Passive = NO --> <!-- vale write-good.Passive = NO -->
<!-- "are Managed" isn't passive in this context --> <!-- "are Managed" isn't passive in this context -->
Providers define every external resource they can create in Kubernetes as a Providers define every external resource they can create in Kubernetes as a
Kubernetes API endpoint. These endpoints are Kubernetes API endpoint. These endpoints are
[_Managed Resources_]({{<ref "managed-resources" >}}). [_Managed Resources_]({{<ref "managed-resources" >}}).
<!-- vale write-good.Passive = YES --> <!-- vale write-good.Passive = YES -->
@ -42,14 +43,14 @@ for more information.
Installing a provider creates a Provider pod that's responsible for installing Installing a provider creates a Provider pod that's responsible for installing
the Provider's APIs into the Kubernetes cluster. Providers constantly watch the the Provider's APIs into the Kubernetes cluster. Providers constantly watch the
state of the desired managed resources and create any external resources that state of the desired managed resources and create any external resources that
are missing. are missing.
Install a Provider with a Crossplane Install a Provider with a Crossplane
{{<hover label="install" line="2">}}Provider{{</hover >}} object setting the {{<hover label="install" line="2">}}Provider{{</hover >}} object setting the
{{<hover label="install" line="6">}}spec.package{{</hover >}} value to the {{<hover label="install" line="6">}}spec.package{{</hover >}} value to the
location of the provider package. location of the provider package.
For example, to install the For example, to install the
[AWS Community Provider](https://github.com/crossplane-contrib/provider-aws), [AWS Community Provider](https://github.com/crossplane-contrib/provider-aws),
```yaml {label="install"} ```yaml {label="install"}
@ -71,12 +72,12 @@ By default, the Provider pod installs in the same namespace as Crossplane
### Install with Helm ### Install with Helm
Crossplane supports installing Providers during an initial Crossplane Crossplane supports installing Providers during an initial Crossplane
installation with the Crossplane Helm chart. installation with the Crossplane Helm chart.
Use the Use the
{{<hover label="helm" line="5" >}}--set provider.packages{{</hover >}} {{<hover label="helm" line="5" >}}--set provider.packages{{</hover >}}
argument with `helm install`. argument with `helm install`.
For example, to install the AWS Community Provider, For example, to install the AWS Community Provider,
@ -92,7 +93,7 @@ crossplane-stable/crossplane \
Installing a Provider from a private package repository requires a Installing a Provider from a private package repository requires a
Kubernetes secret object. The Provider uses the secret with the Kubernetes secret object. The Provider uses the secret with the
{{<hover label="pps" line="7" >}}packagePullSecrets{{</hover>}} option. {{<hover label="pps" line="7" >}}packagePullSecrets{{</hover>}} option.
```yaml {label="pps"} ```yaml {label="pps"}
apiVersion: pkg.crossplane.io/v1 apiVersion: pkg.crossplane.io/v1
@ -115,32 +116,32 @@ the Crossplane pod.
To upgrade an existing Provider edit the installed Provider Package by either To upgrade an existing Provider edit the installed Provider Package by either
applying a new Provider manifest or with `kubectl edit providers`. applying a new Provider manifest or with `kubectl edit providers`.
Update the version number in the Provider's `spec.package` and apply the change. Update the version number in the Provider's `spec.package` and apply the change.
Crossplane installs the new image and creates a new `ProviderRevision`. Crossplane installs the new image and creates a new `ProviderRevision`.
## Remove a Provider ## Remove a Provider
Remove a Provider by deleting the Provider object with `kubectl delete Remove a Provider by deleting the Provider object with `kubectl delete
provider`. provider`.
{{< hint "warning" >}} {{< hint "warning" >}}
Removing a Provider without first removing the Provider's managed resources Removing a Provider without first removing the Provider's managed resources
may abandon the resources. The external resources aren't deleted. may abandon the resources. The external resources aren't deleted.
If you remove the Provider first, you must manually delete external resources If you remove the Provider first, you must manually delete external resources
through your cloud provider. Managed resources must be manually deleted by through your cloud provider. Managed resources must be manually deleted by
removing their finalizers. removing their finalizers.
For more information on deleting abandoned resources read the [Crossplane For more information on deleting abandoned resources read the [Crossplane
troubleshooting guide]({{<ref "/knowledge-base/guides/troubleshoot#deleting-when-a-resource-hangs" >}}). troubleshooting guide]({{<ref "/knowledge-base/guides/troubleshoot#deleting-when-a-resource-hangs" >}}).
{{< /hint >}} {{< /hint >}}
## Verify a Provider ## Verify a Provider
Providers install their own APIs representing the managed resources they support. Providers install their own APIs representing the managed resources they support.
Providers may also create Deployments, Service Accounts or RBAC configuration. Providers may also create Deployments, Service Accounts or RBAC configuration.
View the status of a Provider with View the status of a Provider with
`kubectl get providers` `kubectl get providers`
@ -165,16 +166,17 @@ crossplane-contrib-provider-aws True True xpkg.upbound.io/crosspla
{{<hint "important" >}} {{<hint "important" >}}
Some Providers install hundreds of Kubernetes Custom Resource Definitions (`CRDs`). Some Providers install hundreds of Kubernetes Custom Resource Definitions (`CRDs`).
This can create significant strain on undersized API Servers, impacting Provider This can create significant strain on undersized API Servers, impacting Provider
install times. install times.
The Crossplane community has more The Crossplane community has more
[details on scaling CRDs](https://github.com/crossplane/crossplane/blob/master/design/one-pager-crd-scaling.md). [details on scaling CRDs](https://github.com/crossplane/crossplane/blob/master/design/one-pager-crd-scaling.md).
{{< /hint >}} {{< /hint >}}
### Provider conditions ### Provider conditions
Crossplane uses a standard set of `Conditions` for Providers. Crossplane uses a standard set of `Conditions` for Providers.
View the conditions of a provider under their `Status` with View the conditions of a provider under their `Status` with
`kubectl describe provider`. `kubectl describe provider`.
```yaml ```yaml
kubectl describe provider kubectl describe provider
@ -194,17 +196,21 @@ Status:
``` ```
#### Types #### Types
Provider `Conditions` support two `Types`: Provider `Conditions` support two `Types`:
* `Type: Installed` - the Provider package installed but isn't ready for use. * `Type: Installed` - the Provider package installed but isn't ready for use.
* `Type: Healthy` - The Provider package is ready to use. * `Type: Healthy` - The Provider package is ready to use.
#### Reasons #### Reasons
Each `Reason` relates to a specific `Type` and `Status`. Crossplane uses the Each `Reason` relates to a specific `Type` and `Status`. Crossplane uses the
following `Reasons` for Provider `Conditions`. following `Reasons` for Provider `Conditions`.
<!-- vale Google.Headings = NO --> <!-- vale Google.Headings = NO -->
##### InactivePackageRevision ##### InactivePackageRevision
`Reason: InactivePackageRevision` indicates the Provider Package is using an
`Reason: InactivePackageRevision` indicates the Provider Package is using an
inactive Provider Package Revision. inactive Provider Package Revision.
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
@ -218,10 +224,10 @@ Reason: InactivePackageRevision
##### ActivePackageRevision ##### ActivePackageRevision
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
The Provider Package is the current Package Revision, but Crossplane hasn't The Provider Package is the current Package Revision, but Crossplane hasn't
finished installing the Package Revision yet. finished installing the Package Revision yet.
{{< hint "tip" >}} {{< hint "tip" >}}
Providers stuck in this state are because of a problem with Package Revisions. Providers stuck in this state are because of a problem with Package Revisions.
Use `kubectl describe providerrevisions` for more details. Use `kubectl describe providerrevisions` for more details.
{{< /hint >}} {{< /hint >}}
@ -234,6 +240,7 @@ Reason: ActivePackageRevision
<!-- vale Google.Headings = NO --> <!-- vale Google.Headings = NO -->
##### HealthyPackageRevision ##### HealthyPackageRevision
The Provider is fully installed and ready to use. The Provider is fully installed and ready to use.
{{<hint "tip" >}} {{<hint "tip" >}}
@ -252,7 +259,7 @@ Reason: HealthyPackageRevision
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
There was an error installing the Provider Package Revision, preventing There was an error installing the Provider Package Revision, preventing
Crossplane from installing the Provider Package. Crossplane from installing the Provider Package.
{{<hint "tip" >}} {{<hint "tip" >}}
Use `kubectl describe providerrevisions` for more details on why the Package Use `kubectl describe providerrevisions` for more details on why the Package
@ -268,9 +275,8 @@ Reason: UnhealthyPackageRevision
##### UnknownPackageRevisionHealth ##### UnknownPackageRevisionHealth
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
The status of the Provider Package Revision is `Unknown`. The Provider Package The status of the Provider Package Revision is `Unknown`. The Provider Package
Revision may be installing or has an issue. Revision may be installing or has an issue.
{{<hint "tip" >}} {{<hint "tip" >}}
Use `kubectl describe providerrevisions` for more details on why the Package Use `kubectl describe providerrevisions` for more details on why the Package
@ -286,10 +292,11 @@ Reason: UnknownPackageRevisionHealth
## Configure a Provider ## Configure a Provider
Providers have two different types of configurations: Providers have two different types of configurations:
* _Controller configurations_ that change the settings of the Provider pod * _Controller configurations_ that change the settings of the Provider pod
running inside the Kubernetes cluster. For example, Pod `toleration`. running inside the Kubernetes cluster. For example, Pod `toleration`.
* _Provider configurations_ that change settings used when communicating with * _Provider configurations_ that change settings used when communicating with
an external provider. For example, cloud provider authentication. an external provider. For example, cloud provider authentication.
{{<hint "important" >}} {{<hint "important" >}}
Apply `ControllerConfig` objects to Providers. Apply `ControllerConfig` objects to Providers.
@ -297,22 +304,26 @@ Apply `ControllerConfig` objects to Providers.
Apply `ProviderConfig` objects to managed resources. Apply `ProviderConfig` objects to managed resources.
{{< /hint >}} {{< /hint >}}
### Controller configuration ### Controller configuration
{{< hint "important" >}} {{< hint "important" >}}
The Crossplane community deprecated the `ControllerConfig` type in v1.11. The Crossplane community deprecated the `ControllerConfig` type in v1.11 to
Applying a Controller configuration generates a deprecation warning. 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 Controller configurations are still supported until there is a replacement type
in a future Crossplane version. in a future Crossplane version. You can read more about the design of
[Package Runtime Config](https://github.com/crossplane/crossplane/blob/master/design/one-pager-package-runtime-config.md)
which will replace it in the future.
{{< /hint >}} {{< /hint >}}
Applying a Crossplane `ControllerConfig` to a Provider changes the settings of Applying a Crossplane `ControllerConfig` to a Provider changes the settings of
the Provider's pod. The the Provider's pod. The
[Crossplane ControllerConfig schema](https://doc.crds.dev/github.com/crossplane/crossplane/pkg.crossplane.io/ControllerConfig/v1alpha1) [Crossplane ControllerConfig schema](https://doc.crds.dev/github.com/crossplane/crossplane/pkg.crossplane.io/ControllerConfig/v1alpha1)
defines the supported set of ControllerConfig settings. defines the supported set of ControllerConfig settings.
The most common use-case for ControllerConfigs are providing `args` to a The most common use-case for ControllerConfigs are providing `args` to a
Provider's pod enabling optional services. For example, enabling Provider's pod enabling optional services. For example, enabling
[external secret stores](https://docs.crossplane.io/knowledge-base/integrations/vault-as-secret-store/#enable-external-secret-stores-in-the-provider) [external secret stores](https://docs.crossplane.io/knowledge-base/integrations/vault-as-secret-store/#enable-external-secret-stores-in-the-provider)
for a Provider. for a Provider.
@ -321,20 +332,20 @@ Each Provider determines their supported set of `args`.
### Provider configuration ### Provider configuration
The `ProviderConfig` determines settings the Provider uses communicating to the The `ProviderConfig` determines settings the Provider uses communicating to the
external provider. Each Provider determines available settings of their external provider. Each Provider determines available settings of their
`ProviderConfig`. `ProviderConfig`.
<!-- vale write-good.Weasel = NO --> <!-- vale write-good.Weasel = NO -->
<!-- allow "usually" --> <!-- allow "usually" -->
Provider authentication is usually configured with a `ProviderConfig`. For Provider authentication is usually configured with a `ProviderConfig`. For
example, to use basic key-pair authentication with Provider AWS a example, to use basic key-pair authentication with Provider AWS a
{{<hover label="providerconfig" line="2" >}}ProviderConfig{{</hover >}} {{<hover label="providerconfig" line="2" >}}ProviderConfig{{</hover >}}
{{<hover label="providerconfig" line="5" >}}spec{{</hover >}} {{<hover label="providerconfig" line="5" >}}spec{{</hover >}}
defines the defines the
{{<hover label="providerconfig" line="6" >}}credentials{{</hover >}} and that {{<hover label="providerconfig" line="6" >}}credentials{{</hover >}} and that
the Provider pod should look in the Kubernetes the Provider pod should look in the Kubernetes
{{<hover label="providerconfig" line="7" >}}Secrets{{</hover >}} objects and use {{<hover label="providerconfig" line="7" >}}Secrets{{</hover >}} objects and use
the key named the key named
{{<hover label="providerconfig" line="10" >}}aws-creds{{</hover >}}. {{<hover label="providerconfig" line="10" >}}aws-creds{{</hover >}}.
<!-- vale write-good.Weasel = YES --> <!-- vale write-good.Weasel = YES -->
```yaml {label="providerconfig"} ```yaml {label="providerconfig"}
@ -352,24 +363,24 @@ spec:
``` ```
{{< hint "important" >}} {{< hint "important" >}}
Authentication configuration may be different across Providers. Authentication configuration may be different across Providers.
Read the documentation on a specific Provider for instructions on configuring Read the documentation on a specific Provider for instructions on configuring
authentication for that Provider. authentication for that Provider.
{{< /hint >}} {{< /hint >}}
<!-- vale write-good.TooWordy = NO --> <!-- vale write-good.TooWordy = NO -->
<!-- allow multiple --> <!-- allow multiple -->
ProviderConfig objects apply to individual managed resources with a ProviderConfig objects apply to individual managed resources with a
[`providerConfigRef`]({{<ref "../concepts/managed-resources#providerconfigref" >}}). [`providerConfigRef`]({{<ref "../concepts/managed-resources#providerconfigref" >}}).
A single Provider can authenticate with multiple users or accounts through A single Provider can authenticate with multiple users or accounts through
ProviderConfigs. ProviderConfigs.
<!-- vale write-good.TooWordy = YES --> <!-- vale write-good.TooWordy = YES -->
Each account's credentials tie to a unique ProviderConfig. When creating a Each account's credentials tie to a unique ProviderConfig. When creating a
managed resource, attach the desired ProviderConfig. managed resource, attach the desired ProviderConfig.
For example, two AWS ProviderConfigs, named For example, two AWS ProviderConfigs, named
{{<hover label="user" line="4">}}user-keys{{</hover >}} and {{<hover label="user" line="4">}}user-keys{{</hover >}} and
{{<hover label="admin" line="4">}}admin-keys{{</hover >}} {{<hover label="admin" line="4">}}admin-keys{{</hover >}}
use different Kubernetes secrets. use different Kubernetes secrets.
@ -405,7 +416,7 @@ spec:
Apply the ProviderConfig when creating a managed resource. Apply the ProviderConfig when creating a managed resource.
This creates an AWS {{<hover label="user-bucket" line="2" >}}Bucket{{< /hover >}} This creates an AWS {{<hover label="user-bucket" line="2" >}}Bucket{{< /hover >}}
resource using the resource using the
{{<hover label="user-bucket" line="9" >}}user-keys{{< /hover >}} ProviderConfig. {{<hover label="user-bucket" line="9" >}}user-keys{{< /hover >}} ProviderConfig.
```yaml {label="user-bucket"} ```yaml {label="user-bucket"}
@ -421,7 +432,7 @@ spec:
``` ```
This creates a second {{<hover label="admin-bucket" line="2" >}}Bucket{{< /hover >}} This creates a second {{<hover label="admin-bucket" line="2" >}}Bucket{{< /hover >}}
resource using the resource using the
{{<hover label="admin-bucket" line="9" >}}admin-keys{{< /hover >}} ProviderConfig. {{<hover label="admin-bucket" line="9" >}}admin-keys{{< /hover >}} ProviderConfig.
```yaml {label="admin-bucket"} ```yaml {label="admin-bucket"}
@ -435,4 +446,3 @@ spec:
providerConfigRef: providerConfigRef:
name: admin-keys name: admin-keys
``` ```

114
content/v1.13/concepts/providers.md
View File

@ -5,7 +5,7 @@ description: "Providers connect Crossplane to external APIs"
--- ---
Providers enable Crossplane to provision infrastructure on an Providers enable Crossplane to provision infrastructure on an
external service. Providers create new Kubernetes APIs and map them to external external service. Providers create new Kubernetes APIs and map them to external
APIs. APIs.
Providers are responsible for all aspects of connecting to non-Kubernetes Providers are responsible for all aspects of connecting to non-Kubernetes
@ -15,6 +15,7 @@ providing
logic for any external resources. logic for any external resources.
Examples of providers include: Examples of providers include:
* [Provider AWS](https://github.com/upbound/provider-aws) * [Provider AWS](https://github.com/upbound/provider-aws)
* [Provider Azure](https://github.com/upbound/provider-azure) * [Provider Azure](https://github.com/upbound/provider-azure)
* [Provider GCP](https://github.com/upbound/provider-gcp) * [Provider GCP](https://github.com/upbound/provider-gcp)
@ -27,7 +28,7 @@ Find more providers in the [Upbound Marketplace](https://marketplace.upbound.io)
<!-- vale write-good.Passive = NO --> <!-- vale write-good.Passive = NO -->
<!-- "are Managed" isn't passive in this context --> <!-- "are Managed" isn't passive in this context -->
Providers define every external resource they can create in Kubernetes as a Providers define every external resource they can create in Kubernetes as a
Kubernetes API endpoint. These endpoints are Kubernetes API endpoint. These endpoints are
[_Managed Resources_]({{<ref "managed-resources" >}}). [_Managed Resources_]({{<ref "managed-resources" >}}).
<!-- vale write-good.Passive = YES --> <!-- vale write-good.Passive = YES -->
@ -42,14 +43,14 @@ for more information.
Installing a provider creates a Provider pod that's responsible for installing Installing a provider creates a Provider pod that's responsible for installing
the Provider's APIs into the Kubernetes cluster. Providers constantly watch the the Provider's APIs into the Kubernetes cluster. Providers constantly watch the
state of the desired managed resources and create any external resources that state of the desired managed resources and create any external resources that
are missing. are missing.
Install a Provider with a Crossplane Install a Provider with a Crossplane
{{<hover label="install" line="2">}}Provider{{</hover >}} object setting the {{<hover label="install" line="2">}}Provider{{</hover >}} object setting the
{{<hover label="install" line="6">}}spec.package{{</hover >}} value to the {{<hover label="install" line="6">}}spec.package{{</hover >}} value to the
location of the provider package. location of the provider package.
For example, to install the For example, to install the
[AWS Community Provider](https://github.com/crossplane-contrib/provider-aws), [AWS Community Provider](https://github.com/crossplane-contrib/provider-aws),
```yaml {label="install"} ```yaml {label="install"}
@ -71,12 +72,12 @@ By default, the Provider pod installs in the same namespace as Crossplane
### Install with Helm ### Install with Helm
Crossplane supports installing Providers during an initial Crossplane Crossplane supports installing Providers during an initial Crossplane
installation with the Crossplane Helm chart. installation with the Crossplane Helm chart.
Use the Use the
{{<hover label="helm" line="5" >}}--set provider.packages{{</hover >}} {{<hover label="helm" line="5" >}}--set provider.packages{{</hover >}}
argument with `helm install`. argument with `helm install`.
For example, to install the AWS Community Provider, For example, to install the AWS Community Provider,
@ -92,7 +93,7 @@ crossplane-stable/crossplane \
Installing a Provider from a private package repository requires a Installing a Provider from a private package repository requires a
Kubernetes secret object. The Provider uses the secret with the Kubernetes secret object. The Provider uses the secret with the
{{<hover label="pps" line="7" >}}packagePullSecrets{{</hover>}} option. {{<hover label="pps" line="7" >}}packagePullSecrets{{</hover>}} option.
```yaml {label="pps"} ```yaml {label="pps"}
apiVersion: pkg.crossplane.io/v1 apiVersion: pkg.crossplane.io/v1
@ -115,31 +116,31 @@ the Crossplane pod.
To upgrade an existing Provider edit the installed Provider Package by either To upgrade an existing Provider edit the installed Provider Package by either
applying a new Provider manifest or with `kubectl edit providers`. applying a new Provider manifest or with `kubectl edit providers`.
Update the version number in the Provider's `spec.package` and apply the change. Update the version number in the Provider's `spec.package` and apply the change.
Crossplane installs the new image and creates a new `ProviderRevision`. Crossplane installs the new image and creates a new `ProviderRevision`.
## Remove a Provider ## Remove a Provider
Remove a Provider by deleting the Provider object with `kubectl delete Remove a Provider by deleting the Provider object with `kubectl delete
provider`. provider`.
{{< hint "warning" >}} {{< hint "warning" >}}
Removing a Provider without first removing the Provider's managed resources Removing a Provider without first removing the Provider's managed resources
may abandon the resources. The external resources aren't deleted. may abandon the resources. The external resources aren't deleted.
If you remove the Provider first, you must manually delete external resources If you remove the Provider first, you must manually delete external resources
through your cloud provider. Managed resources must be manually deleted by through your cloud provider. Managed resources must be manually deleted by
removing their finalizers. 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" >}}). For more information on deleting abandoned resources read the [Crossplane troubleshooting guide]({{<ref "/knowledge-base/guides/troubleshoot#deleting-when-a-resource-hangs" >}}).
{{< /hint >}} {{< /hint >}}
## Verify a Provider ## Verify a Provider
Providers install their own APIs representing the managed resources they support. Providers install their own APIs representing the managed resources they support.
Providers may also create Deployments, Service Accounts or RBAC configuration. Providers may also create Deployments, Service Accounts or RBAC configuration.
View the status of a Provider with View the status of a Provider with
`kubectl get providers` `kubectl get providers`
@ -164,16 +165,17 @@ crossplane-contrib-provider-aws True True xpkg.upbound.io/crosspla
{{<hint "important" >}} {{<hint "important" >}}
Some Providers install hundreds of Kubernetes Custom Resource Definitions (`CRDs`). Some Providers install hundreds of Kubernetes Custom Resource Definitions (`CRDs`).
This can create significant strain on undersized API Servers, impacting Provider This can create significant strain on undersized API Servers, impacting Provider
install times. install times.
The Crossplane community has more The Crossplane community has more
[details on scaling CRDs](https://github.com/crossplane/crossplane/blob/master/design/one-pager-crd-scaling.md). [details on scaling CRDs](https://github.com/crossplane/crossplane/blob/master/design/one-pager-crd-scaling.md).
{{< /hint >}} {{< /hint >}}
### Provider conditions ### Provider conditions
Crossplane uses a standard set of `Conditions` for Providers. Crossplane uses a standard set of `Conditions` for Providers.
View the conditions of a provider under their `Status` with View the conditions of a provider under their `Status` with
`kubectl describe provider`. `kubectl describe provider`.
```yaml ```yaml
kubectl describe provider kubectl describe provider
@ -193,17 +195,21 @@ Status:
``` ```
#### Types #### Types
Provider `Conditions` support two `Types`: Provider `Conditions` support two `Types`:
* `Type: Installed` - the Provider package installed but isn't ready for use. * `Type: Installed` - the Provider package installed but isn't ready for use.
* `Type: Healthy` - The Provider package is ready to use. * `Type: Healthy` - The Provider package is ready to use.
#### Reasons #### Reasons
Each `Reason` relates to a specific `Type` and `Status`. Crossplane uses the Each `Reason` relates to a specific `Type` and `Status`. Crossplane uses the
following `Reasons` for Provider `Conditions`. following `Reasons` for Provider `Conditions`.
<!-- vale Google.Headings = NO --> <!-- vale Google.Headings = NO -->
##### InactivePackageRevision ##### InactivePackageRevision
`Reason: InactivePackageRevision` indicates the Provider Package is using an
`Reason: InactivePackageRevision` indicates the Provider Package is using an
inactive Provider Package Revision. inactive Provider Package Revision.
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
@ -217,10 +223,10 @@ Reason: InactivePackageRevision
##### ActivePackageRevision ##### ActivePackageRevision
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
The Provider Package is the current Package Revision, but Crossplane hasn't The Provider Package is the current Package Revision, but Crossplane hasn't
finished installing the Package Revision yet. finished installing the Package Revision yet.
{{< hint "tip" >}} {{< hint "tip" >}}
Providers stuck in this state are because of a problem with Package Revisions. Providers stuck in this state are because of a problem with Package Revisions.
Use `kubectl describe providerrevisions` for more details. Use `kubectl describe providerrevisions` for more details.
{{< /hint >}} {{< /hint >}}
@ -233,6 +239,7 @@ Reason: ActivePackageRevision
<!-- vale Google.Headings = NO --> <!-- vale Google.Headings = NO -->
##### HealthyPackageRevision ##### HealthyPackageRevision
The Provider is fully installed and ready to use. The Provider is fully installed and ready to use.
{{<hint "tip" >}} {{<hint "tip" >}}
@ -251,7 +258,7 @@ Reason: HealthyPackageRevision
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
There was an error installing the Provider Package Revision, preventing There was an error installing the Provider Package Revision, preventing
Crossplane from installing the Provider Package. Crossplane from installing the Provider Package.
{{<hint "tip" >}} {{<hint "tip" >}}
Use `kubectl describe providerrevisions` for more details on why the Package Use `kubectl describe providerrevisions` for more details on why the Package
@ -267,9 +274,8 @@ Reason: UnhealthyPackageRevision
##### UnknownPackageRevisionHealth ##### UnknownPackageRevisionHealth
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
The status of the Provider Package Revision is `Unknown`. The Provider Package The status of the Provider Package Revision is `Unknown`. The Provider Package
Revision may be installing or has an issue. Revision may be installing or has an issue.
{{<hint "tip" >}} {{<hint "tip" >}}
Use `kubectl describe providerrevisions` for more details on why the Package Use `kubectl describe providerrevisions` for more details on why the Package
@ -285,10 +291,11 @@ Reason: UnknownPackageRevisionHealth
## Configure a Provider ## Configure a Provider
Providers have two different types of configurations: Providers have two different types of configurations:
* _Controller configurations_ that change the settings of the Provider pod * _Controller configurations_ that change the settings of the Provider pod
running inside the Kubernetes cluster. For example, Pod `toleration`. running inside the Kubernetes cluster. For example, Pod `toleration`.
* _Provider configurations_ that change settings used when communicating with * _Provider configurations_ that change settings used when communicating with
an external provider. For example, cloud provider authentication. an external provider. For example, cloud provider authentication.
{{<hint "important" >}} {{<hint "important" >}}
Apply `ControllerConfig` objects to Providers. Apply `ControllerConfig` objects to Providers.
@ -296,22 +303,26 @@ Apply `ControllerConfig` objects to Providers.
Apply `ProviderConfig` objects to managed resources. Apply `ProviderConfig` objects to managed resources.
{{< /hint >}} {{< /hint >}}
### Controller configuration ### Controller configuration
{{< hint "important" >}} {{< hint "important" >}}
The Crossplane community deprecated the `ControllerConfig` type in v1.11. The Crossplane community deprecated the `ControllerConfig` type in v1.11 to
Applying a Controller configuration generates a deprecation warning. 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 Controller configurations are still supported until there is a replacement type
in a future Crossplane version. in a future Crossplane version. You can read more about the design of
[Package Runtime Config](https://github.com/crossplane/crossplane/blob/master/design/one-pager-package-runtime-config.md)
which will replace it in the future.
{{< /hint >}} {{< /hint >}}
Applying a Crossplane `ControllerConfig` to a Provider changes the settings of Applying a Crossplane `ControllerConfig` to a Provider changes the settings of
the Provider's pod. The the Provider's pod. The
[Crossplane ControllerConfig schema](https://doc.crds.dev/github.com/crossplane/crossplane/pkg.crossplane.io/ControllerConfig/v1alpha1) [Crossplane ControllerConfig schema](https://doc.crds.dev/github.com/crossplane/crossplane/pkg.crossplane.io/ControllerConfig/v1alpha1)
defines the supported set of ControllerConfig settings. defines the supported set of ControllerConfig settings.
The most common use case for ControllerConfigs are providing `args` to a The most common use case for ControllerConfigs are providing `args` to a
Provider's pod enabling optional services. For example, enabling Provider's pod enabling optional services. For example, enabling
[external secret stores](https://docs.crossplane.io/knowledge-base/integrations/vault-as-secret-store/#enable-external-secret-stores-in-the-provider) [external secret stores](https://docs.crossplane.io/knowledge-base/integrations/vault-as-secret-store/#enable-external-secret-stores-in-the-provider)
for a Provider. for a Provider.
@ -320,20 +331,20 @@ Each Provider determines their supported set of `args`.
### Provider configuration ### Provider configuration
The `ProviderConfig` determines settings the Provider uses communicating to the The `ProviderConfig` determines settings the Provider uses communicating to the
external provider. Each Provider determines available settings of their external provider. Each Provider determines available settings of their
`ProviderConfig`. `ProviderConfig`.
<!-- vale write-good.Weasel = NO --> <!-- vale write-good.Weasel = NO -->
<!-- allow "usually" --> <!-- allow "usually" -->
Provider authentication is usually configured with a `ProviderConfig`. For Provider authentication is usually configured with a `ProviderConfig`. For
example, to use basic key-pair authentication with Provider AWS a example, to use basic key-pair authentication with Provider AWS a
{{<hover label="providerconfig" line="2" >}}ProviderConfig{{</hover >}} {{<hover label="providerconfig" line="2" >}}ProviderConfig{{</hover >}}
{{<hover label="providerconfig" line="5" >}}spec{{</hover >}} {{<hover label="providerconfig" line="5" >}}spec{{</hover >}}
defines the defines the
{{<hover label="providerconfig" line="6" >}}credentials{{</hover >}} and that {{<hover label="providerconfig" line="6" >}}credentials{{</hover >}} and that
the Provider pod should look in the Kubernetes the Provider pod should look in the Kubernetes
{{<hover label="providerconfig" line="7" >}}Secrets{{</hover >}} objects and use {{<hover label="providerconfig" line="7" >}}Secrets{{</hover >}} objects and use
the key named the key named
{{<hover label="providerconfig" line="10" >}}aws-creds{{</hover >}}. {{<hover label="providerconfig" line="10" >}}aws-creds{{</hover >}}.
<!-- vale write-good.Weasel = YES --> <!-- vale write-good.Weasel = YES -->
```yaml {label="providerconfig"} ```yaml {label="providerconfig"}
@ -351,23 +362,23 @@ spec:
``` ```
{{< hint "important" >}} {{< hint "important" >}}
Authentication configuration may be different across Providers. Authentication configuration may be different across Providers.
Read the documentation on a specific Provider for instructions on configuring Read the documentation on a specific Provider for instructions on configuring
authentication for that Provider. authentication for that Provider.
{{< /hint >}} {{< /hint >}}
<!-- vale write-good.TooWordy = NO --> <!-- vale write-good.TooWordy = NO -->
<!-- allow multiple --> <!-- allow multiple -->
ProviderConfig objects apply to individual Managed Resources. A single ProviderConfig objects apply to individual Managed Resources. A single
Provider can authenticate with multiple users or accounts through Provider can authenticate with multiple users or accounts through
ProviderConfigs. ProviderConfigs.
<!-- vale write-good.TooWordy = YES --> <!-- vale write-good.TooWordy = YES -->
Each account's credentials tie to a unique ProviderConfig. When creating a Each account's credentials tie to a unique ProviderConfig. When creating a
managed resource, attach the desired ProviderConfig. managed resource, attach the desired ProviderConfig.
For example, two AWS ProviderConfigs, named For example, two AWS ProviderConfigs, named
{{<hover label="user" line="4">}}user-keys{{</hover >}} and {{<hover label="user" line="4">}}user-keys{{</hover >}} and
{{<hover label="admin" line="4">}}admin-keys{{</hover >}} {{<hover label="admin" line="4">}}admin-keys{{</hover >}}
use different Kubernetes secrets. use different Kubernetes secrets.
@ -403,7 +414,7 @@ spec:
Apply the ProviderConfig when creating a managed resource. Apply the ProviderConfig when creating a managed resource.
This creates an AWS {{<hover label="user-bucket" line="2" >}}Bucket{{< /hover >}} This creates an AWS {{<hover label="user-bucket" line="2" >}}Bucket{{< /hover >}}
resource using the resource using the
{{<hover label="user-bucket" line="9" >}}user-keys{{< /hover >}} ProviderConfig. {{<hover label="user-bucket" line="9" >}}user-keys{{< /hover >}} ProviderConfig.
```yaml {label="user-bucket"} ```yaml {label="user-bucket"}
@ -419,7 +430,7 @@ spec:
``` ```
This creates a second {{<hover label="admin-bucket" line="2" >}}Bucket{{< /hover >}} This creates a second {{<hover label="admin-bucket" line="2" >}}Bucket{{< /hover >}}
resource using the resource using the
{{<hover label="admin-bucket" line="9" >}}admin-keys{{< /hover >}} ProviderConfig. {{<hover label="admin-bucket" line="9" >}}admin-keys{{< /hover >}} ProviderConfig.
```yaml {label="admin-bucket"} ```yaml {label="admin-bucket"}
@ -433,4 +444,3 @@ spec:
providerConfigRef: providerConfigRef:
name: admin-keys name: admin-keys
``` ```