Add volumes and files

The portal shows a component's volumes but does not edit them. Volumes are declared through the CLI or the API — or in a blueprint template — as part of the component, and need containerinstance/write.

Declare a volume

A component's volumes list holds up to 8 volumes. Each has a name — lowercase letters, digits and hyphens, starting with a letter, unique in the component — and exactly one of these:

• persistent — a disk that survives restarts and re-deploys.
  • size — how big, as a Kubernetes quantity such as 10Gi. It cannot be changed once the volume exists.
  • retainOnDelete — true by default: the disk is kept when the instance or the component is deleted. false deletes it with them.
  • fsGroup — the group that owns the disk's files, for images that do not run as root. The component uses the first one its persistent volumes set, and 65532 when none sets one.
• emptyDir — scratch space shared by the component's containers and discarded with the pod. sizeLimit caps it, for example 1Gi.
• files — files whose content you write into the instance's configuration.
  • content — a map from file name to the file's text. File names use letters, digits, ., _ and -.
  • sensitive — true stores the files as a secret and hides their content when the instance is read.

A component with a persistent volume runs 0 or 1 replicas and cannot autoscale.

Mount it into a container

A volume is only visible in the containers that mount it. Each container's mounts list names:

• volume — a volume of the same component.
• path — where it appears in the container: an absolute path, not /, without .., not under /proc, /sys, /dev, /var/run or /etc/kubernetes, and used once per container.
• subPath — optional: mount one file of the volume instead of all of it. This lets a single configuration file sit next to the files the image already has in that directory.
• readOnly — optional, false by default.

Update the instance

A component is replaced as a whole when the instance is updated, so the file carries every component in full — the containers, ports, variables and commands you keep as well as the volumes you add. Start from the instance as it is: stsh ci get web -o json shows its components. Put only components in the file:

{
  "components": [
    {
      "name": "main",
      "replicas": 1,
      "startupOrder": 1,
      "computePlan": "small",
      "containers": [
        {
          "name": "main",
          "image": "nginx",
          "tag": "1.27",
          "ports": [{ "name": "http", "port": 80, "protocol": "TCP" }],
          "mounts": [
            { "volume": "config", "path": "/etc/nginx/conf.d/default.conf", "subPath": "default.conf", "readOnly": true },
            { "volume": "site", "path": "/usr/share/nginx/html" }
          ]
        }
      ],
      "volumes": [
        { "name": "config", "files": { "content": { "default.conf": "server { listen 80; root /usr/share/nginx/html; }" } } },
        { "name": "site", "persistent": { "size": "5Gi" } }
      ]
    }
  ]
}

stsh ci update web -g my-resource-group --file components.json

Saving replaces the pods of every component whose configuration changed, file content included.

Limits for files

• At most 16 files in one files volume.
• At most 900 KiB of names and content in one volume, and 1 MiB across all files volumes of the instance.
• Content is text.

Sensitive files

Reading an instance returns <redacted> in place of the content of every sensitive file. Sending <redacted> back keeps the stored content, so an instance read and written back unchanged keeps its files; send the new text to change a file. Revisions store the redacted form too — see Compare and roll back revisions.