Task 03: Configure Cluster Mode
DOCUMENT CATEGORY: Task
SCOPE: Cluster mode configuration
PURPOSE: Define cluster VPN, Key Vault, storage, and DNS records MASTER REFERENCE: Azure Local Deployment Overview
Status: Active Last Updated: 2026-02-07
Objective
Describe the cluster side of the environment in infrastructure.yml: the on-premises VPN peer, the cluster Key Vault and witness, and the nodes. The Terraform code builds the Azure foundation only. The cluster itself is deployed with the ARM template in Phase 05.
The Terraform code (src/terraform) does not define the facts of an environment a second time. New-IacVariableFiles.ps1 reads infrastructure.yml and writes terraform.tfvars.json and backend.hcl. The registry says, for every Terraform variable, which key it comes from. Every value comes from infrastructure.yml (a key the file leaves out gets its registry default); terraform.tfvars.example holds comments only. Add no .tfvars file of your own: a later -var-file overrides the generated values. A secret is never written to a file: the generator writes not-written.txt and names the environment variable that Terraform reads at run time.
Prerequisites
- Task 02 complete
- The on-premises network design and the VPN device details from Planning & Discovery
Configuration
| Key | What it holds |
|---|---|
landing_zone.connectivity.vpn_gateway.site_to_site[] | The on-premises peer: connection_name, local_gateway_name, peer_public_ip, peer_address_prefixes, peer_bgp_address, peer_asn, shared_key (a secret reference) |
cluster.name, cluster.deployment_mode | The cluster name and deployment mode |
cluster.key_vault | The cluster Key Vault: name, create_new, soft_delete_retention_days |
cluster.witness | The witness: type, storage_account, path |
nodes[] | Each machine: name, serial_number, bmc, network_adapters[] |
networking.outbound.arc_gateway | The Azure Arc gateway: name and resource_group |
Every key, with its type, default and example, is in the variables reference.
Node names
Pick a node naming pattern and keep it. Names follow the pattern {cluster}-{node}-{env}-{location}, for example iic-clus01-n01.
Validation
- Cluster instance and location codes correct
- On-premises cluster BGP ASN matches network team documentation
- Cluster IP and gateway public IP verified
- Gateway BGP IP confirmed with network team
- VPN Gateway ID references management deployment
- All cluster nodes listed with correct hostnames and IPs
- Node naming convention follows standard pattern
- Arc Gateway setting matches requirements
Resources Deployed
When cluster mode is configured, these resources are created:
| Resource | Purpose |
|---|---|
| VPN Connection | Site-to-site connectivity to cluster network |
| Key Vault | Cluster-specific secrets storage |
| Log Analytics Workspace | Cluster monitoring and logs |
| Storage Account | Cloud witness for cluster quorum |
| DNS A Records | Name resolution for all cluster nodes |
| Arc Gateway (optional) | Hybrid cloud management |
Next Steps
Configuration complete. Proceed to Phase 02 - Pipeline Execution to deploy infrastructure.
- GitHub
- GitLab
- Azure DevOps
When to use: Use this tab if your CI/CD pipeline runs on GitHub Actions.
See procedure steps above for GitHub-specific guidance.
When to use: Use this tab if your CI/CD pipeline runs on GitLab CI/CD.
See procedure steps for GitLab-specific guidance.
When to use: Use this tab if your CI/CD pipeline runs on Azure DevOps Pipelines.
See procedure steps for Azure DevOps-specific guidance.
Scripts for this task are located in the azurelocal-toolkit repository under scripts/deploy/ in the appropriate task folder.
Alternatives
The procedures in this task use the methods shown in the tabs above. The toolkit is PowerShell 7 only and has no Bash scripts. A few tasks that act on Azure also have an Azure CLI script written in PowerShell. The script status page of the toolkit lists which task has which script.
Navigation
| Previous | Up | Next |
|---|---|---|
| Task 02 - Management Mode | Phase 01 - Configuration | Phase 02 - Pipeline Execution |
Values from infrastructure.yml
The pipeline settings are in the devops section of infrastructure.yml (schema 5): the platform, the project, the repository, the approval environments, the runners and the Terraform state. The Terraform code does not define these values a second time. config/variables/scripts/New-IacVariableFiles.ps1 writes terraform.tfvars.json and backend.hcl from the file. See the variables reference.
Troubleshooting
| Issue | Cause | Resolution |
|---|---|---|
| Cluster mode configuration errors | Invalid cluster topology settings | Verify cluster mode variables match deployment topology |
| Mode validation fails | Dependencies between management and cluster modes not met | Configure management mode before cluster mode |
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2026-03-24 | Azure Local Cloud | Initial release |