Skip to content

Commit abe5b48

Browse files
azure-verified-modules[bot]azure-verified-modules[bot]
authored
chore: pre-commit updates (#104)
Co-authored-by: azure-verified-modules[bot] <187664033+azure-verified-modules[bot]@users.noreply.github.com>
1 parent 6b5f0e4 commit abe5b48

9 files changed

Lines changed: 1206 additions & 457 deletions

File tree

‎.agents/skills/AVM-Terraform-Development/AzAPI.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# AzAPI Provider
2+
3+
All Azure resources in AVM modules MUST be deployed using the **AzAPI provider** (`Azure/azapi`).
4+
5+
## Provider Configuration
6+
7+
```hcl
8+
terraform {
9+
required_providers {
10+
azapi = {
11+
source = "Azure/azapi"
12+
version = "~> 2.8"
13+
}
14+
}
15+
}
16+
```
17+
18+
## Resource Pattern
19+
20+
AzAPI resources use ARM resource types with explicit API versions:
21+
22+
```hcl
23+
resource "azapi_resource" "example" {
24+
type = "<ResourceProvider>/<ResourceType>@<ApiVersion>"
25+
parent_id = "<parent resource ID>"
26+
name = "<resource name>"
27+
location = "<Azure region>"
28+
29+
body = {
30+
properties = {
31+
# Resource-specific properties (HCL object, NOT JSON string)
32+
}
33+
}
34+
35+
# MUST include this, set to empty list if no exports are needed.
36+
response_export_values = [
37+
"properties.<field>",
38+
]
39+
}
40+
```
41+
42+
### Key attributes
43+
44+
| Attribute | Description |
45+
| ------------------------ | ----------------------------------------------------------------------------------------------------- |
46+
| `type` | ARM resource type with API version (e.g., `Microsoft.Storage/storageAccounts@2023-01-01`) |
47+
| `parent_id` | ID of the parent resource. For top-level resources: `/subscriptions/{sub}/resourceGroups/{rg}` |
48+
| `name` | Resource name |
49+
| `location` | Azure region |
50+
| `body` | Resource properties as an **HCL object** (not a JSON string) |
51+
| `response_export_values` | List of ARM property paths to export set to empty list if not used (e.g., `"properties.principalId"`) |
52+
| `locks` | A mutex. List of resource IDs to lock on to prevent concurrent operations |
53+
54+
### Accessing outputs
55+
56+
Use `.output` to access exported values:
57+
58+
```hcl
59+
azapi_resource.example.output.properties.principalId
60+
```
61+
62+
## Data sources
63+
64+
```hcl
65+
# Get current client context (subscription, tenant)
66+
data "azapi_client_config" "current" {}
67+
68+
# Use in expressions:
69+
data.azapi_client_config.current.subscription_id
70+
data.azapi_client_config.current.subscription_resource_id
71+
data.azapi_client_config.current.tenant_id
72+
```
73+
74+
## Unit test mocking
75+
76+
```hcl
77+
mock_provider "azapi" {}
78+
```
79+
80+
## Azure Resource Schema Lookup
81+
82+
Use the `azure-schema` CLI tool (bundled at `.agents/skills/AVM-Terraform-Development/azure-schema`) to look up resource type schemas, properties, constraints, and available API versions. This is essential for knowing the correct `type` and `body` structure for `azapi_resource`.
83+
84+
### List available API versions
85+
86+
```bash
87+
.agents/skills/AVM-Terraform-Development/azure-schema versions Microsoft.Storage
88+
```
89+
90+
### Get a resource schema (human-readable)
91+
92+
```bash
93+
.agents/skills/AVM-Terraform-Development/azure-schema get Microsoft.Storage/storageAccounts 2023-01-01
94+
```
95+
96+
### Get a resource schema (resolved JSON)
97+
98+
```bash
99+
.agents/skills/AVM-Terraform-Development/azure-schema get Microsoft.Storage/storageAccounts 2023-01-01 --json
100+
```
101+
102+
### Control depth
103+
104+
```bash
105+
# Shallow view (top-level properties only)
106+
.agents/skills/AVM-Terraform-Development/azure-schema get Microsoft.Storage/storageAccounts 2023-01-01 --depth 2
107+
108+
# Deep view (default is 5)
109+
.agents/skills/AVM-Terraform-Development/azure-schema get Microsoft.Storage/storageAccounts 2023-01-01 --depth 8
110+
```
111+
112+
## Sensitive attributes
113+
114+
- Passwords, keys, etc should be passed in using the `sensitive_body` attribute. This object is merged with the `body` at runtime.
115+
- All sensitive values MUST be ephemeral.
116+
- Use `sensitive_body_version` as a map to track the JSON properties that are set via `sensitive_body`. This allows Terraform to know when the sensitive value has changed, e.g. `sensitive_body_version = { "properties.key1" = "1" }`."
117+
- Reference each sensitive body version as a variable.
118+
119+
### Workflow
120+
121+
1. Find the API version: `azure-schema versions <Provider>`
122+
2. Get the schema: `azure-schema get <ResourceType> <ApiVersion>`
123+
3. Map the schema properties into the `body` block of your `azapi_resource`
124+
4. Properties marked `[READ-ONLY]` should not be set in `body` -- use `response_export_values` to read them if required
125+
5. Properties marked `[REQUIRED]` must be included in `body`

‎.agents/skills/AVM-Terraform-Development/SKILL.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
name: AVM-Terraform-Development
3+
description: Azure Verified Modules (AVM) Terraform development workflow for fixing issues and adding features
4+
glob: "**/*.terraform,**/*.tf,**/*.tfvars,**/*.tfstate,**/*.tflint.hcl,**/*.tf.json,**/*.tfvars.json"
5+
---
6+
7+
# Azure Verified Modules (AVM) Terraform
8+
9+
Azure Verified Modules (AVM) are pre-built, tested, and validated Terraform and Bicep modules that follow Azure best practices. Use these modules to create, update, or review Azure Infrastructure as Code (IaC) with confidence.
10+
11+
## Development Workflow
12+
13+
Follow these steps in order when fixing an issue or adding a feature.
14+
15+
### Step 1: Start from a clean main branch
16+
17+
```bash
18+
git checkout main
19+
git pull
20+
```
21+
22+
### Step 2: Create and checkout a feature/issue branch
23+
24+
```bash
25+
git checkout -b feature/<short-description>
26+
# or
27+
git checkout -b fix/<issue-number>-<short-description>
28+
```
29+
30+
### Step 3: Implement the change
31+
32+
All Azure resources MUST be deployed using the **AzAPI provider** (`Azure/azapi`). For AzAPI resource patterns, schema lookups, and the `azure-schema` CLI tool, read [AzAPI.md](AzAPI.md).
33+
34+
To query Terraform provider schemas (resources, data sources, functions, ephemeral resources), use the `tfpluginschema` CLI. See [tfpluginschema.md](tfpluginschema.md).
35+
36+
Make the necessary code changes to add the feature or fix the issue.
37+
38+
### Step 4: Add unit tests (if justified)
39+
40+
Unit tests use **provider mocking** and live in the `tests/unit` directory. Add or update unit tests when your change introduces new logic, variables, or outputs that can be validated without deploying real infrastructure. For test writing guidance, syntax, and patterns, read [terraform-test.md](terraform-test.md).
41+
42+
```bash
43+
PORCH_NO_TUI=1 ./avm tf-test-unit
44+
```
45+
46+
### Step 5: Add integration tests (if justified)
47+
48+
Integration tests do **not** use provider mocking and live in the `tests/integration` directory. Add or update integration tests when your change requires validation against real Azure infrastructure. For test writing guidance, syntax, and patterns, read [terraform-test.md](terraform-test.md).
49+
50+
```bash
51+
PORCH_NO_TUI=1 ./avm tf-test-integration
52+
```
53+
54+
### Step 6: Add or update examples (if justified)
55+
56+
If your change affects module usage or introduces new functionality, add or update examples in the `examples/` directory. Test only the pertinent example:
57+
58+
```bash
59+
PORCH_NO_TUI=1 AVM_EXAMPLE="<ExampleDir>" ./avm test-examples
60+
```
61+
62+
### Step 7: Update documentation (if justified)
63+
64+
If documentation changes are needed, edit `_header.md`. **NEVER edit README.md directly** -- it is auto-generated and will be overwritten.
65+
66+
### Step 8: Run pre-commit checks (MANDATORY)
67+
68+
This must **always** be run before committing:
69+
70+
```bash
71+
PORCH_NO_TUI=1 ./avm pre-commit
72+
```
73+
74+
### Step 9: Commit changes
75+
76+
```bash
77+
git add .
78+
git commit -m "<type>: <meaningful description>"
79+
```
80+
81+
### Step 10: Run PR checks (MANDATORY)
82+
83+
This must **always** be run after committing:
84+
85+
```bash
86+
PORCH_NO_TUI=1 ./avm pr-check
87+
```
88+
89+
### Step 11: Push and open a PR
90+
91+
Push the branch to remote and open a pull request with a meaningful description. Reference any issues that should be closed.
92+
93+
```bash
94+
git push -u origin HEAD
95+
```
96+
97+
When creating the PR, include:
98+
99+
- A clear description of what was changed and why
100+
- References to related issues (e.g., `Closes #123`)
101+
102+
## Troubleshooting Test Failures
103+
104+
If any issues arise during testing or PR checks, refer to the official AVM testing documentation:
105+
106+
<https://raw.githubusercontent.com/Azure/Azure-Verified-Modules/refs/heads/main/docs/content/contributing/terraform/testing.md>
107+
108+
## Reference
109+
110+
### Code Quality
111+
112+
- Always run `terraform fmt` after making changes
113+
- Always run `terraform validate` after making changes
114+
- Use meaningful variable names and descriptions
115+
- Use snake_case
116+
- Add proper tags and metadata
117+
- Document complex configurations
118+
119+
### Tool Integration
120+
121+
- **AzAPI Provider & Schema Lookup**: See [AzAPI.md](AzAPI.md) for resource patterns and the `azure-schema` CLI tool
122+
- **Terraform Provider Schemas**: See [tfpluginschema.md](tfpluginschema.md) for querying resource, data source, function, and ephemeral schemas from any provider
123+
- **Terraform Tests**: See [terraform-test.md](terraform-test.md) for writing unit and integration tests
124+
- **Deployment Guidance**: Use `azure_get_deployment_best_practices` tool
125+
- **Service Documentation**: Use `microsoft.docs.mcp` tool for Azure service-specific guidance

0 commit comments

Comments
 (0)