feat: Support Kata mounts with virtio-blk by sprt · Pull Request #3805 · kubernetes-sigs/azuredisk-csi-driver

sprt · 2026-09-04T19:28:38Z

What type of PR is this?

/kind feature

What this PR does / why we need it:

Cc @andyzhangx who is aware of this.

This revives work from 2 years ago to better support Azure CSI with Kata Containers (micro-VM container runtime): https://github.com/kubernetes-sigs/azurefile-csi-driver/pulls?q=is%3Apr+author%3Aarc9693

By default, Kata passes the host-mounted filesystem to the pod VM via virtio-fs. Here, we teach the driver to pass the underlying block device to the pod VM via virtio-blk, which will then be mounted by Kata inside the pod VM. This improves performance significantly.

Dependencies:

This introduces a dependency on Kata's so-called DirectVolume API to pass the virtio-blk metadata (e.g. device, mount options, fsGroup) to the pod VM. The API surface is a Kata host folder storing JSON metadata files. The driver accesses it via a new hostPath volume.

Limitations:

The pod VM requires exclusive access to the disk. Hence, volumes used with this must be ReadWriteOncePod, else the driver will return an error on the Kata path.
NodeGetVolumeStats and NodeExpandVolume are not yet supported.

The overall flow is:

The user adds the RuntimeClass annotation azure.csi.disk/kata-mount: direct-volume to their Kata RuntimeClass to opt into the new behavior. The goal is to gate the feature in the RuntimeClass (as opposed to Pod/StorageClass) for users to migrate easily.
In NodePublishVolume:
1. Probe for Kata RuntimeClass annotation.
2. If probing fails, log the error and fall back to non-Kata handling. If annotation present, proceed with below Kata handling.
3. If the volume is not ReadWriteOncePod, return an error.
4. Unmount the disk so the pod VM can have exclusive access.
5. Use the DirectVolume Kata API to pass the virtio-blk device metadata to Kata, and return.
In NodeUnpublishVolume:
1. At the end, probe for any DirectVolume metadata.
2. If probing fails, log the error and continue.
3. If metadata is present, clean it up.
4. Return as usual.

Implementation notes:

We also grab the fsGroup from the pod spec as DirectVolume needs it. This avoids having to advertise VOLUME_MOUNT_GROUP and implementing that on the non-Kata path.
You will notice changes to the RBAC and podInfoOnMount: true in the driver to enable probing the Pod RuntimeClass and fsGroup.

Which issue(s) this PR fixes:

N/A

Requirements:

uses conventional commit messages
includes documentation
adds unit tests
tested upgrade from previous version

Special notes for your reviewer:
See above

Release note:

Implemented mounting with virtio-blk on Kata Containers for improved performance.

linux-foundation-easycla · 2026-09-04T19:28:45Z

The committers listed above are authorized under a signed CLA.

✅ login: sprt / name: Aurélien Bombo (6155c51, 87477d5, f1a42b1, f46ac2f)

kubernetes-prow · 2026-09-04T19:28:45Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: sprt
Once this PR has been reviewed and has the lgtm label, please assign feiskyer for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

kubernetes-prow · 2026-09-04T19:28:47Z

Welcome @sprt!

It looks like this is your first PR to kubernetes-sigs/azuredisk-csi-driver 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/azuredisk-csi-driver has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

kubernetes-prow · 2026-09-04T19:28:49Z

Hi @sprt. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

andyzhangx · 2026-09-05T02:34:07Z

/ok-to-test

Copilot

🟡 Changes recommended

DirectVolume correctness issues and the missing packaged Helm chart update must be addressed before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds experimental Kata Containers virtio-blk support through Kata’s DirectVolume API.

Changes:

Adds Kata-aware direct-volume lifecycle handling.
Adds RBAC, hostPath, pod metadata, tests, and documentation.
Vendors the Kata DirectVolume dependency.

File summaries

