feat: add CoreDNS hosts plugin support for LocalDNS

[saewoni]

Prior review history: This PR continues the work from #7639, which contains review comments and testing notes. That PR could not be reopened after a branch force-push. Please refer to #7639 for prior context.

What this PR does / why we need it:

Adds CoreDNS hosts plugin support for LocalDNS. When enabled, critical AKS FQDNs (mcr.microsoft.com, packages.aks.azure.com, etc.) are resolved and cached in /etc/localdns/hosts by a systemd timer (aks-hosts-setup), then served authoritatively by the CoreDNS hosts plugin — eliminating upstream DNS lookups for these endpoints.

Key changes:

• aks-hosts-setup.sh / .service / .timer — resolves AKS FQDNs and writes /etc/localdns/hosts
• CoreDNS corefile template gains hosts /etc/localdns/hosts { fallthrough } block in both VnetDNS and KubeDNS listeners
• Two corefile variants generated at provisioning time: LOCALDNS_COREFILE_BASE (vanilla) and LOCALDNS_COREFILE_FULL (with all optional plugins). localdns.sh dynamically selects the full variant once the hosts file is populated.
• enableLocalDNS() is the single entry point for all localdns setup including hosts plugin
• E2E: table-driven tests across 7 distros (legacy) and 5 distros (scriptless), validating dig AA flag + IP match against hosts file
• VHD: packer configs updated to include aks-hosts-setup files on all Linux images

Which issue(s) this PR fixes:

[github-actions]

