github.com/rstandt/terraform@v0.12.32-0.20230710220336-b1063613405c/website/docs/configuration/functions/cidrsubnet.html.md (about) 1 --- 2 layout: "functions" 3 page_title: "cidrsubnet - Functions - Configuration Language" 4 sidebar_current: "docs-funcs-ipnet-cidrsubnet" 5 description: |- 6 The cidrsubnet function calculates a subnet address within a given IP network 7 address prefix. 8 --- 9 10 # `cidrsubnet` Function 11 12 -> **Note:** This page is about Terraform 0.12 and later. For Terraform 0.11 and 13 earlier, see 14 [0.11 Configuration Language: Interpolation Syntax](../../configuration-0-11/interpolation.html). 15 16 `cidrsubnet` calculates a subnet address within given IP network address prefix. 17 18 ```hcl 19 cidrsubnet(prefix, newbits, netnum) 20 ``` 21 22 `prefix` must be given in CIDR notation, as defined in 23 [RFC 4632 section 3.1](https://tools.ietf.org/html/rfc4632#section-3.1). 24 25 `newbits` is the number of additional bits with which to extend the prefix. 26 For example, if given a prefix ending in `/16` and a `newbits` value of 27 `4`, the resulting subnet address will have length `/20`. 28 29 `netnum` is a whole number that can be represented as a binary integer with 30 no more than `newbits` binary digits, which will be used to populate the 31 additional bits added to the prefix. 32 33 This function accepts both IPv6 and IPv4 prefixes, and the result always uses 34 the same addressing scheme as the given prefix. 35 36 Unlike the related function [`cidrsubnets`](./cidrsubnets.html), `cidrsubnet` 37 allows you to give a specific network number to use. `cidrsubnets` can allocate 38 multiple network addresses at once, but numbers them automatically starting 39 with zero. 40 41 ## Examples 42 43 ``` 44 > cidrsubnet("172.16.0.0/12", 4, 2) 45 172.18.0.0/16 46 > cidrsubnet("10.1.2.0/24", 4, 15) 47 10.1.2.240/28 48 > cidrsubnet("fd00:fd12:3456:7890::/56", 16, 162) 49 fd00:fd12:3456:7800:a200::/72 50 ``` 51 52 ## Netmasks and Subnets 53 54 Using `cidrsubnet` requires familiarity with some network addressing concepts. 55 56 The most important idea is that an IP address (whether IPv4 or IPv6) is 57 fundamentally constructed from binary digits, even though we conventionally 58 represent it as either four decimal octets (for IPv4) or a sequence of 16-bit 59 hexadecimal numbers (for IPv6). 60 61 Taking our example above of `cidrsubnet("10.1.2.0/24", 4, 15)`, the function 62 will first convert the given IP address string into an equivalent binary 63 representation: 64 65 ``` 66 10 . 1 . 2 . 0 67 00001010 00000001 00000010 | 00000000 68 network | host 69 ``` 70 71 The `/24` at the end of the prefix string specifies that the first 24 72 bits -- or, the first three octets -- of the address identify the network 73 while the remaining bits (32 - 24 = 8 bits in this case) identify hosts 74 within the network. 75 76 The CLI tool [`ipcalc`](https://gitlab.com/ipcalc/ipcalc) is useful for 77 visualizing CIDR prefixes as binary numbers. We can confirm the conversion 78 above by providing the same prefix string to `ipcalc`: 79 80 ``` 81 $ ipcalc 10.1.2.0/24 82 Address: 10.1.2.0 00001010.00000001.00000010. 00000000 83 Netmask: 255.255.255.0 = 24 11111111.11111111.11111111. 00000000 84 Wildcard: 0.0.0.255 00000000.00000000.00000000. 11111111 85 => 86 Network: 10.1.2.0/24 00001010.00000001.00000010. 00000000 87 HostMin: 10.1.2.1 00001010.00000001.00000010. 00000001 88 HostMax: 10.1.2.254 00001010.00000001.00000010. 11111110 89 Broadcast: 10.1.2.255 00001010.00000001.00000010. 11111111 90 Hosts/Net: 254 Class A, Private Internet 91 ``` 92 93 This gives us some additional information but also confirms (using a slightly 94 different notation) the conversion from decimal to binary and shows the range 95 of possible host addresses in this network. 96 97 While [`cidrhost`](./cidrhost.html) allows calculating single host IP addresses, 98 `cidrsubnet` on the other hand creates a new network prefix _within_ the given 99 network prefix. In other words, it creates a subnet. 100 101 When we call `cidrsubnet` we also pass two additional arguments: `newbits` and 102 `netnum`. `newbits` decides how much longer the resulting prefix will be in 103 bits; in our example here we specified `4`, which means that the resulting 104 subnet will have a prefix length of 24 + 4 = 28 bits. We can imagine these 105 bits breaking down as follows: 106 107 ``` 108 10 . 1 . 2 . ? 0 109 00001010 00000001 00000010 | XXXX | 0000 110 parent network | netnum | host 111 ``` 112 113 Four of the eight bits that were originally the "host number" are now being 114 repurposed as the subnet number. The network prefix no longer falls on an 115 exact octet boundary, so in effect we are now splitting the last decimal number 116 in the IP address into two parts, using half of it to represent the subnet 117 number and the other half to represent the host number. 118 119 The `netnum` argument then decides what number value to encode into those 120 four new subnet bits. In our current example we passed `15`, which is 121 represented in binary as `1111`, allowing us to fill in the `XXXX` segment 122 in the above: 123 124 ``` 125 10 . 1 . 2 . 15 0 126 00001010 00000001 00000010 | 1111 | 0000 127 parent network | netnum | host 128 ``` 129 130 To convert this back into normal decimal notation we need to recombine the 131 two portions of the final octet. Converting `11110000` from binary to decimal 132 gives 240, which can then be combined with our new prefix length of 28 to 133 produce the result `10.1.2.240/28`. Again we can pass this prefix string to 134 `ipcalc` to visualize it: 135 136 ``` 137 $ ipcalc 10.1.2.240/28 138 Address: 10.1.2.240 00001010.00000001.00000010.1111 0000 139 Netmask: 255.255.255.240 = 28 11111111.11111111.11111111.1111 0000 140 Wildcard: 0.0.0.15 00000000.00000000.00000000.0000 1111 141 => 142 Network: 10.1.2.240/28 00001010.00000001.00000010.1111 0000 143 HostMin: 10.1.2.241 00001010.00000001.00000010.1111 0001 144 HostMax: 10.1.2.254 00001010.00000001.00000010.1111 1110 145 Broadcast: 10.1.2.255 00001010.00000001.00000010.1111 1111 146 Hosts/Net: 14 Class A, Private Internet 147 ``` 148 149 The new subnet has four bits available for host numbering, which means 150 that there are 14 host addresses available for assignment once we subtract 151 the network's own address and the broadcast address. You can thus use 152 [`cidrhost`](./cidrhost.html) function to calculate those host addresses by 153 providing it a value between 1 and 14: 154 155 ``` 156 > cidrhost("10.1.2.240/28", 1) 157 10.1.2.241 158 > cidrhost("10.1.2.240/28", 14) 159 10.1.2.254 160 ``` 161 162 For more information on CIDR notation and subnetting, see 163 [Classless Inter-domain Routing](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing). 164 165 ## Related Functions 166 167 * [`cidrhost`](./cidrhost.html) calculates the IP address for a single host 168 within a given network address prefix. 169 * [`cidrnetmask`](./cidrnetmask.html) converts an IPv4 network prefix in CIDR 170 notation into netmask notation. 171 * [`cidrsubnets`](./cidrsubnets.html) can allocate multiple consecutive 172 addresses under a prefix at once, numbering them automatically.