From d489591078dcbbb442f62aa484781eb754ddca51 Mon Sep 17 00:00:00 2001 From: John Downs Date: Tue, 16 Jul 2024 10:51:09 +1200 Subject: [PATCH 1/3] Move docs to new folder --- README.md | 28 +++++++++---------- .../01-prerequisites.md | 0 .../02-ca-certificates.md | 0 .../03-microsoft-entra-id.md | 0 04-networking.md => docs/04-networking.md | 0 .../05-bootstrap-prep.md | 0 06-aks-cluster.md => docs/06-aks-cluster.md | 0 .../07-bootstrap-validation.md | 0 .../08-workload-prerequisites.md | 0 ...ecret-management-and-ingress-controller.md | 0 10-workload.md => docs/10-workload.md | 0 11-validation.md => docs/11-validation.md | 0 12-cleanup.md => docs/12-cleanup.md | 0 .../aks-baseline_details.drawio.svg | 0 14 files changed, 14 insertions(+), 14 deletions(-) rename 01-prerequisites.md => docs/01-prerequisites.md (100%) rename 02-ca-certificates.md => docs/02-ca-certificates.md (100%) rename 03-microsoft-entra-id.md => docs/03-microsoft-entra-id.md (100%) rename 04-networking.md => docs/04-networking.md (100%) rename 05-bootstrap-prep.md => docs/05-bootstrap-prep.md (100%) rename 06-aks-cluster.md => docs/06-aks-cluster.md (100%) rename 07-bootstrap-validation.md => docs/07-bootstrap-validation.md (100%) rename 08-workload-prerequisites.md => docs/08-workload-prerequisites.md (100%) rename 09-secret-management-and-ingress-controller.md => docs/09-secret-management-and-ingress-controller.md (100%) rename 10-workload.md => docs/10-workload.md (100%) rename 11-validation.md => docs/11-validation.md (100%) rename 12-cleanup.md => docs/12-cleanup.md (100%) rename {networking => docs}/aks-baseline_details.drawio.svg (100%) diff --git a/README.md b/README.md index 78716c68..70fecdd4 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ This project has a companion set of articles that describe challenges, design pa The implementation presented here is the *minimum recommended baseline for most AKS clusters*. This implementation integrates with Azure services that will deliver observability, provide a network topology that will support multiregional growth, and keep the in-cluster traffic secure as well. This architecture should be considered your starting point for preproduction and production stages. -The material here is relatively dense. We strongly encourage you to dedicate time to walk through these instructions, with a mind to learning. Therefore, we do NOT provide any "one click" deployment here. To understand the relationship between the deployed resources, we suggest that you consult the [detailed architecture overview](/networking/aks-baseline_details.drawio.svg) while exploring your deployment. Once you've understood the components involved and identified the shared responsibilities between your team and your great organization, it is encouraged that you build suitable, auditable deployment processes around your final infrastructure. +The material here is relatively dense. We strongly encourage you to dedicate time to walk through these instructions, with a mind to learning. Therefore, we do NOT provide any "one click" deployment here. To understand the relationship between the deployed resources, we suggest that you consult the [detailed architecture overview](./docs/aks-baseline_details.drawio.svg) while exploring your deployment. Once you've understood the components involved and identified the shared responsibilities between your team and your great organization, it is encouraged that you build suitable, auditable deployment processes around your final infrastructure. Throughout the reference implementation, you will see reference to *Contoso Bicycle*. They are a fictional small and fast-growing startup that provides online web services to its clientele on the west coast of North America. They have no on-premises datacenters and all their containerized line of business applications are now about to be orchestrated by secure, enterprise-ready AKS clusters. You can read more about [their requirements and their IT team composition](./contoso-bicycle/README.md). This narrative provides grounding for some implementation details, naming conventions, and so on. You should adapt as you see fit. @@ -47,7 +47,7 @@ Finally, this implementation uses the [ASP.NET Core Docker sample web app](https ![Network diagram depicting a hub-spoke network with two peered VNets and main Azure resources used in the architecture.](https://learn.microsoft.com/azure/architecture/reference-architectures/containers/aks/images/secure-baseline-architecture.svg) -Also do not forget to view the [detailed architecture diagram](/networking/aks-baseline_details.drawio.svg) to understand how the deployed resources work together in this reference architecture. +Also do not forget to view the [detailed architecture diagram](./docs/aks-baseline_details.drawio.svg) to understand how the deployed resources work together in this reference architecture. ## Deploy the reference implementation @@ -59,23 +59,23 @@ A deployment of AKS-hosted workloads typically experiences a separation of dutie There are considerations that must be addressed before you start deploying your cluster. Do I have enough permissions in my subscription and AD tenant to do a deployment of this size? How much of this will be handled by my team directly vs having another team be responsible? -- [ ] Begin by ensuring you [install and meet the prerequisites](./01-prerequisites.md) -- [ ] [Procure client-facing and AKS Ingress Controller TLS certificates](./02-ca-certificates.md) -- [ ] [Plan your Microsoft Entra ID integration](./03-microsoft-entra-id.md) +- [ ] Begin by ensuring you [install and meet the prerequisites](./docs/01-prerequisites.md) +- [ ] [Procure client-facing and AKS Ingress Controller TLS certificates](./docs/02-ca-certificates.md) +- [ ] [Plan your Microsoft Entra ID integration](./docs/03-microsoft-entra-id.md) ### 2. Build target network Microsoft recommends AKS be deployed into a carefully planned network; sized appropriately for your needs and with proper network observability. Organizations typically favor a traditional hub-spoke model, which is reflected in this implementation. While this is a standard hub-spoke model, there are fundamental sizing and portioning considerations included that should be understood. -- [ ] [Build the hub-spoke network](./04-networking.md) +- [ ] [Build the hub-spoke network](./docs/04-networking.md) ### 3. Deploying the cluster This is the heart of the guidance in this reference implementation; paired with prior network topology guidance. Here you will deploy the Azure resources for your cluster and the adjacent services such as Azure Application Gateway WAF, Azure Monitor, Azure Container Registry, and Azure Key Vault. This is also where you will validate the cluster is bootstrapped. -- [ ] [Prep for cluster bootstrapping](./05-bootstrap-prep.md) -- [ ] [Deploy the AKS cluster and supporting services](./06-aks-cluster.md) -- [ ] [Validate cluster bootsrapping](./07-bootstrap-validation.md) +- [ ] [Prep for cluster bootstrapping](./docs/05-bootstrap-prep.md) +- [ ] [Deploy the AKS cluster and supporting services](./docs/06-aks-cluster.md) +- [ ] [Validate cluster bootstrapping](./docs/07-bootstrap-validation.md) We perform the prior steps manually here for you to understand the involved components, but we advocate for an automated DevOps process. Therefore, incorporate the prior steps into your CI/CD pipeline, as you would any infrastructure as code (IaC). See the dedicated [AKS baseline automation guidance](https://github.com/Azure/aks-baseline-automation#aks-baseline-automation) for additional details. @@ -83,21 +83,21 @@ We perform the prior steps manually here for you to understand the involved comp Without a workload deployed to the cluster it will be hard to see how these decisions come together to work as a reliable application platform for your business. The deployment of this workload would typically follow a CI/CD pattern and may involve even more advanced deployment strategies (such as blue/green). The following steps represent a manual deployment, suitable for illustration purposes of this infrastructure. -- [ ] Just like the cluster, there are [workload prerequisites to address](./08-workload-prerequisites.md) -- [ ] [Configure AKS Ingress Controller with Azure Key Vault integration](./09-secret-management-and-ingress-controller.md) -- [ ] [Deploy the workload](./10-workload.md) +- [ ] Just like the cluster, there are [workload prerequisites to address](./docs/08-workload-prerequisites.md) +- [ ] [Configure AKS Ingress Controller with Azure Key Vault integration](./docs/09-secret-management-and-ingress-controller.md) +- [ ] [Deploy the workload](./docs/10-workload.md) ### 5. :checkered_flag: Validation Now that the cluster and the sample workload is deployed; it's time to look at how the cluster is functioning. -- [ ] [Perform end-to-end deployment validation](./11-validation.md) +- [ ] [Perform end-to-end deployment validation](./docs/11-validation.md) ## :broom: Clean up resources Most of the Azure resources deployed in the prior steps will incur ongoing charges unless removed. -- [ ] [Cleanup all resources](./12-cleanup.md) +- [ ] [Clean up all resources](./docs/12-cleanup.md) ## Preview and additional features diff --git a/01-prerequisites.md b/docs/01-prerequisites.md similarity index 100% rename from 01-prerequisites.md rename to docs/01-prerequisites.md diff --git a/02-ca-certificates.md b/docs/02-ca-certificates.md similarity index 100% rename from 02-ca-certificates.md rename to docs/02-ca-certificates.md diff --git a/03-microsoft-entra-id.md b/docs/03-microsoft-entra-id.md similarity index 100% rename from 03-microsoft-entra-id.md rename to docs/03-microsoft-entra-id.md diff --git a/04-networking.md b/docs/04-networking.md similarity index 100% rename from 04-networking.md rename to docs/04-networking.md diff --git a/05-bootstrap-prep.md b/docs/05-bootstrap-prep.md similarity index 100% rename from 05-bootstrap-prep.md rename to docs/05-bootstrap-prep.md diff --git a/06-aks-cluster.md b/docs/06-aks-cluster.md similarity index 100% rename from 06-aks-cluster.md rename to docs/06-aks-cluster.md diff --git a/07-bootstrap-validation.md b/docs/07-bootstrap-validation.md similarity index 100% rename from 07-bootstrap-validation.md rename to docs/07-bootstrap-validation.md diff --git a/08-workload-prerequisites.md b/docs/08-workload-prerequisites.md similarity index 100% rename from 08-workload-prerequisites.md rename to docs/08-workload-prerequisites.md diff --git a/09-secret-management-and-ingress-controller.md b/docs/09-secret-management-and-ingress-controller.md similarity index 100% rename from 09-secret-management-and-ingress-controller.md rename to docs/09-secret-management-and-ingress-controller.md diff --git a/10-workload.md b/docs/10-workload.md similarity index 100% rename from 10-workload.md rename to docs/10-workload.md diff --git a/11-validation.md b/docs/11-validation.md similarity index 100% rename from 11-validation.md rename to docs/11-validation.md diff --git a/12-cleanup.md b/docs/12-cleanup.md similarity index 100% rename from 12-cleanup.md rename to docs/12-cleanup.md diff --git a/networking/aks-baseline_details.drawio.svg b/docs/aks-baseline_details.drawio.svg similarity index 100% rename from networking/aks-baseline_details.drawio.svg rename to docs/aks-baseline_details.drawio.svg From 73c07136281bb8fb26abf7443d7c5cc9a4edd5b8 Mon Sep 17 00:00:00 2001 From: John Downs Date: Tue, 16 Jul 2024 10:53:59 +1200 Subject: [PATCH 2/3] Move to correct folder --- README.md | 24 +++++++++---------- docs/{ => deploy}/01-prerequisites.md | 0 docs/{ => deploy}/02-ca-certificates.md | 0 docs/{ => deploy}/03-microsoft-entra-id.md | 0 docs/{ => deploy}/04-networking.md | 0 docs/{ => deploy}/05-bootstrap-prep.md | 0 docs/{ => deploy}/06-aks-cluster.md | 0 docs/{ => deploy}/07-bootstrap-validation.md | 0 .../{ => deploy}/08-workload-prerequisites.md | 0 ...ecret-management-and-ingress-controller.md | 0 docs/{ => deploy}/10-workload.md | 0 docs/{ => deploy}/11-validation.md | 0 docs/{ => deploy}/12-cleanup.md | 0 13 files changed, 12 insertions(+), 12 deletions(-) rename docs/{ => deploy}/01-prerequisites.md (100%) rename docs/{ => deploy}/02-ca-certificates.md (100%) rename docs/{ => deploy}/03-microsoft-entra-id.md (100%) rename docs/{ => deploy}/04-networking.md (100%) rename docs/{ => deploy}/05-bootstrap-prep.md (100%) rename docs/{ => deploy}/06-aks-cluster.md (100%) rename docs/{ => deploy}/07-bootstrap-validation.md (100%) rename docs/{ => deploy}/08-workload-prerequisites.md (100%) rename docs/{ => deploy}/09-secret-management-and-ingress-controller.md (100%) rename docs/{ => deploy}/10-workload.md (100%) rename docs/{ => deploy}/11-validation.md (100%) rename docs/{ => deploy}/12-cleanup.md (100%) diff --git a/README.md b/README.md index 70fecdd4..4b5275e2 100644 --- a/README.md +++ b/README.md @@ -59,23 +59,23 @@ A deployment of AKS-hosted workloads typically experiences a separation of dutie There are considerations that must be addressed before you start deploying your cluster. Do I have enough permissions in my subscription and AD tenant to do a deployment of this size? How much of this will be handled by my team directly vs having another team be responsible? -- [ ] Begin by ensuring you [install and meet the prerequisites](./docs/01-prerequisites.md) -- [ ] [Procure client-facing and AKS Ingress Controller TLS certificates](./docs/02-ca-certificates.md) -- [ ] [Plan your Microsoft Entra ID integration](./docs/03-microsoft-entra-id.md) +- [ ] Begin by ensuring you [install and meet the prerequisites](./docs/deploy/01-prerequisites.md) +- [ ] [Procure client-facing and AKS Ingress Controller TLS certificates](./docs/deploy/02-ca-certificates.md) +- [ ] [Plan your Microsoft Entra ID integration](./docs/deploy/03-microsoft-entra-id.md) ### 2. Build target network Microsoft recommends AKS be deployed into a carefully planned network; sized appropriately for your needs and with proper network observability. Organizations typically favor a traditional hub-spoke model, which is reflected in this implementation. While this is a standard hub-spoke model, there are fundamental sizing and portioning considerations included that should be understood. -- [ ] [Build the hub-spoke network](./docs/04-networking.md) +- [ ] [Build the hub-spoke network](./docs/deploy/04-networking.md) ### 3. Deploying the cluster This is the heart of the guidance in this reference implementation; paired with prior network topology guidance. Here you will deploy the Azure resources for your cluster and the adjacent services such as Azure Application Gateway WAF, Azure Monitor, Azure Container Registry, and Azure Key Vault. This is also where you will validate the cluster is bootstrapped. -- [ ] [Prep for cluster bootstrapping](./docs/05-bootstrap-prep.md) -- [ ] [Deploy the AKS cluster and supporting services](./docs/06-aks-cluster.md) -- [ ] [Validate cluster bootstrapping](./docs/07-bootstrap-validation.md) +- [ ] [Prep for cluster bootstrapping](./docs/deploy/05-bootstrap-prep.md) +- [ ] [Deploy the AKS cluster and supporting services](./docs/deploy/06-aks-cluster.md) +- [ ] [Validate cluster bootstrapping](./docs/deploy/07-bootstrap-validation.md) We perform the prior steps manually here for you to understand the involved components, but we advocate for an automated DevOps process. Therefore, incorporate the prior steps into your CI/CD pipeline, as you would any infrastructure as code (IaC). See the dedicated [AKS baseline automation guidance](https://github.com/Azure/aks-baseline-automation#aks-baseline-automation) for additional details. @@ -83,21 +83,21 @@ We perform the prior steps manually here for you to understand the involved comp Without a workload deployed to the cluster it will be hard to see how these decisions come together to work as a reliable application platform for your business. The deployment of this workload would typically follow a CI/CD pattern and may involve even more advanced deployment strategies (such as blue/green). The following steps represent a manual deployment, suitable for illustration purposes of this infrastructure. -- [ ] Just like the cluster, there are [workload prerequisites to address](./docs/08-workload-prerequisites.md) -- [ ] [Configure AKS Ingress Controller with Azure Key Vault integration](./docs/09-secret-management-and-ingress-controller.md) -- [ ] [Deploy the workload](./docs/10-workload.md) +- [ ] Just like the cluster, there are [workload prerequisites to address](./docs/deploy/08-workload-prerequisites.md) +- [ ] [Configure AKS Ingress Controller with Azure Key Vault integration](./docs/deploy/09-secret-management-and-ingress-controller.md) +- [ ] [Deploy the workload](./docs/deploy/10-workload.md) ### 5. :checkered_flag: Validation Now that the cluster and the sample workload is deployed; it's time to look at how the cluster is functioning. -- [ ] [Perform end-to-end deployment validation](./docs/11-validation.md) +- [ ] [Perform end-to-end deployment validation](./docs/deploy/11-validation.md) ## :broom: Clean up resources Most of the Azure resources deployed in the prior steps will incur ongoing charges unless removed. -- [ ] [Clean up all resources](./docs/12-cleanup.md) +- [ ] [Clean up all resources](./docs/deploy/12-cleanup.md) ## Preview and additional features diff --git a/docs/01-prerequisites.md b/docs/deploy/01-prerequisites.md similarity index 100% rename from docs/01-prerequisites.md rename to docs/deploy/01-prerequisites.md diff --git a/docs/02-ca-certificates.md b/docs/deploy/02-ca-certificates.md similarity index 100% rename from docs/02-ca-certificates.md rename to docs/deploy/02-ca-certificates.md diff --git a/docs/03-microsoft-entra-id.md b/docs/deploy/03-microsoft-entra-id.md similarity index 100% rename from docs/03-microsoft-entra-id.md rename to docs/deploy/03-microsoft-entra-id.md diff --git a/docs/04-networking.md b/docs/deploy/04-networking.md similarity index 100% rename from docs/04-networking.md rename to docs/deploy/04-networking.md diff --git a/docs/05-bootstrap-prep.md b/docs/deploy/05-bootstrap-prep.md similarity index 100% rename from docs/05-bootstrap-prep.md rename to docs/deploy/05-bootstrap-prep.md diff --git a/docs/06-aks-cluster.md b/docs/deploy/06-aks-cluster.md similarity index 100% rename from docs/06-aks-cluster.md rename to docs/deploy/06-aks-cluster.md diff --git a/docs/07-bootstrap-validation.md b/docs/deploy/07-bootstrap-validation.md similarity index 100% rename from docs/07-bootstrap-validation.md rename to docs/deploy/07-bootstrap-validation.md diff --git a/docs/08-workload-prerequisites.md b/docs/deploy/08-workload-prerequisites.md similarity index 100% rename from docs/08-workload-prerequisites.md rename to docs/deploy/08-workload-prerequisites.md diff --git a/docs/09-secret-management-and-ingress-controller.md b/docs/deploy/09-secret-management-and-ingress-controller.md similarity index 100% rename from docs/09-secret-management-and-ingress-controller.md rename to docs/deploy/09-secret-management-and-ingress-controller.md diff --git a/docs/10-workload.md b/docs/deploy/10-workload.md similarity index 100% rename from docs/10-workload.md rename to docs/deploy/10-workload.md diff --git a/docs/11-validation.md b/docs/deploy/11-validation.md similarity index 100% rename from docs/11-validation.md rename to docs/deploy/11-validation.md diff --git a/docs/12-cleanup.md b/docs/deploy/12-cleanup.md similarity index 100% rename from docs/12-cleanup.md rename to docs/deploy/12-cleanup.md From e27454616654f2795391dd96810e0145c1dc58c2 Mon Sep 17 00:00:00 2001 From: John Downs Date: Tue, 16 Jul 2024 11:38:15 +1200 Subject: [PATCH 3/3] Fix relative links --- docs/deploy/04-networking.md | 2 +- docs/deploy/05-bootstrap-prep.md | 2 +- docs/deploy/06-aks-cluster.md | 2 +- docs/deploy/08-workload-prerequisites.md | 2 +- docs/deploy/11-validation.md | 2 +- docs/deploy/12-cleanup.md | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/deploy/04-networking.md b/docs/deploy/04-networking.md index b5ffc581..22e99404 100644 --- a/docs/deploy/04-networking.md +++ b/docs/deploy/04-networking.md @@ -1,6 +1,6 @@ # Deploy the hub-spoke network topology -The prerequisites for the [AKS baseline cluster](./) are now completed with [Microsoft Entra group and user work](./03-microsoft-entra-id.md) performed in the prior steps. Now we will start with our first Azure resource deployment, the network resources. +The prerequisites for the [AKS baseline cluster](../../) are now completed with [Microsoft Entra group and user work](./03-microsoft-entra-id.md) performed in the prior steps. Now we will start with our first Azure resource deployment, the network resources. ## Subscription and resource group topology diff --git a/docs/deploy/05-bootstrap-prep.md b/docs/deploy/05-bootstrap-prep.md index 4f300b0c..1a9d5b36 100644 --- a/docs/deploy/05-bootstrap-prep.md +++ b/docs/deploy/05-bootstrap-prep.md @@ -1,6 +1,6 @@ # Prep for cluster bootstrapping -Now that the [hub-spoke network is provisioned](./04-networking.md), the next step in the [AKS baseline reference implementation](./) is preparing what your AKS cluster should be bootstrapped with. +Now that the [hub-spoke network is provisioned](./04-networking.md), the next step in the [AKS baseline reference implementation](../../) is preparing what your AKS cluster should be bootstrapped with. ## Expected results diff --git a/docs/deploy/06-aks-cluster.md b/docs/deploy/06-aks-cluster.md index 063f9df3..d9b988f3 100644 --- a/docs/deploy/06-aks-cluster.md +++ b/docs/deploy/06-aks-cluster.md @@ -1,6 +1,6 @@ # Deploy the AKS cluster -Now that your [Azure Container Registry instance is deployed and ready to support cluster bootstrapping](./05-bootstrap-prep.md), the next step in the [AKS baseline reference implementation](./) is deploying the AKS cluster and its remaining adjacent Azure resources. +Now that your [Azure Container Registry instance is deployed and ready to support cluster bootstrapping](./05-bootstrap-prep.md), the next step in the [AKS baseline reference implementation](../../) is deploying the AKS cluster and its remaining adjacent Azure resources. ## Steps diff --git a/docs/deploy/08-workload-prerequisites.md b/docs/deploy/08-workload-prerequisites.md index a6c3dac8..fdfcdd4b 100644 --- a/docs/deploy/08-workload-prerequisites.md +++ b/docs/deploy/08-workload-prerequisites.md @@ -1,6 +1,6 @@ # Workload prerequisites -The AKS Cluster has been [bootstrapped](./07-bootstrap-validation.md), wrapping up the infrastructure focus of the [AKS baseline reference implementation](./). Follow these steps to import the TLS certificate that the ingress controller will serve for Application Gateway to connect to your web app. +The AKS Cluster has been [bootstrapped](./07-bootstrap-validation.md), wrapping up the infrastructure focus of the [AKS baseline reference implementation](../../). Follow these steps to import the TLS certificate that the ingress controller will serve for Application Gateway to connect to your web app. ## Steps diff --git a/docs/deploy/11-validation.md b/docs/deploy/11-validation.md index 52ef965d..6ef14bb2 100644 --- a/docs/deploy/11-validation.md +++ b/docs/deploy/11-validation.md @@ -1,6 +1,6 @@ # End-to-end validation -Now that you have a workload deployed, the [ASP.NET Core sample web app](./10-workload.md), you can start validating and exploring this reference implementation of the [AKS baseline cluster](./). In addition to the workload, there is some observability validation you can perform as well. +Now that you have a workload deployed, the [ASP.NET Core sample web app](./10-workload.md), you can start validating and exploring this reference implementation of the [AKS baseline cluster](../../). In addition to the workload, there is some observability validation you can perform as well. ## Validate the web app diff --git a/docs/deploy/12-cleanup.md b/docs/deploy/12-cleanup.md index bfef4401..82650101 100644 --- a/docs/deploy/12-cleanup.md +++ b/docs/deploy/12-cleanup.md @@ -1,6 +1,6 @@ # Clean up -After you are done exploring your deployed [AKS baseline cluster](./), you'll want to delete the created Azure resources to prevent undesired costs from accruing. Follow these steps to delete all resources created as part of this reference implementation. +After you are done exploring your deployed [AKS baseline cluster](../../), you'll want to delete the created Azure resources to prevent undesired costs from accruing. Follow these steps to delete all resources created as part of this reference implementation. ## Steps