Merge pull request #12 from Danil-Grigorev/quickstart-operator

Helm quick-start guide for operator, turtles and rancher
rancher · Sep 18, 2023 · 222a1bd · 222a1bd
2 parents c94e672 + 04615c7
commit 222a1bd
Show file tree

Hide file tree

Showing 8 changed files with 306 additions and 8 deletions.
diff --git a/docs/getting-started/install_capi_operator.md b/docs/getting-started/install_capi_operator.md
@@ -2,6 +2,73 @@
 sidebar_position: 3
 ---
 
-# Install CAPI Operator
+# Install Cluster API Operator
 
-This section needs to be filled out.
+This section describes how to install `Cluster API Operator` in the Kubernetes cluster.
+
+## Installing CAPI and providers
+
+`CAPI` and desired `CAPI` providers could be installed using the helm-based installation for [`Cluster API Operator`](https://github.com/kubernetes-sigs/cluster-api-operator) or as a helm dependency for the `Rancher Turtles`.
+
+### Install as a `Rancher Turtles` dependency (recommended)
+
+See the `Rancher Turtles` section for installing the operator as a Helm [dependency](./install_turtles_operator.md#install-rancher-turtles-operator-with-cluster-api-operator-as-a-helm-dependency)
+
+### Install manually with Helm (alternative)
+To install `Cluster API Operator` with version `1.4.6` of the `CAPI` + `Docker` provider using helm, follow these steps:
+
+1. Add the Helm repository for the `Cluster API Operator` by running the following command:
+```bash
+helm repo add capi-operator https://kubernetes-sigs.github.io/cluster-api-operator
+```
+2. Update the Helm repository by running the following command:
+```bash
+helm repo update
+```
+3. Install the `Cluster API Operator` using the following command, which will also install `cert-manager`:
+```bash
+helm install capi-operator capi-operator/cluster-api-operator
+	--create-namespace -n capi-operator-system
+	--set infrastructure=docker:v1.4.6
+	--set core=cluster-api:v1.4.6
+	--set cert-manager.enabled=true
+	--timeout 90s --wait # Core Cluster API with kubeadm bootstrap and control plane providers will also be installed
+```
+*Note: `cert-manager` is a hard requirement for CAPI and `Cluster API Operator`*
+
+To provide additional environment variables, choose some feature gates, or provide cloud credentials, similar to `clusterctl` [common provider](https://cluster-api.sigs.k8s.io/user/quick-start#initialization-for-common-providers), in `Cluster API Operator`, a variables secret could be used. A `name` and a `namespace` of the secret could be specified for the `Cluster API Operator`.
+
+```bash
+helm install capi-operator capi-operator/cluster-api-operator
+	--create-namespace -n capi-operator-system
+	--set infrastructure=docker:v1.4.6
+	--set core=cluster-api:v1.4.6
+	--set cert-manager.enabled=true
+	--timeout 90s
+	--secret-name <secret_name>
+	--secret-namespace <secret_namespace>
+	--wait
+```
+
+Example secret data:
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: variables
+  namespace: default
+type: Opaque
+stringData:
+  CLUSTER_TOPOLOGY: "true"
+  EXP_CLUSTER_RESOURCE_SET: "true"
+```
+
+To select more than one desired provider to be installed together with the `Cluster API Operator`, the `--infrastructure` flag can be specified with multiple provider names separated by a comma. For example:
+
+```bash
+helm install ... --set infrastructure="docker:v1.4.6;azure:v1.4.6"
+```
+
+The `infrastructure` flag is set to `docker:v1.4.6;azure:v1.4.6`, representing the desired provider names. This means that the `Cluster API Operator` will install and manage multiple provider systems, `Docker` and `Azure` respectively, with versions `1.4.6` specified.
+
+For more fine-grained control of the providers and other components installed with CAPI, see the [Add the infrastructure provider](../tasks/capi-operator/add_infrastructure_provider.md) section.
diff --git a/docs/getting-started/install_turtles_operator.md b/docs/getting-started/install_turtles_operator.md
@@ -2,6 +2,105 @@
 sidebar_position: 4
 ---
 
-# Install Rancher Turtles Operator
+# Install Rancher Turtles Operator without `Cluster API Operator` as a Helm dependency
 
-This section needs to be filled out.
+A `Rancher Turtles` requires a connection to the `Rancher Manager` cluster. This can be achieved by:
+
+1. Installing it in the same cluster as the `Rancher Manager`.
+
+*Note: In the future, we will support different deployment topologies*
+
+The recommended path of installation for the operator is by using `Helm`. To install it in the cluster, a repository should be added first:
+
+```bash
+helm repo add turtles https://rancher-sandbox.github.io/rancher-turtles/
+helm repo update
+```
+and then it can be installed into the `rancher-turtles-system` namespace with:
+
+```bash
+helm install rancher-turtles turtles/rancher-turtles
+    -n rancher-turtles-system
+    --set cluster-api-operator.enabled=false
+    --set cluster-api-operator.cluster-api.enabled=false
+    --create-namespace --wait
+    --dependency-update
+```
+
+### Install Rancher Turtles Operator with `Cluster API Operator` as a Helm dependency
+
+*Note: this section will be extended with additional details later*
+
+A `rancher-turtles` repository should be added first:
+
+```bash
+helm repo add turtles https://rancher-sandbox.github.io/rancher-turtles/
+helm repo update
+```
+
+To install `Cluster API Operator` as a dependency to the `Rancher Turtles`, a set of additional helm flags should be specified:
+
+```bash
+helm install rancher-turtles turtles/rancher-turtles
+    -n rancher-turtles-system
+    --dependency-update
+    # Passing secret name and namespace for additional environment variables to be used when deploying CAPI provider
+	--set cluster-api-operator.cluster-api.configSecret.name=<secret_name>
+	--set cluster-api-operator.cluster-api.configSecret.namespace=<secret_namespace>
+    --create-namespace --wait
+    --timeout 180s
+```
+
+Any values passed to `helm` with the `cluster-api-operator` key will be passed along to the `Cluster API Operator` project. A full set of available values for the `Cluster API Operator` can be found in the operator [values.yaml](https://github.com/kubernetes-sigs/cluster-api-operator/blob/main/hack/charts/cluster-api-operator/values.yaml).
+
+Currently the available set of values for the `cluster-api-operator` setup in the `rancher-turtles`:
+
+```yaml
+cluster-api-operator:
+  enabled: true # indicates if CAPI operator should be installed (default: true)
+  cert-manager:
+    enabled: true # indicates if cert-manager should be installed (default: true)
+  cluster-api:
+    enabled: true # indicates if core CAPI controllers should be installed (default: true)
+    version: v1.4.6 # version of CAPI to install (default: v1.4.6)
+    configSecret:
+      name: "" # name of the config secret to use for core CAPI controllers, used by the CAPI operator. See [CAPI operator](https://github.com/kubernetes-sigs/cluster-api-operator/tree/main/docs#installing-azure-infrastructure-provider) docs for more details.
+      namespace: "" # namespace of the config secret to use for core CAPI controllers, used by the CAPI operator.
+    core:
+      namespace: capi-system
+      fetchConfig: # (only required for airgapped environments)
+        url: ""  # url to fetch config from, used by the CAPI operator. See [CAPI operator](https://github.com/kubernetes-sigs/cluster-api-operator/tree/main/docs#provider-spec) docs for more details.
+        selector: ""  # selector to use for fetching config, used by the CAPI operator.
+    kubeadmBootstrap:
+      namespace: capi-kubeadm-bootstrap-system
+      fetchConfig:
+        url: ""
+        selector: ""
+    kubeadmControlPlane:
+      namespace: capi-kubeadm-control-plane-system
+      fetchConfig:
+        url: ""
+        selector: ""
+```
+
+A `secret` with a set of environment variables should be passed to the `Cluster API Operator` installation.
+
+Example `variables/default` `secret` configuration with `CLUSTER_TOPOLOGY` and `EXP_CLUSTER_RESOURCE_SET` feature flags set:
+
+```sh title="helm install flags"
+helm install ...
+--set cluster-api-operator.cluster-api.configSecret.name=variables
+--set cluster-api-operator.cluster-api.configSecret.namespace=default
+```
+
+```yaml title="secret.yaml"
+apiVersion: v1
+kind: Secret
+metadata:
+  name: variables
+  namespace: default
+type: Opaque
+stringData:
+  CLUSTER_TOPOLOGY: "true"
+  EXP_CLUSTER_RESOURCE_SET: "true"
+```
diff --git a/docs/getting-started/intro.md b/docs/getting-started/intro.md
@@ -8,4 +8,13 @@ Everything you need to know about getting started with Rancher Turtles.
 
 # Prerequisites
 
-Add the pre-reqs here
+
+| Name                     | Version                                  | Details                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ------------------------ | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Kubernetes cluster       | `>=1.26.0`                               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Helm                     | `>=3.12.0`                               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Rancher                  | Reach out to the early adopters contacts | Using [helm based](https://ranchermanager.docs.rancher.com/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster#install-the-rancher-helm-chart) installation on any kuberenetes cluster directly or on a newly created [Amazon](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks), [Azure](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks) or [Google](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke) service based options. Additional feature gate [modifications](./rancher.md#installing-rancher) are reqired. |
+| Cert-manager             | `>=v1.12.0`                              | Using [helm](https://cert-manager.io/docs/installation/helm/#installing-with-helm) based installation or via [kubectl apply](https://cert-manager.io/docs/installation/#default-static-install) command or as a helm [dependency](./install_capi_operator.md#install-with-helm)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Cluster API Operator     | `>=v0.5.1`                               | Using [helm chart](https://github.com/kubernetes-sigs/cluster-api-operator/blob/main/docs/README.md#method-2-use-helm-charts) install or as a [dependency](./install_turtles_operator.md#install-cluster-api-operator-as-a-helm-dependency) to the `Rancher Turtles`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Cluster API              | `v1.4.6`                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Rancher-turtles operator | `>=0.0.1`                                | Using helm based [installation](./install_turtles_operator.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
diff --git a/docs/getting-started/rancher.md b/docs/getting-started/rancher.md
@@ -4,4 +4,34 @@ sidebar_position: 2
 
 # Rancher Setup
 
-This section needs to be filled out.
+## Installing Rancher
+
+To install `Rancher` in an existing or new Kubernetes cluster, you can use the following steps:
+
+1. First, make sure to follow one of the official [installation guides](https://ranchermanager.docs.rancher.com/pages-for-subheaders/installation-and-upgrade) for `Rancher`.
+2. When installing `Rancher` using the `helm` command, use the `--set` option to specify the `features` parameter. For the `embedded-cluster-api` feature, set the value to `false` to disable it.
+3. Use the `--version` option to specify the version of `Rancher` you want to install. In this case, use the [recommended](../getting-started/intro.md#prerequisites) `Rancher` version for `Rancher Turtles`.
+
+Here's the complete command to install `Rancher` with the `embedded-cluster-api` feature disabled. Replace `<rancher-hostname>` with the actual hostname of your `Rancher` server:
+
+```bash
+helm install rancher rancher-stable/rancher --set features=embedded-cluster-api=false --set hostname=<rancher-hostname> --set version=<rancher-version> --set namespace=cattle-system --create-namespace --wait
+```
+
+## Existing Rancher installation
+
+To install `Rancher Turtles` in an existing `Rancher` cluster, follow these steps:
+
+1. Create a `feature.yaml` file, with `embedded-cluster-api` feature disabled:
+```yaml title="feature.yaml"
+apiVersion: management.cattle.io/v3
+kind: Feature
+metadata:
+  name: embedded-cluster-api
+spec:
+  value: false
+```
+2. Use `kubectl` to apply the `feature.yaml` file to the cluster:
+```bash
+kubectl apply -f feature.yaml
+```
diff --git a/docs/tasks/capi-operator/add_infrastructure_provider.md b/docs/tasks/capi-operator/add_infrastructure_provider.md
@@ -1,7 +1,48 @@
 ---
-sidebar_position: 1
+sidebar_position: 2
 ---
 
 # Add Infrastructure Provider
 
-In this section we will cover how to add an infrastructure proviedr such as AWS.
+This section describes how an infrastructure provider such as `Azure` could be added using `Cluster API Operator`.
+
+### Installing Azure Infrastructure Provider
+
+Next, install [Azure Infrastructure Provider](https://capz.sigs.k8s.io/). Before that ensure that `capz-system` namespace exists.
+
+Since the provider requires variables to be set, create a secret containing them in the same namespace as the provider. It is also recommended to include a `github-token` in the secret. This token is used to fetch the provider repository, and it is required for the provider to be installed. The operator may exceed the rate limit of the GitHub API without the token. Like [clusterctl](https://cluster-api.sigs.k8s.io/clusterctl/overview.html?highlight=github_token#avoiding-github-rate-limiting), the token needs only the `repo` scope.
+
+```yaml
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: azure-variables
+  namespace: capz-system
+type: Opaque
+stringData:
+  AZURE_CLIENT_ID_B64: Zm9vCg==
+  AZURE_CLIENT_SECRET_B64: Zm9vCg==
+  AZURE_SUBSCRIPTION_ID_B64: Zm9vCg==
+  AZURE_TENANT_ID_B64: Zm9vCg==
+  github-token: ghp_fff
+---
+apiVersion: operator.cluster.x-k8s.io/v1alpha1
+kind: InfrastructureProvider
+metadata:
+ name: azure
+ namespace: capz-system
+spec:
+ version: v1.9.3
+ configSecret:
+   name: azure-variables
+```
+
+### Deleting providers
+
+To remove the installed providers and all related kubernetes objects just delete the following CRs:
+
+```bash
+kubectl delete coreprovider cluster-api
+kubectl delete infrastructureprovider azure
+```
diff --git a/docs/tasks/capi-operator/basic_cluster_api_provider_installation.md b/docs/tasks/capi-operator/basic_cluster_api_provider_installation.md
@@ -0,0 +1,15 @@
+---
+sidebar_position: 1
+---
+
+# Basic Cluster API Provider Installation
+
+This section describes the basic process of installing `CAPI` providers using the operator. The `Cluster API Operator` manages five types of objects:
+
+- `CoreProvider`
+- `BootstrapProvider`
+- `ControlPlaneProvider`
+- `InfrastructureProvider`
+- `AddonProvider`
+
+Please note that this example provides a basic configuration of Azure Infrastructure provider for getting started. More detailed examples and CRD descriptions are provided in the `Cluster API Operator` [documentation](https://github.com/kubernetes-sigs/cluster-api-operator/tree/main/docs#readme)