Illumina Innovates with Rancher and Kubernetes
Available as of v2.3.0
The RKE metadata feature allows you to provision clusters with new versions of Kubernetes as soon as they are released, without upgrading Rancher. This feature is useful for taking advantage of patch versions of Kubernetes, for example, if you want to upgrade to Kubernetes v1.14.7 when your Rancher server originally supported v1.14.6.
Note: The Kubernetes API can change between minor versions. Therefore, we don’t support introducing minor Kubernetes versions, such as introducing v1.15 when Rancher currently supports v1.14. You would need to upgrade Rancher to add support for minor Kubernetes versions.
Rancher’s Kubernetes metadata contains information specific to the Kubernetes version that Rancher uses to provision RKE clusters. Rancher syncs the data periodically and creates custom resource definitions (CRDs) for system images, service options and addon templates. Consequently, when a new Kubernetes version is compatible with the Rancher server version, the Kubernetes metadata makes the new version available to Rancher for provisioning clusters. The metadata gives you an overview of the information that the Rancher Kubernetes Engine (RKE) uses for deploying various Kubernetes versions.
This table below describes the CRDs that are affected by the periodic data sync.
Note: Only administrators can edit metadata CRDs. It is recommended not to update existing objects unless explicitly advised.
<RANCHER_SERVER_URL>/v3/rkek8ssystemimages
kube-api
scheduler
kubelet
kube-proxy
kube-controller-manager
<RANCHER_SERVER_URL>/v3/rkek8sserviceoptions
metrics-server
nginx-ingress
<RANCHER_SERVER_URL>/v3/rkeaddons
Administrators might configure the RKE metadata settings to do the following:
The option to refresh the Kubernetes metadata is available for administrators by default, or for any user who has the Manage Cluster Drivers global role.
To force Rancher to refresh the Kubernetes metadata, a manual refresh action is available under Tools > Drivers > Refresh Kubernetes Metadata on the right side corner.
Only administrators can change these settings.
The RKE metadata config controls how often Rancher syncs metadata and where it downloads data from. You can configure the metadata from the settings in the Rancher UI, or through the Rancher API at the endpoint v3/settings/rke-metadata-config.
v3/settings/rke-metadata-config
To edit the metadata config in Rancher,
You can optionally fill in the following parameters:
refresh-interval-minutes
url
branch
If you don’t have an air gap setup, you don’t need to specify the URL or Git branch where Rancher gets the metadata, because the default setting is to pull from Rancher’s metadata Git repository.
However, if you have an air gap setup, you will need to mirror the Kubernetes metadata repository in a location available to Rancher. Then you need to change the URL and Git branch in the rke-metadata-config settings to point to the new location of the repository.
rke-metadata-config
Rancher relies on a periodic refresh of the rke-metadata-config to download new Kubernetes version metadata if it is supported with the current version of the Rancher server. For a table of compatible Kubernetes and Rancher versions, refer to the service terms section.
If you have an air gap setup, you might not be able to get the automatic periodic refresh of the Kubernetes metadata from Rancher’s Git repository. In that case, you should disable the periodic refresh to prevent your logs from showing errors. Optionally, you can configure your metadata settings so that Rancher can sync with a local copy of the RKE metadata.
To sync Rancher with a local mirror of the RKE metadata, an administrator would configure the rke-metadata-config settings by updating the url and branch to point to the mirror.
After new Kubernetes versions are loaded into the Rancher setup, additional steps would be required in order to use them for launching clusters. Rancher needs access to updated system images. While the metadata settings can only be changed by administrators, any user can download the Rancher system images and prepare a private Docker registry for them.
rancher-images.txt
Result: The air gap installation of Rancher can now sync the Kubernetes metadata. If you update your private registry when new versions of Kubernetes are released, you can provision clusters with the new version without having to upgrade Rancher.