How to set the metadata config using the CATTLE prefixed extra environment variable

This document (000020811) is provided subject to the disclaimer at the end of this document.

Environment

Rancher v2.6.x, v2.7.x and v2.8.x

Situation

- Rancher embeds the RKE metadata feature (rke-metadata-config) to synchronize Kubernetes version metadata periodically, inline with the desired refresh interval. This in turn enables users to explore up-to-date Kubernetes patch versions for RKE-provisioned downstream clusters launched and managed by Rancher as soon as they are released. One of the benefits is that Rancher does not need to be upgraded, allowing administrators to set a Kubernetes patch version that is higher than the latest supported version that originally shipped with a Rancher release at the time of installation.

- In some air-gapped environments the RKE metadata setting can be modified to meet security and compliance concerns. In addition users will be able to manage these settings through the Rancher helm values file on installation and/or upgrades.

Resolution

A) Method 1: Customizing the Metadata Settings via Rancher UI

The metadata config setting can be found in the UI under Global Settings > Settings > rke-metadata-config.
In an open environment (with internet access), the default metadata config for Rancher v2.5.x and 2.6.x is to pull/refresh the Kubernetes metadata via a JSON file in the Rancher Git repository.

Note: In air-gapped environments, this works differently, i.e. only those Kubernetes versions available and included at the time of the Rancher release will be selectable. To take advantage of later Kubernetes patch versions, the Kontainer Driver Metadata from the Kubernetes metadata repository will need to be mirrored in a location that is accessible to air-gapped installations of Rancher. The default rke-metadata-config URL can be modified to point to the local mirror. Updated system images will also be required.

B) Method 2: Customizing the Metadata Settings via Helm

Using Helm, the rke-metadata-config settings can be passed with --set, using the CATTLE_ prefixed extra environment variables.
The example command shown below makes use of the current Rancher release values exported to a file, and the file is referenced during a Helm upgrade.

helm upgrade rancher rancher-stable/rancher   --namespace cattle-system  -f rancher-values.yaml --version <version> --set 'extraEnv[0].name=CATTLE_RKE_METADATA_CONFIG' --set 'extraEnv[0].value=\{\"refresh-interval-minutes\":\"1450"\,\"url"\:\"https://releases.rancher.com/kontainer-driver-metadata/release-v2.6/data.json\"}'

Alternatively, it is also possible to supply the necessary arguments in the values file.

extraEnv:
- name: CATTLE_RKE_METADATA_CONFIG
  value: '{"refresh-interval-minutes":"1450","url":"https://releases.rancher.com/kontainer-driver-metadata/release-v2.6/data.json"}'

Please see below example screenshot taken from the Global Settings > Settings menu in the Rancher UI after applying the rke-metadata-config setting using Helm.

NOTE:

When upgrading Rancher to the next major/minor release (e.g 2.7.x or 2.8.x), please ensure that the RKE metadata setting matches the release in use, i.e. release-v2.7 or release-v8.0

Status

Top Issue

Additional Information

Further reading
Please refer to the following Rancher documentation pages to find out more information.

Disclaimer

This Support Knowledgebase provides a valuable tool for SUSE customers and parties interested in our products and solutions to acquire information, ideas and learn from one another. Materials are provided for informational, personal or non-commercial use within your organization and are presented "AS IS" WITHOUT WARRANTY OF ANY KIND.