crossplane
/
docs
mirror of https://github.com/crossplane/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Concepts: Provider rewrite (#420)

This commit is contained in:
Pete Lumbis 2023-05-05 16:50:47 -04:00 committed by GitHub
parent 980736c846
commit 4f213f50e7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 366 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

414
content/master/concepts/providers.md
View File

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

5
utils/vale/styles/Crossplane/spelling-exceptions.txt
View File

@ -9,9 +9,11 @@ Datastore
editCode editCode
Enum Enum
Env Env
finalizers
GCP's GCP's
Geekdocs Geekdocs
Grammarly Grammarly
HashiCorp
kubeconfig kubeconfig
kubectl kubectl
minikube minikube
@ -36,5 +38,4 @@ XRD
XRD's XRD's
XRDs XRDs
XRs XRs
Zendesk Zendesk
Hashicorp

1
utils/vale/styles/alex/ProfanityUnlikely.yml
View File

@ -105,7 +105,6 @@ tokens:
- execution - execution
- executioner - executioner
- explosion - explosion
- failed
- failure - failure
- fairies - fairies
- fairy - fairy