From c8d1370545db5761685bb569f4ad114e2238114b Mon Sep 17 00:00:00 2001 From: Vitali Date: Tue, 16 Jun 2026 11:17:46 +0000 Subject: [PATCH 1/5] MC-1857: add persistent volume permissions docs - Add persistent-volume-permissions.mdx explaining file permission behaviour between root/non-root containers sharing a volume - Update rolling-updates.mdx with a note about volumes: existing pods are shut down first to unmount volumes before new pods start - Add persistent-volume-permissions page to Managing Apps in docs.json --- docs.json | 1 + .../persistent-volume-permissions.mdx | 85 +++++++++++++++++++ magic-containers/rolling-updates.mdx | 8 ++ 3 files changed, 94 insertions(+) create mode 100644 magic-containers/persistent-volume-permissions.mdx diff --git a/docs.json b/docs.json index 373e8eb..3b7d170 100644 --- a/docs.json +++ b/docs.json @@ -298,6 +298,7 @@ "magic-containers/configuration", "magic-containers/environment-variables", "magic-containers/persistent-volumes", + "magic-containers/persistent-volume-permissions", "magic-containers/endpoints", "magic-containers/undeploy", "magic-containers/delete" diff --git a/magic-containers/persistent-volume-permissions.mdx b/magic-containers/persistent-volume-permissions.mdx new file mode 100644 index 0000000..d99e3aa --- /dev/null +++ b/magic-containers/persistent-volume-permissions.mdx @@ -0,0 +1,85 @@ +--- +title: "Persistent Volume Permissions" +description: "Understand how file permissions work when multiple containers in a pod share a persistent volume." +--- + +When multiple containers in a pod share a persistent volume, their ability to read, modify, or delete each other's files depends on which user each container runs as. This page explains what to expect. + +## How it works + +Each volume is automatically configured so that all containers within the same pod can access it. Files created inside the volume inherit a shared group identity, meaning containers can read and interact with each other's files. + +### A note on deletion + +On Linux, whether a process can delete a file is determined by write permission on the **directory** containing the file — not by the file's own permissions. Because all pod containers share write access to the volume directory, a non-root container would ordinarily be able to delete any file inside it, regardless of who created it. + +To prevent this, the volume directory is configured with the **sticky bit**. With the sticky bit set, only the file's owner or root can delete or rename a file, even if the process has write access to the directory. This is the same mechanism used by shared system directories such as `/tmp`. + +The `Delete ❌` entries in the tables below rely on the sticky bit being present on the volume directory. + +## Permission tables + +### Root container writes, non-root container reads + +| Operation | Result | +|-----------|--------| +| Read | ✅ | +| Modify | ❌ | +| Delete | ❌ | + +Files created by a root process can be read but not modified or deleted by non-root containers. + +--- + +### Non-root container writes, root container reads + +| Operation | Result | +|-----------|--------| +| Read | ✅ | +| Modify | ✅ | +| Delete | ✅ | + +Root always has full access regardless of file permissions. + +--- + +### Non-root container writes, non-root container reads (same user) + +Both containers run as the same user ID. + +| Operation | Result | +|-----------|--------| +| Read | ✅ | +| Modify | ✅ | +| Delete | ✅ | + +Full access — the reading container is the file owner. + +--- + +### Non-root container writes, non-root container reads (different users) + +Containers run as different user IDs. + +| Operation | Result | +|-----------|--------| +| Read | ✅ | +| Modify | ❌ | +| Delete | ❌ | + +The reading container is not the file owner. It can read files but cannot modify or delete them. + +--- + +## Summary + +| Scenario | Read | Modify | Delete | +|-----------------------------------|------|--------|--------| +| Root writes → non-root reads | ✅ | ❌ | ❌ | +| Non-root writes → root reads | ✅ | ✅ | ✅ | +| Same user writes and reads | ✅ | ✅ | ✅ | +| Different non-root users | ✅ | ❌ | ❌ | + + + Volumes are only shared between containers within the same pod. Containers from different pods cannot access each other's volumes — this is handled at the mount level. + diff --git a/magic-containers/rolling-updates.mdx b/magic-containers/rolling-updates.mdx index d92f5a1..d93685f 100644 --- a/magic-containers/rolling-updates.mdx +++ b/magic-containers/rolling-updates.mdx @@ -32,6 +32,14 @@ Imagine you have an application deployed in 3 regions, each with 10 pods. If you **Total Iterations** - 5 iterations to update all pods in each region. +# Applications with persistent volumes + +When your application uses [persistent volumes](/magic-containers/persistent-volumes), the rolling update process is adjusted to prevent data corruption. Rather than starting new pods before removing old ones, existing pods are shut down first to fully unmount their volumes before new pods are started. + + + This means applications with persistent volumes will experience brief downtime during a rolling update, as the old pod must release the volume before the new pod can attach it. + + # Handling issues during a rolling update If the Rolling Update encounters problems, such as deploying a broken image, it handles the situation by detecting any new pod that fails to reach a running state within ten minutes and considering it unhealthy. In such cases, the Rolling Update is terminated. All new pods with the faulty configuration are deleted, and old pods are restored to maintain application stability. The Rolling Update then restarts automatically, using the latest configuration. If the issue is fixed, such as by providing a healthy image, the update will proceed successfully. From 95e9d70eaa917de633379e4e49ba4c8d6b09eac1 Mon Sep 17 00:00:00 2001 From: Vitali Date: Tue, 16 Jun 2026 13:36:07 +0200 Subject: [PATCH 2/5] rolling update fix --- magic-containers/rolling-updates.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/magic-containers/rolling-updates.mdx b/magic-containers/rolling-updates.mdx index d93685f..53728bb 100644 --- a/magic-containers/rolling-updates.mdx +++ b/magic-containers/rolling-updates.mdx @@ -37,7 +37,7 @@ Imagine you have an application deployed in 3 regions, each with 10 pods. If you When your application uses [persistent volumes](/magic-containers/persistent-volumes), the rolling update process is adjusted to prevent data corruption. Rather than starting new pods before removing old ones, existing pods are shut down first to fully unmount their volumes before new pods are started. - This means applications with persistent volumes will experience brief downtime during a rolling update, as the old pod must release the volume before the new pod can attach it. + Applications with persistent volumes may experience a short period of downtime during a rolling update if the number of pods is less than 2, as the old pod must release the volume before the new pod can attach it. # Handling issues during a rolling update From 59c1cb891ccc7830554900bf77d301224ca8b9d2 Mon Sep 17 00:00:00 2001 From: Vitali Date: Tue, 16 Jun 2026 14:31:01 +0200 Subject: [PATCH 3/5] docs updated --- docs.json | 1 - magic-containers/persistent-volumes.mdx | 74 +++++++++++++++++++++++++ 2 files changed, 74 insertions(+), 1 deletion(-) diff --git a/docs.json b/docs.json index 3b7d170..373e8eb 100644 --- a/docs.json +++ b/docs.json @@ -298,7 +298,6 @@ "magic-containers/configuration", "magic-containers/environment-variables", "magic-containers/persistent-volumes", - "magic-containers/persistent-volume-permissions", "magic-containers/endpoints", "magic-containers/undeploy", "magic-containers/delete" diff --git a/magic-containers/persistent-volumes.mdx b/magic-containers/persistent-volumes.mdx index 64166d6..e68caf5 100644 --- a/magic-containers/persistent-volumes.mdx +++ b/magic-containers/persistent-volumes.mdx @@ -91,6 +91,80 @@ Your application now has scalable persistent volumes attached to each container. Throughput limits are defined in the pod cgroup and apply to each volume individually. If a pod has two volumes attached, each volume receives its own 10 MB/s read and 10 MB/s write limits. +## File permissions + +When multiple containers in a pod share a volume, their ability to read, modify, or delete each other's files depends on which user each container runs as. + +**Which user does a container run as?** By default, if no `USER` instruction is present in your Dockerfile, the container runs as root (`uid=0`). If a `USER` instruction is specified, the container runs as that user. + +```dockerfile +# Runs as root (no USER specified) +FROM ubuntu:22.04 +CMD ["myapp"] + +# Runs as a non-root user +FROM ubuntu:22.04 +USER 1000 +CMD ["myapp"] +``` + + + Volumes are only shared between containers within the same pod. Containers from different pods cannot access each other's volumes. + + +### Root creates files, non-root accesses them + +| Operation | Result | +|-----------|--------| +| Read | ✅ | +| Modify | ❌ | +| Delete | ❌ | + +Files created by a root process can be read but not modified or deleted by non-root containers. + +### Non-root creates files, root accesses them + +| Operation | Result | +|-----------|--------| +| Read | ✅ | +| Modify | ✅ | +| Delete | ✅ | + +Root always has full access regardless of file permissions. + +### Both containers run as the same non-root user + +| Operation | Result | +|-----------|--------| +| Read | ✅ | +| Modify | ✅ | +| Delete | ✅ | + +Full access as both containers are the file owner. + +### Each container runs as a different non-root user + +| Operation | Result | +|-----------|--------| +| Read | ✅ | +| Modify | ❌ | +| Delete | ❌ | + +The accessing container is not the file owner. It can read files but cannot modify or delete them. + +### Summary + +| Scenario | Read | Modify | Delete | +|----------------------------------------|------|--------|--------| +| Root creates, non-root accesses | ✅ | ❌ | ❌ | +| Non-root creates, root accesses | ✅ | ✅ | ✅ | +| Same non-root user | ✅ | ✅ | ✅ | +| Different non-root users | ✅ | ❌ | ❌ | + +### A note on deletion + +On Linux, whether a process can delete a file is determined by write permission on the **directory** containing the file, not by the file's own permissions. Because all pod containers share write access to the volume directory, a non-root container would ordinarily be able to delete any file inside it regardless of who created it. To prevent this, the volume directory is configured with the **sticky bit** — the same mechanism used by shared system directories such as `/tmp`. With the sticky bit set, only the file's owner or root can delete or rename a file, even with directory write access. The `Delete ❌` entries in the tables above rely on this. + ## FAQ From e0870dfa2345bc290e5709debd96af15699c09dc Mon Sep 17 00:00:00 2001 From: Vitali Date: Tue, 16 Jun 2026 14:32:19 +0200 Subject: [PATCH 4/5] removed permissions file --- .../persistent-volume-permissions.mdx | 85 ------------------- 1 file changed, 85 deletions(-) delete mode 100644 magic-containers/persistent-volume-permissions.mdx diff --git a/magic-containers/persistent-volume-permissions.mdx b/magic-containers/persistent-volume-permissions.mdx deleted file mode 100644 index d99e3aa..0000000 --- a/magic-containers/persistent-volume-permissions.mdx +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: "Persistent Volume Permissions" -description: "Understand how file permissions work when multiple containers in a pod share a persistent volume." ---- - -When multiple containers in a pod share a persistent volume, their ability to read, modify, or delete each other's files depends on which user each container runs as. This page explains what to expect. - -## How it works - -Each volume is automatically configured so that all containers within the same pod can access it. Files created inside the volume inherit a shared group identity, meaning containers can read and interact with each other's files. - -### A note on deletion - -On Linux, whether a process can delete a file is determined by write permission on the **directory** containing the file — not by the file's own permissions. Because all pod containers share write access to the volume directory, a non-root container would ordinarily be able to delete any file inside it, regardless of who created it. - -To prevent this, the volume directory is configured with the **sticky bit**. With the sticky bit set, only the file's owner or root can delete or rename a file, even if the process has write access to the directory. This is the same mechanism used by shared system directories such as `/tmp`. - -The `Delete ❌` entries in the tables below rely on the sticky bit being present on the volume directory. - -## Permission tables - -### Root container writes, non-root container reads - -| Operation | Result | -|-----------|--------| -| Read | ✅ | -| Modify | ❌ | -| Delete | ❌ | - -Files created by a root process can be read but not modified or deleted by non-root containers. - ---- - -### Non-root container writes, root container reads - -| Operation | Result | -|-----------|--------| -| Read | ✅ | -| Modify | ✅ | -| Delete | ✅ | - -Root always has full access regardless of file permissions. - ---- - -### Non-root container writes, non-root container reads (same user) - -Both containers run as the same user ID. - -| Operation | Result | -|-----------|--------| -| Read | ✅ | -| Modify | ✅ | -| Delete | ✅ | - -Full access — the reading container is the file owner. - ---- - -### Non-root container writes, non-root container reads (different users) - -Containers run as different user IDs. - -| Operation | Result | -|-----------|--------| -| Read | ✅ | -| Modify | ❌ | -| Delete | ❌ | - -The reading container is not the file owner. It can read files but cannot modify or delete them. - ---- - -## Summary - -| Scenario | Read | Modify | Delete | -|-----------------------------------|------|--------|--------| -| Root writes → non-root reads | ✅ | ❌ | ❌ | -| Non-root writes → root reads | ✅ | ✅ | ✅ | -| Same user writes and reads | ✅ | ✅ | ✅ | -| Different non-root users | ✅ | ❌ | ❌ | - - - Volumes are only shared between containers within the same pod. Containers from different pods cannot access each other's volumes — this is handled at the mount level. - From 8d9543495d6562efc1698cbb615615c132f63cbb Mon Sep 17 00:00:00 2001 From: Vitali Date: Tue, 16 Jun 2026 14:46:15 +0200 Subject: [PATCH 5/5] practical example to volume rolling update flow --- magic-containers/rolling-updates.mdx | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/magic-containers/rolling-updates.mdx b/magic-containers/rolling-updates.mdx index 53728bb..3f87e29 100644 --- a/magic-containers/rolling-updates.mdx +++ b/magic-containers/rolling-updates.mdx @@ -40,6 +40,19 @@ When your application uses [persistent volumes](/magic-containers/persistent-vol Applications with persistent volumes may experience a short period of downtime during a rolling update if the number of pods is less than 2, as the old pod must release the volume before the new pod can attach it. +## Practical example + +Imagine you have an application deployed in 3 regions, each with 10 pods, and each pod has a persistent volume attached. If you update the container image: + +1. Iteration 1: + - Remove 2 old pods (20% of 10) in each region and wait for their volumes to fully unmount. + - Start 2 new pods in each region and wait until they are running and healthy. + +2. Iterations 2–5: + - Repeat the above steps until all pods are updated. + +**Total Iterations** - 5 iterations to update all pods in each region. + # Handling issues during a rolling update If the Rolling Update encounters problems, such as deploying a broken image, it handles the situation by detecting any new pod that fails to reach a running state within ten minutes and considering it unhealthy. In such cases, the Rolling Update is terminated. All new pods with the faulty configuration are deleted, and old pods are restored to maintain application stability. The Rolling Update then restarts automatically, using the latest configuration. If the issue is fixed, such as by providing a healthy image, the update will proceed successfully.