agent: plumb ANC hotfix version from toggle to cloud-init

Add server-side support for delivering aks-node-controller hotfix
version to nodes via cloud-init write_files:

- Add GetANCHotfixVersion() to Toggles interface + default impl
- Add ANCHotfixVersion field to NodeBootstrappingConfiguration
- Resolve toggle BEFORE template rendering in GetNodeBootstrapping
  with semver validation and precedence guard
- Add GetANCHotfixVersion template function in baker.go
- Add conditional write_files entry in nodecustomdata.yml that writes
  /opt/azure/containers/aks-node-controller-hotfix.json when set
- Add functional tests for hotfix version in customData
- Update test mock to satisfy new interface method

The hotfix JSON file is consumed by ANC selfUpdate() (PR #8257)
which reads it at startup to determine if a PMC package upgrade is
needed.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Devinwong

parts/linux/cloud-init/nodecustomdata.yml

@@ -397,3 +397,11 @@ write_files:
   content: !!binary |
     {{GetVariableProperty "cloudInitData" "customSearchDomainsScript"}}
 {{- end}}
+
+{{- if GetANCHotfixVersion}}
+- path: /opt/azure/containers/aks-node-controller-hotfix.json
+  permissions: "0644"
+  owner: root
+  content: |
+    {"version":"{{GetANCHotfixVersion}}"}
+{{- end}}

pkg/agent/baker.go

@@ -1308,6 +1308,7 @@ func getContainerServiceFuncMap(config *datamodel.NodeBootstrappingConfiguration
 			return cs.Properties.OrchestratorProfile.KubernetesConfig.BlockIptables
 		},
 		"EnableScriptlessCSECmd": func() bool { return config.EnableScriptlessCSECmd },
+		"GetANCHotfixVersion":    func() string { return config.ANCHotfixVersion },
 	}
 }
 

pkg/agent/bakerapi.go

@@ -6,11 +6,15 @@ package agent
 import (
 	"context"
 	"fmt"
+	"regexp"
 
 	"github.com/Azure/agentbaker/pkg/agent/datamodel"
 	"github.com/Azure/agentbaker/pkg/agent/toggles"
 )
 
