Calamari Image Volume

Calamari is the command-line tool invoked by the Kubernetes agent during deployments. Currently Octopus Server, at the start of the deployment, verifies that the correct version of Calamari is present on the shared storage volume.

When a new version of Calamari is required, this is packaged by Octopus Server, sent to the agent, and then unpacked into the shared volume. Then, during deployment, Calamari is executed from the shared filesystem.

When the Calamari Image Volume feature is enabled, the agent instead mounts Calamari as a read-only Kubernetes Image Volume directly into each script pod.

Benefits

Eliminates the Calamari transfer step: When Octopus Server ships a new version of Calamari, there is no longer a bundle transfer and unpack step. The cluster pulls the updated image through its normal container image pull mechanism.
Node-level caching: The Calamari image is cached at the node level by the container runtime, consistent with how all other container images are managed.
Increased performance: As Calamari is no longer being executed from the shared storage, performance is improved.
Reduced persistent storage: Calamari is no longer stored on the shared persistent volume. Only workspace data and user packages remain on shared storage.

Requirements

Kubernetes: 1.35 or later. Image Volumes require the ImageVolume feature gate, which is enabled by default from Kubernetes 1.35 (Beta) and is GA from 1.36. Clusters running an older version will fall back to the existing transfer-and-unpack mechanism automatically and log a warning.
Kubernetes agent: v3.5.0
Octopus Server: 2026.3.892 or later

Enabling the feature

Calamari Image Volume is opt-in. To enable it, set the following value in the Helm chart:

scriptPods:
  calamariImageVolume:
    enabled: true

Or as a --set flag in your Helm command:

--set scriptPods.calamariImageVolume.enabled=true

Using a private registry

By default, the Calamari image is pulled from the octopusdeploy repository on Docker Hub. If your cluster cannot access Docker Hub directly, you must mirror the Calamari image to your own registry and update the repository value accordingly:

scriptPods:
  calamariImageVolume:
    enabled: true
    image:
      repository: "your-registry.example.com/octopusdeploy"
      pullPolicy: IfNotPresent

When using a private registry, you are responsible for keeping the mirrored Calamari image up to date as new versions are released.

Changing the repository

The structure of the Calamari image name is octopusdeploy/{CalamariTool}:{Version} where the {CalamariTool} and {Version} are dictated and provided by Octopus Server during deployment execution.

This means that the scriptPods.calamariImageVolume.image.repository should not include the {CalamariTool} and {Version} part of image name.

For example, if your mirrored Calamari image names are like your-registry.example.com/octopusdeploy/{CalamariTool}, then the scriptPods.calamariImageVolume.image.repository should be your-registry.example.com/octopusdeploy.

Fallback behavior

If Calamari Image Volume is enabled but the cluster is running Kubernetes 1.34 or earlier, the agent will log a warning to the task log and fall back to the existing Octopus Server delivery mechanism.