documentdb-azure-deployment

Files (3)

• SKILL.md
• bicep-cluster-template.md · references/
• terraform-cluster-template.md · references/

SKILL.md (first lines)

# Deploy Azure DocumentDB

Interactive skill for provisioning a managed **Azure DocumentDB** cluster (resource type `Microsoft.DocumentDB/mongoClusters`, API `2025-09-01`). Azure DocumentDB is the managed Azure service built on the open-source [`microsoft/documentdb`](https://github.com/microsoft/documentdb) engine.

For running DocumentDB locally instead (Docker / Compose), use `documentdb-local-deployment`. For connection-string tuning after the cluster exists, use `documentdb-connection`.

> **No-agent shortcut.** A ready-to-run Bicep + deploy script is checked in at [`examples/azure-deployment/`](../../examples/azure-deployment/) — customers who prefer to run the deploy themselves can clone the repo and just run `./deploy.sh` (no arguments). The script interactively lists subscriptions → resource groups → regions (same flow as this skill). Use it as a reference when generating project files too.

## Step 0 — preflight checks (run before anything else)

Run these checks at the start of every deployment session. If any fails, **fix it in place and re-run the loop** before continuing to Step 1 — don't skip ahead, and don't ask the user configuration questions you'll have to re-ask after they fix their environment.

```bash
# 1. Azure CLI installed?
az version --query '"azure-cli"' -o tsv
# → If 'az' is not found, stop and install: https://learn.microsoft.com/cli/azure/install-azure-cli

# 2. Signed in?
az account show --query '{name:name, id:id}' -o json
# → On failure, run: az login

# 3. Correct subscription active?
az account show --query name -o tsv
# → If wrong, run: az account set --subscription "<name-or-id>"

# 4. Microsoft.DocumentDB provider registered on the subscription?
az provider show --namespace Microsoft.DocumentDB --query registrationState -o tsv
# → If 'NotRegistered' or 'Unregistered', run:
#     az provider register --namespace Microsoft.DocumentDB
#   Then poll until state is 'Registered' (~1–2 min).

# 5. Caller has Contributor/Owner on the target scope?
az role assignment list --assignee "$(az ad signed-in-user show --query id -o tsv)" \
  --scope "/subscriptions/$(az account show --query id -o tsv)" \
  --query "[].roleDefinitionName" -o tsv
# → Expect Contributor, Owner, or a custom role with Microsoft.DocumentDB/mongoClusters/write.
#   If empty or only a reader role, escalate before proceeding.

# 6. Region supports mongoClusters?
az provider show --namespace Microsoft.DocumentDB \
  --query "resourceTypes[?resourceType=='mongoClusters'].locations[]" -o tsv
# → Confirm the user's chosen location is in the list.
```

`examples/azure-deployment/deploy.sh` and `deploy.ps1` implement checks 1–4 automatically and will `az login` / register the provider / create the resource group as needed. If you're generating deployment files into a user's project, copy those scripts or use them as a template.

## Step 0.5 — is this production or dev/test?

Ask the user **before** anything else in Step 1. The answer drives every default. Never assume.

| If "production" (default) | If "dev / prototype / test" |
|---|---|
| Tier: **M30** (minimum that supports HA) | Tier: **M10** or M20 |
| Storage: **128 GiB** per shard | Storage: **32 GiB** |
| HA: **ZoneRedundantPreferred** | HA: **Disabled** |
| Firewall: Private Endpoint; `allowAzureServices: false` | `allowAzureServices: true` + developer IP rule |
| Password source: **Key Vault reference** | Key Vault preferred; literal OK for throwaway |
| Parameters file: `main.parameters.sample.json` | `main.parameters.dev.json` |

Production is the safer default — the Bicep template and `main.parameters.sample.json` in `examples/azure-deployment/` ship with M30 + ZoneRedundantPreferred + 128 GiB so that a customer who runs `./deploy.sh <rg> <location>` without overrides ends up with a cluster they can actually put workloads on. If the user answers "dev", either:

- pass `--parameters @main.parameters.dev.json` to the deploy script, **or**
- override on the command line:
  ```bash
  az deployment group create \
    --resource-group "<rg>" \
    --template-file main.bicep \
    --parameters computeTier=M10 storageSizeGb=32 haTargetMode=Disabled
  ```

## Step 1 — pick the Azure subscription (always ask, never assume)

The currently active subscription from `az account show` may not be the one the user wants. Always list and confirm — never silently use the active one.

```bash
# Show all subscriptions the signed-in user can access
az account list --query "[].{Name:name, SubscriptionId:id, State:state, IsDefault:isDefault}" \
  --output table
```

Present the list to the user and ask them to pick one (by name or ID). Then set it active so subsequent commands are scoped to it:

```bash
az account set --subscription "<subscription-id-or-name>"
az account show --query "{name:name, id:id}" -o table   # confirm
```

Record the chosen subscription ID as `$SUBSCRIPTION_ID` and pass `--subscription "$SUBSCRIPTION_ID"` to every subsequent `az` command in this flow — this guarantees RG / region lookups stay scoped to the user's choice even if the active context drifts.

If the user has only one subscription, still confirm out loud ("I'll deploy into `<name>` — OK?") rather than silently proceeding.

## Step 2 — pick the resource group in that subscription (existing or new)

List the resource groups **scoped to the chosen subscription** (do not omit `--subscription` — it prevents showing RGs from a different context):

```bash
az group list \
  --subscription "$SUBSCRIPTION_ID" \
  --query "[].{Name:name, Location:location}" \
  --output table
```

Present the list to the user and ask them to pick **one of**:

**(a) Reuse an existing RG** — take its `location` from the table above and use that as the cluster's region by default. **Skip Step 3** (the region is already fixed by the RG). Record it as `$LOCATION`.

**(b) Create a new RG** — ask the user for the new RG name, then continue to Step 3 to pick a region before creating it.

Do not proceed to Step 3 or Step 4 until the user has explicitly picked (a) or (b).

## Step 3 — pick the Azure region (only when creating a new RG)

Reached only when the user chose 2(b). List the regions that support `Microsoft.DocumentDB/mongoClusters` so the user can pick one that is both regionally appropriate and supported:

```bash
az provider show \
  --subscription "$SUBSCRIPTION_ID" \
  --namespace Microsoft.DocumentDB \
  --query "resourceTypes[?resourceType=='mongoClusters'].locations[]" \

From Azure/documentdb-agent-kit, MIT.

More from Azure/documentdb-agent-kit