Install & Configure

On this page

This document is for an older version of Crossplane.

This document applies to Crossplane version v1.9 and not to the latest release v1.11.

Choosing Your Crossplane Distribution

Users looking to use Crossplane for the first time have two options available to them today. The first way is to use the version of Crossplane which is maintained and released by the community and found on the Crossplane GitHub.

The second option is to use a vendor supported Crossplane distribution. These distributions are certified by the CNCF to be conformant with Crossplane, but may include additional features or tooling around it that makes it easier to use in production environments.

Start with Upstream Crossplane

Installing Crossplane into an existing Kubernetes cluster will require a bit more setup, but can provide more flexibility for users who need it.

Get a Kubernetes Cluster

For macOS via Homebrew use the following:

1brew upgrade
2brew install kind
3brew install kubectl
4brew install helm
5kind create cluster --image kindest/node:v1.23.0 --wait 5m

For macOS / Linux use the following:

[Kubernetes cluster]
- [Kind]
- [Minikube], minimum version v0.28+
- etc.
[Helm], minimum version v3.0.0+.

For Windows use the following:

[Kubernetes cluster]
- [Kind]
- [Minikube], minimum version v0.28+
- etc.
[Helm], minimum version v3.0.0+.

Install Crossplane

Use Helm 3 to install the latest official stable release of Crossplane, suitable for community use and testing:

1kubectl create namespace crossplane-system
2helm repo add crossplane-stable https://charts.crossplane.io/stable
3helm repo update
4
5helm install crossplane --namespace crossplane-system crossplane-stable/crossplane

Use Helm 3 to install the latest pre-release version of Crossplane:

1kubectl create namespace crossplane-system
2
3helm repo add crossplane-master https://charts.crossplane.io/master/
4helm repo update
5helm search repo crossplane-master --devel
6
7helm install crossplane --namespace crossplane-system crossplane-master/crossplane \
8  --devel --version <version>

For example:

1helm install crossplane --namespace crossplane-system crossplane-master/crossplane \
2  --version 0.11.0-rc.100.gbc5d311 --devel

Check Crossplane Status

1helm list -n crossplane-system
2
3kubectl get all -n crossplane-system

Install Crossplane CLI

The Crossplane CLI extends kubectl with functionality to build, push, and install [Crossplane packages]:

1curl -sL https://raw.githubusercontent.com/crossplane/crossplane/master/install.sh | sh

1curl -sL https://raw.githubusercontent.com/crossplane/crossplane/master/install.sh | XP_CHANNEL=master sh

You may also specify XP_VERSION for download if you would like to select a specific version from the given release channel. If a version is not specified the latest version from the release channel will be used.

1curl -sL https://raw.githubusercontent.com/crossplane/crossplane/master/install.sh | XP_CHANNEL=master XP_VERSION=v1.0.0-rc.0.130.g94f34fd3 sh

Select a Getting Started Configuration

Crossplane goes beyond simply modelling infrastructure primitives as custom resources - it enables you to define new custom resources with schemas of your choosing. We call these “composite resources” (XRs). Composite resources compose managed resources – Kubernetes custom resources that offer a high fidelity representation of an infrastructure primitive, like an SQL instance or a firewall rule.

We use two special Crossplane resources to define and configure these new custom resources:

A CompositeResourceDefinition (XRD) defines a new kind of composite resource, including its schema. An XRD may optionally offer a claim (XRC).
A Composition specifies which resources a composite resource will be composed of, and how they should be configured. You can create multiple Composition options for each composite resource.

XRDs and Compositions may be packaged and installed as a configuration. A configuration is a [package] of composition configuration that can easily be installed to Crossplane by creating a declarative Configuration resource, or by using kubectl crossplane install configuration.

In the examples below we will install a configuration that defines a new XPostgreSQLInstance XR and PostgreSQLInstance XRC that takes a single storageGB parameter, and creates a connection Secret with keys for username, password, and endpoint. A Configuration exists for each provider that can satisfy a PostgreSQLInstance. Let’s get started!

Install Configuration Package

If you prefer to see the contents of this configuration package and how it is constructed prior to install, skip ahead to the [create a configuration] section.

1kubectl crossplane install configuration registry.upbound.io/xp/getting-started-with-aws:v1.9.1

Wait until all packages become healthy:

1watch kubectl get pkg

Get AWS Account Keyfile

Using an AWS account with permissions to manage RDS databases:

1AWS_PROFILE=default && echo -e "[default]\naws_access_key_id = $(aws configure get aws_access_key_id --profile $AWS_PROFILE)\naws_secret_access_key = $(aws configure get aws_secret_access_key --profile $AWS_PROFILE)" > creds.conf

Create a Provider Secret

1kubectl create secret generic aws-creds -n crossplane-system --from-file=creds=./creds.conf

Configure the Provider

We will create the following ProviderConfig object to configure credentials for AWS Provider:

 1apiVersion: aws.crossplane.io/v1beta1
 2kind: ProviderConfig
 3metadata:
 4  name: default
 5spec:
 6  credentials:
 7    source: Secret
 8    secretRef:
 9      namespace: crossplane-system
