[New Extension] Add chaos extension (Microsoft.Chaos 2026-05-01-preview)

src/chaos/HISTORY.rst

@@ -0,0 +1,38 @@
+.. :changelog:
+
+Release History
+===============
+
+1.0.0b1
++++++++
+* Initial preview release of the ``chaos`` extension. Targets api-version
+  ``2026-05-01-preview`` of ``Microsoft.Chaos``.
+
+  Command surface:
+
+  * ``az chaos workspace`` -- ``create``, ``show``, ``list``, ``update``,
+    ``delete``, ``refresh-recommendation``, ``evaluate-scenarios``,
+    ``show-discovery``, ``show-evaluation``, ``identity`` subgroup.
+  * ``az chaos scenario`` -- ``create``, ``show``, ``list``, ``update``,
+    ``delete``.
+  * ``az chaos scenario config`` -- ``create``, ``show``, ``list``,
+    ``update``, ``delete``, ``validate``, ``fix-permissions``, ``execute``,
+    ``show-validation``, ``show-permission-fix``.
+  * ``az chaos scenario run`` -- ``start``, ``show``, ``list``, ``cancel``,
+    ``wait``.
+  * ``az chaos discovered-resource`` -- ``show``, ``list``.
+
+  Notable hand-written commands beyond the spec-derived surface:
+
+  * ``scenario run start`` (porcelain composite of validate + execute with
+    a satisfied evaluation gate).
+  * ``workspace refresh-recommendation`` / ``evaluate-scenarios`` --
+    AAZ subclass override that adds inner-LRO failure detection
+    (``discoveries/latest`` + ``evaluations/latest`` ``properties.status``
+    inspection) on top of the AAZ-generated outer-LRO polling. Surfaces
+    the silent-failure case (e.g. Azure Resource Graph propagation lag
+    after a fresh Reader role assignment) that the AAZ framework polling
+    alone misses.
+  * ``workspace show-discovery``, ``workspace show-evaluation``,
+    ``scenario config show-validation``, ``scenario config show-permission-fix``
+    -- singleton-latest GETs not exposed by the spec.

src/chaos/README.md

@@ -0,0 +1,91 @@
+# Microsoft Azure CLI 'chaos' Extension
+
+Azure CLI extension for Azure Chaos Studio v2 Workspaces.
+
+Provides the `az chaos` command group for workspace lifecycle management,
+scenario browsing, scenario configuration with validation and execution,
+and run history with per-run cancellation.
+
+## Installation
+
+```bash
+az extension add --name chaos
+```
+
+## Usage
+
+```bash
+# Create a workspace with a system-assigned managed identity
+az chaos workspace create -g MyRG --workspace-name my-workspace --location eastus \
+    --system-assigned "" \
+    --scopes "/subscriptions/<sub-id>/resourceGroups/MyRG"
+
+# Create a workspace with a user-assigned managed identity
+az chaos workspace create -g MyRG --workspace-name my-workspace --location eastus \
+    --mi-user-assigned "/subscriptions/<sub-id>/resourceGroups/MyRG/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId" \
+    --scopes "/subscriptions/<sub-id>/resourceGroups/MyRG"
+
+# List workspaces
+az chaos workspace list
+az chaos workspace list -g MyRG
+
+# List scenarios
+az chaos scenario list -g MyRG --workspace-name my-workspace
+
+# Create a scenario configuration (--scenario-id is auto-derived)
+az chaos scenario config create -g MyRG --workspace-name my-workspace \
+    --scenario-name ZoneDown-1.0 -n my-config \
+    --parameters "[{key:duration,value:PT10M}]" \
+    --filters "{locations:[westus2],zones:[1]}"
+
+# Validate a scenario configuration
+az chaos scenario config validate -g MyRG --workspace-name my-workspace \
+    --scenario-name ZoneDown-1.0 -n my-config
+
+# Fix resource permissions
+az chaos scenario config fix-permissions -g MyRG --workspace-name my-workspace \
+    --scenario-name ZoneDown-1.0 -n my-config
+
+# Start a run
+az chaos scenario run start -g MyRG --workspace-name my-workspace \
+    --scenario-name ZoneDown-1.0 --config-name my-config
+
+# Show run status
+az chaos scenario run show -g MyRG --workspace-name my-workspace \
+    --scenario-name ZoneDown-1.0 --run-id <id>
+
+# List runs
+az chaos scenario run list -g MyRG --workspace-name my-workspace \
+    --scenario-name ZoneDown-1.0
+```
+
+For full documentation, see the [Azure Chaos Studio CLI reference](https://learn.microsoft.com/azure/chaos-studio/).
+
+## Modifying the AAZ-generated code
+
+**NEVER edit files under `azext_chaos/aaz/`.** They are generated by `aaz-dev` from
+the pinned spec and overwritten on every regen. The regression test
+`tests/latest/test_aaz_pristine.py` fails any PR that hand-edits `pre_operations`
+or `post_operations` bodies inside `aaz/`.
+
+To customize:
+
+- **Arg aliases, command renames, help text, examples** → edit
+  `automation/cli-extension/scripts/customize_workspace.py` (the workspace
+  customization driver), then run
+  `automation/cli-extension/scripts/regen.cmd` to regenerate the
+  `azext_chaos/aaz/` tree. The pinned spec + commit SHA are recorded in
+  `automation/cli-extension/aaz-models/chaos/CODEGEN_SOURCE.md`.
+- **`pre_operations` / `post_operations` hooks, computed args, derived defaults**
+  → subclass the generated class in `azext_chaos/custom.py` and register the
+  subclass in `azext_chaos/commands.py` via
+  `self.command_table["<full command name>"] = MySubclass(loader=self)`.
+  Existing examples: `ScenarioConfigCreate` (auto-derives `--scenario-id`).
+- **New commands not in the spec** → write them in `azext_chaos/custom.py`
+  (regular Python functions wired with `g.custom_command(...)`) or, for full
+  AAZ-shaped commands, a sibling module like `azext_chaos/custom_wait.py` using
+  `@register_command` + an `AAZCommand` / `AAZWaitCommand` subclass that is
+  registered explicitly in `azext_chaos/commands.py`.
+
+Reference: `Azure/azure-cli-extensions/src/connectedmachine/azext_connectedmachine`
+is the canonical pattern for AAZ subclass + manual `command_table` registration.

src/chaos/azext_chaos/__init__.py

@@ -0,0 +1,40 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+from azure.cli.core import AzCommandsLoader
+from azext_chaos._help import helps  # pylint: disable=unused-import
+
+
+class ChaosCommandsLoader(AzCommandsLoader):
+
+    def __init__(self, cli_ctx=None):
+        from azure.cli.core.commands import CliCommandType
+        chaos_custom = CliCommandType(
+            operations_tmpl='azext_chaos.custom#{}')
+        super().__init__(cli_ctx=cli_ctx,
+                         custom_command_type=chaos_custom)
+
+    def load_command_table(self, args):
+        from azext_chaos.commands import load_command_table
+        from azure.cli.core.aaz import load_aaz_command_table
+        try:
+            from . import aaz
+        except ImportError:
+            aaz = None
+        if aaz:
+            load_aaz_command_table(
+                loader=self,
+                aaz_pkg_name=aaz.__name__,
+                args=args
+            )
+        load_command_table(self, args)
+        return self.command_table
+
+    def load_arguments(self, command):
+        from azext_chaos._params import load_arguments
+        load_arguments(self, command)
+
+
+COMMAND_LOADER_CLS = ChaosCommandsLoader