# Azure Key Vault Operating Runbook
**Cold Bore Ballistics LLC — Confidential**
Last updated: 2026-06-06

> Day-to-day procedures for managing CBB Key Vault secrets. For resource inventory and design decisions see `Azure_Key_Vault_Architecture_Reference.md`. For full rebuild from scratch see `Azure_Key_Vault_Rebuild_Guide.md`.

---

## Prerequisites

These procedures require the Azure CLI. Install it if not already present:

**Debian / Ubuntu:**
```bash
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
```

**RHEL / Fedora:**
```bash
sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc
sudo dnf install azure-cli
```

**Windows:**
```powershell
winget install Microsoft.AzureCLI
```

**macOS:**
```bash
brew install azure-cli
```

After installing, authenticate:
```bash
az login
az account set --subscription "<your-subscription-id>"
```

---

## Procedure: Read a Secret

Use this to retrieve a secret value for manual use (e.g., during a rebuild or debugging session). Do not store retrieved values in files or paste them into chat.

```bash
az keyvault secret show \
  --vault-name <kv-cbb-shared-prod or kv-scope-dope-prod> \
  --name <secret-name> \
  --query value \
  --output tsv
```

Example — retrieve the Flask secret key:
```bash
az keyvault secret show \
  --vault-name kv-scope-dope-prod \
  --name flask-secret-key \
  --query value \
  --output tsv
```

---

## Procedure: Rotate a Secret

Use this when a secret must be changed — credential exposure, annual rotation, or infrastructure change.

1. Generate the new secret value (outside of Azure — e.g., `openssl rand -base64 32` for a random key).
2. Set the new version in Key Vault:
```bash
az keyvault secret set \
  --vault-name <vault-name> \
  --name <secret-name> \
  --value "<new-value>"
```
3. If the secret drives a running service (e.g., `database-url`, `flask-secret-key`), restart the Container App to pick up the new version:
```bash
az containerapp revision restart \
  --resource-group rg-cbb-prod \
  --name <container-app-name> \
  --revision <revision-name>
```
   Or trigger a new revision by updating the image tag via the CI/CD pipeline.
4. Verify the service is healthy after the restart.
5. Update `Azure_Key_Vault_Architecture_Reference.md` — update the "last rotated" date for that secret if you are tracking rotation dates.

> **Note:** Key Vault keeps all prior secret versions automatically. The old version is disabled but not deleted. This provides rollback capability.

---

## Procedure: List All Secrets in a Vault

```bash
az keyvault secret list \
  --vault-name <vault-name> \
  --query "[].{Name:name, Enabled:attributes.enabled}" \
  --output table
```

---

## Procedure: Grant a New Principal Access

Use this when a new service, automation account, or operator needs access to a vault.

1. Look up the principal's object ID:
```bash
# For a user:
az ad user show --id user@coldboreballisticsllc.com --query id --output tsv

# For a managed identity:
az identity show \
  --resource-group rg-cbb-prod \
  --name <identity-name> \
  --query principalId \
  --output tsv
```

2. Assign the appropriate built-in RBAC role:

| Use case | Role |
|---|---|
| Read secrets only (app/service) | `Key Vault Secrets User` |
| Read + write secrets (operator) | `Key Vault Secrets Officer` |
| Full vault admin | `Key Vault Administrator` |

```bash
az role assignment create \
  --role "Key Vault Secrets User" \
  --assignee <object-id> \
  --scope "/subscriptions/<sub-id>/resourceGroups/rg-cbb-prod/providers/Microsoft.KeyVault/vaults/<vault-name>"
```

3. Document the new access in `Azure_Key_Vault_Architecture_Reference.md` under the vault's Access table.

---

## Procedure: Disable a Secret (without deleting)

Use when a credential is suspected compromised but you are not yet ready to rotate — disabling immediately prevents the old value from being retrieved while you prepare the new one.

```bash
az keyvault secret set-attributes \
  --vault-name <vault-name> \
  --name <secret-name> \
  --enabled false
```

Re-enable after rotation is complete:
```bash
az keyvault secret set-attributes \
  --vault-name <vault-name> \
  --name <secret-name> \
  --enabled true
```

---

## Procedure: Check Container App Is Using Key Vault Secrets

After wiring up or rotating, verify the Container App environment variables are resolving correctly:

```bash
az containerapp show \
  --resource-group rg-cbb-prod \
  --name <app-name> \
  --query "properties.template.containers[0].env" \
  --output table
```

Values sourced from Key Vault will show `secretRef` rather than a plaintext value. A `null` or missing value for a Key Vault-backed env var indicates a managed identity permission problem — check the RBAC assignment.

---

## Document Control

| Field | Value |
|---|---|
| **Document owner** | `jschwefel@coldboreballisticsllc.com` |
| **Classification** | Confidential (03_-_Confidential/) |
| **Location** | `OneDrive/CBB_Corporate/03_-_Confidential/Infrastructure/Azure_Key_Vault/Azure_Key_Vault_Operating_Runbook.md` |
| **Cross-references** | `Azure_Key_Vault_Architecture_Reference.md`; `Azure_Key_Vault_Rebuild_Guide.md` |
| **Created** | 2026-06-06 |
| **Last updated** | 2026-06-06 |
| **Next full review due** | 2027-06-06 |

---

## Revision Control Block

| Rev | Date | Changed By | Reviewed By | Approved By | Summary |
|-----|------|------------|-------------|-------------|---------|
| 0.9 | 2026-06-06 | jschwefel | — | — | Initial release |
