aks: support BYO VNet for Automatic Managed System Pool clusters by wenhug · Pull Request #33259 · Azure/azure-cli

wenhug · 2026-04-23T22:32:30Z

Summary

Adds core az aks create support for Automatic SKU Managed System Pool BYO VNet, plus fixes follow-up AKS commands against clusters whose server-side agentPoolProfiles is null.

New az aks create flags:

--system-node-subnet-id
--node-subnet-id
--enable-hosted-system

Behavior:

--enable-hosted-system is valid only with --sku automatic. It sets hostedSystemProfile.enabled=true and skips synthesizing the CLI default agentPoolProfiles, because the RP provisions the Managed System Pool server-side.
BYO VNet is implied when --system-node-subnet-id, --node-subnet-id, and the existing --apiserver-subnet-id are supplied together on --sku automatic.
BYO VNet populates hostedSystemProfile.systemNodeSubnetID, hostedSystemProfile.nodeSubnetID, and apiServerAccessProfile.subnetId; it also sets apiServerAccessProfile.enableVnetIntegration=true.
BYO VNet defaults to loadBalancer outbound instead of the normal Automatic no-VNet managedNATGateway default. BYO subnets also satisfy the VNet requirement for userAssignedNATGateway and userDefinedRouting; managedNATGateway is rejected with BYO/custom VNet input.
The CLI grants Network Contributor on all BYO subnets for service-principal/user-assigned identity creates, and defers the grants for system-assigned identity creates until the cluster identity exists.
az aks upgrade, az aks scale, and az aks update now handle Managed System Pool clusters with agentPoolProfiles=null; update also preserves the existing outbound type instead of reapplying the Automatic create default.

Validation:

Partial BYO trio -> RequiredArgumentMissingError listing missing flags.
BYO trio without --sku automatic -> RequiredArgumentMissingError.
--enable-hosted-system without --sku automatic -> RequiredArgumentMissingError.

Test plan

… crash Add --system-node-subnet-id, --node-subnet-id, --disable-hosted-system to 'az aks create'. When the subnet trio (system-node, node, apiserver) is supplied on --sku automatic, the cluster is created with an MC hosted_system_profile carrying BYO subnets; the Enabled flag is left unset so the server decides the default. --disable-hosted-system deterministically opts an Automatic cluster out of HOBO. Validate the BYO VNet trio up front: - Partial trio -> RequiredArgumentMissingError listing missing flags. - Trio without --sku automatic -> RequiredArgumentMissingError. - --disable-hosted-system + any subnet flag -> MutuallyExclusiveArgumentError. - --disable-hosted-system without --sku automatic -> RequiredArgumentMissingError. Fix 'az aks upgrade' / 'az aks scale' crash on HOBO clusters where agent_pool_profiles can be None server-side ('NoneType is not iterable'). Signed-off-by: wenhug <50309350+wenhug@users.noreply.github.com>

azure-client-tools-bot-prd · 2026-04-23T22:32:33Z

Validation for Azure CLI Full Test Starting...

Thanks for your contribution!

azure-client-tools-bot-prd · 2026-04-23T22:32:36Z

Hi @wenhug,
Since the current milestone time is less than 7 days, this pr will be reviewed in the next milestone.

azure-client-tools-bot-prd · 2026-04-23T22:32:39Z

Validation for Breaking Change Starting...

Thanks for your contribution!

yonzhan · 2026-04-23T22:32:39Z

Thank you for your contribution! We will review the pull request and get back to you soon.

github-actions · 2026-04-23T22:32:41Z

The git hooks are available for azure-cli and azure-cli-extensions repos. They could help you run required checks before creating the PR.

Please sync the latest code with latest dev branch (for azure-cli) or main branch (for azure-cli-extensions).
After that please run the following commands to enable git hooks:

pip install azdev --upgrade
azdev setup -c <your azure-cli repo path> -r <your azure-cli-extensions repo path>

Signed-off-by: wenhug <50309350+wenhug@users.noreply.github.com>

Copilot

Pull request overview

Adds CLI support for BYO VNet on AKS Automatic SKU (HOBO) clusters via new az aks create flags, and hardens az aks upgrade against RP responses where agentPoolProfiles is null.

Changes:

Introduce --system-node-subnet-id/--sys-node-subnet-id, --node-subnet-id, and --disable-hosted-system for az aks create, plus validation and request shaping via hosted_system_profile.
Update help/params/validators to expose and validate the new subnet arguments.
Prevent az aks upgrade from crashing when instance.agent_pool_profiles is None.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`src/azure-cli/azure/cli/command_modules/acs/managed_cluster_decorator.py`	Adds new context getters, validation, and `hosted_system_profile` setup during create flow.
`src/azure-cli/azure/cli/command_modules/acs/custom.py`	Adds new `aks_create` parameters and guards `aks_upgrade` iterations over `agent_pool_profiles`.
`src/azure-cli/azure/cli/command_modules/acs/_validators.py`	Adds subnet ID validators for the new flags.
`src/azure-cli/azure/cli/command_modules/acs/_params.py`	Wires new flags into `aks create` argument registration.
`src/azure-cli/azure/cli/command_modules/acs/_help.py`	Documents the new create flags and intended usage.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