10      name: aws-creds
11      key: creds

1kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/release-1.9/docs/snippets/configure/aws/providerconfig.yaml

Install Configuration Package

If you prefer to see the contents of this configuration package and how it is constructed prior to install, skip ahead to the [create a configuration] section.

1kubectl crossplane install configuration registry.upbound.io/xp/getting-started-with-aws-with-vpc:v1.9.1

Wait until all packages become healthy:

1watch kubectl get pkg

Get AWS Account Keyfile

Using an AWS account with permissions to manage RDS databases:

1AWS_PROFILE=default && echo -e "[default]\naws_access_key_id = $(aws configure get aws_access_key_id --profile $AWS_PROFILE)\naws_secret_access_key = $(aws configure get aws_secret_access_key --profile $AWS_PROFILE)" > creds.conf

Create a Provider Secret

1kubectl create secret generic aws-creds -n crossplane-system --from-file=creds=./creds.conf

Configure the Provider

We will create the following ProviderConfig object to configure credentials for AWS Provider:

 1apiVersion: aws.crossplane.io/v1beta1
 2kind: ProviderConfig
 3metadata:
 4  name: default
 5spec:
 6  credentials:
 7    source: Secret
 8    secretRef:
 9      namespace: crossplane-system
10      name: aws-creds
11      key: creds

1kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/release-1.9/docs/snippets/configure/aws/providerconfig.yaml

Install Configuration Package

If you prefer to see the contents of this configuration package and how it is constructed prior to install, skip ahead to the [create a configuration] section.

1kubectl crossplane install configuration registry.upbound.io/xp/getting-started-with-gcp:v1.9.1

Wait until all packages become healthy:

watch kubectl get pkg

Get GCP Account Keyfile

 1# replace this with your own gcp project id and the name of the service account
 2# that will be created.
 3PROJECT_ID=my-project
 4NEW_SA_NAME=test-service-account-name
 5
 6# create service account
 7SA="${NEW_SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"
 8gcloud iam service-accounts create $NEW_SA_NAME --project $PROJECT_ID
 9
10# enable cloud API
11SERVICE="sqladmin.googleapis.com"
12gcloud services enable $SERVICE --project $PROJECT_ID
13
14# grant access to cloud API
15ROLE="roles/cloudsql.admin"
16gcloud projects add-iam-policy-binding --role="$ROLE" $PROJECT_ID --member "serviceAccount:$SA"
17
18# create service account keyfile
19gcloud iam service-accounts keys create creds.json --project $PROJECT_ID --iam-account $SA

Create a Provider Secret

1kubectl create secret generic gcp-creds -n crossplane-system --from-file=creds=./creds.json

Configure the Provider

We will create the following ProviderConfig object to configure credentials for GCP Provider:

 1# replace this with your own gcp project id
 2PROJECT_ID=my-project
 3echo "apiVersion: gcp.crossplane.io/v1beta1
 4kind: ProviderConfig
 5metadata:
 6  name: default
 7spec:
 8  projectID: ${PROJECT_ID}
 9  credentials:
10    source: Secret
11    secretRef:
12      namespace: crossplane-system
13      name: gcp-creds
14      key: creds" | kubectl apply -f -

Install Configuration Package

If you prefer to see the contents of this configuration package and how it is constructed prior to install, skip ahead to the [create a configuration] section.

1kubectl crossplane install configuration registry.upbound.io/xp/getting-started-with-azure:v1.9.1

Wait until all packages become healthy:

watch kubectl get pkg

Get Azure Principal Keyfile

1# create service principal with Owner role
2az ad sp create-for-rbac --role Contributor --scopes /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx > "creds.json"

Create a Provider Secret

1kubectl create secret generic azure-creds -n crossplane-system --from-file=creds=./creds.json

Configure the Provider

We will create the following ProviderConfig object to configure credentials for Azure Provider:

 1apiVersion: azure.crossplane.io/v1beta1
 2kind: ProviderConfig
 3metadata:
 4  name: default
 5spec:
 6  credentials:
 7    source: Secret
 8    secretRef:
 9      namespace: crossplane-system
10      name: azure-creds
11      key: creds

1kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/release-1.9/docs/snippets/configure/azure/providerconfig.yaml

Next Steps

Now that you have configured Crossplane with support for PostgreSQLInstance, you can [provision infrastructure].

Start with a Downstream Distribution

Upbound, the founders of Crossplane, maintains a free and open source downstream distribution of Crossplane which makes getting started with Crossplane easy. Universal Crossplane, or UXP for short, connects to Upbound’s hosted management console and Registry to make it easier to develop, debug, and manage Provider and Configuration packages.

[Get started with Universal Crossplane] on the Upbound Documentation site.

Want see another hosted Crossplane service listed? Please [reach out on Slack][Slack] and our community will highlight it here!

More Info

See Install and Configure docs for installing alternate versions and more detailed instructions.
See Uninstall docs for cleaning up resources, packages, and Crossplane itself.
See Providers for installing and using different providers beyond AWS, GCP and Azure mentionded in this guide.