Skip to content

Azure target reference

What cloudseed setup azure builds, every variable you can set with --var, and every output. In the terminal: cloudseed help azure or cloudseed explain target azure.

Generated from the code

This page is generated by scripts/gen-docs.py from terraform/azure/variables.tf, terraform/azure/outputs.tf, the setup questions and skills/cloudseed-azure/SKILL.md, so it always matches the CLI you install (this build: cloudseed 0.2.3).

What it builds

cloudseed setup azure --env <env> --subscription-id <id> builds, in one location:

  • Resource group <name>-<env>-rg holding everything.
  • VNet (network_cidr) with public and private subnets (default outbound access disabled on both).
  • NSGs: public subnet allows TCP/22 only from allowed_ssh_cidrs (priority 100) - with enable_vpn also UDP vpn_port (Tailscale: 41641) from the Internet to the VPN host only (AllowVPN, 110) - then denies all inbound; private subnet allows SSH from the public subnet (100), with enable_vpn everything from the VPN host (AllowFromVPN, 150; VPN clients are NATed behind it), traffic inside the private subnet (200), with AKS the pod CIDR of the overlay network (210) and TCP 80/443 from the bastion to the internal ingress (220), and AzureLoadBalancer health probes (300), then denies all inbound (4000). The deny rules are not logged (NSG / VNet flow logs are not managed).
  • NAT gateway (Standard, static public IP) attached to the private subnet for egress.
  • Bastion VM: Ubuntu 24.04 LTS (Ubuntu Pro FIPS 22.04 marketplace image when fips_mode=true; the terms are accepted for you), Standard_B1s, SSH key only, Trusted Launch (secure boot + vTPM), system-assigned managed identity, static Standard public IP. Login user = admin_username (default azureuser; names Azure reserves - admin, administrator, root, guest, test, user, ... - are refused at setup).
  • Logging baseline: Log Analytics workspace (PerGB2018; log_retention_days 30-730 - Azure raises anything below 30 to 30) and the subscription Activity Log streamed into it. Optional Microsoft Defender for Cloud (enable_defender=true): Defender for Servers Plan 2 and Defender for Storage (DefenderForStorageV2); a sub-plan or extension an administrator changes later (agentless scanning, malware scanning, ...) is left alone.
  • Remote state (when chosen): dedicated resource group + StorageV2 account (TLS 1.2, HTTPS only, no public blob access, blob versioning + soft delete) with a private tfstate container.
  • AKS (optional, enable_kubernetes=true): private cluster (unless kubernetes_public_endpoint=true, whose authorized ranges are allowed_ssh_cidrs plus the NAT egress IP and the bastion; changing it later re-creates the cluster) in the private subnet; a private cluster also publishes its API server's private IP under a public DNS name (<prefix>-<id>.hcp.<region>.azmk8s.io), so kubectl works over the VPN or Tailscale and through the bastion tunnel while the API stays unreachable from the Internet (for an existing cluster, applying this is an in-place update); Azure CNI overlay, egress through the NAT gateway, workload identity + OIDC issuer, Azure Policy, control-plane logs (API server, audit-admin, controller manager, scheduler, autoscaler) in Log Analytics, autoscaling system pool (fips_enabled in FIPS mode). Changing the node size or FIPS mode rotates the system pool through a temporary pool systemtmp, which needs spare vCPU quota and subnet IPs. Managed identities for external-secrets and external-dns; Velero's storage account, container, identity and a custom role (its name ends with the first 8 characters of the subscription id, so same-named environments in two subscriptions of one tenant do not collide) are added by cloudseed platform install velero. After creation the pool is resized through the AKS API (cloudseed node add|remove|scale).
  • VPN host (optional, enable_vpn=true): OpenVPN (default) or a Tailscale subnet router (vpn_type=tailscale, needs TS_AUTHKEY) in the public subnet (Ubuntu Pro FIPS image in FIPS mode).
  • FIPS 140 (optional, fips_mode=true, new environments only): Pro FIPS images for the bastion and VPN host, FIPS AKS node pool, RSA-4096 SSH keys (Azure refuses ECDSA; a key you bring must be RSA-3072 or larger); Tailscale, kubeadm and ed25519 keys are refused.
  • Provider: azurerm >= 4.65, < 5.0 (the remote-state storage root needs >= 4.9).

Stack variables