* Simplify --system-node-subnet-id registration (drop the --sys-node-subnet-id alias so the linter picks up help correctly). * Relax _get_apiserver_subnet_id CREATE-time check: don't require --vnet-subnet-id when BYO HOBO subnets are set, since system-node/node subnets replace vnet-subnet-id on --sku automatic. * Run _validate_byo_hobo_subnets up front in set_up_api_server_access_profile so the targeted "require --sku automatic" error beats the generic --apiserver-subnet-id messaging. * Also fix aks_scale against HOBO clusters where agent_pool_profiles is None (same crash Qizhe hit with aks_upgrade): guard with `or []` and return a user-friendly error for empty pools. * Add linter_exclusions entries for the three new parameters (missing_parameter_test_coverage) to keep azdev-linter green without recorded scenario tests at this stage. Signed-off-by: wenhug <50309350+wenhug@users.noreply.github.com>

When customers pass --system-node-subnet-id / --node-subnet-id / --apiserver-subnet-id on --sku automatic to bring their own VNet for HOBO, the CLI was producing a payload the RP rejected: 1. apiServerAccessProfile.enableVnetIntegration was not set, so the RP treated the cluster as default-VNet while subnetId was populated and returned ApiserverSubnetConfigError. Auto-wire enable_vnet_integration whenever the BYO HOBO subnet trio is present. 2. hostedSystemProfile.enabled was left unset, so the RP could not distinguish BYO HOBO from default mode. Set enabled=True when the subnet trio is provided. 3. agentPoolProfiles contained the default system pool, which the RP rejected because HOBO manages node pools itself. Clear agent_pool_profiles in BYO HOBO mode, matching the preview path. 4. outbound_type defaulted to managedNATGateway for Automatic SKU, which the RP disallows on BYO VNet. Keep the user's explicit value (or let it default to loadBalancer) when the BYO trio is provided. Signed-off-by: wenhug <50309350+wenhug@users.noreply.github.com>

HOBO (Automatic SKU Hosted Overlay System Pool) clusters have agent_pool_profiles=null on the RP side because node pools are server-managed. update_agentpool_profile was raising 'Encounter an unexpected error while getting agent pool profiles...' on any 'az aks update' against a HOBO cluster (including 'az aks update --sku base' for Automatic-to-Base downgrade). Skip that step when hostedSystemProfile.enabled is true. Also refines the Automatic-SKU outbound-type override: keep the existing 'default to ManagedNATGateway when no user value and no vnet subnet' behavior unchanged; the BYO-HOBO exemption added in the prior commit is already enough. Signed-off-by: wenhug <50309350+wenhug@users.noreply.github.com>

Address Copilot review feedback on PR Azure#33259: - Clarify _validate_byo_hobo_subnets docstring: BYO VNet HOBO is triggered only by --system-node-subnet-id / --node-subnet-id. --apiserver-subnet-id keeps its existing general-purpose meaning for --enable-apiserver-vnet-integration flows on non-HOBO clusters, so it is deliberately not part of the trigger or the mutual-exclusion set. - Remove the unused 'any_trio_set' placeholder variable. Signed-off-by: wenhug <50309350+wenhug@users.noreply.github.com>

Fix pylint W0212 (protected-access) reported by CI: the validator is called across classes (AKSManagedClusterCreateDecorator accessing AKSManagedClusterContext), so it should be a public method. Signed-off-by: wenhug <50309350+wenhug@users.noreply.github.com>

Docstring still described the earlier 'enabled left unset' behavior, but the code now sets enabled=True on BYO VNet HOBO trio (required so the RP treats the request as BYO rather than default-VNet mode) and clears agent_pool_profiles because HOBO manages node pools server-side. Signed-off-by: wenhug <50309350+wenhug@users.noreply.github.com>

Per review feedback: - Remove --disable-hosted-system flag entirely (PM decision). - Rename user-visible HOBO / Hosted Overlay System Pool terminology to Managed System Pool for Automatic cluster. - Drop associated getter, validator branch, param, linter exclusion, and related test cases. Signed-off-by: wenhug <50309350+wenhug@users.noreply.github.com>

Rework short/long summaries for --system-node-subnet-id and --node-subnet-id so each flag clearly explains which pool it maps to (Managed System Pool vs user node pools) and states that the full three-subnet trio (including --apiserver-subnet-id) must belong to the same VNet and requires --sku automatic. Signed-off-by: wenhug <50309350+wenhug@users.noreply.github.com>

