AgentBaker
AGENTS.md158 starsChanged 45 days agoMITView on GitHub
AgentBaker repo has 2 main services discussed below: It builds VHDs using Packer for base OS: Windows, Azure Linux/Mariner and Ubuntu. For each OS there are multiple supported versions (windows 2019, 2022, ubuntu 2004, 2204 etc). The VHDs are base images for a node in an aks cluster. VHDs are built using Packer in vhdbuilder. Windows VHD is configured through VHD apiserver is go based webserver. It receives request from external client and generates CSE and CustomData to be used…
We split this AGENTS.md into the rules it gives an agent
9 rules. About 0 are common, 8 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 47
When opening a pull request against this repository, the PR's head branch must live in Azure/AgentBaker itself — not in a fork.
- Distinctive: line 56
avoid functional regression when introducing new features (component updates, new drivers, new binaries), ensure that all supported OS / …
- Distinctive: line 57
avoid VHD build performance regressions when making any changes
- Distinctive: line 58
avoid node provisioning performance regression when making any changes
- Distinctive: line 64
use shellcheck for sanity checking
- Distinctive: line 65
use ShellSpec for testing
- Distinctive: line 67
when using functions defined in other files, ensure it is sourced properly.
- Distinctive: line 68
use local variables rather than constants when their scoping allows for it.
- Distinctive: line 69
avoid using variables declared inside another function, even they are visible.
≈ “Common” is an estimate: at least 1 in 5 of the 36,368 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Overview
AgentBaker repo has 2 main services discussed below:
- VHD Builder
- AgentBaker Service
VHD Builder
It builds VHDs using Packer for base OS: Windows, Azure Linux/Mariner and Ubuntu. For each OS there are multiple supported versions (windows 2019, 2022, ubuntu 2004, 2204 etc). The VHDs are base images for a node in an aks cluster.
VHDs are built using Packer in vhdbuilder.
Windows VHD is configured through VHD
AgentBaker Service
apiserver is go based webserver. It receives request from external client and generates CSE and CustomData to be used on the VHD when a new node is created / provisioned.
windows generates its CSE package using script.
Both CSE scripts run in two phases — Windows BasePrep/NodePrep (kuberneteswindowssetup.ps1.template) and Linux basePrep/nodePrep (cse_main.sh). basePrep is gated only by the base_prep.complete marker, so it is skipped on a PIS-cached VHD (the marker is baked in); nodePrep runs whenever PreProvisionOnly is false — every real node. So node-specific, secret, or expiring data (e.g. the TLS bootstrap token / kubeconfig) must be written in nodePrep, not basePrep, or the baked copy goes stale. On PIS the phases are separate VM runs — variables re-initialize from the real node's live CustomData, so nodePrep can't rely on basePrep state. (Non-PIS: both run sequentially in one execution, no reboot between phases.)
The webserver is also used to determine the latest version of Linux VHDs available for provisioning within AKS clusters.
Code Structure
parts serves both AgentBaker Service and VHD build. AgentBaker service and VHDs are coupled because of this shared component. When building VHD, packer maps and renames scripts from parts depending on the OS / versions. The mappings can be found at packer.
Windows uses a different folder cse for almost the same purpose. There are subtle differences as windows CSEs can be downloaded as a zip file during provisioning time due to restrictions on the file size on Windows system, while for linux based systems the cse/custom data are dropped in during provisioning time.
Deployment and Release
The VHD build is triggered by Azure Devops pipelines. For release, the pipelines following the same templates for different OS versions:
- linux/ubuntu
- windows
you can reason the steps by following the steps defined in the pipeline.
Tags of AgentBaker and corresponding Linux VHDs are released every week. Linux VHDs are built with a particular image version in the YYYYMM.DD.PATCH format. All Linux VHD versions correspond to a particular tag of the AgentBaker go module. AgentBaker go module tags follow the format v0.YYYYMMDD.PATCH. The mapping between AgentBaker tag and Linux VHD version is defined within linux_sig_version.json.
Windows VHD are released separately, following windows patch tuesday schedule.
Contributing
When opening a pull request against this repository, the PR's head branch must live in Azure/AgentBaker itself — not in a fork.
Guidelines
SRE Guidelines
The operational goals of this project are:
- achieve consistency across different OS as much as possible
- avoid functional regression when introducing new features (component updates, new drivers, new binaries), ensure that all supported OS / versions are tested
- avoid VHD build performance regressions when making any changes
- avoid node provisioning performance regression when making any changes
When making changes, reason whether the file is used in VHD building stage, or provision stage, or both. Make sure the changes are valid in its life stage. as an example, windows-vhd-configuration.ps1 defines container images to be cached in VHD, while configure-windows-vhd.ps1 executes commands at provision time.
ShellScripts Guidelines
- use shellcheck for sanity checking
- use ShellSpec for testing
- the shell scripts are used on both azure linux/mariner and ubuntu and cross platform portability is critical.
- when using functions defined in other files, ensure it is sourced properly.
- use local variables rather than constants when their scoping allows for it.
- avoid using variables declared inside another function, even they are visible. It is hard to reason and might introduce subtle bugs.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 28,693 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository2 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- code-reviewSkill
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.