This is unreleased documentation for Rancher Turtles v0.26-dev.

Features

This section describes features and feature stages in Rancher Turtles.

List of Features

Feature Helm Feature Name Sub-Feature Default Stage

Agent TLS Mode

agent-tls-mode

None

enabled

beta

No Cert Manager

no-cert-manager

None

enabled

beta

Use Rancher Default Registry

use-rancher-default-registry

None

enabled

beta

Use CAAPF

use-caapf

None

disabled

alpha

Agent TLS Mode

This feature gate is used to instruct Rancher Turtles on whether it should follow Rancher’s agent-tls-mode setting, when retrieving cluster registration manifests for importing clusters. When enabled, Turtles will lookup the value of Rancher’s agent-tls-mode setting to determine whether it has been set to system-store or strict. If set to system-store, Turtles will trust any certificate generated by a public Certificate Authority contained in the operating system’s trust store, including those signed by authorities such as Let’s Encrypt. If set to strict, Turtles will only trust certificates generated by the Certificate Authority contained in Rancher’s cacerts setting. When this setting is disabled, Turtles will fallback to work in system-store mode. This feature is in beta stage and enabled by default.

No Cert Manager

This feature gate converts the CAPI Providers manifests to replace cert-manager usage with wrangler.

In particular, the validating and mutating admission webhooks will be updated to use certificates generated by wrangler, instead of cert-manager, allowing for a cert-manager free environment.

Beware that usage of the Rancher CATTLE_SYNC_ONLY_CHANGED_OBJECTS functionality may prevent certificates from renewing after the default expiration time of one year.

It is possible to disable this feature to restore all provider manifests to the original cert-manager usage.

Use Rancher Default Registry

This feature gate instructs Rancher Turtles to leverage Rancher’s system-default-registry management setting when constructing image references for CAPI provider components. When enabled, Rancher Turtles reads this setting and, if a registry is configured, rewrites the repository for every provider image to use that registry. If the setting is empty, Rancher Turtles falls back to the default image references. Image overrides defined in the ClusterctlConfig resource always take precedence. For detailed usage in air-gapped environments, see Air-gapped Environment. This feature is in alpha stage and enabled by default.

Use CAAPF

This feature gate instructs Rancher Turtles that the Cluster API Add-on Provider for Fleet (CAAPF) will be used to provide integration with Fleet and enable the easy deployment of applications to CAPI provisioned clusters. CAAPF automatically installs Fleet in the management cluster and registers newly provisioned CAPI clusters with Fleet, so that applications can be deployed to these clusters via GitOps, Bundle or HelmOp resources. CAAPF also includes support for grouping CAPI clusters that reference the same ClusterClass through Fleet’s ClusterGroup, essentially simplifying application deployments to large groups of clusters. This feature is in alpha stage and disabled by default.

Feature Stages

Rancher Turtles follows the Kubernetes feature stages process. A feature can be in one of the following stages: Alpha, Beta, or General Availability (GA).

Alpha Stage

  • Disabled by default.

  • May be buggy, with no long-term support.

  • API may change without notice.

  • Recommended only for short-lived testing clusters.

Beta Stage

  • Always enabled by default.

  • Well-tested and considered safe.

  • Support is stable, but schema may change in future releases.

  • Recommended for non-business-critical uses due to potential incompatible changes.

Please provide feedback on Alpha and Beta features!

General Availability (GA) Stage

  • Always enabled, cannot be disabled.

  • No feature gate needed.

  • Stable, with long-term support in future releases.

How to set feature gates

You can set configuration options for all charts that get installed as part of Rancher.

To enable/disable feature gates for the Rancher Turtles chart, patch the rancher-config ConfigMap in the cattle-system namespace to add or update the rancher-turtles key under .data. The value of this key is a YAML string containing a features map, where each entry corresponds to a feature gate name from the list above with an enabled boolean field. For example:

kubectl patch configmap rancher-config -n cattle-system --type=merge -p '
  data:
    rancher-turtles: |
      features:
        agent-tls-mode:
          enabled: true
        no-cert-manager:
          enabled: true
        use-rancher-default-registry:
          enabled: true
        use-caapf:
          enabled: false
  '

Rancher then reads this ConfigMap and passes these values to the Rancher Turtles controller.

Note that because rancher-turtles is a plain string value (containing embedded YAML), the patch replaces the entire string — so include all desired feature gate entries in the patch as well as any other settings, not just the ones you are changing, to avoid inadvertently dropping settings that were previously present under that key.