Available as of v2.3.0

Rancher includes some features that are experimental and disabled by default. You might want to enable these features, for example, if you decide that the benefits of using an unsupported storage type outweighs the risk of using an untested feature. Feature flags were introduced to allow you to try these features that are not enabled by default.

The features can be enabled in two ways:

  • When installing Rancher with a CLI, you can use a feature flag to enable a feature by default
  • After installing Rancher, you can turn on the features with the Rancher API

Each feature has two values:

  • A default value, which can be configured with a flag or environment variable from the command line
  • A set value, which can be configured with the Rancher API

If no value has been set, Rancher uses the default value.

Because the API sets the actual value and the command line sets the default value, that means that if you enable or disable a feature with the API, it will override any value set with the command line.

For example, if you install Rancher, then set a feature flag to true with the Rancher API, then upgrade Rancher with a command that sets the feature flag to false, the default value will still be false, but the feature will still be enabled because it was set with the Rancher API. If you then deleted the set value (true) with the Rancher API, setting it to NULL, the default value (false) would take effect.

The following is a list of the feature flags available in Rancher:

Feature Feature Flag Name Default Value Description Available as of
Allow unsupported storage drivers unsupported-storage-drivers false This feature enables types for storage providers and provisioners that are not enabled by default. v2.3.0
UI for Istio virtual services and destination rules istio-virtual-service-ui false Enables a UI that lets you create, read, update and delete virtual services and destination rules, which are traffic management features of Istio v2.3.0

Enabling Features when Starting Rancher

When you install Rancher, enable the feature you want with a feature flag. The command is different depending on whether you are installing Rancher on a single node or if you are doing an HA installation of Rancher.

Note: Values set from the Rancher API will override the value passed in through the command line.

When installing Rancher with a Helm chart, use the --features option. In the below example, two features are enabled by passing the feature flag names names in a comma separated list:

helm install rancher-latest/rancher \
  --name rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org \
  --set 'extraEnv[0].name=CATTLE_FEATURES' # Available as of v2.3.0
  --set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true' # Available as of v2.3.0

Rendering the Helm Chart for Air Gap Installations

For an air gap installation of Rancher, you need to add a Helm chart repository and render a Helm template before installing Rancher with Helm. For details, refer to the air gap installation documentation.

Here is an example of a command for passing in the feature flag names when rendering the Helm template. In the below example, two features are enabled by passing the feature flag names in a comma separated list:

helm template ./rancher-<VERSION>.tgz --output-dir . \
  --name rancher \
  --namespace cattle-system \
  --set hostname=<RANCHER.YOURDOMAIN.COM> \
  --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
  --set ingress.tls.source=secret \
  --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
  --set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
  --set 'extraEnv[0].name=CATTLE_FEATURES' # Available as of v2.3.0
  --set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true' # Available as of v2.3.0

When installing Rancher with Docker, use the --features option. In the below example, two features are enabled by passing the feature flag names in a comma separated list:

docker run -d -p 80:80 -p 443:443 \
  --restart=unless-stopped \
  rancher/rancher:rancher-latest \
  --features=<FEATURE-FLAG-NAME-1>=true,<FEATURE-NAME-2>=true # Available as of v2.3.0

Enabling Features with the Rancher API

  1. Go to <RANCHER-SERVER-URL>/v3/features.
  2. In the data section, you will see an array containing all of the features that can be turned on with feature flags. The name of the feature is in the id field. Click the name of the feature you want to enable.
  3. In the upper left corner of the screen, under Operations, click Edit.
  4. In the Value drop-down menu, click True.
  5. Click Show Request.
  6. Click Send Request.
  7. Click Close.

Result: The feature is enabled.

Disabling Features with the Rancher API

  1. Go to <RANCHER-SERVER-URL>/v3/features.
  2. In the data section, you will see an array containing all of the features that can be turned on with feature flags. The name of the feature is in the id field. Click the name of the feature you want to enable.
  3. In the upper left corner of the screen, under Operations, click Edit.
  4. In the Value drop-down menu, click False.
  5. Click Show Request.
  6. Click Send Request.
  7. Click Close.

Result: The feature is disabled.