Skip to content

Commit

Permalink
Merge pull request #75 from salasberryfin/add-rancher-ui-installation…
Browse files Browse the repository at this point in the history 
…-instructions

docs: add rancher ui installation instructions
  • Loading branch information
@richardcase
richardcase authored Apr 2, 2024
2 parents f951b7c + 6c79423 commit 21ac4d3
Show file tree
Hide file tree
Showing 11 changed files with 94 additions and 29 deletions.
Binary file added docs/getting-started/install-rancher-turtles/deployments-turtles.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/getting-started/install-rancher-turtles/install-turtles-from-ui.gif
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
28 changes: 15 additions & 13 deletions ...tting-started/install_turtles_operator.md → ...ted/install-rancher-turtles/using_helm.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,31 +2,33 @@
sidebar_position: 4
---

# Install Rancher Turtles Operator
# Via Helm install

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).
If you want to manually apply the Helm chart and be in full control of the installation.

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.
This section walks through different installation options for the Rancher Turtles.
- [Install Rancher Turtles with Cluster API Operator as a dependency](#install-rancher-turtles-with-cluster-api-operator-as-a-helm-dependency).
- [Install Rancher Turtles without Cluster API Operator](#install-rancher-turtles-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-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.
Before [installing Rancher Turtles](#install-rancher-turtles-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.

To simplify setting up Rancher for installing Rancher Turtles, the official Rancher Turtles Helm chart includes a `pre-install` hook that applies these changes, making it transparent to the end user:
- Disable the `embedded-cluster-api` feature in Rancher.
- 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.
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)
If uninstalling, you can refer to [Uninstalling Rancher Turtles](../uninstall_turtles.md)
:::

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

The `rancher-turtles` chart is available in https://rancher.github.io/turtles and this Helm repository must be added before proceeding with the installation:

Expand Down Expand Up @@ -82,13 +84,13 @@ stringData:
```
:::info
For detailed information on the values supported by the chart and their usage, refer to [Helm chart options](../reference-guides/rancher-turtles-chart/values)
For detailed information on the values supported by the chart and their usage, refer to [Helm chart options](../../reference-guides/rancher-turtles-chart/values)
:::
### Install Rancher Turtles Operator without `Cluster API Operator` as a Helm dependency
### Install Rancher Turtles without `Cluster API Operator` as a Helm dependency

:::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)
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 `rancher-turtles` chart is available in https://rancher.github.io/turtles and this Helm repository must be added before proceeding with the installation:
Expand All @@ -111,5 +113,5 @@ helm install rancher-turtles turtles/rancher-turtles --version v0.5.0

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:
This operation could take a few minutes and, after installing, you can take some time to study the installed controller:
- `rancher-turtles-controller`.
52 changes: 52 additions & 0 deletions docs/getting-started/install-rancher-turtles/using_rancher_dashboard.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
---
sidebar_position: 4
---

# Via Rancher Dashboard

This is the recommended option for installing Rancher Turtles.

Via Rancher UI, and just by adding the Turtles repository, we can easily let Rancher take care of the installation and configuration of the Cluster API Extension.

:::caution
If you already have Cluster API Operator installed in your cluster, you should use the [manual helm install method](./using_helm.md) instead.
:::

:::info
Before [installing Rancher Turtles](./using_helm.md#install-rancher-turtles-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.

To simplify setting up Rancher for installing Rancher Turtles, the official Rancher Turtles Helm chart includes a `pre-install` hook that applies these changes, making it transparent to the end user:
- Disable the `embedded-cluster-api` feature in Rancher.
- 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.md)
:::

### Installation

- From your browser, access Rancher Manager and explore the **local** cluster.
- Using the left navigation pane, go to `Apps` -> `Repositories`.
- Click `Create` to add a new repository.
- Enter the following:
- **Name**: `turtles`.
- **Index URL**: https://rancher.github.io/turtles.
- Wait for the `turtles` repository to have a status of `Active`.
- Go to `Apps` -> `Charts`.
- Filter for `turtles`.
- Click `Rancher Turtles - the Cluster API Extension`
- Click `Install` -> `Next` -> `Install`.

![install-turtles-from-ui](./install-turtles-from-ui.gif)

This will use the default values for the Helm chart, which are good for most installations. If your configuration requires overriding some of these defaults, you can either specify the values during installation from Rancher UI or, alternatively, you can opt for the [manual installation via Helm](./using_helm.md). And, if you are interested on learning more about the available values, you can check the [reference guide](../../reference-guides/rancher-turtles-chart/values.md).

The installation may take a few minutes and, when it finishes, you will be able to see the following new deployments in the cluster:
- `rancher-turtles-system/rancher-turtles-controller-manager`
- `rancher-turtles-system/rancher-turtles-cluster-api-operator`
- `capi-system/capi-controller-manager`

![deployments-turtles](./deployments-turtles.png)
6 changes: 3 additions & 3 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_turtles_operator.md) (recommended) |
| Cluster API Operator | `>=v0.9.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` |
| 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-rancher-turtles/using_rancher_dashboard.md) (recommended) |
| Cluster API Operator | `>=v0.9.1` | Using [Rancher UI](./install-rancher-turtles/using_rancher_dashboard.md) (recommended) or [Helm install](https://github.com/kubernetes-sigs/cluster-api-operator/blob/main/docs/README.md#method-2-use-helm-charts) (for advanced use cases) |
| Cluster API | `v1.4.6` | |
| Rancher-turtles operator | `v0.6.0` | Using helm based [installation](./install_turtles_operator.md) |
| Rancher Turtles | `v0.6.0` | Using [Rancher UI](./install-rancher-turtles/using_rancher_dashboard.md) (recommended) or [Helm install](./install-rancher-turtles/using_helm.md) (for advanced use cases) |
2 changes: 1 addition & 1 deletion docs/getting-started/rancher.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ sidebar_position: 2

## Installing Rancher

*If you're already running Rancher, you can skip this section and jump to [Install Rancher Turtles Operator](./install_turtles_operator.md).*
*If you're already running Rancher, you can skip this section and jump to [Install Rancher Turtles](./install-rancher-turtles/using_rancher_dashboard.md).*

Helm is the recommended way to install `Rancher` in an existing or new Kubernetes cluster.

Expand Down
12 changes: 6 additions & 6 deletions ...ing-started/uninstall_turtles_operator.md → docs/getting-started/uninstall_turtles.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
sidebar_position: 5
---

# Uninstall Rancher Turtles Operator
# Uninstall Rancher Turtles

This gives an overview of Rancher Turtles Operator uninstallation process.
This gives an overview of Rancher Turtles uninstallation process.

:::caution
When installing Rancher Turtles in your Rancher environment, by default, Rancher Turtles enables the Cluster API Operator cleanup. This includes cleaning up Cluster API Operator specific webhooks and deployments that otherwise cause issues with Rancher provisioning.
Expand All @@ -14,11 +14,11 @@ To simplify uninstalling Rancher Turtles (via Rancher Manager or helm command),
- Delete the CAPI `deployments` that are no longer needed.
:::

There are two options to uninstall the Rancher Turtles Operator depending on the installation method.
There are two options to uninstall the Rancher Turtles depending on the installation method.

1. Rancher Turtles Operator installed via Rancher Manager (i.e in local cluster, `Apps->Repositories` to add a turtles repository then `Apps->Charts` to install rancher-turtles extension). To uninstall, simply navigate to local cluster, `Apps->Installed Apps`, find `rancher-turtles` extension and click `Delete`.
1. Rancher Turtles installed via Rancher Manager (i.e in local cluster, `Apps->Repositories` to add a turtles repository then `Apps->Charts` to install rancher-turtles extension). To uninstall, simply navigate to local cluster, `Apps->Installed Apps`, find `rancher-turtles` extension and click `Delete`.

2. Rancher Turtles Operator installed via [helm command](install_turtles_operator.md). If you would like to uninstall it manually,
2. Rancher Turtles installed via [helm command](./install-rancher-turtles/using_helm.md). If you would like to uninstall it manually,
it can be simply achieived via `helm`:

```bash
Expand All @@ -45,4 +45,4 @@ spec:
2. Use `kubectl` to apply the `feature.yaml` file to the cluster:
```bash
kubectl apply -f feature.yaml
```
```
4 changes: 2 additions & 2 deletions docs/reference-guides/architecture/intro.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ For guidance about setting up Rancher, refer to
[Rancher Setup](../../getting-started/rancher.md)

For information on how to install Rancher Turtles, refer to
[Install Rancher Turtles Operator with Cluster API Operator as a Helm
dependency](../../getting-started/install_turtles_operator.md)
[Install Rancher Turtles with Cluster API Operator as a Helm
dependency](../../getting-started/install-rancher-turtles/using_rancher_dashboard.md)
:::

**A Rancher User will use Rancher to manage clusters. Rancher will be able to use
Expand Down
Loading

0 comments on commit 21ac4d3

Please sign in to comment.