Repository navigation
Allow creating a task from an actor template #491
Description
Add an optional template field to TaskSpec that references a Substrate ActorTemplate. A task sets at most one of image and template:
- If
imageis set, the task runs from that image, as today. - If
templateis set, the task runs from the referenced template. - If neither is set, keep today's default (
DefaultTaskImage).
The API server rejects a Task that sets both image and template. It also rejects command together with template, because the template defines what runs.
Example
apiVersion: ax.io/v1alpha1
kind: Task
metadata:
name: lint
atespace: default
spec:
# The actor is created from this ActorTemplate.
template:
name: node-agent
atespace: ax-system # optional, defaults to the task's atespace
workspaces:
- name: default-workspaceRejected at apply time:
spec:
image: gcr.io/ax-substrate/ate-images/ax-task-runner:latest
template: # error: set image or template, not both
name: node-agentmessage TaskSpec {
// ...existing fields 1-6...
// template references the Substrate ActorTemplate to run the task from.
// It can't be combined with image or command.
ObjectRef template = 7;
}
// ObjectRef references a resource by name.
message ObjectRef {
string name = 1;
// atespace defaults to the referencing resource's atespace.
string atespace = 2;
}
Activity
cloudonly commentedon Oct 21, 2026
Following up on @rakyll's note on #505 — I'd like to take this on.
The spec above is clear on the API surface. Three points where I'd want a decision before coding:
Template lifecycle and ownership. Today the reconciler provisions
<task>-tmpl-<digest>ActorTemplates andReconcileDeletesweeps them by that name pattern. For a user-supplied template, AX should neither create nor delete it — so deleting a task withspec.templateset skips template cleanup and only deletes the actor. Related edge: a user-supplied template whose name happens to match another task's generated pattern could be swept by that task's deletion. I'd restrict the sweep to templates AX itself created rather than rejecting names at apply time, but either works.Existence check at apply time. Reject a Task whose bound Workspace does not exist #461 rejects Tasks whose referenced Workspaces don't exist. Should
CreateTaskdo the same for the referenced template, or is a lateTemplateCreationFailedat reconciliation acceptable for v1? I'd lean toward the apply-time check, same reasoning as Reject a Task whose bound Workspace does not exist #461, accepting that the template can still disappear later.Template drift. Tasks are immutable but ActorTemplates are mutable in Substrate, and the reference is by name — a recreated or edited template changes what the actor boots on the next resume. Is name-reference drift acceptable for v1, or should the task pin something stronger once Substrate exposes it?
Minor: the example still shows the pre-#496
workspaces:list; I'll use the singularworkspacebinding in the implementation and tests.Unless the answers change the shape, the plan is: the proto field, apply-time validation (image XOR template, no
commandwithtemplate), reconciler paths that run against an existing template without provisioning one, deletion that never touches user templates, and tests for each.siyuanfoundation commentedon Nov 2, 2026
/assign
siyuanfoundation commentedon Nov 2, 2026
Thanks @cloudonly for your interest.
I have already created a PR for it.
For your questions:
ActorTemplateitself is actually immutable after creation, see https://github.com/agent-substrate/substrate/blob/ae3ac05b0140c30bed1f323b2e62d2c28f580079/cmd/ateapi/internal/controlapi/actor_template.go#L140feat: allow creating a task from an actor template (google#491)
mayawang commentedon Nov 2, 2026
@cloudonly sorry we didn't get back to you on this sooner, that's on us. Thanks for the questions, they shaped the PR. If you're up for another one, #424 or anything labeled devx would be great.
feat: allow creating a task from an actor template (google#491)