crossplane
/
docs
mirror of https://github.com/crossplane/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
docs/content/v1.20/software/install.md

17 KiB
Raw Permalink Blame History

title weight
Install Crossplane 100

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

{{< hint type="tip" >}} If you don't have a Kubernetes cluster create one locally with Kind. {{< /hint >}}

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.

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

Update the local Helm chart cache with helm repo update.

helm repo update

Install the Crossplane Helm chart

Install the Crossplane Helm chart with helm install.

{{< hint "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. {{< /hint >}}

Crossplane creates and installs into the crossplane-system namespace.

helm install crossplane \
--namespace crossplane-system \
--create-namespace crossplane-stable/crossplane

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

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

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

helm install crossplane \
--namespace crossplane-system \
--create-namespace crossplane-stable/crossplane \
--version 1.10.0

{{< /hint >}}

Installed deployments

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

kubectl get deployments -n crossplane-system
NAME                      READY   UP-TO-DATE   AVAILABLE   AGE
crossplane                1/1     1            1           8m13s
crossplane-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.

{{<expand "All Crossplane customization options" >}} {{< table "table table-hover table-striped table-sm">}}

Parameter Description Default
affinity Add affinities to the Crossplane pod deployment. {}
args Add custom arguments to the Crossplane pod. []
configuration.packages A list of Configuration packages to install. []
customAnnotations Add custom annotations to the Crossplane pod deployment. {}
customLabels Add custom labels to the Crossplane pod deployment. {}
deploymentStrategy The deployment strategy for the Crossplane and RBAC Manager pods. "RollingUpdate"
dnsPolicy Specify the dnsPolicy to be used by the Crossplane pod. ""
extraEnvVarsCrossplane Add custom environmental variables to the Crossplane pod deployment. Replaces any . in a variable name with _. For example, SAMPLE.KEY=value1 becomes SAMPLE_KEY=value1. {}
extraEnvVarsRBACManager Add 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. {}
extraObjects To add arbitrary Kubernetes Objects during a Helm Install []
extraVolumeMountsCrossplane Add custom volumeMounts to the Crossplane pod. {}
extraVolumesCrossplane Add custom volumes to the Crossplane pod. {}
function.packages A list of Function packages to install []
functionCache.medium Set to Memory to hold the function cache in a RAM backed file system. Useful for Crossplane development. ""
functionCache.pvc The name of a PersistentVolumeClaim to use as the function cache. Disables the default function cache emptyDir Volume. ""
functionCache.sizeLimit The size limit for the function cache. If medium is Memory the sizeLimit can't exceed Node memory. "512Mi"
hostNetwork Enable hostNetwork for the Crossplane deployment. Caution: enabling hostNetwork grants the Crossplane Pod access to the host network namespace. Consider setting dnsPolicy to ClusterFirstWithHostNet. false
image.pullPolicy The image pull policy used for Crossplane and RBAC Manager pods. "IfNotPresent"
image.repository Repository for the Crossplane pod image. "xpkg.crossplane.io/crossplane/crossplane"
image.tag The Crossplane image tag. Defaults to the value of appVersion in Chart.yaml. ""
imagePullSecrets The imagePullSecret names to add to the Crossplane ServiceAccount. []
leaderElection Enable leader election for the Crossplane pod. true
metrics.enabled Enable Prometheus path, port and scrape annotations and expose port 8080 for both the Crossplane and RBAC Manager pods. false
metrics.port The port the metrics server listens on. ""
nodeSelector Add nodeSelectors to the Crossplane pod deployment. {}
packageCache.configMap The name of a ConfigMap to use as the package cache. Disables the default package cache emptyDir Volume. ""
packageCache.medium Set to Memory to hold the package cache in a RAM backed file system. Useful for Crossplane development. ""
packageCache.pvc The name of a PersistentVolumeClaim to use as the package cache. Disables the default package cache emptyDir Volume. ""
packageCache.sizeLimit The size limit for the package cache. If medium is Memory the sizeLimit can't exceed Node memory. "20Mi"
podSecurityContextCrossplane Add a custom securityContext to the Crossplane pod. {}
podSecurityContextRBACManager Add a custom securityContext to the RBAC Manager pod. {}
priorityClassName The PriorityClass name to apply to the Crossplane and RBAC Manager pods. ""
provider.packages A list of Provider packages to install. []
rbacManager.affinity Add affinities to the RBAC Manager pod deployment. {}
rbacManager.args Add custom arguments to the RBAC Manager pod. []
rbacManager.deploy Deploy the RBAC Manager pod and its required roles. true
rbacManager.leaderElection Enable leader election for the RBAC Manager pod. true
rbacManager.nodeSelector Add nodeSelectors to the RBAC Manager pod deployment. {}
rbacManager.replicas The number of RBAC Manager pod replicas to deploy. 1
rbacManager.revisionHistoryLimit The number of RBAC Manager ReplicaSets to retain. nil
rbacManager.skipAggregatedClusterRoles Don't install aggregated Crossplane ClusterRoles. false
rbacManager.tolerations Add tolerations to the RBAC Manager pod deployment. []
rbacManager.topologySpreadConstraints Add topologySpreadConstraints to the RBAC Manager pod deployment. []
readiness.port The port the readyz server listens on. ""
registryCaBundleConfig.key The ConfigMap key containing a custom CA bundle to enable fetching packages from registries with unknown or untrusted certificates. ""
registryCaBundleConfig.name The ConfigMap name containing a custom CA bundle to enable fetching packages from registries with unknown or untrusted certificates. ""
replicas The number of Crossplane pod replicas to deploy. 1
resourcesCrossplane.limits.cpu CPU resource limits for the Crossplane pod. "500m"
resourcesCrossplane.limits.memory Memory resource limits for the Crossplane pod. "1024Mi"
resourcesCrossplane.requests.cpu CPU resource requests for the Crossplane pod. "100m"
resourcesCrossplane.requests.memory Memory resource requests for the Crossplane pod. "256Mi"
resourcesRBACManager.limits.cpu CPU resource limits for the RBAC Manager pod. "100m"
resourcesRBACManager.limits.memory Memory resource limits for the RBAC Manager pod. "512Mi"
resourcesRBACManager.requests.cpu CPU resource requests for the RBAC Manager pod. "100m"
resourcesRBACManager.requests.memory Memory resource requests for the RBAC Manager pod. "256Mi"
revisionHistoryLimit The number of Crossplane ReplicaSets to retain. nil
runtimeClassName The runtimeClassName name to apply to the Crossplane and RBAC Manager pods. ""
securityContextCrossplane.allowPrivilegeEscalation Enable allowPrivilegeEscalation for the Crossplane pod. false
securityContextCrossplane.readOnlyRootFilesystem Set the Crossplane pod root file system as read-only. true
securityContextCrossplane.runAsGroup The group ID used by the Crossplane pod. 65532
securityContextCrossplane.runAsUser The user ID used by the Crossplane pod. 65532
securityContextRBACManager.allowPrivilegeEscalation Enable allowPrivilegeEscalation for the RBAC Manager pod. false
securityContextRBACManager.readOnlyRootFilesystem Set the RBAC Manager pod root file system as read-only. true
securityContextRBACManager.runAsGroup The group ID used by the RBAC Manager pod. 65532
securityContextRBACManager.runAsUser The user ID used by the RBAC Manager pod. 65532
service.customAnnotations Configure annotations on the service object. Only enabled when webhooks.enabled = true {}
serviceAccount.create Specifies whether Crossplane ServiceAccount should be created true
serviceAccount.customAnnotations Add custom annotations to the Crossplane ServiceAccount. {}
serviceAccount.name Provide the name of an already created Crossplane ServiceAccount. Required when serviceAccount.create is false ""
tolerations Add tolerations to the Crossplane pod deployment. []
topologySpreadConstraints Add topologySpreadConstraints to the Crossplane pod deployment. []
webhooks.enabled Enable webhooks for Crossplane and installed Provider packages. true
webhooks.port The port the webhook server listens on. ""
{{< /table >}}
{{< /expand >}}

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:

helm install crossplane \
--namespace crossplane-system \
--create-namespace \
crossplane-stable/crossplane \
--set image.pullPolicy=Always

Helm supports comma-separated arguments.

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

helm install crossplane \
--namespace crossplane-system \
--create-namespace \
crossplane-stable/crossplane \
--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.

replicas: 2

image:
  pullPolicy: Always

Apply the file with helm install:

helm install crossplane \
--namespace crossplane-system \
--create-namespace \
crossplane-stable/crossplane \
-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.

{{< expand "Feature flags" >}} {{< table caption="Feature flags" >}}

Status Flag Description
Beta --enable-composition-webhook-schema-validation Enable Composition validation using schemas.
Beta --enable-deployment-runtime-configs Enable support for DeploymentRuntimeConfigs.
Beta --enable-usages Enable support for Usages.
Beta --enable-ssa-claims Enable support for using server-side apply to sync claims with XRs.
Beta --enable-realtime-compositions Enable support for real time compositions.
Alpha --enable-external-secret-stores Enable support for External Secret Stores.
Alpha --enable-dependency-version-upgrades Enable automatic version upgrades of dependencies when updating packages.
Alpha --enable-dependency-version-downgrades Enable automatic version downgrades of dependencies when updating packages.
Alpha --enable-signature-verification Enable support for package signature verification via ImageConfig API.
Alpha --enable-function-response-cache Enable support for caching composition function responses.
{{< /table >}}
{{< /expand >}}

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.20.0 Crossplane uses the crossplane-contrib GitHub Container Registry at xpkg.crossplane.io by default for downloading and installing packages.

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.

{{< hint "warning" >}} Don't use Crossplane master releases in production. Only use stable channel. Only use master for testing and development. {{< /hint >}}

Add the Crossplane master Helm repository

Add the Crossplane repository with the helm repo add command.

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

Update the local Helm chart cache with helm repo update.

helm repo update

Install the Crossplane master Helm chart

Install the Crossplane master Helm chart with helm install.

{{< hint "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. {{< /hint >}}

Crossplane creates and installs into the crossplane-system namespace.

helm install crossplane \
--namespace crossplane-system \
--create-namespace crossplane-master/crossplane \
--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.