This is a standalone PowerShell diagnostic script that captures network connectivity, private endpoint configuration, and Azure RBAC status for Cosmos DB accounts. It's designed to be run locally on a customer's machine to help troubleshoot HTTP 0.0 and connection errors.

Key Features:

✅ DNS resolution verification
✅ TCP 443 connectivity testing
✅ HTTPS reachability probe
✅ Private endpoint detection
✅ Private network route analysis
✅ Azure CLI optional context (network config, RBAC)
✅ Structured JSON output for triage automation
✅ Sensitive data redaction for safe sharing
✅ Interactive and non-interactive modes

Quick Start

Prerequisites

PowerShell 5.0+ (works on Windows, Linux, macOS)
If querying Azure config: Azure CLI installed and authenticated (az login)
Outbound network access to documents.azure.com

Option 1: Interactive Mode (Recommended for First Run)

Simplest approach—script prompts for inputs:

.\Diagnose-CosmosConnectivity.ps1 -Interactive

The script will display a guide showing where to find each input, then prompt:

Endpoint URL
Subscription ID
Resource Group
Account Name
(Optional) Private Endpoint IP
(Optional) VPN Subnet Range

Option 2: Non-Interactive Mode (Scripted/Automated)

Provide all parameters directly:

.\Diagnose-CosmosConnectivity.ps1 `
  -EndpointUrl "https://my-cosmos-account.documents.azure.com" `
  -SubscriptionId "12345678-1234-1234-1234-123456789012" `
  -ResourceGroup "my-resource-group" `
  -AccountName "my-cosmos-account"

Option 3: Non-Interactive with Redaction (Safe for Support)

Output JSON with sensitive data masked:

.\Diagnose-CosmosConnectivity.ps1 `
  -EndpointUrl "https://my-cosmos-account.documents.azure.com" `
  -SubscriptionId "12345678-1234-1234-1234-123456789012" `
  -ResourceGroup "my-resource-group" `
  -AccountName "my-cosmos-account" `
  -Redact

Detailed Usage

Getting Your Inputs

1. Endpoint URL (Required)

Location: Azure Portal → Cosmos DB Account → Overview

Go to Azure Portal
Search for "Cosmos DB"
Click your Cosmos DB account
Look for the "URI" field in the Overview tab
Copy the entire URL (e.g., https://my-cosmos-account.documents.azure.com)

Format: https://<account-name>.documents.azure.com (do NOT include trailing slash or :443/)

Note: If using a regional endpoint, use the primary endpoint. Private endpoints will have the same hostname with different IP resolution.

2. Subscription ID (Required)

Location: Azure Portal → Subscriptions or Portal → Home

Go to Azure Portal
Click on "Subscriptions" (or search for it)
Find your subscription
Copy the Subscription ID (looks like 12345678-1234-1234-1234-123456789012)

Alternative: From your Cosmos account page, look at the breadcrumb at the top or search box.

3. Resource Group (Required)

Location: Azure Portal → Cosmos DB Account (top-right corner)

Open your Cosmos DB account
At the top of the page, you'll see breadcrumbs
Look for "Resource group: " in the top-right
Or on the Overview page, find the "Resource group" field

Example: my-production-rg or cosmos-resources

4. Account Name (Required)

Location: Extract from endpoint URL or Azure Portal

From URL:

Endpoint: https://my-cosmos-account.documents.azure.com
Account Name: my-cosmos-account (the part before .documents.azure.com)

From Portal:

Open Cosmos DB account → Look at the account name in the breadcrumb or page title

5. Private Endpoint IP (Optional but Recommended)

Location: Azure Portal → Cosmos DB Account → Private Endpoint Connections

Open your Cosmos DB account
Go to Settings → Private Endpoint Connections
If any connections exist, look for "Private IP address" column
Copy the IP (e.g., 10.123.171.30)

When to provide:

If your Cosmos account has private endpoints configured
Otherwise, leave blank (press Enter in interactive mode)

Format: 10.x.x.x, 172.16-31.x.x, or 192.168.x.x (RFC 1918 ranges)

6. VPN Subnet Range (Optional)

Location: Ask your network team or VPN client properties

If you're connecting via VPN, your network team should know your VPN subnet CIDR.

Example: 10.0.0.0/24 (network: 10.0.0.0–10.0.0.255)

When to provide:

If you're behind a VPN
If you suspect VPN routing is the issue
Otherwise, leave blank

Understanding Output

Console Summary

After running, you'll see:

═════════════════════════════════════════════════════════════════════════════
DIAGNOSTIC COMPLETE
═════════════════════════════════════════════════════════════════════════════

Summary:
  DNS Resolution: ✓ PASS
  TCP Connectivity: ✗ FAIL
  Private Network: Detected (Private Endpoint)
  Classification: FAILURE - tcp_connectivity_blocked

Full report saved to: cosmos-diagnostic-20260513_143045.json

Summary:
TCP 443 connection failed to private endpoint. Network path is blocked.

Recommended Actions:
  1. Verify VPN connectivity and that your client subnet can route to the private endpoint subnet
  2. Ask your network team to verify routing from DESKTOP-ABC123 to private endpoint 10.123.171.30
  3. Check Azure network security groups (NSGs) rules for port 443 inbound
  4. Verify Azure Virtual Network peering and User Defined Routes (UDRs)
  5. Check if corporate firewall/NVA is blocking the connection
  6. Manually run: Test-NetConnection -ComputerName my-cosmos-account.documents.azure.com -Port 443

Full JSON Report:
...

JSON Output File

A file like cosmos-diagnostic-20260513_143045.json is automatically saved in the current directory.

Use this file to:

Share with support (can use -Redact to mask sensitive data)
Parse with automation tools
Retain diagnostic history

Common Scenarios

Scenario 1: "I can't connect to Cosmos DB from my machine"

Run this:

.\Diagnose-CosmosConnectivity.ps1 -Interactive

Interpret results:

If dns_resolution_failed → Check VPN/proxy DNS settings
If tcp_connectivity_blocked → Ask network team to check firewall/NSG rules
If network_connectivity_healthy → Issue is auth/RBAC, not network

Scenario 2: "Private endpoint isn't working"

Run this:

.\Diagnose-CosmosConnectivity.ps1 `
  -EndpointUrl "https://my-cosmos.documents.azure.com" `
  -SubscriptionId "your-sub-id" `
  -ResourceGroup "your-rg" `
  -AccountName "your-account" `
  -PrivateEndpointIP "10.123.171.30"

Interpret results:

If resolved IP matches private endpoint IP but TCP fails → VPN route blocked
If resolved IP differs from provided IP → Route misconfiguration
If network is healthy → Check private DNS zone configuration

Run with redaction:

.\Diagnose-CosmosConnectivity.ps1 `
  -EndpointUrl "https://my-cosmos.documents.azure.com" `
  -SubscriptionId "your-sub-id" `
  -ResourceGroup "your-rg" `
  -AccountName "your-account" `
  -Redact

Then share the generated JSON file. Sensitive data (subscription ID, usernames, tenant ID) will be masked as REDACTED.

Scenario 4: "I need the diagnostics in a pipeline"

Non-interactive with JSON output capture:

$json = .\Diagnose-CosmosConnectivity.ps1 `
  -EndpointUrl "https://my-cosmos.documents.azure.com" `
  -SubscriptionId "your-sub-id" `
  -ResourceGroup "your-rg" `
  -AccountName "your-account" 2>&1 `
  | Select-String -Pattern '^\{' -SimpleMatch | ConvertFrom-Json

# Now use $json in automation
if ($json.classification.code -eq "network_connectivity_healthy") {
    Write-Host "Network OK, escalating to app team"
} else {
    Write-Host "Network issue: $($json.classification.summary)"
}

Classification Codes

The script produces one of these classification codes:

Code	Meaning
`network_connectivity_healthy`	✓ Network works. If errors, check auth/RBAC.
`dns_resolution_failed`	✗ Cannot resolve endpoint hostname.
`tcp_connectivity_blocked`	✗ DNS works, but TCP 443 blocked.
`private_endpoint_network_path_blocked`	✗ Private endpoint detected, TCP fails.
`rbac_insufficient`	⚠ Network OK, but RBAC permissions missing.
`azure_config_check_skipped`	⚠ Azure CLI not authenticated.

See CLASSIFICATION_MATRIX.md for detailed playbooks and support guidance.

Advanced Usage

Running Specific Checks

The script always runs all checks, but you can parse the JSON to focus on specific ones:

# Get just DNS results
$report = Get-Content cosmos-diagnostic-*.json | ConvertFrom-Json
$report.diagnostics.dns | ConvertTo-Json

# Get classification only
$report.classification | ConvertTo-Json

# Check if RBAC is sufficient
$report.diagnostics.rbac.classification

Integration with Support Ticketing

When opening a support case:

Run the script (interactive mode is fine)
Include the generated JSON file in your ticket
Or use -Redact flag if sharing with external support

Example ticket text:

Title: Cosmos DB Connection Errors

Body:
Experiencing connection errors to my Cosmos DB account.
Attached diagnostic results (cosmos-diagnostic-*.json).

Network Status: [paste classification.status]
Issue Code: [paste classification.code]
Endpoint: [paste target.hostname]

Troubleshooting the Script Itself

Script won't run (permission denied)

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Then re-run the script.

"Azure CLI not found" but I need RBAC checks

Install Azure CLI:

Windows: https://learn.microsoft.com/en-us/cli/azure/install-azure-cli-windows
Mac: brew install azure-cli
Linux: Follow docs at https://learn.microsoft.com/en-us/cli/azure/install-azure-cli-linux

Then:

az login

Re-run the script.

Endpoint validation error

Error: "Invalid format. Expected: https://.documents.azure.com"

Fix: Remove trailing slash or port from URL:

❌ https://my-cosmos.documents.azure.com/ (trailing slash)
❌ https://my-cosmos.documents.azure.com:443/ (with port)
✅ https://my-cosmos.documents.azure.com (correct)

File Outputs

Generated Files

After running, the script creates:

cosmos-diagnostic-<timestamp>.json

Full diagnostic report in JSON format
Machine-readable for automation
Can be shared with support
Keep for troubleshooting history

JSON Schema

For details on JSON structure, field definitions, and sample outputs, see DIAGNOSTIC_SCHEMA.md.

Support Routing

Based on classification code, route as follows:

Classification	Route To
`network_connectivity_healthy`	Application/Auth team—network verified working
`dns_resolution_failed`	VPN/Network team—DNS issue
`tcp_connectivity_blocked` (public IP)	Firewall/ISP team—outbound port blocked
`private_endpoint_network_path_blocked`	Network team—PE routing issue
`rbac_insufficient`	Cosmos DB Access Control team
`azure_config_check_skipped`	Customer: Run `az login` first

Version

Script Version: 1.0.0
Schema Version: 1.0.0
Last Updated: 2026-05-13

License

This script is provided as-is for diagnosing Cosmos DB connectivity issues. See LICENSE for terms.

Next Steps

Run the script: .\Diagnose-CosmosConnectivity.ps1 -Interactive
Review output: Check the JSON report and console summary
Follow recommended actions based on the classification code
Share with support if needed (use -Redact for sensitive data masking)

For questions or issues with the script itself, contact the Cosmos DB team.

README.md Unescape Escape

Cosmos DB Connectivity Diagnostic Script - README

Overview