diff --git a/docs/config.toml b/docs/config.toml index 26200bce7..28a9444e5 100644 --- a/docs/config.toml +++ b/docs/config.toml @@ -26,10 +26,6 @@ enableRobotsTXT = true tag = "tags" [params] - - # Include custom JS files - customJS = ["js/clarity.js"] - # (Optional, default 6) Set how many table of contents levels to be showed on page. # Use false to hide ToC, note that 0 will default to 6 (https://gohugo.io/functions/default/) # You can also specify this parameter per page in front matter. diff --git a/docs/content/contributing/website/_index.md b/docs/content/contributing/website/_index.md index 7a399d21b..c99253f28 100644 --- a/docs/content/contributing/website/_index.md +++ b/docs/content/contributing/website/_index.md @@ -33,7 +33,7 @@ When in VS Code you should be able to open a terminal and run the below commands ```text cd docs -hugo server -D +hugo server -D // you can add "--poll 700ms", if file changes are not detected ``` ### Software/Applications diff --git a/docs/content/faq/_index.md b/docs/content/faq/_index.md index 1e5e8f53e..9b600b38e 100644 --- a/docs/content/faq/_index.md +++ b/docs/content/faq/_index.md @@ -401,29 +401,7 @@ The high level steps are: ### How can I use Bicep modules through the Public Registry? -Use the [Bicep Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-bicep) to author your Bicep template and explore modules published in the Bicep Public Registry. For more details, see the the below example steps. - -{{< hint type=note >}} -The Bicep VSCode extension is reading metadata through [this JSON file](https://live-data.bicep.azure.com/module-index). All modules are added to this file, as part of the publication process. -{{< /hint >}} - -1. When authoring a new Bicep file, use the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-bicep) to explore the modules published in the Bicep Public Registry. -Select br/public: - -2. Expanding on this you can see the AVM modules that are published. -Select module from the Public Bicep Registry - -3. Selecting the module expands on the current available versions. -Choose from the available versions - -4. Setting required properties exposes what is required on the module. -Select required-properties - -5. Hovering over the `myTestModule` name exposes the module's documentation URL. -Hover over the module name - -6. Clicking on the link opens up the Bicep Registry Repo for the AVM module's source code, where you can find the documentation detailing all the module's functionality, input parameters and outputs, while providing various examples. -See the module's documentation online +Please see the Bicep Quickstart guide [here](/Azure-Verified-Modules/usage/quickstart/bicep/). --- diff --git a/docs/content/usage/quickstart/_index.md b/docs/content/usage/quickstart/_index.md index 8a11c7109..ee54a6b6d 100644 --- a/docs/content/usage/quickstart/_index.md +++ b/docs/content/usage/quickstart/_index.md @@ -6,17 +6,16 @@ geekdocAnchor: true geekdocCollapseSection: true --- -- this section describes the simplest way to get started with the project -- a few sentences about why I should use AVM (and/or the kv module in this example) -- am I "safe" to use the default values? -- where can I find some examples? how can I find out all the features the kv module has to offer? -- deploying a key vault the simplest way possible -- prerequisites (VS code, packages, PS modules, etc.) -- use story telling / screenshots from [FAQ](/Azure-Verified-Modules/faq/#how-can-i-use-bicep-modules-through-the-public-registry) - - how do I explore what modules are there? - - what are the built-in features of the key-vault module - - UDTs - - intellisense - - explore the source of the kv module without leaving VS code - - how can I see the readme of the kv module from vs code - - what if there's a missing feature? --> file a module issue +This quickstart section describes the simplest way to get started with the project by providing step-by-step instructions and essential information, allowing you to leverage the benefits of AVM with minimal effort. It guides you through the initial setup, including the necessary tools and configurations, to help you quickly deploy and manage your Azure resources and solutions using Azure Verified Modules (AVM). + +## Why should I use Azure Verified Modules? + +Using AVM ensures that your infrastructure-as-code deployments adhere to Microsoft's best practices and guidelines, providing a consistent and reliable foundation for your cloud solutions. By leveraging AVM, you can accelerate your development process, reduce the risk of misconfigurations, and enhance the security and compliance of your applications. The AVM Key Vault resource module, used as an example through this chapter, simplifies the deployment and management of Azure Key Vaults, ensuring secure storage and access to your secrets, keys, and certificates. + +## Am I "safe" to use the default values? + +Using the default values provided by AVM is generally safe as they are configured to follow best practices and ensure a secure and reliable setup. However, it is important to review these values to ensure they meet your specific requirements and compliance needs. Customizing the default values may be necessary to align with your organization's policies and the specific needs of your project. + +## Where can I find some examples? How can I find out all the features a given module has to offer? + +You can find examples and detailed documentation for the each AVM module in their respective code repository's `README.MD` file that details all the features, input parameters, and outputs. The module's documentation also provides comprehensive usage examples, covering various scenarios and configurations. Additionally, you can explore the module's source code repository. This information will help you understand the full capabilities of the module and how to effectively integrate it into your projects. diff --git a/docs/content/usage/quickstart/bicep/_index.md b/docs/content/usage/quickstart/bicep/_index.md index bded60c3a..19e8cc9c1 100644 --- a/docs/content/usage/quickstart/bicep/_index.md +++ b/docs/content/usage/quickstart/bicep/_index.md @@ -3,6 +3,393 @@ title: Bicep Quickstart geekdocNav: true geekdocAlign: left geekdocAnchor: true +geekdocToC: 2 --- -TBD +{{< toc >}} + +## Introduction + +This guide shows how to deploy an Azure Verified Module. By leveraging AVM modules, you can rapidly deploy and manage Azure infrastructure without having to write extensive code from scratch. + +In this guide, we'll deploy deploy a [Key Vault](https://azure.microsoft.com/en-us/products/key-vault/) resource and a Personal Access Token as a secret. + +This article is written for a typical "infra-dev" user (cloud infrastructure professional) who is new to Azure Verified Modules and wants to learn how to deploy a module the easiest possible way using AVM. The user has a basic understanding of Azure and Bicep templates. + +If you first need to learn Bicep, you can find a [Bicep Quickstart](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/quickstart-create-bicep-use-modules) on the Microsoft Learn platform, study the [detailed documentation](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/file), or leverage the [Fundamentals of Bicep](https://learn.microsoft.com/en-us/training/paths/fundamentals-bicep/) learning path. + +## Prerequisites + +For the best experience, you will need: + +- [Visual Studio Code (VS Code)](https://code.visualstudio.com/download) to develop your solution. +- [Bicep Visual Studio Code Extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-bicep) to author your Bicep template and explore modules published in the [registry](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/modules#public-module-registry). +- One of the following command line tools: + - [PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell) AND [Azure PowerShell](https://learn.microsoft.com/en-us/powershell/azure/install-azure-powershell) + - [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) to deploy your solution. +- [Bicep CLI](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install#install-manually) +- [Azure Subscription](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/considerations/fundamental-concepts) to deploy your Bicep template. + +Make sure you have these tools set up before proceeding. + +## Module Discovery + +### Find your module + +With our scenario in mind, we need to deploy a Key Vault resource and some of its child resources - e.g., a secret. Let's find the AVM module that will help us achieve this. + +There are two primary ways for locating published Bicep Azure Verified Modules: + +- Option 1 (preferred): Using IntelliSense in the Bicep extension of Visual Studio Code, and +- Option 2: browsing the[AVM Bicep module index](https://aka.ms/avm/moduleindex/bicep). + +#### Option 1: Use the Bicep Extension in VS Code + + + +1. In VS Code, create a new file with called `main.bicep`. +1. Start typing `module`, then give your module a symbolic name, such as `myModule`. +1. Use Intellisense to select `br/public`. +1. The list of all AVM modules published in the Bicep Public Registry will show up. Use this to explore the published modules. + {{< hint type=note >}}The Bicep VSCode extension is reading metadata through [this JSON file](https://live-data.bicep.azure.com/module-index). All modules are added to this file, as part of the publication process. This lists all the modules marked as Published or Orphaned on the [AVM Bicep module index pages](https://aka.ms/AVM/ModuleIndex/Bicep).{{< /hint >}} +1. Select the module you want to use and the version you want to deploy. Note how you can type full or partial module names to filter the list. +1. Right click on the module's path and select `Go to definition` or hit `F12` to see the module's source code. You can toggle between the Bicep and the JSON view. +1. Hover over the module's symbolic name to see the module's documentation URL. Clicking on it leads you to the module's GitHub folder in the [bicep-registry-modules (BRM)](https://aka.ms/BRM) repository, where its source code and documentation are stored as shows [below](#module-details-and-examples). + +#### Option 2: Use the AVM Bicep Module Index + + + +Searching the Azure Verified Module indexes is the most complete way to discover published as well as planned (proposed) modules. As shown in the video above, use the following steps to locate a specific module on the AVM website: + +- Use your web browser to open the AVM website at [https://aka.ms/avm](https://aka.ms/avm). +- Expand the **Module Indexes** menu item and select the **Bicep** sub-menu item. +- Select the menu item for the module type you are searching for: [Resource](/Azure-Verified-Modules/indexes/bicep/bicep-resource-modules/), [Pattern](/Azure-Verified-Modules/indexes/bicep/bicep-pattern-modules/), or [Utility](/Azure-Verified-Modules/indexes/bicep/bicep-utility-modules/). + {{< hint >}}Since the Key Vault module used as an example in this guide is published as an AVM resource module, it can be found under the [resource modules](/Azure-Verified-Modules/indexes/bicep/bicep-resource-modules/) section in the AVM Bicep module index.{{< /hint >}} +- A detailed description of each module classifications types can be found under the related section [here](https://azure.github.io/Azure-Verified-Modules/specs/shared/module-classifications/). +- Select the **Published modules** link from the table of contents at the top of the page. +- Use the in-page search feature of your browser. In most Windows browsers you can access it using the `CTRL` + `F` keyboard shortcut. +- Enter a **search term** to find the module you are looking for - e.g., Key Vault. +- **Move through the search results until you locate the desired module.** If you are unable to find a published module, return to the table of contents and expand the **All modules** link to search both published and proposed modules - i.e., modules that are planned, likely in development but not published yet. +- After finding the desired module, click on the **module's name**. This link will lead you to the module's folder in the [bicep-registry-modules (BRM)](https://aka.ms/BRM) repository, where the module's [source code](https://github.com/Azure/bicep-registry-modules/tree/main/avm/res/key-vault/vault) and [documentation](https://github.com/Azure/bicep-registry-modules/blob/main/avm/res/key-vault/vault/README.md) can be found, including [usage examples](https://github.com/Azure/bicep-registry-modules/blob/main/avm/res/key-vault/vault/README.md#Usage-examples). + +### Module details and examples + + + +In the module's documentation, you can find detailed information about the module's functionality, components, input parameters, outputs and more. The documentation also provides comprehensive usage examples, covering various scenarios and configurations. + +Explore the Key Vault module’s documentation for usage examples and to understand its functionality, input parameters, and outputs. + +- Note the mandatory and optional parameters in the [**Parameters**](https://github.com/Azure/bicep-registry-modules/blob/main/avm/res/key-vault/vault/README.md#Parameters) section. +- Review [**Usage examples**](https://github.com/Azure/bicep-registry-modules/blob/main/avm/res/key-vault/vault/README.md#Usage-examples). AVM modules are developed including multiple tests. They can be found under the **`tests`** folder and are used as the basis of the usage examples, therefore they are always up-to-date and deployable. + +In our example, we want to deploy a secret in a new Key Vault instance without needing to provide other parameters. AVM not only provides these, but it also does it with security and reliability being core principles, as the default settings apply the recommendations of the [Well Architected Framework](/Azure-Verified-Modules/faq/#what-does-avm-mean-by-waf-aligned) where possible and appropriate. + +Note how [Example 2](https://github.com/Azure/bicep-registry-modules/tree/main/avm/res/key-vault/vault#example-2-using-only-defaults) seems to do pretty much what we want to achieve. + +## Develop your new template using AVM + +In this section, you will develop a Bicep template that references the AVM Key Vault module and its child resources and features, such as a secret and role based access control configuration to grant permissions to a user. + +1. Start VSCode (make sure the Bicep extension is installed) and open a folder in which you want to work. +2. Create a `main.bicep` and a `dev.bicepparam` file, which will hold parameters for your Key Vault deployment. + +The scope for the deployment of the Key Vault instance will be a resource group. The Bicep extension offers code-completion, which makes it easy to find and use the Azure Verified Module. It will e.g. provide the required properties for a module. You can start typing, let the magic do its thing and end up with (we've added comments here, to describe the different names): + + +```bicep +module keyVault 'br/public:avm/res/key-vault/vault:0.11.0' = { + name: // the name of the module's deployment + params: { + name: '' // the name of the Key Vault instance - length and character limits apply + } +} +``` + + {{< hint >}} For Azure Key Vaults, the name must be globally unique. When you deploy the Key Vault, ensure you select a name that is alphanumeric, twenty-four characters or less, and unique enough to ensure no one else has used the name for their Key Vault. If the name has been used previously, you will get an error. {{< /hint >}} + +After setting the values for the required properties, the module can be [deployed](#deploy-your-solution). This minimal configuration automatically applies the security and reliability recommendations of the [Well Architected Framework](/Azure-Verified-Modules/faq/#what-does-avm-mean-by-waf-aligned) where possible and appropriate. These settings can be overridden if needed. + +{{< hint type=tip title="Bicep-specific configuration" >}} + +We suggest to create a [`bicepconfig.json`](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-config) file, and enable *use-recent-module-versions*, which warns you to use the latest available version of the AVM module. + +```json +// This is a Bicep configuration file. It can be used to control how Bicep operates and to customize +// validation settings for the Bicep linter. The linter uses these settings when evaluating your +// Bicep files for best practices. For further information, please refer to the official documentation at: +// https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-config +{ + "analyzers": { + "core": { + "rules": { + "use-recent-module-versions": { + "level": "warning", + "message": "The module version is outdated. Please consider updating to the latest version." + } + } + } + } +} +``` + +{{< /hint >}} + +### Define the Key Vault instance + +In this scenario, and every other real-world setup, there is a bit more that we want to configure. You can use the documentation URL (by hovering over the module) to see the module’s documentation online for other supported parameters. The ```main.bicep``` might look like this: + + +```bicep +// the scope, the deployment deploys resources to +targetScope = 'resourceGroup' + +// parameters and default values +param keyVaultName string +param resourceLocation string = resourceGroup().location + +@description('Disable for development deployments.') +param enablePurgeProtection bool = true + +// the resources to deploy +module keyVault 'br/public:avm/res/key-vault/vault:0.11.0' = { + name: 'key-vault-deployment' + params: { + name: keyVaultName + location: resourceLocation + enablePurgeProtection: enablePurgeProtection + // more properties are not needed, as AVM provides default values + } +} +``` + +The code I added makes the module usa is for passing in the Key Vault name and optionally change the location and purge protection. You might not want to enable the latter in a non-production environment, as it makes it harder to delete and recreate resources. + +The ```dev.bicepparam``` file is optional and sets parameter values for a certain environment. You can instead pass these parameters at the time of deployment (using PowerShell or Azure CLI). + + +```bicep +using 'main.bicep' + +// environment specific values +param keyVaultName = '' +param enablePurgeProtection = false +``` + +### Create a secret and set permissions + +Now, let's add a secret to the Key Vault instance and grant permissions to a user to work with the secret. Sample role assignments can be found in [Example 3: Using large parameter set](https://github.com/Azure/bicep-registry-modules/tree/main/avm/res/key-vault/vault#example-3-using-large-parameter-set). See [Parameter: roleAssignments](https://github.com/Azure/bicep-registry-modules/tree/main/avm/res/key-vault/vault#parameter-roleassignments) for a list of pre-defined roles, that you can reference by name instead of a GUID. Again, this is a huge advantage of using AVM, as the code is easy to read and increases the maintainability. + +You can also make use of [User-defined data types](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/user-defined-data-types) and simplify the parameterization of the modules instead of guessing or looking up parameters. Therefore, first import UDTs from the Key Vault and common types module and leverage the UDTs in your Bicep and parameter files. + +For a role assignment, the principal ID is needed, that will be granted a role (specified by its name) on the resource. Your own ID can be found out with `az ad signed-in-user show --query id`. + + +```bicep +// the scope, the deployment deploys resources to +targetScope = 'resourceGroup' + +// parameters and default values +param keyVaultName string +param resourceLocation string = resourceGroup().location + +@description('Enabled by default. Disable for development deployments') +param enablePurgeProtection bool = true + +import { secretType } from 'br/public:avm/res/key-vault/vault:0.11.0' +// adding secrets is optional in the Key Vault module +param secrets secretType[]? + +import { roleAssignmentType } from 'br/public:avm/utl/types/avm-common-types:0.4.0' +// the role assignments are optional in the Key Vault module +param roleAssignments roleAssignmentType[]? + +// the resources to deploy +module keyVault 'br/public:avm/res/key-vault/vault:0.11.0' = { + name: 'key-vault-deployment' + params: { + name: keyVaultName + location: resourceLocation + enablePurgeProtection: enablePurgeProtection + secrets: secrets + roleAssignments: roleAssignments + } +} +``` + +Notice the secrets parameter, which has a UDT ([User-defined data type](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/user-defined-data-types)) that is part of the Key Vault module and enables code completion for easy usage. No need to look up what parameters a secret might have. Just start typing and tab-complete what you need from the parameters offered by the Bicep extension in combination with Azure Verified Modules. + +And the bicep parameter file now looks like this: + + +```bicep +// reference to the Bicep file to set the context +using 'main.bicep' + +// environment specific values +param keyVaultName = '' +param enablePurgeProtection = false + +param secrets = [ + { + // set required parameters + name: 'PAT' + value: '' + } +] + +param roleAssignments = [ + { + principalId: '' + // using the name of the role instead of looking up the Guid (which can also be used) + roleDefinitionIdOrName: 'Key Vault Crypto Officer' + } +] +``` + +{{< hint >}} +The display names for roleDefinitionIdOrName can be acquired the following two ways: + +- From the [parameters section](https://github.com/Azure/bicep-registry-modules/blob/avm/res/key-vault/vault/0.11.0/avm/res/key-vault/vault/README.md#parameter-roleassignments) module's documentation. +- From the `builtInRoleNames` variable in the module's source code. To get there, hit `F12` while the cursor is set on the module path starting with `br/public:`. +{{< /hint >}} + +### Boost your development with VS Code IntelliSense + +Leverage the IntelliSense feature in VS Code to speed up your development process. IntelliSense provides code completion, possible parameter values and structure. It helps you write code more efficiently by providing context-aware suggestions as you type. + +Here's how quickly you can deliver the solution we detailed in this section: + + + +## Deploy your solution + +Now that your template and parameter file is ready, you can deploy your solution to Azure. You can use PowerShell or Azure CLI to deploy your solution. + +{{< tabs "deploy" >}} + {{< tab "PowerShell" >}} + + ```powershell + # Log in to Azure + Connect-AzAccount + + # Select your subscription + Set-AzContext -SubscriptionId '' + + # Deploy a resource group + New-AzResourceGroup -Name 'avm-quickstart-rg' -Location 'germanywestcentral' + + # Parameterize your deployment + $inputObject = @{ + DeploymentName = 'avm-quickstart-deployment-{0}' -f (-join (Get-Date -Format 'yyyyMMddTHHMMssffffZ')[0..63]) + ResourceGroupName = 'avm-quickstart-rg' + TemplateParameterFile = 'dev.bicepparam' + TemplateFile = 'main.bicep' + } + + # Invoke your deployment + New-AzResourceGroupDeployment @inputObject + ``` + + {{< /tab >}} + {{< tab "AZ CLI" >}} + + ```bash + # Log in to Azure + az login + + # Select your subscription + az account set --subscription '' + + # Deploy a resource group + az group create --name 'avm-quickstart-rg' --location 'germanywestcentral' + + # Parameterize your deployment + $inputObject = @( + '--name', 'avm-quickstart-deployment{0}' -f (-join (Get-Date -Format 'yyyyMMddTHHMMssffffZ')[0..63])), + '--resource-group', 'avm-quickstart-rg', + '--parameters', 'dev.bicepparam', + '--template-file', 'main.bicep', + ) + + # Invoke your deployment + az deployment group create @inputObject + ``` + + {{< /tab >}} +{{< /tabs >}} + +Use the Azure portal, Azure PowerShell or the Azure CLI to verify that the Key Vault instance has been successfully created with the correct configuration, along the secret. + +## Clean up your environment + +When you are ready, you can remove the infrastructure deployed in this example. The following commands will remove all resources created by your deployment: + + + +{{< tabs "cleanup" >}} + {{< tab "PowerShell" >}} + + ```powershell + # Delete the key + Remove-AzKeyVaultKey -VaultName "" -Name "PAT" + + # Purge the key + Remove-AzKeyVaultKey -VaultName "" -Name "PAT" -InRemovedState + + # Delete the Key Vault + Remove-AzKeyVault -VaultName "" + + # Purge the Key Vault + Remove-AzKeyVault -VaultName "" -Location "germanywestcentral" -InRemovedState + + # Delete the resource group + Remove-AzResourceGroup -Name "avm-quickstart-rg" -Force + ``` + + {{< /tab >}} + {{< tab "AZ CLI" >}} + + ```bash + # Delete the key + az keyvault key delete --vault-name '' --name PAT + + # Purge the key + az keyvault key purge --vault-name '' --name PAT + + # Delete the Key Vault + az keyvault delete --name '' --resource-group avm-quickstart-rg + + # Purge the Key Vault + az keyvault purge --name '' + + # Delete the resource group + az group delete --name avm-quickstart-rg --yes --no-wait + ``` + + {{< /tab >}} +{{< /tabs >}} + +Congratulations, you have successfully leveraged an AVM Bicep module to deploy resources in Azure! + +{{< hint type=tip >}} +We welcome your contributions and feedback to help us improve the AVM modules and the overall experience for the community. +{{< /hint >}} diff --git a/docs/content/usage/quickstart/terraform/_index.md b/docs/content/usage/quickstart/terraform/_index.md index e8d3bad21..c0a494f29 100644 --- a/docs/content/usage/quickstart/terraform/_index.md +++ b/docs/content/usage/quickstart/terraform/_index.md @@ -2,7 +2,216 @@ title: Terraform Quickstart geekdocNav: true geekdocAlign: left +geekdocToC: 2 geekdocAnchor: true --- -TBD +{{< toc >}} + +## Introduction + +This guide provides instructions for using an Azure Verified Module (AVM) as part of your Terraform workflow. By leveraging AVM modules, you can rapidly deploy and manage Azure infrastructure without having to write extensive code from scratch. + +In this guide, we'll deploy a [Key Vault](https://azure.microsoft.com/en-us/products/key-vault/) resource and generate and store a key. + +This article is written for a typical "infra-dev" user (cloud infrastructure professional) who is new to Azure Verified Modules and wants to learn how to deploy a module the easiest possible way using AVM. The user has a basic understanding of Azure and Terraform. + +If you first need to learn Terraform, you can start by trying a [tutorial](https://developer.hashicorp.com/terraform/tutorials/azure-get-started) on the HashiCorp website or studying the [detailed documentation.](https://developer.hashicorp.com/terraform/docs) + +## Prerequisites + +For the best experience, you will need: + +- [Visual Studio Code (VS Code)](https://code.visualstudio.com/docs/setup/setup-overview) to develop your solution. +- [Terraform CLI](https://developer.hashicorp.com/terraform/install) to deploy your Terraform modules. Make sure you have a recent version installed. +- [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) to authenticate to Azure. +- [Azure Subscription](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/considerations/fundamental-concepts) to deploy your resources. + +Before you begin, ensure you have the these tools installed in your development environment. + +## Module Discovery + +### Find your module + +With our scenario in mind, we need to deploy a Key Vault resource and some of its child resources - e.g., a key. Let's find the AVM module that will help us achieve this. + +There are two primary ways for locating published Terraform Azure Verified Modules: + +- Searching the [official Terraform Registry](https://registry.terraform.io/), and +- Browsing the[AVM Terraform module index](https://aka.ms/avm/moduleindex/terraform). + +#### Use the Terraform Registry + + + +The simplest way to discover published AVM Terraform modules is to search the Terraform Registry. As shown in the video above, use the following steps to locate a specific module. + +- Use your web browser to go to the [HashiCorp Terraform Registry](https://registry.terraform.io/) +- In the search bar at the top of the screen type **avm**. Optionally, append additional search terms to narrow the search results. (e.g., **avm keyvault** for AVM modules with keyvault in the name.) +- Select **see all** to display the full list of published modules matching your search criteria. +- Find the module you wish to use and select it from the search results. + +{{< hint >}} It is possible to discover other unofficial modules with **avm** in the name using this search method. Look for the **`Partner`** tag in the module title as a way to determine if the module is part of the official set. {{< /hint >}} + +#### Use the AVM Terraform Module Index + + + +Searching the Azure Verified Module indexes is the most complete way to discover published as well as planned modules - shown as proposed. As presented in the video above, use the following steps to locate a specific module on the AVM website: + +- Use your web browser to open the AVM website at [https://aka.ms/avm](https://aka.ms/avm). +- Expand the **Module Indexes** menu item and select the **Terraform** sub-menu item. +- Select the menu item for the module type you are searching for: [Resource](/Azure-Verified-Modules/indexes/terraform/tf-resource-modules/), [Pattern](/Azure-Verified-Modules/indexes/terraform/tf-pattern-modules/), or [Utility](/Azure-Verified-Modules/indexes/terraform/tf-utility-modules/). + {{< hint >}}Since the Key Vault module used as an example in this guide is published as an AVM resource module, it can be found under the [resource modules](/Azure-Verified-Modules/indexes/terraform/tf-resource-modules/) section in the AVM Terraform module index.{{< /hint >}} +- A detailed description of each module classification type can be found under the related section [here](/Azure-Verified-Modules/specs/shared/module-classifications/). +- Select the **Published modules** link from the table of contents at the top of the page. +- Use the in-page search feature of your browser (in most Windows browsers you can access it using the `CTRL` + `F` keyboard shortcut). +- Enter a **search term** to find the module you are looking for - e.g., Key Vault. +- **Move through the search results until you locate the desired module.** If you are unable to find a published module, return to the table of contents and expand the **All modules** link to search both published and proposed modules - i.e., modules that are planned, likely in development but not published yet. +- After finding the desired module, click on the **module's name**. This link will lead you to the official Hashicorp Terraform Registry page for the module where you can find the module's documentation and examples. + +### Module details and examples + +Once you have identified the AVM module in the Terraform Registry you can find detailed information about the module’s functionality, components, input parameters, outputs and more. The documentation also provides comprehensive usage examples, covering various scenarios and configurations. + +Explore the Key Vault module’s documentation and usage examples to understand its functionality, input variables, and outputs. + +- Note the **Examples** drop-down list and explore each example +- Review the **Readme** tab to see module provider minimums, a list of resources and data sources used by the module, a nicely formatted version of the inputs and outputs, and a reference to any submodules that may be called. +- Explore the [**Inputs**](https://registry.terraform.io/modules/Azure/avm-res-keyvault-vault/azurerm/latest?tab=inputs) tab and observe how each input has a detailed description and a type definition for you to use when adding input values to your module configuration. +- Explore the [**Outputs**](https://registry.terraform.io/modules/Azure/avm-res-keyvault-vault/azurerm/latest?tab=outputs) tab and review each of the outputs that are exported by the AVM module for use by other modules in your deployment. +- Finally, review the [**Resources**](https://registry.terraform.io/modules/Azure/avm-res-keyvault-vault/azurerm/latest?tab=resources) tab to get a better understanding of the resources defined in the module. + +In our example, we want to deploy a secret in a new Key Vault instance without needing to provide other parameters. The AVM Key Vault resource module provides these capabilities, and does so with security and reliability being core principles. The default settings of the module also apply the recommendations of the Well Architected Framework where possible and appropriate. + +Note how the [**create-key**](https://registry.terraform.io/modules/Azure/avm-res-keyvault-vault/azurerm/latest/examples/create-key) example seems to do what we want to achieve. + +## Create your new solution using AVM + +Now that you've located the module details, you can use the module content from the Terraform Registry to accelerate your development efforts in one of two ways: + +1. Option 1: [Create a solution using AVM module examples](#option-1-create-a-solution-using-avm-module-examples): duplicate a module example and edit it for your needs. This is useful if you're starting without any existing infrastructure and need to create supporting resources like resource groups as part of your deployment. +1. Option 2: [Create a solution by changing the AVM module input values](#option-2-create-a-solution-by-changing-the-avm-module-input-values): add the AVM module to an existing solution that already includes other resources. This method requires some knowledge of the resource(s) being deployed so that you can make choices about optional features configured within the module. + +Each deployment method includes a section below so that you can choose the method which best fits your needs. + +{{< hint >}} For Azure Key Vaults, the name must be globally unique. When you deploy the Key Vault, ensure you select a name that is alphanumeric, twenty-four characters or less, and unique enough to ensure no one else has used the name for their Key Vault. If the name has been used previously, you will get an error. {{< /hint >}} + +### Option 1: Create a solution using AVM module examples + + + +Use the following steps as a template for how to leverage examples for bootstrapping your new module. We will use the Key Vault resource module as an example, but in practice you may use whichever module applies to your scenario. + +- Locate and select the **Examples** drop down menu in the middle of the module page. +- From the drop-down list select an example whose name most closely aligns with your scenario - e.g., **create-key**. +- When the example page loads, read the example description to determine if this is the desired example. If it is not, return to the module main page, and select a different example until you are satisfied that the example covers the scenario you are trying to deploy. If you are unable to find a suitable example, leverage the last two steps in the [option 2](#option-2-create-a-solution-by-changing-the-avm-module-input-values) instructions to modify the inputs of the selected example to match your requirements. +- Scroll to the code block for the example and select the **Copy** button on the top right of the block to copy the content to the clipboard. + + + +- In your IDE - Visual Studio Code in our example - create the **main.tf** file for your new solution. +- **Paste** the content from the clipboard into **main.tf**. +- AVM examples frequently use naming and/or region selection Terraform modules to generate deployment region and/or naming values as well as any default values for required fields. If you want to use a specific region or other custom resource values, remove the existing region and naming module calls and replace example input values with the new desired custom input values. +- Once supporting resources such as resource groups have been modified, locate the module call for the AVM module - i.e., **`module "keyvault"`**. +- AVM module examples use dot notation for a relative reference that is useful during module testing. However, you will need to replace the relative reference with a source reference that points to the Terraform Registry source location. In most cases, this source reference has been left as a comment in the module example to simplify replacing the existing source dot reference. Perform the following two actions to update the source: + - Delete the existing source definition that uses a dot reference - i.e., **`source = "../../"`**. + - Uncomment the Terraform Registry source reference by deleting the **#** sign at the start of the commented source line - i.e., **`source = "Azure/avm-res-keyvault-vault/azurerm"`**. +- AVM module examples use a variable to enable or disable the telemetry collection. Update the **`enable_telemetry`** input value to **true** or **false**. -e.g. **`enable_telemetry = true`** +- **Save** your `main.tf` file changes and then proceed to the guide section for running your module. + +### Option 2: Create a solution by changing the AVM module input values + + + +Use the following steps as a guide for a custom implementation of an AVM Module. This instruction path assumes that you have an existing Terraform module file that you want to add the AVM module to. + +- Locate the **Provision Instructions** box on the right side of the module's registry page in your web browser. +- Select the module template code from the code block and **Copy** it onto the clipboard. +- Switch to your IDE and **Paste** the contents of the clipboard into your custom module's .tf file - **`main.tf`** in our example. +- Return to the module's registry page in the browser and select the **Inputs** tab. +- Review each input, and add the inputs with the desired target value to the solution's code - i.e., **`name = "custom_name"`**. +- Once you are satisfied that you've include all required inputs and any optional inputs, **Save** your file and continue to the next section. + +## Deploy your solution + + + +Once module development is complete you can proceed to the deployment stage. The following steps represent a basic Terraform workflow: + +- Open the command line and login to Azure using the Azure cli + + ```terraform + az login + ``` + +- If your account has access to multiple tenants you may need to modify the command to **`az login --tenant `** where **``** is the guid for the target tenant. +- After logging in, select the **target subscription** from the list of subscriptions that you have access to. +- Change the path to the directory where your completed terraform solution files reside. + + {{< hint >}} Some modules depend on the AzureRM 4.0 provider which mandates that a subscription id is configured for the provider. If you receive an error indicating that **`subscription_id is a required provider property`** then you will need to set a subscription id value for the provider. For unix based systems (linux or mac) you can configure this by running **`export ARM_SUBSCRIPTION_ID=`**. On Microsoft Windows, you can perform the same operation by running **`set ARM_SUBSCRIPTION_ID=""`** from the Windows command prompt or by running **`$env:ARM_SUBSCRIPTION_ID=""`** from a powershell prompt. Replace **"** with your Azure subscription's unique id value in each command. {{< /hint >}} + +- Initialize your Terraform project. This command downloads the necessary modules and sets up the working directory. + + ```terraform + terraform init + ``` + +- Before applying the configuration, it is good practice to validate it to ensure there are no syntax errors. + + ```terraform + terraform validate + ``` + +- Create a deployment plan. This step shows what actions Terraform will take to reach the desired state defined in your configuration. + + ```terraform + terraform plan + ``` + +- Review the plan to ensure that only the desired actions are in the plan output. +- Apply the configuration and create the resources defined in your configuration file. This command will prompt you to confirm the deployment prior to making changes. Type **yes** to apply the module's infrastructure. + + ```terraform + terraform apply + ``` + + {{< hint >}}If you are confident in your changes you can add the `-auto-approve` switch to bypass manual approval: `terraform apply -auto-approve`{{< /hint >}} + +- Once the deployment completes, validate that the infrastructure is configured as desired. + + {{< hint >}}A local `terraform.tfstate` file and a state backup file have been created during the deployment. The use of local state is acceptable for small temporary configurations, but production or long-lived installations should use a remote state configuration where possible. Configuring remote state is out of scope for this guide, but you can find details on using an Azure storage account for this purpose in the [Microsoft Learn documentation](https://learn.microsoft.com/en-us/azure/developer/terraform/store-state-in-azure-storage?tabs=azure-cli).{{< /hint >}} + +## Clean up your environment + +When you are ready, you can remove the infrastructure deployed in this example. The following command will remove all resources created by your deployment: + +```terraform +terraform destroy +``` + +{{< hint >}}Most Key Vault deployment examples activate soft-delete functionality as a best practice. The terraform destroy command will remove the Key Vault resource but does not purge a soft-deleted vault. You may encounter errors if you attempt to re-depoy a Key Vault with the same name during the soft-delete retention window.{{< /hint >}} + +Congratulations, you have successfully leveraged Terraform and AVM to deploy resources in Azure! + +{{< hint type=tip >}} +We welcome your contributions and feedback to help us improve the AVM modules and the overall experience for the community. +{{< /hint >}} diff --git a/docs/data/menu/main.yaml b/docs/data/menu/main.yaml index 486c6cf32..c265926a1 100644 --- a/docs/data/menu/main.yaml +++ b/docs/data/menu/main.yaml @@ -26,16 +26,16 @@ main: ref: "indexes/terraform/tf-pattern-modules" - name: "Utility Modules" ref: "indexes/terraform/tf-utility-modules" - # - name: "Usage Guide" - # ref: "usage" - # sub: - # - name: "Quickstart" - # ref: "usage/quickstart" - # sub: - # - name: "Bicep" - # ref: "usage/quickstart/bicep" - # - name: "Terraform" - # ref: "usage/quickstart/terraform" + - name: "Usage Guide" + ref: "usage" + sub: + - name: "Quickstart" + ref: "usage/quickstart" + sub: + - name: "Bicep" + ref: "usage/quickstart/bicep" + - name: "Terraform" + ref: "usage/quickstart/terraform" # - name: "Deployment options" # ref: "usage/deployment-options" # - name: "Usage Scenarios" diff --git a/docs/layouts/partials/page-header.html b/docs/layouts/partials/page-header.html new file mode 100644 index 000000000..56352a042 --- /dev/null +++ b/docs/layouts/partials/page-header.html @@ -0,0 +1,69 @@ +{{ $geekdocRepo := default (default false .Site.Params.geekdocRepo) .Page.Params.geekdocRepo }} +{{ $geekdocEditPath := default (default false .Site.Params.geekdocEditPath) .Page.Params.geekdocEditPath }} +{{ if .File }} + {{ $.Scratch.Set "geekdocFilePath" (default (strings.TrimPrefix hugo.WorkingDir .File.Filename) .Page.Params.geekdocFilePath) }} +{{ else }} + {{ $.Scratch.Set "geekdocFilePath" false }} +{{ end }} + +{{ define "breadcrumb" }} + {{ $parent := .page.Parent }} + {{ if $parent }} + {{ $name := (partial "utils/title" $parent) }} + {{ $position := (sub .position 1) }} + {{ $value := (printf "
  • %s
  • /
    • %s" $parent.RelPermalink $parent.RelPermalink $name $position .value) }} + {{ template "breadcrumb" dict "page" $parent "value" $value "position" $position }} + {{ else }} + {{ .value | safeHTML }} + {{ end }} +{{ end }} + +{{ $showBreadcrumb := (and (default true .Page.Params.geekdocBreadcrumb) (default true .Site.Params.geekdocBreadcrumb)) }} +{{ $showEdit := (and ($.Scratch.Get "geekdocFilePath") $geekdocRepo $geekdocEditPath) }} +
    + {{ if $showBreadcrumb }} +
    + +
      + {{ $position := sub (len (split .RelPermalink "/")) 1 }} + {{ $name := (partial "utils/title" .) }} + {{ $value := (printf "
    1. %s
      2. " $name $position ) }} + {{ template "breadcrumb" dict "page" . "value" $value "position" $position }} +
    +
    + {{ end }} + {{ if $showEdit }} + + {{ end }} +
    +

    Last updated: {{ dateFormat "02 Jan 2006" .Page.Lastmod }}

    + + + diff --git a/docs/static/img/faq/use-bicep-module-01.png b/docs/static/img/faq/use-bicep-module-01.png deleted file mode 100644 index 4d9ea134f..000000000 Binary files a/docs/static/img/faq/use-bicep-module-01.png and /dev/null differ diff --git a/docs/static/img/faq/use-bicep-module-02.png b/docs/static/img/faq/use-bicep-module-02.png deleted file mode 100644 index 8637054ca..000000000 Binary files a/docs/static/img/faq/use-bicep-module-02.png and /dev/null differ diff --git a/docs/static/img/faq/use-bicep-module-03.png b/docs/static/img/faq/use-bicep-module-03.png deleted file mode 100644 index 692143cdb..000000000 Binary files a/docs/static/img/faq/use-bicep-module-03.png and /dev/null differ diff --git a/docs/static/img/faq/use-bicep-module-04.png b/docs/static/img/faq/use-bicep-module-04.png deleted file mode 100644 index 2b51a595d..000000000 Binary files a/docs/static/img/faq/use-bicep-module-04.png and /dev/null differ diff --git a/docs/static/img/faq/use-bicep-module-05.png b/docs/static/img/faq/use-bicep-module-05.png deleted file mode 100644 index 756c01515..000000000 Binary files a/docs/static/img/faq/use-bicep-module-05.png and /dev/null differ diff --git a/docs/static/img/faq/use-bicep-module-06.png b/docs/static/img/faq/use-bicep-module-06.png deleted file mode 100644 index 9259589e2..000000000 Binary files a/docs/static/img/faq/use-bicep-module-06.png and /dev/null differ diff --git a/docs/static/img/usage/quickstart/bicep/key-vault-readme-bcp-1080-10fps.mp4 b/docs/static/img/usage/quickstart/bicep/key-vault-readme-bcp-1080-10fps.mp4 new file mode 100644 index 000000000..8f61d4818 Binary files /dev/null and b/docs/static/img/usage/quickstart/bicep/key-vault-readme-bcp-1080-10fps.mp4 differ diff --git a/docs/static/img/usage/quickstart/bicep/key-vault-vscode-bcp-1080-10fps.mp4 b/docs/static/img/usage/quickstart/bicep/key-vault-vscode-bcp-1080-10fps.mp4 new file mode 100644 index 000000000..946016e8d Binary files /dev/null and b/docs/static/img/usage/quickstart/bicep/key-vault-vscode-bcp-1080-10fps.mp4 differ diff --git a/docs/static/img/usage/quickstart/bicep/module-index_bcp_res_1080-10fps.mp4 b/docs/static/img/usage/quickstart/bicep/module-index_bcp_res_1080-10fps.mp4 new file mode 100644 index 000000000..578c66e57 Binary files /dev/null and b/docs/static/img/usage/quickstart/bicep/module-index_bcp_res_1080-10fps.mp4 differ diff --git a/docs/static/img/usage/quickstart/bicep/vs-code-intellisense-bcp-1080-10fps.mp4 b/docs/static/img/usage/quickstart/bicep/vs-code-intellisense-bcp-1080-10fps.mp4 new file mode 100644 index 000000000..e2433d6db Binary files /dev/null and b/docs/static/img/usage/quickstart/bicep/vs-code-intellisense-bcp-1080-10fps.mp4 differ diff --git a/docs/static/img/usage/quickstart/terraform/avm-qs-tf-commands-1080-10.mp4 b/docs/static/img/usage/quickstart/terraform/avm-qs-tf-commands-1080-10.mp4 new file mode 100644 index 000000000..b152e23f4 Binary files /dev/null and b/docs/static/img/usage/quickstart/terraform/avm-qs-tf-commands-1080-10.mp4 differ diff --git a/docs/static/img/usage/quickstart/terraform/avm-tf-qa-discovery-1080-10.mp4 b/docs/static/img/usage/quickstart/terraform/avm-tf-qa-discovery-1080-10.mp4 new file mode 100644 index 000000000..6250a5ebf Binary files /dev/null and b/docs/static/img/usage/quickstart/terraform/avm-tf-qa-discovery-1080-10.mp4 differ diff --git a/docs/static/img/usage/quickstart/terraform/avm-tf-qs-custom-full-1080-10.mp4 b/docs/static/img/usage/quickstart/terraform/avm-tf-qs-custom-full-1080-10.mp4 new file mode 100644 index 000000000..2c7a6c1bb Binary files /dev/null and b/docs/static/img/usage/quickstart/terraform/avm-tf-qs-custom-full-1080-10.mp4 differ diff --git a/docs/static/img/usage/quickstart/terraform/avm-tf-qs-discovery-1080-10.mp4 b/docs/static/img/usage/quickstart/terraform/avm-tf-qs-discovery-1080-10.mp4 new file mode 100644 index 000000000..d963e62b7 Binary files /dev/null and b/docs/static/img/usage/quickstart/terraform/avm-tf-qs-discovery-1080-10.mp4 differ diff --git a/docs/static/img/usage/quickstart/terraform/avm-tf-qs-example-copy-1080-10.mp4 b/docs/static/img/usage/quickstart/terraform/avm-tf-qs-example-copy-1080-10.mp4 new file mode 100644 index 000000000..8366e2c1b Binary files /dev/null and b/docs/static/img/usage/quickstart/terraform/avm-tf-qs-example-copy-1080-10.mp4 differ diff --git a/docs/static/img/usage/quickstart/terraform/avm-tf-qs-example-vscode-1080-10.mp4 b/docs/static/img/usage/quickstart/terraform/avm-tf-qs-example-vscode-1080-10.mp4 new file mode 100644 index 000000000..35b9da310 Binary files /dev/null and b/docs/static/img/usage/quickstart/terraform/avm-tf-qs-example-vscode-1080-10.mp4 differ diff --git a/docs/static/img/usage/quickstart/terraform/avm-tf-search-5-10.gif b/docs/static/img/usage/quickstart/terraform/avm-tf-search-5-10.gif new file mode 100644 index 000000000..48846374c Binary files /dev/null and b/docs/static/img/usage/quickstart/terraform/avm-tf-search-5-10.gif differ diff --git a/docs/static/img/usage/quickstart/terraform/avm-tf-search-5.mp4 b/docs/static/img/usage/quickstart/terraform/avm-tf-search-5.mp4 new file mode 100644 index 000000000..59ab15145 Binary files /dev/null and b/docs/static/img/usage/quickstart/terraform/avm-tf-search-5.mp4 differ diff --git a/docs/static/img/usage/quickstart/terraform/avm-tf-search-6-10.mp4 b/docs/static/img/usage/quickstart/terraform/avm-tf-search-6-10.mp4 new file mode 100644 index 000000000..8327e9cca Binary files /dev/null and b/docs/static/img/usage/quickstart/terraform/avm-tf-search-6-10.mp4 differ diff --git a/docs/static/img/usage/quickstart/terraform/module-index_tf_res_1080-10fps.mp4 b/docs/static/img/usage/quickstart/terraform/module-index_tf_res_1080-10fps.mp4 new file mode 100644 index 000000000..8063b6db2 Binary files /dev/null and b/docs/static/img/usage/quickstart/terraform/module-index_tf_res_1080-10fps.mp4 differ diff --git a/docs/static/js/clarity.js b/docs/static/js/clarity.js deleted file mode 100644 index e36e64e4f..000000000 --- a/docs/static/js/clarity.js +++ /dev/null @@ -1,10 +0,0 @@ -if (window.location.hostname!=='localhost') { - - (function(c,l,a,r,i,t,y){ - c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)}; - t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i; - y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y); - })(window, document, "clarity", "script", "p0l7yeco82"); - - document.querySelector("Article.post").setAttribute("data-clarity-region", "article"); -}