rke2-patcher

rke2-patcher is a tool for SUSE Rancher Prime: RKE2 that helps operators inspect and patch packaged component images. It can be used two ways: as a CLI, run interactively or scripted; or as a Kubernetes controller that reconciles declarative ImagePatch objects, which suits fleets of clusters managed through GitOps.

The primary use case for rke2-patcher is to consume component images that include serious CVE fixes before the next monthly RKE2 release is available. The built-in patching limitations are intentional and are designed to encourage timely RKE2 upgrades, rather than carrying rke2-patcher overrides indefinitely on the same RKE2 version.

rke2-patcher supports Prime clusters only and requires prime: true in the RKE2 configuration.

Each component command (image-cve, image-list, image-patch, and image-reconcile) checks the HelmChart for the selected component and requires global.prime.enabled to be true.

The tool can be used to inspect the images that are currently running in an RKE2 cluster, review newer tags that are available for supported packaged components, patch a component to a newer eligible image, and reconcile those changes after an RKE2 upgrade.

Supported components

  • rke2-traefik

  • rke2-ingress-nginx

  • rke2-coredns

  • rke2-dns-node-cache

  • rke2-metrics-server

  • rke2-flannel

  • rke2-canal-calico

  • rke2-canal-flannel

  • rke2-coredns-cluster-autoscaler

  • rke2-snapshot-controller

Requirements

  • Kubernetes API access (in-cluster service account or kubeconfig).

  • Permissions to list HelmChart resources for Prime-cluster checks.

  • Access to the configured image registry endpoint.

  • Permissions to create scanner Jobs and read logs for CVE scans.

  • Permissions to create or update HelmChartConfig objects for patch and reconcile operations.

Limitations

  • rke2-patcher supports Prime clusters only and requires prime: true in the RKE2 configuration.

  • Patching is limited to the supported component list shown on this page.

  • For most components, image-patch enforces a 45-day patch window from the RKE2 release date. Tags outside that window are blocked until you upgrade RKE2.

  • rke2-ingress-nginx is exempt from the 45-day patch window check.

  • If stale patch state exists from a previous RKE2 version, new patch operations are blocked until you run image-reconcile.

  • After an RKE2 upgrade, all previously patched components must be reconciled before applying new patches.

  • Patching and reconciliation require Kubernetes API access and permissions to update HelmChartConfig resources.

Installation

You can use rke2-patcher as a locally built CLI binary or as a controller that reconciles ImagePatch objects; see Declarative mode: ImagePatch controller.

The rke2-patcher binary can be found in the Prime Artifacts URL.

rke2-patcher CLI

rke2-patcher --version
rke2-patcher --config
rke2-patcher image-cve <component> [--json]
rke2-patcher image-list <component> [--with-cves] [--verbose] [--json]
rke2-patcher image-patch <component> [--tag TAG] [--dry-run] [--yes|-y]
rke2-patcher image-reconcile <component> [--yes|-y]

rke2-patcher --version

Print the rke2-patcher version. When Kubernetes access is available, this command also reports the connected cluster version.

rke2-patcher --version

rke2-patcher --config

Show the effective runtime configuration used by rke2-patcher, including the configured registry, scanner mode, scanner image, scanner namespace, scanner timeout, and patch state ConfigMap.

rke2-patcher --config

rke2-patcher image-cve <component>

Show the CVEs for the image currently running for the selected component.

By default, image-cve starts an in-cluster scanner Job that runs Trivy. When RKE2_PATCHER_SCANNER_MODE=local is set, the command uses a local scanner instead.

Text output lists each finding’s CVE ID and severity, with CRITICAL findings first. The JSON output includes the same severity information.

Use this command when you want to inspect the current risk profile of a deployed component image before deciding whether to patch.

Add --json to return the component, scanned image, scanner, CVE count, and findings as JSON. Each finding includes its CVE ID and severity.

rke2-patcher image-cve rke2-traefik --json

Scanner progress is written to stderr so standard output remains valid JSON for automation.

rke2-patcher image-cve demo

