This is unreleased documentation for Network Enforcer 0.4-dev.

Upgrade path

Versioning

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

One deliverable follows this version: the network-enforcer Helm chart, in its appVersion field. The controller image carries this version as its tag. Network Enforcer has no separate CLI or plugin to keep in step.

Helm chart versions

A Helm chart has two version fields. The appVersion field holds the Network 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.

The chart also ships two third-party images that follow their own versions. One is fluent-bit, with the Istio provider. The other is the OpenTelemetry collector, with the default telemetry strategy. A chart upgrade can move these images. The chart version field records such a change.

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.3.0 to 0.3.2 in one step. You cannot upgrade from 0.2.0 to 0.4.0 in one step. Upgrade from 0.2.0 to 0.3.x first, then from 0.3.x to 0.4.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 Network Enforcer. 0.2.0(0.2.0)-->0.2.1(0.2.1); 0.2.1-->0.3.0(0.3.0); 0.3.0-->0.3.1(0.3.1); 0.2.0-->0.3.0; 0.3.1-->0.4.0(0.4.0); 0.3.0-->|Not recommended|0.4.0; 0.2.1-->|Not supported|0.4.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

0.3.x to 0.4.0

  • WorkloadNetworkPolicy and WorkloadNetworkPolicyProposal require spec.targetRef and spec.direction. The Kubernetes backend requires spec.kubernetes.policyTypes to contain only that direction. Istio accepts Ingress only.

  • Only one policy can target a workload and direction in a namespace. Platform and application teams must combine their rules in that policy.

  • A new validating webhook fails closed. An outage blocks policy creates and updates, but not proposal writes, policy deletes, or status updates. The chart requires cert-manager and its CSI driver for webhook certificates.

  • The controller checks the policy selector against workload pod templates. Overlapping selectors produce Ready=False with reason SelectorOverlapsWorkload. They can still affect other workloads.

Upgrade order

Upgrade the network-enforcer Helm chart. There is no other component to upgrade. The chart upgrades the controller and, with the Istio provider, the fluent-bit DaemonSet together.

The native policy objects that the controller rendered stay in place during the upgrade. The data plane keeps enforcing them while the controller pod restarts. See Architecture.

Downgrades

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

Policies

A WorkloadNetworkPolicy carries no version of its own. It holds a mode, a backend, a target workload, a direction, and an allow-list. It stays in the cluster across Network Enforcer upgrades. A breaking change can require manifest updates, as described in Breaking changes. The spec.backend field cannot change after creation. See spec.backend is immutable.