Skip to content

Commit aba2bb3

Browse files
craigthackerxcraigthackerx
committed
Update README
1 parent 8742f68 commit aba2bb3

File tree

1 file changed

+148
-20
lines changed

1 file changed

+148
-20
lines changed

‎README.md‎

Lines changed: 148 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,159 @@
1-
```hcl
2-
#
3-
```
4-
## Requirements
1+
# Terraform Azure AzDO Pipeline Templates
2+
3+
A collection of **Azure DevOps pipeline templates** designed to simplify and standardize Terraform deployments for Azure.
4+
These templates leverage the **LibreDevOpsHelpers** PowerShell module for reusable tasks and workflows across your pipelines, but are available within the repo locally inside `PowerShellModules` folder.
5+
6+
---
7+
8+
## Prerequisites
9+
10+
- **Azure DevOps** organization and project.
11+
- **Terraform** code repository structured with numeric stack folders (`0_rg`, `1_network`, etc.).
12+
- **Service connection** in Azure DevOps with permissions to your Azure subscription.
13+
- **PowerShell host** with `PowerShell 7+` agents (Windows, Linux, macOS).
14+
- **LibreDevOpsHelpers** PowerShell module installed on agents or in the repository:
15+
```powershell
16+
Install-Module -Name LibreDevOpsHelpers -Scope CurrentUser
17+
```
18+
19+
- You can also call the script via `Run-AzTerraform.ps1`, where the local modules are imported istead of the remote.
20+
21+
---
22+
23+
## Concept
24+
25+
1. **Discover Stacks**
26+
- The script scans the `${TerraformCodeLocation}` folder for subdirectories matching `^\d+_.+` (e.g. `0_rg`, `1_network`, etc.).
27+
- It builds an ordered list based on the leading number in each folder name.
28+
29+
2. **Normalize Execution Order**
30+
- **Apply/Plan**: Uses the naturally sorted list (`0_rg`, then `1_network`, …).
31+
- **Destroy**: When `RunTerraformPlanDestroy` or `RunTerraformDestroy` is true, it reverses the sorted list so that higher-numbered stacks teardown first (e.g. `1_network` → `0_rg`).
32+
33+
3. **Per-Stack Workflow**
34+
For each stack folder in the final order:
35+
1. **Fmt Check**
36+
```powershell
37+
Invoke-TerraformFmtCheck -CodePath $folder
38+
```
39+
2. **Init** (if enabled)
40+
```powershell
41+
Invoke-TerraformInit -CodePath $folder -InitArgs '-input=false','-upgrade=true'
42+
```
43+
3. **Workspace Select** (if enabled)
44+
```powershell
45+
Invoke-TerraformWorkspaceSelect -CodePath $folder -WorkspaceName $TerraformWorkspace
46+
```
47+
4. **Validate**
48+
```powershell
49+
Invoke-TerraformValidate -CodePath $folder
50+
```
51+
5. **Plan / Plan-Destroy**
52+
- **Plan**:
53+
```powershell
54+
Invoke-TerraformPlan -CodePath $folder `
55+
-PlanFile $TerraformPlanFileName `
56+
-PlanArgs $TerraformPlanExtraArgs
57+
```
58+
- **Plan-Destroy**:
59+
```powershell
60+
Invoke-TerraformPlanDestroy -CodePath $folder `
61+
-PlanFile $TerraformDestroyPlanFileName `
62+
-PlanArgs $TerraformPlanDestroyExtraArgs
63+
```
64+
6. **Convert to JSON + Checkov** (if planning)
65+
```powershell
66+
Convert-TerraformPlanToJson -CodePath $folder -PlanFile $chosenPlanFile
67+
Invoke-Checkov -CodePath $folder `
68+
-CheckovSkipChecks $CheckovSkipCheck `
69+
-SoftFail:$CheckovSoftfail
70+
```
71+
7. **Apply / Destroy**
72+
- **Apply**:
73+
```powershell
74+
Invoke-TerraformApply -CodePath $folder `
75+
-SkipApprove `
76+
-ApplyArgs $TerraformApplyExtraArgs
77+
```
78+
- **Destroy**:
79+
```powershell
80+
Invoke-TerraformDestroy -CodePath $folder `
81+
-SkipApprove `
82+
-DestroyArgs $TerraformDestroyExtraArgs
83+
```
84+
85+
4. **Cleanup**
86+
- After all stacks finish, if `DeletePlanFiles` is true, the script deletes all generated plan and JSON files from each stack folder.
87+
88+
---
589
6-
No requirements.
90+
This ensures that your infrastructure is built in dependency order (low-numbered stacks first) and torn down in reverse (high-numbered stacks first), with consistent formatting, validation, scanning and cleanup at each step.
791
8-
## Providers
92+
---
993
10-
No providers.
94+
## Usage
1195
12-
## Modules
96+
1. **Import templates** in your YAML pipeline:
97+
```yaml
98+
resources:
99+
repositories:
100+
- repository: templates
101+
type: git
102+
name: <your org>/terraform-azure-azdo-pipeline-templates
13103
14-
No modules.
104+
stages:
105+
- template: azure-pipeline.yml@templates
106+
parameters:
107+
TerraformCodeLocation: 'terraform'
108+
TerraformStackToRun: ['all']
109+
TerraformWorkspace: 'dev'
110+
UseAzureClientSecretLogin: true
111+
AzureServiceConnection: 'MyAzServiceConnection'
112+
```
113+
114+
2. **Customize parameters**:
115+
- `TerraformCodeLocation`: Path to your Terraform code folder.
116+
- `TerraformStackToRun`: List of stack folder names (or `all`).
117+
- `TerraformWorkspace`: Terraform workspace name.
118+
- `RunTerraformInit`, `RunTerraformPlan`, `RunTerraformApply`, etc. (boolean flags).
119+
- `UseAzureClientSecretLogin`, `UseAzureOidcLogin`, etc. (authentication modes).
120+
121+
3. **Leverage helpers**:
122+
Templates use `Invoke-Terraform*`, `Connect-AzureCli`, and `Invoke-Checkov` commands from the [LibreDevOpsHelpers](https://www.powershellgallery.com/packages/LibreDevOpsHelpers) module for a consistent experience.
123+
124+
---
125+
126+
## Template Files
127+
128+
- **azure-pipeline.yml**: Main pipeline entry point.
129+
- **Local-DevelopmentScript.ps1**: Run and test pipelines locally.
130+
- **PowerShellModules/**: Sample module directory for local development.
131+
132+
---
133+
134+
## Local Testing
135+
136+
To run locally without Azure DevOps:
137+
138+
```powershell
139+
# Install required modules
140+
Install-Module -Name LibreDevOpsHelpers -Scope CurrentUser
141+
142+
# Execute local script
143+
.\Local-DevelopmentScript.ps1 -TerraformCodeLocation 'terraform' -TerraformStackToRun @('all') -UseAzureClientSecretLogin $true
144+
```
15145

16-
## Resources
146+
---
17147

18-
No resources.
148+
## Contributing
19149

20-
## Inputs
150+
1. Fork the repository.
151+
2. Create a feature branch.
152+
3. Submit a pull request.
153+
4. CI will lint, validate, and test your changes.
21154

22-
| Name | Description | Type | Default | Required |
23-
|------|-------------|------|---------|:--------:|
24-
| <a name="input_location"></a> [location](#input\_location) | The location for this resource to be put in | `string` | n/a | yes |
25-
| <a name="input_name"></a> [name](#input\_name) | The name of the VNet gateway | `string` | n/a | yes |
26-
| <a name="input_rg_name"></a> [rg\_name](#input\_rg\_name) | The name of the resource group, this module does not create a resource group, it is expecting the value of a resource group already exists | `string` | n/a | yes |
27-
| <a name="input_tags"></a> [tags](#input\_tags) | A map of the tags to use on the resources that are deployed with this module. | `map(string)` | n/a | yes |
155+
---
28156

29-
## Outputs
157+
## License
30158

31-
No outputs.
159+
MIT © Libre DevOps

0 commit comments

Comments
 (0)