Azure / Azure/azure-cli-extensions
[k8s-extension] 1.8.0 contains undocumented breaking changes: `az k8s-extension show` output shape and configurationSettings boolean serialization
- 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
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