Skip to main content

Install Crossplane ⏱️ 15m

Your pair:
Running solo locally?

Same cluster, same commands — nothing changes in this module for the solo path. See Solo local setup (k3d) for background.

3.1 Before you start ⏱️ 3m​

Crossplane is a Kubernetes controller — same operator pattern as the built-in Deployment controller — that watches a family of resources you'll meet in the next four modules (XRDs, Compositions, XRs, Managed Resources) and reconciles them into action. After this module Crossplane itself will be running in your cluster, watching nothing yet — module 4 gives it something to watch.

You'll install UXP v2 (Upbound's distribution of Crossplane) via its Helm chart. UXP is Crossplane with a bundled read-only Web UI — everything you learn transfers one-for-one to upstream Crossplane. See the Cheatsheet §1.3 for the full comparison.

Why --devel?

UXP v2 releases are tagged like 2.2.0-up.5, which Helm treats as pre-release. The --devel flag is what tells Helm "install pre-release versions too". It's not actually pre-release code — it's the stable UXP v2 line.

You're about to: add a Helm repo, install the chart, and verify the crossplane Deployment is Available.

3.2 Install the Helm chart ⏱️ 7m​

1. Add the Upbound Helm repo​

helm repo add upbound-stable https://charts.upbound.io/stable
helm repo update upbound-stable

2. Install UXP into crossplane-system​

helm install crossplane upbound-stable/crossplane \
  --version 2.2.0-up.5 \
  --namespace crossplane-system \
  --create-namespace \
  --devel \
  --wait \
  --set webui.enabled=true

--version 2.2.0-up.5 pins the chart to the same revision the workshop's GitOps cluster runs (see gitops/apps/crossplane.yaml) — without it, Helm picks the latest available, which has drifted past what the modules were authored against. --devel is required because the -up.5 suffix is a SemVer pre-release tag that Helm otherwise filters out. --wait makes Helm block until the Crossplane Deployments are Available. On a workshop-sized cluster this usually takes 30–60 seconds. webui.enabled=true turns on the read-only Web UI you'll use in the optional step below.

3. Verify the pods​

kubectl get pods -n crossplane-system

Expected output:

NAME                                      READY   STATUS    RESTARTS   AGE
crossplane-58ff757f44-5vjxz               1/1     Running   0          45s
crossplane-apollo-7d475f549f-bbd6s        3/3     Running   1          45s
crossplane-rbac-manager-75f69f7d64-7xttd  1/1     Running   0          45s
upbound-controller-manager-85cd77fb9-xxx  1/1     Running   0          45s
webui-5c65cc8bdf-xxxxx                    1/1     Running   0          45s

Five pods come up for a UXP v2 install. Two are the ones you'll actually interact with:

  • crossplane — the core Crossplane controller you'd get from any Crossplane install; the long-running program that watches XRDs, Compositions, XRs, Providers, and Functions, and runs a reconciliation loop on each one. Everything in the next four modules depends on this Pod being healthy.
  • webui — the read-only dashboard enabled by webui.enabled=true. You'll use it in §3.3.

The other three are infrastructure you won't touch directly:

What are crossplane-rbac-manager, crossplane-apollo, and upbound-controller-manager?
  • crossplane-rbac-manager — generates ClusterRoles for each XRD you apply, so end-users can get/list the XR kinds you define without you having to write RBAC by hand. Upstream Crossplane ships this too.
  • crossplane-apollo — UXP-specific control-plane component that backs Upbound's managed offering. Benign when you're running UXP locally; it has nothing to do in a standalone install but is still scheduled. A transient restart or two during install is normal — it waits on CRDs the core controller is still registering.
  • upbound-controller-manager — UXP's control-plane orchestrator (sibling to apollo). Same story: extra in local use, required for the Upbound cloud integration you won't exercise here.

If you installed upstream Crossplane (not UXP), only crossplane and crossplane-rbac-manager would appear. The other three are what "UXP" bundles on top; see the Cheatsheet §1.3 comparison.

When the tile turns green, Crossplane is running and you're ready for module 4.

3.3 (Optional) Open the Web UI ⏱️ 5m​

The Web UI shows every Crossplane object in your cluster — Providers, XRDs, Compositions, XRs, and managed resources — in a tree you can click through. It's handy while you're learning; it's not required.

1. Port-forward the service​

Run this in a second terminal (it stays open while you browse):

kubectl port-forward svc/webui -n crossplane-system 8200:80

Leave it running and open http://localhost:8200 in your browser. You'll see a mostly-empty dashboard — there's nothing to compose yet. After modules 4, 5, and 6 you'll come back here to see what you built.

Press Ctrl+C in that terminal when you're done to stop the port-forward.

2. Keep it open for later​

If you want to leave it running through the rest of the workshop: good. Switch to it after each module and watch the tree populate as you install a provider, define an XRD, and apply an XR.

3.4 What just happened​

You installed a Kubernetes controller. The five Pods in crossplane-system are the Crossplane core controller plus its companions; together they're a long-running program that watches certain kinds — Provider, Function, CompositeResourceDefinition (XRD), Composition, and any composite-resource (XR) kinds you define — and runs a reconciliation loop on each one.

Right now Crossplane is watching for those five built-in kinds but no instances of them exist yet, so the loop has nothing to do. In the next four modules you'll feed it work:

  • Module 4 — apply a Function (a Composition's pluggable logic) and your first XRD + Composition + XR. Crossplane will react by creating a ConfigMap.
  • Module 5 — a bigger XRD + Composition that fan out into a frontend + backend.
  • Module 6 — modify the Composition; watch the change propagate.
  • Module 7 — install a Provider and use it to manage a Helm release.

Go deeper​