Azure-Samples / Azure-Samples/cosmos-db-vector-samples
nosql-create-index-typescript: sample fails creating SQL role definition that azd infra already provisions
- Dominant language
- TypeScript
- Stars
- 6
- Forks
- 9
- Avg merge
- 2d 11h
- Merged PRs (30d)
- 3
Description
## Summary
The article-2 `nosql-create-index-typescript` sample errors out at runtime after provisioning with this repo's `azd` template because it tries to create a Cosmos DB SQL role definition that `infra/main.bicep` already creates during `azd provision`.
The duplicate role definition name is:
`Write to Azure Cosmos DB for NoSQL data plane`
This causes the sample's `@azure/arm-cosmosdb` create call to collide with the role definition already provisioned by the infrastructure.
## Exact error
```text
Role Definition with the name [Write to Azure Cosmos DB for NoSQL data plane] already exists
```
## Environment
- Repo: `Azure-Samples/cosmos-db-vector-samples`
- Sample: `nosql-create-index-typescript`
- Provisioning: `azd provision` to `eastus2`
- Infrastructure: resource group + Cosmos DB + Azure OpenAI from `infra/main.bicep`
- Run command: `npm start`
- Node/npm: Node 24 / npm 11
- Identity: signed-in Azure CLI user; identity had `Owner` on the subscription
- Surfaced while validating Dependabot PR #87 (`@azure/identity` 4.13.1, `uuid` removed)
## Repro steps
1. From the repo root, create and configure an azd environment:
```bash
azd env new
azd env set AZURE_LOCATION eastus2
```
2. Provision the repo infrastructure:
```bash
azd provision
```
3. Move to the article-2 TypeScript sample, install dependencies, and populate `.env` from the azd outputs / provisioned resources:
```bash
cd nosql-create-index-typescript
npm ci
```
4. Run the sample:
```bash
npm start
```
5. Observed behavior: the sample connects and successfully creates/updates the container with the vector index. In the validation run, that step completed in about 12 seconds:
```text
=== Step 1: Create Container with Vector Index ===
Container: hotels_diskann
Index type: diskANN
Dimensions: 1536
Distance function: cosine
Created in 12.4s
Vector index is IMMUTABLE — cannot be changed after creation
```
6. The sample then fails in the SQL role-definition creation step:
```text
=== Step 2: Create Data-Plane RBAC Access ===
Creating role definition...
Error: The long-running operation has failed. BadRequest. A Role Definition with the name [Write to Azure Cosmos DB for NoSQL data plane] already exists, please choose a unique name for your new Role Definition.
```
## Root cause
There is duplicate Cosmos DB SQL role-definition creation:
- `infra/main.bicep` / the database infra path already provisions a data-plane SQL role definition named `Write to Azure Cosmos DB for NoSQL data plane` during `azd provision`.
- `nosql-create-index-typescript/src/control-plane.ts` then tries to create another SQL role definition with the same role name at runtime.
That makes the sample non-idempotent against the repo's own azd-provisioned infrastructure.
Related control-plane role note: `Cosmos DB Operator` alone is insufficient for the sample's ARM/control-plane calls because that built-in role excludes SQL role definition and SQL role assignment writes. The sample either needs a role such as `DocumentDB Account Contributor` at a narrow scope, or the docs/README need to explain the required management-plane permission.
## Proposed fix options
Please choose the approach that best matches the intended ownership boundary between infra and sample code:
1. Make the sample's role-definition creation idempotent: check whether the role definition already exists, or catch the "already exists" conflict and continue.
2. Remove role-definition creation from the sample and document that `azd provision` already provisions the role definition.
3. If the sample must own role-definition creation, remove that role-definition creation from `infra/main.bicep` / the azd infra path to avoid the collision.
Options 1 or 2 seem least disruptive because they preserve the current azd template behavior.
## Impact / doc angle
The quickstart article that walks through this sample will hit the same runtime error when used with the repo's azd infrastructure. Whatever fix is chosen should be reflected in both the sample README and the corresponding quickstart documentation.
## Note
This was surfaced while validating Dependabot PR #87 (`@azure/identity` 4.13.1 and `uuid` removal). The dependency bump itself installed and compiled successfully; this appears to be a pre-existing sample/infrastructure contract bug unrelated to the dependency update.
Contributor guide
Research direction
Read infra/main.bicep and nosql-create-index-typescript/src/control-plane.ts to compare the provisioned role definition with the runtime create call. Run azd provision followed by npm ci and npm start in the sample, then verify the sample completes without the duplicate-role error and that its README and quickstart document the required ownership and permissions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- azure, typescript
- Domain
- databases, documentation, infrastructure
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100