|
| 1 | +# Getting started with CAPG |
| 2 | + |
| 3 | +In this section we'll cover the basics of how to prepare your environment to use Cluster API Provider for GCP. |
| 4 | + |
| 5 | +<aside class="note"> |
| 6 | + |
| 7 | +<h1>Tip</h1> |
| 8 | + |
| 9 | +This covers the specifics of CAPG but won't go into detail of core CAPI basics. For more information on how CAPI works and how to interact with different providers, you can refer to [CAPI Quick Start](https://cluster-api.sigs.k8s.io/user/quick-start). |
| 10 | + |
| 11 | +</aside> |
| 12 | + |
| 13 | +Before installing CAPG, your Kubernetes cluster has to be transformed into a CAPI management cluster. If you have already done this, you can jump directly to the next section: [Installing CAPG](#installing-capg). If, on the other hand, you have an existing Kubernetes cluster that is not yet configured as a CAPI management cluster, you can follow the guide from the [CAPI book](https://cluster-api.sigs.k8s.io/user/quick-start#initialize-the-management-cluster). |
| 14 | + |
| 15 | +## Requirements |
| 16 | + |
| 17 | +- Linux or MacOS (Windows isn't supported at the moment). |
| 18 | +- A [Google Cloud](https://console.cloud.google.com) account. |
| 19 | +- [Packer](https://www.packer.io/intro/getting-started/install.html) and [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) to build images |
| 20 | +- `make` to use `Makefile` targets |
| 21 | +- Install `coreutils` (for timeout) on *OSX* |
| 22 | + |
| 23 | +### Create a Service Account |
| 24 | + |
| 25 | +To create and manage clusters, this infrastructure provider uses a service account to authenticate with GCP's APIs. |
| 26 | + |
| 27 | +From your cloud console, follow [these instructions](https://cloud.google.com/iam/docs/creating-managing-service-accounts#creating) to create a new service account with `Editor` permissions. |
| 28 | + |
| 29 | +If you plan to use GKE the service account will also need the `iam.serviceAccountTokenCreator` role. |
| 30 | + |
| 31 | +Afterwards, generate a JSON Key and store it somewhere safe. |
| 32 | + |
| 33 | + |
| 34 | +### Installing CAPG |
| 35 | + |
| 36 | +There are two major provider installation paths: using `clusterctl` or the `Cluster API Operator`. |
| 37 | + |
| 38 | +`clusterctl` is a command line tool that provides a simple way of interacting with CAPI and is usually the preferred alternative for those who are getting started. It automates fetching the YAML files defining provider components and installing them. |
| 39 | + |
| 40 | +The `Cluster API Operator` is a Kubernetes Operator built on top of `clusterctl` and designed to empower cluster administrators to handle the lifecycle of Cluster API providers within a management cluster using a declarative approach. It aims to improve user experience in deploying and managing Cluster API, making it easier to handle day-to-day tasks and automate workflows with GitOps. Visit the CAPI Operator quickstart if you want to experiment with this tool. |
| 41 | + |
| 42 | +You can opt for the tool that works best for you or explore both and decide which is best suited for your use case. |
| 43 | + |
| 44 | +#### clusterctl |
| 45 | + |
| 46 | +The Service Account you created will be used to interact with GCP and it must be base64 encoded and stored in a environment variable before installing the provider via `clusterctl`. |
| 47 | + |
| 48 | +``` |
| 49 | +export GCP_B64ENCODED_CREDENTIALS=$( cat /path/to/gcp-credentials.json | base64 | tr -d '\n' ) |
| 50 | +``` |
| 51 | +Finally, let's initialize the provider. |
| 52 | +``` |
| 53 | +clusterctl init --infrastructure gcp |
| 54 | +``` |
| 55 | +This process may take some time and, once the provider is running, you'll be able to see the `capg-controller-manager` pod in your CAPI management cluster. |
| 56 | + |
| 57 | +#### Cluster API Operator |
| 58 | + |
| 59 | +You can refer to the Cluster API Operator book [here](https://cluster-api-operator.sigs.k8s.io/01_user/02_quick-start) to learn about the basics of the project and how to install the operator. |
| 60 | + |
| 61 | +When using Cluster API Operator, secrets are used to store credentials for cloud providers and not environment variables, which means you'll have to create a new secret containing the base64 encoded version of your GCP credentials and it will be referenced in the yaml file used to initialize the provider. As you can see, by using Cluster API Operator, we're able to manage provider installation declaratively. |
| 62 | + |
| 63 | +Create GCP credentials secret. |
| 64 | +``` |
| 65 | +export CREDENTIALS_SECRET_NAME="gcp-credentials" |
| 66 | +export CREDENTIALS_SECRET_NAMESPACE="default" |
| 67 | +export GCP_B64ENCODED_CREDENTIALS=$( cat /path/to/gcp-credentials.json | base64 | tr -d '\n' ) |
| 68 | +
|
| 69 | +kubectl create secret generic "${CREDENTIALS_SECRET_NAME}" --from-literal=GCP_B64ENCODED_CREDENTIALS="${GCP_B64ENCODED_CREDENTIALS}" --namespace "${CREDENTIALS_SECRET_NAMESPACE}" |
| 70 | +``` |
| 71 | +Define CAPG provider declaratively in a file `capg.yaml`. |
| 72 | +``` |
| 73 | +apiVersion: v1 |
| 74 | +kind: Namespace |
| 75 | +metadata: |
| 76 | + name: capg-system |
| 77 | +--- |
| 78 | +apiVersion: operator.cluster.x-k8s.io/v1alpha2 |
| 79 | +kind: InfrastructureProvider |
| 80 | +metadata: |
| 81 | + name: gcp |
| 82 | + namespace: capg-system |
| 83 | +spec: |
| 84 | + version: v1.8.0 |
| 85 | + configSecret: |
| 86 | + name: gcp-credentials |
| 87 | +``` |
| 88 | +After applying this file, Cluster API Operator will take care of installing CAPG using the set of credentials stored in the specified secret. |
| 89 | +``` |
| 90 | +kubectl apply -f capg.yaml |
| 91 | +``` |
0 commit comments