diff --git a/docs/getting-started/install_turtles_operator.md b/docs/getting-started/install_turtles_operator.md index f882a2a1..6c0ff132 100644 --- a/docs/getting-started/install_turtles_operator.md +++ b/docs/getting-started/install_turtles_operator.md @@ -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. @@ -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 \ @@ -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. @@ -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 @@ -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`. diff --git a/docs/getting-started/intro.md b/docs/getting-started/intro.md index 86e39d39..c6f4d0b3 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_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) | diff --git a/docs/intro.md b/docs/intro.md index 30d651f4..a94ef4db 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -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: diff --git a/docs/reference-guides/architecture/deployment.md b/docs/reference-guides/architecture/deployment.md index bd0a26bc..94aac7df 100644 --- a/docs/reference-guides/architecture/deployment.md +++ b/docs/reference-guides/architecture/deployment.md @@ -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. diff --git a/docs/getting-started/install_capi_operator.md b/docs/tasks/capi-operator/intro.md similarity index 86% rename from docs/getting-started/install_capi_operator.md rename to docs/tasks/capi-operator/intro.md index 4bedaf7e..2a42e6ab 100644 --- a/docs/getting-started/install_capi_operator.md +++ b/docs/tasks/capi-operator/intro.md @@ -2,7 +2,7 @@ sidebar_position: 3 --- -# Install Cluster API Operator +# Installing Cluster API Operator This section describes how to install `Cluster API Operator` in the Kubernetes cluster. @@ -10,10 +10,6 @@ This section describes how to install `Cluster API Operator` in the Kubernetes c `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: @@ -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. ::: diff --git a/sidebars.js b/sidebars.js index 10b14398..fd0de378 100644 --- a/sidebars.js +++ b/sidebars.js @@ -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', { @@ -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', ] }, ]