Skip to content

Commit

Permalink
docs: update installation instructions
Browse files Browse the repository at this point in the history 
remove early adopter, update installation requirements

Signed-off-by: Carlos Salas <[email protected]>
  • Loading branch information
@salasberryfin
salasberryfin committed Mar 13, 2024
1 parent cea6d24 commit 3c6ce26
Show file tree
Hide file tree
Showing 6 changed files with 43 additions and 28 deletions.
38 changes: 28 additions & 10 deletions docs/getting-started/install_turtles_operator.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,12 @@ sidebar_position: 4
# Install Rancher Turtles Operator

This section walks through different installation options for the Rancher Turtles Operator.
- [Install Rancher Turtles with Cluster API Operator as a dependency](#install-rancher-turtles-operator-with-cluster-api-operator-as-a-helm-dependency).
- [Install Rancher Turtles without Cluster API Operator](#install-rancher-turtles-operator-without-cluster-api-operator-as-a-helm-dependency).

The Cluster API Operator is required for installing Rancher Turtles and you can choose whether you want to take care of this dependency yourself or let the Rancher Turtles Helm chart manage it for you. We recommend [installing as a dependency](#install-rancher-turtles-operator-with-cluster-api-operator-as-a-helm-dependency) for the sake of simplicity, but the best option may depend on your specific configuration.

CAPI Operator allows handling the lifecycle of Cluster API Providers using a declarative approach, extending the capabilities of `clusterctl`. If you want to learn more about it, you can refer to [Cluster API Operator book](https://cluster-api-operator.sigs.k8s.io/).

:::info
Before [installing Rancher Turtles](#install-rancher-turtles-operator-with-cluster-api-operator-as-a-helm-dependency) in your Rancher environment, Rancher's `embedded-cluster-api` functionality must be disabled. This includes also cleaning up Rancher-specific webhooks that otherwise would conflict with CAPI ones.
Expand All @@ -14,16 +20,22 @@ To simplify setting up Rancher for installing Rancher Turtles, the official Ranc
- Delete the `mutating-webhook-configuration` and `validating-webhook-configuration` webhooks that are no longer needed.
:::

If you would like to understand how Rancher Turtles works and what the architecture looks like, you can refer to the [Architecture](../reference-guides/architecture/intro.md) section.

:::note
If uninstalling, you can refer to [Uninstalling Rancher Turtles](./uninstall_turtles_operator.md)
:::

### Install Rancher Turtles Operator with `Cluster API Operator` as a Helm dependency

A `rancher-turtles` chart repository should be added first:
The `rancher-turtles` chart is available in https://charts.rancher-turtles.com and this Helm repository must be added before proceeding with the installation:

```bash
helm repo add turtles https://charts.rancher-turtles.com
helm repo update
```

To install `Cluster API Operator` as a dependency to the `Rancher Turtles`, a minimum set of additional helm flags should be specified:
As mentioned before, installing Rancher Turtles requires the [Cluster API Operator](https://github.com/kubernetes-sigs/cluster-api-operator) and the Helm chart can handle its installation automatically with a minimum set of flags:

```bash
helm install rancher-turtles turtles/rancher-turtles --version v0.5.0 \
Expand All @@ -33,13 +45,17 @@ helm install rancher-turtles turtles/rancher-turtles --version v0.5.0 \
--timeout 180s
```

This operation could take a few minutes and, after installing, you can take some time to study the installed controllers, including:
- `rancher-turtles-controller`.
- `capi-operator`.

:::note
- If `cert-manager` is already available in the cluster, you can disable its installation as a Rancher Turtles dependency to avoid conflicts:
`--set cluster-api-operator.cert-manager.enabled=false`
- For a list of Rancher Turtles versions, refer to [Releases page](https://github.com/rancher-sandbox/rancher-turtles/releases).
:::

This is the basic, recommended configuration, which manages the creation of a secret containing the required feature flags (`CLUSTER_TOPOLOGY`, `EXP_CLUSTER_RESOURCE_SET` and `EXP_MACHINE_POOL` enabled) in the core provider namespace.
This is the basic, recommended configuration, which manages the creation of a secret containing the required CAPI feature flags (`CLUSTER_TOPOLOGY`, `EXP_CLUSTER_RESOURCE_SET` and `EXP_MACHINE_POOL` enabled) in the core provider namespace. These feature flags are required to enable additional Cluster API functionality.

If you need to override the default behavior and use an existing secret (or add custom environment variables), you can pass the secret name helm flag. In this case, as a user, you are in charge of managing the secret creation and its content, including the minimum required features: `CLUSTER_TOPOLOGY`, `EXP_CLUSTER_RESOURCE_SET` and `EXP_MACHINE_POOL` enabled.

Expand Down Expand Up @@ -71,20 +87,17 @@ For detailed information on the values supported by the chart and their usage, r
### Install Rancher Turtles Operator without `Cluster API Operator` as a Helm dependency

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

:::tip
For information on deployment options, refer to [Deployment Scenarios](../reference-guides/architecture/deployment)
:::note
Remember that if you opt for this installation option, you will need to manage the Cluster API Operator installation yourself. You can follow the [CAPI Operator guide](../tasks/capi-operator/intro.md)
:::

The recommended path of installation for the operator is by using `Helm`. To install it in the cluster, a chart repository should be added first:
The `rancher-turtles` chart is available in https://charts.rancher-turtles.com and this Helm repository must be added before proceeding with the installation:

```bash
helm repo add turtles https://charts.rancher-turtles.com
helm repo update
```

and then it can be installed into the `rancher-turtles-system` namespace with:

```bash
Expand All @@ -95,3 +108,8 @@ helm install rancher-turtles turtles/rancher-turtles --version v0.5.0
--create-namespace --wait
--dependency-update
```

As you can see, we are telling Helm to ignore installing `cluster-api-operator` as a dependency.

This operation could take a few minutes and, after installing, you can take some time to study the installed operator:
- `rancher-turtles-controller`.
4 changes: 2 additions & 2 deletions docs/getting-started/intro.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Everything you need to know about getting started with Rancher Turtles.
| Kubernetes cluster | `>=1.26.0` | |
| Helm | `>=3.12.0` | |
| Rancher | `>=2.8.1 | 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 kubernetes 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 required. |
| 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` |
| 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_turtles_operator.md) (recommended) |
| 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) (recommended) to the `Rancher Turtles` |
| Cluster API | `v1.4.6` | |
| Rancher-turtles operator | `v0.5.0` | Using helm based [installation](./install_turtles_operator.md) |
4 changes: 4 additions & 0 deletions docs/intro.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,10 @@ Please checkout out [getting started guide](./getting-started/intro).
This section focuses on implementation details, including
[architecture](./reference-guides/architecture/intro) and how Rancher Turtles integrates with Rancher.

## Tasks

In this section we cover additional [operational tasks](./tasks/intro.md).

## Security

This section focuses on security-related topics:
Expand Down
2 changes: 1 addition & 1 deletion docs/reference-guides/architecture/deployment.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar_position: 0
# Deployment Scenarios

:::note
The early release of Rancher Turtles only supports having Rancher Manager and
Currently Rancher Turtles only supports having Rancher Manager and
Rancher Turtles running in the same cluster. A topology with a separate Rancher
Manager cluster and one/multiple CAPI management cluster/s will be supported in
future releases.
Expand Down
10 changes: 3 additions & 7 deletions .../getting-started/install_capi_operator.md → docs/tasks/capi-operator/intro.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,14 @@
sidebar_position: 3
---

# Install Cluster API Operator
# Installing Cluster API Operator

This section describes how to install `Cluster API Operator` in the Kubernetes cluster.

## Installing Cluster API (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:

Expand Down Expand Up @@ -73,8 +69,8 @@ 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 providers, `Docker` and `Azure` respectively, with versions `v1.4.6` specified in this example.

The cluster is now ready to install Rancher Turtles. The default behavior when installing the chart is to install Cluster API Operator as a Helm dependency. Since we decided to install it manually before installing Rancher Turtles, the feature `cluster-api-operator.enabled` must be explicitly disabled as otherwise it would conflict with the existing installation. You can refer to [Install Rancher Turtles Operator without Cluster API Operator](./install_turtles_operator.md#install-rancher-turtles-operator-without-cluster-api-operator-as-a-helm-dependency) to see next steps.
The cluster is now ready to install Rancher Turtles. The default behavior when installing the chart is to install Cluster API Operator as a Helm dependency. Since we decided to install it manually before installing Rancher Turtles, the feature `cluster-api-operator.enabled` must be explicitly disabled as otherwise it would conflict with the existing installation. You can refer to [Install Rancher Turtles Operator without Cluster API Operator](../../getting-started/install_turtles_operator.md#install-rancher-turtles-operator-without-cluster-api-operator-as-a-helm-dependency) to see next steps.

:::tip
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.
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.
:::
13 changes: 5 additions & 8 deletions sidebars.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,6 @@ const sidebars = {
items: [
'getting-started/intro',
'getting-started/rancher',
'getting-started/install_capi_operator',
'getting-started/install_turtles_operator',
'getting-started/uninstall_turtles_operator',
{
Expand Down Expand Up @@ -88,14 +87,12 @@ const sidebars = {
type: 'category',
label: 'Cluster API Operator',
collapsed: true,
link: {
type: 'generated-index'
},
items: [
{
type: 'autogenerated',
dirName: 'tasks/capi-operator',
},
'tasks/capi-operator/intro',
'tasks/capi-operator/basic_cluster_api_provider_installation',
'tasks/capi-operator/installing_core_provider',
'tasks/capi-operator/capiprovider_resource',
'tasks/capi-operator/add_infrastructure_provider',
]
},
]
Expand Down

0 comments on commit 3c6ce26

Please sign in to comment.