api: rename Volume.external_volume_template (ExternalVolumeTemplate) to external (ExternalVolumeSource)

Michelle Au (@msau42)

Background

In pkg/proto/ateapipb/ateapi.proto, three of the four union members on Volume (ateapi.proto:1248-1275) use <Type>VolumeSource for the message name and a concise <type> field name without repeating _volume:

message Volume {
  string name = 1;

  DurableDirVolumeSource durable_dir = 2;
  ExternalVolumeTemplate external_volume_template = 3;
  SystemInfoVolumeSource system_info = 5;
  ImageVolumeSource image = 6;
}

ExternalVolumeTemplate external_volume_template breaks both conventions:

Every sibling message on ActorTemplate.volumes is named *VolumeSource (DurableDirVolumeSource, SystemInfoVolumeSource, ImageVolumeSource), even though all of them are part of ActorTemplate.
Its field name repeats _volume_template inside Volume, whereas the siblings use durable_dir, system_info, and image (and internal/proto/ateletpb/atelet.proto:358 already uses ExternalVolumeSource external = 3;).

Proposed Changes

pkg/proto/ateapipb/ateapi.proto:
- Rename message ExternalVolumeTemplate -> ExternalVolumeSource.
- Rename field Volume.external_volume_template -> external.
Regenerate & update callers:
- Run hack/update/codegen.sh to regenerate pkg/proto/ateapipb/ateapi.pb.go and declarative validation in cmd/ateapi/internal/apivalidation.
- Update Go callers, tests, and YAML examples in docs/ (docs/api-guide.md, docs/api-style-guide.md, docs/csi-volumes.md, docs/csi-deployment.md).

Michelle Au (@msau42)

We also have an Atelet ExternalVolumeSource that should probably be renamed just to ExternalVolume to match SystemInfo and Durable dir

substrate/internal/proto/ateletpb/atelet.pb.go

Lines 1584 to 1611 in c1ab95d

    
           type ExternalVolumeSource struct { 
        
           	state protoimpl.MessageState `protogen:"open.v1"` 
        
           	// Required, unlike the actor status counterpart: the control plane only 
        
           	// sends volumes that finished provisioning. 
        
           	// 
        
           	// +k8s:required 
        
           	// +k8s:maxLength=256 # matches ExternalVolume.storage_volume_id's bound 
        
           	// +k8s:customValidation # no control characters 
        
           	StorageVolumeId string `protobuf:"bytes,1,opt,name=storage_volume_id,json=storageVolumeId,proto3" json:"storage_volume_id,omitempty"` 
        
           	// +k8s:optional 
        
           	// +k8s:maxLength=253 # matches ExternalVolume.volume_type's bound 
        
           	// +k8s:customValidation # optional "substrate.io/" prefix + DNS subdomain 
        
           	VolumeType string `protobuf:"bytes,2,opt,name=volume_type,json=volumeType,proto3" json:"volume_type,omitempty"` 
        
           	// volume_context is the driver's provisioning metadata. Its entries 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 
        
           	VolumeContext map[string]string `protobuf:"bytes,3,rep,name=volume_context,json=volumeContext,proto3" json:"volume_context,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"` 
        
           	// publish_context is the driver's attachment metadata for this node, which 
        
           	// the node plugin needs to complete the mount. Bounded like volume_context. 
        
           	// 
        
           	// +k8s:optional 
        
           	// +k8s:customValidation # at most 40 KiB in total, ten times the CSI limit for map fields 
        
           	PublishContext map[string]string `protobuf:"bytes,4,rep,name=publish_context,json=publishContext,proto3" json:"publish_context,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"` 
        
           	unknownFields  protoimpl.UnknownFields 
        
           	sizeCache      protoimpl.SizeCache 
        
           }

substrate/internal/proto/ateletpb/atelet.pb.go

