Design Spec: azure-cosmosdb-config-health
Parent: #102
Target: rw-cli-codecollection
Spec
codebundle_name: "azure-cosmosdb-config-health"
target_collection: "rw-cli-codecollection"
display_name: "Azure Cosmos DB Configuration Health"
author: "rw-codebundle-agent"
purpose: |
Validates Azure Cosmos DB account configuration that affects availability, security,
recoverability, and operability (API settings, backup, networking, diagnostics, and change history).
tasks:
- name: "Check Cosmos DB Resource Health for Account `${COSMOSDB_ACCOUNT_NAME}` in Resource Group `${AZURE_RESOURCE_GROUP}`"
description: "Uses Azure Resource Health to detect platform incidents or account-level availability problems."
script_name: "cosmosdb-resource-health.sh"
expected_issue_severity: [2, 3]
access_level: "read-only"
data_type: "config"
- name: "Check Cosmos DB API and Consistency Configuration for Account `${COSMOSDB_ACCOUNT_NAME}` in Resource Group `${AZURE_RESOURCE_GROUP}`"
description: "Reviews default consistency, multi-region writes, and capability flags against expected baselines for the workload tier."
script_name: "cosmosdb-api-consistency-config.sh"
expected_issue_severity: [2, 3]
access_level: "read-only"
data_type: "config"
- name: "Check Cosmos DB Backup and Point-in-Time Settings for Account `${COSMOSDB_ACCOUNT_NAME}` in Resource Group `${AZURE_RESOURCE_GROUP}`"
description: "Verifies periodic and/or continuous backup configuration and retention suitability for recovery objectives."
script_name: "cosmosdb-backup-policy.sh"
expected_issue_severity: [2, 4]
access_level: "read-only"
data_type: "config"
- name: "Check Cosmos DB Public Network Access and Firewall Rules for Account `${COSMOSDB_ACCOUNT_NAME}` in Resource Group `${AZURE_RESOURCE_GROUP}`"
description: "Flags public exposure or overly permissive IP rules that conflict with zero-trust patterns."
script_name: "cosmosdb-network-firewall.sh"
expected_issue_severity: [2, 3]
access_level: "read-only"
data_type: "config"
- name: "Check Cosmos DB Private Endpoint Configuration for Account `${COSMOSDB_ACCOUNT_NAME}` in Resource Group `${AZURE_RESOURCE_GROUP}`"
description: "Validates private link setup and connection state when private access is required."
script_name: "cosmosdb-private-endpoints.sh"
expected_issue_severity: [2, 3]
access_level: "read-only"
data_type: "config"
- name: "Check Cosmos DB Diagnostic Settings for Account `${COSMOSDB_ACCOUNT_NAME}` in Resource Group `${AZURE_RESOURCE_GROUP}`"
description: "Ensures metrics and control-plane logs flow to Log Analytics or storage for troubleshooting and audit."
script_name: "cosmosdb-diagnostic-settings.sh"
expected_issue_severity: [3, 4]
access_level: "read-only"
data_type: "logs-config"
- name: "Check Cosmos DB Activity Log for Recent Configuration Changes to Account `${COSMOSDB_ACCOUNT_NAME}` in Resource Group `${AZURE_RESOURCE_GROUP}`"
description: "Surfaces recent management mutations (throughput, failover, network, backup) that may explain behavior changes."
script_name: "cosmosdb-activity-changes.sh"
expected_issue_severity: [3, 4]
access_level: "read-only"
data_type: "logs-config"
scope:
level: "ResourceGroup"
qualifiers:
- AZ_SUBSCRIPTION
- AZURE_RESOURCE_GROUP
iteration_pattern: |
Target one or all Cosmos DB accounts in `${AZURE_RESOURCE_GROUP}`.
When `${COSMOSDB_ACCOUNT_NAME}` is set, scope to that account; when unset or `All`,
enumerate `Microsoft.DocumentDB/databaseAccounts` in the group.
resource_types:
- "azure_cosmosdb_database_account"
generation_strategy: |
Match discovered Cosmos DB database account resources; one SLX per account with qualifiers
resource_group and subscription_id. Confirm the RunWhen resource type slug against the
platform registry during implementation (use the canonical Cosmos DB account type).
env_vars:
- name: AZ_SUBSCRIPTION
description: "Azure subscription ID (UUID)"
required: true
- name: AZURE_RESOURCE_GROUP
description: "Resource group containing the Cosmos DB account(s)"
required: true
- name: COSMOSDB_ACCOUNT_NAME
description: "Cosmos DB account name, or All for every account in the resource group"
required: false
default: "All"
- name: ACTIVITY_LOG_LOOKBACK_HOURS
description: "Hours of activity log history to scan for configuration changes"
required: false
default: "168"
secrets:
- name: azure_credentials
description: "Service principal used by Azure CLI"
format: |
JSON object with: CLIENT_ID, TENANT_ID, CLIENT_SECRET, SUBSCRIPTION_ID
(or equivalent AZ_USERNAME / AZ_SECRET_VALUE / AZ_TENANT patterns used by sibling Azure bundles)
platform:
name: "azure"
cli_tools:
- "az"
- "jq"
auth_methods:
- "Service Principal (azure_credentials)"
api_docs: "https://learn.microsoft.com/en-us/rest/api/cosmos-db-resource-provider/"
related_bundles:
- name: "azure-cosmosdb-utilization-health"
relationship: "complements"
notes: "Covers RU, storage, and latency utilization; pair for full sizing and health picture."
- name: "azure-kv-health"
relationship: "complements"
notes: "Same read-only Azure health pattern; reuse CLI auth and issue JSON shapes where practical."
- name: "azure-subscription-cost-report"
relationship: "complements"
notes: "Mentions Cosmos DB reservation context; no configuration or utilization depth."
test_scenarios:
- name: "healthy_account"
description: "Account available, private access aligned with policy, backup and diagnostics enabled"
expected_issues: 0
- name: "public_exposed_account"
description: "Public network access enabled without compensating controls"
expected_issues: 2
expected_severities: [2, 3]
notes: |
Azure Cosmos DB does not expose classic VM-style CPU and memory metrics to customers; capacity
signals live in RU, partition layout, and storage metrics and belong in azure-cosmosdb-utilization-health.
Prefer Resource Graph or `az cosmosdb` / `az monitor diagnostic-settings` for configuration reads.
Respect read-only RBAC (Reader + monitoring roles) for implementation and testing.
Design Spec: azure-cosmosdb-config-health
Parent: #102
Target:
rw-cli-codecollectionSpec