Skip to content

Commit

Permalink
📖 Minor doc improvements
Browse files Browse the repository at this point in the history
  • Loading branch information
@yiannistri
yiannistri committed Mar 3, 2025
1 parent f918e5a commit 4fd650c
Show file tree
Hide file tree
Showing 8 changed files with 65 additions and 59 deletions.
6 changes: 3 additions & 3 deletions docs/next/modules/en/pages/operator/airgapped.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
= Air-gapped environment
= Air-gapped Environment
:sidebar_position: 3

{product_name} provides support for an air-gapped environment out-of-the-box by leveraging features of the Cluster API Operator, the required dependency for installing {product_name}.
Expand Down Expand Up @@ -85,7 +85,7 @@ spec:

Additionally the *CAPIProvider* overrides the container image to use for the provider using the `deployment.containers[].imageUrl` field. This allows the operator to pull the image from a registry within the air-gapped environment.

=== Situation when manifests do not fit into ConfigMap
=== ConfigMap size limitations

There is a limit on the https://kubernetes.io/docs/concepts/configuration/configmap/#motivation[maximum size] of a ConfigMap - 1MiB. If the manifests do not fit into this size, Kubernetes will generate an error and provider installation fail. To avoid this, you can archive the manifests and put them in the ConfigMap that way.

Expand All @@ -112,7 +112,7 @@ kubectl create configmap v1.11.2 --namespace=capv-system --from-file=components=
yq eval -i '.metadata.annotations += {"provider.cluster.x-k8s.io/compressed": "true"}' configmap.yaml
----
+
NOTE: without this annotation operator won't be able to determine if the data is compressed or not.
NOTE: Without this annotation, the operator won't be able to determine if the data is compressed or not.

. Add labels that will be used to match the ConfigMap in `fetchConfig` section of the provider
+
Expand Down
4 changes: 2 additions & 2 deletions docs/next/modules/en/pages/operator/capiprovider.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ The `CAPIProvider` resource allows managing Cluster API Operator manifests in a

`CAPIProvider` follows a GitOps model - the spec fields are declarative user inputs. The controller only updates status.

Every field provided by the upstream CAPI Operator resource for the desired `spec.type` is also available in the spec of the `CAPIProvider` resouce. Feel free to refer to upstream configuration https://cluster-api-operator.sigs.k8s.io/03_topics/02_configuration/[guides] for advanced scenarios.
Every field provided by the upstream CAPI Operator resource for the desired `spec.type` is also available in the spec of the `CAPIProvider` resource. Feel free to refer to upstream configuration https://cluster-api-operator.sigs.k8s.io/03_topics/02_configuration/[guides] for advanced scenarios.

== Usage

Expand Down Expand Up @@ -36,7 +36,7 @@ spec:
clusterResourceSet: true
----

This will generate an AWS infrastructure provider with the supplied mapping for rancher credential secret and custom enabled features.
This will generate an AWS infrastructure provider with the supplied mapping for Rancher credential secret and custom enabled features.

The `CAPIProvider` controller will own all the generated provider resources, allowing garbage collection by deleting the `CAPIProvider` object.

Expand Down
45 changes: 24 additions & 21 deletions docs/next/modules/en/pages/operator/chart.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,23 +15,26 @@ When installing {product_name} using the official Helm chart, it is possible to
----
rancherTurtles:
features:
label: true # indicates that the label will be added (default: true)
etcd-snapshot-restore: # etcd snapshot and restore exp feature
enabled: false # indicates that the feature is enabled (default: false)
image: controller
imageVersion: v0.0.0
imagePullPolicy: IfNotPresent
addon-provider-fleet: # install fleet addon provider together with Turtles
enabled: true # indicates that the provider is installed (default: true)
agent-tls-mode: # use ca certs stored in rancher when importing capi clusters
enabled: false # indicates that the feature is enabled (default: false)
day2operations:
enabled: false # indicates whether day 2 operations functionality is enabled (default: false).
etcdBackupRestore:
enabled: false # indicates whether ETCD backup/restore experimental functionality is enabled (default: false).
addon-provider-fleet:
enabled: true # indicates whether the fleet addon provider is installed (default: true).
agent-tls-mode:
enabled: false # use CA certs stored in Rancher when importing CAPI clusters.
clusterclass-operations:
enabled: false # indicates whether ClusterClass operations functionality is enabled (default: false).
----

The list has been truncated to show only the configurable feature flags. Other fields with the `rancherTurtles` key are automatically set when a chart is released.
The list has been truncated to show only the configurable feature flags. Other fields with the `rancherTurtles` key are automatically set when a chart is released.

