From 5d6ef67fe724cddc973160d40cd83d11228bf273 Mon Sep 17 00:00:00 2001 From: Pete Lumbis Date: Tue, 9 May 2023 15:42:15 -0400 Subject: [PATCH] Backport Providers update to release versions (#436) --- content/v1.10/concepts/providers.md | 418 ++++++++++++++++++++++++---- content/v1.11/concepts/providers.md | 416 +++++++++++++++++++++++---- content/v1.12/concepts/providers.md | 414 +++++++++++++++++++++++---- 3 files changed, 1091 insertions(+), 157 deletions(-) diff --git a/content/v1.10/concepts/providers.md b/content/v1.10/concepts/providers.md index 66abb509..ebd4ab5b 100644 --- a/content/v1.10/concepts/providers.md +++ b/content/v1.10/concepts/providers.md @@ -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 >}} + + + +Providers define every external resource they can create in Kubernetes as a +Kubernetes API endpoint. These endpoints are +[_Managed Resources_]({{}}). + + +{{< 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 +{{}}Provider{{}} object setting the +{{}}spec.package{{}} 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]({{}}). +{{< /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 +{{}}--set provider.packages{{}} +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 +{{}}packagePullSecrets{{}} 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]({{}}). +{{< /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 +``` + +{{}} +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: + + +#### InactivePackageRevision + +```yaml +Type: Installed +Status: False +Reason: InactivePackageRevision +``` + +The Provider Package is using an inactive Provider Package Revision. + + +#### ActivePackageRevision + +```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 >}} + + +#### HealthyPackageRevision + +```yaml +Type: Healthy +Status: True +Reason: HealthyPackageRevision +``` + +The Provider is fully installed and ready to use. + + + +#### UnhealthyPackageRevision + ```yaml +Type: Healthy +Status: False +Reason: UnhealthyPackageRevision +``` + +There was an error installing the Provider Package Revision, preventing +Crossplane from installing the Provider Package. + +{{}} +Use `kubectl describe providerrevisions` for more details on why the Package +Revision failed. +{{< /hint >}} + + +#### UnknownPackageRevisionHealth + +```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. + +{{}} +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. + +{{}} +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`. + + + +Provider authentication is usually configured with a `ProviderConfig`. For +example, to use basic key-pair authentication with Provider AWS a +{{}}ProviderConfig{{}} +{{}}spec{{}} +defines the +{{}}credentials{{}} and that +the Provider pod should look in the Kubernetes +{{}}Secrets{{}} objects and use +the key named +{{}}aws-creds{{}}. + +```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 + + +ProviderConfig objects apply to individual Managed Resources. A single +Provider can authenticate with multiple users or accounts through +ProviderConfigs. + + +Each account's credentials tie to a unique ProviderConfig. When creating a +managed resource, attach the desired ProviderConfig. + +For example, two AWS ProviderConfigs, named +{{}}user-keys{{}} and +{{}}admin-keys{{}} +use different Kubernetes secrets. + +```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 +``` - +Apply the ProviderConfig when creating a managed resource. + +This creates an AWS {{}}Bucket{{< /hover >}} +resource using the +{{}}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 {{}}Bucket{{< /hover >}} +resource using the +{{}}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]: {{}} -[Google Cloud Platform (GCP) Service Account]: {{}} -[Microsoft Azure Service Principal]: {{}} -[Amazon Web Services (AWS) IAM User]: {{}} -[managed-resources]: {{}} diff --git a/content/v1.11/concepts/providers.md b/content/v1.11/concepts/providers.md index af1dd9d1..ebd4ab5b 100644 --- a/content/v1.11/concepts/providers.md +++ b/content/v1.11/concepts/providers.md @@ -3,52 +3,311 @@ title: Providers weight: 101 --- -Providers are Crossplane packages that bundle a set of -[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 >}} + + + +Providers define every external resource they can create in Kubernetes as a +Kubernetes API endpoint. These endpoints are +[_Managed Resources_]({{}}). + + +{{< 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 +{{}}Provider{{}} object setting the +{{}}spec.package{{}} 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]({{}}). +{{< /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 +{{}}--set provider.packages{{}} +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 +{{}}packagePullSecrets{{}} 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]({{}}). +{{< /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 +``` + +{{}} +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: + + +#### InactivePackageRevision + +```yaml +Type: Installed +Status: False +Reason: InactivePackageRevision +``` + +The Provider Package is using an inactive Provider Package Revision. + + +#### ActivePackageRevision + +```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 >}} + + +#### HealthyPackageRevision + +```yaml +Type: Healthy +Status: True +Reason: HealthyPackageRevision +``` + +The Provider is fully installed and ready to use. + + + +#### UnhealthyPackageRevision + ```yaml +Type: Healthy +Status: False +Reason: UnhealthyPackageRevision +``` + +There was an error installing the Provider Package Revision, preventing +Crossplane from installing the Provider Package. + +{{}} +Use `kubectl describe providerrevisions` for more details on why the Package +Revision failed. +{{< /hint >}} + + +#### UnknownPackageRevisionHealth + +```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. + +{{}} +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. + +{{}} +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`. + + + +Provider authentication is usually configured with a `ProviderConfig`. For +example, to use basic key-pair authentication with Provider AWS a +{{}}ProviderConfig{{}} +{{}}spec{{}} +defines the +{{}}credentials{{}} and that +the Provider pod should look in the Kubernetes +{{}}Secrets{{}} objects and use +the key named +{{}}aws-creds{{}}. + +```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 + + +ProviderConfig objects apply to individual Managed Resources. A single +Provider can authenticate with multiple users or accounts through +ProviderConfigs. + + +Each account's credentials tie to a unique ProviderConfig. When creating a +managed resource, attach the desired ProviderConfig. + +For example, two AWS ProviderConfigs, named +{{}}user-keys{{}} and +{{}}admin-keys{{}} +use different Kubernetes secrets. + +```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 +``` - +Apply the ProviderConfig when creating a managed resource. + +This creates an AWS {{}}Bucket{{< /hover >}} +resource using the +{{}}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 {{}}Bucket{{< /hover >}} +resource using the +{{}}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 diff --git a/content/v1.12/concepts/providers.md b/content/v1.12/concepts/providers.md index 0b9745f0..ebd4ab5b 100644 --- a/content/v1.12/concepts/providers.md +++ b/content/v1.12/concepts/providers.md @@ -3,52 +3,311 @@ title: Providers weight: 101 --- -Providers are Crossplane packages that bundle a set of -[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 >}} + + + +Providers define every external resource they can create in Kubernetes as a +Kubernetes API endpoint. These endpoints are +[_Managed Resources_]({{}}). + + +{{< 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 +{{}}Provider{{}} object setting the +{{}}spec.package{{}} 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]({{}}). +{{< /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 +{{}}--set provider.packages{{}} +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 +{{}}packagePullSecrets{{}} 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]({{}}). +{{< /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 +``` + +{{}} +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: + + +#### InactivePackageRevision + +```yaml +Type: Installed +Status: False +Reason: InactivePackageRevision +``` + +The Provider Package is using an inactive Provider Package Revision. + + +#### ActivePackageRevision + +```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 >}} + + +#### HealthyPackageRevision + +```yaml +Type: Healthy +Status: True +Reason: HealthyPackageRevision +``` + +The Provider is fully installed and ready to use. + + + +#### UnhealthyPackageRevision + ```yaml +Type: Healthy +Status: False +Reason: UnhealthyPackageRevision +``` + +There was an error installing the Provider Package Revision, preventing +Crossplane from installing the Provider Package. + +{{}} +Use `kubectl describe providerrevisions` for more details on why the Package +Revision failed. +{{< /hint >}} + + +#### UnknownPackageRevisionHealth + +```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. + +{{}} +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. + +{{}} +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`. + + + +Provider authentication is usually configured with a `ProviderConfig`. For +example, to use basic key-pair authentication with Provider AWS a +{{}}ProviderConfig{{}} +{{}}spec{{}} +defines the +{{}}credentials{{}} and that +the Provider pod should look in the Kubernetes +{{}}Secrets{{}} objects and use +the key named +{{}}aws-creds{{}}. + +```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 + + +ProviderConfig objects apply to individual Managed Resources. A single +Provider can authenticate with multiple users or accounts through +ProviderConfigs. + + +Each account's credentials tie to a unique ProviderConfig. When creating a +managed resource, attach the desired ProviderConfig. + +For example, two AWS ProviderConfigs, named +{{}}user-keys{{}} and +{{}}admin-keys{{}} +use different Kubernetes secrets. + +```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 +``` - +Apply the ProviderConfig when creating a managed resource. +This creates an AWS {{}}Bucket{{< /hover >}} +resource using the +{{}}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 {{}}Bucket{{< /hover >}} +resource using the +{{}}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"