[Do Not Merge] Sachim/documentdb gap analysis fixes by sachim · Pull Request #10188 · Azure/azure-cli-extensions

sachim · 2026-08-06T17:53:30Z

Summary

This PR delivers the Azure DocumentDB CLI extension (az documentdb mongocluster, the Microsoft.DocumentDB/mongoClusters resource, API 2026-06-01) together with a round of gap-analysis fixes that make the command surface consistent, safer, and better documented.

Command surface

az documentdb mongocluster — create/update/show/list/delete clusters, list-connection-strings, reset-password
firewall-rule — manage IP firewall rules (public access)
microsoft-entra-user — assign/show/list/remove Microsoft Entra ID database users
identity — assign/show/list/remove user-assigned managed identity
replica — list/create/promote cross-region read replicas
restore — point-in-time restore to a new cluster

Gap-analysis fixes

--source-cluster rename — replaced --parent-cluster-name / --parent-location on replica list, replica create, replica promote, and restore with a single --source-cluster argument that accepts a cluster name or full ARM ID. The source location is now resolved automatically from the source cluster instead of being passed by hand.
microsoft-entra-user rename — the entra-user command group is now microsoft-entra-user; removed the unsupported entra-user update command (the service does not support updating an existing Entra user).
identity list — added a list command for the cluster's user-assigned managed identities.
Promote guard — replica promote now requires --source-cluster and validates that the named replica actually belongs to that source, raising a clear error on mismatch to prevent promoting the wrong replica. Added a destructive-operation confirmation prompt.
Confirmation prompts — added --yes/confirmation prompts to destructive operations (replica promote, identity remove).
--ids support — enabled resource-ID addressing via id_part on the relevant commands.
Password flag consistency — administrator password is --password/-p/--admin-password across create, update, reset-password, and restore.
Docs — README.md updated to reflect all of the above; stale entra-user / parent-cluster-name references removed from the README and test recordings.

Tests

End-to-end scenario tests (recorded live and verified in playback) cover cluster CRUD + connection strings + reset-password, firewall rules, Microsoft Entra users, managed identity, CMK encryption, cross-region replica create, replica promote, and point-in-time restore. Each scenario is an independent test with its own recording.

Note: this branch is based on the feature-documentDB-v2 work, so the diff against main also includes the changes from PR #10113.

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

Related command

az documentdb mongocluster

General Guidelines

Have you run azdev style <YOUR_EXT> locally? (pip install azdev required)
Have you run python scripts/ci/test_index.py -q locally? (pip install azdev required)
My extension version conforms to the Extension version schema

For new extensions:

My extension description/summary conforms to the Extension Summary Guidelines.

About Extension Publish

There is a pipeline to automatically build, upload and publish extension wheels.
Once your pull request is merged into main branch, a new pull request will be created to update src/index.json automatically.
You only need to update the version information in file setup.py and historical information in file HISTORY.rst in your PR but do not modify src/index.json.

Addresses PR review feedback. Adds end to end scenario coverage for mongocluster user, cross region replica (GeoAsyncReplica) and point in time restore, recorded live and verified in playback. A _wait_for_restore_point helper waits (only while recording) for the first backup, and _cmd_retry reissues a mutating command while the service still reports an operation in progress. Fixes _keep_only_args so deregistered arguments are also marked optional. Previously a hidden but still required argument (the base create password on a replica) failed schema validation with a missing required field error, so replica create could not run. Renames the administrator password flag to --password/-p on create and update for consistency with reset-password and restore. Fixes a typo in the user show help text. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 8bf5e49a-3c3e-4dfe-851d-1f2790a2852b

Each mongocluster scenario (crud, firewall, user, identity, replica, restore, cmk) is now an independent test with its own recording, so a failure in one does not mask the others and a single scenario can be re-recorded on its own. Adds coverage for managed identity (assign/show/remove) and customer-managed key (CMK) encryption at rest, and replaces the monolithic lifecycle recording. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 8bf5e49a-3c3e-4dfe-851d-1f2790a2852b

