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
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.
Providers are responsible for all aspects of connecting to non-Kubernetes
@ -15,6 +15,7 @@ providing
logic for any external resources.
Examples of providers include:
* [Provider AWS](https://github.com/upbound/provider-aws)
* [Provider Azure](https://github.com/upbound/provider-azure)
* [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 -->
<!-- "are Managed" isn't passive in this context -->
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" >}}).
<!-- vale write-good.Passive = YES -->
@ -42,14 +43,14 @@ for more information.
Installing a provider creates a Provider pod that's responsible for installing
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.
are missing.
Install a Provider with a Crossplane
{{<hover label="install" line="2">}}Provider{{</hover >}} object setting the
{{<hover label="install" line="6">}}spec.package{{</hover >}} value to the
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),
```yaml {label="install"}
@ -71,12 +72,12 @@ By default, the Provider pod installs in the same namespace as Crossplane
### 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.
Use the
{{<hover label="helm" line="5" >}}--set provider.packages{{</hover >}}
argument with `helm install`.
Use the
{{<hover label="helm" line="5" >}}--set provider.packages{{</hover >}}
argument with `helm install`.
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
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"}
apiVersion: pkg.crossplane.io/v1
@ -115,31 +116,31 @@ the Crossplane pod.
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.
Update the version number in the Provider's `spec.package` and apply the change.
Crossplane installs the new image and creates a new `ProviderRevision`.
## Remove a Provider
Remove a Provider by deleting the Provider object with `kubectl delete
provider`.
provider`.
{{< 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.
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.
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" >}}).
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.
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`
@ -164,16 +165,17 @@ crossplane-contrib-provider-aws True True xpkg.upbound.io/crosspla
{{<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.
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).
{{< /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`.
View the conditions of a provider under their `Status` with
`kubectl describe provider`.
```yaml
kubectl describe provider
@ -193,17 +195,21 @@ Status:
```
#### 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.
* `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`.
<!-- vale Google.Headings = NO -->
##### InactivePackageRevision
`Reason: InactivePackageRevision` indicates the Provider Package is using an
`Reason: InactivePackageRevision` indicates the Provider Package is using an
inactive Provider Package Revision.
<!-- vale Google.Headings = YES -->
@ -217,10 +223,10 @@ Reason: InactivePackageRevision
##### ActivePackageRevision
<!-- vale Google.Headings = YES -->
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" >}}
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.
{{< /hint >}}
@ -233,6 +239,7 @@ Reason: ActivePackageRevision
<!-- vale Google.Headings = NO -->
##### HealthyPackageRevision
The Provider is fully installed and ready to use.
{{<hint "tip" >}}
@ -251,7 +258,7 @@ Reason: HealthyPackageRevision
<!-- vale Google.Headings = YES -->
There was an error installing the Provider Package Revision, preventing
Crossplane from installing the Provider Package.
Crossplane from installing the Provider Package.
{{<hint "tip" >}}
Use `kubectl describe providerrevisions` for more details on why the Package
@ -267,9 +274,8 @@ Reason: UnhealthyPackageRevision
##### UnknownPackageRevisionHealth
<!-- vale Google.Headings = YES -->
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" >}}
Use `kubectl describe providerrevisions` for more details on why the Package
@ -285,10 +291,11 @@ 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, Pod `toleration`.
running inside the Kubernetes cluster. For example, Pod `toleration`.
* _Provider configurations_ that change settings used when communicating with
an external provider. For example, cloud provider authentication.
an external provider. For example, cloud provider authentication.
{{<hint "important" >}}
Apply `ControllerConfig` objects to Providers.
@ -296,22 +303,27 @@ Apply `ControllerConfig` objects to Providers.
Apply `ProviderConfig` objects to managed resources.
{{< /hint >}}
### Controller configuration
### Controller configuration
{{< hint "important" >}}
The Crossplane community deprecated the `ControllerConfig` type in v1.11.
Applying a Controller configuration generates a deprecation warning.
The Crossplane community deprecated the `ControllerConfig` type in v1.11 to
indicate that no further enhancements will be made to it.
Applying a Controller configuration generates a deprecation warning.
Controller configurations are still supported until there is a replacement type
in a future Crossplane version.
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 >}}
Applying a Crossplane `ControllerConfig` to a Provider changes the settings of
the Provider's pod. The
[Crossplane ControllerConfig schema](https://doc.crds.dev/github.com/crossplane/crossplane/pkg.crossplane.io/ControllerConfig/v1alpha1)
defines the supported set of ControllerConfig settings.
[Crossplane ControllerConfig schema](https://doc.crds.dev/github.com/crossplane/crossplane/pkg.crossplane.io/ControllerConfig/v1alpha1)
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
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)
for a Provider.
@ -320,20 +332,20 @@ 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
external provider. Each Provider determines available settings of their
`ProviderConfig`.
<!-- vale write-good.Weasel = NO -->
<!-- allow "usually" -->
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="5" >}}spec{{</hover >}}
defines the
defines the
{{<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
the key named
the key named
{{<hover label="providerconfig" line="10" >}}aws-creds{{</hover >}}.
<!-- vale write-good.Weasel = YES -->
```yaml {label="providerconfig"}
@ -351,23 +363,23 @@ spec:
```
{{< 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
authentication for that Provider.
Read the documentation on a specific Provider for instructions on configuring
authentication for that Provider.
{{< /hint >}}
<!-- vale write-good.TooWordy = NO -->
<!-- allow multiple -->
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.
<!-- vale write-good.TooWordy = YES -->
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="admin" line="4">}}admin-keys{{</hover >}}
use different Kubernetes secrets.
@ -403,7 +415,7 @@ spec:
Apply the ProviderConfig when creating a managed resource.
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.
```yaml {label="user-bucket"}
@ -419,7 +431,7 @@ spec:
```
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.
```yaml {label="admin-bucket"}
@ -433,4 +445,3 @@ spec:
providerConfigRef:
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
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.
Providers are responsible for all aspects of connecting to non-Kubernetes
@ -14,6 +14,7 @@ providing
logic for any external resources.
Examples of providers include:
* [Provider AWS](https://github.com/upbound/provider-aws)
* [Provider Azure](https://github.com/upbound/provider-azure)
* [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 -->
<!-- "are Managed" isn't passive in this context -->
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" >}}).
<!-- vale write-good.Passive = YES -->
@ -42,14 +43,14 @@ for more information.
Installing a provider creates a Provider pod that's responsible for installing
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.
are missing.
Install a Provider with a Crossplane
{{<hover label="install" line="2">}}Provider{{</hover >}} object setting the
{{<hover label="install" line="6">}}spec.package{{</hover >}} value to the
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),
```yaml {label="install"}
@ -71,12 +72,12 @@ By default, the Provider pod installs in the same namespace as Crossplane
### 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.
Use the
{{<hover label="helm" line="5" >}}--set provider.packages{{</hover >}}
argument with `helm install`.
Use the
{{<hover label="helm" line="5" >}}--set provider.packages{{</hover >}}
argument with `helm install`.
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
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"}
apiVersion: pkg.crossplane.io/v1
@ -115,32 +116,32 @@ the Crossplane pod.
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.
Update the version number in the Provider's `spec.package` and apply the change.
Crossplane installs the new image and creates a new `ProviderRevision`.
## Remove a Provider
Remove a Provider by deleting the Provider object with `kubectl delete
provider`.
provider`.
{{< 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.
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.
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" >}}).
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.
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`
@ -165,16 +166,17 @@ crossplane-contrib-provider-aws True True xpkg.upbound.io/crosspla
{{<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.
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).
{{< /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`.
View the conditions of a provider under their `Status` with
`kubectl describe provider`.
```yaml
kubectl describe provider
@ -194,17 +196,21 @@ Status:
```
#### 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.
* `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`.
<!-- vale Google.Headings = NO -->
##### InactivePackageRevision
`Reason: InactivePackageRevision` indicates the Provider Package is using an
`Reason: InactivePackageRevision` indicates the Provider Package is using an
inactive Provider Package Revision.
<!-- vale Google.Headings = YES -->
@ -218,10 +224,10 @@ Reason: InactivePackageRevision
##### ActivePackageRevision
<!-- vale Google.Headings = YES -->
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" >}}
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.
{{< /hint >}}
@ -234,6 +240,7 @@ Reason: ActivePackageRevision
<!-- vale Google.Headings = NO -->
##### HealthyPackageRevision
The Provider is fully installed and ready to use.
{{<hint "tip" >}}
@ -252,7 +259,7 @@ Reason: HealthyPackageRevision
<!-- vale Google.Headings = YES -->
There was an error installing the Provider Package Revision, preventing
Crossplane from installing the Provider Package.
Crossplane from installing the Provider Package.
{{<hint "tip" >}}
Use `kubectl describe providerrevisions` for more details on why the Package
@ -268,9 +275,8 @@ Reason: UnhealthyPackageRevision
##### UnknownPackageRevisionHealth
<!-- vale Google.Headings = YES -->
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" >}}
Use `kubectl describe providerrevisions` for more details on why the Package
@ -286,10 +292,11 @@ 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, Pod `toleration`.
running inside the Kubernetes cluster. For example, Pod `toleration`.
* _Provider configurations_ that change settings used when communicating with
an external provider. For example, cloud provider authentication.
an external provider. For example, cloud provider authentication.
{{<hint "important" >}}
Apply `ControllerConfig` objects to Providers.
@ -297,22 +304,26 @@ Apply `ControllerConfig` objects to Providers.
Apply `ProviderConfig` objects to managed resources.
{{< /hint >}}
### Controller configuration
### Controller configuration
{{< hint "important" >}}
The Crossplane community deprecated the `ControllerConfig` type in v1.11.
Applying a Controller configuration generates a deprecation warning.
The Crossplane community deprecated the `ControllerConfig` type in v1.11 to
indicate that no further enhancements will be made to it.
Applying a Controller configuration generates a deprecation warning.
Controller configurations are still supported until there is a replacement type
in a future Crossplane version.
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 >}}
Applying a Crossplane `ControllerConfig` to a Provider changes the settings of
the Provider's pod. The
[Crossplane ControllerConfig schema](https://doc.crds.dev/github.com/crossplane/crossplane/pkg.crossplane.io/ControllerConfig/v1alpha1)
defines the supported set of ControllerConfig settings.
[Crossplane ControllerConfig schema](https://doc.crds.dev/github.com/crossplane/crossplane/pkg.crossplane.io/ControllerConfig/v1alpha1)
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
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)
for a Provider.
@ -321,20 +332,20 @@ 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
external provider. Each Provider determines available settings of their
`ProviderConfig`.
<!-- vale write-good.Weasel = NO -->
<!-- allow "usually" -->
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="5" >}}spec{{</hover >}}
defines the
defines the
{{<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
the key named
the key named
{{<hover label="providerconfig" line="10" >}}aws-creds{{</hover >}}.
<!-- vale write-good.Weasel = YES -->
```yaml {label="providerconfig"}
@ -352,23 +363,23 @@ spec:
```
{{< 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
authentication for that Provider.
Read the documentation on a specific Provider for instructions on configuring
authentication for that Provider.
{{< /hint >}}
<!-- vale write-good.TooWordy = NO -->
<!-- allow multiple -->
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.
<!-- vale write-good.TooWordy = YES -->
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="admin" line="4">}}admin-keys{{</hover >}}
use different Kubernetes secrets.
@ -404,7 +415,7 @@ spec:
Apply the ProviderConfig when creating a managed resource.
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.
```yaml {label="user-bucket"}
@ -420,7 +431,7 @@ spec:
```
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.
```yaml {label="admin-bucket"}
@ -434,4 +445,3 @@ spec:
providerConfigRef:
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
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.
Providers are responsible for all aspects of connecting to non-Kubernetes
@ -14,6 +14,7 @@ providing
logic for any external resources.
Examples of providers include:
* [Provider AWS](https://github.com/upbound/provider-aws)
* [Provider Azure](https://github.com/upbound/provider-azure)
* [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 -->
<!-- "are Managed" isn't passive in this context -->
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" >}}).
<!-- vale write-good.Passive = YES -->
@ -42,14 +43,14 @@ for more information.
Installing a provider creates a Provider pod that's responsible for installing
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.
are missing.
Install a Provider with a Crossplane
{{<hover label="install" line="2">}}Provider{{</hover >}} object setting the
{{<hover label="install" line="6">}}spec.package{{</hover >}} value to the
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),
```yaml {label="install"}
@ -71,12 +72,12 @@ By default, the Provider pod installs in the same namespace as Crossplane
### 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.
Use the
{{<hover label="helm" line="5" >}}--set provider.packages{{</hover >}}
argument with `helm install`.
Use the
{{<hover label="helm" line="5" >}}--set provider.packages{{</hover >}}
argument with `helm install`.
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
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"}
apiVersion: pkg.crossplane.io/v1
@ -115,32 +116,32 @@ the Crossplane pod.
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.
Update the version number in the Provider's `spec.package` and apply the change.
Crossplane installs the new image and creates a new `ProviderRevision`.
## Remove a Provider
Remove a Provider by deleting the Provider object with `kubectl delete
provider`.
provider`.
{{< 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.
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.
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" >}}).
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.
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`
@ -165,16 +166,17 @@ crossplane-contrib-provider-aws True True xpkg.upbound.io/crosspla
{{<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.
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).
{{< /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`.
View the conditions of a provider under their `Status` with
`kubectl describe provider`.
```yaml
kubectl describe provider
@ -194,17 +196,21 @@ Status:
```
#### 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.
* `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`.
<!-- vale Google.Headings = NO -->
##### InactivePackageRevision
`Reason: InactivePackageRevision` indicates the Provider Package is using an
`Reason: InactivePackageRevision` indicates the Provider Package is using an
inactive Provider Package Revision.
<!-- vale Google.Headings = YES -->
@ -218,10 +224,10 @@ Reason: InactivePackageRevision
##### ActivePackageRevision
<!-- vale Google.Headings = YES -->
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" >}}
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.
{{< /hint >}}
@ -234,6 +240,7 @@ Reason: ActivePackageRevision
<!-- vale Google.Headings = NO -->
##### HealthyPackageRevision
The Provider is fully installed and ready to use.
{{<hint "tip" >}}
@ -252,7 +259,7 @@ Reason: HealthyPackageRevision
<!-- vale Google.Headings = YES -->
There was an error installing the Provider Package Revision, preventing
Crossplane from installing the Provider Package.
Crossplane from installing the Provider Package.
{{<hint "tip" >}}
Use `kubectl describe providerrevisions` for more details on why the Package
@ -268,9 +275,8 @@ Reason: UnhealthyPackageRevision
##### UnknownPackageRevisionHealth
<!-- vale Google.Headings = YES -->
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" >}}
Use `kubectl describe providerrevisions` for more details on why the Package
@ -286,10 +292,11 @@ 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, Pod `toleration`.
running inside the Kubernetes cluster. For example, Pod `toleration`.
* _Provider configurations_ that change settings used when communicating with
an external provider. For example, cloud provider authentication.
an external provider. For example, cloud provider authentication.
{{<hint "important" >}}
Apply `ControllerConfig` objects to Providers.
@ -297,22 +304,26 @@ Apply `ControllerConfig` objects to Providers.
Apply `ProviderConfig` objects to managed resources.
{{< /hint >}}
### Controller configuration
### Controller configuration
{{< hint "important" >}}
The Crossplane community deprecated the `ControllerConfig` type in v1.11.
Applying a Controller configuration generates a deprecation warning.
The Crossplane community deprecated the `ControllerConfig` type in v1.11 to
indicate that no further enhancements will be made to it.
Applying a Controller configuration generates a deprecation warning.
Controller configurations are still supported until there is a replacement type
in a future Crossplane version.
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 >}}
Applying a Crossplane `ControllerConfig` to a Provider changes the settings of
the Provider's pod. The
[Crossplane ControllerConfig schema](https://doc.crds.dev/github.com/crossplane/crossplane/pkg.crossplane.io/ControllerConfig/v1alpha1)
defines the supported set of ControllerConfig settings.
[Crossplane ControllerConfig schema](https://doc.crds.dev/github.com/crossplane/crossplane/pkg.crossplane.io/ControllerConfig/v1alpha1)
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
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)
for a Provider.
@ -321,20 +332,20 @@ 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
external provider. Each Provider determines available settings of their
`ProviderConfig`.
<!-- vale write-good.Weasel = NO -->
<!-- allow "usually" -->
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="5" >}}spec{{</hover >}}
defines the
defines the
{{<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
the key named
the key named
{{<hover label="providerconfig" line="10" >}}aws-creds{{</hover >}}.
<!-- vale write-good.Weasel = YES -->
```yaml {label="providerconfig"}
@ -352,24 +363,24 @@ spec:
```
{{< 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
authentication for that Provider.
Read the documentation on a specific Provider for instructions on configuring
authentication for that Provider.
{{< /hint >}}
<!-- vale write-good.TooWordy = NO -->
<!-- allow multiple -->
ProviderConfig objects apply to individual managed resources with a
[`providerConfigRef`]({{<ref "../concepts/managed-resources#providerconfigref" >}}).
A single Provider can authenticate with multiple users or accounts through
ProviderConfig objects apply to individual managed resources with a
[`providerConfigRef`]({{<ref "../concepts/managed-resources#providerconfigref" >}}).
A single Provider can authenticate with multiple users or accounts through
ProviderConfigs.
<!-- vale write-good.TooWordy = YES -->
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="admin" line="4">}}admin-keys{{</hover >}}
use different Kubernetes secrets.
@ -405,7 +416,7 @@ spec:
Apply the ProviderConfig when creating a managed resource.
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.
```yaml {label="user-bucket"}
@ -421,7 +432,7 @@ spec:
```
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.
```yaml {label="admin-bucket"}
@ -435,4 +446,3 @@ spec:
providerConfigRef:
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
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.
Providers are responsible for all aspects of connecting to non-Kubernetes
@ -15,6 +15,7 @@ providing
logic for any external resources.
Examples of providers include:
* [Provider AWS](https://github.com/upbound/provider-aws)
* [Provider Azure](https://github.com/upbound/provider-azure)
* [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 -->
<!-- "are Managed" isn't passive in this context -->
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" >}}).
<!-- vale write-good.Passive = YES -->
@ -42,14 +43,14 @@ for more information.
Installing a provider creates a Provider pod that's responsible for installing
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.
are missing.
Install a Provider with a Crossplane
{{<hover label="install" line="2">}}Provider{{</hover >}} object setting the
{{<hover label="install" line="6">}}spec.package{{</hover >}} value to the
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),
```yaml {label="install"}
@ -71,12 +72,12 @@ By default, the Provider pod installs in the same namespace as Crossplane
### 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.
Use the
{{<hover label="helm" line="5" >}}--set provider.packages{{</hover >}}
argument with `helm install`.
Use the
{{<hover label="helm" line="5" >}}--set provider.packages{{</hover >}}
argument with `helm install`.
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
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"}
apiVersion: pkg.crossplane.io/v1
@ -115,31 +116,31 @@ the Crossplane pod.
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.
Update the version number in the Provider's `spec.package` and apply the change.
Crossplane installs the new image and creates a new `ProviderRevision`.
## Remove a Provider
Remove a Provider by deleting the Provider object with `kubectl delete
provider`.
provider`.
{{< 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.
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.
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" >}}).
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.
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`
@ -164,16 +165,17 @@ crossplane-contrib-provider-aws True True xpkg.upbound.io/crosspla
{{<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.
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).
{{< /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`.
View the conditions of a provider under their `Status` with
`kubectl describe provider`.
```yaml
kubectl describe provider
@ -193,17 +195,21 @@ Status:
```
#### 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.
* `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`.
<!-- vale Google.Headings = NO -->
##### InactivePackageRevision
`Reason: InactivePackageRevision` indicates the Provider Package is using an
`Reason: InactivePackageRevision` indicates the Provider Package is using an
inactive Provider Package Revision.
<!-- vale Google.Headings = YES -->
@ -217,10 +223,10 @@ Reason: InactivePackageRevision
##### ActivePackageRevision
<!-- vale Google.Headings = YES -->
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" >}}
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.
{{< /hint >}}
@ -233,6 +239,7 @@ Reason: ActivePackageRevision
<!-- vale Google.Headings = NO -->
##### HealthyPackageRevision
The Provider is fully installed and ready to use.
{{<hint "tip" >}}
@ -251,7 +258,7 @@ Reason: HealthyPackageRevision
<!-- vale Google.Headings = YES -->
There was an error installing the Provider Package Revision, preventing
Crossplane from installing the Provider Package.
Crossplane from installing the Provider Package.
{{<hint "tip" >}}
Use `kubectl describe providerrevisions` for more details on why the Package
@ -267,9 +274,8 @@ Reason: UnhealthyPackageRevision
##### UnknownPackageRevisionHealth
<!-- vale Google.Headings = YES -->
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" >}}
Use `kubectl describe providerrevisions` for more details on why the Package
@ -285,10 +291,11 @@ 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, Pod `toleration`.
running inside the Kubernetes cluster. For example, Pod `toleration`.
* _Provider configurations_ that change settings used when communicating with
an external provider. For example, cloud provider authentication.
an external provider. For example, cloud provider authentication.
{{<hint "important" >}}
Apply `ControllerConfig` objects to Providers.
@ -296,22 +303,26 @@ Apply `ControllerConfig` objects to Providers.
Apply `ProviderConfig` objects to managed resources.
{{< /hint >}}
### Controller configuration
### Controller configuration
{{< hint "important" >}}
The Crossplane community deprecated the `ControllerConfig` type in v1.11.
Applying a Controller configuration generates a deprecation warning.
The Crossplane community deprecated the `ControllerConfig` type in v1.11 to
indicate that no further enhancements will be made to it.
Applying a Controller configuration generates a deprecation warning.
Controller configurations are still supported until there is a replacement type
in a future Crossplane version.
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 >}}
Applying a Crossplane `ControllerConfig` to a Provider changes the settings of
the Provider's pod. The
[Crossplane ControllerConfig schema](https://doc.crds.dev/github.com/crossplane/crossplane/pkg.crossplane.io/ControllerConfig/v1alpha1)
defines the supported set of ControllerConfig settings.
[Crossplane ControllerConfig schema](https://doc.crds.dev/github.com/crossplane/crossplane/pkg.crossplane.io/ControllerConfig/v1alpha1)
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
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)
for a Provider.
@ -320,20 +331,20 @@ 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
external provider. Each Provider determines available settings of their
`ProviderConfig`.
<!-- vale write-good.Weasel = NO -->
<!-- allow "usually" -->
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="5" >}}spec{{</hover >}}
defines the
defines the
{{<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
the key named
the key named
{{<hover label="providerconfig" line="10" >}}aws-creds{{</hover >}}.
<!-- vale write-good.Weasel = YES -->
```yaml {label="providerconfig"}
@ -351,23 +362,23 @@ spec:
```
{{< 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
authentication for that Provider.
Read the documentation on a specific Provider for instructions on configuring
authentication for that Provider.
{{< /hint >}}
<!-- vale write-good.TooWordy = NO -->
<!-- allow multiple -->
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.
<!-- vale write-good.TooWordy = YES -->
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="admin" line="4">}}admin-keys{{</hover >}}
use different Kubernetes secrets.
@ -403,7 +414,7 @@ spec:
Apply the ProviderConfig when creating a managed resource.
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.
```yaml {label="user-bucket"}
@ -419,7 +430,7 @@ spec:
```
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.
```yaml {label="admin-bucket"}
@ -433,4 +444,3 @@ spec:
providerConfigRef:
name: admin-keys
```