Helm quick-start guide for operator, turtles and rancher

docs/getting-started/install_capi_operator.md

@@ -2,6 +2,71 @@
 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 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
+
+See the `Rancher Turtles` section for installing operator as a Helm [dependency](./install_turtles_operator.md#install-cluster-api-operator-as-a-helm-dependency)
+
+### Install with Helm
+To install `Cluster API Operator` with version `1.4.4` 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.4
+	--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.4
+	--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 ... infrastructure="docker:v1.4.4;azure:v1.4.4"
+```
+
+The `infrastructure` flag is set to `docker:v1.4.4;azure:v1.4.4`, 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.4` specified.
+
+For more fine-grained control on the providers and other components installed with CAPI, see the [Add infrastructure provider](../tasks/capi-operator/add_infrastructure_provider.md) section.

docs/getting-started/install_turtles_operator.md

@@ -4,4 +4,40 @@ sidebar_position: 4
 
 # Install Rancher Turtles Operator
 
-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 future we will support different deployment topologies*
+
+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
+    --create-namespace --wait
+```
+
+### Install `Cluster API Operator` as a Helm dependency
+
+*Note: this section will be extended with additional details later*
+
+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
+    --set cluster-api-operator.cert-manager.enabled=true # Allows to install cert manager dependency with Cluster API Operator
+	--set secret-name=<secret_name> # Passing secret name and namespace for additional environment variables to be used when deploying CAPI provider
+	--set secret-namespace=<secret_namespace>
+    --create-namespace --wait
+    --timeout 90s
+```
+
+Any values passed to `helm` with the `cluster-api-operator` label will be passed along to the `Cluster API Operator` project. Full set of avaliable values for the `Cluster API Operator` could be found in the operator [values.yaml](https://github.com/kubernetes-sigs/cluster-api-operator/blob/main/hack/charts/cluster-api-operator/values.yaml).

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.4`                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Rancher-turtles operator | `>=0.0.1`                                | Using helm based [installation](./install_turtles_operator.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

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 [recommentded](../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
+```

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
+```

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)

docs/tasks/capi-operator/installing_core_provider.md

@@ -0,0 +1,23 @@
+---
+sidebar_position: 3
+---
+
+# Installing the CoreProvider
+
+This section describes how to install the CoreProvider, which is responsible for managing the Cluster API CRDs and the Cluster API controller.
+
+Any existing namespace could be utilized for providers in the Kubernetes cluster. However, before creating a provider object, make sure the specified namespace has been created. In the example below, we use the `capi-system` namespace. To create this namespace through either the Command Line Interface (CLI) by running `kubectl create namespace capi-system`, or the declarative approach described in the [official Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/namespaces-walkthrough/#create-new-namespaces) could be used.
+
+*Example:*
+
+```yaml
+apiVersion: operator.cluster.x-k8s.io/v1alpha2
+kind: CoreProvider
+metadata:
+  name: cluster-api
+  namespace: capi-system
+spec:
+  version: v1.4.4
+```
+
+**Note:** Only one CoreProvider can be installed at the same time on a single cluster.

sidebars.js

@@ -51,6 +51,20 @@ const sidebars = {
       collapsed: true,
       items: [
         'tasks/intro',
+        {
+          type: 'category',
+          label: 'Cluster API Operator',
+          collapsed: true,
+          link: {
+            type: 'generated-index'
+          },
+          items: [
+            {
+              type: 'autogenerated',
+              dirName: 'tasks/capi-operator',
+            },
+          ]
+        },
       ]
     }
   ]