Version specific notes

As the capabilities of the Kubernetes agent evolve and change, this page will document major version specific functionality that is different from the current major version.

Version 2

NFS storage

By default, the Kubernetes agent Helm chart will set up an NFS server suitable for use by the agent inside your cluster. The server runs as a StatefulSet in the same namespace as the Kubernetes agent, and uses EmptyDir storage, as the working files of the agent are not required to be long-lived.

This NFS server is referenced in the StorageClass that the Kubernetes agent and the script pod use. This StorageClass will then instruct the NFS CSI Driver to mount the server as directed.

This default implementation is made to let you try the Kubernetes agent without worrying about installing a ReadWriteMany compatible StorageClass yourself. There are some drawbacks to this approach:

Privileges

The NFS server requires privileged access when running as a container, which may not be permitted depending on the cluster configuration. Access to the NFS pod should be kept to a minimum since it enables access to the host.

Reliability

Since the NFS server runs inside your Kubernetes cluster, upgrades and other cluster operations can cause the NFS server to restart. Due to how NFS stores and allows access to shared data, script pods will not be able to recover cleanly from an NFS server restart. This causes running deployments to fail when the NFS server is restarted.

If you have a use case that can’t tolerate occasional deployment failures, it’s recommended to provide your own StorageClass instead of using the default NFS implementation.

NFS CSI driver

If no Storage Class name is set, the default NFS storage pod will be used. This runs a small NFS pod next to the agent pod and provides shared storage to the agent and script pods.

A requirement of using the NFS pod is the installation of the NFS CSI Driver. This can be achieved by executing the following helm command in a terminal connected to the target Kubernetes cluster.

helm upgrade --install --atomic --repo https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/charts --namespace kube-system --version "v4.*.*" csi-driver-nfs csi-driver-nfs

helm repo update

NFS Server Pod Permissions

If you have not provided a predefined storageClassName for persistence, an NFS pod will be used. This NFS Server pod requires privileged access.

Migrating from NFS storage to a custom StorageClass

If you installed the Kubernetes agent using the default NFS storage, and want to change to a custom StorageClass instead, simply rerun the installation Helm command with specified values for persistence.storageClassName.

The following steps assume your Kubernetes agent is in the octopus-agent-nfs-to-pv namespace:

Step 1: Find your Helm release

Take note of the current Helm release name and Chart version for your Kubernetes agent by running the following command:

helm list --namespace octopus-agent-nfs-to-pv

The output should look like this:

In this example, the release name is nfs-to-pv while the chart version is 1.0.1.

Step 2: Change Persistence

Run the following command (substitute the placeholders with your own values):

helm upgrade --reuse-values --atomic --set persistence.storageClassName="<storage class>" --namespace <namespace> --version "<chart version>" <release name> oci://registry-1.docker.io/octopusdeploy/kubernetes-agent`

Here is an example to convert the nfs-to-pv Helm release in the octopus-agent-nfs-to-pv namespace to use the octopus-agent-nfs-migration StorageClass:

helm upgrade --reuse-values --atomic --set persistence.storageClassName="octopus-agent-nfs-migration" --namespace octopus-agent-nfs-to-pv --version "1.0.1" nfs-to-pv oci://registry-1.docker.io/octopusdeploy/kubernetes-agent`

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Friday, May 1, 2026