wip: alztf docs

.github/workflows/hugo.yml

@@ -37,7 +37,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     env:
-      HUGO_VERSION: 0.128.2
+      HUGO_VERSION: 0.136.5
     steps:
       - name: Install Hugo CLI
         run: |

docs/.gitignore

@@ -10,3 +10,7 @@ hugo.linux
 
 # Temporary lock file while building
 .hugo_build.lock
+
+# Exclude Terraform files used for testing examples
+.terraform
+.terraform.lock.hcl

docs/content/_index.md

@@ -1,8 +1,5 @@
 ---
 title: Azure Landing Zones Documentation
-geekdocNav: true
-geekdocAlign: left
-geekdocAnchor: true
 ---
 
 Welcome to the Azure Landing Zones technical documentation site.
@@ -22,7 +19,7 @@ The Azure Landing Zones journey is a multi-step process that starts with the ent
 graph LR;
     A[Enterprise bootstrap] --> B[Azure Landing Zones platform];
     B --> C[Subscription vending];
-    C --> D[Applicaiton landing zones];
+    C --> D[Application landing zones];
     D --> E[Workloads];
 ```
 
@@ -32,27 +29,7 @@ The enterprise bootstrap is the first step in the Azure Landing Zones journey.
 It is the process of setting up the foundational components that will be used to deploy and manage Azure Landing Zones.
 In this step we ensure we have the correct access and some subscriptions to work with.
 
-### Access
-
-You will need the correct access to Azure to deploy the core components for Azure Landing Zones.
-You need to be able to create management groups, and assign policy and roles.
-The built-in role `Management Group Contributor` provides the necessary permissions to create and manage management groups.
-This is typically assigned at the parent management group under which the Azure Landing Zones will be deployed.
-
-It is also possible to have a organizational root management group provided to you by your organization but you will require `Owner` permissions on this management group to deploy the Azure Landing Zones platform.
-This is becasue Azure Landing Zones assigns policies with DeployIfNotExists and modify effects, which require role assignments to be created.
-
-### Azure subscriptions
-
-You will need some Azure subscriptions to work with to deploy the core compoents for Azure Landing Zones, e.g. the central Log Analytics workspace, the core networking components, etc.
-
-We typically recommend these subscriptions are created in the Azure Portal or using the CLI tools.
-
-We recommend the following subscriptions:
-
-- **connectivity** - this subscription is used to deploy the core networking components for the Azure Landing Zones.
-- **management** - this subscription is used to deploy the core management components for the Azure Landing Zones.
-- **identity** (Optional) - this subscription is used to host AD-DS domain controllers.
+See the [Enterprise Bootstrap](enterprisebootstrap) section for more information.
 
 ### Azure Landing Zones platform
 
@@ -74,7 +51,7 @@ The reference management group and policy structure for Azure Landing Zones is p
 Subscription vending is the process of automating the creation of new subscriptions for use by the organization.
 
 To be able to automate the creation of subscriptions, you will need to have the correct permissions.
-These permissions are asssigned at the billing scope and the process is documented [here](https://learn.microsoft.com/azure/cost-management-billing/manage/programmatically-create-subscription).
+These permissions are assigned at the billing scope and the process is documented [here](https://learn.microsoft.com/azure/cost-management-billing/manage/programmatically-create-subscription).
 
 ### Application landing zones
 
@@ -83,3 +60,7 @@ Application landing zones build upon subscription vending to provide application
 ### Workloads
 
 Workloads are the applications and services that are deployed into the Azure Landing Zones.
+
+## Next steps
+
+To get started with the Azure Landing Zones journey, let's look at the [enterprise bootstrap](enterprisebootstrap) process.

docs/content/accalerator/_index.md

@@ -1,8 +1,5 @@
 ---
 title: Accelerator
-geekdocNav: true
-geekdocAlign: left
-geekdocAnchor: true
 ---
 
 TBC...

docs/content/bicep/2_platform.md.md

@@ -1,8 +1,5 @@
 ---
 title: 2. Platform
-geekdocNav: true
-geekdocAlign: left
-geekdocAnchor: true
 ---
 
 TBC...

docs/content/bicep/3_networking.md

@@ -1,8 +1,5 @@
 ---
 title: 3. Networking
-geekdocNav: true
-geekdocAlign: left
-geekdocAnchor: true
 ---
 
 TBC...

docs/content/bicep/4_subscriptionvending.md

@@ -1,8 +1,5 @@
 ---
 title: 4. Subscription Vending
-geekdocNav: true
-geekdocAlign: left
-geekdocAnchor: true
 ---
 
 TBC...

docs/content/bicep/5_applicationlandingzones.md

@@ -1,8 +1,5 @@
 ---
 title: 5. Application Landing Zones
-geekdocNav: true
-geekdocAlign: left
-geekdocAnchor: true
 ---
 
 TBC...

docs/content/bicep/_index.md

@@ -1,8 +1,5 @@
 ---
 title: Bicep
-geekdocNav: true
-geekdocAlign: left
-geekdocAnchor: true
 ---
 
 TBC...

docs/content/enterprisebootstrap.md

@@ -0,0 +1,47 @@
+---
+title: Enterprise Bootstrap
+---
+
+Before we begin our Azure Landing Zones journey proper, we need some pre-requisites in place.
+
+## Azure Subscriptions
+
+We recommend setting up 3 subscriptions for Azure landing zones.
+These are management, identity and connectivity.
+
+- **Management**: This is used to deploy the bootstrap and management resources, such as log analytics and automation accounts.
+- **Connectivity**: This is used to deploy the hub networking resources, such as virtual networks and firewalls.
+- **Identity**: (Optional) This is used to deploy the identity resources, such as Azure AD and Azure AD Domain Services. You will not need this if you do not have any AD-DS or [Entra Domain Services](https://azure.microsoft.com/products/microsoft-entra-ds) requirements.
+
+You can read more about the management, identity and connectivity subscriptions in the [Landing Zone docs](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/deploy-landing-zones-with-terraform).
+
+To create the subscriptions you will need access to a billing agreement.
+The following links detail the permissions required for each type of agreement:
+
+- [Enterprise Agreement (EA)](https://learn.microsoft.com/en-us/azure/cost-management-billing/manage/create-enterprise-subscription)
+- [Microsoft Customer Agreement (MCA)](https://learn.microsoft.com/en-us/azure/cost-management-billing/manage/create-subscription)
+
+Once you have the access required, create the three subscriptions following your desired naming convention.
+
+Take note of the subscription id of each subscription as we will need them later.
+
+## Azure Authentication and Permissions
+
+You need either an Azure User Account or Service Principal with the following permissions to run the bootstrap:
+
+- `Owner` on your chosen parent management group for the Azure landing zone. This could be `Tenant Root Group` or a new management group you create under there if preferred.
+  - Owner is required as this account will be granting permissions for the identities that run the management group deployment. Those identities will be granted least privilege permissions.
+- `Owner` on each of your Azure landing zone subscriptions.
+
+## Next Steps
+
+Now choose your next step!
+
+The Accelerator allows you to quickly get started with IaC and DevOps best practices for Azure Landing Zones.
+It supports both Terraform and Bicep.
+
+You can also opt to use Bicep and Terraform directly.
+
+- [**Accelerator**](/Azure-Landing-Zones/accelerator/)
+- [**Bicep**](/Azure-Landing-Zones/bicep/)
+- [**Terraform**](/Azure-Landing-Zones/terraform/)

docs/content/terraform/1_managementcomponents.md

@@ -0,0 +1,37 @@
+---
+title: 1. Management components
+---
+
+Core to Azure Landing Zones is the concept of centralized logging.
+We recommend beginning with the deployment of the management components, which include the following:
+
+- **Log Analytics workspace**: Used to collect and analyze logs from Azure resources.
+- **Automation account**: (Optional) Used to automate tasks in Azure.
+- **Azure Monitor Agent Resources**: The identity and data collection rules required for AMA.
+
+We have a Terraform module that deploys these resources for you: <https://registry.terraform.io/modules/Azure/avm-ptn-alz-management/azurerm/latest>
+
+## Getting started
+
+First let's create a `terraform.tf` file in a new directory and add the following code:
+
+{{< include file="/static/examples/tf/1_management/terraform.tf" language="terraform" >}}
+
+Here we specify the minimum version of Terraform we want to use.
+We set [pessimistic version constraints](https://developer.hashicorp.com/terraform/language/expressions/version-constraints) to allow only the minor version to change.
+This will prevent a new major version from being used, which could introduce breaking changes.
+
+## Add the ALZ Management module
+
+Create a file called `main.tf` in the same directory and add the following code:
+
+{{< include file="/static/examples/tf/1_management/main.tf" language="terraform" >}}
+
+## Plan and apply
+
+We recommend using CI/CD to deploy your infrastructure, the Accelerator is a great way to get started with this.
+However you can also run Terraform locally:
+
+Run `terraform init` to download the module and initialize the directory.
+Next, run `terraform plan` to see what resources will be created.
+Finally, run `terraform apply` to create the resources.

docs/content/terraform/3_subscriptionvending.md

@@ -0,0 +1,5 @@
+---
+title: 2. Subscription Vending
+---
+
+TBC...

docs/content/terraform/4_applicationlandingzones.md

@@ -0,0 +1,5 @@
+---
+title: 5. Application Landing Zones
+---
+
+TBC...

docs/content/terraform/_index.md

@@ -1,8 +1,58 @@
 ---
-title: Terraform
-geekdocNav: true
-geekdocAlign: left
-geekdocAnchor: true
+title: Azure Landing Zones with Terraform
 ---
 
-TBC...
+ALZ ❤️ AVM - A new approach to Azure Landing Zones with Terraform
+
+Based on continuous feedback from the community, we have adopted a more modular approach to deploying Azure Landing Zones with Terraform.
+This new approach is based on the Azure Virtual Network Module (AVM) and is designed to be more flexible.
+
+## Why have we made this change?
+
+We received feedback from our community that the following improvements were needed:
+
+### Customization
+
+You asked us to be able to fully customize the configuration of each component.
+Examples included defining a custom management group hierarchy, or setting specific settings (and names!) on resources.
+This requirement was front and center in our minds when designing the new approach.
+
+***You can now fully customize the configuration of each component (including the resource names 😇).***
+
+### Modularity
+
+You didn't like that the module contained a combination of components that you may not need, and that you had to deploy the entire module even if you only wanted to use a subset of the components.
+
+You also asked that we make it easier for organizations to have different teams manage different components of the Azure Landing Zone.
+
+***You can now choose your own adventure and pick and choose only the components you need.***
+
+## What is the new approach?
+
+The new approach is based on  Azure Virtual Network Modules (AVM) and is designed to be more flexible.
+
+Here is the list of modules that pertain to Azure Landing Zones and covers the scope of the original ALZ Terraform module:
+
+- [ALZ core](https://registry.terraform.io/modules/Azure/avm-ptn-alz/azurerm/latest)
+- [ALZ management](https://registry.terraform.io/modules/Azure/avm-ptn-alz-management/azurerm/latest)
+- [Hub networking](https://registry.terraform.io/modules/Azure/avm-ptn-hubnetworking/azurerm/latest)
+- [Virtual network gateway](https://registry.terraform.io/modules/Azure/avm-ptn-virtualwan/azurerm/latest)
+- [Virtual WAN](https://registry.terraform.io/modules/Azure/avm-ptn-virtualwan/azurerm/latest)
+- [Private link DNS zones](https://registry.terraform.io/modules/Azure/avm-ptn-network-private-link-private-dns-zones/azurerm/latest)
+
+Using these modules together, you can create a fully customized Azure Landing Zone.
+
+## How do I get started?
+
+We recognize that this is a significant change, and we want to make it as easy as possible for you to get started.
+We have created this documentation site to centralize the integration documentation for the new modular approach.
+
+In here you will find examples and guidance on how to use the new modules to build your very own Azure Landing Zone.
+
+{{< hint type=note title="Deployment order" >}}
+We recommend deploying the management components first, followed by the hub networking components and then finally the management groups and policy.
+
+This is because we need certain resources to exist so that we can reference them in Azure Policy.
+{{< /hint >}}
+
+[Get started with deploying the management components](1_managementcomponents)

docs/hugo.toml

@@ -27,7 +27,7 @@ tag = "tags"
 [params]
 # (Optional, default 6) Set how many table of contents levels to be showed on page.
 # Use false to hide ToC, note that 0 will default to 6 (https://gohugo.io/functions/default/)
-# You can also specify this parameter per page in front matter.
+# You can also specify this paramet.Site.IsMultiLingualer per page in front matter.
 geekdocToC = 2
 
 # (Optional, default static/brand.svg) Set the path to a logo for the Geekdoc
@@ -42,6 +42,15 @@ geekdocMenuBundle = false
 # per page if enabled. Can be enabled per page via 'geekdocCollapseSection'.
 geekdocCollapseAllSections = false
 
+# Defautl align left
+geekdocAlign = "left"
+
+# Default include nav
+geekdockNav = true
+
+# Defautl include anchor
+geekdockAnchor = true
+
 # (Optional, default true) Show page navigation links at the bottom of each
 # docs page (bundle menu only).
 geekdocNextPrev = true