title	toc	weight	indent
Install & Configure	true	2	true

Choosing Hosted or Self-Hosted Crossplane

Users looking to use Crossplane for the first time have two options available to them today. The first way is to use a hosted Crossplane service like Upbound Cloud. Alternatively, users looking for some more flexibility can install Crossplane into their own Kubernetes cluster.

Crossplane will be installed using the regularly published Helm chart. The Helm chart contains all the custom resources and controllers needed to deploy and configure Crossplane.

Users choosing the self-hosted option can reference our Install and Configure docs for installing alternate versions and more detailed instructions.

Hosted Crossplane
Self-Hosted Crossplane

Start with a Hosted Crossplane

Upbound Cloud is a managed service of Crossplane created by the founders of Crossplane. You can create an account to get started. Once logged in, you can create and then connect to your hosted Crossplane cluster.

Once you've completed these two steps, skip down to Install Crossplane CLI for further setup instructions.

Note that Upbound Cloud does not yet include support for Crossplane's alpha Open Application Model (OAM) functionality. You'll need to install a self hosted Crossplane if you'd like to try the 'Run Applications' part of this guide.

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

Start with a Self-Hosted 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

macOS via Homebrew
macOS / Linux
Windows

For macOS via Homebrew use the following:

brew upgrade
brew install kind
brew install kubectl
brew install helm

kind create cluster --image kindest/node:v1.16.15 --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

Helm 3 (stable)
Helm 3 (latest)

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

kubectl create namespace crossplane-system

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

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

Note that OAM is an alpha feature that is disabled by default. Make sure to install the Crossplane Helm chart with the --set alpha.oam.enabled=true flag if you would like to follow the 'Run Applications' part of the guide.

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

kubectl create namespace crossplane-system

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

helm install crossplane --namespace crossplane-system crossplane-master/crossplane \
  --devel --version <version>

For example:

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

Note that OAM is an alpha feature that is disabled by default. Make sure to install the Crossplane Helm chart with the --set alpha.oam.enabled=true flag if you would like to follow the 'Run Applications' part of the guide.

Check Crossplane Status

helm list -n crossplane-system

kubectl get all -n crossplane-system

Install Crossplane CLI

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

Stable
Latest

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

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

You may also specify 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.

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

Select Provider

Now from your terminal, install and configure a provider for Crossplane to use for infrastructure provisioning:

AWS
GCP
Azure
Alibaba

Install AWS Provider

kubectl crossplane install provider crossplane/provider-aws:v0.16.0

Wait until the provider becomes healthy:

kubectl get provider.pkg --watch

Get AWS Account Keyfile

Using an AWS account with permissions to manage RDS databases:

AWS_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

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

Configure the Provider

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

apiVersion: aws.crossplane.io/v1beta1
kind: ProviderConfig
metadata:
  name: default
spec:
  credentials:
    source: Secret
    secretRef:
      namespace: crossplane-system
      name: aws-creds
      key: key

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

Install GCP Provider

kubectl crossplane install provider crossplane/provider-gcp:v0.14.0

Wait until the provider becomes healthy:

kubectl get provider.pkg --watch

Get GCP Account Keyfile

# replace this with your own gcp project id and the name of the service account
# that will be created.
PROJECT_ID=my-project
NEW_SA_NAME=test-service-account-name

# create service account
SA="${NEW_SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"
gcloud iam service-accounts create $NEW_SA_NAME --project $PROJECT_ID

# enable cloud API
SERVICE="sqladmin.googleapis.com"
gcloud services enable $SERVICE --project $PROJECT_ID

# grant access to cloud API
ROLE="roles/cloudsql.admin"
gcloud projects add-iam-policy-binding --role="$ROLE" $PROJECT_ID --member "serviceAccount:$SA"

# create service account keyfile
gcloud iam service-accounts keys create creds.json --project $PROJECT_ID --iam-account $SA

Create a Provider Secret

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

Configure the Provider

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

# replace this with your own gcp project id
PROJECT_ID=my-project
echo "apiVersion: gcp.crossplane.io/v1beta1
kind: ProviderConfig
metadata:
  name: default
spec:
  projectID: ${PROJECT_ID}
  credentials:
    source: Secret
    secretRef:
      namespace: crossplane-system
      name: gcp-creds
      key: key" | kubectl apply -f -

Install Azure Provider

kubectl crossplane install provider crossplane/provider-azure:v0.14.0

Wait until the provider becomes healthy:

kubectl get provider.pkg --watch

Get Azure Principal Keyfile

# create service principal with Owner role
az ad sp create-for-rbac --sdk-auth --role Owner > "creds.json"

