aks-baseline: an AKS reference implementation built to be read

A reference implementation that refuses a one click install

Most infrastructure samples offer you a deployment button and a short README. aks-baseline does the opposite, and says why. The README states that the guidance here is relatively dense, encourages you to dedicate time to walking through the instructions, and explicitly says that no one click deployment is provided. The stated reason is that you should understand the relationship between the deployed resources, and it points you at the detailed architecture overview, stored as ./docs/aks-baseline_details.drawio.svg, while you explore.

That is a deliberate trade. You lose the convenience of a single pipeline run and gain a deployment where each layer can be argued about. The project describes itself as the recommended starting infrastructure architecture for a general purpose AKS cluster, and the README frames it as guidance for an interdisciplinary team, or several distinct teams such as networking, security and development, each of whom needs to understand the pieces they will share.

The companion article set on the Azure Architecture Center is not optional reading in the project's view. The README suggests reviewing it first, since it explains the challenges and design patterns behind this implementation, and describes the repository as the direct implementation of that specific architectural guidance.

Hub and spoke with every outbound connection through Azure Firewall

The network shape is the part of this implementation that changes what you can run afterwards. Azure virtual networks are laid out in a hub-spoke pattern, and the README lists Azure Firewall managed egress as the component in the spoke that controls outbound traffic. The architecture description also mentions a network topology that supports multiregional growth, which is the reason to pick hub-spoke over a single virtual network in the first place.

Traffic into the cluster arrives through Azure Application Gateway with the web application firewall enabled, and the cluster relies on AKS-managed internal load balancers for services that stay inside the estate. Nothing about that path is exposed by default to the public internet, and the workload itself is deliberately uninteresting: the ASP.NET Core Docker sample web app from the dotnet-docker repository is used as the example workload, present only so you can experience the baseline infrastructure.

Because the topology is shared, the repository splits deployment responsibility into a network-team directory alongside cluster-manifests and workload-team. The README is explicit that a deployment of AKS-hosted workloads typically separates duties across prerequisites, host network, cluster infrastructure and the workload itself, and that this implementation follows a similar approach.

Entra ID integration with local accounts switched off

Identity is where the baseline makes a decision you can feel later. The core component list names AKS-managed Microsoft Entra ID integration and Microsoft Entra ID-backed Kubernetes RBAC, with local user accounts disabled. That parenthetical matters: cluster administrators authenticate against the tenant directory rather than against a Kubernetes secret, so access to the cluster is tied to directory roles you already manage.

Managed identities appear in the same list, and they are the bridge between the cluster and other Azure services. The in-cluster component list adds Azure Workload Identity as an AKS-managed add-on, which lets pods authenticate to Azure resources without credentials stored in the cluster. The README describes the architecture as concentrating on the cluster itself, including concerns with identity, post-deployment configuration, secret management and network topologies, and calls the implementation the minimum recommended baseline for most AKS clusters.

Planning the integration is treated as a prerequisite task rather than a deployment detail. The checklist at the top of the deployment section points to separate documents for prerequisites, for procuring client-facing and AKS gateway TLS certificates, and for planning the Microsoft Entra ID integration, each under ./docs/deploy/. If your tenant has group naming rules or guest account policies, that planning step is where the friction appears, and it comes before any resource is created.

Node pool separation, CNI Overlay and add-ons the platform manages

The cluster component named in the README is AKS v1.34, configured with system and user node pool separation. Splitting the two means system components and your workloads run on different virtual machines, which changes both blast radius and capacity planning.

Networking inside the cluster uses Azure CNI Overlay, so pods get an address space from the virtual network without each consuming a routable address from the subnet. That choice sits underneath the hub-spoke design: overlay addressing keeps pod subnets small and leaves address space for the spoke growth the README describes.

Observability comes from Azure Monitor for containers, listed as a core component rather than an optional add-on. The whole list reads as a set of decisions that shift operational work onto managed services, and that is the point of a baseline. It is also where the upgrade cost sits. Azure CNI Overlay, Azure Monitor integration, the ImageCleaner add-on and the Secrets Store CSI Driver are all platform-maintained components whose behaviour changes with the AKS version you adopt, and the project tracks that through its own versioned releases rather than through a compatibility matrix you can rely on.

Flux, ImageCleaner and a CSI driver for secrets

The in-cluster open source components are deliberately few, and each has a stated role. Flux GitOps Operator comes in as an AKS-managed extension, so cluster configuration is expected to arrive from Git rather than from kubectl runs by hand. ImageCleaner (Eraser) is registered as an AKS-managed add-on and addresses a specific problem in the list of things that get deployed to a cluster but never used again.

