From d0ae68a61a67d6ec51bbd77bc95db661d992c035 Mon Sep 17 00:00:00 2001 From: Jared Holgate Date: Wed, 26 Feb 2025 22:02:32 +0000 Subject: [PATCH] chore: improve docs (#62) --- DEVELOPER.md | 6 ++++ docs/content/accelerator/faq.md | 34 +++++++++++++++---- .../userguide/1_prerequisites/_index.md | 19 ++++++++--- 3 files changed, 48 insertions(+), 11 deletions(-) diff --git a/DEVELOPER.md b/DEVELOPER.md index 54e2b77..afbf799 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -5,6 +5,12 @@ You will need Hugo installed on your machine to build the documentation. You can download Hugo from the [Hugo website](https://gohugo.io/installation/). Make sure you install the same version as the one specified in the `.github/workflows/hugo.yml` file. +For example: + +```pwsh +winget install Hugo.Hugo.Extended -v 0.136.5 +``` + ## Creating a local HTTP server To create a local HTTP server, if you are on Linux and have GNU make installed, run the following command: diff --git a/docs/content/accelerator/faq.md b/docs/content/accelerator/faq.md index 8b28887..8477d55 100644 --- a/docs/content/accelerator/faq.md +++ b/docs/content/accelerator/faq.md @@ -60,6 +60,7 @@ resource_names: container_registry_private_endpoint: "pe-{{service_name}}-{{environment_name}}-{{azure_location}}-acr-{{postfix_number}}" container_image_name: "azure-devops-agent" ``` + ## Questions about bootstrap clean up ### I was just testing or I made a mistake, how do I remove the bootstrap environment and start again? @@ -68,10 +69,29 @@ 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 -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`. +1. Now run `Deploy-Accelerator` with the `-destroy` flag, for example: + + {{< tabs "1" >}} + {{< tab "Windows" >}} +```pwsh +Deploy-Accelerator ` + -inputs "c:\accelerator\config\inputs.yaml", "c:\accelerator\config\platform-landing-zone.tfvars" ` + -output "c:\accelerator\output" ` + -destroy +``` + {{< /tab >}} + {{< tab "Linux / macOS" >}} +```pwsh +Deploy-Accelerator ` + -inputs "/accelerator/config/inputs.yaml", "/accelerator/config/platform-landing-zone.tfvars" ` + -output "/accelerator/output" ` + -destroy +``` + {{< /tab >}} + {{< /tabs >}} + +1. You can confirm the destroy by hitting enter when prompted. +1. To fully clean up, you should now delete the folder that was created for the accelerator. 1. You'll now be able to run the `Deploy-Accelerator` command again to start fresh. ## Questions about changing variables @@ -100,8 +120,8 @@ After bootstrapping, the PowerShell leaves the folder structure intact, includin 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 -inputs "~/config/inputs1.json" -output "./deployment1"` -- Deployment 2: `Deploy-Accelerator -inputs "~/config/inputs2.json" -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. @@ -114,7 +134,7 @@ Yes, you can skip the approval of the Terraform plan by using the `-autoApprove` For example: ```powershell -Deploy-Accelerator -inputs "~/config/inputs.json" -autoApprove +Deploy-Accelerator -inputs "~/config/inputs.json" -output "./deployment1" -autoApprove ``` ## Questions about adding more subscriptions post initial deployment diff --git a/docs/content/accelerator/userguide/1_prerequisites/_index.md b/docs/content/accelerator/userguide/1_prerequisites/_index.md index 62a0243..3b47bab 100644 --- a/docs/content/accelerator/userguide/1_prerequisites/_index.md +++ b/docs/content/accelerator/userguide/1_prerequisites/_index.md @@ -6,18 +6,29 @@ weight: 5 Phase 1 of the accelerator is to setup your prerequisites. Follow the steps below to do that. -## 1 - Tools +## 1 - Tools and Internet Access You'll need to install the following tools before getting started. -- PowerShell 7.4 (or newer): [Follow the instructions for your operating system](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell) -- Azure CLI 2.55.0 (or newer): [Follow the instructions for your operating system](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) -- Git (any supported version): [Follow the instructions for your opersating system](https://git-scm.com/downloads). +* PowerShell 7.4 (or newer): [Follow the instructions for your operating system](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell) +* Azure CLI 2.55.0 (or newer): [Follow the instructions for your operating system](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) +* Git (any supported version): [Follow the instructions for your opersating system](https://git-scm.com/downloads). {{< hint type=note >}} In all cases, ensure that the tools are available from a PowerShell core (pwsh) terminal. You may need to add them to your environment path if they are not. {{< /hint >}} +You will also need open access to the internet to download tools, terraform providers and connect to Azure and your Version Control System. + +We **DO NOT** explicitly support: + +* Running behind a corporate proxy +* Running in Azure Cloud Shell + +{{< hint type=tip >}} +If your local machine is behind a corporate proxy, consider spinning up a temporary VM in Azure to run the Accelerator from, then tear it down when you are done. +{{< /hint >}} + ## 2 - Azure Subscriptions and Permissions Follow the instructions in the [Platform Subscriptions and Permissions]({{< relref "platform-subscriptions" >}}) section.