# we need to get the clientId from the json file to add Azure Active Directory
# permissions.
if which jq > /dev/null 2>&1; then
  AZURE_CLIENT_ID=$(jq -r ".clientId" < "./creds.json")
else
  AZURE_CLIENT_ID=$(cat creds.json | grep clientId | cut -c 16-51)
fi

RW_ALL_APPS=1cda74f2-2616-4834-b122-5cb1b07f8a59
RW_DIR_DATA=78c8a3c8-a07e-4b9e-af1b-b5ccab50a175
AAD_GRAPH_API=00000002-0000-0000-c000-000000000000

az ad app permission add --id "${AZURE_CLIENT_ID}" --api ${AAD_GRAPH_API} --api-permissions ${RW_ALL_APPS}=Role ${RW_DIR_DATA}=Role
az ad app permission grant --id "${AZURE_CLIENT_ID}" --api ${AAD_GRAPH_API} --expires never > /dev/null
az ad app permission admin-consent --id "${AZURE_CLIENT_ID}"

Create a Provider Secret

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

Configure the Provider

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

apiVersion: azure.crossplane.io/v1beta1
kind: ProviderConfig
metadata:
  name: default
spec:
  credentials:
    source: Secret
    secretRef:
      namespace: crossplane-system
      name: azure-creds
      key: key

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

Install Alibaba Provider

kubectl crossplane install provider crossplane/provider-alibaba:v0.5.0

Wait until the provider becomes healthy:

kubectl get provider.pkg --watch

Create a Provider Secret

# Replace <your-key> and <your-secret> with your actual key id and key secret.
kubectl create secret generic alibaba-creds --from-literal=accessKeyId=<your-key> --from-literal=accessKeySecret=<your-secret> -n crossplane-system

Configure the Provider

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

apiVersion: alibaba.crossplane.io/v1alpha1
kind: ProviderConfig
metadata:
  name: default
spec:
  region: cn-beijing
  credentials:
    source: Secret
    secretRef:
      namespace: crossplane-system
      name: alibaba-creds
      # "key" field does not have any effect right now but it has to be given.
      # See https://github.com/crossplane/crossplane-runtime/issues/215
      key: credentials

kubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/configure/alibaba/providerconfig.yaml

Next Steps

Now that you have a provider configured, you can provision infrastructure.

More Info

See Install and Configure docs for installing alternate versions and more detailed instructions.

Uninstall Provider

Let's check whether there are any managed resources before deleting the provider.

kubectl get managed

If there are any, please delete them first, so you don't lose the track of them. Then delete all the ProviderConfigs you created. An example command if you used AWS Provider:

kubectl delete providerconfig.aws --all

List installed providers:

kubectl get provider.pkg

Delete the one you want to delete:

kubectl delete provider.pkg <provider-name>

Uninstall Crossplane

helm delete crossplane --namespace crossplane-system

kubectl delete namespace crossplane-system

Helm does not delete CRD objects. You can delete the ones Crossplane created with the following commands:

kubectl patch lock lock -p '{"metadata":{"finalizers": []}}' --type=merge
kubectl get crd -o name | grep crossplane.io | xargs kubectl delete

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

install-configure.md

install-configure.md

Choosing Hosted or Self-Hosted Crossplane

Start with a Hosted Crossplane

Start with a Self-Hosted Crossplane

Get a Kubernetes Cluster

Install Crossplane

Check Crossplane Status

Install Crossplane CLI

Select Provider

Install AWS Provider

Get AWS Account Keyfile

Create a Provider Secret

Configure the Provider

Install GCP Provider

Get GCP Account Keyfile

Create a Provider Secret

Configure the Provider

Install Azure Provider

Get Azure Principal Keyfile

Create a Provider Secret

Configure the Provider

Install Alibaba Provider

Create a Provider Secret

Configure the Provider

Next Steps

More Info

Uninstall Provider

Uninstall Crossplane

Files

install-configure.md

Latest commit

History

install-configure.md

File metadata and controls

Choosing Hosted or Self-Hosted Crossplane

Start with a Hosted Crossplane

Start with a Self-Hosted Crossplane

Get a Kubernetes Cluster

Install Crossplane

Check Crossplane Status

Install Crossplane CLI

Select Provider

Install AWS Provider

Get AWS Account Keyfile

Create a Provider Secret

Configure the Provider

Install GCP Provider

Get GCP Account Keyfile

Create a Provider Secret

Configure the Provider

Install Azure Provider

Get Azure Principal Keyfile

Create a Provider Secret

Configure the Provider

Install Alibaba Provider

Create a Provider Secret

Configure the Provider

Next Steps

More Info

Uninstall Provider

Uninstall Crossplane