Replace actor template namespace/name pair with ActorTemplate atespace and name pair in internal APIs by zoez7 · Pull Request #1304 · agent-substrate/substrate

Zoe Zhao (zoez7) · 2026-08-28T23:01:52Z

Both Atelet and Ateom internal APIs consume actor template namespace/name pair to telemetry. Updated them to use the new Substrate ActorTemplate proto instead of the legacy CRD one.

Julian Gutierrez Oschmann (juli4n) · 2026-08-29T19:31:27Z

+
 message TerminateWorkloadRequest {
+  reserved 4, 5;
+  reserved "actor_template_namespace", "actor_template_name";


Don't reserve fields. Just drop them and reuse the IDs. We are breaking the API anyways.

Done. I renamed "actor_template_namespace" to "actor_template_atespace" instead.

Julian Gutierrez Oschmann (juli4n) · 2026-08-29T19:38:52Z


+// ObjectRef references a Substrate resource by its (atespace, name) identity.
+// Mirrors ateapipb.ObjectRef, which internal protos do not import.
+message ObjectRef {


ObjectRef is a concept of the control plane API (mgmt plane) where we need a way for resources to reference another resources. We could introduce the same concept in the atelet API (control plane), although I'm not sure how useful that is.

If we adopt it, we should use it consistently, for example, we have atespace, actor_name , which could be an ObjectRef too, but for actors we also have an actor_uid which isn't in the ObjectRef (I guess that could be a separate top level field alongside actor ?

ObjectRef actor; string actor_uid; ObjectReg actor_template;

Dropped ObjectRef concept in internal API for now, since the internal APIs only need the ActorTemplate's name and atepsace for telemetry for now.

Krisztian F (krisztianfekete) · 2026-08-31T09:48:19Z

+		return nil
+	}
+	return &ateletpb.ObjectRef{Atespace: ref.GetAtespace(), Name: ref.GetName()}
+}


This drops the CRD fallback, so actors now might send nil and ate.template.* becomes empty on all the atelet/ateom metrics and actor logs.

Here:

substrate/cmd/ateapi/internal/controlapi/workflow_resume.go

Lines 519 to 526 in 6982894

if ref := actorTemplateObjectRef(actor); ref != nil {

assignment.ActorTemplateRef = ref

} else {

assignment.ActorTemplate = &ateapipb.KubeNamespacedObjectRef{

Namespace: actor.GetActorTemplateNamespace(),

Name: actor.GetActorTemplateName(),

}

}

we already do the if/else against actorTemplateObjectRef, can we do the same until the legacy one is gone?

I restricted the scope of this PR to just renaming the actor template "Namespace" to "Atespace" in internal APIs. Will fix this in a follow up PR.
The legacy one will be gone in the next 2 days. I'll have a PR to do the cutover so we won't have to maintain 2 branches.

