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