Lines 2021 to 2034 in c1ab95d

    
           // Exactly one of durable_dir / external / system_info / image must be set. 
        
           // 
        
           // +k8s:optional 
        
           // +k8s:unionMember 
        
           DurableDir *DurableDirVolume `protobuf:"bytes,2,opt,name=durable_dir,json=durableDir,proto3" json:"durable_dir,omitempty"` 
        
           // +k8s:optional 
        
           // +k8s:unionMember 
        
           External *ExternalVolumeSource `protobuf:"bytes,3,opt,name=external,proto3" json:"external,omitempty"` 
        
           // +k8s:optional 
        
           // +k8s:unionMember 
        
           SystemInfo *SystemInfoVolume `protobuf:"bytes,4,opt,name=system_info,json=systemInfo,proto3" json:"system_info,omitempty"` 
        
           // +k8s:optional 
        
           // +k8s:unionMember 
        
           Image         *ImageVolumeSource `protobuf:"bytes,5,opt,name=image,proto3" json:"image,omitempty"`

Michelle Au (@msau42)

As of now we are looking at several changes to the External Volume objects

Introduce an ExternalVolumeRef message which enables actors to refer to existing CSI volumes
Nest ExternalVolumeTemplate & ExternalVolumeRef into a single ateapi object ExternalVolumeSource (to match other volumes)
Rename atelet ExternalVolumeSource -> ExternalVolume (to match other volumes)
Introduce a new Atespaced ExternalVolume object (naming scheme tbd).

As of now I think we should close #2436, and I can cover cover all issues as part of a single PR.

cc: Michelle Au (@msau42)

api: nest the external volume template and rename the volume messages

api: nest the external volume template under Volume.external

api: reformat external volumes api

csi: reformat external volumes objects (agent-substrate#2653)

Navigation Menu

Repository navigation

api: rename `Volume.external_volume_template` (`ExternalVolumeTemplate`) to `external` (`ExternalVolumeSource`) #2407

Background

Proposed Changes

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	type ExternalVolumeSource struct {
	state protoimpl.MessageState `protogen:"open.v1"`
	// Required, unlike the actor status counterpart: the control plane only
	// sends volumes that finished provisioning.
	//
	// +k8s:required
	// +k8s:maxLength=256 # matches ExternalVolume.storage_volume_id's bound
	// +k8s:customValidation # no control characters
	StorageVolumeId string `protobuf:"bytes,1,opt,name=storage_volume_id,json=storageVolumeId,proto3" json:"storage_volume_id,omitempty"`
	// +k8s:optional
	// +k8s:maxLength=253 # matches ExternalVolume.volume_type's bound
	// +k8s:customValidation # optional "substrate.io/" prefix + DNS subdomain
	VolumeType string `protobuf:"bytes,2,opt,name=volume_type,json=volumeType,proto3" json:"volume_type,omitempty"`
	// volume_context is the driver's provisioning metadata. Its entries 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
	VolumeContext map[string]string `protobuf:"bytes,3,rep,name=volume_context,json=volumeContext,proto3" json:"volume_context,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"`
	// publish_context is the driver's attachment metadata for this node, which
	// the node plugin needs to complete the mount. Bounded like volume_context.
	//
	// +k8s:optional
	// +k8s:customValidation # at most 40 KiB in total, ten times the CSI limit for map fields
	PublishContext map[string]string `protobuf:"bytes,4,rep,name=publish_context,json=publishContext,proto3" json:"publish_context,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"`
	unknownFields protoimpl.UnknownFields
	sizeCache protoimpl.SizeCache
	}

	// Exactly one of durable_dir / external / system_info / image must be set.
	//
	// +k8s:optional
	// +k8s:unionMember
	DurableDir *DurableDirVolume `protobuf:"bytes,2,opt,name=durable_dir,json=durableDir,proto3" json:"durable_dir,omitempty"`
	// +k8s:optional
	// +k8s:unionMember
	External *ExternalVolumeSource `protobuf:"bytes,3,opt,name=external,proto3" json:"external,omitempty"`
	// +k8s:optional
	// +k8s:unionMember
	SystemInfo *SystemInfoVolume `protobuf:"bytes,4,opt,name=system_info,json=systemInfo,proto3" json:"system_info,omitempty"`
	// +k8s:optional
	// +k8s:unionMember
	Image *ImageVolumeSource `protobuf:"bytes,5,opt,name=image,proto3" json:"image,omitempty"`

api: rename Volume.external_volume_template (ExternalVolumeTemplate) to external (ExternalVolumeSource) #2407

Description

Background

Proposed Changes

Activity

hajiler commented on Oct 13, 2026

hajiler commented on Oct 13, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

api: rename `Volume.external_volume_template` (`ExternalVolumeTemplate`) to `external` (`ExternalVolumeSource`) #2407