rke2-patcher image-list <component>

List the image tags available for a supported component.

The image-list command can optionally scan selected tags for CVEs:

  • --with-cves: scan the current, previous, and eligible newer tags

  • --verbose: show the full CVE list for each scanned tag

  • --json: return component and repository details, running images, and selected tags as JSON; with --with-cves, include each scanned tag’s CVE count and complete findings

CVEs are limited to CRITICAL and HIGH severity and are displayed with CRITICAL findings first. JSON includes each finding’s ID and severity, and always includes the complete list regardless of --verbose.

Use this command to compare the currently running tag with newer eligible tags before applying a patch.

rke2-patcher image-list rke2-traefik --with-cves --json
rke2-patcher image-list demo

rke2-patcher image-patch <component>

Patch a supported component to the next eligible image tag.

The command creates or updates a HelmChartConfig in the cluster and records patch state so the change can be reconciled later.

image-patch supports the following options:

  • --tag TAG: patch to this exact tag instead of automatically selecting the next tag

  • --dry-run: print the generated HelmChartConfig without applying it

  • --yes or -y: automatically approve prompts

For example, to preview an exact eligible tag from image-list:

rke2-patcher image-patch rke2-traefik --tag TAG_FROM_IMAGE_LIST --dry-run

An explicitly selected tag must exist in the configured registry, be newer than the running tag, and be on the same major and minor release line. The command also enforces the patch window rules for the target component. If a target image falls outside the allowed window, rke2-patcher instructs you to upgrade RKE2 first.

rke2-patcher image-patch demo

rke2-patcher image-reconcile <component>

Reconcile or revert a previously applied patch for a supported component.

This command is typically used after an RKE2 upgrade, when an older patch state must be cleared before patching can be used again.

image-reconcile supports the following option:

  • --yes or -y: automatically approve prompts

When reconciliation succeeds, rke2-patcher removes the patcher-managed image override values and lets RKE2 return to the packaged chart defaults.

rke2-patcher image-reconcile demo

Typical workflow

  1. Check current status and available tags.

  2. Patch one or more supported components.

  3. Upgrade RKE2 when needed.

  4. Run image-reconcile for previously patched components.

For complete behavior and command details, refer to the upstream project documentation: https://github.com/rancher/rke2-patcher.

Declarative mode: ImagePatch controller

Besides the CLI, rke2-patcher controller runs a Kubernetes controller that reconciles ImagePatch objects (patcher.rke2.cattle.io/v1alpha1, cluster-scoped). This suits fleets of clusters: distribute ImagePatch objects (for example with Fleet) and every cluster enforces its own guardrails, with no CLI commands to run by hand.

The CLI and the controller are exclusive modes on the same cluster. While any ImagePatch object exists, rke2-patcher image-patch refuses to run. image-reconcile keeps working in either mode, since it only reverts patches made with the CLI.

Installing the controller

Requirements:

  • An RKE2 Prime cluster (prime: true) and kubectl plus helm with cluster-admin access to it.

  • An rke2-patcher image that contains the controller. Release images are published to the Rancher Prime registry (registry.rancher.com/rancher/rke2-patcher).

Install the chart into its own namespace:

helm upgrade --install rke2-patcher oci://registry.rancher.com/rancher/charts/rke2-patcher \
  --namespace rke2-patcher --create-namespace \
  --set image.repository=registry.rancher.com/rancher/rke2-patcher \
  --set image.tag=<version>

Use the rke2-patcher namespace: the chart’s templates expect it, and the controller uses it for leader election. The chart installs the ImagePatch CRD (imagepatches.patcher.rke2.cattle.io), a ServiceAccount with a ClusterRole/ClusterRoleBinding, and a Deployment on control-plane nodes running rke2-patcher controller with leader election. The same image also ships the CLI, so kubectl exec still works.

Verify it is running:

kubectl -n rke2-patcher rollout status deployment/rke2-patcher
kubectl get crd imagepatches.patcher.rke2.cattle.io

Using ImagePatch objects