Secret handling is covered by the Secrets Store CSI Driver for Kubernetes, again as an AKS-managed add-on. Paired with managed identities and Azure Workload Identity, it gives pods a way to read secrets from Azure without the secret values living in the cluster as base64 encoded strings in a manifest. The README describes secret management as one of the concerns the architecture concentrates on, alongside identity and post-deployment configuration.

Two limits are worth naming. The README describes this implementation as infrastructure focused, more so than workload, and says nothing about how your application images are built or promoted, so the Flux configuration in this repository is a starting point rather than a delivery pipeline you can adopt as is. Second, because these components are AKS-managed extensions and add-ons, they follow the service release cycle of the cluster rather than the schedule of this repository, which matters when you plan upgrades.

A fictional company stands in for your own

The reference implementation uses Contoso Bicycle throughout, and the README is candid about why. Contoso Bicycle is described as a fictional small and fast-growing startup providing online web services to clients on the west coast of North America, with no on-premises datacenters, moving its containerized line of business applications onto secure, enterprise-ready AKS clusters. Their requirements and IT team composition are documented under ./contoso-bicycle/README.md.

This narrative is doing real work rather than decoration. It grounds naming conventions, explains why the topology has the shape it has, and gives you a worked example of how a small team is divided. The README asks you to adapt it as you see fit, which is the honest instruction: the value in this repository is the structure and the reasoning, not the specific names.

That same framing is applied to the deployment itself. The README does not present the steps as a fixed procedure for every organisation. It says lifecycle and SDLC management of your cluster and its dependencies depends on your situation, team roles and organisational standards, and that once you have understood the components and identified the shared responsibilities between your team and your organisation, you should build suitable, auditable deployment processes around your final infrastructure. In other words, the repository hands you infrastructure, and asks your organisation to supply the process around it.

Reading the deployment documents in order

The practical entry point for an evaluator is the document list at the top of the deployment section, not the templates. The README asks you to start with the Preparing for the cluster section and follow it through to the end, ending with the recommended baseline cluster installed and an end-to-end sample workload running in your own Azure subscription. The steps that follow cover building the target network, and the document tree under ./docs/deploy/ holds the detail for each stage.

Two repository-level files are worth a look before you start. saveenv.sh sits at the top level next to the cluster manifests, which suggests environment variables are gathered in one place for the deployment scripts rather than typed into each step. CONTRIBUTING.md and SECURITY.md are also present, so the project has a defined process for contributions and a published security contact.

On licensing, the repository is MIT licensed with the licence text in LICENSE.md, which is a permissive licence and does not carry the file-level copyleft obligations some infrastructure projects do. Read LICENSE.md for the exact terms, and note that the licences of the Azure services and in-cluster components you deploy are separate from the licence of this template.

How often the baseline moves, and what a release gives you

The repository is not archived, and the last push was on 2026-10-01. Releases follow a versioning scheme of the form v1.36.0.0, with v1.36.0.0 published on 2026-07-08, v1.35.0.0 on 2026-04-19 and v1.34.0.0 on 2025-12-15. The pattern is roughly quarterly for the release tag, which gives you something to schedule against.

What a release contains is less clear than the tag suggests. No changelog entry is shown here, so you cannot tell from the tag alone whether a version bumps the AKS version, changes the network topology or only adjusts a template parameter. The AKS version named in the README is v1.34, which sits below the latest release tag of v1.36.0.0, so the cluster version and the repository version are not the same axis and should not be read as one.

For a team adopting this, the practical consequence is that upgrading means re-reading the templates rather than bumping a package. Because the deployment is deliberately staged rather than automated end to end, an upgrade can touch the network stage, the cluster stage or the workload stage independently, and the stage boundaries follow the network-team, cluster-manifests and workload-team split in the repository. If you need an unattended pipeline, you will be building that pipeline yourself around these stages, which the README also asks you to do.

Editorial conclusion

aks-baseline suits teams that want a defensible starting topology for AKS and have the appetite to walk the deployment steps rather than paste a script. It suits a pre-production or production cluster where identity, egress and GitOps are all in scope. It does not suit anyone wanting a fast single command install, since the project deliberately does not offer one, and it does not suit teams that already have a platform baseline they intend to keep. Before adopting, read the prerequisites document, confirm the split of responsibilities between the network, cluster and workload teams described in the repository layout, and check whether the AKS v1.34 baseline still matches the version your subscription team supports.

Frequently asked questions

Official sources

1. License: MIT
2. mspnp/aks-baseline on GitHub
3. Project website
4. README
5. Releases