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>-rgholding everything. - VNet (
network_cidr) withpublicandprivatesubnets (default outbound access disabled on both). - NSGs: public subnet allows TCP/22 only from
allowed_ssh_cidrs(priority 100) - withenable_vpnalso UDPvpn_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), withenable_vpneverything 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(defaultazureuser; names Azure reserves - admin, administrator, root, guest, test, user, ... - are refused at setup). - Logging baseline: Log Analytics workspace (PerGB2018;
log_retention_days30-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
tfstatecontainer. - AKS (optional,
enable_kubernetes=true): private cluster (unlesskubernetes_public_endpoint=true, whose authorized ranges areallowed_ssh_cidrsplus 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_enabledin FIPS mode). Changing the node size or FIPS mode rotates the system pool through a temporary poolsystemtmp, 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 bycloudseed 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, needsTS_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/writeat 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/writeat 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
azcommands 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.
--tagon 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_kuberneteswithoutkubernetes_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 underAZURE_CONFIG_DIRis honoured) or theARM_CLIENT_ID/ARM_CLIENT_SECRET/ARM_TENANT_ID/ARM_SUBSCRIPTION_IDenv vars (service principal). A system-assigned managed identity needs onlyARM_USE_MSI=true; OIDC needsARM_CLIENT_IDplusARM_USE_OIDC=true(an OIDC token alone does nothing). Never handle the values yourself. - Tag names are case-insensitive:
--tag environment=xsetsEnvironment(and--tag Environment=...reaches every resource), a later run's spelling replaces a saved one, and two spellings in one run are refused. --regionis checked against the Azure cloudARM_ENVIRONMENTselects:usgov*/usdod*locations needARM_ENVIRONMENT=usgovernment,china*needARM_ENVIRONMENT=china(then alsoaz cloud setandaz login), and the default location follows it (eastus,usgovvirginiaorchinanorth3). Whenazis 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.