…eset - Rewrite --system-node-subnet-id and --node-subnet-id short summaries to follow the 'The ID of a subnet in an existing VNet to be used by ...' style already used for --vnet-subnet-id. - Rewrite the comment above the BYO-path 'agent_pool_profiles = None' assignment to explain the real reason: on an Automatic cluster with BYO VNet, the RP provisions the system pool from hosted_system_profile, so the CLI-synthesized default agent pool entry conflicts with the BYO trio and must be cleared. Signed-off-by: wenhug <50309350+wenhug@users.noreply.github.com>

Give power users an explicit way to request a Managed System Pool on Automatic SKU clusters, independent of the region-level default toggle. - `--enable-hosted-system` sets `hosted_system_profile.enabled=True` and clears the CLI-synthesized default agent pool. This avoids the ghost-pool problem on non-BYO Automatic clusters in toggle-ON regions where the RP auto-enables HOBO but the CLI still ships a default pool. - The BYO VNet subnet trio implies `--enable-hosted-system`, so existing BYO flows keep working unchanged. - `--enable-hosted-system` is gated to `--sku automatic`. Signed-off-by: wenhug <50309350+wenhug@users.noreply.github.com>

Signed-off-by: wenhug <50309350+wenhug@users.noreply.github.com>

Copilot AI review requested due to automatic review settings April 23, 2026 22:32

wenhug requested review from FumingZhang, NoriZC, teresaritorto and yanzhudd as code owners April 23, 2026 22:32

azure-client-tools-bot-prd Bot added this to the June 2026 (2026-06-02) milestone Apr 23, 2026

Copilot started reviewing on behalf of wenhug April 23, 2026 22:34 View session

microsoft-github-policy-service Bot requested review from yonzhan and zhoxing-ms April 23, 2026 22:34

microsoft-github-policy-service Bot assigned yanzhudd and zhoxing-ms Apr 23, 2026

microsoft-github-policy-service Bot added Auto-Assign Auto assign by bot AKS az aks/acs/openshift act-observability-squad labels Apr 23, 2026

test: add unit tests for BYO HOBO validator

997ac9c

Signed-off-by: wenhug <50309350+wenhug@users.noreply.github.com>

Copilot AI reviewed Apr 23, 2026

View reviewed changes

yonzhan unassigned zhoxing-ms Apr 23, 2026

wenhug added 5 commits April 23, 2026 23:38

zqingqing1 reviewed Apr 24, 2026

View reviewed changes

Comment thread src/azure-cli/azure/cli/command_modules/acs/_help.py Outdated

zqingqing1 reviewed Apr 24, 2026

View reviewed changes

Comment thread src/azure-cli/azure/cli/command_modules/acs/_help.py Outdated

zqingqing1 reviewed Apr 24, 2026

View reviewed changes

wenhug added 7 commits April 24, 2026 05:04

aks: grant BYO hosted-system subnet permissions

6aa0aa3

Signed-off-by: wenhug <50309350+wenhug@users.noreply.github.com>

aks: preserve outbound type when updating hosted-system clusters

75b0357

Signed-off-by: wenhug <50309350+wenhug@users.noreply.github.com>

aks: align BYO subnet outbound validation

fb312fc

Signed-off-by: wenhug <50309350+wenhug@users.noreply.github.com>

wenhug changed the title ~~aks: BYO VNet support for Automatic SKU HOBO clusters + fix upgrade crash~~ aks: support BYO VNet for Automatic Managed System Pool clusters Apr 24, 2026

zqingqing1 reviewed Apr 24, 2026

View reviewed changes

Comment thread src/azure-cli/azure/cli/command_modules/acs/managed_cluster_decorator.py Outdated

Comment thread src/azure-cli/azure/cli/command_modules/acs/managed_cluster_decorator.py

wenhug added 4 commits April 24, 2026 23:36

aks: refine hosted-system agent pool handling

0ed79d8

Signed-off-by: wenhug <50309350+wenhug@users.noreply.github.com>

aks: track CLI default pool before hosted-system removal

7fd3c16

Signed-off-by: wenhug <50309350+wenhug@users.noreply.github.com>

aks: skip default agent pool for hosted-system create

717c22f

Signed-off-by: wenhug <50309350+wenhug@users.noreply.github.com>

aks: remove hosted system hobo wording

b9553b7

zqingqing1 reviewed Apr 25, 2026

View reviewed changes

Comment thread src/azure-cli/azure/cli/command_modules/acs/managed_cluster_decorator.py

Comment thread src/azure-cli/azure/cli/command_modules/acs/managed_cluster_decorator.py Outdated

aks: clarify automatic outbound subnet errors

4417e80

zqingqing1 approved these changes Apr 25, 2026

View reviewed changes

Conversation

wenhug commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

azure-client-tools-bot-prd Bot commented Apr 23, 2026

Uh oh!

azure-client-tools-bot-prd Bot commented Apr 23, 2026

Uh oh!

azure-client-tools-bot-prd Bot commented Apr 23, 2026

Uh oh!

yonzhan commented Apr 23, 2026

Uh oh!

github-actions Bot commented Apr 23, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

wenhug commented Apr 23, 2026 •

edited

Loading