diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 000000000..b3a0e4e0c --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,90 @@ +# Quickstart + +This is a quickstart guide for getting Cluster API Operator up and running on your Kubernetes cluster. + +For more detailed information, please refer to the full documentation. + +## Prerequisites + +- [Running Kubernetes cluster](https://cluster-api.sigs.k8s.io/user/quick-start#install-andor-configure-a-kubernetes-cluster). +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) for interacting with the management cluster. +- [Helm](https://helm.sh/docs/intro/install/) for installing operator on the cluster (optional). + +## Install and configure Cluster API Operator + +### Configuring credential for cloud providers + +Instead of using environment variables as clusterctl does, Cluster API Operator uses Kubernetes secrets to store credentials for cloud providers. Refer to [provider documentation](https://cluster-api.sigs.k8s.io/user/quick-start#initialization-for-common-providers) on which credentials are required. + +This example uses AWS provider, but the same approach can be used for other providers. + +```bash +export CREDENTIALS_SECRET_NAME="credentials-secret" +export CREDENTIALS_SECRET_NAMESPACE="default" + +kubectl create secret generic "${CREDENTIALS_SECRET_NAME}" --from-literal=AWS_B64ENCODED_CREDENTIALS="${AWS_B64ENCODED_CREDENTIALS}" --namespace "${CREDENTIALS_SECRET_NAMESPACE}" +``` + +### Installing Cluster API Operator + +Add helm repository: + +```bash +helm repo add capi-operator https://kubernetes-sigs.github.io/cluster-api-operator +helm repo update +``` + +Deploy Cluster API components with docker provider using a single command during operator installation + +```bash +helm install capi-operator capi-operator/cluster-api-operator --create-namespace -n capi-operator-system --set infrastructure=docker --set cert-manager.enabled=true --set configSecret.name=${CREDENTIALS_SECRET_NAME} --set configSecret.namespace=${CREDENTIALS_SECRET_NAMESPACE} --wait --timeout 90s +``` + +Docker provider can be replaced by any provider supported by [clusterctl](https://cluster-api.sigs.k8s.io/reference/providers.html?highlight=hetz#infrastructure). + +Other options for installing Cluster API Operator are described in [full documentation](README.md#installation). + +# Example API Usage + +Deploy latest version of core Cluster API components: + +```yaml +apiVersion: operator.cluster.x-k8s.io/v1alpha2 +kind: CoreProvider +metadata: + name: cluster-api + namespace: capi-system + +``` + +Deploy Cluster API AWS provider with specific version, custom manager options and flags: + +```yaml +--- +apiVersion: operator.cluster.x-k8s.io/v1alpha2 +kind: InfrastructureProvider +metadata: + name: aws + namespace: capa-system +spec: + version: v2.1.4 + configSecret: + name: aws-variables + manager: + # These top level controller manager flags, supported by all the providers. + # These flags come with sensible defaults, thus requiring no or minimal + # changes for the most common scenarios. + metrics: + bindAddress: ":8181" + syncPeriod: "500s" + fetchConfig: + url: https://github.com/kubernetes-sigs/cluster-api-provider-aws/releases + deployment: + containers: + - name: manager + args: + # These are controller flags that are specific to a provider; usage + # is reserved for advanced scenarios only. + "--awscluster-concurrency": "12" + "--awsmachine-concurrency": "11" +```