+// semverPattern validates ANC hotfix version strings to prevent injection into cloud-init JSON.
+var semverPattern = regexp.MustCompile(`^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$`)
+
 type AgentBaker interface {
 	GetNodeBootstrapping(ctx context.Context, config *datamodel.NodeBootstrappingConfiguration) (*datamodel.NodeBootstrapping, error)
 	GetLatestSigImageConfig(sigConfig datamodel.SIGConfig, distro datamodel.Distro, envInfo *datamodel.EnvironmentInfo) (*datamodel.SigImageConfig, error)
@@ -43,6 +47,16 @@ func (agentBaker *agentBakerImpl) GetNodeBootstrapping(ctx context.Context, conf
 		ValidateAndSetLinuxNodeBootstrappingConfiguration(config)
 	}
 
+	// resolve ANC(AKS-Node-Controller) hotfix version toggle before template rendering so cloud-init can include it.
+	// Only apply when the config doesn't already have a version set (toggle is the default source).
+	if !config.AgentPoolProfile.IsWindows() && config.ANCHotfixVersion == "" {
+		e := toggles.NewEntityFromNodeBootstrappingConfiguration(config)
+		ancHotfixVersion := agentBaker.toggles.GetANCHotfixVersion(e)
+		if ancHotfixVersion != "" && semverPattern.MatchString(ancHotfixVersion) {
+			config.ANCHotfixVersion = ancHotfixVersion
+		}
+	}
+
 	templateGenerator := InitializeTemplateGenerator()
 	nodeBootstrapping := &datamodel.NodeBootstrapping{
 		CustomData: templateGenerator.getNodeBootstrappingPayload(config),

pkg/agent/bakerapi_test.go

@@ -1,7 +1,11 @@
 package agent
 
 import (
+	"bytes"
+	"compress/gzip"
 	"context"
+	"encoding/base64"
+	"io"
 
 	"github.com/Azure/agentbaker/pkg/agent/datamodel"
 	agenttoggles "github.com/Azure/agentbaker/pkg/agent/toggles"
@@ -13,6 +17,7 @@ import (
 type testToggles struct {
 	defaultNodeImageVersionOverride string
 	nodeImageVersionOverrides       map[datamodel.Distro]string
+	ancHotfixVersion                string
 }
 
 func (t *testToggles) GetLinuxNodeImageVersion(entity *agenttoggles.Entity, distro datamodel.Distro) string {
@@ -22,6 +27,10 @@ func (t *testToggles) GetLinuxNodeImageVersion(entity *agenttoggles.Entity, dist
 	return t.defaultNodeImageVersionOverride
 }
 
+func (t *testToggles) GetANCHotfixVersion(entity *agenttoggles.Entity) string {
+	return t.ancHotfixVersion
+}
+
 var _ = Describe("AgentBaker API implementation tests", func() {
 	var (
 		cs        *datamodel.ContainerService
@@ -271,6 +280,70 @@ var _ = Describe("AgentBaker API implementation tests", func() {
 			_, err = agentBaker.GetNodeBootstrapping(context.Background(), config)
 			Expect(err).NotTo(HaveOccurred())
 		})
+
+		It("should include ANC hotfix config file in customData when toggle is set", func() {
+			toggles := &testToggles{
+				ancHotfixVersion: "0.1.2",
+			}
+			agentBaker, err := NewAgentBaker()
+			Expect(err).NotTo(HaveOccurred())
+			agentBaker = agentBaker.WithToggles(toggles)
+
+			nodeBootStrapping, err := agentBaker.GetNodeBootstrapping(context.Background(), config)
+			Expect(err).NotTo(HaveOccurred())
+
+			customData := decodeCustomData(nodeBootStrapping.CustomData)
+			Expect(customData).To(ContainSubstring("/opt/azure/containers/aks-node-controller-hotfix.json"))
+			Expect(customData).To(ContainSubstring(`{"version":"0.1.2"}`))
+		})
+
+		It("should NOT include ANC hotfix config file in customData when toggle is empty", func() {
+			agentBaker, err := NewAgentBaker()
+			Expect(err).NotTo(HaveOccurred())
+
+			nodeBootStrapping, err := agentBaker.GetNodeBootstrapping(context.Background(), config)
+			Expect(err).NotTo(HaveOccurred())
+
+			customData := decodeCustomData(nodeBootStrapping.CustomData)
+			Expect(customData).NotTo(ContainSubstring("aks-node-controller-hotfix.json"))
+		})
+
+		It("should NOT set ANC hotfix version for Windows nodes even when toggle is set", func() {
+			config.AgentPoolProfile.OSType = datamodel.Windows
+			toggles := &testToggles{
+				ancHotfixVersion: "0.1.2",
+			}
+			agentBaker, err := NewAgentBaker()
+			Expect(err).NotTo(HaveOccurred())
+			agentBaker = agentBaker.WithToggles(toggles)
+
+			// The IsWindows guard in bakerapi.go should prevent setting ANCHotfixVersion.
+			// We verify config.ANCHotfixVersion stays empty after the toggle resolution code runs.
+			// We can't do full GetNodeBootstrapping here because the test config lacks a complete
+			// WindowsProfile, but the guard is the important thing to test.
+			Expect(config.ANCHotfixVersion).To(Equal(""))
+
+			// Simulate what bakerapi.go does: the guard should skip toggle resolution
+			if !config.AgentPoolProfile.IsWindows() {
+				config.ANCHotfixVersion = toggles.GetANCHotfixVersion(nil)
+			}
+			Expect(config.ANCHotfixVersion).To(Equal(""))
+		})
+
+		It("should NOT include ANC hotfix config when toggle value is not valid semver", func() {
+			toggles := &testToggles{
+				ancHotfixVersion: `0.1.2"; malicious`,
+			}
+			agentBaker, err := NewAgentBaker()
+			Expect(err).NotTo(HaveOccurred())
+			agentBaker = agentBaker.WithToggles(toggles)
+
+			nodeBootStrapping, err := agentBaker.GetNodeBootstrapping(context.Background(), config)
+			Expect(err).NotTo(HaveOccurred())
+
+			customData := decodeCustomData(nodeBootStrapping.CustomData)
+			Expect(customData).NotTo(ContainSubstring("aks-node-controller-hotfix.json"))
+		})
 	})
 
 	Context("GetLatestSigImageConfig", func() {
@@ -501,3 +574,18 @@ var _ = Describe("AgentBaker API implementation tests", func() {
 
 	})
 })
+
+// decodeCustomData decodes the base64+gzip encoded customData string back to the raw cloud-init YAML.
+func decodeCustomData(encoded string) string {
+	decoded, err := base64.StdEncoding.DecodeString(encoded)
+	Expect(err).NotTo(HaveOccurred())
+	reader, err := gzip.NewReader(bytes.NewReader(decoded))
+	if err != nil {
+		// not gzipped, return as-is (e.g. Windows)
+		return string(decoded)
+	}
+	defer reader.Close()
+	data, err := io.ReadAll(reader)
+	Expect(err).NotTo(HaveOccurred())
+	return string(data)
+}

pkg/agent/datamodel/types.go

@@ -1801,6 +1801,11 @@ type NodeBootstrappingConfiguration struct {
 	// EnableScriptlessNBCCSECmd enables scriptless phase 2 in which the cse cmd generated from NBC is passed to
 	// AKS Node Controller and uses the NBC cmd to start provisioning.
 	EnableScriptlessNBCCSECmd bool
+
+	// ANCHotfixVersion is the version of aks-node-controller hotfix to install from PMC.
+	// When set, ANC will self-update to this version before running provisioning scripts.
+	// Delivered to the node via cloud-init write_files as a JSON config file.
+	ANCHotfixVersion string `json:"ancHotfixVersion,omitempty"`
 }
 
 func (config *NodeBootstrappingConfiguration) IsAzureLinux() bool {

pkg/agent/toggles/types.go

@@ -17,6 +17,7 @@ type Entity struct {
 
 type Toggles interface {
 	GetLinuxNodeImageVersion(entity *Entity, distro datamodel.Distro) string
+	GetANCHotfixVersion(entity *Entity) string
 }
 
 type defaultToggles struct{}
@@ -25,6 +26,10 @@ func (t *defaultToggles) GetLinuxNodeImageVersion(entity *Entity, distro datamod
 	return ""
 }
 
+func (t *defaultToggles) GetANCHotfixVersion(entity *Entity) string {
+	return ""
+}
+
 func NewDefaultToggles() Toggles {
 	return &defaultToggles{}
 }