Azure / Azure/azure-cli-extensions

[k8s-extension] 1.8.0 contains undocumented breaking changes: `az k8s-extension show` output shape and configurationSettings boolean serialization

Open
#10,238 1 comment 0 reactions 0 assignees View on GitHub
act-observability-squad AKS Auto-Assign bug Service Attention
Dominant language
Python
Stars
454
Forks
1.7k
Avg merge
2d 19h
Merged PRs (30d)
64

Description

### Describe the bug

k8s-extension **1.8.0** (PR #10045, merged 2026-07-17, wheel published 2026-07-17
14:12 UTC) migrated the `extensions` operations to api-version `2025-03-01`.

`HISTORY.rst` documents this only as:

> Migrate Extensions api-version to 2025-03-01 and bump extension version to 1.8.0.

Two customer-visible behavioral changes shipped with it that are not mentioned anywhere,
and that the repo's automated breaking-change check does not detect (it only flagged the
new `auto_upgrade_mode` parameter).

#### Change 1 — `az k8s-extension show` output is no longer flattened

The `2023-05-01` msrest model declared the properties flattened:

```python
"configuration_settings": {"key": "properties.configurationSettings", "type": "{str}"}
```

so the CLI emitted them at the top level. The `2025-03-01` TypeSpec model declares

```python
properties: Optional["_models.ExtensionProperties"] = rest_field(...)
```

so they are now emitted nested under `properties`.

**1.7.0**
```json
{ "configurationSettings": { ... }, "extensionType": "...", "provisioningState": "Succeeded" }
```

**1.8.0**
```json
{ "properties": { "configurationSettings": { ... }, "extensionType": "...", "provisioningState": "Succeeded" } }
```

Any script doing `az k8s-extension show ... --query configurationSettings` or parsing the
JSON breaks. Python attribute access still works (the model keeps `__flattened_items`
compat), so this only bites consumers of the **CLI output** — which makes it easy to miss
in Python-level testing.

#### Change 2 — boolean `configurationSettings` values are no longer stringified

`configuration_settings` was typed `{str}` under msrest, so a Python `bool` passed by a
caller was coerced via `str()`. The TypeSpec model passes the value through to
`json.dumps`.

```python
# 1.7.0
Serializer().serialize_data({"nvme.enabled": True}, "{str}")
# -> {'nvme.enabled': 'True'}

# 1.8.0
json.dumps(dict(ExtensionProperties(configuration_settings={"nvme.enabled": True})))
# -> {"configurationSettings": {"nvme.enabled": true}}
```

Values that used to round-trip as `"True"`/`"False"` now round-trip as `"true"`/`"false"`.
This silently broke `az aks` ACStor support, which compares them against `"True"`
(filed as a separate issue on `Azure/azure-cli`). Other partner extensions that write
booleans through this field are likely affected the same way.

### Related command

`az k8s-extension show`

### Errors

Any script doing az k8s-extension show ... --query configurationSettings or parsing the
JSON breaks. Python attribute access still works (the model keeps __flattened_items
compat), so this only bites consumers of the CLI output — which makes it easy to miss
in Python-level testing.

Values that used to round-trip as `"True"`/`"False"` now round-trip as `"true"`/`"false"`.
This silently broke `az aks` ACStor support, which compares them against `"True"`
(filed as a separate issue on `Azure/azure-cli`). Other partner extensions that write
booleans through this field are likely affected the same way.

### Issue script & Debug output

```bash
az extension add --name k8s-extension --version 1.7.0
az k8s-extension show -g --cluster-name \
--cluster-type managedClusters --name --query configurationSettings # works

az extension add --upgrade --name k8s-extension # 1.8.0
az k8s-extension show -g --cluster-name \
--cluster-type managedClusters --name --query configurationSettings # null
```

### Expected behavior

Either the output shape and value serialization are preserved across the api-version
migration, or the change is called out as a breaking change in `HISTORY.rst` with a
migration note, and the major/minor version bump reflects it.

#### Suggested actions

1. Document both changes in `HISTORY.rst` for 1.8.0.
2. Consider restoring the flattened top-level output shape in the command layer for
backwards compatibility (or emitting both).
3. Consider coercing `configuration_settings` values to `str` on the write path to
preserve the previous wire format.
4. Consider whether the breaking-change CI rules can cover response-shape changes, not
just command signatures.

### Environment Summary

```
k8s-extension 1.7.0 -> 1.8.0
azure-cli 2.74.0 / 2.86.0 (both reproduce)
```

### Additional context

_No response_

Contributor guide

Open the contributing guide

Research direction

Start with HISTORY.rst and PR #10045, then reproduce the 1.7.0 and 1.8.0 commands shown in the issue. Trace the k8s-extension command and model path responsible for the show output and configuration_settings serialization. Done means both breaking changes are documented with migration guidance, or compatibility behavior is restored and covered by tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
azure, python
Domain
cli, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.