Task 10: Configure Hostname
The automated OS configuration run covers this task in the Hostname step (the computer name equals the node name; a restart follows). Use the manual steps below when you can't use the run, or to understand or troubleshoot what it does. See how the run works.
DOCUMENT CATEGORY: Runbook SCOPE: Set the computer hostname for each node according to naming standards PURPOSE: Set the computer hostname for each node according to naming standards MASTER REFERENCE: Microsoft Learn - Install the Azure Local operating system (SConfig, computer name)
Status: Active
Overview
Rename each node to its target hostname from infrastructure.yml. Nodes must restart to apply the change.
- Do not use an underscore (
_) in the computer name. Learn: "Using an underscore (_) in the computer name is not supported, as it impacts storage path creation." - The computer name is the name shown in the Azure portal and, once joined, in Active Directory. Choose it now; it is not a cosmetic setting.
- Use a name that is unique in the domain and matches the node name in
infrastructure.ymland the Active Directory preparation (Phase 01).
Prerequisites
| Requirement | Details |
|---|---|
| Tasks 01–09 complete | Unused adapters disabled |
| Hostnames from infrastructure.yml | nodes[].name |
Config Reference
| YAML Key | Variable | Example |
|---|---|---|
nodes[].name | $NewHostname | azlocal-node01 |
nodes[].network_adapters[].ip_address | $ServerList / $node.ip | 10.0.0.11 |
Execution Options
- SConfig (Recommended)
- Orchestrated Script
Run on each node via console, KVM, or RDP. SConfig is the simplest method.
- At the PowerShell prompt, type
SConfigand press Enter - Select option 2 — Computer Name
- Type the hostname from
infrastructure.yml(nodes[].name) - Press Enter and confirm
- Select Yes to restart now
Repeat on each node.
PowerShell
No script in this task folder. The folder
scripts/deploy/04-cluster-deployment/phase-03-os-configuration/task-10-configure-hostnameholds only a placeholder. A placeholder printsNOT IMPLEMENTED, changes nothing and exits with code 3. The earlierSet-NodeHostname.ps1is removed. The OS configuration does this task in its Hostname step.
Script
| Script | What it does |
|---|---|
scripts/deploy/04-cluster-deployment/phase-03-os-configuration/Invoke-AzureLocalOsConfiguration.ps1 | The one entry point of the OS configuration. It runs Set-AzureLocalNodeConfiguration.ps1 for each node: it reads the node, changes only what differs from infrastructure.yml, and reports. -Step limits the run to one step. |
The nodes' local administrator comes from identity.local_admin of infrastructure.yml (the password is a secret reference), or from -Credential. The script never prompts. Run settings go in a JSON file given with -SettingsFile.
Run
# Plan (the default): read every node and list what would change
./Invoke-AzureLocalOsConfiguration.ps1 -InfrastructureFile ./infrastructure.yml -Step Hostname
# Apply
./Invoke-AzureLocalOsConfiguration.ps1 -InfrastructureFile ./infrastructure.yml -Step Hostname -Mode Apply
See how the run works.
Validation
# Confirm hostname on each node
$env:COMPUTERNAME
# or remotely:
Invoke-Command -ComputerName <ip> -ScriptBlock { $env:COMPUTERNAME }
Validation Checklist
- Each node reports the correct hostname
- All nodes accessible after restart
- Hostnames match
nodes[].namein infrastructure.yml - No hostname contains an underscore
Values from infrastructure.yml
The values for this task come from infrastructure.yml (schema 5). Every key, with its type, default and example, is in the variables reference.
Troubleshooting
| Issue | Resolution |
|---|---|
| Node didn't come back after restart | Wait another 60s then ping the management IP |
| Hostname not applied | Confirm Rename-Computer ran without error; restart if needed |
Hostname contains _ | Rename the node. An underscore in the computer name impacts storage path creation (Learn). |
Alternatives
The procedures in this task use the methods shown in the tabs above. The toolkit is PowerShell 7 only and has no Bash scripts. A few tasks that act on Azure also have an Azure CLI script written in PowerShell. The script status page of the toolkit lists which task has which script.
Navigation
← Task 09: Disable Adapters · ↑ Phase 03 · Task 11: Clear Storage →
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2025-03-25 | Azure Local Cloud | Initial release |
| 1.1.0 | 2026-11-08 | Azure Local Cloud | Aligned to Azure Local 2610: underscore not allowed in the computer name (impacts storage path creation); Learn master reference and platform badge updated |