Crossplane logo
Crossplane logo
master v1.18
Latest
v1.17 v1.16

Install Crossplane

On this page

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, function 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 Manager 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
affinityAdd affinities to the Crossplane pod deployment.{}
argsAdd custom arguments to the Crossplane pod.[]
configuration.packagesA list of Configuration packages to install.[]
customAnnotationsAdd custom annotations to the Crossplane pod deployment.{}
customLabelsAdd custom labels to the Crossplane pod deployment.{}
deploymentStrategyThe deployment strategy for the Crossplane and RBAC Manager pods."RollingUpdate"
extraEnvVarsCrossplaneAdd custom environmental variables to the Crossplane pod deployment. Replaces any . in a variable name with _. For example, SAMPLE.KEY=value1 becomes SAMPLE_KEY=value1.{}
extraEnvVarsRBACManagerAdd custom environmental variables to the RBAC Manager pod deployment. Replaces any . in a variable name with _. For example, SAMPLE.KEY=value1 becomes SAMPLE_KEY=value1.{}
extraObjectsTo add arbitrary Kubernetes Objects during a Helm Install[]
extraVolumeMountsCrossplaneAdd custom volumeMounts to the Crossplane pod.{}
extraVolumesCrossplaneAdd custom volumes to the Crossplane pod.{}
function.packagesA list of Function packages to install.[]
hostNetworkEnable hostNetwork for the Crossplane deployment. Caution: enabling hostNetwork grants the Crossplane Pod access to the host network namespace.false
image.pullPolicyThe image pull policy used for Crossplane and RBAC Manager pods."IfNotPresent"
image.repositoryRepository for the Crossplane pod image."xpkg.upbound.io/crossplane/crossplane"
image.tagThe Crossplane image tag. Defaults to the value of appVersion in Chart.yaml.""
imagePullSecretsThe imagePullSecret names to add to the Crossplane ServiceAccount.{}
leaderElectionEnable leader election for the Crossplane pod.true
metrics.enabledEnable Prometheus path, port and scrape annotations and expose port 8080 for both the Crossplane and RBAC Manager pods.false
nodeSelectorAdd nodeSelectors to the Crossplane pod deployment.{}
packageCache.configMapThe name of a ConfigMap to use as the package cache. Disables the default package cache emptyDir Volume.""
packageCache.mediumSet to Memory to hold the package cache in a RAM backed file system. Useful for Crossplane development.""
packageCache.pvcThe name of a PersistentVolumeClaim to use as the package cache. Disables the default package cache emptyDir Volume.""
packageCache.sizeLimitThe size limit for the package cache. If medium is Memory the sizeLimit can’t exceed Node memory."20Mi"
podSecurityContextCrossplaneAdd a custom securityContext to the Crossplane pod.{}
podSecurityContextRBACManagerAdd a custom securityContext to the RBAC Manager pod.{}
priorityClassNameThe PriorityClass name to apply to the Crossplane and RBAC Manager pods.""
provider.packagesA list of Provider packages to install.[]
rbacManager.affinityAdd affinities to the RBAC Manager pod deployment.{}
rbacManager.argsAdd custom arguments to the RBAC Manager pod.[]
rbacManager.deployDeploy the RBAC Manager pod and its required roles.true
rbacManager.leaderElectionEnable leader election for the RBAC Manager pod.true
rbacManager.nodeSelectorAdd nodeSelectors to the RBAC Manager pod deployment.{}
rbacManager.replicasThe number of RBAC Manager pod replicas to deploy.1
rbacManager.skipAggregatedClusterRolesDon’t install aggregated Crossplane ClusterRoles.false
rbacManager.tolerationsAdd tolerations to the RBAC Manager pod deployment.[]
rbacManager.topologySpreadConstraintsAdd topologySpreadConstraints to the RBAC Manager pod deployment.[]
registryCaBundleConfig.keyThe ConfigMap key containing a custom CA bundle to enable fetching packages from registries with unknown or untrusted certificates.""
registryCaBundleConfig.nameThe ConfigMap name containing a custom CA bundle to enable fetching packages from registries with unknown or untrusted certificates.""
replicasThe number of Crossplane pod replicas to deploy.1
resourcesCrossplane.limits.cpuCPU resource limits for the Crossplane pod."100m"
resourcesCrossplane.limits.memoryMemory resource limits for the Crossplane pod."512Mi"
resourcesCrossplane.requests.cpuCPU resource requests for the Crossplane pod."100m"
resourcesCrossplane.requests.memoryMemory resource requests for the Crossplane pod."256Mi"
resourcesRBACManager.limits.cpuCPU resource limits for the RBAC Manager pod."100m"
resourcesRBACManager.limits.memoryMemory resource limits for the RBAC Manager pod."512Mi"
resourcesRBACManager.requests.cpuCPU resource requests for the RBAC Manager pod."100m"
resourcesRBACManager.requests.memoryMemory resource requests for the RBAC Manager pod."256Mi"
securityContextCrossplane.allowPrivilegeEscalationEnable allowPrivilegeEscalation for the Crossplane pod.false
securityContextCrossplane.readOnlyRootFilesystemSet the Crossplane pod root file system as read-only.true
securityContextCrossplane.runAsGroupThe group ID used by the Crossplane pod.65532
securityContextCrossplane.runAsUserThe user ID used by the Crossplane pod.65532
securityContextRBACManager.allowPrivilegeEscalationEnable allowPrivilegeEscalation for the RBAC Manager pod.false
securityContextRBACManager.readOnlyRootFilesystemSet the RBAC Manager pod root file system as read-only.true
securityContextRBACManager.runAsGroupThe group ID used by the RBAC Manager pod.65532
securityContextRBACManager.runAsUserThe user ID used by the RBAC Manager pod.65532
serviceAccount.customAnnotationsAdd custom annotations to the Crossplane ServiceAccount.{}
tolerationsAdd tolerations to the Crossplane pod deployment.[]
topologySpreadConstraintsAdd topologySpreadConstraints to the Crossplane pod deployment.[]
webhooks.enabledEnable webhooks for Crossplane and installed Provider packages.true

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-separated 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 introduces new features behind feature flags. By default alpha features are off. Crossplane enables beta features by default. 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-functionsEnable support for Composition Functions.
Beta--enable-composition-functions-extra-resourcesEnable support for Composition Functions Extra Resources. Only respected with --enable-composition-functions enabled.
Beta--enable-composition-webhook-schema-validationEnable Composition validation using schemas.
Beta--enable-deployment-runtime-configsEnable support for DeploymentRuntimeConfigs.
Alpha--enable-environment-configsEnable support for EnvironmentConfigs.
Alpha--enable-external-secret-storesEnable support for External Secret Stores.
Alpha--enable-realtime-compositionsEnable support for real time compositions.
Alpha--enable-ssa-claimsEnable support for using server-side apply to sync claims with XRs.
Alpha--enable-usagesEnable support for Usages.
Alpha--enable-dependency-version-upgradesEnable automatic version upgrades of dependencies when updating packages.

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"}'.

Change the default package registry

Beginning with Crossplane version 1.15.0 Crossplane downloads packages from the Upbound Marketplace at xpkg.upbound.io instead of DockerHub.

Change the default registry location during the Crossplane install with --set args='{"--registry=index.docker.io"}'.

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.