The generated replica promote command sent {mode, promoteOption} at the request root, which the service rejects with a schema error, and passed a null final-result callback to the long-running-operation poller, which raised a TypeError once the operation completed. The custom.py wrapper now nests the body under "properties" and supplies a no-op callback, mirroring how the generated delete handles its empty response. Adds an end-to-end promote scenario test (source + cross-region replica, forced switchover, asserts the replica settles into the primary role) plus a helper that waits out the brief post-operation Updating state. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 8bf5e49a-3c3e-4dfe-851d-1f2790a2852b

Adds a negative test covering client-side validation (invalid --storage-type and --high-availability enum values, invalid --mode, and a missing required --promote-option, all asserted via SystemExit) and service rejections (show/firewall-rule show/user show/replica list against a cluster that does not exist, asserted with expect_failure). This matches the negative-case convention used by the official cosmosdb CLI tests. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 8bf5e49a-3c3e-4dfe-851d-1f2790a2852b

…identity check Resolve mongocluster scenario test review feedback: * Expose all three password aliases (--admin-password, --password, -p) on create, update, reset-password, and restore. Examples show --admin-password. * Exercise the native wait command explicitly: firewall uses create --no-wait then firewall-rule wait --created. Replace the two hand authored pollers with mongocluster wait --custom in the restore and promote tests. * Use 0.0.0.0 firewall ranges instead of a hardcoded test IP. * Validate the user assigned identity in the CMK test through identity show (type, key presence, and principalId). * Fix user command examples to a pattern valid username (alice-entra). Recorded the affected cassettes again (firewall, restore, promote, cmk). All nine scenario tests pass in playback. Style and linter pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 8bf5e49a-3c3e-4dfe-851d-1f2790a2852b

…id identifier Address Oliver Towers' PR review on the mongocluster user commands: the users API only supports Microsoft Entra ID principals today, so the generic `user` naming misleads customers about what is provisioned and what identifier to pass. - Rename command group `mongocluster user` -> `mongocluster entra-user`. - Rename the identifier arg `--user-name` -> `--object-id` (keeps `-n`/`--name` aliases); help now states it is the Entra object (client) ID GUID, not a friendly name or UPN. - Make all command/group help Entra-specific; fix "defintion" typo in show. - Update examples to use a GUID object id. - Fix roles singular option in the aaz model (was generating ----role). - Re-record the entra-user and negative scenario tests live; both pass playback. The flat --type wrapper (custom.py) and its command-table registration are rewired to the entra-user name so the flattening survives the rename. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 40a4fbc4-fd62-4bcc-9b7d-6e70f80e114d

Address Oliver Towers' PR review: an entra-user binding grants an already-existing Microsoft Entra principal data-plane access to the cluster (a roles assignment), rather than creating a new user. Rename the commands `entra-user create` -> `assign` and `entra-user delete` -> `remove` (verbs only; group and update/show/list stay), matching the sibling `mongocluster identity assign/remove`. - Regenerated aaz code: _assign.py/_remove.py with classes Assign/Remove. - custom.py/commands.py: the flat --type wrapper is rewired to `entra-user assign`. - Updated README and the scenario test; re-recorded the user cassette live. Pairs with the aaz model change in Azure/aaz. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 40a4fbc4-fd62-4bcc-9b7d-6e70f80e114d

Version bump for the entra-user rename work (user -> entra-user, --object-id, create/delete -> assign/remove, password aliases). Adds the 1.0.0b2 changelog entry. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 40a4fbc4-fd62-4bcc-9b7d-6e70f80e114d

Two release-readiness fixes for the extension: - Mark all command groups and commands as Preview (stage=Preview in the aaz model, regenerated here) so the CLI reference docs show Preview instead of GA. - Rebrand the product name to "Azure DocumentDB": update README, HISTORY, the service_name.json mapping, and the root/mongocluster group help. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 40a4fbc4-fd62-4bcc-9b7d-6e70f80e114d

Regenerate replica list from the aaz model and update the hand written replica create and restore wrappers so the parent cluster and its region use parent-cluster-name and parent-location instead of source-cluster and source-location, per review feedback. Also updates the scenario tests and the README. The ARM property names sourceResourceId and sourceLocation are unchanged. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 40a4fbc4-fd62-4bcc-9b7d-6e70f80e114d

- Rename replica/restore source arg to --source-cluster (name-or-ARM-ID); derive replica source location from the source cluster; drop --parent-location - Rename 'replica list' arg to --source-cluster - Add 'replica promote' --source-cluster guard (validate vs replica sourceResourceId) - Add confirmations to 'identity remove' and 'replica promote' - Add 'identity list' command - Rename 'entra-user' group to 'microsoft-entra-user' - Remove 'entra-user update' (unsupported by service) - Update scenario tests for renamed args/commands

azure-client-tools-bot-prd · 2026-08-06T17:53:36Z

Hi sachim,
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.

azure-pipelines · 2026-08-06T17:53:39Z

Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run.

azure-client-tools-agent · 2026-08-06T17:55:15Z

Automated sensitive-information remediation ran on this pull request.

Detected categories: credential
Replaced with typed [REDACTED:category] placeholders in: no writable PR fields
Could not edit: file changes on a fork branch
Comment/review owners notified because Agent Assist cannot edit another user's text: none

If a credential was exposed, rotate or revoke it immediately. Detected values are never copied into this comment.

✅ Keep the redaction · ❌ Dispute the redaction

GitHub only supports a fixed reaction set, so 👍 represents ✅ and 👎 represents ❌. The bot-created reactions are only poll choices.

Posted by agent-assist (autonomous bug-fix pipeline).

sachim · 2026-08-06T17:56:06Z

sachim please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.
@microsoft-github-policy-service agree [company="{your company}"]
Options:

(default - no company specified) I have sole ownership of intellectual property rights to my Submissions and I am not making Submissions in the course of work for my employer.
@microsoft-github-policy-service agree
(when company given) I am making Submissions in the course of work for my employer (or my employer has intellectual property rights in my Submissions by contract or applicable law). I have permission from my employer to make Submissions and enter into this Agreement on behalf of my employer. By signing below, the defined term “You” includes me and my employer.
@microsoft-github-policy-service agree company="Microsoft"
Contributor License Agreement

@microsoft-github-policy-service agree company="Microsoft"

microsoft-github-policy-service · 2026-08-06T17:56:08Z

Thank you for your contribution sachim! We will review the pull request and get back to you soon.

…EADME and recordings

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

…luster guard; re-record crud/identity/promote

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

… 4.5); reset-password includes current admin login; re-record crud

azure-pipelines · 2026-08-06T22:12:23Z

Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run.

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Yong Zhang (yonzhan) · 2026-08-06T22:49:10Z

documentdb

Oliver Towers (olivertowers)

lgtm - just some test gaps we should resolve.

I largely used the test scenarios as my way of reviewing how things worked, so use the test scenarios as the full functional spec definition for the commands for coverage.

Goal should be coverage of each command and each parameter specific to command that we are adding.

Oliver Towers (olivertowers) · 2026-08-06T22:57:38Z

+            'replica_loc': 'westus2',
+        })
+
+        # A source cluster with the GeoReplicas preview feature and a cross-region


GeoReplcias is not necessary for this - let's not require it in test cases as it is misleading.

Done — removed the GeoReplicas preview feature from the replica and promote scenarios. Re-recorded both live and confirmed geo-replica creation and promote/switchover succeed without it, so it's no longer required or referenced in those tests.

Oliver Towers (olivertowers) · 2026-08-06T23:03:51Z

@@ -3,46 +3,90 @@
 # Licensed under the MIT License. See License.txt in the project root for license information.
 # --------------------------------------------------------------------------------------------

+import json
+import os
+import tempfile
 import unittest

 from azure.cli.testsdk import ScenarioTest, ResourceGroupPreparer
 from azure.cli.testsdk.scenario_tests.decorators import AllowLargeResponse


 class DocumentdbScenario(ScenarioTest):


Add tests that validate additional props

server-version

public-network-access

network-bypass-mode (an update only op but good to test in the same scenario with public network acess)

tags

preview-features (we should find something better that GeoReplicas, it can be misleading if we say that it needs to be set for replica creation, we can probably pick a data plane specific feature switch to avoid confusion with management operations).

Added a dedicated test_documentdb_mongocluster_properties scenario covering the properties you listed (plus a couple of related ones), each validated via show/response checks:

--server-version (create, 7.0)

--public-network-access (create Enabled -> update Disabled)

--network-bypass-mode (update-only, AzureCosmosDB, tested in the same scenario right after disabling public network access)

--tags (create + update)

--data-api-mode (enable then disable via update — the service only allows toggling it after the cluster is provisioned)

--auth-allowed-modes (NativeAuth+MicrosoftEntraID -> MicrosoftEntraID-only)

--preview-features (GeoReplicas)

On preview-features: GeoReplicas is currently the only value in the PreviewFeature enum in 2026-06-01 (there is no data-plane feature switch), so it is covered here purely as a create-time flag, fully decoupled from replica creation. The scenario also encodes the service prerequisite chain for networkBypassMode (public network access disabled + Entra-ID-only auth).

azure-pipelines · 2026-08-06T23:16:28Z

Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run.

…plicas from replica scenarios (PR feedback)

amatarritamicrosoft and others added 12 commits July 13, 2026 16:03

documentdb: re-record replica and promote scenario tests (live)

b3c3462

Copilot AI lite review requested due to automatic review settings August 6, 2026 17:53

azure-client-tools-bot-prd Bot added this to the September 2026 (2026-09-01) milestone Aug 6, 2026

sachim added the do-not-merge label Aug 6, 2026

sachim marked this pull request as draft August 6, 2026 17:54

azure-client-tools-agent Bot added the azure-client-tools-agent Pull request commented on or reviewed by Azure Client Tools Agent label Aug 6, 2026

microsoft-github-policy-service Bot added the customer-reported Issues that are reported by GitHub users external to the Azure organization. label Aug 6, 2026

[documentdb] Fix stale entra-user/parent-cluster-name references in R…

ea1fff1

…EADME and recordings

Copilot AI reviewed Aug 6, 2026

[documentdb] Add tests for --ids, identity list, and promote source-c…

1945c07

…luster guard; re-record crud/identity/promote

sachim requested a balanced review from Copilot August 6, 2026 20:17

Copilot AI reviewed Aug 6, 2026

[documentdb] Make 'mongocluster update' a true sparse HTTP PATCH (gap…

844515b

… 4.5); reset-password includes current admin login; re-record crud

sachim marked this pull request as ready for review August 6, 2026 22:12

sachim changed the title ~~Sachim/documentdb gap analysis fixes~~ [Do Not Merge] Sachim/documentdb gap analysis fixes Aug 6, 2026

sachim marked this pull request as draft August 6, 2026 22:12

sachim requested a balanced review from Copilot August 6, 2026 22:13

Copilot AI reviewed Aug 6, 2026

Yong Zhang (yonzhan) requested a review from Qi Pan (Pan-Qi) August 6, 2026 22:48

Yong Zhang (yonzhan) assigned Qi Pan (Pan-Qi) Aug 6, 2026

Copilot started reviewing on behalf of sachim August 6, 2026 22:57 View session

Oliver Towers (olivertowers) suggested changes Aug 6, 2026

View reviewed changes

sachim marked this pull request as ready for review August 6, 2026 23:16

sachim marked this pull request as draft August 6, 2026 23:16

Copilot started reviewing on behalf of sachim August 6, 2026 23:25 View session

Copilot started reviewing on behalf of sachim August 6, 2026 23:37 View session

Sachin Maske added 2 commits August 6, 2026 20:15

[documentdb] Add exhaustive property-coverage test and decouple GeoRe…

579eccf

…plicas from replica scenarios (PR feedback)

[documentdb] Fix flake8 E303 (too many blank lines) in custom.py

4a1abbb

Uh oh!

Conversation

sachim commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Command surface

Gap-analysis fixes

Tests

Related command

General Guidelines

About Extension Publish

Uh oh!

azure-client-tools-bot-prd Bot commented Aug 6, 2026

Uh oh!

azure-pipelines Bot commented Aug 6, 2026

Uh oh!

azure-client-tools-agent Bot commented Aug 6, 2026

Uh oh!

sachim commented Aug 6, 2026

Uh oh!

microsoft-github-policy-service Bot commented Aug 6, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

azure-pipelines Bot commented Aug 6, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Yong Zhang (yonzhan) commented Aug 6, 2026

Uh oh!

Oliver Towers (olivertowers) left a comment

Choose a reason for hiding this comment

Uh oh!

Oliver Towers (olivertowers) Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

sachim Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

Oliver Towers (olivertowers) Aug 6, 2026

Choose a reason for hiding this comment

Uh oh!

sachim Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

azure-pipelines Bot commented Aug 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

sachim commented Aug 6, 2026 •

edited

Loading