What does cidrsubnet("10.0.0.0/16", 8, 3) return in Terraform, and what do the two numeric arguments mean?

## The arithmetic ```hcl cidrsubnet("10.0.0.0/16", 8, 3) # => "10.0.3.0/24" cidrsubnet("10.0.0.0/16", 4, 2) # => "10.0.32.0/20" cidrsubnet("10.0.0.0/16", 8, 255) # => "10.0.255.0/24" ``` Read it as: *take this prefix, make it `newbits` bits longer, and give me subnet number `netnum` of the result.* The new prefix length is `prefix_length + newbits`, and there are `2^newbits` subnets available, indexed `0` to `2^newbits - 1`. In the second example, `/16 + 4 = /20`; each `/20` holds 4096 addresses, which is 16 whole third-octet steps, so index 2 lands on `10.0.32.0`. Requesting a netnum that does not fit — `cidrsubnet("10.0.0.0/16", 4, 20)` when only 16 subnets exist — is an error. Terraform does not wrap around or truncate. ## Why it exists Without it, network layouts get hardcoded: a variable per subnet, or a list of literal CIDR strings that a human calculated once and nobody dares touch. `cidrsubnet` lets a module take one address-space input and derive the rest, so the same code stands up a network in any region or account by changing one string: ```hcl variable "vpc_cidr" { type = string } locals { # three /24s carved out of whatever space the caller gave us subnet_cidrs = [for i in range(3) : cidrsubnet(var.vpc_cidr, 8, i)] } ``` `range(3)` produces `[0, 1, 2]`, and the `for` expression maps each index through the function. ## The companion functions - **`cidrsubnets(prefix, newbits...)`** — allocates a *series* in one call, and each `newbits` argument may differ, so you can hand out one `/22` and several `/24`s from the same space without computing offsets by hand. It packs them consecutively, which is usually what you actually want. - **`cidrhost(prefix, hostnum)`** — returns a single host address within a prefix, useful for a fixed gateway or resolver address. - **`cidrnetmask(prefix)`** — returns the dotted-decimal mask; only meaningful for IPv4. ## The trap worth talking about The function is pure arithmetic and always correct. The risk lives in where `netnum` comes from. When it is derived from a position in an input list, the mapping between a logical subnet and its address is positional — so inserting a new entry in the middle of the list renumbers everything after it. Because a subnet's address range cannot be changed in place, that renumbering is a plan full of destroy-and-recreate on live networks, and everything attached to those subnets goes with them. The defence is to make the index stable rather than positional: derive `netnum` from a key you control — an explicit map of name to index — so adding a network appends a fresh index and never disturbs the existing ones. ```hcl variable "subnet_indexes" { type = map(number) default = { public-a = 0, public-b = 1, private-a = 2 } } locals { cidrs = { for name, i in var.subnet_indexes : name => cidrsubnet(var.vpc_cidr, 8, i) } } ``` Now a new entry with index 3 changes nothing that already exists, and the allocation is documented in the configuration rather than implied by list order. ## Readability tradeoff Computed CIDRs are DRY but opaque: a reviewer reading `cidrsubnet(var.vpc_cidr, 8, 7)` cannot tell what address that is without doing the arithmetic. On a small, stable estate, an explicit map of literal CIDRs is often easier to review and audit against a network diagram. On a module that stands up the same layout in many accounts, computing them is the only sane option. Being able to argue both sides — rather than reciting the arithmetic — is what distinguishes the answer.