[hajiler]

Part of #1637. (design: Substrate Shared External Volumes).

API-only: adds volumes[].external.external_volume to ActorTemplate so a template can name an ExternalVolume (#3744) in its atespace. Nothing mounts it yet: CreateActorTemplate rejects a template that sets it with UNIMPLEMENTED until the resume path can resolve it, so no actor can be created against a source nothing knows how to mount. Standalone; it does not depend on #3744.

external_volume.name is required for now. Binding an unnamed slot per actor at CreateActor comes with the change that uses the reference, and only relaxes this.

The reference is an ObjectRef, like every other reference to an atespaced resource. external_volume.atespace is required and CreateActorTemplate validation rejects a value that differs from the template's metadata.atespace, since the volume is mounted into that template's actors.

AI use: drafted with an AI agent under my direction.

TODO, for the change that lifts the UNIMPLEMENTED guard:

• Resolve external_volume on the resume path so the actor mounts the registered volume.

• Make DeleteExternalVolume reject with FAILED_PRECONDITION while an ActorTemplate or Actor references the volume. ateapi: add the ExternalVolume resource #3744's doc on that RPC already says it does; nothing enforces it until then, which only holds because this PR rejects the reference at create.

• Record the reference on the volume's status, and settle the ExternalVolumeStatus naming before it lands (see the deferred threads on ateapi: add the ExternalVolume resource #3744).

• Relax external_volume.name to optional once CreateActor can bind an unnamed slot.

• Tests pass: apivalidation table rows (gate off and on), a controlapi test for the UNIMPLEMENTED guard, hack/verify-all.sh, apitool validate, hack/verify/proto-breaking.sh.

• Docs updated: none needed; the field is not served yet and its API reference comment says so.

[hajiler]

Looked at the proto change, the create-time cross-atespace check, the UNIMPLEMENTED guard, the generated code, and the tests (they pass locally). I also checked for bypass paths: there is no UpdateActorTemplate RPC, the only create path goes through the RPC validation plus the ServiceImpl guard, and with the gate off or the client opted out the generated ifDisabled forbid on external short-circuits before ref is reached. Nothing blocking; two small API-surface notes inline.

[hajiler]

docs/api-style-guide.md section 2.3 says a cross-resource reference is named after the resource it points to (actor_template, not actor_template_ref), and #3744 follows that for the same target with GetExternalVolumeRequest.external_volume / DeleteExternalVolumeRequest.external_volume. A bare ref is the one place in the API where an ObjectRef field does not say what it refers to, and once more volume kinds arrive the name gives the reader nothing.

Suggest ObjectRef external_volume = 2; (so the union reads template / external_volume), with the comment, the custom-validation path (external, external_volume, atespace), the UNIMPLEMENTED message, and the test rows updated to match. Renaming is cheap now and a wire break later.

[hajiler]

Renamed to external_volume in a83d19e, with the validation path, the UNIMPLEMENTED message, and the test rows updated to match.

[hajiler]

ExternalVolume is not a message in this file yet; it lands in #3744, which is still open. If this merges first, the rendered API reference (and the comment copied into ateapi.pb.go) names a resource that does not exist anywhere in the API, and a reader has no pointer to where it is defined.

Either sequence this after #3744, or add an internal note here, e.g. (-- The ExternalVolume resource is added in #3744. --), so the dependency is visible from the proto without leaking into the user-facing docs (style guide section 13.1).

[hajiler]

Acknowledged. This PR will be sequenced after #3744 merges, so ExternalVolume will exist in the file by the time this lands.