mirror of https://github.com/crossplane/docs.git
Backport Providers update to release versions (#436)
This commit is contained in:
Pete Lumbis
GitHub
parent
e0d897441c
commit
5d6ef67fe7
|
|
@ -3,52 +3,311 @@ title: Providers
|
|||
weight: 101
|
||||
---
|
||||
|
||||
Providers are Crossplane packages that bundle a set of [Managed
|
||||
Resources][managed-resources] and their respective controllers to allow
|
||||
Crossplane to provision the respective infrastructure resource.
|
||||
Providers enable Crossplane to provision infrastructure on an
|
||||
external service. Providers create new Kubernetes APIs and map them to external
|
||||
APIs.
|
||||
|
||||
## Installing Providers
|
||||
Providers are responsible for all aspects of connecting to non-Kubernetes
|
||||
resources. This includes authentication, making external API calls and
|
||||
providing
|
||||
[Kubernetes Controller](https://kubernetes.io/docs/concepts/architecture/controller/)
|
||||
logic for any external resources.
|
||||
|
||||
The core Crossplane controller can install provider controllers and CRDs for you
|
||||
through its own provider packaging mechanism, which is triggered by the
|
||||
application of a `Provider` resource. For example, in order to request
|
||||
installation of the `provider-aws` package, apply the following resource to the
|
||||
cluster where Crossplane is running:
|
||||
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)
|
||||
* [Provider Kubernetes](https://github.com/crossplane-contrib/provider-kubernetes)
|
||||
|
||||
```yaml
|
||||
{{< hint "tip" >}}
|
||||
Find more providers in the [Upbound Marketplace](https://marketplace.upbound.io).
|
||||
{{< /hint >}}
|
||||
|
||||
<!-- 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
|
||||
[_Managed Resources_]({{<ref "managed-resources" >}}).
|
||||
<!-- vale write-good.Passive = YES -->
|
||||
|
||||
{{< hint "note" >}}
|
||||
Instructions on building your own Provider are outside of the scope of this
|
||||
document. Read the Crossplane contributing [Provider Development
|
||||
Guide](https://github.com/crossplane/crossplane/blob/master/contributing/guide-provider-development.md)
|
||||
for more information.
|
||||
{{< /hint >}}
|
||||
|
||||
## Install a Provider
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
[AWS Community Provider](https://github.com/crossplane-contrib/provider-aws),
|
||||
|
||||
```yaml {label="install"}
|
||||
apiVersion: pkg.crossplane.io/v1
|
||||
kind: Provider
|
||||
metadata:
|
||||
name: provider-aws
|
||||
spec:
|
||||
package: "xpkg.upbound.io/crossplane-contrib/provider-aws:v0.33.0"
|
||||
package: xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0
|
||||
```
|
||||
|
||||
The field `spec.package` is where you refer to the container image of the
|
||||
provider. Crossplane Package Manager will unpack that container, register CRDs
|
||||
and set up necessary RBAC rules and then start the controllers.
|
||||
{{< hint "tip" >}}
|
||||
Providers are Crossplane Packages. Read more about Packages in the
|
||||
[Packages documentation]({{<ref "packages" >}}).
|
||||
{{< /hint >}}
|
||||
|
||||
There are a few other ways to to trigger the installation of provider packages:
|
||||
By default, the Provider pod installs in the same namespace as Crossplane
|
||||
(`crossplane-system`).
|
||||
|
||||
* As part of Crossplane Helm chart by adding the following statement to your
|
||||
`helm install` command: `--set
|
||||
provider.packages={xpkg.upbound.io/crossplane-contrib/provider-aws:v0.33.0}`.
|
||||
* Using the Crossplane CLI: `kubectl crossplane install provider
|
||||
xpkg.upbound.io/crossplane-contrib/provider-aws:v0.33.0`
|
||||
### Install with Helm
|
||||
|
||||
You can uninstall a provider by deleting the `Provider` resource
|
||||
you've created.
|
||||
Crossplane supports installing Providers during an initial Crossplane
|
||||
installation with the Crossplane Helm chart.
|
||||
|
||||
## Configuring Providers
|
||||
Use the
|
||||
{{<hover label="helm" line="5" >}}--set provider.packages{{</hover >}}
|
||||
argument with `helm install`.
|
||||
|
||||
In order to authenticate with the external provider API, the provider
|
||||
controllers need to have access to credentials. It could be an IAM User for AWS,
|
||||
a Service Account for GCP or a Service Principal for Azure. Every provider has a
|
||||
type called `ProviderConfig` that has information about how to authenticate to
|
||||
the provider API. An example `ProviderConfig` resource for AWS looks like the
|
||||
following:
|
||||
For example, to install the AWS Community Provider,
|
||||
|
||||
```shell {label="helm"}
|
||||
helm install crossplane \
|
||||
crossplane-stable/crossplane \
|
||||
--namespace crossplane-system \
|
||||
--create-namespace \
|
||||
--set provider.packages={xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0}
|
||||
```
|
||||
|
||||
### Install from a private repository
|
||||
|
||||
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.
|
||||
|
||||
```yaml {label="pps"}
|
||||
apiVersion: pkg.crossplane.io/v1
|
||||
kind: Provider
|
||||
metadata:
|
||||
name: private-provider
|
||||
spec:
|
||||
package: private-repo.example.org/providers/my-provider
|
||||
packagePullSecrets:
|
||||
- name: my-secret
|
||||
```
|
||||
|
||||
{{< hint "note" >}}
|
||||
The Kubernetes secret object the Provider uses must be in the same namespace as
|
||||
the Crossplane pod.
|
||||
{{< /hint >}}
|
||||
|
||||
## Upgrade a Provider
|
||||
|
||||
To upgrade an existing Provider edit the installed Provider Package by either
|
||||
applying a new Provider manifest or with `kubectl edit providers`.
|
||||
|
||||
Update the version number in the Provider's `spec.package` and apply the change.
|
||||
Crossplane installs the new image and creates a new `ProviderRevision`.
|
||||
|
||||
## Remove a Provider
|
||||
|
||||
Remove a Provider by deleting the Provider object with `kubectl delete
|
||||
provider`.
|
||||
|
||||
{{< hint "warning" >}}
|
||||
Removing a Provider without first removing the Provider's managed resources
|
||||
may abandon the resources. The external resources aren't deleted.
|
||||
|
||||
If you remove the Provider first, you must manually delete external resources
|
||||
through your cloud provider. Managed resources must be manually deleted by
|
||||
removing their finalizers.
|
||||
|
||||
For more information on deleting abandoned resources read the [Crossplane
|
||||
troubleshooting guide]({{<ref "/knowledge-base/guides/troubleshoot#deleting-when-a-resource-hangs" >}}).
|
||||
{{< /hint >}}
|
||||
|
||||
## Verify a Provider
|
||||
|
||||
Providers install their own APIs representing the managed resources they support.
|
||||
Providers may also create Deployments, Service Accounts or RBAC configuration.
|
||||
|
||||
View the status of a Provider with
|
||||
|
||||
`kubectl get providers`
|
||||
|
||||
During the install a Provider report `INSTALLED` as `True` and `HEALTHY` as
|
||||
`Unknown`.
|
||||
|
||||
```shell
|
||||
kubectl get providers
|
||||
NAME INSTALLED HEALTHY PACKAGE AGE
|
||||
crossplane-contrib-provider-aws True Unknown xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0 63s
|
||||
```
|
||||
|
||||
After the Provider install completes and it's ready for use the `HEALTHY` status
|
||||
reports `True`.
|
||||
|
||||
```shell
|
||||
kubectl get providers
|
||||
NAME INSTALLED HEALTHY PACKAGE AGE
|
||||
crossplane-contrib-provider-aws True True xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0 88s
|
||||
```
|
||||
|
||||
{{<hint "important" >}}
|
||||
Some Providers install hundreds of Kubernetes Custom Resource Definitions (`CRDs`).
|
||||
This can create significant strain on undersized API Servers, impacting Provider
|
||||
install times.
|
||||
|
||||
The Crossplane community has more
|
||||
[details on scaling CRDs](https://github.com/crossplane/crossplane/blob/master/design/one-pager-crd-scaling.md).
|
||||
{{< /hint >}}
|
||||
### Provider conditions
|
||||
|
||||
View the conditions of a provider under their `Status` with
|
||||
`kubectl describe provider`.
|
||||
|
||||
Providers have the following possible conditions:
|
||||
|
||||
<!-- vale Google.Headings = NO -->
|
||||
#### InactivePackageRevision
|
||||
<!-- vale Google.Headings = YES -->
|
||||
```yaml
|
||||
Type: Installed
|
||||
Status: False
|
||||
Reason: InactivePackageRevision
|
||||
```
|
||||
|
||||
The Provider Package is using an inactive Provider Package Revision.
|
||||
|
||||
<!-- vale Google.Headings = NO -->
|
||||
#### ActivePackageRevision
|
||||
<!-- vale Google.Headings = YES -->
|
||||
```yaml
|
||||
Type: Installed
|
||||
Status: True
|
||||
Reason: ActivePackageRevision
|
||||
```
|
||||
|
||||
The Provider Package is the current Package Revision, but Crossplane hasn't
|
||||
finished installing the Package Revision yet.
|
||||
|
||||
{{< hint "tip" >}}
|
||||
Providers stuck in this state are because of a problem with Package Revisions.
|
||||
|
||||
Use `kubectl describe providerrevisions` for more details.
|
||||
{{< /hint >}}
|
||||
|
||||
<!-- vale Google.Headings = NO -->
|
||||
#### HealthyPackageRevision
|
||||
<!-- vale Google.Headings = YES -->
|
||||
```yaml
|
||||
Type: Healthy
|
||||
Status: True
|
||||
Reason: HealthyPackageRevision
|
||||
```
|
||||
|
||||
The Provider is fully installed and ready to use.
|
||||
|
||||
|
||||
<!-- vale Google.Headings = NO -->
|
||||
#### UnhealthyPackageRevision
|
||||
<!-- vale Google.Headings = YES -->
|
||||
|
||||
```yaml
|
||||
Type: Healthy
|
||||
Status: False
|
||||
Reason: UnhealthyPackageRevision
|
||||
```
|
||||
|
||||
There was an error installing the Provider Package Revision, preventing
|
||||
Crossplane from installing the Provider Package.
|
||||
|
||||
{{<hint "tip" >}}
|
||||
Use `kubectl describe providerrevisions` for more details on why the Package
|
||||
Revision failed.
|
||||
{{< /hint >}}
|
||||
|
||||
<!-- vale Google.Headings = NO -->
|
||||
#### UnknownPackageRevisionHealth
|
||||
<!-- vale Google.Headings = YES -->
|
||||
```yaml
|
||||
Type: Healthy
|
||||
Status: Unknown
|
||||
Reason: UnknownPackageRevisionHealth
|
||||
```
|
||||
|
||||
The status of the Provider Package Revision is `Unknown`. The Provider Package
|
||||
Revision may be installing or has an issue.
|
||||
|
||||
{{<hint "tip" >}}
|
||||
Use `kubectl describe providerrevisions` for more details on why the Package
|
||||
Revision failed.
|
||||
{{< /hint >}}
|
||||
|
||||
## Configure a Provider
|
||||
|
||||
Providers have two different types of configurations:
|
||||
* _Controller configurations_ that change the settings of the Provider pod
|
||||
running inside the Kubernetes cluster. For example, Pod `toleration`.
|
||||
* _Provider configurations_ that change settings used when communicating with
|
||||
an external provider. For example, cloud provider authentication.
|
||||
|
||||
{{<hint "important" >}}
|
||||
Apply `ControllerConfig` objects to Providers.
|
||||
|
||||
Apply `ProviderConfig` objects to managed resources.
|
||||
{{< /hint >}}
|
||||
|
||||
### Controller configuration
|
||||
{{< hint "important" >}}
|
||||
The Crossplane community deprecated the `ControllerConfig` type in v1.11.
|
||||
Applying a Controller configuration generates a deprecation warning.
|
||||
|
||||
Controller configurations are still supported until there is a replacement type
|
||||
in a future Crossplane version.
|
||||
{{< /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.
|
||||
|
||||
The most common use-case for ControllerConfigs are providing `args` to a
|
||||
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.
|
||||
|
||||
Each Provider determines their supported set of `args`.
|
||||
|
||||
### Provider configuration
|
||||
|
||||
The `ProviderConfig` determines settings the Provider uses communicating to the
|
||||
external provider. Each Provider determines available settings of their
|
||||
`ProviderConfig`.
|
||||
|
||||
<!-- 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
|
||||
{{<hover label="providerconfig" line="2" >}}ProviderConfig{{</hover >}}
|
||||
{{<hover label="providerconfig" line="5" >}}spec{{</hover >}}
|
||||
defines the
|
||||
{{<hover label="providerconfig" line="6" >}}credentials{{</hover >}} and that
|
||||
the Provider pod should look in the Kubernetes
|
||||
{{<hover label="providerconfig" line="7" >}}Secrets{{</hover >}} objects and use
|
||||
the key named
|
||||
{{<hover label="providerconfig" line="10" >}}aws-creds{{</hover >}}.
|
||||
<!-- vale write-good.Weasel = YES -->
|
||||
```yaml {label="providerconfig"}
|
||||
apiVersion: aws.crossplane.io/v1beta1
|
||||
kind: ProviderConfig
|
||||
metadata:
|
||||
|
|
@ -62,36 +321,87 @@ spec:
|
|||
key: creds
|
||||
```
|
||||
|
||||
You can see that there is a reference to a key in a specific `Secret`. The value
|
||||
of that key should contain the credentials that the controller will use. The
|
||||
documentation of each provider should give you an idea of how that credentials
|
||||
blob should look like. See [Getting Started][getting-started] guide for more
|
||||
details.
|
||||
{{< hint "important" >}}
|
||||
Authentication configuration may be different across Providers.
|
||||
|
||||
The following is an example usage of AWS `ProviderConfig`, referenced by a
|
||||
`RDSInstance`:
|
||||
Read the documentation on a specific Provider for instructions on configuring
|
||||
authentication for that Provider.
|
||||
{{< /hint >}}
|
||||
|
||||
```yaml
|
||||
apiVersion: database.aws.crossplane.io/v1beta1
|
||||
kind: RDSInstance
|
||||
<!-- 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
|
||||
ProviderConfigs.
|
||||
<!-- vale write-good.TooWordy = YES -->
|
||||
|
||||
Each account's credentials tie to a unique ProviderConfig. When creating a
|
||||
managed resource, attach the desired ProviderConfig.
|
||||
|
||||
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.
|
||||
|
||||
```yaml {label="user"}
|
||||
apiVersion: aws.crossplane.io/v1beta1
|
||||
kind: ProviderConfig
|
||||
metadata:
|
||||
name: prod-sql
|
||||
name: user-keys
|
||||
spec:
|
||||
providerConfigRef:
|
||||
name: aws-provider
|
||||
...
|
||||
credentials:
|
||||
source: Secret
|
||||
secretRef:
|
||||
namespace: crossplane-system
|
||||
name: my-key
|
||||
key: secret-key
|
||||
```
|
||||
|
||||
The AWS provider controller will use that provider for this instance of
|
||||
`RDSInstance`. Since every resource has its own reference to a `ProviderConfig`,
|
||||
you can have multiple `ProviderConfig` resources in your cluster referenced by
|
||||
different resources. When no `providerConfigRef` is specified, the `RDSInstance`
|
||||
will attempt to use a `ProviderConfig` named `default`.
|
||||
```yaml {label="admin"}
|
||||
apiVersion: aws.crossplane.io/v1beta1
|
||||
kind: ProviderConfig
|
||||
metadata:
|
||||
name: admin-keys
|
||||
spec:
|
||||
credentials:
|
||||
source: Secret
|
||||
secretRef:
|
||||
namespace: crossplane-system
|
||||
name: admin-key
|
||||
key: admin-secret-key
|
||||
```
|
||||
|
||||
<!-- Named Links -->
|
||||
Apply the ProviderConfig when creating a managed resource.
|
||||
|
||||
This creates an AWS {{<hover label="user-bucket" line="2" >}}Bucket{{< /hover >}}
|
||||
resource using the
|
||||
{{<hover label="user-bucket" line="9" >}}user-keys{{< /hover >}} ProviderConfig.
|
||||
|
||||
```yaml {label="user-bucket"}
|
||||
apiVersion: s3.aws.upbound.io/v1beta1
|
||||
kind: Bucket
|
||||
metadata:
|
||||
name: user-bucket
|
||||
spec:
|
||||
forProvider:
|
||||
region: us-east-2
|
||||
providerConfigRef:
|
||||
name: user-keys
|
||||
```
|
||||
|
||||
This creates a second {{<hover label="admin-bucket" line="2" >}}Bucket{{< /hover >}}
|
||||
resource using the
|
||||
{{<hover label="admin-bucket" line="9" >}}admin-keys{{< /hover >}} ProviderConfig.
|
||||
|
||||
```yaml {label="admin-bucket"}
|
||||
apiVersion: s3.aws.upbound.io/v1beta1
|
||||
kind: Bucket
|
||||
metadata:
|
||||
name: user-bucket
|
||||
spec:
|
||||
forProvider:
|
||||
region: us-east-2
|
||||
providerConfigRef:
|
||||
name: admin-keys
|
||||
```
|
||||
|
||||
[getting-started]: {{<ref "../getting-started/install-configure" >}}
|
||||
[Google Cloud Platform (GCP) Service Account]: {{<ref "../cloud-providers/gcp/gcp-provider" >}}
|
||||
[Microsoft Azure Service Principal]: {{<ref "../cloud-providers/azure/azure-provider" >}}
|
||||
[Amazon Web Services (AWS) IAM User]: {{<ref "../cloud-providers/aws/aws-provider" >}}
|
||||
[managed-resources]: {{<ref "managed-resources" >}}
|
||||
|
|
|
|||
|
|
@ -3,52 +3,311 @@ title: Providers
|
|||
weight: 101
|
||||
---
|
||||
|
||||
Providers are Crossplane packages that bundle a set of
|
||||
[Managed Resources]({{<ref "managed-resources" >}}) and their respective controllers to allow
|
||||
Crossplane to provision the respective infrastructure resource.
|
||||
Providers enable Crossplane to provision infrastructure on an
|
||||
external service. Providers create new Kubernetes APIs and map them to external
|
||||
APIs.
|
||||
|
||||
## Installing Providers
|
||||
Providers are responsible for all aspects of connecting to non-Kubernetes
|
||||
resources. This includes authentication, making external API calls and
|
||||
providing
|
||||
[Kubernetes Controller](https://kubernetes.io/docs/concepts/architecture/controller/)
|
||||
logic for any external resources.
|
||||
|
||||
The core Crossplane controller can install provider controllers and CRDs for you
|
||||
through its own provider packaging mechanism, which is triggered by the
|
||||
application of a `Provider` resource. For example, in order to request
|
||||
installation of the `provider-aws` package, apply the following resource to the
|
||||
cluster where Crossplane is running:
|
||||
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)
|
||||
* [Provider Kubernetes](https://github.com/crossplane-contrib/provider-kubernetes)
|
||||
|
||||
```yaml
|
||||
{{< hint "tip" >}}
|
||||
Find more providers in the [Upbound Marketplace](https://marketplace.upbound.io).
|
||||
{{< /hint >}}
|
||||
|
||||
<!-- 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
|
||||
[_Managed Resources_]({{<ref "managed-resources" >}}).
|
||||
<!-- vale write-good.Passive = YES -->
|
||||
|
||||
{{< hint "note" >}}
|
||||
Instructions on building your own Provider are outside of the scope of this
|
||||
document. Read the Crossplane contributing [Provider Development
|
||||
Guide](https://github.com/crossplane/crossplane/blob/master/contributing/guide-provider-development.md)
|
||||
for more information.
|
||||
{{< /hint >}}
|
||||
|
||||
## Install a Provider
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
[AWS Community Provider](https://github.com/crossplane-contrib/provider-aws),
|
||||
|
||||
```yaml {label="install"}
|
||||
apiVersion: pkg.crossplane.io/v1
|
||||
kind: Provider
|
||||
metadata:
|
||||
name: provider-aws
|
||||
spec:
|
||||
package: "xpkg.upbound.io/crossplane-contrib/provider-aws:v0.33.0"
|
||||
package: xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0
|
||||
```
|
||||
|
||||
The field `spec.package` is where you refer to the container image of the
|
||||
provider. Crossplane Package Manager will unpack that container, register CRDs
|
||||
and set up necessary RBAC rules and then start the controllers.
|
||||
{{< hint "tip" >}}
|
||||
Providers are Crossplane Packages. Read more about Packages in the
|
||||
[Packages documentation]({{<ref "packages" >}}).
|
||||
{{< /hint >}}
|
||||
|
||||
There are a few other ways to to trigger the installation of provider packages:
|
||||
By default, the Provider pod installs in the same namespace as Crossplane
|
||||
(`crossplane-system`).
|
||||
|
||||
* As part of Crossplane Helm chart by adding the following statement to your
|
||||
`helm install` command: `--set
|
||||
provider.packages={xpkg.upbound.io/crossplane-contrib/provider-aws:v0.33.0}`.
|
||||
* Using the Crossplane CLI: `kubectl crossplane install provider
|
||||
xpkg.upbound.io/crossplane-contrib/provider-aws:v0.33.0`
|
||||
### Install with Helm
|
||||
|
||||
You can uninstall a provider by deleting the `Provider` resource
|
||||
you've created.
|
||||
Crossplane supports installing Providers during an initial Crossplane
|
||||
installation with the Crossplane Helm chart.
|
||||
|
||||
## Configuring Providers
|
||||
Use the
|
||||
{{<hover label="helm" line="5" >}}--set provider.packages{{</hover >}}
|
||||
argument with `helm install`.
|
||||
|
||||
In order to authenticate with the external provider API, the provider
|
||||
controllers need to have access to credentials. It could be an IAM User for AWS,
|
||||
a Service Account for GCP or a Service Principal for Azure. Every provider has a
|
||||
type called `ProviderConfig` that has information about how to authenticate to
|
||||
the provider API. An example `ProviderConfig` resource for AWS looks like the
|
||||
following:
|
||||
For example, to install the AWS Community Provider,
|
||||
|
||||
```shell {label="helm"}
|
||||
helm install crossplane \
|
||||
crossplane-stable/crossplane \
|
||||
--namespace crossplane-system \
|
||||
--create-namespace \
|
||||
--set provider.packages={xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0}
|
||||
```
|
||||
|
||||
### Install from a private repository
|
||||
|
||||
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.
|
||||
|
||||
```yaml {label="pps"}
|
||||
apiVersion: pkg.crossplane.io/v1
|
||||
kind: Provider
|
||||
metadata:
|
||||
name: private-provider
|
||||
spec:
|
||||
package: private-repo.example.org/providers/my-provider
|
||||
packagePullSecrets:
|
||||
- name: my-secret
|
||||
```
|
||||
|
||||
{{< hint "note" >}}
|
||||
The Kubernetes secret object the Provider uses must be in the same namespace as
|
||||
the Crossplane pod.
|
||||
{{< /hint >}}
|
||||
|
||||
## Upgrade a Provider
|
||||
|
||||
To upgrade an existing Provider edit the installed Provider Package by either
|
||||
applying a new Provider manifest or with `kubectl edit providers`.
|
||||
|
||||
Update the version number in the Provider's `spec.package` and apply the change.
|
||||
Crossplane installs the new image and creates a new `ProviderRevision`.
|
||||
|
||||
## Remove a Provider
|
||||
|
||||
Remove a Provider by deleting the Provider object with `kubectl delete
|
||||
provider`.
|
||||
|
||||
{{< hint "warning" >}}
|
||||
Removing a Provider without first removing the Provider's managed resources
|
||||
may abandon the resources. The external resources aren't deleted.
|
||||
|
||||
If you remove the Provider first, you must manually delete external resources
|
||||
through your cloud provider. Managed resources must be manually deleted by
|
||||
removing their finalizers.
|
||||
|
||||
For more information on deleting abandoned resources read the [Crossplane
|
||||
troubleshooting guide]({{<ref "/knowledge-base/guides/troubleshoot#deleting-when-a-resource-hangs" >}}).
|
||||
{{< /hint >}}
|
||||
|
||||
## Verify a Provider
|
||||
|
||||
Providers install their own APIs representing the managed resources they support.
|
||||
Providers may also create Deployments, Service Accounts or RBAC configuration.
|
||||
|
||||
View the status of a Provider with
|
||||
|
||||
`kubectl get providers`
|
||||
|
||||
During the install a Provider report `INSTALLED` as `True` and `HEALTHY` as
|
||||
`Unknown`.
|
||||
|
||||
```shell
|
||||
kubectl get providers
|
||||
NAME INSTALLED HEALTHY PACKAGE AGE
|
||||
crossplane-contrib-provider-aws True Unknown xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0 63s
|
||||
```
|
||||
|
||||
After the Provider install completes and it's ready for use the `HEALTHY` status
|
||||
reports `True`.
|
||||
|
||||
```shell
|
||||
kubectl get providers
|
||||
NAME INSTALLED HEALTHY PACKAGE AGE
|
||||
crossplane-contrib-provider-aws True True xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0 88s
|
||||
```
|
||||
|
||||
{{<hint "important" >}}
|
||||
Some Providers install hundreds of Kubernetes Custom Resource Definitions (`CRDs`).
|
||||
This can create significant strain on undersized API Servers, impacting Provider
|
||||
install times.
|
||||
|
||||
The Crossplane community has more
|
||||
[details on scaling CRDs](https://github.com/crossplane/crossplane/blob/master/design/one-pager-crd-scaling.md).
|
||||
{{< /hint >}}
|
||||
### Provider conditions
|
||||
|
||||
View the conditions of a provider under their `Status` with
|
||||
`kubectl describe provider`.
|
||||
|
||||
Providers have the following possible conditions:
|
||||
|
||||
<!-- vale Google.Headings = NO -->
|
||||
#### InactivePackageRevision
|
||||
<!-- vale Google.Headings = YES -->
|
||||
```yaml
|
||||
Type: Installed
|
||||
Status: False
|
||||
Reason: InactivePackageRevision
|
||||
```
|
||||
|
||||
The Provider Package is using an inactive Provider Package Revision.
|
||||
|
||||
<!-- vale Google.Headings = NO -->
|
||||
#### ActivePackageRevision
|
||||
<!-- vale Google.Headings = YES -->
|
||||
```yaml
|
||||
Type: Installed
|
||||
Status: True
|
||||
Reason: ActivePackageRevision
|
||||
```
|
||||
|
||||
The Provider Package is the current Package Revision, but Crossplane hasn't
|
||||
finished installing the Package Revision yet.
|
||||
|
||||
{{< hint "tip" >}}
|
||||
Providers stuck in this state are because of a problem with Package Revisions.
|
||||
|
||||
Use `kubectl describe providerrevisions` for more details.
|
||||
{{< /hint >}}
|
||||
|
||||
<!-- vale Google.Headings = NO -->
|
||||
#### HealthyPackageRevision
|
||||
<!-- vale Google.Headings = YES -->
|
||||
```yaml
|
||||
Type: Healthy
|
||||
Status: True
|
||||
Reason: HealthyPackageRevision
|
||||
```
|
||||
|
||||
The Provider is fully installed and ready to use.
|
||||
|
||||
|
||||
<!-- vale Google.Headings = NO -->
|
||||
#### UnhealthyPackageRevision
|
||||
<!-- vale Google.Headings = YES -->
|
||||
|
||||
```yaml
|
||||
Type: Healthy
|
||||
Status: False
|
||||
Reason: UnhealthyPackageRevision
|
||||
```
|
||||
|
||||
There was an error installing the Provider Package Revision, preventing
|
||||
Crossplane from installing the Provider Package.
|
||||
|
||||
{{<hint "tip" >}}
|
||||
Use `kubectl describe providerrevisions` for more details on why the Package
|
||||
Revision failed.
|
||||
{{< /hint >}}
|
||||
|
||||
<!-- vale Google.Headings = NO -->
|
||||
#### UnknownPackageRevisionHealth
|
||||
<!-- vale Google.Headings = YES -->
|
||||
```yaml
|
||||
Type: Healthy
|
||||
Status: Unknown
|
||||
Reason: UnknownPackageRevisionHealth
|
||||
```
|
||||
|
||||
The status of the Provider Package Revision is `Unknown`. The Provider Package
|
||||
Revision may be installing or has an issue.
|
||||
|
||||
{{<hint "tip" >}}
|
||||
Use `kubectl describe providerrevisions` for more details on why the Package
|
||||
Revision failed.
|
||||
{{< /hint >}}
|
||||
|
||||
## Configure a Provider
|
||||
|
||||
Providers have two different types of configurations:
|
||||
* _Controller configurations_ that change the settings of the Provider pod
|
||||
running inside the Kubernetes cluster. For example, Pod `toleration`.
|
||||
* _Provider configurations_ that change settings used when communicating with
|
||||
an external provider. For example, cloud provider authentication.
|
||||
|
||||
{{<hint "important" >}}
|
||||
Apply `ControllerConfig` objects to Providers.
|
||||
|
||||
Apply `ProviderConfig` objects to managed resources.
|
||||
{{< /hint >}}
|
||||
|
||||
### Controller configuration
|
||||
{{< hint "important" >}}
|
||||
The Crossplane community deprecated the `ControllerConfig` type in v1.11.
|
||||
Applying a Controller configuration generates a deprecation warning.
|
||||
|
||||
Controller configurations are still supported until there is a replacement type
|
||||
in a future Crossplane version.
|
||||
{{< /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.
|
||||
|
||||
The most common use-case for ControllerConfigs are providing `args` to a
|
||||
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.
|
||||
|
||||
Each Provider determines their supported set of `args`.
|
||||
|
||||
### Provider configuration
|
||||
|
||||
The `ProviderConfig` determines settings the Provider uses communicating to the
|
||||
external provider. Each Provider determines available settings of their
|
||||
`ProviderConfig`.
|
||||
|
||||
<!-- 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
|
||||
{{<hover label="providerconfig" line="2" >}}ProviderConfig{{</hover >}}
|
||||
{{<hover label="providerconfig" line="5" >}}spec{{</hover >}}
|
||||
defines the
|
||||
{{<hover label="providerconfig" line="6" >}}credentials{{</hover >}} and that
|
||||
the Provider pod should look in the Kubernetes
|
||||
{{<hover label="providerconfig" line="7" >}}Secrets{{</hover >}} objects and use
|
||||
the key named
|
||||
{{<hover label="providerconfig" line="10" >}}aws-creds{{</hover >}}.
|
||||
<!-- vale write-good.Weasel = YES -->
|
||||
```yaml {label="providerconfig"}
|
||||
apiVersion: aws.crossplane.io/v1beta1
|
||||
kind: ProviderConfig
|
||||
metadata:
|
||||
|
|
@ -62,34 +321,87 @@ spec:
|
|||
key: creds
|
||||
```
|
||||
|
||||
You can see that there is a reference to a key in a specific `Secret`. The value
|
||||
of that key should contain the credentials that the controller will use. The
|
||||
documentation of each provider should give you an idea of how that credentials
|
||||
blob should look like.
|
||||
{{< hint "important" >}}
|
||||
Authentication configuration may be different across Providers.
|
||||
|
||||
The following is an example usage of AWS `ProviderConfig`, referenced by a
|
||||
`RDSInstance`:
|
||||
Read the documentation on a specific Provider for instructions on configuring
|
||||
authentication for that Provider.
|
||||
{{< /hint >}}
|
||||
|
||||
```yaml
|
||||
apiVersion: database.aws.crossplane.io/v1beta1
|
||||
kind: RDSInstance
|
||||
<!-- 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
|
||||
ProviderConfigs.
|
||||
<!-- vale write-good.TooWordy = YES -->
|
||||
|
||||
Each account's credentials tie to a unique ProviderConfig. When creating a
|
||||
managed resource, attach the desired ProviderConfig.
|
||||
|
||||
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.
|
||||
|
||||
```yaml {label="user"}
|
||||
apiVersion: aws.crossplane.io/v1beta1
|
||||
kind: ProviderConfig
|
||||
metadata:
|
||||
name: prod-sql
|
||||
name: user-keys
|
||||
spec:
|
||||
providerConfigRef:
|
||||
name: aws-provider
|
||||
...
|
||||
credentials:
|
||||
source: Secret
|
||||
secretRef:
|
||||
namespace: crossplane-system
|
||||
name: my-key
|
||||
key: secret-key
|
||||
```
|
||||
|
||||
The AWS provider controller will use that provider for this instance of
|
||||
`RDSInstance`. Since every resource has its own reference to a `ProviderConfig`,
|
||||
you can have multiple `ProviderConfig` resources in your cluster referenced by
|
||||
different resources. When no `providerConfigRef` is specified, the `RDSInstance`
|
||||
will attempt to use a `ProviderConfig` named `default`.
|
||||
```yaml {label="admin"}
|
||||
apiVersion: aws.crossplane.io/v1beta1
|
||||
kind: ProviderConfig
|
||||
metadata:
|
||||
name: admin-keys
|
||||
spec:
|
||||
credentials:
|
||||
source: Secret
|
||||
secretRef:
|
||||
namespace: crossplane-system
|
||||
name: admin-key
|
||||
key: admin-secret-key
|
||||
```
|
||||
|
||||
<!-- Named Links -->
|
||||
Apply the ProviderConfig when creating a managed resource.
|
||||
|
||||
This creates an AWS {{<hover label="user-bucket" line="2" >}}Bucket{{< /hover >}}
|
||||
resource using the
|
||||
{{<hover label="user-bucket" line="9" >}}user-keys{{< /hover >}} ProviderConfig.
|
||||
|
||||
```yaml {label="user-bucket"}
|
||||
apiVersion: s3.aws.upbound.io/v1beta1
|
||||
kind: Bucket
|
||||
metadata:
|
||||
name: user-bucket
|
||||
spec:
|
||||
forProvider:
|
||||
region: us-east-2
|
||||
providerConfigRef:
|
||||
name: user-keys
|
||||
```
|
||||
|
||||
This creates a second {{<hover label="admin-bucket" line="2" >}}Bucket{{< /hover >}}
|
||||
resource using the
|
||||
{{<hover label="admin-bucket" line="9" >}}admin-keys{{< /hover >}} ProviderConfig.
|
||||
|
||||
```yaml {label="admin-bucket"}
|
||||
apiVersion: s3.aws.upbound.io/v1beta1
|
||||
kind: Bucket
|
||||
metadata:
|
||||
name: user-bucket
|
||||
spec:
|
||||
forProvider:
|
||||
region: us-east-2
|
||||
providerConfigRef:
|
||||
name: admin-keys
|
||||
```
|
||||
|
||||
[getting-started]: ../../getting-started/introduction
|
||||
[Google Cloud Platform (GCP) Service Account]: ../../cloud-providers/provider-gcp
|
||||
[Microsoft Azure Service Principal]: ../../cloud-providers/provider-azure
|
||||
[Amazon Web Services (AWS) IAM User]: ../../cloud-providers/provider-aws
|
||||
|
|
|
|||
|
|
@ -3,52 +3,311 @@ title: Providers
|
|||
weight: 101
|
||||
---
|
||||
|
||||
Providers are Crossplane packages that bundle a set of
|
||||
[Managed Resources]({{<ref "managed-resources" >}}) and their respective controllers to allow
|
||||
Crossplane to provision the respective infrastructure resource.
|
||||
Providers enable Crossplane to provision infrastructure on an
|
||||
external service. Providers create new Kubernetes APIs and map them to external
|
||||
APIs.
|
||||
|
||||
## Installing Providers
|
||||
Providers are responsible for all aspects of connecting to non-Kubernetes
|
||||
resources. This includes authentication, making external API calls and
|
||||
providing
|
||||
[Kubernetes Controller](https://kubernetes.io/docs/concepts/architecture/controller/)
|
||||
logic for any external resources.
|
||||
|
||||
The core Crossplane controller can install provider controllers and CRDs for you
|
||||
through its own provider packaging mechanism, which is triggered by the
|
||||
application of a `Provider` resource. For example, in order to request
|
||||
installation of the `provider-aws` package, apply the following resource to the
|
||||
cluster where Crossplane is running:
|
||||
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)
|
||||
* [Provider Kubernetes](https://github.com/crossplane-contrib/provider-kubernetes)
|
||||
|
||||
```yaml
|
||||
{{< hint "tip" >}}
|
||||
Find more providers in the [Upbound Marketplace](https://marketplace.upbound.io).
|
||||
{{< /hint >}}
|
||||
|
||||
<!-- 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
|
||||
[_Managed Resources_]({{<ref "managed-resources" >}}).
|
||||
<!-- vale write-good.Passive = YES -->
|
||||
|
||||
{{< hint "note" >}}
|
||||
Instructions on building your own Provider are outside of the scope of this
|
||||
document. Read the Crossplane contributing [Provider Development
|
||||
Guide](https://github.com/crossplane/crossplane/blob/master/contributing/guide-provider-development.md)
|
||||
for more information.
|
||||
{{< /hint >}}
|
||||
|
||||
## Install a Provider
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
[AWS Community Provider](https://github.com/crossplane-contrib/provider-aws),
|
||||
|
||||
```yaml {label="install"}
|
||||
apiVersion: pkg.crossplane.io/v1
|
||||
kind: Provider
|
||||
metadata:
|
||||
name: provider-aws
|
||||
spec:
|
||||
package: "xpkg.upbound.io/crossplane-contrib/provider-aws:v0.33.0"
|
||||
package: xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0
|
||||
```
|
||||
|
||||
The field `spec.package` is where you refer to the container image of the
|
||||
provider. Crossplane Package Manager will unpack that container, register CRDs
|
||||
and set up necessary RBAC rules and then start the controllers.
|
||||
{{< hint "tip" >}}
|
||||
Providers are Crossplane Packages. Read more about Packages in the
|
||||
[Packages documentation]({{<ref "packages" >}}).
|
||||
{{< /hint >}}
|
||||
|
||||
There are a few other ways to to trigger the installation of provider packages:
|
||||
By default, the Provider pod installs in the same namespace as Crossplane
|
||||
(`crossplane-system`).
|
||||
|
||||
* As part of Crossplane Helm chart by adding the following statement to your
|
||||
`helm install` command: `--set
|
||||
provider.packages={xpkg.upbound.io/crossplane-contrib/provider-aws:v0.33.0}`.
|
||||
* Using the Crossplane CLI: `kubectl crossplane install provider
|
||||
xpkg.upbound.io/crossplane-contrib/provider-aws:v0.33.0`
|
||||
### Install with Helm
|
||||
|
||||
You can uninstall a provider by deleting the `Provider` resource
|
||||
you've created.
|
||||
Crossplane supports installing Providers during an initial Crossplane
|
||||
installation with the Crossplane Helm chart.
|
||||
|
||||
## Configuring Providers
|
||||
Use the
|
||||
{{<hover label="helm" line="5" >}}--set provider.packages{{</hover >}}
|
||||
argument with `helm install`.
|
||||
|
||||
In order to authenticate with the external provider API, the provider
|
||||
controllers need to have access to credentials. It could be an IAM User for AWS,
|
||||
a Service Account for GCP or a Service Principal for Azure. Every provider has a
|
||||
type called `ProviderConfig` that has information about how to authenticate to
|
||||
the provider API. An example `ProviderConfig` resource for AWS looks like the
|
||||
following:
|
||||
For example, to install the AWS Community Provider,
|
||||
|
||||
```shell {label="helm"}
|
||||
helm install crossplane \
|
||||
crossplane-stable/crossplane \
|
||||
--namespace crossplane-system \
|
||||
--create-namespace \
|
||||
--set provider.packages={xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0}
|
||||
```
|
||||
|
||||
### Install from a private repository
|
||||
|
||||
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.
|
||||
|
||||
```yaml {label="pps"}
|
||||
apiVersion: pkg.crossplane.io/v1
|
||||
kind: Provider
|
||||
metadata:
|
||||
name: private-provider
|
||||
spec:
|
||||
package: private-repo.example.org/providers/my-provider
|
||||
packagePullSecrets:
|
||||
- name: my-secret
|
||||
```
|
||||
|
||||
{{< hint "note" >}}
|
||||
The Kubernetes secret object the Provider uses must be in the same namespace as
|
||||
the Crossplane pod.
|
||||
{{< /hint >}}
|
||||
|
||||
## Upgrade a Provider
|
||||
|
||||
To upgrade an existing Provider edit the installed Provider Package by either
|
||||
applying a new Provider manifest or with `kubectl edit providers`.
|
||||
|
||||
Update the version number in the Provider's `spec.package` and apply the change.
|
||||
Crossplane installs the new image and creates a new `ProviderRevision`.
|
||||
|
||||
## Remove a Provider
|
||||
|
||||
Remove a Provider by deleting the Provider object with `kubectl delete
|
||||
provider`.
|
||||
|
||||
{{< hint "warning" >}}
|
||||
Removing a Provider without first removing the Provider's managed resources
|
||||
may abandon the resources. The external resources aren't deleted.
|
||||
|
||||
If you remove the Provider first, you must manually delete external resources
|
||||
through your cloud provider. Managed resources must be manually deleted by
|
||||
removing their finalizers.
|
||||
|
||||
For more information on deleting abandoned resources read the [Crossplane
|
||||
troubleshooting guide]({{<ref "/knowledge-base/guides/troubleshoot#deleting-when-a-resource-hangs" >}}).
|
||||
{{< /hint >}}
|
||||
|
||||
## Verify a Provider
|
||||
|
||||
Providers install their own APIs representing the managed resources they support.
|
||||
Providers may also create Deployments, Service Accounts or RBAC configuration.
|
||||
|
||||
View the status of a Provider with
|
||||
|
||||
`kubectl get providers`
|
||||
|
||||
During the install a Provider report `INSTALLED` as `True` and `HEALTHY` as
|
||||
`Unknown`.
|
||||
|
||||
```shell
|
||||
kubectl get providers
|
||||
NAME INSTALLED HEALTHY PACKAGE AGE
|
||||
crossplane-contrib-provider-aws True Unknown xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0 63s
|
||||
```
|
||||
|
||||
After the Provider install completes and it's ready for use the `HEALTHY` status
|
||||
reports `True`.
|
||||
|
||||
```shell
|
||||
kubectl get providers
|
||||
NAME INSTALLED HEALTHY PACKAGE AGE
|
||||
crossplane-contrib-provider-aws True True xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0 88s
|
||||
```
|
||||
|
||||
{{<hint "important" >}}
|
||||
Some Providers install hundreds of Kubernetes Custom Resource Definitions (`CRDs`).
|
||||
This can create significant strain on undersized API Servers, impacting Provider
|
||||
install times.
|
||||
|
||||
The Crossplane community has more
|
||||
[details on scaling CRDs](https://github.com/crossplane/crossplane/blob/master/design/one-pager-crd-scaling.md).
|
||||
{{< /hint >}}
|
||||
### Provider conditions
|
||||
|
||||
View the conditions of a provider under their `Status` with
|
||||
`kubectl describe provider`.
|
||||
|
||||
Providers have the following possible conditions:
|
||||
|
||||
<!-- vale Google.Headings = NO -->
|
||||
#### InactivePackageRevision
|
||||
<!-- vale Google.Headings = YES -->
|
||||
```yaml
|
||||
Type: Installed
|
||||
Status: False
|
||||
Reason: InactivePackageRevision
|
||||
```
|
||||
|
||||
The Provider Package is using an inactive Provider Package Revision.
|
||||
|
||||
<!-- vale Google.Headings = NO -->
|
||||
#### ActivePackageRevision
|
||||
<!-- vale Google.Headings = YES -->
|
||||
```yaml
|
||||
Type: Installed
|
||||
Status: True
|
||||
Reason: ActivePackageRevision
|
||||
```
|
||||
|
||||
The Provider Package is the current Package Revision, but Crossplane hasn't
|
||||
finished installing the Package Revision yet.
|
||||
|
||||
{{< hint "tip" >}}
|
||||
Providers stuck in this state are because of a problem with Package Revisions.
|
||||
|
||||
Use `kubectl describe providerrevisions` for more details.
|
||||
{{< /hint >}}
|
||||
|
||||
<!-- vale Google.Headings = NO -->
|
||||
#### HealthyPackageRevision
|
||||
<!-- vale Google.Headings = YES -->
|
||||
```yaml
|
||||
Type: Healthy
|
||||
Status: True
|
||||
Reason: HealthyPackageRevision
|
||||
```
|
||||
|
||||
The Provider is fully installed and ready to use.
|
||||
|
||||
|
||||
<!-- vale Google.Headings = NO -->
|
||||
#### UnhealthyPackageRevision
|
||||
<!-- vale Google.Headings = YES -->
|
||||
|
||||
```yaml
|
||||
Type: Healthy
|
||||
Status: False
|
||||
Reason: UnhealthyPackageRevision
|
||||
```
|
||||
|
||||
There was an error installing the Provider Package Revision, preventing
|
||||
Crossplane from installing the Provider Package.
|
||||
|
||||
{{<hint "tip" >}}
|
||||
Use `kubectl describe providerrevisions` for more details on why the Package
|
||||
Revision failed.
|
||||
{{< /hint >}}
|
||||
|
||||
<!-- vale Google.Headings = NO -->
|
||||
#### UnknownPackageRevisionHealth
|
||||
<!-- vale Google.Headings = YES -->
|
||||
```yaml
|
||||
Type: Healthy
|
||||
Status: Unknown
|
||||
Reason: UnknownPackageRevisionHealth
|
||||
```
|
||||
|
||||
The status of the Provider Package Revision is `Unknown`. The Provider Package
|
||||
Revision may be installing or has an issue.
|
||||
|
||||
{{<hint "tip" >}}
|
||||
Use `kubectl describe providerrevisions` for more details on why the Package
|
||||
Revision failed.
|
||||
{{< /hint >}}
|
||||
|
||||
## Configure a Provider
|
||||
|
||||
Providers have two different types of configurations:
|
||||
* _Controller configurations_ that change the settings of the Provider pod
|
||||
running inside the Kubernetes cluster. For example, Pod `toleration`.
|
||||
* _Provider configurations_ that change settings used when communicating with
|
||||
an external provider. For example, cloud provider authentication.
|
||||
|
||||
{{<hint "important" >}}
|
||||
Apply `ControllerConfig` objects to Providers.
|
||||
|
||||
Apply `ProviderConfig` objects to managed resources.
|
||||
{{< /hint >}}
|
||||
|
||||
### Controller configuration
|
||||
{{< hint "important" >}}
|
||||
The Crossplane community deprecated the `ControllerConfig` type in v1.11.
|
||||
Applying a Controller configuration generates a deprecation warning.
|
||||
|
||||
Controller configurations are still supported until there is a replacement type
|
||||
in a future Crossplane version.
|
||||
{{< /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.
|
||||
|
||||
The most common use-case for ControllerConfigs are providing `args` to a
|
||||
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.
|
||||
|
||||
Each Provider determines their supported set of `args`.
|
||||
|
||||
### Provider configuration
|
||||
|
||||
The `ProviderConfig` determines settings the Provider uses communicating to the
|
||||
external provider. Each Provider determines available settings of their
|
||||
`ProviderConfig`.
|
||||
|
||||
<!-- 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
|
||||
{{<hover label="providerconfig" line="2" >}}ProviderConfig{{</hover >}}
|
||||
{{<hover label="providerconfig" line="5" >}}spec{{</hover >}}
|
||||
defines the
|
||||
{{<hover label="providerconfig" line="6" >}}credentials{{</hover >}} and that
|
||||
the Provider pod should look in the Kubernetes
|
||||
{{<hover label="providerconfig" line="7" >}}Secrets{{</hover >}} objects and use
|
||||
the key named
|
||||
{{<hover label="providerconfig" line="10" >}}aws-creds{{</hover >}}.
|
||||
<!-- vale write-good.Weasel = YES -->
|
||||
```yaml {label="providerconfig"}
|
||||
apiVersion: aws.crossplane.io/v1beta1
|
||||
kind: ProviderConfig
|
||||
metadata:
|
||||
|
|
@ -62,34 +321,87 @@ spec:
|
|||
key: creds
|
||||
```
|
||||
|
||||
You can see that there is a reference to a key in a specific `Secret`. The value
|
||||
of that key should contain the credentials that the controller will use. The
|
||||
documentation of each provider should give you an idea of how that credentials
|
||||
blob should look like.
|
||||
{{< hint "important" >}}
|
||||
Authentication configuration may be different across Providers.
|
||||
|
||||
The following is an example usage of AWS `ProviderConfig`, referenced by a
|
||||
`RDSInstance`:
|
||||
Read the documentation on a specific Provider for instructions on configuring
|
||||
authentication for that Provider.
|
||||
{{< /hint >}}
|
||||
|
||||
```yaml
|
||||
apiVersion: database.aws.crossplane.io/v1beta1
|
||||
kind: RDSInstance
|
||||
<!-- 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
|
||||
ProviderConfigs.
|
||||
<!-- vale write-good.TooWordy = YES -->
|
||||
|
||||
Each account's credentials tie to a unique ProviderConfig. When creating a
|
||||
managed resource, attach the desired ProviderConfig.
|
||||
|
||||
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.
|
||||
|
||||
```yaml {label="user"}
|
||||
apiVersion: aws.crossplane.io/v1beta1
|
||||
kind: ProviderConfig
|
||||
metadata:
|
||||
name: prod-sql
|
||||
name: user-keys
|
||||
spec:
|
||||
providerConfigRef:
|
||||
name: aws-provider
|
||||
...
|
||||
credentials:
|
||||
source: Secret
|
||||
secretRef:
|
||||
namespace: crossplane-system
|
||||
name: my-key
|
||||
key: secret-key
|
||||
```
|
||||
|
||||
The AWS provider controller will use that provider for this instance of
|
||||
`RDSInstance`. Since every resource has its own reference to a `ProviderConfig`,
|
||||
you can have multiple `ProviderConfig` resources in your cluster referenced by
|
||||
different resources. When no `providerConfigRef` is specified, the `RDSInstance`
|
||||
will attempt to use a `ProviderConfig` named `default`.
|
||||
```yaml {label="admin"}
|
||||
apiVersion: aws.crossplane.io/v1beta1
|
||||
kind: ProviderConfig
|
||||
metadata:
|
||||
name: admin-keys
|
||||
spec:
|
||||
credentials:
|
||||
source: Secret
|
||||
secretRef:
|
||||
namespace: crossplane-system
|
||||
name: admin-key
|
||||
key: admin-secret-key
|
||||
```
|
||||
|
||||
<!-- Named Links -->
|
||||
Apply the ProviderConfig when creating a managed resource.
|
||||
|
||||
This creates an AWS {{<hover label="user-bucket" line="2" >}}Bucket{{< /hover >}}
|
||||
resource using the
|
||||
{{<hover label="user-bucket" line="9" >}}user-keys{{< /hover >}} ProviderConfig.
|
||||
|
||||
```yaml {label="user-bucket"}
|
||||
apiVersion: s3.aws.upbound.io/v1beta1
|
||||
kind: Bucket
|
||||
metadata:
|
||||
name: user-bucket
|
||||
spec:
|
||||
forProvider:
|
||||
region: us-east-2
|
||||
providerConfigRef:
|
||||
name: user-keys
|
||||
```
|
||||
|
||||
This creates a second {{<hover label="admin-bucket" line="2" >}}Bucket{{< /hover >}}
|
||||
resource using the
|
||||
{{<hover label="admin-bucket" line="9" >}}admin-keys{{< /hover >}} ProviderConfig.
|
||||
|
||||
```yaml {label="admin-bucket"}
|
||||
apiVersion: s3.aws.upbound.io/v1beta1
|
||||
kind: Bucket
|
||||
metadata:
|
||||
name: user-bucket
|
||||
spec:
|
||||
forProvider:
|
||||
region: us-east-2
|
||||
providerConfigRef:
|
||||
name: admin-keys
|
||||
```
|
||||
|
||||
[Google Cloud Platform (GCP) Service Account]: "../cloud-providers/gcp/gcp-provider"
|
||||
[Microsoft Azure Service Principal]: "../cloud-providers/azure/azure-provider"
|
||||
[Amazon Web Services (AWS) IAM User]: "../cloud-providers/aws/aws-provider"
|
||||
|
|
|
|||
Loading…
Reference in New Issue