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.

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.

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

1git checkout v2.0.2

Determine artifacts destination

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

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

Build the artifacts

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

1earthly +multiplatform-build \
2  --CROSSPLANE_REPO=${REGISTRY}/crossplane \
3  --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.

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

Install Crossplane with the custom image

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

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

Install Crossplane to your cluster using the custom image.

1helm install crossplane ${CHART_PATH} \
2  --namespace crossplane-system \
3  --create-namespace \
4  --set image.repository=${REGISTRY}/crossplane \
5  --set image.tag=${VERSION} \
6  --set image.pullPolicy=IfNotPresent

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

1--set imagePullSecrets[0].name=regcred

Verify the installation

View the installed Crossplane pods with kubectl get pods.

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

Verify the Crossplane deployment is using your custom image.

1kubectl get deployment crossplane -n crossplane-system -o jsonpath='{.spec.template.spec.containers[0].image}'
2your-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.

1earthly +build --CROSSPLANE_VERSION=${VERSION}

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

For macOS ARM64:

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

For Linux AMD64:

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

Verify the installation.

1crossplane version
2v2.0.0-yourtag