[Reference feedback]: Ambiguous phrasing for --network-plugin-mode

[johananl]

Type of issue

Other (describe below)

Reference command name

az aks create

Feedback

The following phrasing in the description of --network-plugin-mode is ambiguous:

If not specified with "azure" as network plugin, pods are given routable IPs from VNET.

I'm not sure which of the following is correct:

1. When --network-plugin is azure and --network-plugin-mode is omitted, pods are given routable IPs from VNET.
2. When --network-plugin-mode is specified and --network-plugin is not azure, pods are given routable IPs from VNET.

Page URL

https://learn.microsoft.com/en-us/cli/azure/aks?view=azure-cli-latest#az-aks-create

Content source URL

https://github.com/MicrosoftDocs/azure-docs-cli/blob/main/docs-ref-autogen/Latest-version/latest/aks.yml

Author

@mikefrobbins

Document Id

218b75bf-f010-bd7f-d783-257a4b70af4d

[yonzhan]

Thank you for opening this issue, we will look into it.

[johananl]

Another point:

The flag description says that the default value is overlay, however this doc makes it sound like the default isn't overlay:

Make sure to use the argument --network-plugin-mode to specify an overlay cluster.

I think we can improve the clarity here.

[johananl]

IIUC, the core idea is that the default AKS behavior is VNET IPs (for backward compatibility) and that overlay mode is opt-in. If that's correct, I suggest the following:

Change

If not specified with "azure" as network plugin, pods are given routable IPs from VNET.

to

When using "azure" as network plugin without specifying a mode, pods are given routable IPs from VNET.

and remove

Defaults to "overlay".

since this statement is incorrect.

Lastly, I'm not clear on whether --network-plugin-mode is applicable to --network-plugin=azure only. If so, I suggest we clarity if explicitly. If not, I suggest we explain the behavior of this flag with other network plugins.

[chasewilson]

Thanks for raising this. The behavior itself is correct, but I agree the documentation could be clearer about how the defaults are applied.

The key point is that the default depends on whether --network-plugin is explicitly set:

• If --network-plugin is not specified, AKS defaults to azure with overlay mode.
• If --network-plugin=azure is specified without --network-plugin-mode, AKS intentionally uses the VNET (node subnet) mode for backward compatibility.

Because of that distinction, overlay is the default only in the first case. When azure is explicitly specified, the behavior is different by design.

I’ll update the Overlay documentation to make this distinction clearer and to explicitly call out that --network-plugin-mode applies only when --network-plugin=azure.

[mbifeld]

Thanks @chasewilson! I see the documentation at https://learn.microsoft.com/en-us/azure/aks/azure-cni-overlay?tabs=kubectl&pivots=aks-cni-overlay-cluster#key-parameters-for-azure-cni-overlay-aks-clusters has been updated. Closing this issue.

[johananl]

Looks clearer now. Thanks a lot for addressing this! 🙏