Skip to content

docs(azure): fix private cluster NAT subnet setup instructions #9209

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
bryan-cox wants to merge 1 commit into from
+34 −26
Closed

docs(azure): fix private cluster NAT subnet setup instructions #9209

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 17 additions & 13 deletions docs/content/how-to/azure/deploy-azure-private-clusters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,15 +57,19 @@ subnet must be in the **management cluster's VNet** and must have
HostedCluster's configured location. Azure will reject PLS creation if the NAT subnet
is in a different region.

First, identify the management cluster's VNet:
First, identify the management cluster's VNet. HyperShift may place the VNet in a
separate resource group from the infrastructure resource group, so the most reliable
method is to trace a worker node's network interface back to its VNet:

```bash
# Get the management cluster's infrastructure resource group
MGMT_INFRA_RG=$(oc get infrastructure cluster -o jsonpath='{.status.platformStatus.azure.resourceGroupName}')

# Find the VNet in the infrastructure resource group
MGMT_VNET_NAME=$(az network vnet list --resource-group "${MGMT_INFRA_RG}" --query "[0].name" -o tsv)
MGMT_VNET_RG="${MGMT_INFRA_RG}"
# Discover the VNet by tracing a VM's network interface
NIC_ID=$(az vm list -g "${MGMT_INFRA_RG}" --query '[0].networkProfile.networkInterfaces[0].id' -o tsv)
SUBNET_ID=$(az network nic show --ids "${NIC_ID}" --query 'ipConfigurations[0].subnet.id' -o tsv)
MGMT_VNET_RG=$(echo "${SUBNET_ID}" | cut -d'/' -f5)
MGMT_VNET_NAME=$(echo "${SUBNET_ID}" | cut -d'/' -f9)
Comment on lines +60 to +72

@coderabbitai coderabbitai Bot Aug 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

rg -n -C 4 \
  'az vm (list|show)|networkProfile\.networkInterfaces|VMSS|worker' \
  docs/content/how-to/azure \
  docs/content/reference/infrastructure

Repository: openshift/hypershift

Length of output: 18790

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

printf '%s\n' '--- document context ---'
sed -n '45,85p' docs/content/how-to/azure/deploy-azure-private-clusters.md

printf '%s\n' '--- Azure resource-group references ---'
rg -n -C 3 \
  'resourceGroupName|resource group|infrastructure resource group|management cluster' \
  docs/content/how-to/azure docs/content/reference/infrastructure \
  | head -n 240

printf '%s\n' '--- Markdown spelling check ---'
make verify-codespell

Repository: openshift/hypershift

Length of output: 24005

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

printf '%s\n' '--- Azure resource-group and VM implementation references ---'
rg -n -C 4 \
  'resourceGroupName|ResourceGroupName|networkInterfaces|VirtualMachine|worker.*VM|VM.*worker' \
  --glob '*.go' --glob '*.md' .

printf '%s\n' '--- Related deployment documentation ---'
sed -n '55,90p' docs/content/how-to/azure/create-infra-separately.md
sed -n '250,335p' docs/content/reference/infrastructure/azure-aro-hcp.md

printf '%s\n' '--- Azure CLI availability and local help sources ---'
command -v az || true
command -v make || true
git ls-files | rg '(^|/)(Makefile|makefile|GNUmakefile)$|azure.*(vm|network)|deploy-azure-private-clusters'

Repository: openshift/hypershift

Length of output: 50377

🌐 Web query:

Azure CLI az vm list query order resource group network profile networkInterfaces documented workflow select VM name

💡 Result:

To list Azure Virtual Machines (VMs) and include their associated network interface IDs using the Azure CLI, you can use the az vm list command combined with a JMESPath query [1][2]. Note that the basic az vm list command does not return detailed network profile information by default; you must use the --show-details flag to retrieve properties like network interfaces [3][2]. The following command retrieves a list of VMs, displaying their name, resource group, and the IDs of all attached network interfaces: az vm list --show-details --query "[].{VMName:name, ResourceGroup:resourceGroup, NetworkInterfaces:networkProfile.networkInterfaces[].id}" --output table Key components of this workflow: 1. --show-details: This flag is essential as it instructs the Azure CLI to fetch extended properties, including the networkProfile, which are not returned in the standard summary output [3][2]. 2. --query: The JMESPath query "[].{VMName:name, ResourceGroup:resourceGroup, NetworkInterfaces:networkProfile.networkInterfaces[].id}" performs the following actions: - [].: Flattens the array of VM objects so you can access individual VM properties [1][4]. - {VMName:name,...}: Creates a custom JSON object for each VM containing only the fields you requested [1][4]. - networkProfile.networkInterfaces[].id: Accesses the nested networkInterfaces array, flattens it, and extracts the unique ID for each NIC [2]. 3. Sorting/Ordering: The Azure CLI does not natively support an order-by parameter within the CLI command itself [1]. To order the output, you can pipe the result to standard command-line tools like sort. For example, to sort by the VM name: az vm list --show-details --query "[].{VMName:name, ResourceGroup:resourceGroup, NetworkInterfaces:networkProfile.networkInterfaces[].id}" --output tsv | sort -k1 If you require more granular information about specific network interfaces, you can use the retrieved IDs with the az network nic show command [2][5].

Citations:

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

printf '%s\n' '--- non-vendored Azure references ---'
rg -n -C 4 \
  'resourceGroupName|ResourceGroupName|networkInterfaces|VirtualMachine|worker.*VM|VM.*worker' \
  --glob '!vendor/**' --glob '*.go' --glob '*.md' .

printf '%s\n' '--- resource-group topology ---'
sed -n '55,85p' docs/content/how-to/azure/create-infra-separately.md
sed -n '275,335p' docs/content/reference/infrastructure/azure-aro-hcp.md

printf '%s\n' '--- tracked build and verification files ---'
git ls-files | rg '(^|/)(Makefile|makefile|GNUmakefile)$|azure.*(vm|network)|deploy-azure-private-clusters'

Repository: openshift/hypershift

Length of output: 50379

🌐 Web query:

site:learn.microsoft.com/en-us/cli/azure/vm az vm list --show-details networkProfile networkInterfaces

💡 Result:

The command az vm list --show-details networkProfile networkInterfaces is not a valid Azure CLI command syntax [1]. The az vm list command does not support networkProfile or networkInterfaces as positional arguments or flags [1]. Additionally, while az vm list has a --show-details parameter (which provides more comprehensive information about VMs, such as power state and hardware profile), it does not include granular network configuration details by default [1]. To retrieve network interface information for an Azure Virtual Machine, you should use the dedicated az vm nic command group. To list all network interfaces associated with a specific VM, use: az vm nic list --resource-group <resource-group> --vm-name <vm-name> [2] To display detailed information for a specific network interface attached to a VM, use: az vm nic show --resource-group <resource-group> --vm-name <vm-name> --nic <nic-name> [2] If your goal is to extract specific network profile data from the az vm list command, you can use the --query parameter with a JMESPath expression, though this is often more efficiently handled by querying the NIC resources directly [2].

Citations:

🏁 Script executed:

python3 - <<'PY'
import json

payload = {
    "vms": [
        {
            "name": "management-control-plane-0",
            "networkProfile": {
                "networkInterfaces": [{"id": "/nic/control-plane"}]
            },
        },
        {
            "name": "management-worker-0",
            "networkProfile": {
                "networkInterfaces": [{"id": "/nic/worker"}]
            },
        },
    ]
}

selected = payload["vms"][0]["networkProfile"]["networkInterfaces"][0]["id"]
print(json.dumps({
    "query": "[0].networkProfile.networkInterfaces[0].id",
    "selected_vm": payload["vms"][0]["name"],
    "selected_nic": selected,
    "worker_selected": payload["vms"][0]["name"].endswith("worker-0"),
}, indent=2))
PY

Repository: openshift/hypershift

Length of output: 333

Select a worker VM explicitly.

When the resource group contains multiple VMs, line 69 can select a non-worker VM because [0] has no worker filter. Use an explicit worker VM name, then query its NIC with az vm nic list or az vm nic show.

🧰 Tools
🪛 markdownlint-cli2 (0.23.1)

[warning] 64-64: Code block style
Expected: indented; Actual: fenced

(MD046, code-block-style)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/content/how-to/azure/deploy-azure-private-clusters.md` around lines 60 -
72, Update the management VNet discovery commands to select a worker VM
explicitly rather than relying on the unfiltered `[0]` result from `az vm list`.
Define or obtain the worker VM name, then use `az vm nic list` or `az vm nic
show` for that VM to populate `NIC_ID`, preserving the subsequent subnet and
VNet resource-group/name extraction.

```

Create the NAT subnet:
Expand All @@ -84,18 +88,18 @@ az network vnet subnet create \
--resource-group "${MGMT_VNET_RG}" \
--vnet-name "${MGMT_VNET_NAME}" \
--name "${NAT_SUBNET_NAME}" \
--address-prefixes 10.1.64.0/24 \
--address-prefixes 10.0.1.0/24 \
--disable-private-link-service-network-policies true
```

!!! warning "Choose a Non-Overlapping CIDR"

The `10.1.64.0/24` address prefix above is an **example only**. You must choose a
CIDR range that does not overlap with any existing subnets in the management cluster's
VNet. Check the VNet's address space and existing subnets before creating the NAT
subnet. If the management cluster's VNet uses `10.0.0.0/16`, the NAT subnet must
fall within that range (e.g., `10.0.64.0/24`) or you must first expand the VNet's
address space.
The `10.0.1.0/24` address prefix above works for the default `10.0.0.0/16` VNet
address space and does not overlap with the default node subnet (`10.0.0.0/24`).
You must choose a CIDR range that does not overlap with any existing subnets in
the management cluster's VNet. Check the VNet's address space and existing subnets
before creating the NAT subnet. If your VNet uses a different address space, adjust
the CIDR accordingly or first expand the VNet's address space.

Get the NAT subnet resource ID for later use:

Expand Down Expand Up @@ -421,8 +425,8 @@ The deletion process automatically cleans up Private Link resources in the corre
### NAT Subnet

- The NAT subnet CIDR (`--address-prefixes`) must fall within the management cluster's
VNet address space. If the VNet uses `10.0.0.0/16`, a NAT subnet of `10.1.64.0/24`
will fail unless you first expand the VNet address space.
VNet address space. For the default `10.0.0.0/16` VNet, `10.0.1.0/24` works without
overlapping the default node subnet (`10.0.0.0/24`).

- The `--disable-private-link-service-network-policies true` flag is **required** on
the NAT subnet. If omitted, Azure will reject PLS creation with an error about
Expand Down
30 changes: 17 additions & 13 deletions docs/content/reference/aggregated-docs.md
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading