public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-09-25 04:28:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updating after review for syntax/wording and moving pre-reqs into top intro section.

Browse Source 
Signed-off-by: Sunil Singh <sunil.singh@suse.com>
This commit is contained in:
Sunil Singh
2024-04-05 10:54:08 -07:00
parent bbe73308a7
commit 297b515f4d
6 changed files with 126 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/integrations-in-rancher/cluster-api/capi.md
+4 -4
View File
@@ -6,9 +6,9 @@ title: Cluster API with Rancher Turtles
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/integrations-in-rancher/cluster-api"/>
</head>
Rancher Turtles is a [Rancher extension](../rancher-extensions.md) that provides integration between your Cluster API (CAPI) and Rancher to manage the lifecycle of provisioned Kubernetes clusters. The main functionality is outlined below:
Rancher Turtles is a [Rancher extension](../rancher-extensions.md) that manages the lifecycle of provisioned Kubernetes clusters, by providing integration between your Cluster API (CAPI) and Rancher. With Rancher Turtles, you can:
- Importing CAPI clusters into Rancher: Installing the Rancher Cluster Agent in CAPI provisioned clusters.
- Configuration support for the CAPI Operator.
- Import CAPI clusters into Rancher, by installing the Rancher Cluster Agent in CAPI provisioned clusters.
- Configure the CAPI Operator.
The [Overview](./overview.md) section outlines installation options, the main architecture, and a brief demo. For more detailed information, please view the [Rancher Turtles documentation](https://docs.rancher-turtles.com/docs/intro).
The [Overview](./overview.md) section outlines installation options, Rancher Turtles architecture, and a brief demo. For more details, see the [Rancher Turtles documentation](https://turtles.docs.rancher.com/).
docs/integrations-in-rancher/cluster-api/overview.md
+38 -48
View File
@@ -12,39 +12,39 @@ title: Overview
## Installing the Rancher Turtles Operator
### Via Rancher Dashboard
This is the recommended option for installing Rancher Turtles.
Using the Rancher UI, and by adding the Turtles repository, we can let Rancher process the installation and configuration of the Cluster API Extension.
You can install the Rancher Turtles operator via the Rancher UI, or with Helm. The first method is recommended for most environments.
:::caution
If you already have the Cluster API Operator installed in your cluster, you need to use the [manual helm installation method](./overview.md#via-helm-install) instead.
If you already have the Cluster API Operator installed in your cluster, you must use the [manual helm installation method](./overview.md#via-helm-install).
:::
:::info prerequisite
Before installing Rancher Turtles 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 in your Rancher environment, you must disable Rancher's `embedded-cluster-api` functionality. This also includes 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 which are outlined below if manually removing:
- Disable the `embedded-cluster-api` feature in Rancher.
- Delete the `mutating-webhook-configuration` and `validating-webhook-configuration` webhooks that are no longer needed.
To simplify setting up Rancher for installing Rancher Turtles, the official Rancher Turtles Helm chart includes a `pre-install` hook that removes the following:
- Disables the `embedded-cluster-api` feature in Rancher.
- Deletes the `mutating-webhook-configuration` and `validating-webhook-configuration` webhooks, as they are no longer needed.
:::
### Via Rancher UI
By adding the Turtles repository via the Rancher UI, Rancher can process the installation and configuration of the Cluster API Extension.
#### Installation
- From your browser, access Rancher Manager and explore the **local** cluster.
- Using the left navigation panel, go to `Apps` -> `Repositories`.
- Click `Create` to add a new repository.
- Click **☰**. Under **Explore Cluster** in the left navigation menu, select **local**.
- In the left navigation menu of the **Cluster Dashboard**, select **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`.
- **Name**: turtles
- **Index URL**: https://rancher.github.io/turtles
- Wait until the new repository has a status of `Active`.
- In the left navigation menu, select **Apps > Charts**.
- Enter "turtles" into the search filter to find the Turtles chart.
- Click **Rancher Turtles - the Cluster API Extension**.
- Click **Install > Next > Install**.
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 the Rancher UI or, alternatively, you can opt for the [manual installation via Helm](./overview.md#via-helm-install). If you are interested in learning more about the available values, you can check the Rancher Turtles [Helm chart reference guide](https://docs.rancher-turtles.com/docs/reference-guides/rancher-turtles-chart/values).
This process uses 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 the Rancher UI or you can [manually install the chart via Helm](./overview.md#via-helm-install). For details about available values, see the Rancher Turtles [Helm chart reference guide](https://turtles.docs.rancher.com/docs/reference-guides/rancher-turtles-chart/values).
The installation may take a few minutes and once completed you will see the following new deployments in the cluster:
- `rancher-turtles-system/rancher-turtles-controller-manager`
@@ -53,32 +53,24 @@ The installation may take a few minutes and once completed you will see the foll
### Via Helm Install
This section walks through different Helm installation options for Rancher Turtles depending on CAPI operator use:
The Helm installation options for Rancher Turtles has two paths depending on CAPI operator use:
- [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.
The Cluster API Operator is required for installing Rancher Turtles. You can choose whether you want to take care of this dependency yourself or let the Rancher Turtles Helm chart manage it for you. [Installing Turtles as a dependency](#install-rancher-turtles-with-cluster-api-operator-as-a-helm-dependency) is simpler, but your best option depends on your specific configuration.
CAPI Operator allows for 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 prerequisite
Before installing Rancher Turtles 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 which are outlined below:
- Disable the `embedded-cluster-api` feature in Rancher.
- Delete the `mutating-webhook-configuration` and `validating-webhook-configuration` webhooks that are no longer needed.
:::
#### 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:
The `rancher-turtles` chart is available in https://rancher.github.io/turtles. This Helm repository must be added before installation:
```bash
helm repo add turtles https://rancher.github.io/turtles
helm repo update
```
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:
As mentioned before, installing Rancher Turtles requires the [Cluster API Operator](https://github.com/kubernetes-sigs/cluster-api-operator). The Helm chart can automatically install it with a minimal set of flags:
```bash
helm install rancher-turtles turtles/rancher-turtles --version v0.5.0 \
@@ -93,19 +85,19 @@ This operation could take a few minutes and once completed you can review the in
- `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:
- If `cert-manager` is already available in the cluster, to avoid conflicts, disable its installation as a Rancher Turtles dependency:
`--set cluster-api-operator.cert-manager.enabled=false`
- For a list of Rancher Turtles versions, refer to [Releases page](https://github.com/rancher/turtles/releases).
- For a list of Rancher Turtles versions, refer to the [Turtles release page](https://github.com/rancher/turtles/releases).
:::
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.
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 enabling the minimum required features: `CLUSTER_TOPOLOGY`, `EXP_CLUSTER_RESOURCE_SET` and `EXP_MACHINE_POOL`.
```bash
helm install ...
# Passing secret name and namespace for additional environment variables
--set cluster-api-operator.cluster-api.configSecret.name=<secret_name>
--set cluster-api-operator.cluster-api.configSecret.name=<secret-name>
```
The following is an example of a user-managed secret `cluster-api-operator.cluster-api.configSecret.name=variables` with `CLUSTER_TOPOLOGY`, `EXP_CLUSTER_RESOURCE_SET` and `EXP_MACHINE_POOL` feature flags set and an extra custom variable:
@@ -125,23 +117,23 @@ stringData:
```
:::info
For detailed information on the values supported by the chart and their usage, refer to [Helm chart options](https://docs.rancher-turtles.com/docs/reference-guides/rancher-turtles-chart/values)
For detailed information on the values supported by the chart and their usage, refer to [Helm chart options](https://turtles.docs.rancher.com/docs/reference-guides/rancher-turtles-chart/values)
:::
#### 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](https://docs.rancher-turtles.com/docs/next/tasks/capi-operator/intro) in the Rancher Turtles documentation for assistance.
Remember that if you opt for this installation option, you must manage the Cluster API Operator installation yourself. You can follow the [CAPI Operator guide](https://turtles.docs.rancher.com/docs/tasks/capi-operator/intro) in the Rancher Turtles documentation for assistance.
:::
The `rancher-turtles` chart is available in https://rancher.github.io/turtles and this Helm repository must be added before proceeding with the installation:
Add the `rancher-turtles` chart from the in https://rancher.github.io/turtles Helm repository before installation:
```bash
helm repo add turtles https://rancher.github.io/turtles
helm repo update
```
and then it can be installed into the `rancher-turtles-system` namespace with:
Install the chart into the `rancher-turtles-system` namespace:
```bash
helm install rancher-turtles turtles/rancher-turtles --version v0.5.0
@@ -152,24 +144,22 @@ helm install rancher-turtles turtles/rancher-turtles --version v0.5.0
--dependency-update
```
As you can see, we are telling Helm to ignore installing `cluster-api-operator` as a dependency.
The previous commands tell Helm to ignore installing `cluster-api-operator` as a dependency.
This operation could take a few minutes and once completed you can review the installed controller listed below:
- `rancher-turtles-controller`
## Uninstalling Rancher Turtles
This section gives an overview of the 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.
To simplify uninstalling Rancher Turtles (via Rancher Manager or helm command), the official Rancher Turtles Helm chart includes a `post-delete` hook that applies these changes that are outlined below:
To simplify uninstalling Rancher Turtles (via Rancher Manager or Helm command), the official Rancher Turtles Helm chart includes a `post-delete` hook that that removes the following:
- Deletes the `mutating-webhook-configuration` and `validating-webhook-configuration` webhooks that are no longer needed.
- Deletes the CAPI `deployments` that are no longer needed.
:::
To uninstall the Rancher Turtles Extension use the following helm command:
To uninstall Rancher Turtles:
```bash
helm uninstall -n rancher-turtles-system rancher-turtles --cascade foreground --wait
@@ -181,7 +171,7 @@ This may take a few minutes to complete.
Remember that, if you use a different name for the installation or a different namespace, you may need to customize the command for your specific configuration.
:::
Once uninstalled, Rancher's `embedded-cluster-api` feature must be re-enabled:
Once Rancher Turtles is uninstalled, Rancher's `embedded-cluster-api` feature must be re-enabled:
1. Create a `feature.yaml` file, with `embedded-cluster-api` set to true:
```yaml title="feature.yaml"
@@ -207,4 +197,4 @@ Below is a visual representation of the key components of Rancher Turtles and th
[SLSA](https://slsa.dev/spec/v1.0/about) is a set of incrementally adoptable guidelines for supply chain security, established by industry consensus. The specification set by SLSA is useful for both software producers and consumers: producers can follow SLSA’s guidelines to make their software supply chain more secure, and consumers can use SLSA to make decisions about whether to trust a software package.
Rancher Turtles meets [SLSA Level 3](https://slsa.dev/spec/v1.0/levels#build-l3) requirements for appropriate build platform, consistent build process, and provenance distribution. For more information, please visit the [Rancher Turtles Security](https://docs.rancher-turtles.com/docs/security/slsa) document.
Rancher Turtles meets [SLSA Level 3](https://slsa.dev/spec/v1.0/levels#build-l3) requirements for appropriate build platform, consistent build process, and provenance distribution. For more information, visit the [Rancher Turtles Security](https://turtles.docs.rancher.com/docs/security/slsa) document.
versioned_docs/version-2.7/integrations-in-rancher/cluster-api/capi.md
+4 -4
View File
@@ -6,9 +6,9 @@ title: Cluster API with Rancher Turtles
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/integrations-in-rancher/cluster-api"/>
</head>
Rancher Turtles is a [Rancher extension](../rancher-extensions.md) that provides integration between your Cluster API (CAPI) and Rancher to manage the lifecycle of provisioned Kubernetes clusters. The main functionality is outlined below:
Rancher Turtles is a [Rancher extension](../rancher-extensions.md) that manages the lifecycle of provisioned Kubernetes clusters, by providing integration between your Cluster API (CAPI) and Rancher. With Rancher Turtles, you can:
- Importing CAPI clusters into Rancher: Installing the Rancher Cluster Agent in CAPI provisioned clusters.
- Configuration support for the CAPI Operator.
- Import CAPI clusters into Rancher, by installing the Rancher Cluster Agent in CAPI provisioned clusters.
- Configure the CAPI Operator.
The [Overview](./overview.md) section outlines installation options, the main architecture, and a brief demo. For more detailed information, please view the [Rancher Turtles documentation](https://docs.rancher-turtles.com/docs/intro).
The [Overview](./overview.md) section outlines installation options, Rancher Turtles architecture, and a brief demo. For more details, see the [Rancher Turtles documentation](https://turtles.docs.rancher.com/).
versioned_docs/version-2.7/integrations-in-rancher/cluster-api/overview.md
+38 -48
View File
@@ -12,39 +12,39 @@ title: Overview
## Installing the Rancher Turtles Operator
### Via Rancher Dashboard
This is the recommended option for installing Rancher Turtles.
Using the Rancher UI, and by adding the Turtles repository, we can let Rancher process the installation and configuration of the Cluster API Extension.
You can install the Rancher Turtles operator via the Rancher UI, or with Helm. The first method is recommended for most environments.
:::caution
If you already have the Cluster API Operator installed in your cluster, you need to use the [manual helm installation method](./overview.md#via-helm-install) instead.
If you already have the Cluster API Operator installed in your cluster, you must use the [manual helm installation method](./overview.md#via-helm-install).
:::
:::info prerequisite
Before installing Rancher Turtles 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 in your Rancher environment, you must disable Rancher's `embedded-cluster-api` functionality. This also includes 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 which are outlined below if manually removing:
- Disable the `embedded-cluster-api` feature in Rancher.
- Delete the `mutating-webhook-configuration` and `validating-webhook-configuration` webhooks that are no longer needed.
To simplify setting up Rancher for installing Rancher Turtles, the official Rancher Turtles Helm chart includes a `pre-install` hook that removes the following:
- Disables the `embedded-cluster-api` feature in Rancher.
- Deletes the `mutating-webhook-configuration` and `validating-webhook-configuration` webhooks, as they are no longer needed.
:::
### Via Rancher UI
By adding the Turtles repository via the Rancher UI, Rancher can process the installation and configuration of the Cluster API Extension.
#### Installation
- From your browser, access Rancher Manager and explore the **local** cluster.
- Using the left navigation panel, go to `Apps` -> `Repositories`.
- Click `Create` to add a new repository.
- Click **☰**. Under **Explore Cluster** in the left navigation menu, select **local**.
- In the left navigation menu of the **Cluster Dashboard**, select **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`.
- **Name**: turtles
- **Index URL**: https://rancher.github.io/turtles
- Wait until the new repository has a status of `Active`.
- In the left navigation menu, select **Apps > Charts**.
- Enter "turtles" into the search filter to find the Turtles chart.
- Click **Rancher Turtles - the Cluster API Extension**.
- Click **Install > Next > Install**.
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 the Rancher UI or, alternatively, you can opt for the [manual installation via Helm](./overview.md#via-helm-install). If you are interested in learning more about the available values, you can check the Rancher Turtles [Helm chart reference guide](https://docs.rancher-turtles.com/docs/reference-guides/rancher-turtles-chart/values).
This process uses 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 the Rancher UI or you can [manually install the chart via Helm](./overview.md#via-helm-install). For details about available values, see the Rancher Turtles [Helm chart reference guide](https://turtles.docs.rancher.com/docs/reference-guides/rancher-turtles-chart/values).
The installation may take a few minutes and once completed you will see the following new deployments in the cluster:
- `rancher-turtles-system/rancher-turtles-controller-manager`
@@ -53,32 +53,24 @@ The installation may take a few minutes and once completed you will see the foll
### Via Helm Install
This section walks through different Helm installation options for Rancher Turtles depending on CAPI operator use:
The Helm installation options for Rancher Turtles has two paths depending on CAPI operator use:
- [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.
The Cluster API Operator is required for installing Rancher Turtles. You can choose whether you want to take care of this dependency yourself or let the Rancher Turtles Helm chart manage it for you. [Installing Turtles as a dependency](#install-rancher-turtles-with-cluster-api-operator-as-a-helm-dependency) is simpler, but your best option depends on your specific configuration.
CAPI Operator allows for 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 prerequisite
Before installing Rancher Turtles 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 which are outlined below:
- Disable the `embedded-cluster-api` feature in Rancher.
- Delete the `mutating-webhook-configuration` and `validating-webhook-configuration` webhooks that are no longer needed.
:::
#### 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:
The `rancher-turtles` chart is available in https://rancher.github.io/turtles. This Helm repository must be added before installation:
```bash
helm repo add turtles https://rancher.github.io/turtles
helm repo update
```
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:
As mentioned before, installing Rancher Turtles requires the [Cluster API Operator](https://github.com/kubernetes-sigs/cluster-api-operator). The Helm chart can automatically install it with a minimal set of flags:
```bash
helm install rancher-turtles turtles/rancher-turtles --version v0.5.0 \
@@ -93,19 +85,19 @@ This operation could take a few minutes and once completed you can review the in
- `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:
- If `cert-manager` is already available in the cluster, to avoid conflicts, disable its installation as a Rancher Turtles dependency:
`--set cluster-api-operator.cert-manager.enabled=false`
- For a list of Rancher Turtles versions, refer to [Releases page](https://github.com/rancher/turtles/releases).
- For a list of Rancher Turtles versions, refer to the [Turtles release page](https://github.com/rancher/turtles/releases).
:::
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.
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 enabling the minimum required features: `CLUSTER_TOPOLOGY`, `EXP_CLUSTER_RESOURCE_SET` and `EXP_MACHINE_POOL`.
```bash
helm install ...
# Passing secret name and namespace for additional environment variables
--set cluster-api-operator.cluster-api.configSecret.name=<secret_name>
--set cluster-api-operator.cluster-api.configSecret.name=<secret-name>
```
The following is an example of a user-managed secret `cluster-api-operator.cluster-api.configSecret.name=variables` with `CLUSTER_TOPOLOGY`, `EXP_CLUSTER_RESOURCE_SET` and `EXP_MACHINE_POOL` feature flags set and an extra custom variable:
@@ -125,23 +117,23 @@ stringData:
```
:::info
For detailed information on the values supported by the chart and their usage, refer to [Helm chart options](https://docs.rancher-turtles.com/docs/reference-guides/rancher-turtles-chart/values)
For detailed information on the values supported by the chart and their usage, refer to [Helm chart options](https://turtles.docs.rancher.com/docs/reference-guides/rancher-turtles-chart/values)
:::
#### 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](https://docs.rancher-turtles.com/docs/next/tasks/capi-operator/intro) in the Rancher Turtles documentation for assistance.
Remember that if you opt for this installation option, you must manage the Cluster API Operator installation yourself. You can follow the [CAPI Operator guide](https://turtles.docs.rancher.com/docs/tasks/capi-operator/intro) in the Rancher Turtles documentation for assistance.
:::
The `rancher-turtles` chart is available in https://rancher.github.io/turtles and this Helm repository must be added before proceeding with the installation:
Add the `rancher-turtles` chart from the in https://rancher.github.io/turtles Helm repository before installation:
```bash
helm repo add turtles https://rancher.github.io/turtles
helm repo update
```
and then it can be installed into the `rancher-turtles-system` namespace with:
Install the chart into the `rancher-turtles-system` namespace:
```bash
helm install rancher-turtles turtles/rancher-turtles --version v0.5.0
@@ -152,24 +144,22 @@ helm install rancher-turtles turtles/rancher-turtles --version v0.5.0
--dependency-update
```
As you can see, we are telling Helm to ignore installing `cluster-api-operator` as a dependency.
The previous commands tell Helm to ignore installing `cluster-api-operator` as a dependency.
This operation could take a few minutes and once completed you can review the installed controller listed below:
- `rancher-turtles-controller`
## Uninstalling Rancher Turtles
This section gives an overview of the 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.
To simplify uninstalling Rancher Turtles (via Rancher Manager or helm command), the official Rancher Turtles Helm chart includes a `post-delete` hook that applies these changes that are outlined below:
To simplify uninstalling Rancher Turtles (via Rancher Manager or Helm command), the official Rancher Turtles Helm chart includes a `post-delete` hook that that removes the following:
- Deletes the `mutating-webhook-configuration` and `validating-webhook-configuration` webhooks that are no longer needed.
- Deletes the CAPI `deployments` that are no longer needed.
:::
To uninstall the Rancher Turtles Extension use the following helm command:
To uninstall Rancher Turtles:
```bash
helm uninstall -n rancher-turtles-system rancher-turtles --cascade foreground --wait
@@ -181,7 +171,7 @@ This may take a few minutes to complete.
Remember that, if you use a different name for the installation or a different namespace, you may need to customize the command for your specific configuration.
:::
Once uninstalled, Rancher's `embedded-cluster-api` feature must be re-enabled:
Once Rancher Turtles is uninstalled, Rancher's `embedded-cluster-api` feature must be re-enabled:
1. Create a `feature.yaml` file, with `embedded-cluster-api` set to true:
```yaml title="feature.yaml"
@@ -207,4 +197,4 @@ Below is a visual representation of the key components of Rancher Turtles and th
[SLSA](https://slsa.dev/spec/v1.0/about) is a set of incrementally adoptable guidelines for supply chain security, established by industry consensus. The specification set by SLSA is useful for both software producers and consumers: producers can follow SLSA’s guidelines to make their software supply chain more secure, and consumers can use SLSA to make decisions about whether to trust a software package.
Rancher Turtles meets [SLSA Level 3](https://slsa.dev/spec/v1.0/levels#build-l3) requirements for appropriate build platform, consistent build process, and provenance distribution. For more information, please visit the [Rancher Turtles Security](https://docs.rancher-turtles.com/docs/security/slsa) document.
Rancher Turtles meets [SLSA Level 3](https://slsa.dev/spec/v1.0/levels#build-l3) requirements for appropriate build platform, consistent build process, and provenance distribution. For more information, visit the [Rancher Turtles Security](https://turtles.docs.rancher.com/docs/security/slsa) document.
versioned_docs/version-2.8/integrations-in-rancher/cluster-api/capi.md
+4 -4
View File
@@ -6,9 +6,9 @@ title: Cluster API with Rancher Turtles
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/integrations-in-rancher/cluster-api"/>
</head>
Rancher Turtles is a [Rancher extension](../rancher-extensions.md) that provides integration between your Cluster API (CAPI) and Rancher to manage the lifecycle of provisioned Kubernetes clusters. The main functionality is outlined below:
Rancher Turtles is a [Rancher extension](../rancher-extensions.md) that manages the lifecycle of provisioned Kubernetes clusters, by providing integration between your Cluster API (CAPI) and Rancher. With Rancher Turtles, you can:
- Importing CAPI clusters into Rancher: Installing the Rancher Cluster Agent in CAPI provisioned clusters.
- Configuration support for the CAPI Operator.
- Import CAPI clusters into Rancher, by installing the Rancher Cluster Agent in CAPI provisioned clusters.
- Configure the CAPI Operator.
The [Overview](./overview.md) section outlines installation options, the main architecture, and a brief demo. For more detailed information, please view the [Rancher Turtles documentation](https://docs.rancher-turtles.com/docs/intro).
The [Overview](./overview.md) section outlines installation options, Rancher Turtles architecture, and a brief demo. For more details, see the [Rancher Turtles documentation](https://turtles.docs.rancher.com/).
versioned_docs/version-2.8/integrations-in-rancher/cluster-api/overview.md
+38 -48
View File
@@ -12,39 +12,39 @@ title: Overview
## Installing the Rancher Turtles Operator
### Via Rancher Dashboard
This is the recommended option for installing Rancher Turtles.
Using the Rancher UI, and by adding the Turtles repository, we can let Rancher process the installation and configuration of the Cluster API Extension.
You can install the Rancher Turtles operator via the Rancher UI, or with Helm. The first method is recommended for most environments.
:::caution
If you already have the Cluster API Operator installed in your cluster, you need to use the [manual helm installation method](./overview.md#via-helm-install) instead.
If you already have the Cluster API Operator installed in your cluster, you must use the [manual helm installation method](./overview.md#via-helm-install).
:::
:::info prerequisite
Before installing Rancher Turtles 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 in your Rancher environment, you must disable Rancher's `embedded-cluster-api` functionality. This also includes 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 which are outlined below if manually removing:
- Disable the `embedded-cluster-api` feature in Rancher.
- Delete the `mutating-webhook-configuration` and `validating-webhook-configuration` webhooks that are no longer needed.
To simplify setting up Rancher for installing Rancher Turtles, the official Rancher Turtles Helm chart includes a `pre-install` hook that removes the following:
- Disables the `embedded-cluster-api` feature in Rancher.
- Deletes the `mutating-webhook-configuration` and `validating-webhook-configuration` webhooks, as they are no longer needed.
:::
### Via Rancher UI
By adding the Turtles repository via the Rancher UI, Rancher can process the installation and configuration of the Cluster API Extension.
#### Installation
- From your browser, access Rancher Manager and explore the **local** cluster.
- Using the left navigation panel, go to `Apps` -> `Repositories`.
- Click `Create` to add a new repository.
- Click **☰**. Under **Explore Cluster** in the left navigation menu, select **local**.
- In the left navigation menu of the **Cluster Dashboard**, select **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`.
- **Name**: turtles
- **Index URL**: https://rancher.github.io/turtles
- Wait until the new repository has a status of `Active`.
- In the left navigation menu, select **Apps > Charts**.
- Enter "turtles" into the search filter to find the Turtles chart.
- Click **Rancher Turtles - the Cluster API Extension**.
- Click **Install > Next > Install**.
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 the Rancher UI or, alternatively, you can opt for the [manual installation via Helm](./overview.md#via-helm-install). If you are interested in learning more about the available values, you can check the Rancher Turtles [Helm chart reference guide](https://docs.rancher-turtles.com/docs/reference-guides/rancher-turtles-chart/values).
This process uses 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 the Rancher UI or you can [manually install the chart via Helm](./overview.md#via-helm-install). For details about available values, see the Rancher Turtles [Helm chart reference guide](https://turtles.docs.rancher.com/docs/reference-guides/rancher-turtles-chart/values).
The installation may take a few minutes and once completed you will see the following new deployments in the cluster:
- `rancher-turtles-system/rancher-turtles-controller-manager`
@@ -53,32 +53,24 @@ The installation may take a few minutes and once completed you will see the foll
### Via Helm Install
This section walks through different Helm installation options for Rancher Turtles depending on CAPI operator use:
The Helm installation options for Rancher Turtles has two paths depending on CAPI operator use:
- [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.
The Cluster API Operator is required for installing Rancher Turtles. You can choose whether you want to take care of this dependency yourself or let the Rancher Turtles Helm chart manage it for you. [Installing Turtles as a dependency](#install-rancher-turtles-with-cluster-api-operator-as-a-helm-dependency) is simpler, but your best option depends on your specific configuration.
CAPI Operator allows for 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 prerequisite
Before installing Rancher Turtles 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 which are outlined below:
- Disable the `embedded-cluster-api` feature in Rancher.
- Delete the `mutating-webhook-configuration` and `validating-webhook-configuration` webhooks that are no longer needed.
:::
#### 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:
The `rancher-turtles` chart is available in https://rancher.github.io/turtles. This Helm repository must be added before installation:
```bash
helm repo add turtles https://rancher.github.io/turtles
helm repo update
```
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:
As mentioned before, installing Rancher Turtles requires the [Cluster API Operator](https://github.com/kubernetes-sigs/cluster-api-operator). The Helm chart can automatically install it with a minimal set of flags:
```bash
helm install rancher-turtles turtles/rancher-turtles --version v0.5.0 \
@@ -93,19 +85,19 @@ This operation could take a few minutes and once completed you can review the in
- `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:
- If `cert-manager` is already available in the cluster, to avoid conflicts, disable its installation as a Rancher Turtles dependency:
`--set cluster-api-operator.cert-manager.enabled=false`
- For a list of Rancher Turtles versions, refer to [Releases page](https://github.com/rancher/turtles/releases).
- For a list of Rancher Turtles versions, refer to the [Turtles release page](https://github.com/rancher/turtles/releases).
:::
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.
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 enabling the minimum required features: `CLUSTER_TOPOLOGY`, `EXP_CLUSTER_RESOURCE_SET` and `EXP_MACHINE_POOL`.
```bash
helm install ...
# Passing secret name and namespace for additional environment variables
--set cluster-api-operator.cluster-api.configSecret.name=<secret_name>
--set cluster-api-operator.cluster-api.configSecret.name=<secret-name>
```
The following is an example of a user-managed secret `cluster-api-operator.cluster-api.configSecret.name=variables` with `CLUSTER_TOPOLOGY`, `EXP_CLUSTER_RESOURCE_SET` and `EXP_MACHINE_POOL` feature flags set and an extra custom variable:
@@ -125,23 +117,23 @@ stringData:
```
:::info
For detailed information on the values supported by the chart and their usage, refer to [Helm chart options](https://docs.rancher-turtles.com/docs/reference-guides/rancher-turtles-chart/values)
For detailed information on the values supported by the chart and their usage, refer to [Helm chart options](https://turtles.docs.rancher.com/docs/reference-guides/rancher-turtles-chart/values)
:::
#### 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](https://docs.rancher-turtles.com/docs/next/tasks/capi-operator/intro) in the Rancher Turtles documentation for assistance.
Remember that if you opt for this installation option, you must manage the Cluster API Operator installation yourself. You can follow the [CAPI Operator guide](https://turtles.docs.rancher.com/docs/tasks/capi-operator/intro) in the Rancher Turtles documentation for assistance.
:::
The `rancher-turtles` chart is available in https://rancher.github.io/turtles and this Helm repository must be added before proceeding with the installation:
Add the `rancher-turtles` chart from the in https://rancher.github.io/turtles Helm repository before installation:
```bash
helm repo add turtles https://rancher.github.io/turtles
helm repo update
```
and then it can be installed into the `rancher-turtles-system` namespace with:
Install the chart into the `rancher-turtles-system` namespace:
```bash
helm install rancher-turtles turtles/rancher-turtles --version v0.5.0
@@ -152,24 +144,22 @@ helm install rancher-turtles turtles/rancher-turtles --version v0.5.0
--dependency-update
```
As you can see, we are telling Helm to ignore installing `cluster-api-operator` as a dependency.
The previous commands tell Helm to ignore installing `cluster-api-operator` as a dependency.
This operation could take a few minutes and once completed you can review the installed controller listed below:
- `rancher-turtles-controller`
## Uninstalling Rancher Turtles
This section gives an overview of the 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.
To simplify uninstalling Rancher Turtles (via Rancher Manager or helm command), the official Rancher Turtles Helm chart includes a `post-delete` hook that applies these changes that are outlined below:
To simplify uninstalling Rancher Turtles (via Rancher Manager or Helm command), the official Rancher Turtles Helm chart includes a `post-delete` hook that that removes the following:
- Deletes the `mutating-webhook-configuration` and `validating-webhook-configuration` webhooks that are no longer needed.
- Deletes the CAPI `deployments` that are no longer needed.
:::
To uninstall the Rancher Turtles Extension use the following helm command:
To uninstall Rancher Turtles:
```bash
helm uninstall -n rancher-turtles-system rancher-turtles --cascade foreground --wait
@@ -181,7 +171,7 @@ This may take a few minutes to complete.
Remember that, if you use a different name for the installation or a different namespace, you may need to customize the command for your specific configuration.
:::
Once uninstalled, Rancher's `embedded-cluster-api` feature must be re-enabled:
Once Rancher Turtles is uninstalled, Rancher's `embedded-cluster-api` feature must be re-enabled:
1. Create a `feature.yaml` file, with `embedded-cluster-api` set to true:
```yaml title="feature.yaml"
@@ -207,4 +197,4 @@ Below is a visual representation of the key components of Rancher Turtles and th
[SLSA](https://slsa.dev/spec/v1.0/about) is a set of incrementally adoptable guidelines for supply chain security, established by industry consensus. The specification set by SLSA is useful for both software producers and consumers: producers can follow SLSA’s guidelines to make their software supply chain more secure, and consumers can use SLSA to make decisions about whether to trust a software package.
Rancher Turtles meets [SLSA Level 3](https://slsa.dev/spec/v1.0/levels#build-l3) requirements for appropriate build platform, consistent build process, and provenance distribution. For more information, please visit the [Rancher Turtles Security](https://docs.rancher-turtles.com/docs/security/slsa) document.
Rancher Turtles meets [SLSA Level 3](https://slsa.dev/spec/v1.0/levels#build-l3) requirements for appropriate build platform, consistent build process, and provenance distribution. For more information, visit the [Rancher Turtles Security](https://turtles.docs.rancher.com/docs/security/slsa) document.