Consul Enterprise HVD on Azure VMs

Terraform module aligned with HashiCorp Validated Designs (HVD) to deploy Consul Enterprise on Microsoft Azure using Azure Virtual Machines.

Prerequisites

This module requires the following resources to already be deployed to an Azure subscription:

• Azure Virtual Network
• Azure Key Vault
• Azure Storage Account
• SSH Public Key
• Consul Enterprise License
• Gossip Encryption Key
• Agent PKI - CA Cert
• Agent PKI - Leaf Cert
• Agent PKI - Leaf Key

Examples

The examples/ubuntu-nlb-consul-primary directory contains a reference deployment of the aforementioned prerequisite resources.

TLS

The certificate authority and leaf certificates for Consul server agents are expected to be generated via an outside authority (e.g. Vault, Consul CLI, Terraform TLS Provider, etc.).

Server certificates are expected to have the following Subject Alternate Names:

• server.<dc>.consul (Required - Should also be certificate CN)
• localhost (Optional - For local CLI/API access)
• 127.0.0.1 (Optional - See above)

Server certificates are required to define the following key usage values:

• Digital Signature
• Key Encipherment
• Server Authentication
• Client Authentication

Secrets management

Use of Azure Key Vault is required for this module. Secrets are expected to conform to the following naming conventions:

Key	Description
gossip-key	Encryption key to use for Serf Gossip traffic. May be generated via consul keygen
storage-account-key	Azure storage account key, provided to the snapshot agent process for periodic backup
consul-agent-cert	Base64-encoded PEM certificate for server TLS
consul-agent-key	Base64-encoded PEM private key for the agent's TLS certificate
consul-ca-cert	Base64-encoded PEM certificate of consul-agent-cert's signing certificate authority
consul-license	Consul Enterprise license

Deployment

Upon initial deployment, Consul servers will auto-join and form a fresh cluster. The ACL system is always enabled in deny-by-default mode. When consul_agent.bootstrap_acls is true (the default setting), the cluster is bootstrapped with basic policies and ACL tokens generated. An operator, or other automation, should then connect to the cluster to perform any post-deployment customization.

Azure Key Vault is required with this module. Review the secrets management section for further information.

ACL Bootstrapping

When the consul_agent.bootstrap_acls parameter is set to true cloud-init will attempt to:

1. Bootstrap the Consul ACL system, creating the initial management token
2. Write the management token to Azure Key Vault (via the mgmt-token secret)
3. Apply a minimal policy set:
   • Anonymous catalog read policy
   • Server agent registration policy
4. Create an ACL token for server agent registration
5. Write the server registration to Azure Key Vault (via the agent-token secret)
6. Apply the written agent token to the running servers

VM image

This module performs all required software installation and configuration at boot time via cloud-init. Currently, a dpkg-based Linux distribution with the apt suite is expected. All testing is performed against Ubuntu 22.04 LTS.

Upon deployment, the following packages are installed:

• Consul Enterprise
• Azure CLI
• unzip
• jq

VM image reference

The VM Scale Set will attempt to use an Azure Platform Image for its base deployment. By default, this is configured to use Ubuntu 22.04 LTS. Alternative images may be provided by overriding the image_reference variable. See the Azure Documentation for more information on discovering platform images.

Docs

Additional documentation for customization and usage can be found in the docs folder.

Module support

This open source software is maintained by the HashiCorp Technical Field Organization, independently of our enterprise products. While our Support Engineering team provides dedicated support for our enterprise offerings, this open source software is not included.

• For help using this open source software, please engage your account team.
• To report bugs/issues with this open source software, please open them directly against this code repository using the GitHub issues feature.

Please note that there is no official Service Level Agreement (SLA) for support of this software as a HashiCorp customer. This software falls under the definition of Community Software/Versions in your Agreement. We appreciate your understanding and collaboration in improving our open source projects.

Requirements

Name	Version
terraform	~> 1.9
azurerm	>=3.113.0
cloudinit	>=2.3.2

Providers

Name	Version
azurerm	>=3.113.0
cloudinit	>=2.3.2

Resources

Name	Type
azurerm_application_security_group.consul_agents	resource
azurerm_dns_a_record.consul	resource
azurerm_lb.consul	resource
azurerm_lb_backend_address_pool.consul_servers	resource
azurerm_lb_probe.consul_health	resource
azurerm_lb_rule.consul_tcp	resource
azurerm_linux_virtual_machine_scale_set.consul	resource
azurerm_private_dns_a_record.consul	resource
azurerm_private_dns_zone_virtual_network_link.consul	resource
azurerm_public_ip.consul_lb	resource
azurerm_resource_group.consul	resource
azurerm_role_assignment.consul_kvso	resource
azurerm_role_assignment.consul_reader	resource
azurerm_user_assigned_identity.consul_iam	resource
azurerm_client_config.current	data source
azurerm_dns_zone.consul	data source
azurerm_private_dns_zone.consul	data source
azurerm_resource_group.consul	data source
cloudinit_config.consul	data source

