From 247313fa20913a346ab127b1e06ec4b5f5494f74 Mon Sep 17 00:00:00 2001 From: Jared Holgate Date: Fri, 13 Dec 2024 17:36:13 +0000 Subject: [PATCH] feat: accelerator doc improvements (#11) * Split Bicep and Terraform onto separate pages * Tidy docs and links * Fix links * Update docs/content/accelerator/userguide/2_start/bicep-azuredevops.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/content/accelerator/userguide/2_start/bicep-azuredevops.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/content/accelerator/userguide/2_start/bicep-github.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/content/accelerator/userguide/2_start/bicep-github.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Spelling * Add configurable preview banner * Add configurable title --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/content/accelerator/_index.md | 10 +- docs/content/accelerator/faq.md | 65 ++----- .../userguide/2_start/2b_azuredevops.md | 181 ------------------ .../accelerator/userguide/2_start/_index.md | 27 ++- .../userguide/2_start/bicep-azuredevops.md | 87 +++++++++ .../userguide/2_start/bicep-github.md | 79 ++++++++ .../userguide/2_start/bicep-local.md | 74 +++++++ .../2_start/terraform-azuredevops.md | 122 ++++++++++++ .../{2a_github.md => terraform-github.md} | 122 ++++-------- .../{2c_local.md => terraform-local.md} | 117 ++++------- docs/hugo.toml | 3 + .../layouts/partials/site-header.html | 10 + 12 files changed, 489 insertions(+), 408 deletions(-) delete mode 100644 docs/content/accelerator/userguide/2_start/2b_azuredevops.md create mode 100644 docs/content/accelerator/userguide/2_start/bicep-azuredevops.md create mode 100644 docs/content/accelerator/userguide/2_start/bicep-github.md create mode 100644 docs/content/accelerator/userguide/2_start/bicep-local.md create mode 100644 docs/content/accelerator/userguide/2_start/terraform-azuredevops.md rename docs/content/accelerator/userguide/2_start/{2a_github.md => terraform-github.md} (50%) rename docs/content/accelerator/userguide/2_start/{2c_local.md => terraform-local.md} (50%) diff --git a/docs/content/accelerator/_index.md b/docs/content/accelerator/_index.md index bc9c073..470e470 100644 --- a/docs/content/accelerator/_index.md +++ b/docs/content/accelerator/_index.md @@ -13,7 +13,7 @@ resources: Welcome to the Azure Landing Zones Accelerators for Bicep and Terraform! -The Azure landing zones [Terraform][alz_tf_module] and [Bicep][alz_bc_module] modules provide an opinionated approach for deploying and managing the core platform capabilities of [Azure landing zones architecture][alz_architecture] using Bicep or Terraform. +The Azure landing zones [Terraform](https://github.com/Azure/alz-terraform-accelerator/tree/main/templates/platform_landing_zone) and [Bicep](https://github.com/Azure/ALZ-Bicep) modules provide an opinionated approach for deploying and managing the core platform capabilities of [Azure landing zones architecture](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone#azure-landing-zone-conceptual-architecture) using Bicep or Terraform. This accelerator provides an opinionated approach for configuring and securing those modules in a continuous delivery environment. It has end to end automation for bootstrapping the modules. @@ -119,10 +119,4 @@ Check out the [User Guide]({{< relref "userguide" >}}). The following diagram and links detail the Azure landing zone, but you can learn a lot more about Azure landing zones [here](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/). -![Azure landing zone conceptual architecture][alz_tf_overview] - -[alz_tf_overview]: https://learn.microsoft.com/azure/cloud-adoption-framework/ready/enterprise-scale/media/ns-arch-cust-expanded.svg "A conceptual architecture diagram highlighting the design areas covered by the Azure landing zones Terraform module." - -[alz_tf_module]: https://registry.terraform.io/modules/Azure/caf-enterprise-scale/azurerm/latest "Terraform: Azure landing zones module" -[alz_bc_module]: https://github.com/Azure/ALZ-Bicep "Bicep: Azure landing zones module" -[alz_architecture]: https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone#azure-landing-zone-conceptual-architecture +![Azure landing zone conceptual architecture](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/enterprise-scale/media/ns-arch-cust-expanded.svg) diff --git a/docs/content/accelerator/faq.md b/docs/content/accelerator/faq.md index 21dea85..4b19270 100644 --- a/docs/content/accelerator/faq.md +++ b/docs/content/accelerator/faq.md @@ -6,16 +6,20 @@ weight: 15 This article answers frequently asked questions relating to the Azure landing zones Terraform accelerator. {{< hint type=note >}} -If you have a question not listed here, please raise an [issue](https://github.com/Azure/alz-terraform-accelerator/issues) and we'll do our best to help. +If you have a question not listed here, please raise an [Issue](https://github.com/Azure/ALZ-PowerShell-Module/issues) and we'll do our best to help. {{< /hint >}} -## Questions about customisation +## Questions about customization ### How do I use my own naming convention for the resources that are deployed? -You can add any hidden variables to your inputs file, including the `resource_names` map. This map is used to set the names of the resources that are deployed. You can find the default values in the `terraform.tfvars` file in the bootstrap module. +You can add any hidden variables to your inputs file, including the `resource_names` map. This map is used to set the names of the resources that are deployed. You can find the default values in the `variables.hidden.tf` file in the bootstrap module: -For example adding this to the end of your inputs file and updating to your standard: +* Azure DevOps: [variables.hidden.tf](https://github.com/Azure/accelerator-bootstrap-modules/blob/2b3aa805fd03fa5afa4de970ca11899a9a66d2a6/alz/azuredevops/variables.hidden.tf#L79) +* GitHub: [variables.hidden.tf](https://github.com/Azure/accelerator-bootstrap-modules/blob/2b3aa805fd03fa5afa4de970ca11899a9a66d2a6/alz/github/variables.hidden.tf#L13) +* Local: [variables.hidden.tf](https://github.com/Azure/accelerator-bootstrap-modules/blob/2b3aa805fd03fa5afa4de970ca11899a9a66d2a6/alz/local/variables.hidden.tf#L25) + +For example adding this to the end of your bootstrap config file and updating to your standard: ```yaml # Extra Inputs @@ -56,9 +60,6 @@ resource_names: container_registry_private_endpoint: "pe-{{service_name}}-{{environment_name}}-{{azure_location}}-acr-{{postfix_number}}" container_image_name: "azure-devops-agent" ``` - -Alternatively, you can take a copy of the `terraform.tfvars` file from the bootstrap module, update it and supply it via the `-bootstrapTfVarsOverridePath` parameter as an absolute path. - ## Questions about bootstrap clean up ### I was just testing or I made a mistake, how do I remove the bootstrap environment and start again? @@ -67,7 +68,7 @@ After the Terraform apply has been completed there is an opportunity to remove t 1. If you already ran the CD pipeline / action in phase 3 to deploy the ALZ, then you will need to run the pipeline / action again, but this time select the `destroy` option. This will delete the landing zone resources. If you don't do this, those resource will be left orphaned and you will have to clean them up manually. 1. Wait for the destroy run to complete before moving to the next step, you will need to approve it if you configured approvals. -1. Now run `Deploy-Accelerator` with the `-destroy` flag. E.g. `Deploy-Accelerator -i "terraform" -b "alz_azuredevops" -o "./my-folder" -destroy`. +1. Now run `Deploy-Accelerator` with the `-destroy` flag. E.g. `Deploy-Accelerator -inputs "~/config/inputs.json" -output "./my-folder" -destroy`. 1. The module will run and ask if you want to use the existing variables, enter `use` to use them. 1. You can confirm the destroy by typing `yes` when prompted. 1. To fully clean up, you should now delete the folder that was created for the accelerator. E.g. `./my-folder`. @@ -97,49 +98,15 @@ Follow the steps in the [Upgrade Guide]({{< relref "upgradeguide" >}}) to upgrad After bootstrapping, the PowerShell leaves the folder structure intact, including the Terraform state file. This is by design, so you have an opportunity to amend or destroy the environment. -If you want to deploy to a separate environment, the simplest approach is to specify a separate folder for each deployment using the `-Output` parameter. For example: +If you want to deploy to a separate environment, the simplest approach is to specify a separate folder for each deployment using the `-output` parameter. For example: -- Deployment 1: `Deploy-Accelerator -i "terraform" -b "alz_azuredevops" -Output "./deployment1"` -- Deployment 2: `Deploy-Accelerator -i "terraform" -b "alz_azuredevops" -Output "./deployment2"` +- Deployment 1: `Deploy-Accelerator -inputs "~/config/inputs1.json" -output "./deployment1"` +- Deployment 2: `Deploy-Accelerator -inputs "~/config/inputs2.json" -output "./deployment2"` You can then deploy as many times as you like without interferring with a previous deployment. ## Questions about Automating the PowerShell Module -### I want to automate the PowerShell module, but it keeps prompting me for input, can I supply the answers? - ->NOTE: We now recommend this as the preferred approach and our documentation has been updated to reflect this. - -Yes, you can supply the variables to the PowerShell module by using the `-inputs` parameter. You just need to supply a single file that includes the variables for the bootstrap and the starter module. The ordering of the variables in the file is not important. - -The module will accept inputs as in json or yaml format. `.json,`, `.yaml` or `.yml` file extensions are supported. Examples of both are shown below. - -To call the module, you then specify the `-inputs` parameter with the path to the file containing the inputs. For example: - -```powershell -Deploy-Accelerator -i "terraform" -b "alz_azuredevops" -Inputs "~/config/inputs.json" -``` - -yaml example: - -```yaml -starter: "basic" -azure_location: "uksouth" -``` - -json example: - -```json -{ - "starter": "basic", - "azure_location": "uksouth" -} -``` - -> NOTE: These examples show a partial set of variables. In this scenario, the module will prompt for the remaining variables. You can find the full list of variables in the quick start phase 2 and starter module documentation. - -Full yaml examples can be found under the `Input Files` section of the right-hand menu. - ### I get prompted to approve the Terraform plan, can I skip that? Yes, you can skip the approval of the Terraform plan by using the `-autoApprove` parameter. @@ -147,7 +114,7 @@ Yes, you can skip the approval of the Terraform plan by using the `-autoApprove` For example: ```powershell -Deploy-Accelerator -i "terraform" -b "alz_azuredevops" -Inputs "~/config/inputs.json" -autoApprove +Deploy-Accelerator -inputs "~/config/inputs.json" -autoApprove ``` ## Questions about adding more subscriptions post initial deployment @@ -171,11 +138,11 @@ There are some steps you need to take: Follow the structure and json schema in the [Azure/accelerator-bootstrap-modules](https://github.com/Azure/accelerator-bootstrap-modules). You can then target your custom bootstrap module by using the `bootstrapModuleUrl` or `bootstrapModuleOverrideFolderPath` parameters in the PowerShell module. For example: ```powershell -Deploy-Accelerator -i "terraform" -b "alz_azuredevops" -bootstrapModuleUrl "https://github.com/my-org/my-boostrap-modules" +Deploy-Accelerator -inputs "~/config/inputs.json" -bootstrapModuleUrl "https://github.com/my-org/my-boostrap-modules" ``` ```powershell -Deploy-Accelerator -i "terraform" -b "alz_azuredevops" -bootstrapModuleOverrideFolderPath "./my-bootstrap-modules" +Deploy-Accelerator -inputs "~/config/inputs.json" -bootstrapModuleOverrideFolderPath "./my-bootstrap-modules" ``` ### I want to use my own custom starter modules, how do I do that? @@ -183,7 +150,7 @@ Deploy-Accelerator -i "terraform" -b "alz_azuredevops" -bootstrapModuleOverrideF Follow the folder structure in this repository and create your own custom starter module(s). You can then target your custom starter module by using the `starterModuleOverrideFolderPath` parameters in the PowerShell module. For example: ```powershell -Deploy-Accelerator -i "terraform" -b "alz_azuredevops" -starterModuleOverrideFolderPath "~/my-custom-starter-modules" +Deploy-Accelerator -inputs "~/config/inputs.json" -starterModuleOverrideFolderPath "~/my-custom-starter-modules" ``` Alternatively, if you are also supplying a custom bootstrap module, you can specify the starter module repo url in the `json` config file in the bootstrap module. diff --git a/docs/content/accelerator/userguide/2_start/2b_azuredevops.md b/docs/content/accelerator/userguide/2_start/2b_azuredevops.md deleted file mode 100644 index f08763d..0000000 --- a/docs/content/accelerator/userguide/2_start/2b_azuredevops.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: Azure DevOps ---- - -You can choose to bootstrap with `bicep` or `terraform` skip to the relevant section below to do that. - -Although you can just run `Deploy-Accelerator` and fill out the prompted inputs, we recommend creating an inputs file. This will make it easier to run the accelerator more than once in order to refine your preferred configuration. In the following docs, we'll show that approach, but if you want to be prompted for inputs, just go ahead and run `Deploy-Accelerator` now. - -## Azure DevOps with Bicep - -1. Create a new folder on your local drive called `accelerator`. -1. Inside the accelerator create two folders called `config` and `output`. You'll store you input file inside config and the output folder will be the place that the accelerator stores files while it works. -1. Inside the `config` folder create a new file called `inputs.yaml`. You can use `json` if you prefer, but our examples here are `yaml`. - - ```pwsh - # Windows - New-Item -ItemType "file" c:\accelerator\config\inputs.yaml -Force - New-Item -ItemType "directory" c:\accelerator\output - ``` - - ```pwsh - # Linux/Mac - New-Item -ItemType "file" /accelerator/config/inputs.yaml -Force - New-Item -ItemType "directory" /accelerator/output - ``` - - ```plaintext - 📂accelerator - ┣ 📂config - ┃ ┗ 📜inputs.yaml - ┗ 📂output - ``` - -1. Open your `inputs.yaml` file in Visual Studio Code (or your preferred editor) and copy the content from [inputs-azure-devops.yaml](https://raw.githubusercontent.com/Azure/alz-bicep/refs/heads/main/accelerator/examples/bootstrap/inputs-azure-devops.yaml) into that file. -1. Check through the file and update each input as required. It is mandatory to update items with placeholders surrounded by angle brackets `<>`: - - {{< hint type=tip >}} -The following inputs can also be supplied via environment variables. This may be useful for sensitive values you don't wish to persist to a file. The `Env Var Prefix` denotes the prefix the environment variable should have. The environment variable is formatting is `_`, e.g. `$env:ALZ_iac_type = "terraform"` or `$env:TF_VAR_github_personal_access_token = "*****..."`. - {{< /hint >}} - - | Input | Env Var Prefix | Placeholder | Description | - | - | - | -- | --- | - | `iac_type` | `ALZ` | `bicep` | This is the choice of `bicep` or `terraform`. Keep this as `bicep` for this example. | - | `bootstrap_module_name` | `ALZ` | `alz_azuredevops` | This is the choice of Version Control System. Keep this as `alz_azuredevops` for this example. | - | `starter_module_name` | `ALZ` | `complete` | This is the choice of [Starter Modules]({{< relref "../../startermodules" >}}), which is the baseline configuration you want for your Azure landing zone. Keep this as `complete` for this example. | - | `bootstrap_location` | `TF_VAR` | `` | Replace `` with the Azure region where you would like to deploy the bootstrap resources in Azure. This field expects the `name` of the region, such as `uksouth`. You can find a full list of names by running `az account list-locations -o table`. | - | `starter_locations` | `TF_VAR` | `[,]` | Replace `` and `` with the Azure regions where you would like to deploy the starter module resources in Azure. This field expects the `name` of the regions in and array, such as `["uksouth", "ukwest"]`. You can find a full list of names by running `az account list-locations -o table`. | - | `root_parent_management_group_id` | `TF_VAR` | `""` | This is the id of the management group that will be the parent of the management group structure created by the accelerator. If you are using the `Tenant Root Group` management group, you leave this as an empty string `""` or supply the tenant id. | - | `subscription_id_management` | `TF_VAR` | `` | Replace `` with the id of the management subscription you created in the previous phase. | - | `subscription_id_identity` | `TF_VAR` | `` | Replace `` with the id of the identity subscription you created in the previous phase. | - | `subscription_id_connectivity` | `TF_VAR` | `` | Replace `` with the id of the connectivity subscription you created in the previous phase. | - | `azure_devops_personal_access_token` | `TF_VAR` | `` | Replace `` with the `token-1` Azure DevOps PAT you generated in a previous step. | - | `azure_devops_agents_personal_access_token` | `TF_VAR` | `` | Replace `` with the `token-2` Azure DevOps PAT you generated in the previous step specifically for the self-hosted agents. This only applies if you have `use_self_hosted_agents` set to `true`. You can set this to an empty string `""` if you are not using self-hosted agents. | - | `azure_devops_organization_name` | `TF_VAR` | `` | Replace `` with the name of your Azure DevOps organization. This is the section of the url after `dev.azure.com` or before `.visualstudio.com`. E.g. enter `my-org` for `https://dev.azure.com/my-org`. | - | `use_separate_repository_for_templates` | `TF_VAR` | `true` | Determine whether to create a separate repository to store pipeline templates as an extra layer of security. Set to `false` if you don't wish to secure your pipeline templates by using a separate repository. This will default to `true`. | - | `bootstrap_location` | `TF_VAR` | `` | Replace `` with the Azure region where you would like to deploy the bootstrap resources in Azure. This field expects the `name` of the region, such as `uksouth`. You can find a full list of names by running `az account list-locations -o table`. | - | `bootstrap_subscription_id` | `TF_VAR` | `""` | Enter the id of the subscription in which you would like to deploy the bootstrap resources in Azure. If left blank, the subscription you are connected to via `az login` will be used. In most cases this is the management subscription, but you can specifiy a separate subscription if you prefer. | - | `service_name` | `TF_VAR` | `alz` | This is used to build up the names of your Azure and Azure DevOps resources, for example `rg--mgmt-uksouth-001`. We recommend using `alz` for this. | - | `environment_name` | `TF_VAR` | `mgmt` | This is used to build up the names of your Azure and Azure DevOps resources, for example `rg-alz--uksouth-001`. We recommend using `mgmt` for this. | - | `postfix_number` | `TF_VAR` | `1` | This is used to build up the names of your Azure and Azure DevOps resources, for example `rg-alz-mgmt-uksouth-`. We recommend using `1` for this. | - | `azure_devops_use_organisation_legacy_url` | `TF_VAR` | `false` | If you have not migrated to the modern url (still using `https://.visualstudio.com`) for your Azure DevOps organisation, then set this to `true`. | - | `azure_devops_create_project` | `TF_VAR` | `true` | If you have an existing project you want to use rather than creating a new one, select `true`. We recommend creating a new project to ensure it is isolated by a strong security boundary. | - | `azure_devops_project_name` | `TF_VAR` | `` | Replace `` with the name of the Azure DevOps project to create or the name of an existing project if you set `azure_devops_create_project` to `false`. | - | `use_self_hosted_agents` | `TF_VAR` | `true` | This controls if you want to deploy self-hosted agents. This will default to `true`. | - | `use_private_networking` | `TF_VAR` | `true` | This controls whether private networking is deployed for your self-hosted agents and storage account. This only applies if you have `use_self_hosted_agents` set to `true`. This defaults to `true`. | - | `allow_storage_access_from_my_ip` | `TF_VAR` | `false` | This is not relecant to Bicep and we'll remove the need to specify it later, leave it set to `false`. | - | `apply_approvers` | `TF_VAR` | `` | This is a list of service principal names (SPN) of people you wish to be in the group that approves apply of the Azure landing zone module. This is an array of strings like `["abc@xyz.com", "def@xyz.com", "ghi@xyz.com"]`. You may need to check what the SPN is prior to filling this out as it can vary based on identity provider. Use empty array `[]` to disable approvals. Note if supplying via the user interface, use a comma separated string like `abc@xyz.com,def@xyz.com,ghi@xyz.com`. | - | `create_branch_policies` | `TF_VAR` | `true` | This controls whether to create branch policies for the repository. This defaults to `true`. | - -1. Now head over to your chosen starter module documentation to get the specific inputs for that module. Come back here when you are done. - - [Bicep Complete Starter Module]({{< relref "../../startermodules/bicepcomplete" >}}) -1. In your PowerShell Core (pwsh) terminal run the module: - - ```pwsh - # Windows (adjust the paths to match your setup) - Deploy-Accelerator -inputs "c:\accelerator\config\inputs.yaml" -output "c:\accelerator\output" - ``` - - ```pwsh - # Linux/Mac (adjust the paths to match your setup) - Deploy-Accelerator -inputs "/accelerator/config/inputs.yaml" -output "/accelerator/output" - ``` - -1. You will see a Terraform `init` and `apply` happen. -1. There will be a pause after the `plan` phase you allow you to validate what is going to be deployed. -1. If you are happy with the plan, then type `yes` and hit enter. -1. The Terraform will `apply` and your environment will be bootstrapped. - -## Azure DevOps with Terraform - -1. Create a new folder on you local drive called `accelerator`. -1. Inside the accelerator create two folders called `config` and `output`. You'll store you input file inside config and the output folder will be the place that the accelerator stores files while it works. -1. Inside the `config` folder create a new file called `inputs.yaml`. You can use `json` if you prefer, but our examples here are `yaml`. - - ```pwsh - # Windows - New-Item -ItemType "file" c:\accelerator\config\inputs.yaml -Force - New-Item -ItemType "directory" c:\accelerator\output - ``` - - ```pwsh - # Linux/Mac - New-Item -ItemType "file" /accelerator/config/inputs.yaml -Force - New-Item -ItemType "directory" /accelerator/output - ``` - - ```plaintext - 📂accelerator - ┣ 📂config - ┃ ┗ 📜inputs.yaml - ┗ 📂output - ``` - -1. Open your `inputs.yaml` file in Visual Studio Code (or your preferred editor) and copy the content from the relevant input file for your chosen starter module: - 1. Azure Verified Modules for Platform Landing Zone (ALZ) - [inputs-azure-devops.yaml](https://raw.githubusercontent.com/Azure/alz-terraform-accelerator/refs/heads/main/templates/platform_landing_zone/examples/bootstrap/inputs-azure-devops.yaml) - 1. Financial Services Industry Landing Zone - [inputs-azure-devops.yaml](https://raw.githubusercontent.com/Azure/alz-terraform-accelerator/refs/heads/main/templates/microsoft_cloud_for_industry/financial_services_landing_zone/examples/bootstrap/azure-devops-local.yaml) - 1. Sovereign Landing Zone - [inputs-azure-devops.yaml](https://raw.githubusercontent.com/Azure/alz-terraform-accelerator/refs/heads/main/templates/microsoft_cloud_for_industry/sovereign_landing_zone/examples/bootstrap/azure-devops-local.yaml) -1. Check through the file and update each input as required. It is mandatory to update items with placeholders surrounded by angle brackets `<>`: - - {{< hint type=tip >}} -The following inputs can also be supplied via environment variables. This may be useful for sensitive values you don't wish to persist to a file. The `Env Var Prefix` denotes the prefix the environment variable should have. The environment variable is formatting is `_`, e.g. `$env:ALZ_iac_type = "terraform"` or `$env:TF_VAR_github_personal_access_token = "*****..."`. - {{< /hint >}} - - | Input | Env Var Prefix | Placeholder | Description | - | - | - | -- | --- | - | `iac_type` | `ALZ` | `terraform` | This is the choice of `bicep` or `terraform`. Keep this as `terraform` for this example. | - | `bootstrap_module_name` | `ALZ` | `alz_azuredevops` | This is the choice of Version Control System. Keep this as `alz_azuredevops` for this example. | - | `starter_module_name` | `ALZ` | `platform_landing_zone` | This is the choice of [Starter Modules]({{< relref "../../startermodules" >}}), which is the baseline configuration you want for your Azure landing zone. Choose `platform_landing_zone` for this example. | - | `bootstrap_location` | `TF_VAR` | `` | Replace `` with the Azure region where you would like to deploy the bootstrap resources in Azure. This field expects the `name` of the region, such as `uksouth`. You can find a full list of names by running `az account list-locations -o table`. | - | `starter_locations` | `TF_VAR` | `[,]` | Replace `` and `` with the Azure regions where you would like to deploy the starter module resources in Azure. This field expects the `name` of the regions in and array, such as `["uksouth", "ukwest"]`. You can find a full list of names by running `az account list-locations -o table`. | - | `root_parent_management_group_id` | `TF_VAR` | `""` | This is the id of the management group that will be the parent of the management group structure created by the accelerator. If you are using the `Tenant Root Group` management group, you leave this as an empty string `""` or supply the tenant id. | - | `subscription_id_management` | `TF_VAR` | `` | Replace `` with the id of the management subscription you created in the previous phase. | - | `subscription_id_identity` | `TF_VAR` | `` | Replace `` with the id of the identity subscription you created in the previous phase. | - | `subscription_id_connectivity` | `TF_VAR` | `` | Replace `` with the id of the connectivity subscription you created in the previous phase. | - | `azure_devops_personal_access_token` | `TF_VAR` | `` | Replace `` with the `token-1` Azure DevOps PAT you generated in a previous step. | - | `azure_devops_agents_personal_access_token` | `TF_VAR` | `` | Replace `` with the `token-2` Azure DevOps PAT you generated in the previous step specifically for the self-hosted agents. This only applies if you have `use_self_hosted_agents` set to `true`. You can set this to an empty string `""` if you are not using self-hosted agents. | - | `azure_devops_organization_name` | `TF_VAR` | `` | Replace `` with the name of your Azure DevOps organization. This is the section of the url after `dev.azure.com` or before `.visualstudio.com`. E.g. enter `my-org` for `https://dev.azure.com/my-org`. | - | `use_separate_repository_for_templates` | `TF_VAR` | `true` | Determine whether to create a separate repository to store pipeline templates as an extra layer of security. Set to `false` if you don't wish to secure your pipeline templates by using a separate repository. This will default to `true`. | - | `bootstrap_subscription_id` | `TF_VAR` | `""` | Enter the id of the subscription in which you would like to deploy the bootstrap resources in Azure. If left blank, the subscription you are connected to via `az login` will be used. In most cases this is the management subscription, but you can specifiy a separate subscription if you prefer. | - | `service_name` | `TF_VAR` | `alz` | This is used to build up the names of your Azure and Azure DevOps resources, for example `rg--mgmt-uksouth-001`. We recommend using `alz` for this. | - | `environment_name` | `TF_VAR` | `mgmt` | This is used to build up the names of your Azure and Azure DevOps resources, for example `rg-alz--uksouth-001`. We recommend using `mgmt` for this. | - | `postfix_number` | `TF_VAR` | `1` | This is used to build up the names of your Azure and Azure DevOps resources, for example `rg-alz-mgmt-uksouth-`. We recommend using `1` for this. | - | `azure_devops_use_organisation_legacy_url` | `TF_VAR` | `false` | If you have not migrated to the modern url (still using `https://.visualstudio.com`) for your Azure DevOps organisation, then set this to `true`. | - | `azure_devops_create_project` | `TF_VAR` | `true` | If you have an existing project you want to use rather than creating a new one, select `true`. We recommend creating a new project to ensure it is isolated by a strong security boundary. | - | `azure_devops_project_name` | `TF_VAR` | `` | Replace `` with the name of the Azure DevOps project to create or the name of an existing project if you set `azure_devops_create_project` to `false`. | - | `use_self_hosted_agents` | `TF_VAR` | `true` | This controls if you want to deploy self-hosted agents. This will default to `true`. | - | `use_private_networking` | `TF_VAR` | `true` | This controls whether private networking is deployed for your self-hosted agents and storage account. This only applies if you have `use_self_hosted_agents` set to `true`. This defaults to `true`. | - | `allow_storage_access_from_my_ip` | `TF_VAR` | `false` | This controls whether to allow access to the storage account from your IP address. This is only needed for trouble shooting. This only applies if you have `use_private_networking` set to `true`. This defaults to `false`. | - | `apply_approvers` | `TF_VAR` | `` | This is a list of service principal names (SPN) of people you wish to be in the group that approves apply of the Azure landing zone module. This is an array of strings like `["abc@xyz.com", "def@xyz.com", "ghi@xyz.com"]`. You may need to check what the SPN is prior to filling this out as it can vary based on identity provider. Use empty array `[]` to disable approvals. Note if supplying via the user interface, use a comma separated string like `abc@xyz.com,def@xyz.com,ghi@xyz.com`. | - | `create_branch_policies` | `TF_VAR` | `true` | This controls whether to create branch policies for the repository. This defaults to `true`. | - | `architecture_definition_name` | `TF_VAR` | N/A | This is the name of the architecture definition to use when applying the ALZ archetypes via the architecture definition template. This is only relevant to some starter modules, such as the `sovereign_landing_zone` starter module. This defaults to `null`. | - -1. Now head over to your chosen starter module documentation to get the specific inputs for that module. Come back here when you are done. - - [Terraform Azure Verified Modules for Platform Landing Zone (ALZ)]({{< relref "../../startermodules/terraform-platform-landing-zone" >}}): Management groups, policies, Multi Region hub networking with fully custom configuration. - - [Terraform Financial Services Industry Landing Zone Starter Module]({{< relref "../../startermodules/terraformfsi" >}}): Management groups, policies, hub networking for the Financial Services Industry Landing Zone. - - [Terraform Sovereign Landing Zone Starter Module]({{< relref "../../startermodules/terraformsovereign" >}}): Management groups, policies, hub networking for the Sovereign Landing Zone. - -1. In your PowerShell Core (pwsh) terminal run the module: - - {{< hint type=tip >}} -The following examples include 2 input files. This is the recommended approach for the `platform_landing_zone` starter module. However, all inputs into multiple files if desired. - {{< /hint >}} - - ```pwsh - # Windows (adjust the paths to match your setup) - Deploy-Accelerator -inputs "c:\accelerator\config\inputs.yaml", "c:\accelerator\config\networking.yaml" -output "c:\accelerator\output" - ``` - - ```pwsh - # Linux/Mac (adjust the paths to match your setup) - Deploy-Accelerator -inputs "/accelerator/config/inputs.yaml", "/accelerator/config/networking.yaml" -output "/accelerator/output" - ``` - -1. You will see a Terraform `init` and `apply` happen. -1. There will be a pause after the `plan` phase you allow you to validate what is going to be deployed. -1. If you are happy with the plan, then type `yes` and hit enter. -1. The Terraform will `apply` and your environment will be bootstrapped. - -## Next Steps - -Now head to [Phase 3]({{< relref "3_deploy" >}}). diff --git a/docs/content/accelerator/userguide/2_start/_index.md b/docs/content/accelerator/userguide/2_start/_index.md index bfd2d1e..fb06996 100644 --- a/docs/content/accelerator/userguide/2_start/_index.md +++ b/docs/content/accelerator/userguide/2_start/_index.md @@ -11,6 +11,11 @@ Phase 2 of the accelerator is to run the bootstrap. Follow the steps below to do The ALZ PowerShell module is used to run the bootstrap phase. It is available on the [PowerShell Gallery](https://www.powershellgallery.com/packages/ALZ/). You can install it using the following steps: 1. Open a PowerShell Core (pwsh) terminal. + + {{< hint type=warning >}} +Double check you are running in a PowerShell Core terminal. Run `$psversiontable` to check. + {{< /hint >}} + 2. Check if you already have the ALZ module installed by running `Get-InstalledModule -Name ALZ`. You'll see something like this if it is already installed: ```powershell @@ -24,13 +29,25 @@ Version Name Repository Description ## 2.2 Run the Bootstrap -You are now ready to run the bootstrap and setup your environment. If you want to use custom names for your resources or automate the bootstrap, please refer to our [FAQs](https://github.com/Azure/alz-terraform-accelerator/wiki/Frequently-Asked-Questions) section. +You are now ready to run the bootstrap and setup your environment. If you want to use custom names for your resources or automate the bootstrap, please refer to our [FAQs]({{< relref "../../faq" >}}) section. + +The inputs differ depending on the version control system and infrastructure as code tooling you have chosen. + +### 2.2.1 Bicep + +Click through to the relevant page for detailed instructions: + +* [Azure DevOps with Bicep]({{< relref "bicep-azuredevops" >}}) +* [GitHub with Bicep]({{< relref "bicep-github" >}}) +* [Local File System]({{< relref "bicep-local" >}}) + +### 2.2.2 Terraform -The inputs differ depending on the version control system and infrastructure as code tooling you have chosen. Click through to the relevant page for detailed instructions: +Click through to the relevant page for detailed instructions: -- [Azure DevOps]({{< relref "2b_azuredevops" >}}) -- [GitHub]({{< relref "2a_github" >}}) -- [Local file system]({{< relref "2c_local" >}}) +* [Azure DevOps with Terraform]({{< relref "terraform-azuredevops" >}}) +* [GitHub with Terraform]({{< relref "terraform-github" >}}) +* [Local File System with Terraform]({{< relref "terraform-local" >}}) ## Next Steps diff --git a/docs/content/accelerator/userguide/2_start/bicep-azuredevops.md b/docs/content/accelerator/userguide/2_start/bicep-azuredevops.md new file mode 100644 index 0000000..7bda904 --- /dev/null +++ b/docs/content/accelerator/userguide/2_start/bicep-azuredevops.md @@ -0,0 +1,87 @@ +--- +title: Azure DevOps with Bicep +--- + +Follow these instructions to bootstrap Azure DevOps ready to deploy your platform landing zone with Bicep. + +1. Create a new folder on your local drive called `accelerator`. +1. Inside the accelerator create two folders called `config` and `output`. You'll store your input file inside config and the output folder will be the place that the accelerator stores files while it works. +1. Inside the `config` folder create a new file called `inputs.yaml`. You can use `json` if you prefer, but our examples here are `yaml`. + + ```pwsh + # Windows + New-Item -ItemType "file" c:\accelerator\config\inputs.yaml -Force + New-Item -ItemType "directory" c:\accelerator\output + ``` + + ```pwsh + # Linux/Mac + New-Item -ItemType "file" /accelerator/config/inputs.yaml -Force + New-Item -ItemType "directory" /accelerator/output + ``` + + ```plaintext + 📂accelerator + ┣ 📂config + ┃ ┗ 📜inputs.yaml + ┗ 📂output + ``` + +1. Open your `inputs.yaml` file in Visual Studio Code (or your preferred editor) and copy the content from [inputs-azure-devops.yaml](https://raw.githubusercontent.com/Azure/alz-bicep/refs/heads/main/accelerator/examples/bootstrap/inputs-azure-devops.yaml) into that file. +1. Check through the file and update each input as required. It is mandatory to update items with placeholders surrounded by angle brackets `<>`: + + {{< hint type=tip >}} +The following inputs can also be supplied via environment variables. This may be useful for sensitive values you don't wish to persist to a file. The `Env Var Prefix` denotes the prefix the environment variable should have. The environment variable is formatting is `_`, e.g. `$env:ALZ_iac_type = "terraform"` or `$env:TF_VAR_github_personal_access_token = "*****..."`. + {{< /hint >}} + + | Input | Env Var Prefix | Placeholder | Description | + | - | - | -- | --- | + | `iac_type` | `ALZ` | `bicep` | This is the choice of `bicep` or `terraform`. Keep this as `bicep` for this example. | + | `bootstrap_module_name` | `ALZ` | `alz_azuredevops` | This is the choice of Version Control System. Keep this as `alz_azuredevops` for this example. | + | `starter_module_name` | `ALZ` | `complete` | This is the choice of [Starter Modules]({{< relref "../../startermodules" >}}), which is the baseline configuration you want for your Azure landing zone. Keep this as `complete` for this example. | + | `bootstrap_location` | `TF_VAR` | `` | Replace `` with the Azure region where you would like to deploy the bootstrap resources in Azure. This field expects the `name` of the region, such as `uksouth`. You can find a full list of names by running `az account list-locations -o table`. | + | `starter_locations` | `TF_VAR` | `[,]` | Replace `` and `` with the Azure regions where you would like to deploy the starter module resources in Azure. This field expects the `name` of the regions in and array, such as `["uksouth", "ukwest"]`. You can find a full list of names by running `az account list-locations -o table`. | + | `root_parent_management_group_id` | `TF_VAR` | `""` | This is the id of the management group that will be the parent of the management group structure created by the accelerator. If you are using the `Tenant Root Group` management group, you leave this as an empty string `""` or supply the tenant id. | + | `subscription_id_management` | `TF_VAR` | `` | Replace `` with the id of the management subscription you created in the previous phase. | + | `subscription_id_identity` | `TF_VAR` | `` | Replace `` with the id of the identity subscription you created in the previous phase. | + | `subscription_id_connectivity` | `TF_VAR` | `` | Replace `` with the id of the connectivity subscription you created in the previous phase. | + | `azure_devops_personal_access_token` | `TF_VAR` | `` | Replace `` with the `token-1` Azure DevOps PAT you generated in a previous step. | + | `azure_devops_agents_personal_access_token` | `TF_VAR` | `` | Replace `` with the `token-2` Azure DevOps PAT you generated in the previous step specifically for the self-hosted agents. This only applies if you have `use_self_hosted_agents` set to `true`. You can set this to an empty string `""` if you are not using self-hosted agents. | + | `azure_devops_organization_name` | `TF_VAR` | `` | Replace `` with the name of your Azure DevOps organization. This is the section of the url after `dev.azure.com` or before `.visualstudio.com`. E.g. enter `my-org` for `https://dev.azure.com/my-org`. | + | `use_separate_repository_for_templates` | `TF_VAR` | `true` | Determine whether to create a separate repository to store pipeline templates as an extra layer of security. Set to `false` if you don't wish to secure your pipeline templates by using a separate repository. This will default to `true`. | + | `bootstrap_location` | `TF_VAR` | `` | Replace `` with the Azure region where you would like to deploy the bootstrap resources in Azure. This field expects the `name` of the region, such as `uksouth`. You can find a full list of names by running `az account list-locations -o table`. | + | `bootstrap_subscription_id` | `TF_VAR` | `""` | Enter the id of the subscription in which you would like to deploy the bootstrap resources in Azure. If left blank, the subscription you are connected to via `az login` will be used. In most cases this is the management subscription, but you can specifiy a separate subscription if you prefer. | + | `service_name` | `TF_VAR` | `alz` | This is used to build up the names of your Azure and Azure DevOps resources, for example `rg--mgmt-uksouth-001`. We recommend using `alz` for this. | + | `environment_name` | `TF_VAR` | `mgmt` | This is used to build up the names of your Azure and Azure DevOps resources, for example `rg-alz--uksouth-001`. We recommend using `mgmt` for this. | + | `postfix_number` | `TF_VAR` | `1` | This is used to build up the names of your Azure and Azure DevOps resources, for example `rg-alz-mgmt-uksouth-`. We recommend using `1` for this. | + | `azure_devops_use_organisation_legacy_url` | `TF_VAR` | `false` | If you have not migrated to the modern url (still using `https://.visualstudio.com`) for your Azure DevOps organisation, then set this to `true`. | + | `azure_devops_create_project` | `TF_VAR` | `true` | If you have an existing project you want to use rather than creating a new one, select `true`. We recommend creating a new project to ensure it is isolated by a strong security boundary. | + | `azure_devops_project_name` | `TF_VAR` | `` | Replace `` with the name of the Azure DevOps project to create or the name of an existing project if you set `azure_devops_create_project` to `false`. | + | `use_self_hosted_agents` | `TF_VAR` | `true` | This controls if you want to deploy self-hosted agents. This will default to `true`. | + | `use_private_networking` | `TF_VAR` | `true` | This controls whether private networking is deployed for your self-hosted agents and storage account. This only applies if you have `use_self_hosted_agents` set to `true`. This defaults to `true`. | + | `allow_storage_access_from_my_ip` | `TF_VAR` | `false` | This is not relevant to Bicep and we'll remove the need to specify it later, leave it set to `false`. | + | `apply_approvers` | `TF_VAR` | `` | This is a list of service principal names (SPN) of people you wish to be in the group that approves apply of the Azure landing zone module. This is an array of strings like `["abc@xyz.com", "def@xyz.com", "ghi@xyz.com"]`. You may need to check what the SPN is prior to filling this out as it can vary based on identity provider. Use empty array `[]` to disable approvals. Note if supplying via the user interface, use a comma separated string like `abc@xyz.com,def@xyz.com,ghi@xyz.com`. | + | `create_branch_policies` | `TF_VAR` | `true` | This controls whether to create branch policies for the repository. This defaults to `true`. | + +1. Now head over to your chosen starter module documentation to get the specific inputs for that module. Come back here when you are done. + - [Bicep Complete Starter Module]({{< relref "../../startermodules/bicepcomplete" >}}) +1. In your PowerShell Core (pwsh) terminal run the module: + + ```pwsh + # Windows (adjust the paths to match your setup) + Deploy-Accelerator -inputs "c:\accelerator\config\inputs.yaml" -output "c:\accelerator\output" + ``` + + ```pwsh + # Linux/Mac (adjust the paths to match your setup) + Deploy-Accelerator -inputs "/accelerator/config/inputs.yaml" -output "/accelerator/output" + ``` + +1. You will see a Terraform `init` and `apply` happen. +1. There will be a pause after the `plan` phase you allow you to validate what is going to be deployed. +1. If you are happy with the plan, then type `yes` and hit enter. +1. The Terraform will `apply` and your environment will be bootstrapped. + +## Next Steps + +Now head to [Phase 3]({{< relref "3_deploy" >}}). diff --git a/docs/content/accelerator/userguide/2_start/bicep-github.md b/docs/content/accelerator/userguide/2_start/bicep-github.md new file mode 100644 index 0000000..606d658 --- /dev/null +++ b/docs/content/accelerator/userguide/2_start/bicep-github.md @@ -0,0 +1,79 @@ +--- +title: GitHub with Bicep +--- + +Follow these instructions to bootstrap GitHub ready to deploy your platform landing zone with Bicep. + +1. Create a new folder on your local drive called `accelerator`. +1. Inside the accelerator create two folders called `config` and `output`. You'll store your input file inside config and the output folder will be the place that the accelerator stores files while it works. +1. Inside the `config` folder create a new file called `inputs.yaml`. You can use `json` if you prefer, but our examples here are `yaml`. + + ```pwsh + # Windows + New-Item -ItemType "file" c:\accelerator\config\inputs.yaml -Force + New-Item -ItemType "directory" c:\accelerator\output + + # Linux/Mac + New-Item -ItemType "file" /accelerator/config/inputs.yaml -Force + New-Item -ItemType "directory" /accelerator/output + ``` + + ```plaintext + 📂accelerator + ┣ 📂config + ┃ ┗ 📜inputs.yaml + ┗ 📂output + ``` + +1. Open your `inputs.yaml` file in Visual Studio Code (or your preferred editor) and copy the content from [inputs-github.yaml](https://raw.githubusercontent.com/Azure/alz-bicep/refs/heads/main/accelerator/examples/bootstrap/inputs-github.yaml) into that file. +1. Check through the file and update each input as required. It is mandatory to update items with placeholders surrounded by angle brackets `<>`: + + {{< hint type=tip >}} +The following inputs can also be supplied via environment variables. This may be useful for sensitive values you don't wish to persist to a file. The `Env Var Prefix` denotes the prefix the environment variable should have. The environment variable is formatting is `_`, e.g. `$env:ALZ_iac_type = "terraform"` or `$env:TF_VAR_github_personal_access_token = "*****..."`. + {{< /hint >}} + + | Input | Env Var Prefix | Placeholder | Description | + | - | - | -- | --- | + | `iac_type` | `ALZ` | `bicep` | This is the choice of `bicep` or `terraform`. Keep this as `bicep` for this example. | + | `bootstrap_module_name` | `ALZ` | `alz_github` | This is the choice of Version Control System. Keep this as `alz_github` for this example. | + | `starter_module_name` | `ALZ` | `complete` | This is the choice of [Starter Modules][wiki_starter_modules], which is the baseline configuration you want for your Azure landing zone. Keep this as `complete` for this example. | + | `bootstrap_location` | `TF_VAR` | `` | Replace `` with the Azure region where you would like to deploy the bootstrap resources in Azure. This field expects the `name` of the region, such as `uksouth`. You can find a full list of names by running `az account list-locations -o table`. | + | `starter_locations` | `TF_VAR` | `[,]` | Replace `` and `` with the Azure regions where you would like to deploy the starter module resources in Azure. This field expects the `name` of the regions in and array, such as `["uksouth", "ukwest"]`. You can find a full list of names by running `az account list-locations -o table`. | + | `root_parent_management_group_id` | `TF_VAR` | `""` | This is the id of the management group that will be the parent of the management group structure created by the accelerator. If you are using the `Tenant Root Group` management group, you leave this as an empty string `""` or supply the tenant id. | + | `subscription_id_management` | `TF_VAR` | `` | Replace `` with the id of the management subscription you created in the previous phase. | + | `subscription_id_identity` | `TF_VAR` | `` | Replace `` with the id of the identity subscription you created in the previous phase. | + | `subscription_id_connectivity` | `TF_VAR` | `` | Replace `` with the id of the connectivity subscription you created in the previous phase. | + | `github_personal_access_token` | `TF_VAR` | `` | Replace `` with the `token-1` GitHub PAT you generated in a previous step. | + | `github_runners_personal_access_token` | `TF_VAR` | `` | Replace `` with the `token-2` GitHub PAT you generated in the previous step specifically for the self-hosted runners. This only applies if you have `use_self_hosted_agents` set to `true`. You can set this to an empty string `""` if you are not using self-hosted runners. | + | `github_organization_name` | `TF_VAR` | `` | Replace `` with the name of your GitHub organization. This is the section of the url after `github.com`. E.g. enter `my-org` for `https://github.com/my-org`. | + | `use_separate_repository_for_templates` | `TF_VAR` | `true` | Determine whether to create a separate repository to store workflow templates as an extra layer of security. Set to `false` if you don't wish to secure your workflow templates by using a separate repository. This will default to `true`. | + | `bootstrap_subscription_id` | `TF_VAR` | `""` | Enter the id of the subscription in which you would like to deploy the bootstrap resources in Azure. If left blank, the subscription you are connected to via `az login` will be used. In most cases this is the management subscription, but you can specify a separate subscription if you prefer. | + | `service_name` | `TF_VAR` | `alz` | This is used to build up the names of your Azure and GitHub resources, for example `rg--mgmt-uksouth-001`. We recommend using `alz` for this. | + | `environment_name` | `TF_VAR` | `mgmt` | This is used to build up the names of your Azure and GitHub resources, for example `rg-alz--uksouth-001`. We recommend using `mgmt` for this. | + | `postfix_number` | `TF_VAR` | `1` | This is used to build up the names of your Azure and GitHub resources, for example `rg-alz-mgmt-uksouth-`. We recommend using `1` for this. | + | `use_self_hosted_agents` | `TF_VAR` | `true` | This controls if you want to deploy self-hosted agents. This will default to `true`. | + | `use_private_networking` | `TF_VAR` | `true` | This controls whether private networking is deployed for your self-hosted agents and storage account. This only applies if you have `use_self_hosted_agents` set to `true`. This defaults to `true`. | + | `allow_storage_access_from_my_ip` | `TF_VAR` | `false` | This is not relevant to Bicep and we'll remove the need to specify it later, leave it set to `false`. | + | `apply_approvers` | `TF_VAR` | `` | This is a list of service principal names (SPN) of people you wish to be in the group that approves apply of the Azure landing zone module. This is an array of strings like `["abc@xyz.com", "def@xyz.com", "ghi@xyz.com"]`. You may need to check what the SPN is prior to filling this out as it can vary based on identity provider. Use empty array `[]` to disable approvals. Note if supplying via the user interface, use a comma separated string like `abc@xyz.com,def@xyz.com,ghi@xyz.com`. | + | `create_branch_policies` | `TF_VAR` | `true` | This controls whether to create branch policies for the repository. This defaults to `true`. | + +1. Now head over to your chosen starter module documentation to get the specific inputs for that module. Come back here when you are done. + - [Bicep Complete Starter Module]({{< relref "../../startermodules/bicepcomplete" >}}) +1. In your PowerShell Core (pwsh) terminal run the module: + + ```pwsh + # Windows (adjust the paths to match your setup) + Deploy-Accelerator -inputs "c:\accelerator\config\inputs.yaml" -output "c:\accelerator\output" + + # Linux/Mac (adjust the paths to match your setup) + Deploy-Accelerator -inputs "/accelerator/config/inputs.yaml" -output "/accelerator/output" + ``` + +1. You will see a Terraform `init` and `apply` happen. +1. There will be a pause after the `plan` phase to allow you to validate what is going to be deployed. +1. If you are happy with the plan, then type `yes` and hit enter. +1. The Terraform will `apply` and your environment will be bootstrapped. + +## Next Steps + +Now head to [Phase 3]({{< relref "3_deploy" >}}). diff --git a/docs/content/accelerator/userguide/2_start/bicep-local.md b/docs/content/accelerator/userguide/2_start/bicep-local.md new file mode 100644 index 0000000..f893afe --- /dev/null +++ b/docs/content/accelerator/userguide/2_start/bicep-local.md @@ -0,0 +1,74 @@ +--- +title: Local File System with Bicep +--- + +Follow these instructions to bootstrap a local file system folder ready to deploy your platform landing zone with Bicep. + +1. Create a new folder on your local drive called `accelerator`. +1. Inside the accelerator create two folders called `config` and `output`. You'll store you input file inside config and the output folder will be the place that the accelerator stores files while it works. +1. Inside the `config` folder create a new file called `inputs.yaml`. You can use `json` if you prefer, but our examples here are `yaml`. + + ```pwsh + # Windows + New-Item -ItemType "file" c:\accelerator\config\inputs.yaml -Force + New-Item -ItemType "directory" c:\accelerator\output + + # Linux/Mac + New-Item -ItemType "file" /accelerator/config/inputs.yaml -Force + New-Item -ItemType "directory" /accelerator/output + ``` + + ```plaintext + 📂accelerator + ┣ 📂config + ┃ ┗ 📜inputs.yaml + ┗ 📂output + ``` + +1. Open your `inputs.yaml` file in Visual Studio Code (or your preferred editor) and copy the content from [inputs-local.yaml](https://raw.githubusercontent.com/Azure/alz-bicep/refs/heads/main/accelerator/examples/bootstrap/inputs-local.yaml) into that file. +1. Check through the file and update each input as required. It is mandatory to update items with placeholders surrounded by angle brackets `<>`: + + {{< hint type=tip >}} +The following inputs can also be supplied via environment variables. This may be useful for sensitive values you don't wish to persist to a file. The `Env Var Prefix` denotes the prefix the environment variable should have. The environment variable is formatting is `_`, e.g. `$env:ALZ_iac_type = "terraform"` or `$env:TF_VAR_github_personal_access_token = "*****..."`. + {{< /hint >}} + + | Input | Env Var Prefix | Placeholder | Description | + | - | - | -- | --- | + | `iac_type` | `ALZ` | `bicep` | This is the choice of `bicep` or `terraform`. Keep this as `bicep` for this example. | + | `bootstrap_module_name` | `ALZ` | `alz_local` | This is the choice of Version Control System. Keep this as `alz_local` for this example. | + | `starter_module_name` | `ALZ` | `complete` | This is the choice of [Starter Modules][wiki_starter_modules], which is the baseline configuration you want for your Azure landing zone. Keep this as `complete` for this example. | + | `bootstrap_location` | `TF_VAR` | `` | Replace `` with the Azure region where you would like to deploy the bootstrap resources in Azure. This field expects the `name` of the region, such as `uksouth`. You can find a full list of names by running `az account list-locations -o table`. | + | `starter_locations` | `TF_VAR` | `[,]` | Replace `` and `` with the Azure regions where you would like to deploy the starter module resources in Azure. This field expects the `name` of the regions in and array, such as `["uksouth", "ukwest"]`. You can find a full list of names by running `az account list-locations -o table`. | + | `root_parent_management_group_id` | `TF_VAR` | `""` | This is the id of the management group that will be the parent of the management group structure created by the accelerator. If you are using the `Tenant Root Group` management group, you leave this as an empty string `""` or supply the tenant id. | + | `subscription_id_management` | `TF_VAR` | `` | Replace `` with the id of the management subscription you created in the previous phase. | + | `subscription_id_identity` | `TF_VAR` | `` | Replace `` with the id of the identity subscription you created in the previous phase. | + | `subscription_id_connectivity` | `TF_VAR` | `` | Replace `` with the id of the connectivity subscription you created in the previous phase. | + | `target_directory` | `TF_VAR` | `""` | This is the directory where the ALZ module code will be created. This defaults a directory called `local-output` in the root of the accelerator output directory if not supplied. | + | `create_bootstrap_resources_in_azure` | `TF_VAR` | `true` | This determines whether the bootstrap will create the bootstrap resources in Azure. This defaults to `true`. | + | `bootstrap_subscription_id` | `TF_VAR` | `""` | Enter the id of the subscription in which you would like to deploy the bootstrap resources in Azure. If left blank, the subscription you are connected to via `az login` will be used. In most cases this is the management subscription, but you can specifiy a separate subscription if you prefer. | + | `service_name` | `TF_VAR` | `alz` | This is used to build up the names of your Azure and Azure DevOps resources, for example `rg--mgmt-uksouth-001`. We recommend using `alz` for this. | + | `environment_name` | `TF_VAR` | `mgmt` | This is used to build up the names of your Azure and Azure DevOps resources, for example `rg-alz--uksouth-001`. We recommend using `mgmt` for this. | + | `postfix_number` | `TF_VAR` | `1` | This is used to build up the names of your Azure and Azure DevOps resources, for example `rg-alz-mgmt-uksouth-`. We recommend using `1` for this. | + | `grant_permissions_to_current_user` | `TF_VAR` | `true` | This determines whether the bootstrap will grant the current user permissions to the management group structure created by the accelerator. This defaults to `true` so that the starter module can be immediately deployed from the local file system. Set this to `false` if you itend to wire up CI/CD with your own provider. | + +1. Now head over to your chosen starter module documentation to get the specific inputs for that module. Come back here when you are done. + - [Bicep Complete Starter Module][wiki_starter_module_bicep_complete] +1. In your PowerShell Core (pwsh) terminal run the module: + + ```pwsh + # Windows (adjust the paths to match your setup) + Deploy-Accelerator -inputs "c:\accelerator\config\inputs.yaml" -output "c:\accelerator\output" + + # Linux/Mac (adjust the paths to match your setup) + Deploy-Accelerator -inputs "/accelerator/config/inputs.yaml" -output "/accelerator/output" + ``` + +1. You will see a Terraform `init` and `apply` happen. +1. There will be a pause after the `plan` phase you allow you to validate what is going to be deployed. +1. If you are happy with the plan, then type `yes` and hit enter. +1. The Terraform will `apply` and your environment will be bootstrapped. +1. You will find the output in the `/accelerator/output/local-output` folder if you didn't specifiy a different location for `target_directory`. + +## Next Steps + +Now head to [Phase 3]({{< relref "3_deploy" >}}) diff --git a/docs/content/accelerator/userguide/2_start/terraform-azuredevops.md b/docs/content/accelerator/userguide/2_start/terraform-azuredevops.md new file mode 100644 index 0000000..5df7e41 --- /dev/null +++ b/docs/content/accelerator/userguide/2_start/terraform-azuredevops.md @@ -0,0 +1,122 @@ +--- +title: Azure DevOps with Terraform +--- + +Follow these instructions to bootstrap Azure DevOps ready to deploy your platform landing zone with Terraform. + +1. Create a new folder on you local drive called `accelerator`. +1. Inside the accelerator create two folders called `config` and `output`. You'll store you input file inside config and the output folder will be the place that the accelerator stores files while it works. +1. Inside the `config` folder create a new files called `inputs.yaml` and `platform-landing-zone.tfvars`. + + ```pwsh + # Windows + New-Item -ItemType "file" c:\accelerator\config\inputs.yaml -Force + New-Item -ItemType "file" c:\accelerator\config\platform-landing-zone.tfvars -Force + New-Item -ItemType "directory" c:\accelerator\output + ``` + + ```pwsh + # Linux/Mac + New-Item -ItemType "file" /accelerator/config/inputs.yaml -Force + New-Item -ItemType "file" c:\accelerator\config\platform-landing-zone.tfvars -Force + New-Item -ItemType "directory" /accelerator/output + ``` + + ```plaintext + 📂accelerator + ┣ 📂config + ┃ ┣📜inputs.yaml + ┃ ┗📜platform-landing-zone.tfvars + ┗ 📂output + ``` + +1. Open your `inputs.yaml` file in Visual Studio Code (or your preferred editor) and copy the content from the relevant input file for your chosen starter module: + 1. Azure Verified Modules for Platform Landing Zone (ALZ) - [inputs-azure-devops.yaml](https://raw.githubusercontent.com/Azure/alz-terraform-accelerator/refs/heads/main/templates/platform_landing_zone/examples/bootstrap/inputs-azure-devops.yaml) + 1. Financial Services Industry Landing Zone - [inputs-azure-devops.yaml](https://raw.githubusercontent.com/Azure/alz-terraform-accelerator/refs/heads/main/templates/microsoft_cloud_for_industry/financial_services_landing_zone/examples/bootstrap/azure-devops-local.yaml) + 1. Sovereign Landing Zone - [inputs-azure-devops.yaml](https://raw.githubusercontent.com/Azure/alz-terraform-accelerator/refs/heads/main/templates/microsoft_cloud_for_industry/sovereign_landing_zone/examples/bootstrap/azure-devops-local.yaml) +1. Check through the file and update each input as required. It is mandatory to update items with placeholders surrounded by angle brackets `<>`: + + {{< hint type=tip >}} +The following inputs can also be supplied via environment variables. This may be useful for sensitive values you don't wish to persist to a file. The `Env Var Prefix` denotes the prefix the environment variable should have. The environment variable is formatting is `_`, e.g. `$env:ALZ_iac_type = "terraform"` or `$env:TF_VAR_github_personal_access_token = "*****..."`. + {{< /hint >}} + + | Input | Env Var Prefix | Placeholder | Description | + | - | - | -- | --- | + | `iac_type` | `ALZ` | `terraform` | This is the choice of `bicep` or `terraform`. Keep this as `terraform` for this example. | + | `bootstrap_module_name` | `ALZ` | `alz_azuredevops` | This is the choice of Version Control System. Keep this as `alz_azuredevops` for this example. | + | `starter_module_name` | `ALZ` | `platform_landing_zone` | This is the choice of [Starter Modules]({{< relref "../../startermodules" >}}), which is the baseline configuration you want for your Azure landing zone. Choose `platform_landing_zone` for this example. | + | `bootstrap_location` | `TF_VAR` | `` | Replace `` with the Azure region where you would like to deploy the bootstrap resources in Azure. This field expects the `name` of the region, such as `uksouth`. You can find a full list of names by running `az account list-locations -o table`. | + | `starter_locations` | `TF_VAR` | `[,]` | Replace `` and `` with the Azure regions where you would like to deploy the starter module resources in Azure. This field expects the `name` of the regions in and array, such as `["uksouth", "ukwest"]`. You can find a full list of names by running `az account list-locations -o table`. | + | `root_parent_management_group_id` | `TF_VAR` | `""` | This is the id of the management group that will be the parent of the management group structure created by the accelerator. If you are using the `Tenant Root Group` management group, you leave this as an empty string `""` or supply the tenant id. | + | `subscription_id_management` | `TF_VAR` | `` | Replace `` with the id of the management subscription you created in the previous phase. | + | `subscription_id_identity` | `TF_VAR` | `` | Replace `` with the id of the identity subscription you created in the previous phase. | + | `subscription_id_connectivity` | `TF_VAR` | `` | Replace `` with the id of the connectivity subscription you created in the previous phase. | + | `azure_devops_personal_access_token` | `TF_VAR` | `` | Replace `` with the `token-1` Azure DevOps PAT you generated in a previous step. | + | `azure_devops_agents_personal_access_token` | `TF_VAR` | `` | Replace `` with the `token-2` Azure DevOps PAT you generated in the previous step specifically for the self-hosted agents. This only applies if you have `use_self_hosted_agents` set to `true`. You can set this to an empty string `""` if you are not using self-hosted agents. | + | `azure_devops_organization_name` | `TF_VAR` | `` | Replace `` with the name of your Azure DevOps organization. This is the section of the url after `dev.azure.com` or before `.visualstudio.com`. E.g. enter `my-org` for `https://dev.azure.com/my-org`. | + | `use_separate_repository_for_templates` | `TF_VAR` | `true` | Determine whether to create a separate repository to store pipeline templates as an extra layer of security. Set to `false` if you don't wish to secure your pipeline templates by using a separate repository. This will default to `true`. | + | `bootstrap_subscription_id` | `TF_VAR` | `""` | Enter the id of the subscription in which you would like to deploy the bootstrap resources in Azure. If left blank, the subscription you are connected to via `az login` will be used. In most cases this is the management subscription, but you can specifiy a separate subscription if you prefer. | + | `service_name` | `TF_VAR` | `alz` | This is used to build up the names of your Azure and Azure DevOps resources, for example `rg--mgmt-uksouth-001`. We recommend using `alz` for this. | + | `environment_name` | `TF_VAR` | `mgmt` | This is used to build up the names of your Azure and Azure DevOps resources, for example `rg-alz--uksouth-001`. We recommend using `mgmt` for this. | + | `postfix_number` | `TF_VAR` | `1` | This is used to build up the names of your Azure and Azure DevOps resources, for example `rg-alz-mgmt-uksouth-`. We recommend using `1` for this. | + | `azure_devops_use_organisation_legacy_url` | `TF_VAR` | `false` | If you have not migrated to the modern url (still using `https://.visualstudio.com`) for your Azure DevOps organisation, then set this to `true`. | + | `azure_devops_create_project` | `TF_VAR` | `true` | If you have an existing project you want to use rather than creating a new one, select `true`. We recommend creating a new project to ensure it is isolated by a strong security boundary. | + | `azure_devops_project_name` | `TF_VAR` | `` | Replace `` with the name of the Azure DevOps project to create or the name of an existing project if you set `azure_devops_create_project` to `false`. | + | `use_self_hosted_agents` | `TF_VAR` | `true` | This controls if you want to deploy self-hosted agents. This will default to `true`. | + | `use_private_networking` | `TF_VAR` | `true` | This controls whether private networking is deployed for your self-hosted agents and storage account. This only applies if you have `use_self_hosted_agents` set to `true`. This defaults to `true`. | + | `allow_storage_access_from_my_ip` | `TF_VAR` | `false` | This controls whether to allow access to the storage account from your IP address. This is only needed for trouble shooting. This only applies if you have `use_private_networking` set to `true`. This defaults to `false`. | + | `apply_approvers` | `TF_VAR` | `` | This is a list of service principal names (SPN) of people you wish to be in the group that approves apply of the Azure landing zone module. This is an array of strings like `["abc@xyz.com", "def@xyz.com", "ghi@xyz.com"]`. You may need to check what the SPN is prior to filling this out as it can vary based on identity provider. Use empty array `[]` to disable approvals. Note if supplying via the user interface, use a comma separated string like `abc@xyz.com,def@xyz.com,ghi@xyz.com`. | + | `create_branch_policies` | `TF_VAR` | `true` | This controls whether to create branch policies for the repository. This defaults to `true`. | + | `architecture_definition_name` | `TF_VAR` | N/A | This is the name of the architecture definition to use when applying the ALZ archetypes via the architecture definition template. This is only relevant to some starter modules, such as the `sovereign_landing_zone` starter module. This defaults to `null`. | + +1. Open your `platform-landing-zone.tfvars` file in Visual Studio Code (or your preferred editor) + +1. Now head over to your chosen starter module documentation to get the specific inputs for that module. Make sure to copy the contents of your chosen configuration file into `platform-landing-zone.tfvars`. + - [Terraform Azure Verified Modules for Platform Landing Zone (ALZ)]({{< relref "../../startermodules/terraform-platform-landing-zone" >}}): Management groups, policies, Multi Region hub networking with fully custom configuration. + - [Terraform Financial Services Industry Landing Zone Starter Module]({{< relref "../../startermodules/terraformfsi" >}}): Management groups, policies, hub networking for the Financial Services Industry Landing Zone. + - [Terraform Sovereign Landing Zone Starter Module]({{< relref "../../startermodules/terraformsovereign" >}}): Management groups, policies, hub networking for the Sovereign Landing Zone. + +1. In your PowerShell Core (pwsh) terminal run the module: + + {{< hint type=tip >}} +The following examples include 2 input files. This is the recommended approach for the `platform_landing_zone` starter module. However, all inputs can be split into multiple files if desired. + {{< /hint >}} + + ```pwsh + # Windows without a lib folder (adjust the paths to match your setup) + Deploy-Accelerator ` + -inputs "c:\accelerator\config\inputs.yaml", "c:\accelerator\config\platform-landing-zone.tfvars" ` + -output "c:\accelerator\output" + ``` + + ```pwsh + # Linux/Mac without a lib folder (adjust the paths to match your setup) + Deploy-Accelerator ` + -inputs "/accelerator/config/inputs.yaml", "/accelerator/config/platform-landing-zone.tfvars" ` + -output "/accelerator/output" + ``` + + ```pwsh + # Windows with a lib folder (adjust the paths to match your setup) + Deploy-Accelerator ` + -inputs "c:\accelerator\config\inputs.yaml", "c:\accelerator\config\platform-landing-zone.tfvars" ` + -starterAdditionalFiles "c:\accelerator\config\lib" ` + -output "c:\accelerator\output" + ``` + + ```pwsh + # Linux/Mac with a lib folder (adjust the paths to match your setup) + Deploy-Accelerator ` + -inputs "/accelerator/config/inputs.yaml", "/accelerator/config/platform-landing-zone.tfvars" ` + -starterAdditionalFiles "/accelerator/config/lib" ` + -output "/accelerator/output" + ``` + +1. You will see a Terraform `init` and `apply` happen. +1. There will be a pause after the `plan` phase you allow you to validate what is going to be deployed. +1. If you are happy with the plan, then type `yes` and hit enter. +1. The Terraform will `apply` and your environment will be bootstrapped. + +## Next Steps + +Now head to [Phase 3]({{< relref "3_deploy" >}}). diff --git a/docs/content/accelerator/userguide/2_start/2a_github.md b/docs/content/accelerator/userguide/2_start/terraform-github.md similarity index 50% rename from docs/content/accelerator/userguide/2_start/2a_github.md rename to docs/content/accelerator/userguide/2_start/terraform-github.md index c54a0dd..bdf7841 100644 --- a/docs/content/accelerator/userguide/2_start/2a_github.md +++ b/docs/content/accelerator/userguide/2_start/terraform-github.md @@ -1,103 +1,32 @@ --- -title: GitHub +title: GitHub with Terraform --- -You can choose to bootstrap with `bicep` or `terraform` skip to the relevant section below to do that. +Follow these instructions to bootstrap GitHub ready to deploy your platform landing zone with Terraform. -Although you can just run `Deploy-Accelerator` and fill out the prompted inputs, we recommend creating an inputs file. This will make it easier to run the accelerator more than once in order to refine your preferred configuration. In the following docs, we'll show that approach, but if you want to be prompted for inputs, just go ahead and run `Deploy-Accelerator` now. - -### GitHub with Bicep - -1. Create a new folder on your local drive called `accelerator`. +1. Create a new folder on you local drive called `accelerator`. 1. Inside the accelerator create two folders called `config` and `output`. You'll store you input file inside config and the output folder will be the place that the accelerator stores files while it works. -1. Inside the `config` folder create a new file called `inputs.yaml`. You can use `json` if you prefer, but our examples here are `yaml`. +1. Inside the `config` folder create a new files called `inputs.yaml` and `platform-landing-zone.tfvars`. ```pwsh # Windows New-Item -ItemType "file" c:\accelerator\config\inputs.yaml -Force + New-Item -ItemType "file" c:\accelerator\config\platform-landing-zone.tfvars -Force New-Item -ItemType "directory" c:\accelerator\output - - # Linux/Mac - New-Item -ItemType "file" /accelerator/config/inputs.yaml -Force - New-Item -ItemType "directory" /accelerator/output - ``` - - ```plaintext - 📂accelerator - ┣ 📂config - ┃ ┗ 📜inputs.yaml - ┗ 📂output - ``` - -1. Open your `inputs.yaml` file in Visual Studio Code (or your preferred editor) and copy the content from [inputs-github.yaml](https://raw.githubusercontent.com/Azure/alz-bicep/refs/heads/main/accelerator/examples/bootstrap/inputs-github.yaml) into that file. -1. Check through the file and update each input as required. It is mandatory to update items with placeholders surrounded by angle brackets `<>`: - - {{< hint type=tip >}} -The following inputs can also be supplied via environment variables. This may be useful for sensitive values you don't wish to persist to a file. The `Env Var Prefix` denotes the prefix the environment variable should have. The environment variable is formatting is `_`, e.g. `$env:ALZ_iac_type = "terraform"` or `$env:TF_VAR_github_personal_access_token = "*****..."`. - {{< /hint >}} - - | Input | Env Var Prefix | Placeholder | Description | - | - | - | -- | --- | - | `iac_type` | `ALZ` | `bicep` | This is the choice of `bicep` or `terraform`. Keep this as `bicep` for this example. | - | `bootstrap_module_name` | `ALZ` | `alz_github` | This is the choice of Version Control System. Keep this as `alz_github` for this example. | - | `starter_module_name` | `ALZ` | `complete` | This is the choice of [Starter Modules][wiki_starter_modules], which is the baseline configuration you want for your Azure landing zone. Keep this as `complete` for this example. | - | `bootstrap_location` | `TF_VAR` | `` | Replace `` with the Azure region where you would like to deploy the bootstrap resources in Azure. This field expects the `name` of the region, such as `uksouth`. You can find a full list of names by running `az account list-locations -o table`. | - | `starter_locations` | `TF_VAR` | `[,]` | Replace `` and `` with the Azure regions where you would like to deploy the starter module resources in Azure. This field expects the `name` of the regions in and array, such as `["uksouth", "ukwest"]`. You can find a full list of names by running `az account list-locations -o table`. | - | `root_parent_management_group_id` | `TF_VAR` | `""` | This is the id of the management group that will be the parent of the management group structure created by the accelerator. If you are using the `Tenant Root Group` management group, you leave this as an empty string `""` or supply the tenant id. | - | `subscription_id_management` | `TF_VAR` | `` | Replace `` with the id of the management subscription you created in the previous phase. | - | `subscription_id_identity` | `TF_VAR` | `` | Replace `` with the id of the identity subscription you created in the previous phase. | - | `subscription_id_connectivity` | `TF_VAR` | `` | Replace `` with the id of the connectivity subscription you created in the previous phase. | - | `github_personal_access_token` | `TF_VAR` | `` | Replace `` with the `token-1` GitHub PAT you generated in a previous step. | - | `github_runners_personal_access_token` | `TF_VAR` | `` | Replace `` with the `token-2` GitHub PAT you generated in the previous step specifically for the self-hosted runners. This only applies if you have `use_self_hosted_agents` set to `true`. You can set this to an empty string `""` if you are not using self-hosted runners. | - | `github_organization_name` | `TF_VAR` | `` | Replace `` with the name of your GitHub organization. This is the section of the url after `github.com`. E.g. enter `my-org` for `https://github.com/my-org`. | - | `use_separate_repository_for_templates` | `TF_VAR` | `true` | Determine whether to create a separate repository to store workflow templates as an extra layer of security. Set to `false` if you don't wish to secure your workflow templates by using a separate repository. This will default to `true`. | - | `bootstrap_subscription_id` | `TF_VAR` | `""` | Enter the id of the subscription in which you would like to deploy the bootstrap resources in Azure. If left blank, the subscription you are connected to via `az login` will be used. In most cases this is the management subscription, but you can specifiy a separate subscription if you prefer. | - | `service_name` | `TF_VAR` | `alz` | This is used to build up the names of your Azure and GitHub resources, for example `rg--mgmt-uksouth-001`. We recommend using `alz` for this. | - | `environment_name` | `TF_VAR` | `mgmt` | This is used to build up the names of your Azure and GitHub resources, for example `rg-alz--uksouth-001`. We recommend using `mgmt` for this. | - | `postfix_number` | `TF_VAR` | `1` | This is used to build up the names of your Azure and GitHub resources, for example `rg-alz-mgmt-uksouth-`. We recommend using `1` for this. | - | `use_self_hosted_agents` | `TF_VAR` | `true` | This controls if you want to deploy self-hosted agents. This will default to `true`. | - | `use_private_networking` | `TF_VAR` | `true` | This controls whether private networking is deployed for your self-hosted agents and storage account. This only applies if you have `use_self_hosted_agents` set to `true`. This defaults to `true`. | - | `allow_storage_access_from_my_ip` | `TF_VAR` | `false` | This is not relevant to Bicep and we'll remove the need to specify it later, leave it set to `false`. | - | `apply_approvers` | `TF_VAR` | `` | This is a list of service principal names (SPN) of people you wish to be in the group that approves apply of the Azure landing zone module. This is an array of strings like `["abc@xyz.com", "def@xyz.com", "ghi@xyz.com"]`. You may need to check what the SPN is prior to filling this out as it can vary based on identity provider. Use empty array `[]` to disable approvals. Note if supplying via the user interface, use a comma separated string like `abc@xyz.com,def@xyz.com,ghi@xyz.com`. | - | `create_branch_policies` | `TF_VAR` | `true` | This controls whether to create branch policies for the repository. This defaults to `true`. | - -1. Now head over to your chosen starter module documentation to get the specific inputs for that module. Come back here when you are done. - - [Bicep Complete Starter Module]({{< relref "../../startermodules/bicepcomplete" >}}) -1. In your PowerShell Core (pwsh) terminal run the module: - - ```pwsh - # Windows (adjust the paths to match your setup) - Deploy-Accelerator -inputs "c:\accelerator\config\inputs.yaml" -output "c:\accelerator\output" - - # Linux/Mac (adjust the paths to match your setup) - Deploy-Accelerator -inputs "/accelerator/config/inputs.yaml" -output "/accelerator/output" ``` -1. You will see a Terraform `init` and `apply` happen. -1. There will be a pause after the `plan` phase you allow you to validate what is going to be deployed. -1. If you are happy with the plan, then type `yes` and hit enter. -1. The Terraform will `apply` and your environment will be bootstrapped. - -### GitHub with Terraform - -1. Create a new folder on you local drive called `accelerator`. -1. Inside the accelerator create two folders called `config` and `output`. You'll store you input file inside config and the output folder will be the place that the accelerator stores files while it works. -1. Inside the `config` folder create a new file called `inputs.yaml`. You can use `json` if you prefer, but our examples here are `yaml`. - ```pwsh - # Windows - New-Item -ItemType "file" c:\accelerator\config\inputs.yaml -Force - New-Item -ItemType "directory" c:\accelerator\output - # Linux/Mac New-Item -ItemType "file" /accelerator/config/inputs.yaml -Force + New-Item -ItemType "file" c:\accelerator\config\platform-landing-zone.tfvars -Force New-Item -ItemType "directory" /accelerator/output ``` ```plaintext 📂accelerator ┣ 📂config - ┃ ┗ 📜inputs.yaml + ┃ ┣📜inputs.yaml + ┃ ┗📜platform-landing-zone.tfvars ┗ 📂output ``` @@ -105,6 +34,7 @@ The following inputs can also be supplied via environment variables. This may be 1. Azure Verified Modules for Platform Landing Zone (ALZ) - [inputs-github.yaml](https://raw.githubusercontent.com/Azure/alz-terraform-accelerator/refs/heads/main/templates/platform_landing_zone/examples/bootstrap/inputs-github.yaml) 1. Financial Services Industry Landing Zone - [inputs-github.yaml](https://raw.githubusercontent.com/Azure/alz-terraform-accelerator/refs/heads/main/templates/microsoft_cloud_for_industry/financial_services_landing_zone/examples/bootstrap/github-local.yaml) 1. Sovereign Landing Zone - [inputs-github.yaml](https://raw.githubusercontent.com/Azure/alz-terraform-accelerator/refs/heads/main/templates/microsoft_cloud_for_industry/sovereign_landing_zone/examples/bootstrap/github-local.yaml) + 1. Check through the file and update each input as required. It is mandatory to update items with placeholders surrounded by angle brackets `<>`: {{< hint type=tip >}} @@ -137,7 +67,9 @@ The following inputs can also be supplied via environment variables. This may be | `create_branch_policies` | `TF_VAR` | `true` | This controls whether to create branch policies for the repository. This defaults to `true`. | | `architecture_definition_name` | `TF_VAR` | N/A | This is the name of the architecture definition to use when applying the ALZ archetypes via the architecture definition template. This is only relevant to some starter modules, such as the `sovereign_landing_zone` starter module. This defaults to `null`. | -1. Now head over to your chosen starter module documentation to get the specific inputs for that module. Come back here when you are done. +1. Open your `platform-landing-zone.tfvars` file in Visual Studio Code (or your preferred editor) + +1. Now head over to your chosen starter module documentation to get the specific inputs for that module. Make sure to copy the contents of your chosen configuration file into `platform-landing-zone.tfvars`. - [Terraform Azure Verified Modules for Platform Landing Zone (ALZ)]({{< relref "../../startermodules/terraform-platform-landing-zone" >}}): Management groups, policies, Multi Region hub networking with fully custom configuration. - [Terraform Financial Services Industry Landing Zone Starter Module]({{< relref "../../startermodules/terraformfsi" >}}): Management groups, policies, hub networking for the Financial Services Industry Landing Zone. - [Terraform Sovereign Landing Zone Starter Module]({{< relref "../../startermodules/terraformsovereign" >}}): Management groups, policies, hub networking for the Sovereign Landing Zone. @@ -145,17 +77,37 @@ The following inputs can also be supplied via environment variables. This may be 1. In your PowerShell Core (pwsh) terminal run the module: {{< hint type=tip >}} -The following examples include 2 input files. This is the recommended approach for the `platform_landing_zone` starter module. However, all inputs into multiple files if desired. +The following examples include 2 input files. This is the recommended approach for the `platform_landing_zone` starter module. However, all inputs can be split into multiple files if desired. {{< /hint >}} ```pwsh - # Windows (adjust the paths to match your setup) - Deploy-Accelerator -inputs "c:\accelerator\config\inputs.yaml", "c:\accelerator\config\networking.yaml" -output "c:\accelerator\output" + # Windows without a lib folder (adjust the paths to match your setup) + Deploy-Accelerator ` + -inputs "c:\accelerator\config\inputs.yaml", "c:\accelerator\config\platform-landing-zone.tfvars" ` + -output "c:\accelerator\output" + ``` + + ```pwsh + # Linux/Mac without a lib folder (adjust the paths to match your setup) + Deploy-Accelerator ` + -inputs "/accelerator/config/inputs.yaml", "/accelerator/config/platform-landing-zone.tfvars" ` + -output "/accelerator/output" + ``` + + ```pwsh + # Windows with a lib folder (adjust the paths to match your setup) + Deploy-Accelerator ` + -inputs "c:\accelerator\config\inputs.yaml", "c:\accelerator\config\platform-landing-zone.tfvars" ` + -starterAdditionalFiles "c:\accelerator\config\lib" ` + -output "c:\accelerator\output" ``` ```pwsh - # Linux/Mac (adjust the paths to match your setup) - Deploy-Accelerator -inputs "/accelerator/config/inputs.yaml", "/accelerator/config/networking.yaml" -output "/accelerator/output" + # Linux/Mac with a lib folder (adjust the paths to match your setup) + Deploy-Accelerator ` + -inputs "/accelerator/config/inputs.yaml", "/accelerator/config/platform-landing-zone.tfvars" ` + -starterAdditionalFiles "/accelerator/config/lib" ` + -output "/accelerator/output" ``` 1. You will see a Terraform `init` and `apply` happen. diff --git a/docs/content/accelerator/userguide/2_start/2c_local.md b/docs/content/accelerator/userguide/2_start/terraform-local.md similarity index 50% rename from docs/content/accelerator/userguide/2_start/2c_local.md rename to docs/content/accelerator/userguide/2_start/terraform-local.md index 54bd0ce..e0c34e3 100644 --- a/docs/content/accelerator/userguide/2_start/2c_local.md +++ b/docs/content/accelerator/userguide/2_start/terraform-local.md @@ -1,98 +1,32 @@ --- -title: Local File System +title: Local File System with Terraform --- -You can choose to bootstrap with `bicep` or `terraform` skip to the relevant section below to do that. +Follow these instructions to bootstrap a local file system folder ready to deploy your platform landing zone with Terraform. -Although you can just run `Deploy-Accelerator` and fill out the prompted inputs, we recommend creating an inputs file. This will make it easier to run the accelerator more than once in order to refine your preferred configuration. In the following docs, we'll show that approach, but if you want to be prompted for inputs, just go ahead and run `Deploy-Accelerator` now. - -## Local File System with Bicep - -1. Create a new folder on your local drive called `accelerator`. +1. Create a new folder on you local drive called `accelerator`. 1. Inside the accelerator create two folders called `config` and `output`. You'll store you input file inside config and the output folder will be the place that the accelerator stores files while it works. -1. Inside the `config` folder create a new file called `inputs.yaml`. You can use `json` if you prefer, but our examples here are `yaml`. +1. Inside the `config` folder create a new files called `inputs.yaml` and `platform-landing-zone.tfvars`. ```pwsh # Windows New-Item -ItemType "file" c:\accelerator\config\inputs.yaml -Force + New-Item -ItemType "file" c:\accelerator\config\platform-landing-zone.tfvars -Force New-Item -ItemType "directory" c:\accelerator\output - - # Linux/Mac - New-Item -ItemType "file" /accelerator/config/inputs.yaml -Force - New-Item -ItemType "directory" /accelerator/output - ``` - - ```plaintext - 📂accelerator - ┣ 📂config - ┃ ┗ 📜inputs.yaml - ┗ 📂output - ``` - -1. Open your `inputs.yaml` file in Visual Studio Code (or your preferred editor) and copy the content from [inputs-local.yaml](https://raw.githubusercontent.com/Azure/alz-bicep/refs/heads/main/accelerator/examples/bootstrap/inputs-local.yaml) into that file. -1. Check through the file and update each input as required. It is mandatory to update items with placeholders surrounded by angle brackets `<>`: - - {{< hint type=tip >}} -The following inputs can also be supplied via environment variables. This may be useful for sensitive values you don't wish to persist to a file. The `Env Var Prefix` denotes the prefix the environment variable should have. The environment variable is formatting is `_`, e.g. `$env:ALZ_iac_type = "terraform"` or `$env:TF_VAR_github_personal_access_token = "*****..."`. - {{< /hint >}} - - | Input | Env Var Prefix | Placeholder | Description | - | - | - | -- | --- | - | `iac_type` | `ALZ` | `bicep` | This is the choice of `bicep` or `terraform`. Keep this as `bicep` for this example. | - | `bootstrap_module_name` | `ALZ` | `alz_local` | This is the choice of Version Control System. Keep this as `alz_local` for this example. | - | `starter_module_name` | `ALZ` | `complete` | This is the choice of [Starter Modules][wiki_starter_modules], which is the baseline configuration you want for your Azure landing zone. Keep this as `complete` for this example. | - | `bootstrap_location` | `TF_VAR` | `` | Replace `` with the Azure region where you would like to deploy the bootstrap resources in Azure. This field expects the `name` of the region, such as `uksouth`. You can find a full list of names by running `az account list-locations -o table`. | - | `starter_locations` | `TF_VAR` | `[,]` | Replace `` and `` with the Azure regions where you would like to deploy the starter module resources in Azure. This field expects the `name` of the regions in and array, such as `["uksouth", "ukwest"]`. You can find a full list of names by running `az account list-locations -o table`. | - | `root_parent_management_group_id` | `TF_VAR` | `""` | This is the id of the management group that will be the parent of the management group structure created by the accelerator. If you are using the `Tenant Root Group` management group, you leave this as an empty string `""` or supply the tenant id. | - | `subscription_id_management` | `TF_VAR` | `` | Replace `` with the id of the management subscription you created in the previous phase. | - | `subscription_id_identity` | `TF_VAR` | `` | Replace `` with the id of the identity subscription you created in the previous phase. | - | `subscription_id_connectivity` | `TF_VAR` | `` | Replace `` with the id of the connectivity subscription you created in the previous phase. | - | `target_directory` | `TF_VAR` | `""` | This is the directory where the ALZ module code will be created. This defaults a directory called `local-output` in the root of the accelerator output directory if not supplied. | - | `create_bootstrap_resources_in_azure` | `TF_VAR` | `true` | This determines whether the bootstrap will create the bootstrap resources in Azure. This defaults to `true`. | - | `bootstrap_subscription_id` | `TF_VAR` | `""` | Enter the id of the subscription in which you would like to deploy the bootstrap resources in Azure. If left blank, the subscription you are connected to via `az login` will be used. In most cases this is the management subscription, but you can specifiy a separate subscription if you prefer. | - | `service_name` | `TF_VAR` | `alz` | This is used to build up the names of your Azure and Azure DevOps resources, for example `rg--mgmt-uksouth-001`. We recommend using `alz` for this. | - | `environment_name` | `TF_VAR` | `mgmt` | This is used to build up the names of your Azure and Azure DevOps resources, for example `rg-alz--uksouth-001`. We recommend using `mgmt` for this. | - | `postfix_number` | `TF_VAR` | `1` | This is used to build up the names of your Azure and Azure DevOps resources, for example `rg-alz-mgmt-uksouth-`. We recommend using `1` for this. | - | `grant_permissions_to_current_user` | `TF_VAR` | `true` | This determines whether the bootstrap will grant the current user permissions to the management group structure created by the accelerator. This defaults to `true` so that the starter module can be immediately deployed from the local file system. Set this to `false` if you itend to wire up CI/CD with your own provider. | - -1. Now head over to your chosen starter module documentation to get the specific inputs for that module. Come back here when you are done. - - [Bicep Complete Starter Module][wiki_starter_module_bicep_complete] -1. In your PowerShell Core (pwsh) terminal run the module: - - ```pwsh - # Windows (adjust the paths to match your setup) - Deploy-Accelerator -inputs "c:\accelerator\config\inputs.yaml" -output "c:\accelerator\output" - - # Linux/Mac (adjust the paths to match your setup) - Deploy-Accelerator -inputs "/accelerator/config/inputs.yaml" -output "/accelerator/output" ``` -1. You will see a Terraform `init` and `apply` happen. -1. There will be a pause after the `plan` phase you allow you to validate what is going to be deployed. -1. If you are happy with the plan, then type `yes` and hit enter. -1. The Terraform will `apply` and your environment will be bootstrapped. -1. You will find the output in the `/accelerator/output/local-output` folder if you didn't specifiy a different location for `target_directory`. - -## File System with Terraform - -1. Create a new folder on you local drive called `accelerator`. -1. Inside the accelerator create two folders called `config` and `output`. You'll store you input file inside config and the output folder will be the place that the accelerator stores files while it works. -1. Inside the `config` folder create a new file called `inputs.yaml`. You can use `json` if you prefer, but our examples here are `yaml`. - ```pwsh - # Windows - New-Item -ItemType "file" c:\accelerator\config\inputs.yaml -Force - New-Item -ItemType "directory" c:\accelerator\output - # Linux/Mac New-Item -ItemType "file" /accelerator/config/inputs.yaml -Force + New-Item -ItemType "file" c:\accelerator\config\platform-landing-zone.tfvars -Force New-Item -ItemType "directory" /accelerator/output ``` ```plaintext 📂accelerator ┣ 📂config - ┃ ┗ 📜inputs.yaml + ┃ ┣📜inputs.yaml + ┃ ┗📜platform-landing-zone.tfvars ┗ 📂output ``` @@ -100,6 +34,7 @@ The following inputs can also be supplied via environment variables. This may be 1. Azure Verified Modules for Platform Landing Zone (ALZ) - [inputs-local.yaml](https://raw.githubusercontent.com/Azure/alz-terraform-accelerator/refs/heads/main/templates/platform_landing_zone/examples/bootstrap/inputs-local.yaml) 1. Financial Services Industry Landing Zone - [inputs-local.yaml](https://raw.githubusercontent.com/Azure/alz-terraform-accelerator/refs/heads/main/templates/microsoft_cloud_for_industry/financial_services_landing_zone/examples/bootstrap/inputs-local.yaml) 1. Sovereign Landing Zone - [inputs-local.yaml](https://raw.githubusercontent.com/Azure/alz-terraform-accelerator/refs/heads/main/templates/microsoft_cloud_for_industry/sovereign_landing_zone/examples/bootstrap/inputs-local.yaml) + 1. Check through the file and update each input as required. It is mandatory to update items with placeholders surrounded by angle brackets `<>`: {{< hint type=tip >}} @@ -126,7 +61,9 @@ The following inputs can also be supplied via environment variables. This may be | `grant_permissions_to_current_user` | `TF_VAR` | `true` | This determines whether the bootstrap will grant the current user permissions to the management group structure and stroage account created by the accelerator. This defaults to `true` so that the starter module can be immediately deployed from the local file system. Set this to `false` if you itend to wire up CI/CD with your own provider. | | `architecture_definition_name` | `TF_VAR` | N/A | This is the name of the architecture definition to use when applying the ALZ archetypes via the architecture definition template. This is only relevant to some starter modules, such as the `sovereign_landing_zone` starter module. This defaults to `null`. | -1. Now head over to your chosen starter module documentation to get the specific inputs for that module. Come back here when you are done. +1. Open your `platform-landing-zone.tfvars` file in Visual Studio Code (or your preferred editor) + +1. Now head over to your chosen starter module documentation to get the specific inputs for that module. Make sure to copy the contents of your chosen configuration file into `platform-landing-zone.tfvars`. - [Terraform Azure Verified Modules for Platform Landing Zone (ALZ)]({{< relref "../../startermodules/terraform-platform-landing-zone" >}}): Management groups, policies, Multi Region hub networking with fully custom configuration. - [Terraform Financial Services Industry Landing Zone Starter Module]({{< relref "../../startermodules/terraformfsi" >}}): Management groups, policies, hub networking for the Financial Services Industry Landing Zone. - [Terraform Sovereign Landing Zone Starter Module]({{< relref "../../startermodules/terraformsovereign" >}}): Management groups, policies, hub networking for the Sovereign Landing Zone. @@ -134,17 +71,37 @@ The following inputs can also be supplied via environment variables. This may be 1. In your PowerShell Core (pwsh) terminal run the module: {{< hint type=tip >}} -The following examples include 2 input files. This is the recommended approach for the `platform_landing_zone` starter module. However, all inputs into multiple files if desired. +The following examples include 2 input files. This is the recommended approach for the `platform_landing_zone` starter module. However, all inputs can be split into multiple files if desired. {{< /hint >}} ```pwsh - # Windows (adjust the paths to match your setup) - Deploy-Accelerator -inputs "c:\accelerator\config\inputs.yaml", "c:\accelerator\config\networking.yaml" -output "c:\accelerator\output" + # Windows without a lib folder (adjust the paths to match your setup) + Deploy-Accelerator ` + -inputs "c:\accelerator\config\inputs.yaml", "c:\accelerator\config\platform-landing-zone.tfvars" ` + -output "c:\accelerator\output" + ``` + + ```pwsh + # Linux/Mac without a lib folder (adjust the paths to match your setup) + Deploy-Accelerator ` + -inputs "/accelerator/config/inputs.yaml", "/accelerator/config/platform-landing-zone.tfvars" ` + -output "/accelerator/output" + ``` + + ```pwsh + # Windows with a lib folder (adjust the paths to match your setup) + Deploy-Accelerator ` + -inputs "c:\accelerator\config\inputs.yaml", "c:\accelerator\config\platform-landing-zone.tfvars" ` + -starterAdditionalFiles "c:\accelerator\config\lib" ` + -output "c:\accelerator\output" ``` ```pwsh - # Linux/Mac (adjust the paths to match your setup) - Deploy-Accelerator -inputs "/accelerator/config/inputs.yaml", "/accelerator/config/networking.yaml" -output "/accelerator/output" + # Linux/Mac with a lib folder (adjust the paths to match your setup) + Deploy-Accelerator ` + -inputs "/accelerator/config/inputs.yaml", "/accelerator/config/platform-landing-zone.tfvars" ` + -starterAdditionalFiles "/accelerator/config/lib" ` + -output "/accelerator/output" ``` 1. You will see a Terraform `init` and `apply` happen. diff --git a/docs/hugo.toml b/docs/hugo.toml index 99cb35e..ffe71e7 100644 --- a/docs/hugo.toml +++ b/docs/hugo.toml @@ -25,6 +25,9 @@ endLevel = 9 tag = "tags" [params] +showPreviewBanner = true +previewBannerTitle = "Preview Only!" +previewBannerText = "This site is under development and subject to change. Please do not rely on the information contained here. Look out for some exciting updates to Azure Landing Zones coming in 2025!" # (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 paramet.Site.IsMultiLingualer per page in front matter. diff --git a/docs/themes/hugo-geekdoc/layouts/partials/site-header.html b/docs/themes/hugo-geekdoc/layouts/partials/site-header.html index 07aabf1..f60f45b 100644 --- a/docs/themes/hugo-geekdoc/layouts/partials/site-header.html +++ b/docs/themes/hugo-geekdoc/layouts/partials/site-header.html @@ -1,4 +1,14 @@
+ + {{ if site.Params.showPreviewBanner }} +
+
+
+
{{ site.Params.previewBannerText }}
+
+
+ {{ end }} +
{{ if .MenuEnabled }}