The latest Buf updates on your PR. Results from workflow Buf CI / buf (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	✅ passed	✅ passed	✅ passed	Apr 8, 2026, 10:06 PM

[Copilot]

Pull request overview

This PR extends AKS LocalDNS to optionally include a CoreDNS hosts plugin backed by a periodically refreshed /etc/localdns/hosts file, and wires the feature through VHD build, CSE/provisioning scripts, datamodel/config, and e2e/spec tests.

Changes:

• Add aks-hosts-setup script + systemd service/timer, and copy them into Linux VHDs.
• Add EnableHostsPlugin config plumbed through datamodel, CSE env, corefile generation (with/without hosts variants), and localdns runtime selection/annotation.
• Add/extend ShellSpec + e2e coverage for hosts-plugin behavior and related cleanup utilities.

Reviewed changes

Copilot reviewed 44 out of 44 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
vhdbuilder/packer/vhd-image-builder-mariner.json	Copies new aks-hosts-setup artifacts into Mariner VHD build staging.
vhdbuilder/packer/vhd-image-builder-mariner-cvm.json	Copies new aks-hosts-setup artifacts into Mariner CVM VHD build staging.
vhdbuilder/packer/vhd-image-builder-mariner-arm64.json	Copies new aks-hosts-setup artifacts into Mariner ARM64 VHD build staging.
vhdbuilder/packer/vhd-image-builder-flatcar.json	Copies new aks-hosts-setup artifacts into Flatcar VHD build staging.
vhdbuilder/packer/vhd-image-builder-flatcar-arm64.json	Copies new aks-hosts-setup artifacts into Flatcar ARM64 VHD build staging.
vhdbuilder/packer/vhd-image-builder-cvm.json	Copies new aks-hosts-setup artifacts into CVM VHD build staging.
vhdbuilder/packer/vhd-image-builder-base.json	Copies new aks-hosts-setup artifacts into base (Ubuntu/AzureLinux) VHD build staging.
vhdbuilder/packer/vhd-image-builder-arm64-gen2.json	Copies new aks-hosts-setup artifacts into ARM64 Gen2 VHD build staging.
vhdbuilder/packer/vhd-image-builder-acl.json	Copies new aks-hosts-setup artifacts into ACL VHD build staging.
vhdbuilder/packer/vhd-image-builder-acl-arm64.json	Copies new aks-hosts-setup artifacts into ACL ARM64 VHD build staging.
vhdbuilder/packer/packer_source.sh	Installs aks-hosts-setup script + systemd units onto the VHD filesystem.
spec/shellspec.Dockerfile	Adds dnsutils to enable nslookup/dig in ShellSpec container.
spec/parts/linux/cloud-init/artifacts/localdns_spec.sh	Updates expectations for new corefile variant behavior and adds tests for node annotation helper.
spec/parts/linux/cloud-init/artifacts/cse_main_spec.sh	New ShellSpec coverage for corefile selection logic sourced from localdns.sh.
spec/parts/linux/cloud-init/artifacts/cse_config_spec.sh	Extends tests for localdns backward-compat guards + env file variant writing + aks-hosts-setup enablement.
spec/parts/linux/cloud-init/artifacts/aks_hosts_setup_spec.sh	New ShellSpec coverage for aks-hosts-setup DNS resolution, cloud selection, atomic writes, and error handling.
pkg/agent/datamodel/types_test.go	Adds unit tests for ShouldEnableHostsPlugin; simplifies ShouldEnableLocalDNS test.
pkg/agent/datamodel/types.go	Adds EnableHostsPlugin to LocalDNSProfile and ShouldEnableHostsPlugin() helper; extends corefile data.
pkg/agent/baker_test.go	Updates LocalDNS corefile generation tests for new GenerateLocalDNSCoreFile signature and hosts/no-hosts variants.
pkg/agent/baker.go	Plumbs hosts-plugin enablement + generates both corefile variants; template now conditionally emits hosts blocks.
parts/linux/cloud-init/artifacts/localdns.sh	Adds dynamic corefile variant selection, best-effort node annotation, and startup regeneration behavior.
parts/linux/cloud-init/artifacts/cse_main.sh	Enables aks-hosts-setup when hosts plugin enabled; starts localdns with the no-hosts variant.
parts/linux/cloud-init/artifacts/cse_config.sh	Writes both corefile variants + SHOULD_ENABLE_HOSTS_PLUGIN to env file; adds enableAKSHostsSetup; adds backward-compat guards.
parts/linux/cloud-init/artifacts/cse_cmd.sh	Exposes SHOULD_ENABLE_HOSTS_PLUGIN and LOCALDNS_GENERATED_COREFILE_NO_HOSTS env vars to provisioning.
parts/linux/cloud-init/artifacts/aks-hosts-setup.timer	New timer to periodically refresh /etc/localdns/hosts.
parts/linux/cloud-init/artifacts/aks-hosts-setup.sh	New script to resolve critical FQDNs and atomically write /etc/localdns/hosts.
parts/linux/cloud-init/artifacts/aks-hosts-setup.service	New oneshot service to run the hosts population script (used by timer and manual refresh).
e2e/vmss.go	Adds MockUnknownCloud injection to validate unsupported cloud handling for aks-hosts-setup.
e2e/validators.go	Adds validators for aks-hosts-setup service/timer, hosts file content, and AA-flag/IP-match hosts-plugin behavior.
e2e/validation.go	Runs new hosts-plugin validators when the feature is enabled.
e2e/types.go	Adds scenario helpers to detect hosts-plugin enablement and choose default FQDNs per cloud.
e2e/scenario_localdns_hosts_test.go	New end-to-end scenarios for hosts plugin (legacy + scriptless) across multiple distros.
e2e/cluster.go	Adds cleanup of tagged Private DNS zones that can interfere with DNS-sensitive tests.
e2e/aks_model.go	Tags created Private DNS zones; adds cleanup helpers for zones and VNET links.
aks-node-controller/proto/aksnodeconfig/v1/localdns_config.proto	Adds enable_hosts_plugin to scriptless LocalDnsProfile.
aks-node-controller/pkg/gen/aksnodeconfig/v1/localdns_config.pb.go	Regenerates protobuf bindings for enable_hosts_plugin.
aks-node-controller/parser/testdata/AKSUbuntu2204+LocalDNS/generatedCSECommand	Adds parser golden output for LocalDNS (no hosts plugin).
aks-node-controller/parser/testdata/AKSUbuntu2204+LocalDNS+HostsPlugin/generatedCSECommand	Adds parser golden output for LocalDNS with hosts plugin enabled.
aks-node-controller/parser/templates/localdns.toml.gtpl	Adds conditional hosts plugin blocks and updates template data shape ($.Config, $.IncludeHostsPlugin).
aks-node-controller/parser/parser_test.go	Adds parser tests covering hosts-plugin env var output.
aks-node-controller/parser/parser.go	Adds SHOULD_ENABLE_HOSTS_PLUGIN + dual corefile env vars to generated CSE environment.
aks-node-controller/parser/helper_test.go	Updates corefile base64 generation tests to new helper signature.
aks-node-controller/parser/helper.go	Implements hosts-plugin enablement + dual corefile generation for scriptless path.
.pipelines/scripts/verify_shell.sh	Marks aks-hosts-setup.sh as intentionally bash-only.

[Devinwong]

Could you add descriptions in the PR What this PR does / why we need it: for reviewers to understand what issues you are trying to solve?

[Copilot]

Pull request overview

Copilot reviewed 45 out of 45 changed files in this pull request and generated 1 comment.

[Copilot]

These error messages still say "using template", but GenerateLocalDNSCoreFile no longer takes a template argument and always uses the built-in localDNSCoreFileTemplateString. Updating the wording would make debugging clearer (e.g., "failed to generate localdns corefile" / "failed to generate base corefile").

Suggested change

	return "", fmt.Errorf("failed generate corefile for localdns using template: %w", err)
	}
	return base64.StdEncoding.EncodeToString([]byte(output)), nil
	},
	"GetGeneratedLocalDNSCoreFileBase": func() (string, error) {
	output, err := GenerateLocalDNSCoreFile(config, profile, false)
	if err != nil {
	return "", fmt.Errorf("failed generate base corefile for localdns using template: %w", err)
	}
	return base64.StdEncoding.EncodeToString([]byte(output)), nil
	},
	"GetGeneratedLocalDNSCoreFileExperimental": func() (string, error) {
	output, err := GenerateLocalDNSCoreFile(config, profile, true)
	if err != nil {
	return "", fmt.Errorf("failed generate experimental corefile for localdns using template: %w", err)
	return "", fmt.Errorf("failed to generate localdns corefile: %w", err)
	}
	return base64.StdEncoding.EncodeToString([]byte(output)), nil
	},
	"GetGeneratedLocalDNSCoreFileBase": func() (string, error) {
	output, err := GenerateLocalDNSCoreFile(config, profile, false)
	if err != nil {
	return "", fmt.Errorf("failed to generate base localdns corefile: %w", err)
	}
	return base64.StdEncoding.EncodeToString([]byte(output)), nil
	},
	"GetGeneratedLocalDNSCoreFileExperimental": func() (string, error) {
	output, err := GenerateLocalDNSCoreFile(config, profile, true)
	if err != nil {
	return "", fmt.Errorf("failed to generate experimental localdns corefile: %w", err)