This is unreleased documentation for Runtime Enforcer 0.12-dev.

Upgrade path

Versioning

Runtime Enforcer uses semantic versioning. A version follows the MAJOR.MINOR.PATCH pattern. The supported version is the latest release.

Two deliverables follow this version:

  • The runtime-enforcer Helm chart, in its appVersion field. The controller, the agent, and the debugger images carry this version as their tag.

  • The kubectl runtime-enforcer plugin binary.

Version compatibility among components

The Helm chart appVersion and the kubectl runtime-enforcer plugin must run the same MAJOR.MINOR.PATCH version. If the chart runs appVersion 0.10.1, install the plugin binary from the v0.10.1 release.

Helm chart versions

A Helm chart has two version fields. The appVersion field holds the Runtime Enforcer version described above. The version field is the version of the chart itself. It also follows semantic versioning, and it describes changes to the chart templates and to values.yaml.

The two fields do not move together. When you plan an upgrade, read the appVersion of the target chart.

Upgrade paths

You can upgrade across several PATCH versions in one operation. You cannot upgrade across more than one MINOR or MAJOR version in one operation.

For example, you can upgrade from 0.10.0 to 0.10.1 in one step. You cannot upgrade from 0.9.0 to 0.11.0 in one step. Upgrade from 0.9.0 to 0.10.x first, then from 0.10.x to 0.11.0. To move across a MAJOR version, apply every MINOR version between the two.

flowchart LR; accTitle: Upgrade path support graph accDescr: A diagram showing supported and unsupported upgrade paths for Runtime Enforcer. 0.9.0(0.9.0)-->0.9.1(0.9.1); 0.9.1-->0.10.0(0.10.0); 0.10.0-->0.10.1(0.10.1); 0.9.0-->0.10.0; 0.10.1-->0.11.0(0.11.0); 0.10.0-->|Not recommended|0.11.0; 0.9.1-->|Not supported|0.11.0; linkStyle 5 color:brown,stroke-width:2px,stroke-dasharray: 3 5 linkStyle 6 color:red,stroke-width:2px,stroke-dasharray: 3 5
Figure 1. Example upgrade path support graph

Breaking and important changes between versions

This section records breaking changes and other important changes that you must review before you upgrade to a specific version.

v0.10 to v0.11

  • The Helm chart no longer deploys an OpenTelemetry collector. The upgrade removes the collector and its Prometheus endpoint on port 9090. The telemetry export is then off until you set global.otel.endpoint. To keep the violation events and the runtime_enforcer_violations_total counter, deploy your own collector before the upgrade. For more information, refer to Export telemetry to an OpenTelemetry collector.

  • The global.otel block replaces the telemetry block:

    • global.otel.endpoint replaces telemetry.externalCollector.endpoint.

    • global.otel.caSecretName replaces telemetry.externalCollector.otelCollectorCertificateSecret.

    • global.otel.clientCertificateSecretName replaces telemetry.externalCollector.otelCollectorClientCertificateSecret.

    • The chart no longer has the telemetry.collectorStrategy, telemetry.externalCollector.protocol, and telemetry.defaultCollector values. The export uses gRPC.

  • The telemetry endpoint must be a URL that starts with http:// or https://. With a value such as collector:4317, the controller and the agent do not start.

  • An https:// endpoint without a CA Secret trusts only public certificate authorities. In v0.10, the chart turned off TLS verification when you set no CA Secret. If a private CA signed the certificate of the collector, set global.otel.caSecretName.

  • The chart has a new global block that holds the values for all workloads. These values moved or changed:

    • global.imagePullSecrets replaces the top-level imagePullSecrets.

    • controller.podDisruptionBudget replaces controller.pdb. The new block has no enabled key. Set minAvailable or maxUnavailable in it.

    • extraEnv replaces env in the controller, agent, and debugger blocks.

    • The chart no longer has the controller.args and agent.args values.

    • image.registry holds the registry of each image, for example ghcr.io. image.repository holds the path without the registry, for example kubewarden/runtime-enforcer/agent.

    • image.pullPolicy is empty by default. The chart then uses global.imagePullPolicy.

    For more information, refer to The layers of the chart values.

  • The chart gives no error for a value that it does not know. After the upgrade, an old value has no effect. Update your Helm values file before you upgrade.

  • The controller no longer serves a metrics endpoint on port 8443. The chart no longer creates the metrics-auth and metrics-reader ClusterRoles.

Do not use helm upgrade --reuse-values for the upgrade to v0.11. With this option, Helm keeps every value of the old release, and this includes the image tags. The pods then run the v0.10 images with the v0.11 chart. Give your updated values file to Helm with the -f option instead.

Upgrade order

Upgrade the runtime-enforcer Helm chart first. The chart upgrades the controller, the agent, and the debugger together. Then install the kubectl runtime-enforcer plugin binary from the same release.

The agent DaemonSet uses a rolling update with a surge. The new agent pod on a node loads every policy and binds every running pod before the old pod stops. Protection does not lapse during the upgrade. See Architecture for the sequence.

Downgrades

Runtime Enforcer does not support downgrades, and the project does not test them.

Policies

A WorkloadPolicy carries no version of its own. It holds a mode and an allow-list, and it stays in the cluster across Runtime Enforcer upgrades. You do not rewrite or re-apply your policies when you upgrade.