Troubleshooting

Troubleshooting

Use this page to narrow failures by symptom.

GitHub Wiki Is Empty

The GitHub UI can show a Wiki tab before the underlying .wiki.git repo exists.

Expected remote:

https://github.com/Jamonygr/azure-landing-zone-lab.wiki.git

If clone or push says Repository not found, create the first page in the GitHub UI or retry pushing a local wiki commit to the wiki remote.

Terraform Format Fails

Symptom:

terraform fmt -check -recursive -diff

Fix:

terraform fmt -recursive

Then review the diff before committing.

Terraform Validate Fails

Check:

• Provider initialization.
• Variable type mismatches.
• Conditional module references.
• Missing required inputs.
• Output references to disabled modules.

Source files:

• main.tf
• variables.tf
• outputs.tf

Azure Login Fails In GitHub Actions

Likely causes:

• Missing id-token: write permission.
• Wrong AZURE_CLIENT_ID.
• Wrong AZURE_TENANT_ID.
• Federated credential subject does not match repo, branch, or environment.
• Entra app lacks required Azure role assignments.

Relevant docs in this wiki:

• CI/CD Pipeline
• Remote State and Secrets

Backend Init Fails

Check secrets:

• TF_STATE_RG
• TF_STATE_SA
• AZURE_SUBSCRIPTION_ID

Check Azure:

• Storage account exists.
• State container exists or action can create it.
• Automation identity has Storage Blob Data Contributor or equivalent.
• Network rules allow the runner path, or private runner path exists.

Source:

• backend.tf
• .github/actions/plan

OPA Policy Fails

Policy files:

• policies/terraform.rego
• policies/security.rego
• policies/naming.rego

Typical causes:

• Missing tags.
• Storage public access.
• SQL public network access.
• Location not in approved region list.
• Key Vault soft delete not configured.

Public RDP Validation Fails

Symptom:

• Plan fails because allowed_jumpbox_source_ips contains 0.0.0.0/0.

Fix:

• Replace with a trusted CIDR.
• Or leave it empty and disable public jumpbox IP.
• Do not set allow_public_rdp_from_internet = true except for temporary break-glass testing.

Source: variables.tf

Cost Management Validation Fails

Symptom:

• Cost management is enabled but no real email is configured.

Fix:

deploy_cost_management = true
cost_alert_emails      = ["platform-team@example.com"]

Source:

• variables.tf
• modules/cost-management

App Gateway Backend Is Empty

Check:

• deploy_application_gateway = true
• deploy_workload_prod = true
• deploy_load_balancer = true if web VMs are expected
• Workload web server IP output exists

Source:

• main.tf application_gateway module
• landing-zones/management/workload/outputs.tf

Private Endpoint DNS Does Not Resolve

Check:

• deploy_private_dns_zones = true
• deploy_private_endpoints = true
• Private DNS zones are linked to hub and relevant spokes.
• Workload DNS path uses Azure DNS or forwards to Azure.
• Private Endpoint network interfaces exist in the shared PE subnet.

Source:

• landing-zones/security/main.tf
• modules/networking/private-dns-zone
• modules/private-endpoint

Terratest Skips

Symptom:

ARM_SUBSCRIPTION_ID not set, skipping integration tests

Fix:

$env:ARM_SUBSCRIPTION_ID = "<subscription-id>"
Set-Location tests
go test ./... -v

Also install Go if go is not recognized.

Source: tests/landing_zone_test.go