Crossplane logo
Crossplane logo
master v1.12
Latest
v1.11 v1.10

Install Crossplane

On this page
This document is for an unreleased version of Crossplane.

This document applies to the Crossplane master branch and not to the latest release v1.12.

Crossplane installs into an existing Kubernetes cluster, creating the Crossplane pod, enabling the installation of Crossplane Provider resources.

Tip
If you don’t have a Kubernetes cluster create one locally with Kind.

Prerequisites

Install Crossplane

Install Crossplane using the Crossplane published Helm chart.

Add the Crossplane Helm repository

Add the Crossplane repository with the helm repo add command.

1helm repo add crossplane-stable https://charts.crossplane.io/stable

Update the local Helm chart cache with helm repo update.

1helm repo update

Install the Crossplane Helm chart

Install the Crossplane Helm chart with helm install.

Tip
View the changes Crossplane makes to your cluster with the helm install --dry-run --debug options. Helm shows what configurations it applies without making changes to the Kubernetes cluster.

Crossplane creates and installs into the crossplane-system namespace.

1helm install crossplane \
2--namespace crossplane-system \
3--create-namespace crossplane-stable/crossplane

View the installed Crossplane pods with kubectl get pods -n crossplane-system.

1kubectl get pods -n crossplane-system
2NAME                                       READY   STATUS    RESTARTS   AGE
3crossplane-6d67f8cd9d-g2gjw                1/1     Running   0          26m
4crossplane-rbac-manager-86d9b5cf9f-2vc4s   1/1     Running   0          26m
Tip

Install a specific version of Crossplane with the --version <version> option. For example, to install version 1.10.0:

1helm install crossplane \
2--namespace crossplane-system \
3--create-namespace crossplane-stable/crossplane \
4--version 1.10.0

Installed deployments

Crossplane creates two Kubernetes deployments in the crossplane-system namespace to deploy the Crossplane pods.

1kubectl get deployments -n crossplane-system
2NAME                      READY   UP-TO-DATE   AVAILABLE   AGE
3crossplane                1/1     1            1           8m13s
4crossplane-rbac-manager   1/1     1            1           8m13s

Crossplane deployment

The Crossplane deployment starts with the crossplane-init container. The init container installs the Crossplane Custom Resource Definitions into the Kubernetes cluster.

After the init container finishes, the crossplane pod manages two Kubernetes controllers.

  • The Package Manager controller installs the provider and configuration packages.
  • The Composition controller installs and manages the Crossplane Composite Resource Definitions, Compositions and Claims.

Crossplane-rbac-manager deployment

The crossplane-rbac-manager creates and manages Kubernetes ClusterRoles for installed Crossplane Provider and their Custom Resource Definitions.

The Crossplane RBAC Manger design document has more information on the installed ClusterRoles.

Installation options

Customize the Crossplane Helm chart

Crossplane supports customizations at install time by configuring the Helm chart.

Apply customizations with the command line or with a Helm values file.

