Health Checks

Configure and monitor health check endpoints for your Bitwarden Server deployment

Bitwarden Server provides health check endpoints to monitor the status of your deployment and its dependencies. These endpoints are critical for production monitoring, load balancers, and orchestration platforms.

Health Check Endpoints

Basic Health Check

The basic health check endpoint provides a simple status indicator:

GET /healthz

Response:

{
  "status": "Healthy"
}

This endpoint is suitable for:

• Load balancer health checks
• Kubernetes liveness probes
• Basic uptime monitoring

Extended Health Check

The extended health check provides detailed information about all system dependencies:

GET /healthz/extended

Response Format:

{
  "status": "Healthy",
  "results": {
    "identity": {
      "status": "Healthy",
      "description": "Identity service is reachable",
      "data": {}
    },
    "sqlserver": {
      "status": "Healthy",
      "description": "Database connection successful",
      "data": {}
    }
  }
}

Configuration

Health Check Services

Health checks are configured in the API service startup. The implementation is in src/SharedWeb/Health/HealthCheckServiceExtensions.cs and src/Api/Utilities/ServiceCollectionExtensions.cs:77.

Default Checks:

1. Identity Service Check

   • Verifies the Identity service OpenID configuration endpoint
   • URL: {IdentityUri}/.well-known/openid-configuration

2. SQL Server Check

   • Validates database connectivity
   • Uses the configured connection string from globalSettings.SqlServer.ConnectionString

Self-Hosted Deployments

Health check endpoints are disabled by default for self-hosted deployments. They are only enabled for cloud deployments.

To enable health checks in self-hosted environments, you’ll need to modify the startup configuration in src/Api/Startup.cs:196.

Rate Limiting

The /alive endpoint (if configured) has rate limiting applied:

{
  "Endpoint": "get:/alive",
  "Period": "1m",
  "Limit": 5
}

This prevents abuse while allowing regular monitoring checks.

Monitoring Integration

Kubernetes

Configure liveness and readiness probes:

livenessProbe:
  httpGet:
    path: /healthz
    port: 5000
  initialDelaySeconds: 30
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /healthz/extended
    port: 5000
  initialDelaySeconds: 10
  periodSeconds: 5
  timeoutSeconds: 3
  failureThreshold: 2

Docker Swarm

Add a health check to your service definition:

services:
  api:
    image: bitwarden/api
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5000/healthz"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 40s

Load Balancers

NGINX

upstream bitwarden_api {
    server api:5000 max_fails=3 fail_timeout=30s;
    # Health check in NGINX Plus
    # health_check interval=10 uri=/healthz;
}

HAProxy

backend bitwarden_api
    option httpchk GET /healthz
    http-check expect status 200
    server api1 api:5000 check inter 10s fall 3 rise 2

Health Check Response Format

The health check response writer is implemented in src/SharedWeb/Health/HealthCheckServiceExtensions.cs:22.

Status Values:

• Healthy - Service is operating normally
• Degraded - Service is operational but with issues
• Unhealthy - Service is not operational

Extended Response Structure:

{
  "status": "string",
  "results": {
    "<check-name>": {
      "status": "string",
      "description": "string",
      "data": {}
    }
  }
}

Troubleshooting

Health Check Fails Immediately

Symptom: /healthz returns 503 or times out

Possible Causes:

1. Identity service is unreachable
2. Database connection is unavailable
3. Service hasn’t finished starting up

Resolution:

1. Check Identity Service

   Verify the Identity service is running and accessible:

   curl https://identity.example.com/.well-known/openid-configuration
   
2. Test Database Connection

   Verify SQL Server connectivity from the API container:

   docker exec -it bitwarden-api bash
   # Test connection using sqlcmd or similar tool
   
3. Check Service Logs

   Review the API service logs for startup errors:

   docker logs bitwarden-api
   

Intermittent Health Check Failures

Symptom: Health checks occasionally fail even when service appears healthy

Common Causes:

1. Network timeouts between services
2. Database connection pool exhaustion
3. Identity service under load

Resolution:

• Increase health check timeout values
• Review database connection pool settings in appsettings.json
• Check Identity service resource allocation

Best Practices

Use Different Endpoints

Use /healthz for liveness probes and /healthz/extended for readiness probes to get appropriate granularity.

Set Appropriate Timeouts

Configure health check timeouts longer than your monitoring interval to avoid false positives.

Monitor Trends

Track health check response times to identify performance degradation before failures occur.

Alert on Patterns

Alert on multiple consecutive failures rather than single failures to reduce noise.

Related Resources

• Logging Configuration
• Metrics and Telemetry
• Troubleshooting Guide