Krisztian F (krisztianfekete) · 2026-08-31T09:50:02Z

 	op := snapshotOp{
-		templateNamespace: req.GetActorTemplateNamespace(),
-		templateName:      req.GetActorTemplateName(),
+		templateNamespace: req.GetActorTemplate().GetAtespace(),


ActorMetricAttributes coerces an empty template to TemplateUnknown, this, and at a few other places below emit "". Can we pick one to make it consistent?

The TemplateUnknown was a temporary hack to fix e2e test during the transition period. Will have a separate PR to use the new substrate atespace everywhere.

Krisztian F (krisztianfekete) · 2026-08-31T09:51:51Z

 	snapshotSizeBytes.Record(ctx, fi.Size(), metric.WithAttributes(
 		semconv.FileNameKey.String(file),
-		ateattr.TemplateNamespaceKey.String(atNamespace),
-		ateattr.TemplateNameKey.String(atName),
+		ateattr.TemplateNamespaceKey.String(templateRef.GetAtespace()),
+		ateattr.TemplateNameKey.String(templateRef.GetName()),


Note that ate.template.namespace is documented like this:

substrate/docs/metrics/registry/metrics.yaml

Lines 74 to 78 in 6982894

attributes:

- id: ate.template.namespace

stability: development

type: string

brief: The Kubernetes namespace of the ActorTemplate of the actor.

but it's an atespace now. Weaver only checks spellings so verify/metrics.sh stays green either way, we should fix the brief in this PR.

Krisztian F (krisztianfekete) · 2026-08-31T09:54:07Z

 	// Actor identity makes a flat snapshot self-identifying if control-plane
 	// persistence is unavailable.
-	Atespace               string `json:"atespace,omitempty"`
-	ActorName              string `json:"actorName,omitempty"`
-	ActorUID               string `json:"actorUid,omitempty"`
-	ActorTemplateNamespace string `json:"actorTemplateNamespace,omitempty"`
-	ActorTemplateName      string `json:"actorTemplateName,omitempty"`
+	Atespace      string               `json:"atespace,omitempty"`
+	ActorName     string               `json:"actorName,omitempty"`
+	ActorUID      string               `json:"actorUid,omitempty"`
+	ActorTemplate *actorTemplateRecord `json:"actorTemplate,omitempty"`


Can we lose template identity before/after this PR? Probably fine at this point though.

Yes, during the switch there are some places where the template might log empty. I'll fix it as part of the full cutover.

Krisztian F (krisztianfekete) · 2026-08-31T09:55:21Z

+				templateNamespace: sample.GetActorTemplate().GetAtespace(),
+				templateName:      sample.GetActorTemplate().GetName(),


If the ref is nil every actor collapses into one ("", "") bucket here, so the per-template memory/cpu gauges merge instead of just going unlabeled. Similar issue to #761

The actor template identity carried on atelet/ateom requests, snapshot manifests, and stats samples now names the substrate ActorTemplate (atespace + name), sourced from the resolved ActorTemplate's metadata, instead of the legacy CRD-backed template's kube namespace/name pair.

Zoe Zhao (zoez7) requested review from Tim Bai (baizhenyu), Da Huang (git286) and Krisztian F (krisztianfekete) August 28, 2026 23:01

Zoe Zhao (zoez7) force-pushed the actor-template-objectref branch 2 times, most recently from 71b19ba to dfe7e8c Compare August 29, 2026 00:50

Julian Gutierrez Oschmann (juli4n) reviewed Aug 29, 2026

View reviewed changes

Krisztian F (krisztianfekete) reviewed Aug 31, 2026

View reviewed changes

Zoe Zhao (zoez7) force-pushed the actor-template-objectref branch from dfe7e8c to 9e173b3 Compare August 31, 2026 17:38

Zoe Zhao (zoez7) changed the title ~~Replace actor template namespace/name pair with ActorTemplate substrate ObjectRef in internal protos~~ Replace actor template namespace/name pair with ActorTemplate atespace and name pair in internal APIs Aug 31, 2026

Julian Gutierrez Oschmann (juli4n) approved these changes Aug 31, 2026

View reviewed changes

Julian Gutierrez Oschmann (juli4n) merged commit 9bddf66 into agent-substrate:main Aug 31, 2026
9 checks passed

Navigation Menu

Uh oh!

Replace actor template namespace/name pair with ActorTemplate atespace and name pair in internal APIs - #1304

Replace actor template namespace/name pair with ActorTemplate atespace and name pair in internal APIs#1304
Julian Gutierrez Oschmann (juli4n) merged 1 commit into
agent-substrate:mainfrom
zoez7:actor-template-objectref

Zoe Zhao (zoez7) commented Aug 28, 2026

Uh oh!

Julian Gutierrez Oschmann (juli4n) Aug 29, 2026

Uh oh!

Zoe Zhao (zoez7) Aug 31, 2026

Uh oh!

Julian Gutierrez Oschmann (juli4n) Aug 29, 2026

Uh oh!

Zoe Zhao (zoez7) Aug 31, 2026

Uh oh!

Krisztian F (krisztianfekete) Aug 31, 2026

Uh oh!

Zoe Zhao (zoez7) Aug 31, 2026

Uh oh!

Krisztian F (krisztianfekete) Aug 31, 2026

Uh oh!

Zoe Zhao (zoez7) Aug 31, 2026

Uh oh!

Krisztian F (krisztianfekete) Aug 31, 2026

Uh oh!

Krisztian F (krisztianfekete) Aug 31, 2026

Uh oh!

Zoe Zhao (zoez7) Aug 31, 2026

Uh oh!

Krisztian F (krisztianfekete) Aug 31, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	if ref := actorTemplateObjectRef(actor); ref != nil {
	assignment.ActorTemplateRef = ref
	} else {
	assignment.ActorTemplate = &ateapipb.KubeNamespacedObjectRef{
	Namespace: actor.GetActorTemplateNamespace(),
	Name: actor.GetActorTemplateName(),
	}
	}

	attributes:
	- id: ate.template.namespace
	stability: development
	type: string
	brief: The Kubernetes namespace of the ActorTemplate of the actor.

		templateNamespace: sample.GetActorTemplate().GetAtespace(),
		templateName: sample.GetActorTemplate().GetName(),

Uh oh!

Conversation

Zoe Zhao (zoez7) commented Aug 28, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants