[documentdb] Add DocumentDB (Mongo vCore) CLI extension by amatarritamicrosoft · Pull Request #10059 · Azure/azure-cli-extensions

amatarritamicrosoft · 2026-07-01T17:47:26Z

Summary

Adds a new Azure CLI extension documentdb for Azure Cosmos DB for MongoDB (vCore) — management-plane commands for Microsoft.DocumentDB/mongoClusters (api-version 2026-06-01).

Generated with the AAZ codegen tool. Companion command-model PR in Azure/aaz: Azure/aaz#1040.

Command tree

az documentdb mongocluster create / update / show / delete / list / list-connection-strings / check-name-availability / wait
az documentdb mongocluster firewall-rule create / update / show / delete / list / wait
az documentdb mongocluster identity assign / remove / show / wait (UserAssigned only)
az documentdb mongocluster replica list / promote
az documentdb mongocluster user create / update / show / delete / list / wait

Design notes

Flattened scalar arguments on create/update (no JSON blobs): --admin-user/-u, --admin-password/-p, --tier, --storage-size, --storage-type, --shard-count, --high-availability, --data-api-mode, --auth-allowed-modes. Core provisioning args required on create, optional on update.
user create/update accept a repeatable --role (singular option) and a custom --type/-t flag mapping to the identityProvider discriminated union (custom.py).
Private-endpoint / private-link commands intentionally omitted (covered by az network per current guidance).
New documentdb entry added to src/service_name.json.

Dependency (why this is a draft)

az documentdb is currently reserved/blocked in azure-cli core. This extension cannot be exercised until the core unblock ships in a released azure-cli:

Core unblock PR: {Cosmos DB} Reclaim the documentdb command namespace azure-cli#33686

Marking ready for review once that lands.

Testing

Live-tested end-to-end against Azure (create/update/delete of real mongoClusters, flattened flags, --role, --type).
Command models pass aaz-dev command-model verify.

This checklist is used to make sure that common guidelines for a pull request are followed.

The PR title and description conform to the repository guidelines.
I have read the Authoring Command Modules doc.
The code generated follows the Command Guidelines.

Add the initial �z documentdb mongocluster extension for the Microsoft.DocumentDB/mongoClusters resource (API 2026-06-01), generated with aaz-dev plus custom refinements: - Flatten cluster create/update inputs into first-class flags (--admin-user/--admin-password, --tier, --storage-size/--storage-type, --shard-count, --high-availability, --data-api-mode, --auth-allowed-modes); the five provisioning inputs are required on create. - Use --cluster-name for the parent on all sub-resources. - Restrict managed identity to UserAssigned (service rejects SystemAssigned). - user create/update: custom --type/-t flag over the identityProvider discriminated union, and repeatable --role db=x role=y (singular_options). - Drop private-endpoint-connection / private-link-resource in favor of the generic az network commands. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

azure-client-tools-bot-prd · 2026-07-01T17:47:30Z

Validation for Breaking Change Starting...

Thanks for your contribution!

azure-client-tools-bot-prd · 2026-07-01T17:47:33Z

Hi @amatarritamicrosoft,
Please write the description of changes which can be perceived by customers into HISTORY.rst.
If you want to release a new extension version, please update the version in setup.py as well.

yonzhan · 2026-07-01T23:24:07Z

documentdb

Add three hand-written custom commands over the AAZ-generated mongocluster surface: - `mongocluster reset-password`: friendly wrapper over update that exposes only --password and maps it to the administrator object (other update flags hidden). - `mongocluster replica create`: creates a cross-region GeoReplica from a source cluster (--source-cluster / --source-location); sets createMode + replicaParameters internally. - `mongocluster restore`: point-in-time restore into a new cluster (--source-cluster / --restore-time + admin credentials); sets createMode + restoreParameters + administrator internally. Since AAZ drops hide=True args from generated code, the create-variant wrappers inject createMode/replicaParameters/restoreParameters via a content override (set_const + set_prop) rather than hidden args. Irrelevant create/update flags are deregistered so each command stays focused. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Address PR feedback: expand the extension README with background, a command-group table, and usage examples for clusters, firewall rules, users, identity, replicas, reset-password, and point-in-time restore. Flesh out the 1.0.0b1 HISTORY entry with the customer-visible command surface. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

The reset-password, replica-create, and restore wrappers subclass the generated Create/Update commands. AAZ caches the built arguments schema in the class attribute ``_arguments_schema`` (used by get_arguments_schema, the CLI parser entry point). Because the wrappers inherit that attribute from their base command, when the base command (create/update) loaded its schema first in the same process, the wrapper reused the base's cached schema and never applied its own option rename/deregistration -- e.g. ``reset-password`` failed with "unrecognized arguments: --password". Give each wrapper its own ``_arguments_schema = None`` (and ``_args_schema = None`` for the internal build cache) so every wrapper builds and caches an isolated schema. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Add a recorded ScenarioTest covering the full mongo cluster lifecycle: check-name-availability, create, show, list, update (tags), reset-password, firewall-rule create/show/list/delete, and delete. Every long-running operation uses --no-wait immediately followed by the matching wait command so each step observes a settled state and the scenario is free of state-condition races. Includes the recorded cassette for offline playback. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Mark admin-user, admin-password, tier, storage-size, shard-count, and high-availability as required on `mongocluster create`, matching the AAZ command model. This gives a clear client-side error when a core provisioning input is omitted instead of a server-side 400. storage-type stays optional, and update keeps all of these optional so a single property can be changed in isolation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

necusjz · 2026-07-03T06:19:08Z

/azp run

azure-pipelines · 2026-07-03T06:19:22Z

Azure Pipelines successfully started running 2 pipeline(s).

necusjz · 2026-07-06T05:22:11Z

/azp run

azure-pipelines · 2026-07-06T05:22:24Z

Azure Pipelines successfully started running 2 pipeline(s).

necusjz · 2026-07-07T05:58:58Z

/azp run

azure-pipelines · 2026-07-07T05:59:11Z

Azure Pipelines successfully started running 2 pipeline(s).

Copilot

Pull request overview

Adds a new documentdb Azure CLI extension to manage Azure Cosmos DB for MongoDB (vCore) Microsoft.DocumentDB/mongoClusters resources (api-version 2026-06-01), primarily via AAZ-generated command modules with a small set of custom command wrappers.

Changes:

Registers az documentdb in service_name.json and introduces a new src/documentdb extension package (setup + metadata + help/params loader).
Adds AAZ-generated command implementations for documentdb mongocluster and subgroups (firewall-rule, identity, replica, user, wait/list/show/etc.).
Adds custom wrappers for UX/behavior tweaks (user --type/-t flattening, reset-password, replica create, restore) plus a scenario test + recording.

Reviewed changes

Copilot reviewed 54 out of 55 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/service_name.json	Registers `az documentdb` service entry for docs/service-name mapping.
src/documentdb/HISTORY.rst	Extension changelog for initial beta release.
src/documentdb/setup.py	Python packaging entrypoint for the extension.
src/documentdb/setup.cfg	Placeholder config file (consistent with other extensions).
src/documentdb/README.md	Extension overview + usage examples.
src/documentdb/azext_documentdb/init.py	Extension command loader wiring (AAZ + custom commands).
src/documentdb/azext_documentdb/_help.py	Help-file scaffold import for the extension.
src/documentdb/azext_documentdb/_params.py	Params hook (currently no extra arg customizations).
src/documentdb/azext_documentdb/azext_metadata.json	Extension metadata (preview + min CLI core version).
src/documentdb/azext_documentdb/commands.py	Registers custom command wrappers into the command table.
src/documentdb/azext_documentdb/custom.py	Custom wrappers: `user --type`, `reset-password`, `replica create`, `restore`.
src/documentdb/azext_documentdb/aaz/init.py	AAZ package marker for the extension.
src/documentdb/azext_documentdb/aaz/latest/init.py	AAZ `latest` package marker.
src/documentdb/azext_documentdb/aaz/latest/documentdb/init.py	AAZ root `documentdb` command-group module export.
src/documentdb/azext_documentdb/aaz/latest/documentdb/__cmd_group.py	Defines the `az documentdb` command group.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/init.py	Exports `mongocluster` command modules.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/__cmd_group.py	Defines the `az documentdb mongocluster` command group.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/_check_name_availability.py	AAZ implementation for `mongocluster check-name-availability`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/_create.py	AAZ implementation for `mongocluster create`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/_delete.py	AAZ implementation for `mongocluster delete`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/_list.py	AAZ implementation for `mongocluster list`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/_list_connection_strings.py	AAZ implementation for `mongocluster list-connection-strings`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/_show.py	AAZ implementation for `mongocluster show`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/_update.py	AAZ implementation for `mongocluster update`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/_wait.py	AAZ implementation for `mongocluster wait`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/firewall_rule/init.py	Exports firewall-rule command modules.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/firewall_rule/__cmd_group.py	Defines the `mongocluster firewall-rule` command group.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/firewall_rule/_create.py	AAZ implementation for `firewall-rule create`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/firewall_rule/_delete.py	AAZ implementation for `firewall-rule delete`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/firewall_rule/_list.py	AAZ implementation for `firewall-rule list`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/firewall_rule/_show.py	AAZ implementation for `firewall-rule show`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/firewall_rule/_update.py	AAZ implementation for `firewall-rule update`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/firewall_rule/_wait.py	AAZ implementation for `firewall-rule wait`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/identity/init.py	Exports identity command modules.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/identity/__cmd_group.py	Defines the `mongocluster identity` command group.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/identity/_assign.py	AAZ implementation for `identity assign`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/identity/_remove.py	AAZ implementation for `identity remove`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/identity/_show.py	AAZ implementation for `identity show`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/identity/_wait.py	AAZ implementation for `identity wait`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/replica/init.py	Exports replica command modules.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/replica/__cmd_group.py	Defines the `mongocluster replica` command group.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/replica/_list.py	AAZ implementation for `replica list`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/replica/_promote.py	AAZ implementation for `replica promote`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/user/init.py	Exports user command modules.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/user/__cmd_group.py	Defines the `mongocluster user` command group.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/user/_create.py	AAZ implementation for `user create`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/user/_delete.py	AAZ implementation for `user delete`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/user/_list.py	AAZ implementation for `user list`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/user/_show.py	AAZ implementation for `user show`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/user/_update.py	AAZ implementation for `user update`.
src/documentdb/azext_documentdb/aaz/latest/documentdb/mongocluster/user/_wait.py	AAZ implementation for `user wait`.
src/documentdb/azext_documentdb/tests/init.py	Test package marker.
src/documentdb/azext_documentdb/tests/latest/init.py	Latest-tests package marker.
src/documentdb/azext_documentdb/tests/latest/test_documentdb.py	Scenario test for core `mongocluster` + firewall-rule + reset-password flow.
src/documentdb/azext_documentdb/tests/latest/recordings/test_documentdb_mongocluster_lifecycle.yaml	Recorded live-test interactions for the scenario test.