Inputs

Name	Description	Type	Default	Required
availability_zones	(Required List(string)) List of availability zones to deploy supported resources to. Only works in select regions.	list(string)	n/a	yes
consul_agent	Object containing the Consul Agent configuration.	object({ bootstrap_acls = optional(bool, true) datacenter = optional(string, "dc1") })	n/a	yes
consul_fqdn	(required string) Fully qualified domain name of the consul cluster. This name must match a SAN entry in the TLS server certificate.	string	n/a	yes
consul_secrets	Object containing the Azure Key Vault secrets necessary to inject Consul Agent TLS, Gossip encryption material, and ACL tokens.	object({ kind = string azure_keyvault = optional(object({ id = optional(string) }), {}) })	n/a	yes
environment_name	(required string) Unique environment name to prefix and disambiguate resources using.	string	n/a	yes
region	(required string) Azure region for this consul deployment.	string	n/a	yes
ssh_public_key	(Required string) SSH public key to use when authenticating to VM instances.	string	n/a	yes
subnet_id	(required string) The ID of the subnet in which resources should be deployed.	string	n/a	yes
vnet_id	(Required string) VNet ID where Consul resources will reside.	string	n/a	yes
cloud_init_config_rendered	(Optional base64 string) To override the azurerm_linux_virtual_machine_scale_set.consul.custom_data provide a base64gzip rendered value from the data.cloud_init	string	null	no
common_tags	(Optional map) Map of common tags for taggable Azure resources.	map(string)	{}	no
consul_config_template	(Optional string) name of *.tpl file in the ./templates folder local to the module decleration, to replace the root server.hcl.tpl	string	null	no
consul_install_version	(Optional string) Version of Consul to install, eg. '1.19.2+ent'	string	"1.19.2+ent"	no
consul_nodes	(Optional number) Number of Consul instances.	number	6	no
consul_vm_size	(Optional string) The size of VM instance to use for Consul agents.	string	"Standard_D2s_v3"	no
create_consul_private_dns_record	(Optional bool) Boolean to create a DNS record for consul in a private Azure DNS zone. private_dns_zone_name must also be provided when true.	bool	false	no
create_consul_public_dns_record	(Optional bool) Boolean to create a DNS record for consul in a public Azure DNS zone. public_dns_zone_name must also be provided when true.	bool	false	no
create_lb	(Optional bool) Boolean to create an Azure Load Balancer for Consul.	bool	true	no
create_resource_group	(Optional bool) Boolean to create a new Resource Group for this consul deployment.	bool	true	no
disk_params	Disk parameters to use for the cluster nodes' block devices.	object({ root = object({ disk_type = optional(string, "Premium_LRS") disk_size = optional(number, 32) }), data = object({ disk_type = optional(string, "Premium_LRS") disk_size = optional(number, 1024) }) })	{ "data": {}, "root": {} }	no
image_reference	Azure platform image details to use for VMSS instances	object({ publisher = string, offer = string, sku = string, version = string })	{ "offer": "0001-com-ubuntu-server-jammy", "publisher": "Canonical", "sku": "22_04-lts-gen2", "version": "latest" }	no
load_balancer_internal	(Optional bool) Whether the provisioned load balancer should be internal-facing or internet-facing. If internal facing, ensure NAT Gateway or another internet egress method has been configured in your vnet.	bool	false	no
private_dns_zone_name	(Optional string) Name of existing private Azure DNS zone to create DNS record in. Required when create_consul_private_dns_record is true.	string	null	no
private_dns_zone_rg	(Optional string) Name of Resource Group where private_dns_zone_name resides. Required when create_consul_private_dns_record is true.	string	null	no
public_dns_zone_name	(Optional string) Name of existing public Azure DNS zone to create DNS record in. Required when create_consul_public_dns_record is true.	string	null	no
public_dns_zone_rg	(Optional string) Name of Resource Group where public_dns_zone_name resides. Required when create_consul_public_dns_record is true.	string	null	no
resource_group_name	(Optional string) Name of Resource Group to use for Consul cluster resources	string	"consul-ent-rg"	no
snapshot_agent	Configures the Consul snapshot agent to store backups to an Azure Storage Account.	object({ enabled = bool storage_account_name = optional(string) object_container_name = optional(string) azure_environment = optional(string, "AZURECLOUD") interval = optional(string, "30m") retention = optional(number, 336) # 1 week @ 30m interval })	{ "enabled": false }	no
ssh_username	(Optional string) Default username to add to VMSS instances.	string	"azureuser"	no
storage_account_type	(Optional string) Redundancy type for the Consul Snapshot storage account. Must be one of LRS, GRS, or RAGRS.	string	"GRS"	no