Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1,929 changes: 1,183 additions & 746 deletions api/ateapi/v1/ateapi.pb.go

Large diffs are not rendered by default.

146 changes: 141 additions & 5 deletions api/ateapi/v1/ateapi.proto
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,29 @@ service Control {
option (method).resource = "Tag";
}

// Register a volume that already exists in the storage system as an
// ExternalVolume. Requires the ExternalVolumes preview gate.
rpc CreateExternalVolume(CreateExternalVolumeRequest) returns (ExternalVolume) {
option (method).resource = "ExternalVolume";
}

// Get an ExternalVolume.
rpc GetExternalVolume(GetExternalVolumeRequest) returns (ExternalVolume) {
option (method).resource = "ExternalVolume";
}

// List ExternalVolumes.
rpc ListExternalVolumes(ListExternalVolumesRequest) returns (ListExternalVolumesResponse) {
option (method).resource = "ExternalVolume";
}

// Delete an ExternalVolume. Removes the record only; the storage is left in
// place. Rejects (FailedPrecondition) if any Actor or ActorTemplate
// references the volume.
Comment on lines +139 to +141

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.

🤖 Per API Style Guide §13.2, gRPC status codes and field names/paths in proto comments should be in code spans: `FAILED_PRECONDITION` instead of (FailedPrecondition) (here and line 223), and code spans around metadata.atespace, metadata.name, volume_id, etc. on lines 1145, 1160, 1166, 1177, 1186, and 2162.

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.

AI: Update to FAILED_PRECONDITION.

rpc DeleteExternalVolume(DeleteExternalVolumeRequest) returns (ExternalVolume) {
Comment thread
hajiler marked this conversation as resolved.
Resolved
Comment thread
hajiler marked this conversation as resolved.
Resolved
option (method).resource = "ExternalVolume";
}

