diff --git a/docs/master/getting-started/configure.md b/docs/master/getting-started/configure.md index e0b6414a..c34e8053 100644 --- a/docs/master/getting-started/configure.md +++ b/docs/master/getting-started/configure.md @@ -1,7 +1,7 @@ --- title: Configure toc: true -weight: 2 +weight: 202 indent: true --- diff --git a/docs/master/getting-started/install-configure.md b/docs/master/getting-started/install-configure.md new file mode 100644 index 00000000..4eeed35e --- /dev/null +++ b/docs/master/getting-started/install-configure.md @@ -0,0 +1,384 @@ +--- +title: Install & Configure +toc: true +weight: 1 +indent: true +--- + +# Install & Configure Quickstart + +Crossplane can be easily installed into any existing Kubernetes cluster using +the regularly published Helm chart. The Helm chart contains all the custom +resources and controllers needed to deploy and configure Crossplane. + +See [Install] and [Configure] docs for installing alternate versions and more +detailed instructions. + +## Get a Kubernetes Cluster + + +
+
+
+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.17.5 --wait 5m +``` + +
+
+For macOS / Linux use the following: + +* [Kubernetes cluster] + * [Kind] + * [Minikube], minimum version `v0.28+` + * etc. + +* [Helm], minimum version `v2.12.0+`. + * For Helm 2, make sure Tiller is initialized with sufficient permissions to + work on `crossplane-system` namespace. + +
+
+For Windows use the following: + +* [Kubernetes cluster] + * [Kind] + * [Minikube], minimum version `v0.28+` + * etc. + +* [Helm], minimum version `v2.12.0+`. + * For Helm 2, make sure Tiller is initialized with sufficient permissions to + work on `crossplane-system` namespace. + +
+
+ +## Install Crossplane + +
+
+
+Use Helm 3 to install the latest official `alpha` release of Crossplane, suitable for community use and testing: + +``` +kubectl create namespace crossplane-system + +helm repo add crossplane-alpha https://charts.crossplane.io/alpha +helm install crossplane --namespace crossplane-system crossplane-alpha/crossplane +``` + +
+
+Use Helm 2 to install the latest official `alpha` release of Crossplane, suitable for community use and testing: + +``` +kubectl create namespace crossplane-system + +helm repo add crossplane-alpha https://charts.crossplane.io/alpha +helm install --name crossplane --namespace crossplane-system crossplane-alpha/crossplane +``` + +
+
+Use Helm 3 to install the latest `master` pre-release version of Crossplane: + +``` +kubectl create namespace crossplane-system + +helm repo add crossplane-master https://charts.crossplane.io/master/ +helm search repo crossplane-master --devel + +# Kubernetes 1.15 and newer versions +helm install crossplane --namespace crossplane-system crossplane-master/crossplane --version --devel +``` + +For example: +``` +helm install crossplane --namespace crossplane-system crossplane-master/crossplane --version 0.11.0-rc.100.gbc5d311 --devel +``` + +
+
+Use Helm 2 to install the latest `master` pre-release version of Crossplane, which is suitable for testing pre-release versions: + +``` +kubectl create namespace crossplane-system + +helm repo add crossplane-master https://charts.crossplane.io/master/ +helm search crossplane-master --devel + +helm install --name crossplane --namespace crossplane-system crossplane-master/crossplane --version +``` + +For example: + +``` +helm install --name crossplane --namespace crossplane-system crossplane-master/crossplane --version 0.11.0-rc.100.gbc5d311 +``` + +
+
+ +## Install Crossplane CLI +The [Crossplane CLI] adds a set of `kubectl crossplane` commands to simplify common tasks: +``` +curl -sL https://raw.githubusercontent.com/crossplane/crossplane-cli/master/bootstrap.sh | bash +``` + +## Select Provider +Install and configure a provider for Crossplane to use for infrastructure provisioning: + +
+
+
+ +### Install AWS Provider + +``` +PACKAGE=crossplane/provider-aws:master +NAME=provider-aws + +kubectl crossplane package install --cluster --namespace crossplane-system ${PACKAGE} ${NAME} +``` + +### 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 +Create the following `provider.yaml`: + +``` +apiVersion: aws.crossplane.io/v1alpha3 +kind: Provider +metadata: + name: aws-provider +spec: + region: us-west-2 + credentialsSecretRef: + namespace: crossplane-system + name: aws-creds + key: key +``` + +Then apply it: +``` +kubectl apply -f provider.yaml +``` + +
+
+ +### Install GCP Provider + +``` +PACKAGE=crossplane/provider-gcp:master +NAME=provider-gcp + +kubectl crossplane package install --cluster --namespace crossplane-system ${PACKAGE} ${NAME} +``` + +### Get GCP Account Keyfile + +``` +# replace this with your own gcp project id and service account name +PROJECT_ID=my-project +SA_NAME=my-service-account-name + +# create service account +SA="${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" +gcloud iam service-accounts create $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 +Create the following `provider.yaml`: + +``` +apiVersion: gcp.crossplane.io/v1alpha3 +kind: Provider +metadata: + name: gcp-provider +spec: + # replace this with your own gcp project id + projectID: my-project + credentialsSecretRef: + namespace: crossplane-system + name: gcp-creds + key: key +``` + +Then apply it: +``` +kubectl apply -f provider.yaml +``` + +
+
+ +### Install Azure Provider + +``` +PACKAGE=crossplane/provider-azure:master +NAME=provider-azure + +kubectl crossplane package install --cluster --namespace crossplane-system ${PACKAGE} ${NAME} +``` + +### Get Azure Principal Keyfile + +``` +# create service principal with Owner role +az ad sp create-for-rbac --sdk-auth --role Owner > "creds.json" + +# add Azure Active Directory permissions +AZURE_CLIENT_ID=$(jq -r ".clientId" < "./creds.json") + +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 +Create the following `provider.yaml`: + +``` +apiVersion: azure.crossplane.io/v1alpha3 +kind: Provider +metadata: + name: azure-provider +spec: + credentialsSecretRef: + namespace: crossplane-system + name: azure-creds + key: key +``` + +Then apply it: +``` +kubectl apply -f provider.yaml +``` + +
+
+ +### Install Alibaba Provider + +``` +PACKAGE=crossplane/provider-alibaba:master +NAME=provider-alibaba + +kubectl crossplane package install --cluster --namespace crossplane-system ${PACKAGE} ${NAME} +``` + +### Create a Provider Secret + +``` +kubectl create secret generic alibaba-creds --from-literal=accessKeyId= --from-literal=accessKeySecret= +``` + +### Configure the Provider +Create the following `provider.yaml`: + +``` +apiVersion: alibaba.crossplane.io/v1alpha1 +kind: Provider +metadata: + name: alibaba-provider +spec: + credentialsSecretRef: + namespace: crossplane-system + name: alibaba-creds + key: credentials +``` + +Then apply it: +``` +kubectl apply -f provider.yaml +``` + +
+
+ +## Next Steps +Now that you have a provider configured, you can [provision +infrastructure](provision-infrastructure.md). + +## More Info +See [Install] and [Configure] docs for installing alternate versions and more +detailed instructions. + +## Uninstall Provider +``` +kubectl delete -f provider.yaml +kubectl delete secret -n crossplane-system --all +``` + +## Uninstall Crossplane +``` +helm delete crossplane --namespace crossplane-system +``` + +[Install]: install.md +[Configure]: configure.md +[Kubernetes cluster]: https://kubernetes.io/docs/setup/ +[Minikube]: https://kubernetes.io/docs/tasks/tools/install-minikube/ +[Helm]: https://docs.helm.sh/using_helm/ +[Kind]: https://kind.sigs.k8s.io/docs/user/quick-start/ +[Crossplane CLI]: https://github.com/crossplane/crossplane-cli diff --git a/docs/master/getting-started/install.md b/docs/master/getting-started/install.md index dd17e305..160c8fbb 100644 --- a/docs/master/getting-started/install.md +++ b/docs/master/getting-started/install.md @@ -1,7 +1,7 @@ --- title: Install toc: true -weight: 1 +weight: 201 indent: true ---