diff --git a/docs/getting-started/install-rancher-turtles/deployments-turtles.png b/docs/getting-started/install-rancher-turtles/deployments-turtles.png new file mode 100644 index 00000000..c165360a Binary files /dev/null and b/docs/getting-started/install-rancher-turtles/deployments-turtles.png differ diff --git a/docs/getting-started/install-rancher-turtles/install-turtles-from-ui.gif b/docs/getting-started/install-rancher-turtles/install-turtles-from-ui.gif new file mode 100644 index 00000000..80f6880e Binary files /dev/null and b/docs/getting-started/install-rancher-turtles/install-turtles-from-ui.gif differ diff --git a/docs/getting-started/install_turtles_operator.md b/docs/getting-started/install-rancher-turtles/using_helm.md similarity index 80% rename from docs/getting-started/install_turtles_operator.md rename to docs/getting-started/install-rancher-turtles/using_helm.md index 7778a335..bb2a4c48 100644 --- a/docs/getting-started/install_turtles_operator.md +++ b/docs/getting-started/install-rancher-turtles/using_helm.md @@ -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: @@ -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: @@ -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`. diff --git a/docs/getting-started/install-rancher-turtles/using_rancher_dashboard.md b/docs/getting-started/install-rancher-turtles/using_rancher_dashboard.md new file mode 100644 index 00000000..0f155c11 --- /dev/null +++ b/docs/getting-started/install-rancher-turtles/using_rancher_dashboard.md @@ -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) diff --git a/docs/getting-started/intro.md b/docs/getting-started/intro.md index d97d7a48..2a73ed7b 100644 --- a/docs/getting-started/intro.md +++ b/docs/getting-started/intro.md @@ -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) | diff --git a/docs/getting-started/rancher.md b/docs/getting-started/rancher.md index 201a128f..ae26b07b 100644 --- a/docs/getting-started/rancher.md +++ b/docs/getting-started/rancher.md @@ -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. diff --git a/docs/getting-started/uninstall_turtles_operator.md b/docs/getting-started/uninstall_turtles.md similarity index 68% rename from docs/getting-started/uninstall_turtles_operator.md rename to docs/getting-started/uninstall_turtles.md index ec332f7c..50d1aef0 100644 --- a/docs/getting-started/uninstall_turtles_operator.md +++ b/docs/getting-started/uninstall_turtles.md @@ -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. @@ -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 @@ -45,4 +45,4 @@ spec: 2. Use `kubectl` to apply the `feature.yaml` file to the cluster: ```bash kubectl apply -f feature.yaml -``` \ No newline at end of file +``` diff --git a/docs/reference-guides/architecture/intro.md b/docs/reference-guides/architecture/intro.md index e2345a62..2e1ddccd 100644 --- a/docs/reference-guides/architecture/intro.md +++ b/docs/reference-guides/architecture/intro.md @@ -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 diff --git a/docs/reference-guides/rancher-turtles-chart/values.md b/docs/reference-guides/rancher-turtles-chart/values.md index f88ff3e9..ec5e2d81 100644 --- a/docs/reference-guides/rancher-turtles-chart/values.md +++ b/docs/reference-guides/rancher-turtles-chart/values.md @@ -10,7 +10,7 @@ For the up-to-date content of `values.yaml` source file, refer to the [Rancher T ## Rancher Turtles values -When installing Rancher Turtles Operator using the official Helm chart, it is possible to configure a number of feature flags. This is a comprehensive list of the available values and their usage: +When installing Rancher Turtles using the official Helm chart, it is possible to configure a number of feature flags. This is a comprehensive list of the available values and their usage: ```yaml rancherTurtles: diff --git a/docs/tasks/capi-operator/intro.md b/docs/tasks/capi-operator/intro.md index 2a42e6ab..04ee0bf4 100644 --- a/docs/tasks/capi-operator/intro.md +++ b/docs/tasks/capi-operator/intro.md @@ -69,7 +69,7 @@ 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](../../getting-started/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 without Cluster API Operator](../../getting-started/install-rancher-turtles/using_helm.md#install-rancher-turtles-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. diff --git a/sidebars.js b/sidebars.js index fd0de378..6a723500 100644 --- a/sidebars.js +++ b/sidebars.js @@ -25,8 +25,18 @@ const sidebars = { items: [ 'getting-started/intro', 'getting-started/rancher', - 'getting-started/install_turtles_operator', - 'getting-started/uninstall_turtles_operator', + { + type: 'category', + label: 'Install Rancher Turtles', + link: { + type: 'generated-index' + }, + collapsed: false, + items: [ + 'getting-started/install-rancher-turtles/using_rancher_dashboard', + 'getting-started/install-rancher-turtles/using_helm', + ] + }, { type: 'category', label: 'Your first cluster', @@ -54,6 +64,7 @@ const sidebars = { }, ] }, + 'getting-started/uninstall_turtles', ], }, {