Azure-Samples / Azure-Samples/cosmos-db-vector-samples

nosql-create-index-typescript: sample fails creating SQL role definition that azd infra already provisions

Open
#101 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.