Skip to main content

Task 03: Configure Cluster Mode

Implementation Terraform

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 variables come from infrastructure.yml

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​

KeyWhat 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_modeThe cluster name and deployment mode
cluster.key_vaultThe cluster Key Vault: name, create_new, soft_delete_retention_days
cluster.witnessThe witness: type, storage_account, path
nodes[]Each machine: name, serial_number, bmc, network_adapters[]
networking.outbound.arc_gatewayThe 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:

ResourcePurpose
VPN ConnectionSite-to-site connectivity to cluster network
Key VaultCluster-specific secrets storage
Log Analytics WorkspaceCluster monitoring and logs
Storage AccountCloud witness for cluster quorum
DNS A RecordsName resolution for all cluster nodes
Arc Gateway (optional)Hybrid cloud management

Next Steps​

Configuration complete. Proceed to Phase 02 - Pipeline Execution to deploy infrastructure.



When to use: Use this tab if your CI/CD pipeline runs on GitHub Actions.

See procedure steps above for GitHub-specific guidance.

Toolkit Reference

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.

PreviousUpNext
Task 02 - Management ModePhase 01 - ConfigurationPhase 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​

IssueCauseResolution
Cluster mode configuration errorsInvalid cluster topology settingsVerify cluster mode variables match deployment topology
Mode validation failsDependencies between management and cluster modes not metConfigure management mode before cluster mode

Version Control​

VersionDateAuthorChanges
1.0.02026-03-24Azure Local CloudInitial release