mirror of https://github.com/crossplane/docs.git
408 lines
14 KiB
Markdown
408 lines
14 KiB
Markdown
---
|
|
title: Crossplane Pods
|
|
weight: 1
|
|
description: Background on the components installed with Crossplane and their functions.
|
|
---
|
|
|
|
The base Crossplane installation consists of two pods, the `crossplane` pod and
|
|
the `crossplane-rbac-manager` pod. Both pods install in the `crossplane-system`
|
|
namespace by default.
|
|
|
|
|
|
## Crossplane pod
|
|
|
|
### Init container
|
|
Before starting the core Crossplane container an _init_ container runs. The init
|
|
container installs the core Crossplane
|
|
[Custom Resource Definitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions)
|
|
(`CRDs`), configures Crossplane webhooks and installs any supplied Providers or
|
|
Configurations.
|
|
|
|
{{<hint "tip" >}}
|
|
The Kubernetes documentation contains more information about
|
|
[init containers](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/).
|
|
{{< /hint >}}
|
|
|
|
The settings the init container sets include installing Provider or Configuration
|
|
packages with Crossplane, customizing the namespace Crossplane installs in and
|
|
defining webhook configurations.
|
|
|
|
The core CRDs installed by the init container include:
|
|
* CompositeResourceDefinitions, Compositions, Configurations and Providers
|
|
* Locks to manage package dependencies
|
|
* DeploymentRuntimeConfigs to apply settings to installed Providers and Functions
|
|
* StoreConfigs for connecting external secret stores like
|
|
[HashiCorp Vault](https://www.vaultproject.io/)
|
|
|
|
{{< hint "note" >}}
|
|
|
|
The [Install Crossplane]({{< ref "../software/install" >}}) section has more
|
|
information about customizing the Crossplane install.
|
|
{{< /hint >}}
|
|
|
|
The status `Init` on the Crossplane pod is the init container running.
|
|
|
|
```shell
|
|
kubectl get pods -n crossplane-system
|
|
NAME READY STATUS RESTARTS AGE
|
|
crossplane-9f6d5cd7b-r9j8w 0/1 Init:0/1 0 6s
|
|
```
|
|
|
|
The init container completes and starts the Crossplane core container
|
|
automatically.
|
|
|
|
```shell
|
|
kubectl get pods -n crossplane-system
|
|
NAME READY STATUS RESTARTS AGE
|
|
crossplane-9f6d5cd7b-r9j8w 1/1 Running 0 15s
|
|
```
|
|
|
|
### Core container
|
|
|
|
The main Crossplane container, called the _core_ container, enforces
|
|
the desired state of Crossplane resources, manages leader elections and process
|
|
webhooks.
|
|
|
|
{{<hint "note" >}}
|
|
The Crossplane pod only reconciles core Crossplane components, including Claims
|
|
and composite resources. Providers are responsible for reconciling their managed
|
|
resources.
|
|
{{< /hint >}}
|
|
|
|
#### Reconcile loop
|
|
|
|
The core container operates on a _reconcile loop_, constantly checking the
|
|
status of deployed resources and correcting any "drift." After checking a
|
|
resource Crossplane waits some time and checks again.
|
|
|
|
Crossplane monitors resources through a Kubernetes
|
|
[_watch_](https://kubernetes.io/docs/reference/using-api/api-concepts/#efficient-detection-of-changes)
|
|
or through periodic polling. Some resources may be both watched and polled.
|
|
|
|
Crossplane requests that the API server notifies Crossplane of any changes on
|
|
objects. This notification tool is a _watch_.
|
|
|
|
Watched objects include Providers, managed resources and
|
|
CompositeResourceDefinitions.
|
|
|
|
For objects that Kubernetes can't provide a watch for, Crossplane
|
|
periodically poll the resource to find it's state. The default polling rate is
|
|
one minute. Change the polling rate with the `--poll-interval` pod argument.
|
|
|
|
Reducing the poll-interval value causes Crossplane to poll resources more
|
|
frequently. This increases the load of the Crossplane pod and
|
|
results in more frequent provider API calls.
|
|
|
|
<!-- vale write-good.TooWordy = NO -->
|
|
<!-- allow "maximum" -->
|
|
Increasing the poll-interval causes Crossplane to poll resources less
|
|
frequently. This increases the maximum time until Crossplane
|
|
discovers changes in the cloud provider that require updating.
|
|
<!-- vale write-good.TooWordy = YES -->
|
|
|
|
Managed resources use polling.
|
|
|
|
{{< hint "note" >}}
|
|
Managed resources watch for Kubernetes events like deletion or changes to
|
|
their `spec`. Managed resources rely on polling to detect changes in the
|
|
external system.
|
|
{{< /hint >}}
|
|
|
|
Crossplane double-checks all resources to
|
|
confirm they're in the desired state. Crossplane does this every one hour by
|
|
default. Use the `--sync-interval` Crossplane pod argument to change this
|
|
interval.
|
|
|
|
The `--max-reconcile-rate` rate defines the rate, in times per second,
|
|
Crossplane reconciles resources.
|
|
|
|
Reducing the `--max-reconcile-rate`, or making it smaller, reduces CPU
|
|
resources Crossplane uses, but increases the amount of time until changed
|
|
resources are fully synced.
|
|
|
|
Increasing the `--max-reconcile-rate`, or making it larger, increases the
|
|
CPU resources Crossplane uses but allows Crossplane to reconcile all resources
|
|
faster.
|
|
|
|
{{< hint "important" >}}
|
|
Most Providers use their own `--max-reconcile-rate`. This determines the
|
|
same settings for Providers and their managed resources. Applying the
|
|
`--max-reconcile-rate` to Crossplane only controls the rate for
|
|
core Crossplane resources.
|
|
{{< /hint >}}
|
|
|
|
##### Enable real time Compositions
|
|
|
|
With real time compositions enabled Crossplane watches every composed resource
|
|
with a Kubernetes watch. Crossplane receives events from the
|
|
Kubernetes API server when a composed resource changes. For example, when
|
|
a provider sets the `Ready` condition to `true`.
|
|
|
|
{{<hint "important" >}}
|
|
Real time compositions are an alpha feature. Alpha features aren't enabled by
|
|
default.
|
|
{{< /hint >}}
|
|
|
|
With real time compositions enabled, Crossplane doesn't use the `--poll-interval`
|
|
settings.
|
|
|
|
Enable real time compositions support by
|
|
[changing the Crossplane pod setting]({{<ref "./pods#change-pod-settings">}})
|
|
and enabling
|
|
{{<hover label="deployment" line="12">}}--enable-realtime-compositions{{</hover>}}
|
|
argument.
|
|
|
|
```yaml {label="deployment",copy-lines="12"}
|
|
$ kubectl edit deployment crossplane --namespace crossplane-system
|
|
apiVersion: apps/v1
|
|
kind: Deployment
|
|
spec:
|
|
# Removed for brevity
|
|
template:
|
|
spec:
|
|
containers:
|
|
- args:
|
|
- core
|
|
- start
|
|
- --enable-realtime-compositions
|
|
```
|
|
|
|
{{<hint "tip" >}}
|
|
|
|
The [Crossplane install guide]({{<ref "../software/install#feature-flags">}})
|
|
describes enabling feature flags like
|
|
{{<hover label="deployment" line="12">}}--enable-realtime-compositions{{</hover>}}
|
|
with Helm.
|
|
{{< /hint >}}
|
|
|
|
##### Reconcile retry rate
|
|
|
|
The `--max-reconcile-rate` setting configures the number of times per second
|
|
Crossplane or a provider attempts to correct a resource. The default value is
|
|
10 times per second.
|
|
|
|
All core Crossplane components share the reconcile rate. Each Provider
|
|
implements their own max reconcile rate setting.
|
|
|
|
##### Number of reconcilers
|
|
|
|
The second value `--max-reconcile-rate` defines is the number of
|
|
resources that Crossplane can reconcile at once. If there are more resources than
|
|
the configured `--max-reconcile-rate` the remaining resources must wait until
|
|
Crossplane reconciles a an existing resource.
|
|
|
|
Read the [Change Pod Settings]({{<ref "#change-pod-settings">}}) section for
|
|
instructions on applying these settings.
|
|
|
|
<!-- vale Microsoft.HeadingAcronyms = NO -->
|
|
<!-- allow 'RBAC' since that's the name -->
|
|
## RBAC manager pod
|
|
<!-- vale Microsoft.HeadingAcronyms = YES -->
|
|
The Crossplane RBAC manager pod automates required Kubernetes RBAC permissions
|
|
for Crossplane and Crossplane Providers.
|
|
|
|
{{<hint "note" >}}
|
|
Crossplane installs and enables the RBAC manager by default.
|
|
Disabling the RBAC manager requires manual Kubernetes permissions definitions
|
|
for proper Crossplane operations.
|
|
|
|
The
|
|
[RBAC manager design document](https://github.com/crossplane/crossplane/blob/main/design/design-doc-rbac-manager.md)
|
|
provides more comprehensive details on the Crossplane RBAC requirements.
|
|
{{< /hint >}}
|
|
|
|
### Disable the RBAC manager
|
|
|
|
Disable the RBAC manager after installation by deleting the
|
|
`crossplane-rbac-manager` deployment from the `crossplane-system` namespace.
|
|
|
|
Disable the RBAC manager before installation by editing the Helm `values.yaml`
|
|
file, setting `rbacManager.deploy` to `false`.
|
|
|
|
{{< hint "note" >}}
|
|
|
|
Instructions for changing Crossplane pod settings during installation are in the
|
|
[Crossplane Install]({{<ref "../software/install">}}) section.
|
|
{{< /hint >}}
|
|
|
|
<!-- vale Microsoft.HeadingAcronyms = NO -->
|
|
<!-- allow 'RBAC' since that's the name -->
|
|
### RBAC init container
|
|
<!-- vale Microsoft.HeadingAcronyms = YES -->
|
|
|
|
The RBAC manager requires the `CompositeResourceDefinition` and
|
|
`ProviderRevision` resources to be available before starting.
|
|
|
|
The RBAC manager init container waits for these resources before starting the
|
|
main RBAC manager container.
|
|
|
|
### RBAC manager container
|
|
|
|
The RBAC manager container preforms the following tasks:
|
|
* creating and binding RBAC roles to Provider ServiceAccounts, allowing
|
|
them to control their managed resources
|
|
* allowing the `crossplane` ServiceAccount to create managed resources
|
|
* creating ClusterRoles to access Crossplane resources in all namespaces
|
|
|
|
Use the [ClusterRoles]({{<ref "#crossplane-clusterroles">}}) to grant access to all Crossplane resources in the
|
|
cluster.
|
|
|
|
#### Crossplane ClusterRoles
|
|
|
|
The RBAC manager creates four Kubernetes ClusterRoles. These Roles grant
|
|
permissions over cluster wide Crossplane resources.
|
|
|
|
<!-- vale Google.Headings = NO -->
|
|
<!-- disable heading checking for the role names -->
|
|
<!-- vale Google.WordList = NO -->
|
|
<!-- allow "admin" -->
|
|
##### crossplane-admin
|
|
<!-- vale Google.WordList = YES -->
|
|
<!-- vale Crossplane.Spelling = NO -->
|
|
The `crossplane-admin` ClusterRole has the following permissions:
|
|
* full access to all Crossplane types
|
|
* full access to all secrets and namespaces (even those unrelated to Crossplane)
|
|
* read-only access to all cluster RBAC roles, CustomResourceDefinitions and
|
|
events
|
|
* ability to bind RBAC roles to other entities.
|
|
<!-- vale Crossplane.Spelling = YES -->
|
|
View the full RBAC policy with
|
|
|
|
```shell
|
|
kubectl describe clusterrole crossplane-admin
|
|
```
|
|
|
|
##### crossplane-edit
|
|
|
|
The `crossplane-edit` ClusterRole has the following permissions:
|
|
|
|
* full access to all Crossplane types
|
|
* full access to all secrets (even those unrelated to Crossplane)
|
|
* read-only access to all namespaces and events (even those unrelated to Crossplane).
|
|
|
|
View the full RBAC policy with
|
|
|
|
```shell
|
|
kubectl describe clusterrole crossplane-edit
|
|
```
|
|
|
|
##### crossplane-view
|
|
|
|
The `crossplane-view` ClusterRole has the following permissions:
|
|
|
|
* read-only access to all Crossplane types
|
|
* read-only access to all namespaces and events (even those unrelated to Crossplane).
|
|
|
|
View the full RBAC policy with
|
|
|
|
```shell
|
|
kubectl describe clusterrole crossplane-view
|
|
```
|
|
|
|
##### crossplane-browse
|
|
|
|
The `crossplane-browse` ClusterRole has the following permissions:
|
|
|
|
* read-only access to Crossplane compositions and XRDs. This allows resource claim
|
|
creators to discover and select an appropriate composition.
|
|
|
|
View the full RBAC policy with
|
|
|
|
```shell
|
|
kubectl describe clusterrole crossplane-browse
|
|
```
|
|
|
|
## Leader election
|
|
|
|
By default only a single Crossplane pod runs in a cluster. If more than one
|
|
Crossplane pod runs both pods try to manage Crossplane resources. To prevent
|
|
conflicts Crossplane uses a _leader election_ to have a single pod in control at
|
|
a time. Other Crossplane pods standby until the leader fails.
|
|
|
|
{{< hint "note" >}}
|
|
It's possible to run more than one Crossplane or RBAC manager pods for
|
|
redundancy.
|
|
|
|
Kubernetes restarts any failed Crossplane or RBAC manager pods.
|
|
Redundant pods aren't required in most deployments.
|
|
{{< /hint >}}
|
|
|
|
Both the Crossplane pod and the RBAC manager pods support leader elections.
|
|
|
|
Enable leader elections with the `--leader-election` pod argument.
|
|
|
|
{{< hint "warning" >}}
|
|
<!-- vale write-good.TooWordy = NO -->
|
|
<!-- "multiple" -->
|
|
<!-- vale write-good.Passive = NO -->
|
|
<!-- allow "is unsupported" -->
|
|
Running multiple Crossplane pods without leader election is unsupported.
|
|
<!-- vale write-good.Passive = YES -->
|
|
<!-- vale write-good.TooWordy = YES -->
|
|
{{< /hint >}}
|
|
|
|
|
|
## Change pod settings
|
|
|
|
Change Crossplane pod settings either before installing Crossplane by editing
|
|
the Helm `values.yml` file or after installation by editing the `Deployment`.
|
|
|
|
The full list of
|
|
[configuration options]({{<ref "../software/install#customize-the-crossplane-helm-chart">}})
|
|
and
|
|
[feature flags]({{<ref "../software/install#feature-flags">}})
|
|
are available in the
|
|
[Crossplane Install]({{<ref "../software/install">}})
|
|
section.
|
|
|
|
{{< hint "note" >}}
|
|
|
|
Instructions for changing Crossplane pod settings during installation are in the
|
|
[Crossplane Install]({{<ref "../software/install">}}) section.
|
|
{{< /hint >}}
|
|
|
|
### Edit the deployment
|
|
{{< hint "note" >}}
|
|
These settings apply to both the `crossplane` and `rbac-manager` pods and
|
|
`Deployments`.
|
|
{{< /hint >}}
|
|
|
|
To change the settings of an installed Crossplane pod, edit the `crossplane`
|
|
deployment in the `crossplane-system` namespace with the command
|
|
|
|
`kubectl edit deployment crossplane --namespace crossplane-system`
|
|
|
|
{{< hint "warning" >}}
|
|
Updating the Crossplane deployment restarts the Crossplane pod.
|
|
{{< /hint >}}
|
|
|
|
Add Crossplane pod arguments to the
|
|
{{<hover label="args" line="9" >}}spec.template.spec.containers[].args{{< /hover >}}
|
|
section of the deployment.
|
|
|
|
For example, to change the `sync-interval` add
|
|
{{<hover label="args" line="12" >}}--sync-interval=30m{{< /hover >}}.
|
|
|
|
```yaml {label="args", copy-lines="1"}
|
|
kubectl edit deployment crossplane --namespace crossplane-system
|
|
apiVersion: apps/v1
|
|
kind: Deployment
|
|
spec:
|
|
# Removed for brevity
|
|
template:
|
|
spec:
|
|
containers:
|
|
- args:
|
|
- core
|
|
- start
|
|
- --sync-interval=30m
|
|
```
|
|
|
|
### Use environmental variables
|
|
|
|
The core Crossplane pod checks for configured environmental variables at startup
|
|
to change default settings.
|
|
|
|
The full list of configurable environmental variables are available in the
|
|
[Crossplane Install]({{<ref "../software/install">}}) section.
|