[NOTE]
Nested feature flags take effect when their parent feature flag is enabled. For example, the `rancherTurtles.features.day2operations.etcdBackupRestore.enabled` flag takes effect only when the `rancherTurtles.features.day2operations.enabled` flag is set to true.

== Cluster API Operator values

Any values passed to `helm` with the `cluster-api-operator` key will be passed along to the `Cluster API Operator` project.
{product_name} uses the `Cluster API Operator` Helm chart to install this dependency, and any values passed to Helm with the `cluster-api-operator` key are passed along to the `Cluster API Operator` chart in order to customize its installation.

[TIP]
====
Expand All @@ -44,29 +47,29 @@ Currently the available set of values for the `cluster-api-operator` setup in th
[source,yaml]
----
cluster-api-operator:
enabled: true # indicates if CAPI operator should be installed (default: true)
cleanup: true # indicates if CAPI operator resources should be cleaned up on uninstall (default: true)
enabled: true # indicates whether CAPI operator is installed (default: true).
cleanup: true # indicates whether CAPI operator resources are cleaned up on uninstall (default: true).
cluster-api:
enabled: true # indicates if core CAPI controllers should be installed (default: true)
enabled: true # indicates whether core CAPI controllers are installed (default: true).
configSecret:
name: "" # (provide only if using a user-managed secret) name of the config secret to use for core CAPI controllers, used by the CAPI operator. See https://github.com/kubernetes-sigs/cluster-api-operator/tree/main/docs#installing-azure-infrastructure-provider docs for more details.
defaultName: "capi-env-variables" # default name for the automatically created secret.
core:
namespace: capi-system
fetchConfig: # (only required for airgapped environments)
fetchConfig: # (only required for airgapped environments).
url: "" # url to fetch config from, used by the CAPI operator. See https://github.com/kubernetes-sigs/cluster-api-operator/tree/main/docs#provider-spec docs for more details.
selector: "" # selector to use for fetching config, used by the CAPI operator.
rke2:
enabled: true # indicates if RKE2 provider for Cluster API should be installed (default: true)
version: "" # version of Cluster API Provider RKE2 (CAPRKE2) to install
bootstrap: # CAPRKE2 Bootstrap Provider
enabled: true # indicates whether RKE2 provider for Cluster API is installed (default: true).
version: "" # version of Cluster API Provider RKE2 (CAPRKE2) to install.
bootstrap: # CAPRKE2 Bootstrap Provider.
namespace: rke2-bootstrap-system
fetchConfig: # (only required for airgapped environments)
url: "" # url to fetch config from, used by the CAPI operator. See https://github.com/kubernetes-sigs/cluster-api-operator/tree/main/docs#provider-spec docs for more details.
selector: "" # selector to use for fetching config, used by the CAPI operator.
controlPlane: # CAPRKE2 Control Plane Provider
controlPlane: # CAPRKE2 Control Plane Provider.
namespace: rke2-control-plane-system
fetchConfig: # (only required for airgapped environments)
fetchConfig: # (only required for airgapped environments)
url: "" # url to fetch config from, used by the CAPI operator. See https://github.com/kubernetes-sigs/cluster-api-operator/tree/main/docs#provider-spec docs for more details.
selector: "" # selector to use for fetching config, used by the CAPI operator.
----
6 changes: 3 additions & 3 deletions docs/next/modules/en/pages/operator/clusterclass.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
= Enabling ClusterClass

In this section we cover enabling *ClusterClass* for a CAPI Provider.
In this section we cover enabling the https://cluster-api.sigs.k8s.io/tasks/experimental-features/cluster-class/[*ClusterClass*] feature for a CAPI Provider.

[TIP]
====
Before using ClusterClass, study the provider docs and confirm that the feature is supported. This documentation includes a matrix in the xref:../reference/certified.adoc[Certified providers] section with xref:../reference/certified.adoc#_clusterclass_support_for_certified_providers[cluster topology support status].
Before using the ClusterClass feature, study the provider docs and confirm that the feature is supported. This documentation includes a matrix in the xref:../reference/certified.adoc[Certified providers] section with xref:../reference/certified.adoc#_clusterclass_support_for_certified_providers[cluster topology support status].
====

== Enable ClusterClass

To use ClusterClass it needs to be enabled for core Cluster API and any provider that supports it. This is done by setting the `CLUSTER_TOPOLOGY` variable to `true`.
In order to use the ClusterClass feature, it needs to be enabled for core Cluster API and any provider that supports it. This is done by setting the `CLUSTER_TOPOLOGY` variable to `true`.

The {product_name} Helm chart will automatically enable the feature when installing CAPI. However, when enabling additional providers, ensure `CLUSTER_TOPOLOGY` is set in the provider configuration. Turtles' xref:../operator/capiprovider.adoc[CAPIProvider] resource supports passing installation parameters to the provider via `variables` as follows:

Expand Down
6 changes: 3 additions & 3 deletions docs/v0.17/modules/en/pages/operator/airgapped.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
= Air-gapped environment
= Air-gapped Environment
:sidebar_position: 3

{product_name} provides support for an air-gapped environment out-of-the-box by leveraging features of the Cluster API Operator, the required dependency for installing {product_name}.
Expand Down Expand Up @@ -85,7 +85,7 @@ spec:

Additionally the *CAPIProvider* overrides the container image to use for the provider using the `deployment.containers[].imageUrl` field. This allows the operator to pull the image from a registry within the air-gapped environment.

=== Situation when manifests do not fit into ConfigMap
=== ConfigMap size limitations

There is a limit on the https://kubernetes.io/docs/concepts/configuration/configmap/#motivation[maximum size] of a ConfigMap - 1MiB. If the manifests do not fit into this size, Kubernetes will generate an error and provider installation fail. To avoid this, you can archive the manifests and put them in the ConfigMap that way.

Expand All @@ -112,7 +112,7 @@ kubectl create configmap v1.11.2 --namespace=capv-system --from-file=components=
yq eval -i '.metadata.annotations += {"provider.cluster.x-k8s.io/compressed": "true"}' configmap.yaml
----
+
NOTE: without this annotation operator won't be able to determine if the data is compressed or not.
NOTE: Without this annotation, the operator won't be able to determine if the data is compressed or not.

. Add labels that will be used to match the ConfigMap in `fetchConfig` section of the provider
+
Expand Down
4 changes: 2 additions & 2 deletions docs/v0.17/modules/en/pages/operator/capiprovider.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ The `CAPIProvider` resource allows managing Cluster API Operator manifests in a

`CAPIProvider` follows a GitOps model - the spec fields are declarative user inputs. The controller only updates status.

Every field provided by the upstream CAPI Operator resource for the desired `spec.type` is also available in the spec of the `CAPIProvider` resouce. Feel free to refer to upstream configuration https://cluster-api-operator.sigs.k8s.io/03_topics/02_configuration/[guides] for advanced scenarios.
Every field provided by the upstream CAPI Operator resource for the desired `spec.type` is also available in the spec of the `CAPIProvider` resource. Feel free to refer to upstream configuration https://cluster-api-operator.sigs.k8s.io/03_topics/02_configuration/[guides] for advanced scenarios.

== Usage

Expand Down Expand Up @@ -36,7 +36,7 @@ spec:
clusterResourceSet: true
----

This will generate an AWS infrastructure provider with the supplied mapping for rancher credential secret and custom enabled features.
This will generate an AWS infrastructure provider with the supplied mapping for Rancher credential secret and custom enabled features.

The `CAPIProvider` controller will own all the generated provider resources, allowing garbage collection by deleting the `CAPIProvider` object.

Expand Down
47 changes: 25 additions & 22 deletions docs/v0.17/modules/en/pages/operator/chart.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,23 +15,26 @@ When installing {product_name} using the official Helm chart, it is possible to
----
rancherTurtles:
features:
label: true # indicates that the label will be added (default: true)
etcd-snapshot-restore: # etcd snapshot and restore exp feature
enabled: false # indicates that the feature is enabled (default: false)
image: controller
imageVersion: v0.0.0
imagePullPolicy: IfNotPresent
addon-provider-fleet: # install fleet addon provider together with Turtles
enabled: true # indicates that the provider is installed (default: true)
agent-tls-mode: # use ca certs stored in rancher when importing capi clusters
enabled: false # indicates that the feature is enabled (default: false)
day2operations:
enabled: false # indicates whether day 2 operations functionality is enabled (default: false).
etcdBackupRestore:
enabled: false # indicates whether ETCD backup/restore experimental functionality is enabled (default: false).
addon-provider-fleet:
enabled: true # indicates whether the fleet addon provider is installed (default: true).
agent-tls-mode:
enabled: false # use CA certs stored in Rancher when importing CAPI clusters.
clusterclass-operations:
enabled: false # indicates whether ClusterClass operations functionality is enabled (default: false).
----

The list has been truncated to show only the configurable feature flags. Other fields with the `rancherTurtles` key are automatically set when a chart is released.
The list has been truncated to show only the configurable feature flags. Other fields with the `rancherTurtles` key are automatically set when a chart is released.

[NOTE]
Nested feature flags take effect when their parent feature flag is enabled. For example, the `rancherTurtles.features.day2operations.etcdBackupRestore.enabled` flag takes effect only when the `rancherTurtles.features.day2operations.enabled` flag is set to true.

== Cluster API Operator values

