Skip to content

docs: retain NFS controller privileges in the CSI example - #3521

Open
Luomu (cloudonly) wants to merge 4 commits into
agent-substrate:mainfrom
cloudonly:fix/docs-csi-controller
Open

Luomu (cloudonly) wants to merge 4 commits into
agent-substrate:mainfrom
cloudonly:fix/docs-csi-controller

Conversation

@cloudonly

@cloudonly Luomu (cloudonly) commented Oct 31, 2026 •

Copy link
Copy Markdown
Contributor

The CSI controller mounts its NFS share when creating and deleting volume directories. The example omits the driver privileges and NODE_ID used by the vendored deployment.

Use privileged mode for the NFS driver, following the vendored controller manifest, and populate NODE_ID from spec.nodeName. Envoy keeps its restricted security context. SYS_ADMIN alone does not override security profiles that deny mounts.

Validation:

  • Real CSI CreateVolume and DeleteVolume calls pass with the privileged driver in isolated containers using nfsplugin v4.13.4 on Linux 5.14. The default-permissions control fails at mount.
  • All six YAML examples parse; checks confirm the driver privileges, NODE_ID and restricted Envoy configuration.
  • git diff --check passes.

The permission comparison did not deploy Kubernetes or the Envoy sidecar. SYS_ADMIN also worked on that test host, but this does not establish compatibility with AppArmor-enabled Kubernetes nodes.

AI use: AI-assisted, I reviewed and tested it.

  • Tests pass
  • Docs updated

@cloudonly
Luomu (cloudonly) marked this pull request as ready for review October 31, 2026 04:59
Signed-off-by: cloudonly <enrondg@gmail.com>
Signed-off-by: cloudonly <enrondg@gmail.com>
SYS_ADMIN alone leaves mounts blocked by default AppArmor profiles. Keep the upstream privileged example and qualify the permission guidance.

Signed-off-by: cloudonly <enrondg@gmail.com>
Comment thread docs/guides/csi-deployment.md Outdated
Comment on lines +188 to +192
The controller mounts the NFS share when creating and deleting volume directories.
This example uses privileged mode for the `nfs` container, following the
[vendored controller manifest](../../hack/third_party/csi-driver-nfs/deploy/csi-nfs-controller.yaml).
Adding `SYS_ADMIN` alone does not bypass security profiles that deny mounts.
Envoy keeps its restricted security context.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Nit: The intent of this example is to demonstrate how to set up the Envoy sidecar rather than the specifics of the NFS driver. Could we reword this paragraph to keep the focus on the Envoy sidecar setup?

Suggested change
The controller mounts the NFS share when creating and deleting volume directories.
This example uses privileged mode for the `nfs` container, following the
[vendored controller manifest](../../hack/third_party/csi-driver-nfs/deploy/csi-nfs-controller.yaml).
Adding `SYS_ADMIN` alone does not bypass security profiles that deny mounts.
Envoy keeps its restricted security context.
The `envoy-proxy` sidecar shares `socket-dir` (`/csi`) with the CSI driver container and mounts the Envoy configuration (`envoy-config`), the Service DNS serving certificate (`servicedns-certs`), and the Pod Identity trust bundle (`podidentity-ca`). Even when the CSI driver container itself requires elevated privileges (such as [the upstream `csi-nfs-controller` manifest](../../hack/third_party/csi-driver-nfs/deploy/csi-nfs-controller.yaml)), the Envoy sidecar runs with a restricted `securityContext` (`allowPrivilegeEscalation: false`, `readOnlyRootFilesystem: true`, and all capabilities dropped).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied your suggestion in 901068b99 and verified the docs build.

Signed-off-by: cloudonly <enrondg@gmail.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants