This is unreleased documentation for Admission Controller 1.40-dev.

Upgrade path

Kubewarden Admission Controller stack versioning

The Admission Controller project uses Semantic versioning to define the "stack" version of all its components: the version follows the MAJOR.MINOR.PATCH pattern. The supported version is the latest release.

The Admission Controller components that follow the rules for the "stack" version are:

  • admission-controller Helm chart, in their appVersion field.

  • policy-server image tag for manually deployed ones. The resource for the default one is already managed by the kubewarden-defaults chart.

  • kwctl binary.

The Admission Controller was shipped as 3 Helm charts (kubewarden-crds, kubewarden-controller, kubewarden-defaults) until v1.36 inclusive. Please browse previous documentation versions for information on them.

From v1.37 onwards, it is shipped as a unique Helm chart, admission-controller.

Stack version compatibility among components

The admission-controller Helm chart, any manually deployed policy-server image, and kwctl should run the same MAJOR.MINOR.PATCH version.

Therefore, if the admission-controller version running is 1.1.2, the policy-servers and kwctl version in use should be 1.1.2 as well.

Helm chart versions

Helm charts define the version field and the appVersion field. The appVersion field informs of the Admission Controller "stack" version as mentioned before. The version field also follows semantic versioning and describes backwards-compatible changes in the chart templates and values.yaml.

Upgrade paths

When upgrading components, you can upgrade multiple PATCH stack versions in a single operation. However, the upgrade of multiple MAJOR or MINOR stack versions in a single upgrade is not supported.

The Admission Controller went over a migration, from v1.36 inclusive (3 Helm charts: kubewarden-crds, kubewarden-controller, kubewarden-defaults) to v1.37 onwards (1 Helm chart: admission-controller).

Please see the migration how-to.

For example, you can upgrade components from version 1.1.10 to 1.1.nn in a single upgrade. But the upgrade from 1.1.10 to 1.5.0 isn’t supported. In these cases, you must upgrade individually to each MAJOR/MINOR version between the two versions. Therefore, it’s necessary to upgrade 1.1.10 to 1.2.0 then 1.3.0 then 1.4.0 and finally to 1.5.0. To upgrade one MAJOR version to another, you need to apply all the MINOR updates between the two MAJOR versions.

flowchart LR; accTitle: Upgrade path support graph accDescr: A diagram showing recommended and supported upgrade paths for {short-project-name}. 1.0.0(1.0.0)-->1.0.1(1.0.1); 1.0.1-->1.0.2(1.0.2); 1.0.2-->1.1.0(1.1.0); 1.1.0-->1.1.2(1.1.2); 1.1.0-->1.1.1(1.1.1); 1.1.1-->1.1.2; 1.1.2-->|Not recommended|1.2.0(1.2.0); 1.0.2-->|Not supported|1.2.0(1.2.0); 1.1.2-->1.2.1(1.2.1); 1.2.0-->1.2.1; linkStyle 6 color:brown,stroke-width:2px,stroke-dasharray: 3 5 linkStyle 7 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.

v1.38 to v1.39

  • The controller creates its certificates and its two webhook configurations. The Helm chart no longer contains them. For more information, refer to Certificate rotation.

  • The chart has a pre-upgrade hook. The hook is a Job that runs the controller with --mode=pre-upgrade before Helm changes the release. It adds helm.sh/resource-policy: keep and Prune=false in argocd.argoproj.io/sync-options to these objects:

    • The secrets kubewarden-ca, kubewarden-webhook-server-cert, and kubewarden-audit-scanner-client-cert.

    • The webhook configurations kubewarden-controller-validating-webhook-configuration and kubewarden-controller-mutating-webhook-configuration.

    Helm does not delete these objects, and Argo CD does not prune them. After the upgrade, the controller uses the same root CA.

  • If you use Argo CD, refer to Upgrade from an earlier version with Argo CD.

Do not use helm upgrade --no-hooks for the upgrade to v1.39. This option skips the pre-upgrade hook. Then Helm deletes the secrets and the webhook configurations of the controller. The upgrade starts a new controller pod, and its init container creates them again with a new root CA. Until the old controller pods stop, you cannot create or change policies and PolicyServer resources. In a test with one replica, this took about 15 seconds. The policies with failurePolicy: Fail reject requests for about one minute. If a webhook configuration of the controller is still missing after the upgrade, refer to A deleted webhook configuration of the controller.

v1.37 to v1.38

  • Namespaced policies (AdmissionPolicy and AdmissionPolicyGroup) can target only the resources that are part of an allow list. The Helm value namespacedPoliciesAllowedResources sets this list. After the upgrade, a policy that targets a resource that is not in the default allow list gets the rejected status. The controller also removes the webhook of this policy. See Namespaced policy allowed resources.

  • The policy-server applies a default memory limit of 256 MiB to the linear memory of each policy. If a policy needs more memory, increase the limit the KUBEWARDEN_POLICY_MEMORY_LIMIT environment variable. See Policy memory limit.

Upgrade order

Admission Controller users should upgrade the stack starting with the admission-controller Helm chart. After that, upgrade the policy-server (via admission-controller Helm chart for the default one, or bumping the images of custom ones) and kwctl.

Downgrades

Downgrades are not supported, and Admission Controller doesn’t test them. Nevertheless, there’s a reasonable expectation that they should work.

SDKs, policies

Policy SDKs for the different languages and policies maintained by the Admission Controller team follow their own semantic versioning. Admission Controller supports the latest release. There is no need for an upgrade path for them, just a bump to the latest release.

Changes to the Admission Controller stack may mean that policies and SDKs receive updates to use the latest Admission Controller features. Admission Controller takes care to perform these updates in a backwards-compatible manner.

For example, a Admission Controller minor version adding support for Audit Scanner (v1.7.0) means that policies gained a new spec.backgroundAudit field. This is optional, backwards-compatible and set to true by default.