Skip to content

Commit c8acbdf

Browse files
GijsreynGijsreyn
committed
Fix test and add reference documentation
1 parent 508ee68 commit c8acbdf

File tree

4 files changed

+732
-0
lines changed

4 files changed

+732
-0
lines changed

‎docs/reference/schemas/config/functions/cidrHost.md‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
---
2+
description: Reference for the 'cidrHost' DSC configuration document function
3+
ms.date: 11/03/2025
4+
ms.topic: reference
5+
title: cidrHost
6+
---
7+
8+
# cidrHost
9+
10+
## Synopsis
11+
12+
Calculates a host IP address within a CIDR network block.
13+
14+
## Syntax
15+
16+
```Syntax
17+
cidrHost(<cidrNotation>, <hostNumber>)
18+
```
19+
20+
## Description
21+
22+
The `cidrHost()` function calculates a specific host IP address within a given
23+
[CIDR][01] network block by adding a host number offset to the network address.
24+
This function is particularly useful for systematically assigning IP addresses
25+
to hosts, generating gateway addresses, or allocating IP addresses for network
26+
resources in infrastructure-as-code scenarios.
27+
28+
The host number is zero-indexed, where `0` represents the network address
29+
itself. For typical host assignments, start with `1` to get the first usable
30+
IP address in the network.
31+
32+
## Examples
33+
34+
### Example 1 - Calculate gateway address
35+
36+
Network configurations commonly use the first usable IP address as the gateway.
37+
This example calculates that address using host number `1`.
38+
39+
```yaml
40+
# cidrHost.example.1.dsc.config.yaml
41+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
42+
resources:
43+
- name: Gateway address
44+
type: Microsoft.DSC.Debug/Echo
45+
properties:
46+
output: "[cidrHost('10.0.1.0/24', 1)]"
47+
```
48+
49+
```bash
50+
dsc config get --file cidrHost.example.1.dsc.config.yaml
51+
```
52+
53+
```yaml
54+
results:
55+
- name: Gateway address
56+
type: Microsoft.DSC.Debug/Echo
57+
result:
58+
actualState:
59+
output: 10.0.1.1
60+
messages: []
61+
hadErrors: false
62+
```
63+
64+
### Example 2 - Assign multiple host addresses
65+
66+
This configuration demonstrates calculating host addresses for a subnet created
67+
with [`cidrSubnet()`][02], useful for assigning IP addresses to multiple servers
68+
or network devices.
69+
70+
```yaml
71+
# cidrHost.example.2.dsc.config.yaml
72+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
73+
parameters:
74+
baseNetwork:
75+
type: string
76+
defaultValue: 172.16.0.0/16
77+
subnetIndex:
78+
type: int
79+
defaultValue: 10
80+
resources:
81+
- name: Web server IPs
82+
type: Microsoft.DSC.Debug/Echo
83+
properties:
84+
output:
85+
subnet: "[cidrSubnet(parameters('baseNetwork'), 24, parameters('subnetIndex'))]"
86+
webServer1: "[cidrHost(cidrSubnet(parameters('baseNetwork'), 24, parameters('subnetIndex')), 10)]"
87+
webServer2: "[cidrHost(cidrSubnet(parameters('baseNetwork'), 24, parameters('subnetIndex')), 11)]"
88+
webServer3: "[cidrHost(cidrSubnet(parameters('baseNetwork'), 24, parameters('subnetIndex')), 12)]"
89+
```
90+
91+
```bash
92+
dsc config get --file cidrHost.example.2.dsc.config.yaml
93+
```
94+
95+
```yaml
96+
results:
97+
- name: Web server IPs
98+
type: Microsoft.DSC.Debug/Echo
99+
result:
100+
actualState:
101+
output:
102+
subnet: 172.16.10.0/24
103+
webServer1: 172.16.10.10
104+
webServer2: 172.16.10.11
105+
webServer3: 172.16.10.12
106+
messages: []
107+
hadErrors: false
108+
```
109+
110+
### Example 3 - Generate network device IPs with range
111+
112+
The configuration uses the [`range()`][03] function to generate IP addresses
113+
for multiple network devices systematically, demonstrating how to combine
114+
functions for dynamic IP allocation.
115+
116+
```yaml
117+
# cidrHost.example.3.dsc.config.yaml
118+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
119+
parameters:
120+
networkCidr:
121+
type: string
122+
defaultValue: 192.168.100.0/24
123+
startHost:
124+
type: int
125+
defaultValue: 20
126+
deviceCount:
127+
type: int
128+
defaultValue: 5
129+
resources:
130+
- name: Device IP allocation
131+
type: Microsoft.DSC.Debug/Echo
132+
properties:
133+
output:
134+
network: "[parameters('networkCidr')]"
135+
gateway: "[cidrHost(parameters('networkCidr'), 1)]"
136+
dnsServer: "[cidrHost(parameters('networkCidr'), 2)]"
137+
deviceIPs: "[map(range(parameters('startHost'), parameters('deviceCount')), 'i', cidrHost(parameters('networkCidr'), add(i, parameters('startHost'))))]"
138+
```
139+
140+
```bash
141+
dsc config get --file cidrHost.example.3.dsc.config.yaml
142+
```
143+
144+
```yaml
145+
results:
146+
- name: Device IP allocation
147+
type: Microsoft.DSC.Debug/Echo
148+
result:
149+
actualState:
150+
output:
151+
network: 192.168.100.0/24
152+
gateway: 192.168.100.1
153+
dnsServer: 192.168.100.2
154+
deviceIPs:
155+
- 192.168.100.20
156+
- 192.168.100.21
157+
- 192.168.100.22
158+
- 192.168.100.23
159+
- 192.168.100.24
160+
messages: []
161+
hadErrors: false
162+
```
163+
164+
## Parameters
165+
166+
### cidrNotation
167+
168+
The `cidrHost()` function expects the first parameter to be a string in valid
169+
CIDR notation format, including both an IP address and prefix length (e.g.,
170+
`10.0.0.0/16`).
171+
172+
```yaml
173+
Type: string
174+
Required: true
175+
MinimumCount: 1
176+
MaximumCount: 1
177+
```
178+
179+
### hostNumber
180+
181+
The second parameter specifies the host number offset from the network address.
182+
The value must be a non-negative integer within the valid range of the network.
183+
184+
- For a `/24` network (254 usable hosts), valid values are `0` to `255`
185+
- For a `/16` network (65,534 usable hosts), valid values are `0` to `65535`
186+
- Value `0` returns the network address itself
187+
- Value `1` typically returns the first usable host (often used for gateways)
188+
189+
The function raises an error if the host number exceeds the network capacity.
190+
191+
```yaml
192+
Type: integer
193+
Required: true
194+
MinimumCount: 1
195+
MaximumCount: 1
196+
```
197+
198+
## Output
199+
200+
The `cidrHost()` function returns a string containing the calculated IP address
201+
in standard notation (e.g., `10.0.1.15` for IPv4 or `2001:db8::a` for IPv6).
202+
203+
```yaml
204+
Type: string
205+
```
206+
207+
## Exceptions
208+
209+
The `cidrHost()` function raises errors for the following conditions:
210+
211+
- **Invalid CIDR notation**: When the CIDR string is malformed or missing the
212+
prefix length
213+
- **Host number out of range**: When the host number exceeds the maximum number
214+
of addresses in the network
215+
- **Invalid host number**: When the host number is negative
216+
217+
## Related functions
218+
219+
- [`cidrSubnet()`][02] - Creates a subnet from a larger CIDR block
220+
- [`parseCidr()`][04] - Parses CIDR notation and returns network details
221+
- [`range()`][03] - Generates a sequence of numbers
222+
- [`map()`][05] - Applies a function to each element in an array
223+
- [`parameters()`][06] - Retrieves parameter values
224+
225+
<!-- Link reference definitions -->
226+
[01]: https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing
227+
[02]: ./cidrSubnet.md
228+
[03]: ./range.md
229+
[04]: ./parseCidr.md
230+
[05]: ./map.md
231+
[06]: ./parameters.md

0 commit comments

Comments
 (0)