| title | toc | weight | indent |
|---|---|---|---|
Install & Configure |
true |
2 |
true |
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.
Installing Crossplane into an existing Kubernetes cluster will require a bit more setup, but can provide more flexibility for users who need it.
brew upgrade
brew install kind
brew install kubectl
brew install helm
kind create cluster --image kindest/node:v1.23.0 --wait 5m-
Helm, minimum version
v3.0.0+.
-
Helm, minimum version
v3.0.0+.
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/crossplanekubectl 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 --develhelm list -n crossplane-system
kubectl get all -n crossplane-systemThe Crossplane CLI extends kubectl with functionality to build, push, and
install Crossplane packages:
curl -sL https://raw.githubusercontent.com/crossplane/crossplane/master/install.sh | shcurl -sL https://raw.githubusercontent.com/crossplane/crossplane/master/install.sh | CHANNEL=master shYou 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 shCrossplane 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
Compositionspecifies which resources a composite resource will be composed of, and how they should be configured. You can create multipleCompositionoptions 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!
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.
kubectl crossplane install configuration registry.upbound.io/xp/getting-started-with-aws:latestWait until all packages become healthy:
watch kubectl get pkg
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.confkubectl create secret generic aws-creds -n crossplane-system --from-file=creds=./creds.confWe 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: credskubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/configure/aws/providerconfig.yamlIf 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.
kubectl crossplane install configuration registry.upbound.io/xp/getting-started-with-aws-with-vpc:latestWait until all packages become healthy:
watch kubectl get pkg
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.confkubectl create secret generic aws-creds -n crossplane-system --from-file=creds=./creds.confWe 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: credskubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/configure/aws/providerconfig.yamlIf 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.
kubectl crossplane install configuration registry.upbound.io/xp/getting-started-with-gcp:latestWait until all packages become healthy:
watch kubectl get pkg
# 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 $SAkubectl create secret generic gcp-creds -n crossplane-system --from-file=creds=./creds.jsonWe 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: creds" | kubectl apply -f -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.
kubectl crossplane install configuration registry.upbound.io/xp/getting-started-with-azure:latestWait until all packages become healthy:
watch kubectl get pkg
# create service principal with Owner role
az ad sp create-for-rbac --sdk-auth --role Owner > "creds.json"kubectl create secret generic azure-creds -n crossplane-system --from-file=creds=./creds.jsonWe 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: credskubectl apply -f https://raw.githubusercontent.com/crossplane/crossplane/master/docs/snippets/configure/azure/providerconfig.yamlNow that you have configured Crossplane with support for PostgreSQLInstance,
you can provision infrastructure.
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 and our community will highlight it here!