Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add rancher ui installation instructions #75

Merged
merged 3 commits into from
Apr 2, 2024
Merged

docs: add rancher ui installation instructions #75

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4241823
docs: add rancher ui installation instructions
salasberryfin Mar 27, 2024
b0c4fa5
Address review comments
furkatgofurov7 Mar 28, 2024
6c79423
Remove 'Operator' word mentions from Rancher Turtles only in the late…
furkatgofurov7 Mar 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added docs/getting-started/install-rancher-turtles/deployments-turtles.png
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As discussed we will only mention uninstalling via helm on the cli initially. But this can be changed in #77. wdyt @furkatgofurov7 @Danil-Grigorev?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's change it in #77 👍🏼


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
Open in desktop
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
Loading