ResiLien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
terraform/website/docs/language/functions/cidrsubnets.mdx

105 lines
3.5 KiB
Plaintext
Raw Normal View History

lang/funcs: cidrsubnets function This is a companion to cidrsubnet that allows bulk-allocation of multiple subnet addresses at once, with automatic numbering. Unlike cidrsubnet, cidrsubnets allows each of the allocations to have a different prefix length, and will pack the networks consecutively into the given address space. cidrsubnets can potentially create more complicated addressing schemes than cidrsubnet alone can, because it's able to take into account the full set of requested prefix lengths rather than just one at a time.
2019-09-20 04:06:15 +02:00
---
migrate docs to mdx
2021-12-15 03:41:17 +01:00
page_title: cidrsubnets - Functions - Configuration Language
lang/funcs: cidrsubnets function This is a companion to cidrsubnet that allows bulk-allocation of multiple subnet addresses at once, with automatic numbering. Unlike cidrsubnet, cidrsubnets allows each of the allocations to have a different prefix length, and will pack the networks consecutively into the given address space. cidrsubnets can potentially create more complicated addressing schemes than cidrsubnet alone can, because it's able to take into account the full set of requested prefix lengths rather than just one at a time.
2019-09-20 04:06:15 +02:00
description: |-
The cidrsubnets function calculates a sequence of consecutive IP address
ranges within a particular CIDR prefix.
---
website/docs: Corrects function name in `cidrsubnets` function documentation (#23473)
2019-11-26 13:50:32 +01:00
# `cidrsubnets` Function
lang/funcs: cidrsubnets function This is a companion to cidrsubnet that allows bulk-allocation of multiple subnet addresses at once, with automatic numbering. Unlike cidrsubnet, cidrsubnets allows each of the allocations to have a different prefix length, and will pack the networks consecutively into the given address space. cidrsubnets can potentially create more complicated addressing schemes than cidrsubnet alone can, because it's able to take into account the full set of requested prefix lengths rather than just one at a time.
2019-09-20 04:06:15 +02:00
website/docs: Corrects function name in `cidrsubnets` function documentation (#23473)
2019-11-26 13:50:32 +01:00
`cidrsubnets` calculates a sequence of consecutive IP address ranges within
lang/funcs: cidrsubnets function This is a companion to cidrsubnet that allows bulk-allocation of multiple subnet addresses at once, with automatic numbering. Unlike cidrsubnet, cidrsubnets allows each of the allocations to have a different prefix length, and will pack the networks consecutively into the given address space. cidrsubnets can potentially create more complicated addressing schemes than cidrsubnet alone can, because it's able to take into account the full set of requested prefix lengths rather than just one at a time.
2019-09-20 04:06:15 +02:00
a particular CIDR prefix.
```hcl
website/docs: Corrects function name in `cidrsubnets` function documentation (#23473)
2019-11-26 13:50:32 +01:00
cidrsubnets(prefix, newbits...)
lang/funcs: cidrsubnets function This is a companion to cidrsubnet that allows bulk-allocation of multiple subnet addresses at once, with automatic numbering. Unlike cidrsubnet, cidrsubnets allows each of the allocations to have a different prefix length, and will pack the networks consecutively into the given address space. cidrsubnets can potentially create more complicated addressing schemes than cidrsubnet alone can, because it's able to take into account the full set of requested prefix lengths rather than just one at a time.
2019-09-20 04:06:15 +02:00
```
`prefix` must be given in CIDR notation, as defined in
[RFC 4632 section 3.1](https://tools.ietf.org/html/rfc4632#section-3.1).
The remaining arguments, indicated as `newbits` above, each specify the number
of additional network prefix bits for one returned address range. The return
value is therefore a list with one element per `newbits` argument, each
a string containing an address range in CIDR notation.
For more information on IP addressing concepts, see the documentation for the
migrate docs to mdx
2021-12-15 03:41:17 +01:00
related function [`cidrsubnet`](/language/functions/cidrsubnet). `cidrsubnet` calculates
lang/funcs: cidrsubnets function This is a companion to cidrsubnet that allows bulk-allocation of multiple subnet addresses at once, with automatic numbering. Unlike cidrsubnet, cidrsubnets allows each of the allocations to have a different prefix length, and will pack the networks consecutively into the given address space. cidrsubnets can potentially create more complicated addressing schemes than cidrsubnet alone can, because it's able to take into account the full set of requested prefix lengths rather than just one at a time.
2019-09-20 04:06:15 +02:00
a single subnet address within a prefix while allowing you to specify its
subnet number, while `cidrsubnets` can calculate many at once, potentially of
different sizes, and assigns subnet numbers automatically.
When using this function to partition an address space as part of a network
address plan, you must not change any of the existing arguments once network
addresses have been assigned to real infrastructure, or else later address
assignments will be invalidated. However, you _can_ append new arguments to
existing calls safely, as long as there is sufficient address space available.
This function accepts both IPv6 and IPv4 prefixes, and the result always uses
the same addressing scheme as the given prefix.
lang/funcs: Preserve IP address leading zero behavior from Go 1.16 Go 1.17 includes a breaking change to both net.ParseIP and net.ParseCIDR functions to reject IPv4 address octets written with leading zeros. Our use of these functions as part of the various CIDR functions in the Terraform language doesn't have the same security concerns that the Go team had in evaluating this change to the standard library, and so we can't justify an exception to our v1.0 compatibility promises on the same sort of security grounds that the Go team used to justify their compatibility exception. For that reason, we'll now use our own fork of the Go library functions which has the new check disabled in order to preserve the prior behavior. We're taking this path, rather than pre-normalizing the IP address before calling into the standard library, because an additional normalization layer would be entirely new code and additional complexity, whereas this fork is relatively minor in terms of code size and avoids any significant changes to our own calls to these functions. Thanks to the Kubernetes team for their prior work on carving out a subset of the "net" package for their similar backward-compatibility concern. Our "ipaddr" package here is a lightly-modified fork of their fork, with only the comments changed to talk about Terraform instead of Kubernetes. This fork is not intended for use in any other future feature implementations, because they wouldn't be subject to the same compatibility constraints as our existing functions. We will use these forked implementations for new callers only if consistency with the behavior of the existing functions is a key requirement.
2021-08-17 20:30:18 +02:00
-> **Note:** As a historical accident, this function interprets IPv4 address
octets that have leading zeros as decimal numbers, which is contrary to some
other systems which interpret them as octal. We have preserved this behavior
for backward compatibility, but recommend against relying on this behavior.
website: Link to hashicorp/subnets/cidr for cidrsubnets docs The cidrsubnets function signature is intentionally very low-level and focused on the core requirement of generating addresses. This registry module then wraps it with some additional functionality to make it more convenient to generate and use subnet address ranges.
2019-09-21 03:00:07 +02:00
-> **Note:** [The Terraform module `hashicorp/subnets/cidr`](https://registry.terraform.io/modules/hashicorp/subnets/cidr)
wraps `cidrsubnets` to provide additional functionality for assigning symbolic
names to your networks and skipping prefixes for obsolete allocations. Its
documentation includes usage examples for several popular cloud virtual network
platforms.
lang/funcs: cidrsubnets function This is a companion to cidrsubnet that allows bulk-allocation of multiple subnet addresses at once, with automatic numbering. Unlike cidrsubnet, cidrsubnets allows each of the allocations to have a different prefix length, and will pack the networks consecutively into the given address space. cidrsubnets can potentially create more complicated addressing schemes than cidrsubnet alone can, because it's able to take into account the full set of requested prefix lengths rather than just one at a time.
2019-09-20 04:06:15 +02:00
## Examples
```
> cidrsubnets("10.1.0.0/16", 4, 4, 8, 4)
[
"10.1.0.0/20",
"10.1.16.0/20",
"10.1.32.0/24",
"10.1.48.0/20",
]
> cidrsubnets("fd00:fd12:3456:7890::/56", 16, 16, 16, 32)
[
"fd00:fd12:3456:7800::/72",
"fd00:fd12:3456:7800:100::/72",
"fd00:fd12:3456:7800:200::/72",
"fd00:fd12:3456:7800:300::/88",
]
```
You can use nested `cidrsubnets` calls with
migrate docs to mdx
2021-12-15 03:41:17 +01:00
[`for` expressions](/language/expressions/for)
lang/funcs: cidrsubnets function This is a companion to cidrsubnet that allows bulk-allocation of multiple subnet addresses at once, with automatic numbering. Unlike cidrsubnet, cidrsubnets allows each of the allocations to have a different prefix length, and will pack the networks consecutively into the given address space. cidrsubnets can potentially create more complicated addressing schemes than cidrsubnet alone can, because it's able to take into account the full set of requested prefix lengths rather than just one at a time.
2019-09-20 04:06:15 +02:00
to concisely allocate groups of network address blocks:
```
> [for cidr_block in cidrsubnets("10.0.0.0/8", 8, 8, 8, 8) : cidrsubnets(cidr_block, 4, 4)]
[
[
"10.0.0.0/20",
"10.0.16.0/20",
],
[
"10.1.0.0/20",
"10.1.16.0/20",
],
[
"10.2.0.0/20",
"10.2.16.0/20",
],
[
"10.3.0.0/20",
"10.3.16.0/20",
],
]
```
## Related Functions
migrate docs to mdx
2021-12-15 03:41:17 +01:00
* [`cidrhost`](/language/functions/cidrhost) calculates the IP address for a single host
lang/funcs: cidrsubnets function This is a companion to cidrsubnet that allows bulk-allocation of multiple subnet addresses at once, with automatic numbering. Unlike cidrsubnet, cidrsubnets allows each of the allocations to have a different prefix length, and will pack the networks consecutively into the given address space. cidrsubnets can potentially create more complicated addressing schemes than cidrsubnet alone can, because it's able to take into account the full set of requested prefix lengths rather than just one at a time.
2019-09-20 04:06:15 +02:00
within a given network address prefix.
migrate docs to mdx
2021-12-15 03:41:17 +01:00
* [`cidrnetmask`](/language/functions/cidrnetmask) converts an IPv4 network prefix in CIDR
lang/funcs: cidrsubnets function This is a companion to cidrsubnet that allows bulk-allocation of multiple subnet addresses at once, with automatic numbering. Unlike cidrsubnet, cidrsubnets allows each of the allocations to have a different prefix length, and will pack the networks consecutively into the given address space. cidrsubnets can potentially create more complicated addressing schemes than cidrsubnet alone can, because it's able to take into account the full set of requested prefix lengths rather than just one at a time.
2019-09-20 04:06:15 +02:00
notation into netmask notation.
migrate docs to mdx
2021-12-15 03:41:17 +01:00
* [`cidrsubnet`](/language/functions/cidrsubnet) calculates a single subnet address, allowing
lang/funcs: cidrsubnets function This is a companion to cidrsubnet that allows bulk-allocation of multiple subnet addresses at once, with automatic numbering. Unlike cidrsubnet, cidrsubnets allows each of the allocations to have a different prefix length, and will pack the networks consecutively into the given address space. cidrsubnets can potentially create more complicated addressing schemes than cidrsubnet alone can, because it's able to take into account the full set of requested prefix lengths rather than just one at a time.
2019-09-20 04:06:15 +02:00
you to specify its network number.