Install Crossplane from source code

Building Crossplane from the source code gives you complete control over the build and installation process.

You build the Crossplane container image and Helm chart directly from the source code, push the image to your own registry, and install to your Kubernetes cluster.

{{< hint "important" >}} Installing Crossplane from source is an advanced installation path for users who require complete control over the build and deployment process. Most users should follow the [standard installation instructions]({{<ref "../get-started/install.md">}}) {{< /hint >}}

This approach is useful when you want to:

• Control the entire build and deployment pipeline
• Use your own container registry and cluster
• Deploy to offline or restricted environments
• Build from a specific commit or branch

Prerequisites

Building Crossplane from source requires:

• Docker
• Earthly version v0.8.16 or later
• kubectl configured for your target cluster
• An actively supported Kubernetes version
• Helm version v3.2.0 or later
• Access to a container registry (Docker Hub, GHCR, Harbor, or any OCI compliant registry)

Clone the Crossplane repository

Clone the Crossplane repository and optionally checkout a specific release.

git clone https://github.com/crossplane/crossplane.git
cd crossplane

{{< hint "tip" >}} To build a specific release, checkout the release tag before building.

git checkout v2.0.2

{{< /hint >}}

Determine artifacts destination

Identify the registry and version tag where you will push your built software artifacts and save them in environment variables:

export REGISTRY="your-registry.com/your-org"; \
  export VERSION="v2.0.0-yourtag"

Build the artifacts

Build Crossplane binaries, container image, and Helm chart for multi-platform architectures:

earthly +multiplatform-build \
  --CROSSPLANE_REPO=${REGISTRY}/crossplane \
  --CROSSPLANE_VERSION=${VERSION}

Earthly creates the container image locally and saves the binaries and Helm chart under _output/bin and _output/charts/ respectively.

Push the image to your registry

Log in to your registry of choice and push the Crossplane image that was built in the previous steps.

{{< hint "tip" >}} Ensure you log into your registry before attempting to push. {{< /hint >}}

docker push ${REGISTRY}/crossplane:${VERSION}

Install Crossplane with the custom image

Locate the built Helm chart in the _output/charts/ directory.

CHART_PATH="_output/charts/crossplane-${VERSION#v}.tgz"

Install Crossplane to your cluster using the custom image.

helm install crossplane ${CHART_PATH} \
  --namespace crossplane-system \
  --create-namespace \
  --set image.repository=${REGISTRY}/crossplane \
  --set image.tag=${VERSION} \
  --set image.pullPolicy=IfNotPresent

{{< hint "important" >}} If your registry requires authentication, create an imagePullSecret before installing.

kubectl create secret docker-registry regcred \
  --docker-server=${REGISTRY} \
  --docker-username=<username> \
  --docker-password=<password> \
  --namespace crossplane-system

Add the secret reference to the helm install command.

--set imagePullSecrets[0].name=regcred

{{< /hint >}}

Verify the installation

View the installed Crossplane pods with kubectl get pods.

kubectl get pods -n crossplane-system
NAME                                       READY   STATUS    RESTARTS   AGE
crossplane-5644774bd4-zvcwc                1/1     Running   0          72s
crossplane-rbac-manager-84dc89c564-b9x6q   1/1     Running   0          72s

Verify the Crossplane deployment is using your custom image.

kubectl get deployment crossplane -n crossplane-system -o jsonpath='{.spec.template.spec.containers[0].image}'
your-registry.com/your-org/crossplane:v2.0.0-yourtag

Optional: Build the Crossplane CLI

The crossplane CLI provides commands for managing Crossplane resources. You can optionally build this binary from source code for your local machine and use it to manage your control plane.

Build the CLI for your local machine.

earthly +build --CROSSPLANE_VERSION=${VERSION}

Earthly creates the CLI binary in _output/bin/<OS>_<ARCH>/. Copy it to your system path.

For macOS ARM64:

sudo cp _output/bin/darwin_arm64/crank /usr/local/bin/crossplane
chmod +x /usr/local/bin/crossplane

For Linux AMD64:

sudo cp _output/bin/linux_amd64/crank /usr/local/bin/crossplane
chmod +x /usr/local/bin/crossplane

Verify the installation.

crossplane version
v2.0.0-yourtag