Any values passed to `helm` with the `cluster-api-operator` key will be passed along to the `Cluster API Operator` project.
{product_name} uses the `Cluster API Operator` Helm chart to install this dependency, and any values passed to Helm with the `cluster-api-operator` key are passed along to the `Cluster API Operator` chart in order to customize its installation.

[TIP]
====
Expand All @@ -44,29 +47,29 @@ Currently the available set of values for the `cluster-api-operator` setup in th
[source,yaml]
----
cluster-api-operator:
enabled: true # indicates if CAPI operator should be installed (default: true)
cleanup: true # indicates if CAPI operator resources should be cleaned up on uninstall (default: true)
enabled: true # indicates whether CAPI operator is installed (default: true).
cleanup: true # indicates whether CAPI operator resources are cleaned up on uninstall (default: true).
cluster-api:
enabled: true # indicates if core CAPI controllers should be installed (default: true)
enabled: true # indicates whether core CAPI controllers are installed (default: true).
configSecret:
name: "" # (provide only if using a user-managed secret) name of the config secret to use for core CAPI controllers, used by the CAPI operator. See https://github.com/kubernetes-sigs/cluster-api-operator/tree/main/docs#installing-azure-infrastructure-provider docs for more details.
defaultName: "capi-env-variables" # default name for the automatically created secret.
core:
namespace: capi-system
fetchConfig: # (only required for airgapped environments)
fetchConfig: # (only required for airgapped environments).
url: "" # url to fetch config from, used by the CAPI operator. See https://github.com/kubernetes-sigs/cluster-api-operator/tree/main/docs#provider-spec docs for more details.
selector: "" # selector to use for fetching config, used by the CAPI operator.
rke2:
enabled: true # indicates if RKE2 provider for Cluster API should be installed (default: true)
version: "" # version of Cluster API Provider RKE2 (CAPRKE2) to install
bootstrap: # CAPRKE2 Bootstrap Provider
enabled: true # indicates whether RKE2 provider for Cluster API is installed (default: true).
version: "" # version of Cluster API Provider RKE2 (CAPRKE2) to install.
bootstrap: # CAPRKE2 Bootstrap Provider.
namespace: rke2-bootstrap-system
fetchConfig: # (only required for airgapped environments)
fetchConfig: # (only required for airgapped environments).
url: "" # url to fetch config from, used by the CAPI operator. See https://github.com/kubernetes-sigs/cluster-api-operator/tree/main/docs#provider-spec docs for more details.
selector: "" # selector to use for fetching config, used by the CAPI operator.
controlPlane: # CAPRKE2 Control Plane Provider
controlPlane: # CAPRKE2 Control Plane Provider.
namespace: rke2-control-plane-system
fetchConfig: # (only required for airgapped environments)
fetchConfig: # (only required for airgapped environments).
url: "" # url to fetch config from, used by the CAPI operator. See https://github.com/kubernetes-sigs/cluster-api-operator/tree/main/docs#provider-spec docs for more details.
selector: "" # selector to use for fetching config, used by the CAPI operator.
----
6 changes: 3 additions & 3 deletions docs/v0.17/modules/en/pages/operator/clusterclass.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
= Enabling ClusterClass

In this section we cover enabling *ClusterClass* for a CAPI Provider.
In this section we cover enabling the https://cluster-api.sigs.k8s.io/tasks/experimental-features/cluster-class/[*ClusterClass*] feature for a CAPI Provider.

[TIP]
====
Before using ClusterClass, study the provider docs and confirm that the feature is supported. This documentation includes a matrix in the xref:../reference/certified.adoc[Certified providers] section with xref:../reference/certified.adoc#_clusterclass_support_for_certified_providers[cluster topology support status].
Before using the ClusterClass feature, study the provider docs and confirm that the feature is supported. This documentation includes a matrix in the xref:../reference/certified.adoc[Certified providers] section with xref:../reference/certified.adoc#_clusterclass_support_for_certified_providers[cluster topology support status].
====

== Enable ClusterClass

To use ClusterClass it needs to be enabled for core Cluster API and any provider that supports it. This is done by setting the `CLUSTER_TOPOLOGY` variable to `true`.
In order to use the ClusterClass feature, it needs to be enabled for core Cluster API and any provider that supports it. This is done by setting the `CLUSTER_TOPOLOGY` variable to `true`.

The {product_name} Helm chart will automatically enable the feature when installing CAPI. However, when enabling additional providers, ensure `CLUSTER_TOPOLOGY` is set in the provider configuration. Turtles' xref:../operator/capiprovider.adoc[CAPIProvider] resource supports passing installation parameters to the provider via `variables` as follows:

Expand Down

0 comments on commit 4fd650c

Please sign in to comment.