From 1f302b982152e877082e501b11f3549fd8e6a523 Mon Sep 17 00:00:00 2001 From: Sacha Narinx Date: Wed, 2 Oct 2024 12:29:13 +0400 Subject: [PATCH] docs: Update placeholder value in ALZ module code creation (#203) # Pull Request ## Description This pull request includes several documentation updates to clarify the usage of configuration file paths and default directory values. The most important changes involve adding instructions for escaping backslashes in YAML file paths on Windows and specifying how to handle default directory values. Clarifications in documentation: * `docs/wiki/[User-Guide]-Quick-Start-Phase-2-Local.md`: Updated the description for the `target_directory` input to specify that the placeholder value `` should be removed to use the default value. ([docs/wiki/[User-Guide]-Quick-Start-Phase-2-Local.mdL45-R45](diffhunk://#diff-f86bb4f6ce154adfd0bf07c039be16f163e0e081779c957de4826e664e2792d0L45-R45), [docs/wiki/[User-Guide]-Quick-Start-Phase-2-Local.mdL113-R113](diffhunk://#diff-f86bb4f6ce154adfd0bf07c039be16f163e0e081779c957de4826e664e2792d0L113-R113)) * `docs/wiki/[User-Guide]-Starter-Module-Terraform-Complete-Multi-Region.md`: Added a note that backslashes need to be escaped in YAML file paths on Windows. ([docs/wiki/[User-Guide]-Starter-Module-Terraform-Complete-Multi-Region.mdL18-R18](diffhunk://#diff-edeec51894dbd58453488f2badb0e44737d2aa7e16be2dd6fe71cd211149db69L18-R18)) * `docs/wiki/[User-Guide]-Starter-Module-Terraform-Complete-VNext.md`: Added a note that backslashes need to be escaped in YAML file paths on Windows. ([docs/wiki/[User-Guide]-Starter-Module-Terraform-Complete-VNext.mdL19-R19](diffhunk://#diff-94372c563fe90e45582ccdb428559491398b4e10af345feeebdbe737633c417bL19-R19)) * `docs/wiki/[User-Guide]-Starter-Module-Terraform-Complete.md`: Added a note that backslashes need to be escaped in YAML file paths on Windows. ([docs/wiki/[User-Guide]-Starter-Module-Terraform-Complete.mdL17-R17](diffhunk://#diff-c95238aa2c2777c9c78aaf4534391f3195707d10f6edf94a1defa573a10d017aL17-R17)) ## License By submitting this pull request, I confirm that my contribution is made under the terms of the projects associated license. --------- Co-authored-by: Jared Holgate --- .github/workflows/wiki-sync.yml | 2 +- .../[User-Guide]-Quick-Start-Phase-2-Local.md | 16 ++++++---------- ...ter-Module-Terraform-Complete-Multi-Region.md | 2 +- ...e]-Starter-Module-Terraform-Complete-VNext.md | 2 +- ...r-Guide]-Starter-Module-Terraform-Complete.md | 2 +- .../inputs-local-bicep-complete.yaml | 2 +- .../inputs-local-terraform-basic.yaml | 2 +- ...ts-local-terraform-complete-multi-region.yaml | 2 +- .../inputs-local-terraform-complete-vnext.yaml | 2 +- .../inputs-local-terraform-complete.yaml | 2 +- .../inputs-local-terraform-hubnetworking.yaml | 2 +- 11 files changed, 16 insertions(+), 20 deletions(-) diff --git a/.github/workflows/wiki-sync.yml b/.github/workflows/wiki-sync.yml index 2b8b5ea1..bd0a4c0a 100644 --- a/.github/workflows/wiki-sync.yml +++ b/.github/workflows/wiki-sync.yml @@ -7,7 +7,7 @@ permissions: # yamllint disable-line rule:truthy on: release: - types: [published] + types: [published, released] workflow_dispatch: env: diff --git a/docs/wiki/[User-Guide]-Quick-Start-Phase-2-Local.md b/docs/wiki/[User-Guide]-Quick-Start-Phase-2-Local.md index 0e55d7fb..137279e7 100644 --- a/docs/wiki/[User-Guide]-Quick-Start-Phase-2-Local.md +++ b/docs/wiki/[User-Guide]-Quick-Start-Phase-2-Local.md @@ -15,20 +15,17 @@ Although you can just run `Deploy-Accelerator` and fill out the prompted inputs, # Windows New-Item -ItemType "file" c:\accelerator\config\inputs.yaml -Force New-Item -ItemType "directory" c:\accelerator\output - New-Item -ItemType "directory" c:\accelerator\target # Linux/Mac New-Item -ItemType "file" /accelerator/config/inputs.yaml -Force New-Item -ItemType "directory" /accelerator/output - New-Item -ItemType "directory" /accelerator/target ``` ```plaintext 📂accelerator ┣ 📂config ┃ ┗ 📜inputs.yaml - ┃ 📂output - ┗ 📂target + ┗ 📂output ``` 1. Open your `inputs.yaml` file in Visual Studio Code (or your preferred editor) and copy the content from [inputs-local-bicep-complete.yaml][example_powershell_inputs_local_bicep_complete] into that file. @@ -47,7 +44,7 @@ Although you can just run `Deploy-Accelerator` and fill out the prompted inputs, | `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` | `/accelerator/target` | 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. | + | `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. | @@ -71,6 +68,7 @@ Although you can just run `Deploy-Accelerator` and fill out the prompted inputs, 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`. ### 2.2.3.2 Local File System with Terraform @@ -82,20 +80,17 @@ Although you can just run `Deploy-Accelerator` and fill out the prompted inputs, # Windows New-Item -ItemType "file" c:\accelerator\config\inputs.yaml -Force New-Item -ItemType "directory" c:\accelerator\output - New-Item -ItemType "directory" c:\accelerator\target # Linux/Mac New-Item -ItemType "file" /accelerator/config/inputs.yaml -Force New-Item -ItemType "directory" /accelerator/output - New-Item -ItemType "directory" /accelerator/target ``` ```plaintext 📂accelerator ┣ 📂config ┃ ┗ 📜inputs.yaml - ┃ 📂output - ┗ 📂target + ┗ 📂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: @@ -118,7 +113,7 @@ Although you can just run `Deploy-Accelerator` and fill out the prompted inputs, | `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` | `/accelerator/target` | 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. | + | `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. | @@ -146,6 +141,7 @@ Although you can just run `Deploy-Accelerator` and fill out the prompted inputs, 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 diff --git a/docs/wiki/[User-Guide]-Starter-Module-Terraform-Complete-Multi-Region.md b/docs/wiki/[User-Guide]-Starter-Module-Terraform-Complete-Multi-Region.md index 5173fbd3..53ff54bb 100644 --- a/docs/wiki/[User-Guide]-Starter-Module-Terraform-Complete-Multi-Region.md +++ b/docs/wiki/[User-Guide]-Starter-Module-Terraform-Complete-Multi-Region.md @@ -15,7 +15,7 @@ The following table describes the inputs required for the `complete_multi_region | Input | Placeholder | Description | | - | -- | --- | -| `configuration_file_path` | `` | This is the absolute path to the configuration file. E.g. `c:\my-config\config.yaml` or `~/my-config/config.yaml` | +| `configuration_file_path` | `` | This is the absolute path to the configuration file. E.g. `c:\my-config\config.yaml` or `~/my-config/config.yaml`. For YAML on Windows you will need to escape the `\`, i.e. `c:\\my-config\\config.yaml`. | | `default_postfix` | `` | This is the default postfix used for resource names. | You can create a custom yaml config to tailor to your needs, for example an Azure Landing Zone with a three-region mesh. Get started with our two region samples: diff --git a/docs/wiki/[User-Guide]-Starter-Module-Terraform-Complete-VNext.md b/docs/wiki/[User-Guide]-Starter-Module-Terraform-Complete-VNext.md index e61b5834..658a3452 100644 --- a/docs/wiki/[User-Guide]-Starter-Module-Terraform-Complete-VNext.md +++ b/docs/wiki/[User-Guide]-Starter-Module-Terraform-Complete-VNext.md @@ -16,7 +16,7 @@ The following table describes the inputs required for the `complete_vnext` start | Input | Placeholder | Description | | - | -- | --- | -| `configuration_file_path` | `` | This is the absolute path to the configuration file. E.g. `c:\my-config\config.yaml` or `~/my-config/config.yaml` | +| `configuration_file_path` | `` | This is the absolute path to the configuration file. E.g. `c:\my-config\config.yaml` or `~/my-config/config.yaml`. For YAML on Windows you will need to escape the `\`, i.e. `c:\\my-config\\config.yaml`. | | `default_postfix` | `` | This is the default postfix used for resource names. | ## Further details on the Complete Starter Module and config file diff --git a/docs/wiki/[User-Guide]-Starter-Module-Terraform-Complete.md b/docs/wiki/[User-Guide]-Starter-Module-Terraform-Complete.md index 4d007ffe..89ed89d4 100644 --- a/docs/wiki/[User-Guide]-Starter-Module-Terraform-Complete.md +++ b/docs/wiki/[User-Guide]-Starter-Module-Terraform-Complete.md @@ -14,7 +14,7 @@ The following table describes the inputs required for the `complete` starter mod | Input | Placeholder | Description | | - | -- | --- | -| `configuration_file_path` | `` | This is the absolute path to the configuration file. E.g. `c:\my-config\config.yaml` or `~/my-config/config.yaml` | +| `configuration_file_path` | `` | This is the absolute path to the configuration file. E.g. `c:\my-config\config.yaml` or `~/my-config/config.yaml`. For YAML on Windows you will need to escape the `\`, i.e. `c:\\my-config\\config.yaml`. | | `default_postfix` | `` | This is the default postfix used for resource names. | ## Further details on the Complete Starter Module and config file diff --git a/docs/wiki/examples/powershell-inputs/inputs-local-bicep-complete.yaml b/docs/wiki/examples/powershell-inputs/inputs-local-bicep-complete.yaml index f7683024..39e33e26 100644 --- a/docs/wiki/examples/powershell-inputs/inputs-local-bicep-complete.yaml +++ b/docs/wiki/examples/powershell-inputs/inputs-local-bicep-complete.yaml @@ -16,7 +16,7 @@ subscription_id_identity: "" subscription_id_connectivity: "" # Bootstrap Inputs -target_directory: "/accelerator/target" +target_directory: "" create_bootstrap_resources_in_azure: "true" bootstrap_subscription_id: "" service_name: "alz" diff --git a/docs/wiki/examples/powershell-inputs/inputs-local-terraform-basic.yaml b/docs/wiki/examples/powershell-inputs/inputs-local-terraform-basic.yaml index 6a0c6a5d..d0b66329 100644 --- a/docs/wiki/examples/powershell-inputs/inputs-local-terraform-basic.yaml +++ b/docs/wiki/examples/powershell-inputs/inputs-local-terraform-basic.yaml @@ -16,7 +16,7 @@ subscription_id_identity: "" subscription_id_connectivity: "" # Bootstrap Inputs -target_directory: "/accelerator/target" +target_directory: "" create_bootstrap_resources_in_azure: true bootstrap_subscription_id: "" service_name: "alz" diff --git a/docs/wiki/examples/powershell-inputs/inputs-local-terraform-complete-multi-region.yaml b/docs/wiki/examples/powershell-inputs/inputs-local-terraform-complete-multi-region.yaml index ed5ee3a1..77a658cd 100644 --- a/docs/wiki/examples/powershell-inputs/inputs-local-terraform-complete-multi-region.yaml +++ b/docs/wiki/examples/powershell-inputs/inputs-local-terraform-complete-multi-region.yaml @@ -16,7 +16,7 @@ subscription_id_identity: "" subscription_id_connectivity: "" # Bootstrap Inputs -target_directory: "/accelerator/target" +target_directory: "" create_bootstrap_resources_in_azure: true bootstrap_subscription_id: "" service_name: "alz" diff --git a/docs/wiki/examples/powershell-inputs/inputs-local-terraform-complete-vnext.yaml b/docs/wiki/examples/powershell-inputs/inputs-local-terraform-complete-vnext.yaml index b2fb8ef8..44e1e9d5 100644 --- a/docs/wiki/examples/powershell-inputs/inputs-local-terraform-complete-vnext.yaml +++ b/docs/wiki/examples/powershell-inputs/inputs-local-terraform-complete-vnext.yaml @@ -16,7 +16,7 @@ subscription_id_identity: "" subscription_id_connectivity: "" # Bootstrap Inputs -target_directory: "/accelerator/target" +target_directory: "" create_bootstrap_resources_in_azure: true bootstrap_subscription_id: "" service_name: "alz" diff --git a/docs/wiki/examples/powershell-inputs/inputs-local-terraform-complete.yaml b/docs/wiki/examples/powershell-inputs/inputs-local-terraform-complete.yaml index 08b002a2..db8f3f31 100644 --- a/docs/wiki/examples/powershell-inputs/inputs-local-terraform-complete.yaml +++ b/docs/wiki/examples/powershell-inputs/inputs-local-terraform-complete.yaml @@ -16,7 +16,7 @@ subscription_id_identity: "" subscription_id_connectivity: "" # Bootstrap Inputs -target_directory: "/accelerator/target" +target_directory: "" create_bootstrap_resources_in_azure: true bootstrap_subscription_id: "" service_name: "alz" diff --git a/docs/wiki/examples/powershell-inputs/inputs-local-terraform-hubnetworking.yaml b/docs/wiki/examples/powershell-inputs/inputs-local-terraform-hubnetworking.yaml index 8c0b2f97..f6ea87bd 100644 --- a/docs/wiki/examples/powershell-inputs/inputs-local-terraform-hubnetworking.yaml +++ b/docs/wiki/examples/powershell-inputs/inputs-local-terraform-hubnetworking.yaml @@ -16,7 +16,7 @@ subscription_id_identity: "" subscription_id_connectivity: "" # Bootstrap Inputs -target_directory: "/accelerator/target" +target_directory: "" create_bootstrap_resources_in_azure: true bootstrap_subscription_id: "" service_name: "alz"