Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Updates the ControllerConfig deprecation warning #548

Merged
merged 1 commit into from
Sep 14, 2023
Merged

Updates the ControllerConfig deprecation warning #548

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 63 additions & 52 deletions content/master/concepts/providers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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)
Expand All @@ -27,7 +28,7 @@ Find more providers in the [Upbound Marketplace](https://marketplace.upbound.io)
<!-- vale write-good.Passive = NO -->
<!-- "are Managed" isn't passive in this context -->
Providers define every external resource they can create in Kubernetes as a
Kubernetes API endpoint. These endpoints are
Kubernetes API endpoint. These endpoints are
[_Managed Resources_]({{<ref "managed-resources" >}}).
<!-- vale write-good.Passive = YES -->

Expand All @@ -42,14 +43,14 @@ for more information.
Installing a provider creates a Provider pod that's responsible for installing
the Provider's APIs into the Kubernetes cluster. Providers constantly watch the
state of the desired managed resources and create any external resources that
are missing.
are missing.

Install a Provider with a Crossplane
{{<hover label="install" line="2">}}Provider{{</hover >}} object setting the
{{<hover label="install" line="6">}}spec.package{{</hover >}} value to the
location of the provider package.

For example, to install the
For example, to install the
[AWS Community Provider](https://github.com/crossplane-contrib/provider-aws),

```yaml {label="install"}
Expand All @@ -71,12 +72,12 @@ By default, the Provider pod installs in the same namespace as Crossplane

### Install with Helm

Crossplane supports installing Providers during an initial Crossplane
Crossplane supports installing Providers during an initial Crossplane
installation with the Crossplane Helm chart.

Use the
{{<hover label="helm" line="5" >}}--set provider.packages{{</hover >}}
argument with `helm install`.
Use the
{{<hover label="helm" line="5" >}}--set provider.packages{{</hover >}}
argument with `helm install`.

For example, to install the AWS Community Provider,

Expand All @@ -92,7 +93,7 @@ crossplane-stable/crossplane \

Installing a Provider from a private package repository requires a
Kubernetes secret object. The Provider uses the secret with the
{{<hover label="pps" line="7" >}}packagePullSecrets{{</hover>}} option.
{{<hover label="pps" line="7" >}}packagePullSecrets{{</hover>}} option.

```yaml {label="pps"}
apiVersion: pkg.crossplane.io/v1
Expand All @@ -115,31 +116,31 @@ the Crossplane pod.
To upgrade an existing Provider edit the installed Provider Package by either
applying a new Provider manifest or with `kubectl edit providers`.

Update the version number in the Provider's `spec.package` and apply the change.
Update the version number in the Provider's `spec.package` and apply the change.
Crossplane installs the new image and creates a new `ProviderRevision`.

## Remove a Provider

Remove a Provider by deleting the Provider object with `kubectl delete
provider`.
provider`.

{{< hint "warning" >}}
Removing a Provider without first removing the Provider's managed resources
Removing a Provider without first removing the Provider's managed resources
may abandon the resources. The external resources aren't deleted.

If you remove the Provider first, you must manually delete external resources
through your cloud provider. Managed resources must be manually deleted by
removing their finalizers.
If you remove the Provider first, you must manually delete external resources
through your cloud provider. Managed resources must be manually deleted by
removing their finalizers.

For more information on deleting abandoned resources read the [Crossplane troubleshooting guide]({{<ref "/knowledge-base/guides/troubleshoot#deleting-when-a-resource-hangs" >}}).
For more information on deleting abandoned resources read the [Crossplane troubleshooting guide]({{<ref "/knowledge-base/guides/troubleshoot#deleting-when-a-resource-hangs" >}}).
{{< /hint >}}

## Verify a Provider

Providers install their own APIs representing the managed resources they support.
Providers may also create Deployments, Service Accounts or RBAC configuration.
Providers may also create Deployments, Service Accounts or RBAC configuration.

View the status of a Provider with
View the status of a Provider with

`kubectl get providers`

Expand All @@ -164,16 +165,17 @@ crossplane-contrib-provider-aws True True xpkg.upbound.io/crosspla
{{<hint "important" >}}
Some Providers install hundreds of Kubernetes Custom Resource Definitions (`CRDs`).
This can create significant strain on undersized API Servers, impacting Provider
install times.
install times.

The Crossplane community has more
The Crossplane community has more
[details on scaling CRDs](https://github.com/crossplane/crossplane/blob/master/design/one-pager-crd-scaling.md).
{{< /hint >}}

### Provider conditions

Crossplane uses a standard set of `Conditions` for Providers.
View the conditions of a provider under their `Status` with
`kubectl describe provider`.
View the conditions of a provider under their `Status` with
`kubectl describe provider`.

```yaml
kubectl describe provider
Expand All @@ -193,17 +195,21 @@ Status:
```

#### Types

Provider `Conditions` support two `Types`:

* `Type: Installed` - the Provider package installed but isn't ready for use.
* `Type: Healthy` - The Provider package is ready to use.
* `Type: Healthy` - The Provider package is ready to use.

#### Reasons

Each `Reason` relates to a specific `Type` and `Status`. Crossplane uses the
following `Reasons` for Provider `Conditions`.

<!-- vale Google.Headings = NO -->
##### InactivePackageRevision
`Reason: InactivePackageRevision` indicates the Provider Package is using an

`Reason: InactivePackageRevision` indicates the Provider Package is using an
inactive Provider Package Revision.

<!-- vale Google.Headings = YES -->
Expand All @@ -217,10 +223,10 @@ Reason: InactivePackageRevision
##### ActivePackageRevision
<!-- vale Google.Headings = YES -->
The Provider Package is the current Package Revision, but Crossplane hasn't
finished installing the Package Revision yet.
finished installing the Package Revision yet.

{{< hint "tip" >}}
Providers stuck in this state are because of a problem with Package Revisions.
Providers stuck in this state are because of a problem with Package Revisions.

Use `kubectl describe providerrevisions` for more details.
{{< /hint >}}
Expand All @@ -233,6 +239,7 @@ Reason: ActivePackageRevision

<!-- vale Google.Headings = NO -->
##### HealthyPackageRevision

The Provider is fully installed and ready to use.

{{<hint "tip" >}}
Expand All @@ -251,7 +258,7 @@ Reason: HealthyPackageRevision
<!-- vale Google.Headings = YES -->

There was an error installing the Provider Package Revision, preventing
Crossplane from installing the Provider Package.
Crossplane from installing the Provider Package.

{{<hint "tip" >}}
Use `kubectl describe providerrevisions` for more details on why the Package
Expand All @@ -267,9 +274,8 @@ Reason: UnhealthyPackageRevision
##### UnknownPackageRevisionHealth
<!-- vale Google.Headings = YES -->


The status of the Provider Package Revision is `Unknown`. The Provider Package
Revision may be installing or has an issue.
Revision may be installing or has an issue.

{{<hint "tip" >}}
Use `kubectl describe providerrevisions` for more details on why the Package
Expand All @@ -285,33 +291,39 @@ Reason: UnknownPackageRevisionHealth
## Configure a Provider

Providers have two different types of configurations:

* _Controller configurations_ that change the settings of the Provider pod
running inside the Kubernetes cluster. For example, Pod `toleration`.
running inside the Kubernetes cluster. For example, Pod `toleration`.
* _Provider configurations_ that change settings used when communicating with
an external provider. For example, cloud provider authentication.
an external provider. For example, cloud provider authentication.

{{<hint "important" >}}
Apply `ControllerConfig` objects to Providers.

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 >}}
Comment on lines +306 to 318
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the relevant section for review


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.

Expand All @@ -320,20 +332,20 @@ Each Provider determines their supported set of `args`.
### Provider configuration

The `ProviderConfig` determines settings the Provider uses communicating to the
external provider. Each Provider determines available settings of their
external provider. Each Provider determines available settings of their
`ProviderConfig`.

<!-- vale write-good.Weasel = NO -->
<!-- allow "usually" -->
Provider authentication is usually configured with a `ProviderConfig`. For
example, to use basic key-pair authentication with Provider AWS a
example, to use basic key-pair authentication with Provider AWS a
{{<hover label="providerconfig" line="2" >}}ProviderConfig{{</hover >}}
{{<hover label="providerconfig" line="5" >}}spec{{</hover >}}
defines the
defines the
{{<hover label="providerconfig" line="6" >}}credentials{{</hover >}} and that
the Provider pod should look in the Kubernetes
the Provider pod should look in the Kubernetes
{{<hover label="providerconfig" line="7" >}}Secrets{{</hover >}} objects and use
the key named
the key named
{{<hover label="providerconfig" line="10" >}}aws-creds{{</hover >}}.
<!-- vale write-good.Weasel = YES -->
```yaml {label="providerconfig"}
Expand All @@ -351,23 +363,23 @@ spec:
```

{{< hint "important" >}}
Authentication configuration may be different across Providers.
Authentication configuration may be different across Providers.

Read the documentation on a specific Provider for instructions on configuring
authentication for that Provider.
Read the documentation on a specific Provider for instructions on configuring
authentication for that Provider.
{{< /hint >}}

<!-- vale write-good.TooWordy = NO -->
<!-- allow multiple -->
ProviderConfig objects apply to individual Managed Resources. A single
Provider can authenticate with multiple users or accounts through
Provider can authenticate with multiple users or accounts through
ProviderConfigs.
<!-- vale write-good.TooWordy = YES -->

Each account's credentials tie to a unique ProviderConfig. When creating a
managed resource, attach the desired ProviderConfig.
managed resource, attach the desired ProviderConfig.

For example, two AWS ProviderConfigs, named
For example, two AWS ProviderConfigs, named
{{<hover label="user" line="4">}}user-keys{{</hover >}} and
{{<hover label="admin" line="4">}}admin-keys{{</hover >}}
use different Kubernetes secrets.
Expand Down Expand Up @@ -403,7 +415,7 @@ spec:
Apply the ProviderConfig when creating a managed resource.

This creates an AWS {{<hover label="user-bucket" line="2" >}}Bucket{{< /hover >}}
resource using the
resource using the
{{<hover label="user-bucket" line="9" >}}user-keys{{< /hover >}} ProviderConfig.

```yaml {label="user-bucket"}
Expand All @@ -419,7 +431,7 @@ spec:
```

This creates a second {{<hover label="admin-bucket" line="2" >}}Bucket{{< /hover >}}
resource using the
resource using the
{{<hover label="admin-bucket" line="9" >}}admin-keys{{< /hover >}} ProviderConfig.

```yaml {label="admin-bucket"}
Expand All @@ -433,4 +445,3 @@ spec:
providerConfigRef:
name: admin-keys
```

Loading
Loading