File	Summary
`vendor/modules.txt`	Updates vendored module metadata.
`vendor/github.com/kata-containers/kata-containers/src/runtime/pkg/direct-volume/utils.go`	Vendors DirectVolume utilities.
`vendor/github.com/kata-containers/kata-containers/src/runtime/LICENSE`	Adds dependency licensing.
`README.md`	Links Kata mount documentation.
`pkg/azuredisk/nodeserver.go`	Implements Kata volume lifecycle handling.
`pkg/azuredisk/nodeserver_test.go`	Tests Kata node operations.
`pkg/azuredisk/kata.go`	Implements Kata detection and DirectVolume integration.
`pkg/azuredisk/fake_azuredisk.go`	Adds a fake DirectVolume service.
`pkg/azuredisk/fake_azuredisk_test.go`	Tests the fake service.
`pkg/azuredisk/azuredisk.go`	Initializes DirectVolume support.
`go.sum`	Records dependency checksums.
`go.mod`	Adds the Kata dependency.
`docs/kata-mount.md`	Documents setup and limitations.
`deploy/rbac-csi-azuredisk-node.yaml`	Grants pod and RuntimeClass reads.
`deploy/csi-azuredisk-node.yaml`	Mounts DirectVolume metadata storage.
`deploy/csi-azuredisk-driver.yaml`	Enables pod metadata.
`charts/latest/azuredisk-csi-driver/templates/rbac-csi-azuredisk-node.yaml`	Mirrors RBAC changes in Helm.
`charts/latest/azuredisk-csi-driver/templates/csi-azuredisk-node.yaml`	Mirrors hostPath changes in Helm.
`charts/latest/azuredisk-csi-driver/templates/csi-azuredisk-driver.yaml`	Enables pod metadata in Helm.

Review details

Files reviewed: 15/20 changed files
Comments generated: 7
Review effort level: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

andyzhangx · 2026-09-07T13:30:01Z

    snapshot: "{{ .Values.snapshot.image.csiSnapshotter.tag }}"
 spec:
  attachRequired: true
-  podInfoOnMount: false


add a .Values.node.enableKataCCMount feature flag to decide whether enable or not here

Done in the template

andyzhangx · 2026-09-07T13:30:37Z

              name: sys-devices-dir
            - mountPath: /sys/class/
              name: sys-class
+            - mountPath: /run/kata-containers/shared/direct-volumes


this should be protected by new feature flag: .Values.node.enableKataCCMount

andyzhangx · 2026-09-07T13:30:52Z

            path: /sys/class/
            type: Directory
          name: sys-class
+        - hostPath:


this should be protected by new feature flag: .Values.node.enableKataCCMount

Done in the template

andyzhangx · 2026-09-07T13:30:57Z

  - apiGroups: [""]
    resources: ["nodes"]
    verbs: ["get", "patch"]
+  - apiGroups: [""]


this should be protected by new feature flag: .Values.node.enableKataCCMount

Done in the template

andyzhangx · 2026-09-07T13:32:00Z