+    "documentdb mongocluster user show",
+)
+class Show(AAZCommand):
+    """Get the defintion of a Mongo cluster user.


+class UserCreate(_UserCreate):
+    @classmethod
+    def _build_arguments_schema(cls, *args, **kwargs):
+        args_schema = super()._build_arguments_schema(*args, **kwargs)
+        return _add_principal_type_arg(args_schema)
+


+@register_command("documentdb mongocluster replica create")
+class ReplicaCreate(_MongoClusterCreate):
+    """Create a cross-region read replica of an existing mongo cluster.
+
+    The source cluster must have the "GeoReplicas" preview feature enabled. The replica
+    is provisioned as a new mongo cluster in the target region and inherits its
+    configuration (compute, storage, sharding) from the source cluster.
+
+    :example: Create a replica of a cluster in another region.
+        az documentdb mongocluster replica create -n MyReplica -g MyResourceGroup --location centralus --source-cluster MySourceCluster --source-location eastus2
+    """


+    from azext_documentdb.custom import (
+        UserCreate, UserUpdate, ResetPassword, ReplicaCreate, Restore)
+    self.command_table['documentdb mongocluster user create'] = UserCreate(loader=self)
+    self.command_table['documentdb mongocluster user update'] = UserUpdate(loader=self)
+    self.command_table['documentdb mongocluster reset-password'] = ResetPassword(loader=self)
+    self.command_table['documentdb mongocluster replica create'] = ReplicaCreate(loader=self)
+    self.command_table['documentdb mongocluster restore'] = Restore(loader=self)


azclibot · 2026-07-10T02:34:48Z

[Release] Update index.json for extension [ documentdb-1.0.0b1 ] : https://dev.azure.com/msazure/One/_build/results?buildId=171153343&view=results

olivertowers

Some things we need to fix up

Key gap - we need to add testing for replica/restore/CMK (user managed identity) to validate the command set fully.

olivertowers · 2026-07-10T20:13:48Z

+        args_schema = super()._build_arguments_schema(*args, **kwargs)
+        _keep_only_args(args_schema, {"cluster_name", "resource_group", "admin_password"})
+        password = args_schema.admin_password
+        password._options = ["--password", "-p"]


Argument name consistency between this command (--password, -p) and what the cluster create/update accepts( --admin-password), let's add the same set of aliases on both sides so that it is consistent.

olivertowers · 2026-07-10T20:18:51Z

+from azure.cli.testsdk.scenario_tests.decorators import AllowLargeResponse
+
+
+class DocumentdbScenario(ScenarioTest):


I don't see tests for restore, replica, CMK, users etc.

olivertowers · 2026-07-10T20:22:50Z

+    self.command_table['documentdb mongocluster user create'] = UserCreate(loader=self)
+    self.command_table['documentdb mongocluster user update'] = UserUpdate(loader=self)
+    self.command_table['documentdb mongocluster reset-password'] = ResetPassword(loader=self)
+    self.command_table['documentdb mongocluster replica create'] = ReplicaCreate(loader=self)


Should we add a wait commands for these sub-command groups?

don't know if the standard pattern is that for every sub-command that supports a LRO command, there should be a corresponding 'wait' command eg.

az documendb mongocluster replica create .... -nowait ....<do some other stuff> az documentdb mongocluster replica wait

Perhaps this is already generated somewhere I just couldn't see it - I did think the liniter/style checks would have failed on this.

Wait commands are generated for most of the sub groups: mongocluster , mongocluster user , mongocluster firewall-rule and mongocluster identity all expose a wait . The one group without its own wait is replica , and that is expected. A replica is itself a Microsoft.DocumentDB/mongoClusters resource, the same resource type as the primary, so it is already covered by the top level az documentdb mongocluster wait -n -g . I verified that mongocluster wait --exists returns 0 against a cluster, and that both replica create and replica promote expose --no-wait . A dedicated replica wait would just duplicate the mongocluster one. On the linter: the CLI linter and style checks do not require a wait command for every LRO command, so no failure is expected here.

olivertowers · 2026-07-10T20:35:52Z



 @register_command(
-    "workload-orchestration context site-reference create",
+    "documentdb mongocluster firewall-rule create",


Did we reach agreement that we would use firewall-rule instead of the AZ cli standard network rule?

Abinav Rameesh review the tree command and there was not issue from his side, I will share the doc why is better to use firewall-rule instead of network rule

yonzhan · 2026-07-14T07:32:15Z

documentdb

amatarritamicrosoft and others added 2 commits July 1, 2026 00:46

Adding entry in service_name.json

eddc499

azure-client-tools-bot-prd Bot added this to the August 2026 (2026-08-04) milestone Jul 1, 2026

microsoft-github-policy-service Bot requested review from necusjz and yonzhan July 1, 2026 17:48

microsoft-github-policy-service Bot added the Auto-Assign Auto assign by bot label Jul 1, 2026

microsoft-github-policy-service Bot assigned necusjz Jul 1, 2026

microsoft-github-policy-service Bot added the Code Gen label Jul 1, 2026

yonzhan requested a review from Pan-Qi July 1, 2026 23:24

yonzhan assigned Pan-Qi Jul 1, 2026

necusjz reviewed Jul 2, 2026

View reviewed changes

Comment thread src/documentdb/azext_documentdb/tests/latest/test_documentdb.py Outdated

necusjz reviewed Jul 2, 2026

View reviewed changes

Comment thread src/documentdb/README.md Outdated

amatarritamicrosoft and others added 4 commits July 2, 2026 10:51

necusjz marked this pull request as ready for review July 7, 2026 06:18

Copilot AI review requested due to automatic review settings July 7, 2026 06:18

Copilot started reviewing on behalf of necusjz July 7, 2026 06:19 View session

Copilot AI reviewed Jul 7, 2026

View reviewed changes

necusjz approved these changes Jul 7, 2026

View reviewed changes

necusjz merged commit 4ec1b87 into Azure:main Jul 7, 2026
24 checks passed

olivertowers reviewed Jul 10, 2026

View reviewed changes

amatarritamicrosoft mentioned this pull request Jul 14, 2026

[DONT MERGE] [documentdb] Add end-to-end mongocluster scenario test coverage and fix replica promote #10113

Draft

		from azure.cli.testsdk.scenario_tests.decorators import AllowLargeResponse


		class DocumentdbScenario(ScenarioTest):

Uh oh!

Conversation

amatarritamicrosoft commented Jul 1, 2026

Summary

Command tree

Design notes

Dependency (why this is a draft)

Testing

Uh oh!

azure-client-tools-bot-prd Bot commented Jul 1, 2026

Uh oh!

azure-client-tools-bot-prd Bot commented Jul 1, 2026

Uh oh!

yonzhan commented Jul 1, 2026

Uh oh!

Uh oh!

Uh oh!

necusjz commented Jul 3, 2026

Uh oh!

azure-pipelines Bot commented Jul 3, 2026

Uh oh!

necusjz commented Jul 6, 2026

Uh oh!

azure-pipelines Bot commented Jul 6, 2026

Uh oh!

necusjz commented Jul 7, 2026

Uh oh!

azure-pipelines Bot commented Jul 7, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

azclibot commented Jul 10, 2026

Uh oh!

olivertowers left a comment

Choose a reason for hiding this comment

Uh oh!

olivertowers Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

olivertowers Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

olivertowers Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

olivertowers Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

amatarritamicrosoft Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

olivertowers Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

amatarritamicrosoft Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

yonzhan commented Jul 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants