Skip to content

armgit / ax

Public Imported from GitHub
0

Agent Executor (AX) is Google's open agentic orchestration runtime

Go

runner: ignore unknown fields in specs from the control plane (#506)

Grant McCloskey0f085aa063db
diff --git a/cmd/ax-task-runner/main.go b/cmd/ax-task-runner/main.go
index e9e0d9c..66cec43 100644
--- a/cmd/ax-task-runner/main.go
+++ b/cmd/ax-task-runner/main.go
@@ -32,6 +32,7 @@ import (
"github.com/google/ax/pkg/apis/v1alpha1"
"github.com/google/ax/runner"
+ "google.golang.org/protobuf/proto"
"gopkg.in/yaml.v3"
)
@@ -73,8 +74,10 @@ func main() {
}
// loadSpec decodes YAML into out from file when set, otherwise from the named
-// environment variable. It is not an error for neither to be present.
-func loadSpec(file, envVar string, out any) error {
+// environment variable. It is not an error for neither to be present, or for
+// the YAML to be blank. Unknown fields are ignored, so a runner image keeps
+// working with a newer control plane.
+func loadSpec(file, envVar string, out proto.Message) error {
var raw []byte
switch {
case file != "":
@@ -88,7 +91,14 @@ func loadSpec(file, envVar string, out any) error {
default:
return nil
}
- if err := yaml.Unmarshal(raw, out); err != nil {
+ var node yaml.Node
+ if err := yaml.Unmarshal(raw, &node); err != nil {
+ return fmt.Errorf("parsing %T: %w", out, err)
+ }
+ if len(node.Content) == 0 || node.Content[0].ShortTag() == "!!null" {
+ return nil
+ }
+ if err := v1alpha1.UnmarshalYAMLLenient(node.Content[0], out); err != nil {
return fmt.Errorf("parsing %T: %w", out, err)
}
return nil
diff --git a/cmd/ax-task-runner/main_test.go b/cmd/ax-task-runner/main_test.go
new file mode 100644
index 0000000..e0cbb03
--- /dev/null
+++ b/cmd/ax-task-runner/main_test.go
@@ -0,0 +1,56 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+ "testing"
+
+ "github.com/google/ax/pkg/apis/v1alpha1"
+)
+
+// A newer ax-server may send Task and Workspace fields this runner doesn't
+// know; they must not stop the task from starting.
+func TestLoadSpec_IgnoresUnknownFields(t *testing.T) {
+ t.Setenv("AX_TASK_YAML", "metadata:\n name: t\nspec:\n image: img\n egress:\n - host: example.com\n")
+ var task v1alpha1.Task
+ if err := loadSpec("", "AX_TASK_YAML", &task); err != nil {
+ t.Fatalf("loadSpec: %v", err)
+ }
+ if task.GetMetadata().GetName() != "t" || task.GetSpec().GetImage() != "img" {
+ t.Errorf("unexpected task %v", &task)
+ }
+}
+
+func TestLoadSpec_Empty(t *testing.T) {
+ t.Setenv("AX_TASK_YAML", "\n")
+ var task v1alpha1.Task
+ if err := loadSpec("", "AX_TASK_YAML", &task); err != nil {
+ t.Fatalf("loadSpec: %v", err)
+ }
+ if task.GetMetadata() != nil {
+ t.Errorf("expected no task, got %v", &task)
+ }
+}
+
+func TestLoadSpec_WorkspaceIgnoresUnknownFields(t *testing.T) {
+ t.Setenv("AX_WORKSPACE_YAML", "metadata:\n name: ws\nspec:\n fieldFromTheFuture: 1\n")
+ var ws v1alpha1.Workspace
+ if err := loadSpec("", "AX_WORKSPACE_YAML", &ws); err != nil {
+ t.Fatalf("loadSpec: %v", err)
+ }
+ if ws.GetMetadata().GetName() != "ws" {
+ t.Errorf("unexpected workspace %v", &ws)
+ }
+}
diff --git a/pkg/apis/v1alpha1/types.go b/pkg/apis/v1alpha1/types.go
index 5b98965..2138223 100644
--- a/pkg/apis/v1alpha1/types.go
+++ b/pkg/apis/v1alpha1/types.go
@@ -59,6 +59,9 @@ const (
var (
protoMarshal = protojson.MarshalOptions{}
protoUnmarshal = protojson.UnmarshalOptions{} // unknown fields are errors
+ // protoUnmarshalLenient is for specs the control plane hands to a runner,
+ // which may come from a newer control plane than the runner image.
+ protoUnmarshalLenient = protojson.UnmarshalOptions{DiscardUnknown: true}
)
// normalizer rewrites a generically decoded document in place so legacy shapes
@@ -74,6 +77,25 @@ func marshalYAML(m proto.Message) (any, error) {
}
func unmarshalYAML(value *yaml.Node, m proto.Message, normalize normalizer) error {
+ return unmarshalYAMLWith(value, m, normalize, protoUnmarshal)
+}
+
+// UnmarshalYAMLLenient decodes a Task, Workspace or Model like their
+// UnmarshalYAML methods but ignores fields it doesn't know. Runners use it for
+// the specs the control plane passes them, so a runner image keeps working
+// when a newer control plane adds fields it doesn't use.
+func UnmarshalYAMLLenient(value *yaml.Node, m proto.Message) error {
+ var normalize normalizer
+ switch m.(type) {
+ case *Workspace:
+ normalize = normalizeWorkspace
+ case *Model:
+ normalize = normalizeModel
+ }
+ return unmarshalYAMLWith(value, m, normalize, protoUnmarshalLenient)
+}
+
+func unmarshalYAMLWith(value *yaml.Node, m proto.Message, normalize normalizer, opts protojson.UnmarshalOptions) error {
var doc any
if err := value.Decode(&doc); err != nil {
return err
@@ -85,7 +107,7 @@ func unmarshalYAML(value *yaml.Node, m proto.Message, normalize normalizer) erro
if err != nil {
return fmt.Errorf("converting yaml to json: %w", err)
}
- return protoUnmarshal.Unmarshal(data, m)
+ return opts.Unmarshal(data, m)
}
// jsonToYAMLNode converts a JSON document into a yaml.Node tree, preserving
diff --git a/pkg/apis/v1alpha1/types_test.go b/pkg/apis/v1alpha1/types_test.go
index e6fefbe..48a6d10 100644
--- a/pkg/apis/v1alpha1/types_test.go
+++ b/pkg/apis/v1alpha1/types_test.go
@@ -559,3 +559,39 @@ func TestValidateWorkspace_Files(t *testing.T) {
t.Errorf("expected path is required error, got %v", err)
}
}
+
+func TestUnmarshalYAMLLenient_IgnoresUnknownFields(t *testing.T) {
+ doc := "metadata:\n name: t\n atespace: default\nspec:\n image: img\n fieldFromTheFuture: 1\n"
+ var node yaml.Node
+ if err := yaml.Unmarshal([]byte(doc), &node); err != nil {
+ t.Fatal(err)
+ }
+
+ var strict v1alpha1.Task
+ if err := node.Decode(&strict); err == nil {
+ t.Fatal("strict decoding should reject an unknown field")
+ }
+
+ var lenient v1alpha1.Task
+ if err := v1alpha1.UnmarshalYAMLLenient(&node, &lenient); err != nil {
+ t.Fatalf("lenient decoding failed: %v", err)
+ }
+ if lenient.GetSpec().GetImage() != "img" {
+ t.Errorf("image = %q, want img", lenient.GetSpec().GetImage())
+ }
+}
+
+func TestUnmarshalYAMLLenient_NormalizesWorkspace(t *testing.T) {
+ doc := "metadata:\n name: ws\nspec:\n fieldFromTheFuture: true\n mcp:\n - name: srv\n"
+ var node yaml.Node
+ if err := yaml.Unmarshal([]byte(doc), &node); err != nil {
+ t.Fatal(err)
+ }
+ var ws v1alpha1.Workspace
+ if err := v1alpha1.UnmarshalYAMLLenient(&node, &ws); err != nil {
+ t.Fatalf("lenient decoding failed: %v", err)
+ }
+ if got := ws.GetSpec().GetMcp().GetServers(); len(got) != 1 || got[0].GetName() != "srv" {
+ t.Errorf("mcp servers = %v, want one named srv", got)
+ }
+}