+annotation on your Kata Containers RuntimeClass:
+
+```yaml
+azure.csi.disk/kata-mount: direct-volume


would you add more explanation as an example with the required annotation here?

Added an example section

andyzhangx · 2026-09-07T13:33:53Z

+## Limitations
+
+ * Virtio-blk requires exclusive access to the Azure Disk and the volume
+   needs to have the `ReadWriteOncePod` access mode. Otherwise the


have the ReadWriteOncePod access mode instead of ReadWriteOnce access mode

andyzhangx · 2026-09-07T13:40:17Z

-	err = preparePublishPath(target, d.mounter)
-	if err != nil {
-		return nil, status.Error(codes.Internal, fmt.Sprintf("Target path could not be prepared: %v", err))
+	if kataPod, err := kataGetMountPod(ctx, d.kubeClient, params); err != nil {


pls also add enableKataCCMount flag in the driver, ref: https://github.com/kubernetes-sigs/azurefile-csi-driver/blob/022c14a4f34207de234477ad36751aeb412e71ca/pkg/azurefile/nodeserver.go#L192

Done - named it enableKataMount because this is not Kata-CC-specific

Copilot

🔵 Needs a closer look

Direct mounts currently mishandle read-only requests, filesystem normalization, raw block semantics, and partitioned disks.

Review details

Suppressed comments (4)

pkg/azuredisk/nodeserver.go:279

The Kata path reimplements filesystem resolution instead of using resolveFSType. This leaves values such as XFS unnormalized (so nouuid is also omitted) and assigns the default ext4 filesystem to raw block capabilities, contradicting the block semantics enforced during staging. Reuse resolveFSType here so the metadata matches the device that was staged.

		// Get fsType that the volume will be formatted and mounted with
		fstype := getDefaultFsType()
		var mountFlags []string
		if mnt := volumeCapability.GetMount(); mnt != nil {
			if mnt.FsType != "" {

pkg/azuredisk/nodeserver.go:292

req.Readonly is not propagated to the direct-volume mount options. Consequently, a filesystem requested read-only is mounted writable inside the Kata VM; several new success cases set Readonly: true while expecting options without ro. Add the read-only option before constructing MountInfo.

		fsGroup, fsGroupChangePolicy := getPodFSGroup(kataPod, volumeCapability, req.GetReadonly())
		metadata := map[string]string{}

pkg/azuredisk/nodeserver.go:320

This passes the whole disk even when volumeAttributes.partition was used during NodeStageVolume. In that case staging formatted/mounted device-partN, but Kata is instructed to mount device, so the guest mount fails against the partition table instead of the filesystem. Apply the same partition suffix for filesystem direct volumes.

		mountInfo := directvolume.MountInfo{
			VolumeType: kataDirectVolumeType,
			Device:     device,
			FsType:     fstype,

docs/kata-mount.md:10

The sentence is missing “be.”

This virtio-blk integration can enabled by setting the following

Files reviewed: 15/20 changed files
Comments generated: 0 new
Review effort level: Balanced

Signed-off-by: Aurélien Bombo <abombo@microsoft.com>

Copilot

🟡 Changes recommended

Zero-valued fsGroup handling can break Kata mounts, and the setup documentation currently cannot enable the feature correctly.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Files reviewed: 18/23 changed files
Comments generated: 3
Review effort level: Balanced

+		if fsGroup != nil {
+			metadata[directvolume.FSGroupMetadataKey] = strconv.FormatInt(*fsGroup, 10)


+This virtio-blk integration can be enabled by setting the following
+annotation on your Kata Containers RuntimeClass:


+metadata:
+  name: kata
+  annotations:
+    io.katacontainers.csi-mount: "direct-volume"


sprt force-pushed the sprt/kata-direct-volume-clean-history branch from 63ffc47 to f1a42b1 Compare September 4, 2026 19:28

kubernetes-prow Bot added the kind/feature Categorizes issue or PR as related to a new feature. label Sep 4, 2026

kubernetes-prow Bot requested review from landreasyan and nearora-msft September 4, 2026 19:28

kubernetes-prow Bot added cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Sep 4, 2026

kubernetes-prow Bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Sep 4, 2026

vendor: add Kata direct-volume dependency

dcff339

sprt marked this pull request as draft September 4, 2026 19:29

kubernetes-prow Bot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. and removed cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. labels Sep 4, 2026

sprt force-pushed the sprt/kata-direct-volume-clean-history branch from f1a42b1 to 7b8671f Compare September 4, 2026 19:38

sprt marked this pull request as ready for review September 4, 2026 19:48

kubernetes-prow Bot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Sep 4, 2026

kubernetes-prow Bot requested a review from cvvz September 4, 2026 19:48

sprt force-pushed the sprt/kata-direct-volume-clean-history branch 3 times, most recently from 22aab7a to e90ea3b Compare September 4, 2026 19:59

kubernetes-prow Bot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Sep 5, 2026

andyzhangx requested a balanced review from Copilot September 5, 2026 02:35

Copilot started reviewing on behalf of andyzhangx September 5, 2026 02:36 View session

Copilot AI reviewed Sep 5, 2026

View reviewed changes

andyzhangx reviewed Sep 7, 2026

View reviewed changes

andyzhangx requested a balanced review from Copilot September 9, 2026 14:28

Copilot started reviewing on behalf of andyzhangx September 9, 2026 14:28 View session

Copilot AI reviewed Sep 9, 2026

View reviewed changes

sprt force-pushed the sprt/kata-direct-volume-clean-history branch 2 times, most recently from 86d7e86 to 1b05456 Compare September 9, 2026 17:15

sprt added 2 commits September 9, 2026 12:16

feat: Support Kata mounts with virtio-blk

380eeb2

chore(chart): update latest helm package

c0395e7

Signed-off-by: Aurélien Bombo <abombo@microsoft.com>

sprt force-pushed the sprt/kata-direct-volume-clean-history branch from 1b05456 to c0395e7 Compare September 9, 2026 19:52

landreasyan requested a balanced review from Copilot September 10, 2026 00:06

Copilot started reviewing on behalf of landreasyan September 10, 2026 00:07 View session

Copilot AI reviewed Sep 10, 2026

View reviewed changes

		if fsGroup != nil {
		metadata[directvolume.FSGroupMetadataKey] = strconv.FormatInt(*fsGroup, 10)

		This virtio-blk integration can be enabled by setting the following
		annotation on your Kata Containers RuntimeClass:

Uh oh!

Conversation

sprt commented Sep 4, 2026

Uh oh!

linux-foundation-easycla Bot commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kubernetes-prow Bot commented Sep 4, 2026

Uh oh!

kubernetes-prow Bot commented Sep 4, 2026

Uh oh!

kubernetes-prow Bot commented Sep 4, 2026

Uh oh!

andyzhangx commented Sep 5, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Suppressed comments (4)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

linux-foundation-easycla Bot commented Sep 4, 2026 •

edited

Loading