ParameterDescriptionDefault
affinityEnable pod affinity for the Crossplane pods.{}
argsOptional arguments passed to the Crossplane pods.{}
configuration.packagesA list of Crossplane Configuration packages to install together with Crossplane.[]
customAnnotationsAdd custom annotations to the Crossplane deployments and pods.{}
customLabelsAdd custom labels to the Crossplane deployments and pods.{}
deploymentStrategyThe deployment strategy for the Crossplane and RBAC Manager pods.RollingUpdate
extraEnvVarsCrossplaneList of extra environment variables to set in the Crossplane deployment. Note: Helm replaces all dot . values with underscores _ (example: SAMPLE.KEY=value1 becomes SAMPLE_KEY=value1).{}
extraEnvVarsRBACManagerList of extra environment variables to set in the Crossplane RBAC Manager deployment. Note: Helm replaces all dot . values with underscores _ (example: SAMPLE.KEY=value1 becomes SAMPLE_KEY=value1).{}
image.pullPolicyImage pull policy used in all Crossplane containers.IfNotPresent
image.repositoryImage repository for the Crossplane pods.crossplane/crossplane
image.tagImage tag used to install the Crossplane pod image.master
imagePullSecretsNames of image pull secrets to use.{}
leaderElectionEnable leader election for the Crossplane Manager pods.true
metrics.enabledExpose Crossplane and RBAC Manager pod metrics endpoints.false
nodeSelectorEnable a node selector for the Crossplane pods.{}
packageCache.configMapA Kubernetes configMap to define the Crossplane Configuration package cache. Configuring packageCache.configMap disables the Kubernetes emptyDir. Crossplane ignores the packageCache.configMap when using packageCache.pvc.""
packageCache.mediumThe Kubernetes emptyDir medium used for the Crossplane Configuration package cache. Unused with packageCache.pvc or packageCache.configMap set.""
packageCache.pvcName of the Kubernetes PersistentVolumeClaim used for the Crossplane Configuration package cache. The packageCache.pvc takes precedence over packageCache.configMap and disables the Kubernetes emptyDir.""
packageCache.sizeLimitThe size limit of the Kubernetes emptyDir used for the Crossplane Configuration package cache. Unused with packageCache.pvc or packageCache.configMap set.5Mi
podSecurityContextCrossplaneConfigure a Kubernetes securityContext for the Crossplane pods.{}
podSecurityContextCrossplaneConfigure a Kubernetes securityContext for the Crossplane RBAC Manager pod.{}
priorityClassNameThe priority class name for Crossplane and RBAC Manager pods.""
provider.packagesA list of Crossplane Provider packages to install together with Crossplane.[]
rbacManager.affinityEnable affinity for the Crossplane RBAC Manager pod.{}
rbacManager.deployDeploy the Crossplane RBAC Manager pod and its required roles.true
rbacManager.leaderElectionEnable the leader election for the Crossplane RBAC Managers pod.true
rbacManager.managementPolicyThe extent to which the Crossplane RBAC manager manages permissions. Setting rbacManager.managementPolicy to All the Crossplane RBAC controller manages all Crossplane controller and user roles. Setting rbacManager.managementPolicy to Basic the Crossplane RBAC controller only manages crossplane-admin, crossplane-edit, and crossplane-view user roles.All
rbacManager.nodeSelectorEnable a node selector for the Crossplane RBAC Manager pod.{}
rbacManager.replicasThe number of replicas to run for the Crossplane RBAC Manager pods.1
rbacManager.skipAggregatedClusterRolesDon’t deploy RBAC aggregated ClusterRoles.false
rbacManager.tolerationsEnable tolerations for Crossplane RBAC Managers pod.[]
registryCaBundleConfig.keyKey to use from the ConfigMap containing a CA bundle for fetching from package registries.{}
registryCaBundleConfig.nameName of ConfigMap containing a CA bundle for fetching from package registries.{}
replicasThe number of replicas to run for the Crossplane pods.1
resourcesCrossplane.limits.cpuCPU resource limits for the Crossplane pods.100m
resourcesCrossplane.limits.memoryMemory resource limits for the Crossplane pods.512Mi
resourcesCrossplane.requests.cpuCPU resource requests for the Crossplane pods.100m
resourcesCrossplane.requests.memoryMemory resource requests for the Crossplane pods.256Mi
resourcesRBACManager.limits.cpuCPU resource limits for the Crossplane RBAC Manager pod.100m
resourcesRBACManager.limits.memoryMemory resource limits for the Crossplane RBAC Manager pod.512Mi
resourcesRBACManager.requests.cpuCPU resource requests for the Crossplane RBAC Manager pod.100m
resourcesRBACManager.requests.memoryMemory resource requests value the Crossplane RBAC Manager pod.256Mi
securityContextCrossplane.allowPrivilegeEscalationAllow privilege escalation for the Crossplane pods.false
securityContextCrossplane.readOnlyRootFilesystemSet a read only root file system for the Crossplane pods.true
securityContextCrossplane.runAsGroupA run as group for the Crossplane pods.65532
securityContextCrossplane.runAsUserA run as user for the Crossplane pods.65532
securityContextRBACManager.allowPrivilegeEscalationAllow privilege escalation for the Crossplane RBAC Manager pod.false
securityContextRBACManager.readOnlyRootFilesystemSet a read only root file system for the Crossplane RBAC Manager pod.true
securityContextRBACManager.runAsGroupThe run as group for the Crossplane RBAC Manager pod.65532
securityContextRBACManager.runAsUserThe run as user for the Crossplane RBAC Manager pod.65532
serviceAccount.customAnnotationsAdd custom annotations to the Crossplane service account.{}
tolerationsEnable tolerations for Crossplane pod.[]
webhooks.enabledEnable webhooks for Crossplane as well as packages installed by Crossplane.false
xfn.argsOptional arguments passed to the Composite Resource Functions sidecar container.{}
xfn.cache.mediumThe Kubernetes emptyDir medium used for the Composite Resource Functions sidecar container cache. Unused with xfn.cache.pvc set.""
xfn.cache.pvcName of the Kubernetes PersistentVolumeClaim used for the Composite Resource Functions sidecar container cache. The xfn.cache.pvc disables the Composite Resource Functions Kubernetes emptyDir.""
xfn.cache.sizeLimitThe size limit of the Kubernetes emptyDir used for the Composite Resource Functions sidecar container cache. Unused with xfn.cache.pvc set.1Gi
xfn.enabledEnable Crossplane Composite Resource Functions. Enabling Composite Resource Functions also requires args set with --enable-composition-functions.false
xfn.extraEnvVarsList of extra environment variables to set in the Composite Resource Functions sidecar container. Note: Helm replaces all dot . values with underscores _ (example: SAMPLE.KEY=value1 becomes SAMPLE_KEY=value1).{}
xfn.image.pullPolicyImage pull policy used in the Composite Resource Functions sidecar container.IfNotPresent
xfn.image.repositoryImage repository for the Composite Resource Functions sidecar container.crossplane/xfn
xfn.image.tagImage tag used to install the Composite Resource Functions sidecar container.The installed Crossplane version.
xfn.imagePullSecretsNames of image pull secrets to use when installing the Composite Resource Functions sidecar container.{}
xfn.limits.cpuCPU resource limits for the Crossplane RBAC Manager pod.2000m
xfn.limits.memoryMemory resource limits for the Crossplane RBAC Manager pod.2Gi
xfn.requests.cpuCPU resource requests for the Crossplane RBAC Manager pod.1000m
xfn.requests.memoryMemory resource requests value the Crossplane RBAC Manager pod.1Gi
xfn.securityContext.allowPrivilegeEscalationAllow privilege escalation for the Crossplane RBAC Manager pod.false
xfn.securityContext.readOnlyRootFilesystemSet a read only root file system for the Crossplane RBAC Manager pod.true
xfn.securityContext.runAsGroupThe run as group for the Crossplane RBAC Manager pod.65532
xfn.securityContext.runAsUserThe run as user for the Crossplane RBAC Manager pod.65532

Command line customization

Apply custom settings at the command line with helm install crossplane --set <setting>=<value>.

For example, to change the image pull policy:

1helm install crossplane \
2--namespace crossplane-system \
3--create-namespace \
4crossplane-stable/crossplane \
5--set image.pullPolicy=Always

Helm supports comma-seperated arguments.

For example, to change the image pull policy and number of replicas:

1helm install crossplane \
2--namespace crossplane-system \
3--create-namespace \
4crossplane-stable/crossplane \
5--set image.pullPolicy=Always,replicas=2

Helm values file

Apply custom settings in a Helm values file with helm install crossplane -f <filename>.

A YAML file defines the customized settings.

For example, to change the image pull policy and number of replicas:

Create a YAML with the customized settings.

1replicas: 2
2
3image:
4  pullPolicy: Always

Apply the file with helm install:

1helm install crossplane \
2--namespace crossplane-system \
3--create-namespace \
4crossplane-stable/crossplane \
5-f settings.yaml

Feature flags

Crossplane usually introduces new features behind feature flags. By default alpha features are off, while beta features are enabled. To enable a feature flag, set the args value in the Helm chart. Available feature flags can be directly found by running crossplane core start --help, or by looking at the table below.

StatusFlagDescription
Beta--enable-composition-revisionsEnable support for CompositionRevisions
Alpha--enable-composition-functionsEnable support for Composition Functions.
Alpha--enable-composition-webhook-schema-validationEnable Composition validation using schemas.
Alpha--enable-environment-configsEnable support for EnvironmentConfigs.
Alpha--enable-external-secret-storesEnable support for External Secret Stores.

Set these flags either in the values.yaml file or at install time using the --set flag, for example: --set args=["--enable-composition-functions","--enable-composition-webhook-schema-validation"].

Install pre-release Crossplane versions

Install a pre-release versions of Crossplane from the master Crossplane Helm channel.

Versions in the master channel are under active development and may be unstable.

Warning
Don’t use Crossplane master releases in production. Only use stable channel.
Only use master for testing and development.

Add the Crossplane master Helm repository

Add the Crossplane repository with the helm repo add command.

1helm repo add crossplane-master https://charts.crossplane.io/master/

Update the local Helm chart cache with helm repo update.

1helm repo update

Install the Crossplane master Helm chart

Install the Crossplane master Helm chart with helm install.

Tip
View the changes Crossplane makes to your cluster with the helm install --dry-run --debug options. Helm shows what configurations it applies without making changes to the Kubernetes cluster.

Crossplane creates and installs into the crossplane-system namespace.

1helm install crossplane \
2--namespace crossplane-system \
3--create-namespace crossplane-master/crossplane \
4--devel

Crossplane distributions

Third-party vendors may maintain their own Crossplane distributions. Vendor supported distribution may have features or tooling that isn’t in the Community Crossplane distribution.

The CNCF certified third-party distributions as “conformant” with the Community Crossplane distribution.

Vendors

Below are vendors providing conformant Crossplane distributions.

Upbound

Upbound, the founders of Crossplane, maintains a free and open source distribution of Crossplane called Universal Crossplane (UXP).

Find information on UXP in the Upbound UXP documentation.