Override any of these with --var name=value on cloudseed setup azure (JSON for lists and maps; --var name=null drops a saved override). Values are read by the variable's declared type.

Variable Default Description
subnet_newbits 8 Extra bits added to network_cidr to carve the public and private subnets (8 => /24s from a /16).
admin_username azureuser (--admin-username) Login user on the bastion and VPN host.
bastion_vm_size "Standard_B1s" Bastion VM size
enable_activity_log true Stream the subscription Activity Log to a Log Analytics workspace.
log_retention_days 30 Retention of the Log Analytics workspace, in days (Azure allows up to 730; values below 30 are raised to 30).
enable_defender false Enable Microsoft Defender for Cloud (Servers + Storage) on the subscription. Paid.
enable_kubernetes false Create a private AKS cluster in the private subnet.
kubernetes_version null AKS version (null = current default).
kubernetes_node_size "Standard_B2s" Kubernetes node size
kubernetes_node_count 2 Nodes the AKS system pool starts with (at least kubernetes_node_min; kubernetes_node_max is raised to it when lower); afterwards the cluster autoscaler owns the count.
kubernetes_node_min 1 Autoscaler minimum of the AKS system pool (the autoscaler adds nodes up to it).
kubernetes_node_max 4 Autoscaler maximum of the AKS system pool.
kubernetes_public_endpoint false Public API server restricted to allowed_ssh_cidrs (plus the environment's NAT egress IP and the bastion, which the nodes and tunnels use) instead of a private cluster. Changing it later re-creates the cluster.
enable_vpn false Create a VPN host in the public subnet for access to the private network.
vpn_type "openvpn" VPN flavour on the VPN host: openvpn (self-contained, client certificates) or tailscale (subnet router, needs TS_AUTHKEY).
vpn_vm_size "Standard_B1s" VM size of the VPN host.
vpn_port 1194 UDP port the OpenVPN server listens on (a Tailscale VPN host uses 41641).
fips_mode false FIPS 140 mode for the whole environment: Ubuntu Pro FIPS bastion/VPN images (marketplace terms accepted automatically), FIPS-enabled AKS node pool, FIPS-only SSH algorithms, ECDSA SSH keys.
kubernetes_sku_tier "Free" AKS control-plane tier: Free or Standard (paid uptime SLA).
kubernetes_zones [] AKS system-pool availability zones. Confirm support in the selected region and VM size; changing zones rotates nodes.

Setup inputs

Asked by setup (or given as flags / --var KEY=VALUE); they are not Terraform variables but shape what is rendered.

Input Default Flag / environment Description
subscription_id the one az account show names --subscription-id, ARM_SUBSCRIPTION_ID, AZURE_SUBSCRIPTION_ID Azure subscription ID

Set by cloudseed

These stack variables are refused in --var: cloudseed sets them itself. Use the flag shown instead.

Variable How to set it
location --region
name --name (default: cloudseed)
environment --env (default: dev)
network_cidr --cidr (default: the first free 10.N.0.0/16 across your environments)
allowed_ssh_cidrs --allow-ip or cloudseed update-ip (default: your public IP)
ssh_public_key the environment's generated key, or --ssh-public-key
tags Project/Environment/Owner/ManagedBy/CloudseedEnv/CloudseedEnvId + --tag KEY=VALUE
platform_prereqs managed by cloudseed platform install <item> (never set it by hand)

Outputs

Read them with cloudseed output azure --env <env> (add --json for scripts).

Output Description
resource_group_name Resource group holding the environment.
location Azure location.
vnet_id Virtual network ID.
public_subnet_id Public subnet (bastion).
private_subnet_id Private subnet for workloads (NAT gateway egress).
nat_public_ip Public IP your private workloads egress from.
bastion_public_ip Static public IP of the bastion.
bastion_vm_id Bastion VM resource ID.
bastion_instance_id Unique ID of the bastion VM (vmId); it changes when the VM is re-created behind the same public IP, so cloudseed then forgets the old SSH host key.
log_analytics_workspace_id Log Analytics workspace receiving the Activity Log.
ssh_user Login user on the bastion.
kubernetes_cluster_name AKS cluster name (null when disabled).
kubernetes_endpoint AKS API server FQDN. For a private cluster (the default) a public DNS name of the API server's private IP (<prefix>-<id>.hcp.<region>.azmk8s.io): reachable over the VPN, through the bastion tunnel or inside the VNet, never from the Internet. With kubernetes_public_endpoint = true the public API name (restricted to allowed_ssh_cidrs).
vpn_public_ip Public IP of the VPN host (null when disabled).
vpn_instance_id Unique ID of the VPN host VM (vmId; null when disabled); it changes when the VM is re-created behind the same public IP.
vpn_type VPN flavour on the VPN host: openvpn or tailscale (null when the VPN is disabled).
vpn_port UDP port the VPN host listens on: vpn_port for OpenVPN, 41641 for Tailscale (null when the VPN is disabled).
kubernetes_external_secrets_client_id Managed identity (workload identity) for external-secrets; grant it Key Vault Secrets User on your vaults.
kubernetes_external_dns_client_id Managed identity client ID (workload identity) for external-dns (null when Kubernetes is disabled).
kubernetes_velero_client_id Managed identity client ID (workload identity) for velero (null when Kubernetes is disabled).
kubernetes_velero_storage_account Storage account for Velero backups (created when the velero platform item is installed).
kubernetes_velero_container Blob container Velero backs up to (null until the velero platform item is installed).
kubernetes_node_resource_group AKS-managed node resource group, MC_* (null when Kubernetes is disabled).
tenant_id Azure tenant (Entra ID) of the environment; the cluster workload identities are issued there.
subscription_id Azure subscription holding the environment.
fips_mode Whether the environment was built in FIPS 140 mode.

Gotchas

  • Permissions: the base environment needs Contributor; the Activity Log diagnostic setting is subscription-scoped (Contributor or Microsoft.Insights/diagnosticSettings/write at subscription scope, otherwise set --var enable_activity_log=false). AKS (enable_kubernetes) creates role assignments (Network Contributor, DNS Zone Contributor), which need Owner, Contributor + User Access Administrator, or Contributor + Role Based Access Control Administrator. Velero (cloudseed platform install velero) adds role assignments (its custom role, Storage Blob Data Contributor) and the custom role definition itself (Microsoft.Authorization/roleDefinitions/write at subscription scope), which only Owner or Contributor + User Access Administrator can create - Role Based Access Control Administrator cannot create role definitions. With Contributor alone they fail with 403 AuthorizationFailed.
  • Subscription-wide singletons: Defender pricing and the Ubuntu Pro FIPS marketplace terms are settings of the whole subscription - enable Defender in one environment only. A destroy leaves both in place (it prints the az commands to turn them off). The Activity Log diagnostic setting counts against the limit of 5 per subscription.
  • NSG flow logs are not created (they need Network Watcher wiring); mention this if the user asks for flow logs on Azure.
  • --tag on Azure: names without < > % & \ ? / or control characters and at most 128 characters (every tag also lands on the storage accounts), values at most 256, and at most 43 names of your own (a resource holds 50 tags and cloudseed sets 7). With a private AKS cluster (enable_kubernetes without kubernetes_public_endpoint) at most 9: AKS copies the cluster's tags onto its private DNS zone, which holds 15, and cloudseed sets 6 on the cluster. Setup refuses anything else before Terraform runs.
  • Credentials: az login (the Azure CLI must then be installed: Terraform reads that login through it; a login under AZURE_CONFIG_DIR is honoured) or the ARM_CLIENT_ID/ARM_CLIENT_SECRET/ARM_TENANT_ID/ARM_SUBSCRIPTION_ID env vars (service principal). A system-assigned managed identity needs only ARM_USE_MSI=true; OIDC needs ARM_CLIENT_ID plus ARM_USE_OIDC=true (an OIDC token alone does nothing). Never handle the values yourself.
  • Tag names are case-insensitive: --tag environment=x sets Environment (and --tag Environment=... reaches every resource), a later run's spelling replaces a saved one, and two spellings in one run are refused.
  • --region is checked against the Azure cloud ARM_ENVIRONMENT selects: usgov* / usdod* locations need ARM_ENVIRONMENT=usgovernment, china* need ARM_ENVIRONMENT=china (then also az cloud set and az login), and the default location follows it (eastus, usgovvirginia or chinanorth3). When az is logged in to that cloud its location list decides (an unknown location is refused, with a did-you-mean); otherwise an unknown location only gets a warning, so a location newer than cloudseed still works.