|
1 | | -# Examples |
| 1 | +# Introduction |
2 | 2 |
|
3 | | -This directory contains examples that are mostly used for documentation, but can also be run/tested manually via the Terraform CLI. |
| 3 | +This directory contains examples for the Azure provider. The examples are categorized by Azure resource type and scenario. Each example contains a `main.tf` file that demonstrates how to use the resource type in a specific scenario. The `README.md` file in each example directory provides additional information about the example. |
| 4 | + |
| 5 | + |
| 6 | +## File Structure |
| 7 | + |
| 8 | +The file structure is as follows: |
| 9 | + |
| 10 | +``` |
| 11 | +AzureResourceType@APIVersion |
| 12 | +├── senario_name |
| 13 | +│ ├── main.tf (required) |
| 14 | +│ ├── README.md (optional) |
| 15 | +
|
| 16 | +
|
| 17 | +# Example |
| 18 | +# Notice: The `/` in the directory name is replaced with `_` in the resource type name |
| 19 | +Microsoft.Storage_storageAccounts@2021-04-01 |
| 20 | +├── basic |
| 21 | +│ ├── main.tf |
| 22 | +├── with_private_endpoint |
| 23 | +│ ├── main.tf |
| 24 | +│ ├── README.md |
| 25 | +``` |
| 26 | + |
| 27 | + |
| 28 | +## Contributing |
| 29 | + |
| 30 | +If you have an example that you would like to contribute, please follow the guidelines below: |
| 31 | + |
| 32 | +1. Create a new directory for the resource type and API version if it does not already exist. The directory name should be in the format `AzureResourceType@APIVersion` and `/` in the resource type name should be replaced with `_`. For example, `Microsoft.Storage_storageAccounts@2021-04-01`. Please try to use the latest API version available. |
| 33 | + |
| 34 | +2. Create a new directory for the scenario if it does not already exist. The directory name should be descriptive of the scenario. For example, `basic`, `with_private_endpoint`. |
| 35 | + |
| 36 | +3. Create a `main.tf` file in the scenario directory that demonstrates how to use the resource type in the scenario. |
| 37 | + |
| 38 | + 1. Template: Here is a template for the `main.tf` file: |
| 39 | + |
| 40 | + ```hcl |
| 41 | + terraform { |
| 42 | + required_providers { |
| 43 | + azapi = { |
| 44 | + source = "Azure/azapi" |
| 45 | + } |
| 46 | + } |
| 47 | + } |
| 48 | +
|
| 49 | + provider "azapi" { |
| 50 | + skip_provider_registration = false |
| 51 | + } |
| 52 | +
|
| 53 | + variable "resource_name" { |
| 54 | + type = string |
| 55 | + default = "acctest0001" |
| 56 | + } |
| 57 | +
|
| 58 | + variable "location" { |
| 59 | + type = string |
| 60 | + default = "westeurope" |
| 61 | + } |
| 62 | +
|
| 63 | + resource "azapi_resource" "resourceGroup" { |
| 64 | + type = "Microsoft.Resources/resourceGroups@2020-06-01" |
| 65 | + name = var.resource_name |
| 66 | + location = var.location |
| 67 | + } |
| 68 | +
|
| 69 | + resource "azapi_resource" "automationAccount" { |
| 70 | + type = "Microsoft.Automation/automationAccounts@2021-06-22" |
| 71 | + parent_id = azapi_resource.resourceGroup.id |
| 72 | + name = var.resource_name |
| 73 | + location = var.location |
| 74 | + body = { |
| 75 | + properties = { |
| 76 | + encryption = { |
| 77 | + keySource = "Microsoft.Automation" |
| 78 | + } |
| 79 | + publicNetworkAccess = true |
| 80 | + sku = { |
| 81 | + name = "Basic" |
| 82 | + } |
| 83 | + } |
| 84 | + } |
| 85 | + } |
| 86 | +
|
| 87 | + ``` |
| 88 | +
|
| 89 | + 2. Resource label: The resource label should be the singular form of the resource type name. For example, for type `Microsoft.Storage/storageAccounts@2021-04-01`, the resource label should be `storageAccount`; for type `Microsoft.Compute/virtualMachines@2021-03-01`, the resource label should be `virtualMachine`. You can add suffixes to the resource label if there are multiple resources of the same type in the scenario. For example, `storageAccount1`, `storageAccount2`. |
| 90 | +
|
| 91 | + 3. Resource name: The resource name should be set to the `resource_name` variable or computed based on the `resource_name` variable for example `name = "${var.resource_name}-ip"`. One exception is when the resource name is required to be a specific value, for example, when creating a subnet for bastion host, the subnet name should be `AzureBastionSubnet`. During the acceptance test, the variable `resource_name` will be replaced with a unique name. |
| 92 | +
|
| 93 | + 4. Location: The location should be set to the `location` variable. The location should be a location that is supported by the resource type. |
| 94 | +
|
| 95 | + 5. Identity: If the resource type supports identity, you should set the identity block in the resource. For example, `identity { type = "SystemAssigned" }`. |
| 96 | +
|
| 97 | + 6. Dependencies: If the resource has dependencies on other resources, you should create the dependent resources in the same `main.tf` file and use `azapi` resources to represent the dependent resources. You could find examples of how to create dependent resources in the existing examples. |
| 98 | + 1. `subscription_id`: `azapi_client_config` data source is used to get the subscription ID, for example, `subscription_id = data.azapi_client_config.current.subscription_id`. |
| 99 | +
|
| 100 | + 5. Other providers: If other providers are required to create the resource, you should add the required providers block in the `main.tf` file. For example, if the resource requires the `azurerm` provider, you should add the following block to the `main.tf` file: |
| 101 | +
|
| 102 | + ```hcl |
| 103 | + terraform { |
| 104 | + required_providers { |
| 105 | + azapi = { |
| 106 | + source = "Azure/azapi" |
| 107 | + } |
| 108 | + azurerm = { |
| 109 | + source = "hashicorp/azurerm" |
| 110 | + version = "=4.20.0" |
| 111 | + } |
| 112 | + } |
| 113 | + } |
| 114 | + ``` |
| 115 | +
|
| 116 | +
|
| 117 | +4. (Optional) Create a `README.md` file in the scenario directory that provides additional information about the example if the example is complex or requires additional context. |
| 118 | +
|
| 119 | +5. Verify that the example works by running the acceptance tests. You can run the acceptance tests by running the following command: |
| 120 | +
|
| 121 | + ```shell |
| 122 | + make example-test TARGET=AzureResourceType@APIVersion |
| 123 | + ``` |
| 124 | +
|
| 125 | + It will run acceptance tests for all scenarios in the specified example. |
| 126 | +
|
| 127 | + For example, to run the acceptance tests for the `basic` scenario of the `Microsoft.Storage_storageAccounts@2021-04-01` example, you can run the following command: |
| 128 | +
|
| 129 | + ```shell |
| 130 | + make example-test TARGET=Microsoft_Storage_storageAccounts@2021-04-01 |
| 131 | + ``` |
| 132 | +
|
| 133 | + For example, to run multiple examples, you can run the following command: |
| 134 | +
|
| 135 | + ```shell |
| 136 | + make example-test TARGET=Microsoft_Storage_storageAccounts@2021-04-01,Microsoft_Compute_virtualMachines@2021-03-01 |
| 137 | + ``` |
| 138 | +
|
| 139 | + Behind the scenes, it will run the unit test `TestAccExamples_Selected` with environment variable `ARM_TEST_EXAMPLES` set to the target example. The test will create the resources defined in the example and verify that the resources are created successfully, then it will destroy the resources. |
| 140 | + |
| 141 | + It's also acceptable to run the below terraform commands to test the examples: |
| 142 | +
|
| 143 | + ```shell |
| 144 | + cd examples/AzureResourceType@APIVersion/scenario_name |
| 145 | + terraform init |
| 146 | + terraform apply |
| 147 | + terraform plan # it's expected to have no changes |
| 148 | + terraform destroy |
| 149 | + ``` |
| 150 | +
|
| 151 | +6. Create a pull request with the changes. Please also include the output of the acceptance tests in the pull request description. |
| 152 | +
|
| 153 | +
|
| 154 | +## Documentation Examples |
| 155 | +
|
| 156 | +These examples are mostly used for documentation, but can also be run/tested manually via the Terraform CLI. |
4 | 157 |
|
5 | 158 | The document generation tool looks for files in the following locations by default. All other *.tf files besides the ones mentioned below are ignored by the documentation tool. This is useful for creating examples that can run and/or ar testable even if some parts are not relevant for the documentation. |
6 | 159 |
|
7 | 160 | * **provider/provider.tf** example file for the provider index page |
8 | 161 | * **data-sources/`full data source name`/data-source.tf** example file for the named data source page |
9 | | -* **resources/`full resource name`/resource.tf** example file for the named data source page |
| 162 | +* **resources/`full resource name`/resource.tf** example file for the named resource page |
| 163 | +* **ephemeral-resources/`full resource name`/ephemeral-resource.tf** example file for the named ephemeral resource page |
| 164 | +
|
0 commit comments