apiVersion: patcher.rke2.cattle.io/v1alpha1
kind: ImagePatch
metadata:
  name: rke2-coredns          # must equal spec.component (one ImagePatch per component)
spec:
  component: rke2-coredns
  tag: v1.14.7-build20261020  # exact tag, as with `image-patch --tag`
  upgradePolicy: Manual       # Manual (default) | AutoRevert
kubectl get imagepatches      # TAG, APPLIED, BASELINE, READY, REASON

The same guardrails as image-patch apply: Prime only, tag newer than the bundled tag, same minor release line, the 45-day patch window (rke2-ingress-nginx exempt), and no patches while stale patches from a previous RKE2 version exist. Violations surface as a Blocked condition with a reason, for example OutsidePatchWindow, MinorVersionChange, TagNotFound, NotNewer, NotPrime, StalePatchesExist, or ConflictingOverride; nothing is written to the cluster.

  • Setting spec.tag to the bundled tag reverts the patch but keeps the ImagePatch object (Ready=True, reason AtBaseline).

  • Deleting an ImagePatch reverts the patch: a finalizer strips the patcher-managed values before the object is removed.

  • If the patcher-managed values are edited or removed by hand on the underlying HelmChartConfig, the controller puts spec.tag back (DriftCorrected event).

  • If the bundled tag ever becomes newer than the applied spec.tag, the patch is reverted (Blocked, reason NotNewer) instead of keeping an older image.

After an RKE2 upgrade

  • upgradePolicy: Manual (default): nothing is touched. The ImagePatch becomes Stale; delete it to revert the component to the image bundled with the new release.

  • upgradePolicy: AutoRevert: the patch is reverted automatically to the newly bundled image, even if spec.tag would still be valid on the new release. The object stays, with Ready=False and reason RevertedAfterUpgrade. Set a new spec.tag to patch again.

Airgap support

Only the rke2-patcher CLI is supported in Airgap environments

rke2-patcher can be used in airgapped environments when required artifacts are mirrored and reachable inside your private network.

To use rke2-patcher in airgap environments:

  • Mirror supported component images and eligible tags to an internal registry.

  • Set RKE2_PATCHER_REGISTRY to your internal registry endpoint.

  • Ensure the cluster can reach the internal registry endpoint.

For CVE scanning in airgap environments, use one of these approaches:

  • Cluster scanning mode:

    • Mirror the scanner image used by the in-cluster scan job.

    • Ensure scan namespaces and required permissions are available.

    • The scanner Job downloads and decompresses the OpenVEX report from the Rancher VEXHub URL, so cluster-mode CVE scans require outbound access to that endpoint.

  • Local scanning mode (RKE2_PATCHER_SCANNER_MODE=local):

    • Install a supported local scanner binary (trivy or grype) on the host OS.

    • Pre-stage the Rancher OpenVEX file at $HOME/rke2-patcher-cache/vex/rancher.openvex.json.

    • The patcher downloads and decompresses the compressed report automatically when internet access is available. When pre-staging it for an air-gapped scan, store the decompressed JSON at the path above.

    • Compressed report source: https://github.com/rancher/vexhub/raw/refs/heads/main/reports/rancher.openvex.json.gz

Example command to pre-stage the OpenVEX file:

mkdir -p "$HOME/rke2-patcher-cache/vex"
curl -fsSL https://github.com/rancher/vexhub/raw/refs/heads/main/reports/rancher.openvex.json.gz \
	| gzip -dc > "$HOME/rke2-patcher-cache/vex/rancher.openvex.json"

Examples:

RKE2_PATCHER_REGISTRY=registry.example.local:5000 \
	rke2-patcher image-list rke2-traefik
RKE2_PATCHER_SCANNER_MODE=local \
	RKE2_PATCHER_REGISTRY=registry.example.local:5000 \
	rke2-patcher image-cve rke2-traefik

With these prerequisites in place, image-patch, image-reconcile, and image-list without --with-cves can run without direct internet access. Cluster-mode CVE scans require access to the VEX report URL.