// List Workers.
rpc ListWorkers(ListWorkersRequest) returns (ListWorkersResponse) {
option (method).resource = "Worker";
Expand Down Expand Up @@ -197,8 +220,8 @@ service Control {
option (method).resource = "Atespace";
}

// Delete an empty Atespace. Rejects (FailedPrecondition) if any Actors or
// Tags remain.
// Delete an empty Atespace. Rejects (FailedPrecondition) if any Actors,
// ActorTemplates, Tags or ExternalVolumes remain.
rpc DeleteAtespace(DeleteAtespaceRequest) returns (Atespace) {
option (method).resource = "Atespace";
}
Expand Down Expand Up @@ -526,9 +549,9 @@ message ExternalVolumeStatus {
string volume_type = 3;

// volume_context contains metadata returned by the CSI driver during volume
// provisioning, needed by the node plugin for mounting (e.g. attachment
// info). Keys and values are the driver's own, so the map is only bounded,
// not validated.
// provisioning, needed by the node plugin for mounting, such as an NFS
// server and export path. Keys and values are the driver's own, so the map
// is only bounded, not validated.
//
// +k8s:optional
// +k8s:customValidation # at most 40 KiB in total, ten times the CSI limit for map fields
Expand Down Expand Up @@ -1116,6 +1139,62 @@ message Tag {
ObjectRef source_actor = 4;
}

// ExternalVolume is an atespace-scoped record of a CSI volume. Its lifetime
// is independent of any actor: it registers a volume that already exists in
// the storage system, by the volume ID and driver the node plugin needs to
// mount it. Identity is (atespace, name). An atespace cannot be deleted while
// it holds an ExternalVolume.
//
// Deleting an ExternalVolume removes the record only; the storage is left in
// place.
//
// (-- Actors cannot reference an ExternalVolume yet. The actor template
Comment thread
hajiler marked this conversation as resolved.
Resolved
// reference, actor references on the volume, and the delete trigger come in
// later changes. --)
message ExternalVolume {
Comment thread
hajiler marked this conversation as resolved.
Resolved
option (resource) = {
scope : SCOPE_ATESPACE
plural : "ExternalVolumes"
};

// Common resource metadata: atespace, name, uid, version, timestamps.
//
// +k8s:required
// +k8s:subfield(atespace)=+k8s:required
ResourceMetadata metadata = 1;

// volume_id is the volume's ID in the storage system, as the CSI driver
// reports it. Its format is the storage system's own, so it is only bounded
// and checked for control characters, like
// `ExternalVolumeStatus.storage_volume_id`.
//
// +k8s:required
// +k8s:maxLength=256
// +k8s:immutable
// +k8s:customValidation # no control characters
string volume_id = 2;
Comment thread
hajiler marked this conversation as resolved.
Resolved
Comment on lines +1166 to +1175

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: now that callers supply volume_id instead of a driver returning it, consider also rejecting leading/trailing whitespace and TAB/LF/CR here, since the control-character check lets them through. It's easier to loosen validation later than tighten it:

Path safety on the node is covered separately by #3180, which names atelet's staging directories by a SHA-256 of the ID.


// volume_type is the CSI driver name, with the syntax of
// `ExternalVolumeStatus.volume_type`.
//
// +k8s:required
// +k8s:maxLength=253

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.

🤖 Tighten +k8s:maxLength=253 to +k8s:maxLength=63 to match the CSI spec (GetPluginInfoResponse.name), Kubernetes CSIDriver, CSIDriverConfigSpec.DriverName (+kubebuilder:validation:MaxLength=63), and ExternalVolumeClass.driver_name in #3751 (+k8s:maxLength=63). A 64–253 character driver name can never match a valid CSIDriverConfig in Substrate.

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.

AI: Tighten to match CSI spec

// +k8s:immutable
// +k8s:customValidation # CSI driver name syntax
string volume_type = 3;
Comment thread
hajiler marked this conversation as resolved.
Resolved

@msau42 Michelle Au (msau42) Nov 16, 2026 •

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.

🤖 API naming suggestion: volume_type → driver_name (or driver): Here this is specifically a CSI driver name, and #3751 (ExternalVolumeClass) names the exact same field driver_name. Renaming volume_type to driver_name removes the redundant volume_ prefix and aligns ExternalVolume with ExternalVolumeClass.

Also update this CLI flag (--driver-name), the table column header in printer.go (DRIVER—matching CSIDriverConfig—or DRIVER NAME), tools/apitool/internal/examples/grpc/ExternalVolume.yaml, docs/guides/csi-volumes.md, and docs/reference/kubectl-ate.md.

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.

AI: Update to driver name and corresponding references.


// volume_context is the driver metadata the node plugin needs to mount the
// volume, as the CSI driver returned it when the volume was provisioned.
// Keys and values are the driver's own, so the map is only bounded, like
// `ExternalVolumeStatus.volume_context`. Attachment metadata is per node
// and not recorded here.
Comment on lines +1186 to +1190

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: please make the ExternalVolume field docs and validators self-contained. volume_id (line 1169), volume_type (line 1178), and volume_context (here) define their constraints by pointing at ExternalVolumeStatus fields, and the ValidateCustom_ExternalVolume_* functions in apivalidation/external_volume.go delegate to ValidateCustom_ExternalVolumeStatus_*. Since ExternalVolumeStatus is going away (and per API Style Guide §8 that name would become this resource's own status message), these references will dangle or point at the wrong thing. Suggest stating the rules inline (e.g. "a DNS-1123 subdomain, optionally prefixed with substrate.io/", "at most 256 bytes, no control characters", "at most 40 KiB in total") and calling resources.ValidateStorageVolumeID, resources.ValidateVolumeType, and resources.ValidateCSIMap directly.

Also, "as the CSI driver returned it when the volume was provisioned" doesn't fit a pre-existing volume registered by hand, where the caller supplies the map. Consider describing what it's used for instead: it's passed as volume_context to the node plugin's NodeStageVolume/NodePublishVolume.

//
// +k8s:optional
// +k8s:immutable
// +k8s:customValidation # at most 40 KiB in total, ten times the CSI limit for map fields
map<string, string> volume_context = 4;
Comment thread
hajiler marked this conversation as resolved.
Resolved
Comment on lines +1192 to +1195

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.

🤖 Unlike ExternalVolumeStatus.volume_context (driver-populated), ExternalVolume.volume_context is caller-supplied on CreateExternalVolume. Because ValidateCSIMap only checks sum(len(k) + len(v)) <= 40 KiB:

  1. Empty map keys ({"": "foo"}) currently pass validation, whereas the CSI spec requires map keys to be non-empty.
  2. docs/api-validation.md (Rules for map fields) requires all map fields to carry +k8s:maxProperties and per-key/per-value bounds (+k8s:eachKey / +k8s:eachVal); without +k8s:maxProperties, up to 40,960 1-byte entries are accepted.

Consider adding +k8s:maxProperties (e.g. 128 or 1024), +k8s:eachKey=+k8s:minLength=1, +k8s:eachKey=+k8s:maxLength=4096, and +k8s:eachVal=+k8s:maxLength=40960 alongside the 40 KiB total size check.

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.

AI: Add additional validation and update unit test accordingly. Use 1024 maxProperties.

}

// Atespace is the isolation boundary an Actor is created into. Global-scoped:
// metadata.atespace is always empty; the atespace's identity is metadata.name.
message Atespace {
Expand Down Expand Up @@ -2078,6 +2157,63 @@ message DeleteTagRequest {
DeleteOptions options = 2;
}

// Request to register an ExternalVolume.
message CreateExternalVolumeRequest {
// The volume to register. metadata.atespace and metadata.name are its
// identity; the other metadata fields are server-assigned and ignored.
//
// +ate:preview=ExternalVolumes
// +k8s:ifDisabled(ExternalVolumes)=+k8s:forbidden
// +k8s:required
Comment thread
hajiler marked this conversation as resolved.
Resolved
ExternalVolume external_volume = 1;
Comment thread
hajiler marked this conversation as resolved.
Resolved
Comment thread
hajiler marked this conversation as resolved.
Resolved
}

// GetExternalVolumeRequest identifies one ExternalVolume.
message GetExternalVolumeRequest {
// The volume to get.
//
// +k8s:required
// +k8s:subfield(atespace)=+k8s:required
ObjectRef external_volume = 1;
}

// ListExternalVolumesRequest selects a page of ExternalVolumes.
message ListExternalVolumesRequest {
// The atespace to list from. Empty lists across all atespaces.
//
// +k8s:optional
// +k8s:format=k8s-short-name
string atespace = 1;

// Pagination controls.
//
// +k8s:optional
ListOptions options = 2;
}

// ListExternalVolumesResponse is one page of ExternalVolumes.
message ListExternalVolumesResponse {
// The volumes in this page.
repeated ExternalVolume external_volumes = 1;

// Pagination token for the next page. Empty on the last page.
string next_page_token = 2;
}

// DeleteExternalVolumeRequest identifies one ExternalVolume to delete.
message DeleteExternalVolumeRequest {
// The volume to delete.
//
// +k8s:required
// +k8s:subfield(atespace)=+k8s:required
ObjectRef external_volume = 1;

// Optional per-delete preconditions.
//
// +k8s:optional
DeleteOptions options = 2;
}

// DeleteOptions are the optional guards a Delete request may carry.
message DeleteOptions {
// Delete only if the resource is still at this version, that is, unchanged
Expand Down
Loading
Loading