feat: ALZ TF intro documentation (#3)

* wip: alztf docs

* feat: finalize intro config

* fix: review issues

* fix: tf title

* fix: further review updates

* docs: add developer guide

.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: |

DEVELOPER.md

@@ -0,0 +1,25 @@
+# Developer Guide
+
+## Pre-Requisites
+
+You will need Hugo installed on your machine to build the documentation. You can download Hugo from the [Hugo website](https://gohugo.io/installation/).
+Make sure you install the same version as the one specified in the `.github/workflows/hugo.yml` file.
+
+## Creating a local HTTP server
+
+To create a local HTTP server, if you have GNU make installed, run the following command:
+
+```bash
+make server
+```
+
+Alternatively, you can run the following commands:
+
+```bash
+cd docs
+hugo server
+```
+
+The server will start and you can access the documentation at <http://localhost:1313/Azure-Landing-Zones/>.
+
+You can stop the server by pressing `Ctrl+C`.

README.md

@@ -14,7 +14,7 @@ Please see the documentation site <https://azure.github.io/Azure-Landing-Zones/>
 
 This project welcomes contributions and suggestions.  Most contributions require you to agree to a
 Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
-the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
+the rights to use your contribution. For details, visit <https://cla.opensource.microsoft.com>.
 
 When you submit a pull request, a CLA bot will automatically determine whether you need to provide
 a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
@@ -24,6 +24,10 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
 For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
 contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
 
+## Developing
+
+See [DEVELOPER.md](DEVELOPER.md) for information on how to build and test the project.
+
 ## Trademarks
 
 This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft

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,10 @@
 ---
 title: Azure Landing Zones Documentation
-geekdocNav: true
-geekdocAlign: left
-geekdocAnchor: true
+resources:
+  - name: alz-journey
+    src: img/customer-landing-zone-journey.png
+    alt: Azure Landing Zones Journey
+    title: Azure Landing Zones Journey
 ---
 
 Welcome to the Azure Landing Zones technical documentation site.
@@ -16,43 +18,17 @@ Please see our [documentation on Learn](https://learn.microsoft.com/azure/cloud-
 
 ## The Azure Landing Zones Journey
 
-The Azure Landing Zones journey is a multi-step process that starts with the enterprise bootstrap and ends with the deployment of workloads.
+The Azure Landing Zones journey is a multi-step process that starts with bootstrapping your environment and ends with the deployment of workloads.
 
-```mermaid
-graph LR;
-    A[Enterprise bootstrap] --> B[Azure Landing Zones platform];
-    B --> C[Subscription vending];
-    C --> D[Applicaiton landing zones];
-    D --> E[Workloads];
-```
+{{< img name="alz-journey" size="large" lazy=true >}}
 
-### Enterprise bootstrap
+### Bootstrap your environment
 
-The enterprise bootstrap is the first step in the Azure Landing Zones journey.
+The 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 [bootstrap](bootstrap) section for more information.
 
 ### Azure Landing Zones platform
 
@@ -74,7 +50,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 +59,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 [bootstrap your environment](bootstrap) process.

docs/content/accelerator/_index.md

@@ -0,0 +1,5 @@
+---
+title: Accelerator
+---
+
+TBC...

docs/content/bicep/_index.md

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

docs/content/bootstrap.md

@@ -0,0 +1,48 @@
+---
+title: Bootstrap your environment
+---
+
+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:
+
+- [**Accelerator**](/Azure-Landing-Zones/accelerator/)
+
+You can also opt to use Bicep and Terraform directly:
+
+- [**Bicep**](/Azure-Landing-Zones/bicep/)
+- [**Terraform**](/Azure-Landing-Zones/terraform/)

docs/content/terraform/1_managementcomponents.md

@@ -0,0 +1,41 @@
+---
+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.
+
+## Next Steps
+
+Add networking components to your Azure Landing Zone by following the [Networking](2_networking) guide.

docs/content/terraform/2_networking.md

@@ -0,0 +1,5 @@
+---
+Title: 2. Networking
+---
+
+TBC...