Skip to content

Enable CSI based external volumes for agents - #552

Merged
Michelle Au (msau42) merged 3 commits into
agent-substrate:mainfrom
hajiler:external-volumes-for-agent-branch
Aug 7, 2026
Merged

Enable CSI based external volumes for agents#552
Michelle Au (msau42) merged 3 commits into
agent-substrate:mainfrom
hajiler:external-volumes-for-agent-branch

Conversation

@hajiler

@hajiler hajiler commented Jul 27, 2026

Copy link
Copy Markdown
Collaborator

#232

Integrate the with the volume interface created in #405, to enable CSI managed external volumes throughout the agent lifecycle.

CSI driver registration in Substrate is managed dynamically via the CSIDriverConfig CRD, which allows the system to discover and integrate with various CSI drivers on-demand. To support central
control-plane operations (such as volume provisioning), the driver must expose its Controller service over a network port (gRPC over TCP or DNS) which ateapi dynamically resolves from the CRD. For node-
level operations (such as volume mounting), the atelet agent on each worker node bypasses the network and connects directly to the driver's Node service using a Unix domain socket mounted from the
Kubelet plugins directory.

Support for secure connection with the controller will be added in a follow-up PR.

  • [ X] Tests pass
  • Appropriate changes to documentation are included in the PR

@hajiler
hajiler force-pushed the external-volumes-for-agent-branch branch 6 times, most recently from c447f89 to f07fb92 Compare July 29, 2026 00:29
@hajiler
hajiler marked this pull request as ready for review July 29, 2026 00:31

@msau42 Michelle Au (msau42) left a comment

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.

Is there a way to squash the dynamic plugin registration commit with the earlier commits that used a binary flag? It would probably be less confusing for other reviewers that go commit by commit because the binary flag changes get completely replaced later on.

Also in the PR description can you provide a high level summary of the driver registration approach?

Comment thread internal/volume/csi/client.go
Comment thread internal/volume/csi/plugin.go
Comment thread internal/volume/csi/plugin.go
Comment thread internal/volume/csi/plugin.go
Comment thread cmd/ateapi/internal/controlapi/volumes.go Outdated
Comment thread pkg/api/v1alpha1/csidriverconfig_types.go Outdated
Comment thread hack/setup-csi-hostpath-kind.sh Outdated
Comment thread hack/setup-csi-hostpath-kind.sh
Comment thread manifests/ate-install/atelet.yaml Outdated
Comment thread manifests/ate-install/generated/ate.dev_csidriverconfigs.yaml
Comment thread hack/setup-csi-hostpath-kind.sh

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.

General comment: Avoid unpinned external references. They're a security risk and they make tests etc unreproducible.

  • container images (refer to by @ sha256 digest)
  • git repos (pin a git commit by hash or find an alternative)
  • install manifests (consider e.g. checking in a copy under a third_party directory)

@msau42 Michelle Au (msau42) self-assigned this Jul 31, 2026
@hajiler
hajiler force-pushed the external-volumes-for-agent-branch branch from f07fb92 to 2bc2eed Compare July 31, 2026 18:21
@zlammerts-svg Zheng Lammerts (zlammerts-svg) added this to the M2 milestone Jul 31, 2026
@hajiler
hajiler force-pushed the external-volumes-for-agent-branch branch 2 times, most recently from 3cbbf55 to 8cc2997 Compare July 31, 2026 20:29
Comment thread cmd/ateapi/internal/controlapi/volumes.go Outdated
Comment thread cmd/ateapi/internal/controlapi/volumes.go Outdated
Comment thread manifests/ate-install/atelet.yaml Outdated
Comment thread manifests/ate-install/atelet.yaml
@hajiler
hajiler force-pushed the external-volumes-for-agent-branch branch 5 times, most recently from a9df0ea to 7291838 Compare August 5, 2026 00:03

@msau42 Michelle Au (msau42) left a comment

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.

Can you also update the PR description to give a high level overview of the CSI driver registration and communication approach?

Comment thread manifests/ate-install/kind/atelet/kustomization.yaml
DriverName string `json:"driverName"`

// ControllerEndpoint is the gRPC endpoint for the CSI Controller service.
// Must be a valid URI (e.g. unix:///var/run/csi.sock or dns:///csi-service:9000).

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.

I would say remove it for now and we can consider adding it back if we need it.

Comment thread cmd/ateapi/internal/controlapi/service.go Outdated
Comment thread cmd/ateapi/internal/controlapi/service.go Outdated
Comment thread cmd/atelet/main.go
Comment thread internal/imagecache/implicitdirs_test.go Outdated
Comment thread hack/setup-csi-hostpath-kind.sh Outdated
Comment thread manifests/ate-install/atelet.yaml
Comment thread internal/volume/csi/plugin.go Outdated
STATUS_DELETING = 3;
}
Status status = 4;
// volume_context contains metadata returned by the CSI driver during volume

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.

Does the CSI spec have any restrictions on syntax that we can add validation on?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

IIUC, volume context isn't really standardized amongsts drivers, so I'm not really sure what validation we could enforce.

Comment thread pkg/api/v1alpha1/csidriverconfig_types.go
Comment thread pkg/api/v1alpha1/csidriverconfig_types.go Outdated
@hajiler
hajiler force-pushed the external-volumes-for-agent-branch branch 2 times, most recently from 8931618 to da93c1f Compare August 5, 2026 18:23
Comment thread internal/imagecache/implicitdirs_test.go Outdated
@hajiler
hajiler force-pushed the external-volumes-for-agent-branch branch 2 times, most recently from b850ccd to 23d7382 Compare August 6, 2026 16:59
@msau42

Copy link
Copy Markdown
Collaborator

PR lgtm, just waiting on tests to run.

Have one minor nit, I am fine fixing it in a followup.

}

// StagingDirPrefix returns the prefix directory for staging CSI volumes.
func StagingDirPrefix() string {

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, can be done in a followup: maybe call it "CSIStagingDirPrefix"

@hajiler hajiler closed this Aug 7, 2026
@hajiler
hajiler force-pushed the external-volumes-for-agent-branch branch from 23d7382 to c9777b4 Compare August 7, 2026 17:00
@hajiler hajiler reopened this Aug 7, 2026
@msau42
Michelle Au (msau42) merged commit 8f4c001 into agent-substrate:main Aug 7, 2026
14 of 15 checks passed
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.

4 participants