az aks upgrade-insights

Note

This reference is part of the aks-preview extension for the Azure CLI (version 2.85.0 or higher). The extension will automatically install the first time you run an az aks upgrade-insights command. Learn more about extensions.

This command group is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Evaluate upgrade readiness and read stored insights for an AKS cluster.

These commands do not upgrade the cluster. By default, results are displayed as a human-readable report with issues nested under their control-plane or agent-pool scope. Use --output json for complete structured results. Explicit output settings and --query retain standard Azure CLI output behavior.

Commands

Name Description Type Status
az aks upgrade-insights create

Generate or refresh a stored upgrade readiness evaluation.

Extension Preview
az aks upgrade-insights list

List all stored upgrade insights for a cluster, including agent-pool and node-image insights.

Extension Preview
az aks upgrade-insights show

Read a stored upgrade insight without regenerating its evaluation.

Extension Preview

az aks upgrade-insights create

Preview

Command group 'aks upgrade-insights' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Generate or refresh a stored upgrade readiness evaluation.

This command does not upgrade the cluster. Displays a scope-nested readiness report by default. Use --output json for complete structured results; explicit output settings, core.output configuration, and --query retain standard Azure CLI formatting.

az aks upgrade-insights create --name
                               --resource-group
                               --target-kubernetes-ver
                               [--acquire-policy-token]
                               [--change-reference]
                               [--upgrade-type {ControlPlane, ControlPlaneAndAgentPools}]

Examples

Evaluate the control plane and all agent pools (the default upgrade type).

az aks upgrade-insights create -g MyResourceGroup --name MyCluster --target-kubernetes-ver 1.35.1

Evaluate only the control plane.

az aks upgrade-insights create -g MyResourceGroup --name MyCluster --upgrade-type ControlPlane --target-kubernetes-ver 1.35.1

Required Parameters

--name -n

The managed cluster name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--target-kubernetes-ver

The target Kubernetes version to evaluate. This command does not upgrade the cluster.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--upgrade-type

The upgrade scope to evaluate. Defaults to the control plane and all agent pools.

Property Value
Default value: ControlPlaneAndAgentPools
Accepted values: ControlPlane, ControlPlaneAndAgentPools
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az aks upgrade-insights list

Preview

Command group 'aks upgrade-insights' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

List all stored upgrade insights for a cluster, including agent-pool and node-image insights.

Displays insight names and issue summaries nested under each evaluated scope by default. Use --output json for complete structured results. This does not regenerate evaluations.

az aks upgrade-insights list --name
                             --resource-group

Examples

List insights with issue summaries nested under each evaluated scope.

az aks upgrade-insights list -g MyResourceGroup --name MyCluster

List complete structured insights.

az aks upgrade-insights list -g MyResourceGroup --name MyCluster --output json

Required Parameters

--name -n

The managed cluster name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az aks upgrade-insights show

Preview

Command group 'aks upgrade-insights' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Read a stored upgrade insight without regenerating its evaluation.

Displays issue messages, affected resources, and recommended actions under their evaluated scope by default. Use --output json for complete structured results.

az aks upgrade-insights show --insight-name
                             --name
                             --resource-group

Examples

Read an insight using its server-generated name.

az aks upgrade-insights show -g MyResourceGroup --name MyCluster --insight-name INSIGHT_NAME

Required Parameters

--insight-name

The stored insight name returned by create or list.

--name -n

The managed cluster name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False