> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Arvo-AI/aurora/llms.txt
> Use this file to discover all available pages before exploring further.

# Liveness & Readiness Probes

> Kubernetes-compatible health probe endpoints

## Overview

Aurora provides dedicated liveness and readiness probe endpoints for Kubernetes and container orchestration platforms. These endpoints enable fine-grained health monitoring and automated recovery strategies.

## Liveness Probe

### Endpoint

```bash theme={null}
GET /health/liveness
```

### Description

The liveness probe checks if the Flask application process is running and responsive. This is a lightweight check that doesn't verify external dependencies. Kubernetes uses this to determine if the container should be restarted.

### Response

<ResponseField name="status" type="string" required>
  Always returns `"alive"` if the application is running
</ResponseField>

### Status Codes

<ResponseField name="200" type="status code">
  Application is alive and responsive
</ResponseField>

### Example Response

```json theme={null}
{
  "status": "alive"
}
```

### Usage

#### Kubernetes Configuration

```yaml theme={null}
apiVersion: v1
kind: Pod
metadata:
  name: aurora-server
spec:
  containers:
  - name: aurora-server
    image: aurora:latest
    livenessProbe:
      httpGet:
        path: /health/liveness
        port: 5080
      initialDelaySeconds: 30
      periodSeconds: 10
      timeoutSeconds: 5
      failureThreshold: 3
```

#### cURL

```bash theme={null}
curl http://localhost:5080/health/liveness
```

***

## Readiness Probe

### Endpoint

```bash theme={null}
GET /health/readiness
```

### Description

The readiness probe checks if the application is ready to accept traffic by verifying critical dependencies (database and Redis). Kubernetes uses this to determine if the pod should receive traffic from the service load balancer.

### Response

#### Ready State

<ResponseField name="status" type="string" required>
  Returns `"ready"` when critical services are available
</ResponseField>

#### Not Ready State

<ResponseField name="status" type="string" required>
  Returns `"not_ready"` when critical services are unavailable
</ResponseField>

<ResponseField name="checks" type="object" required>
  Health status of critical services

  <Expandable title="Service Checks">
    <ResponseField name="database" type="object" required>
      PostgreSQL database health status

      <Expandable title="Properties">
        <ResponseField name="status" type="string" required>
          Health status: `healthy` or `unhealthy`
        </ResponseField>

        <ResponseField name="message" type="string">
          Success message when service is healthy
        </ResponseField>

        <ResponseField name="error" type="string">
          Error message when service is unhealthy
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="redis" type="object" required>
      Redis cache health status

      <Expandable title="Properties">
        <ResponseField name="status" type="string" required>
          Health status: `healthy` or `unhealthy`
        </ResponseField>

        <ResponseField name="message" type="string">
          Success message when service is healthy
        </ResponseField>

        <ResponseField name="error" type="string">
          Error message when service is unhealthy
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Status Codes

<ResponseField name="200" type="status code">
  Application is ready to accept traffic (both database and Redis are healthy)
</ResponseField>

<ResponseField name="503" type="status code">
  Application is not ready (database or Redis is unhealthy)
</ResponseField>

### Example Responses

#### Ready

```json theme={null}
{
  "status": "ready"
}
```

#### Not Ready

```json theme={null}
{
  "status": "not_ready",
  "checks": {
    "database": {
      "status": "unhealthy",
      "error": "Database connection failed"
    },
    "redis": {
      "status": "healthy",
      "message": "Redis connection successful"
    }
  }
}
```

### Usage

#### Kubernetes Configuration

```yaml theme={null}
apiVersion: v1
kind: Pod
metadata:
  name: aurora-server
spec:
  containers:
  - name: aurora-server
    image: aurora:latest
    readinessProbe:
      httpGet:
        path: /health/readiness
        port: 5080
      initialDelaySeconds: 10
      periodSeconds: 5
      timeoutSeconds: 3
      successThreshold: 1
      failureThreshold: 3
```

#### cURL

```bash theme={null}
curl http://localhost:5080/health/readiness
```

#### JavaScript

```javascript theme={null}
const checkReadiness = async () => {
  try {
    const response = await fetch('http://localhost:5080/health/readiness');
    
    if (response.ok) {
      console.log('Service is ready');
      return true;
    } else {
      const data = await response.json();
      console.error('Service not ready:', data.checks);
      return false;
    }
  } catch (error) {
    console.error('Readiness check failed:', error);
    return false;
  }
};

// Poll until ready
const waitForReady = async (maxAttempts = 10, delayMs = 2000) => {
  for (let i = 0; i < maxAttempts; i++) {
    if (await checkReadiness()) {
      return true;
    }
    await new Promise(resolve => setTimeout(resolve, delayMs));
  }
  throw new Error('Service did not become ready in time');
};
```

#### Python

```python theme={null}
import requests
import time

def check_readiness():
    try:
        response = requests.get('http://localhost:5080/health/readiness')
        
        if response.status_code == 200:
            print('Service is ready')
            return True
        else:
            data = response.json()
            print(f"Service not ready: {data.get('checks')}")
            return False
    except requests.RequestException as e:
        print(f"Readiness check failed: {e}")
        return False

def wait_for_ready(max_attempts=10, delay_seconds=2):
    """Poll until service is ready."""
    for i in range(max_attempts):
        if check_readiness():
            return True
        time.sleep(delay_seconds)
    raise RuntimeError('Service did not become ready in time')
```

***

## Probe Comparison

| Aspect             | Liveness Probe                        | Readiness Probe                         |
| ------------------ | ------------------------------------- | --------------------------------------- |
| **Purpose**        | Detect if application is hung/crashed | Detect if application can serve traffic |
| **Checks**         | Application process only              | Database + Redis                        |
| **Failure Action** | Restart container                     | Remove from load balancer               |
| **Response Time**  | Very fast (\~1ms)                     | Moderate (\~50-100ms)                   |
| **Use When**       | Container orchestration               | Load balancing                          |

## Best Practices

### Liveness Probe Configuration

* **Initial Delay**: Set `initialDelaySeconds` to allow application startup (30-60 seconds)
* **Period**: Check frequently (10-30 seconds)
* **Timeout**: Keep short (5 seconds)
* **Threshold**: Allow 2-3 failures before restart to avoid flapping

### Readiness Probe Configuration

* **Initial Delay**: Short delay (10-15 seconds) as dependencies should start first
* **Period**: Check frequently (5-10 seconds) for fast recovery
* **Timeout**: Moderate timeout (3-5 seconds)
* **Threshold**: Single success to start receiving traffic, 2-3 failures to stop

### Combined Configuration Example

```yaml theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: aurora-server
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: aurora-server
        image: aurora:latest
        ports:
        - containerPort: 5080
        
        livenessProbe:
          httpGet:
            path: /health/liveness
            port: 5080
          initialDelaySeconds: 30
          periodSeconds: 10
          timeoutSeconds: 5
          failureThreshold: 3
        
        readinessProbe:
          httpGet:
            path: /health/readiness
            port: 5080
          initialDelaySeconds: 10
          periodSeconds: 5
          timeoutSeconds: 3
          successThreshold: 1
          failureThreshold: 3
        
        startupProbe:
          httpGet:
            path: /health/liveness
            port: 5080
          initialDelaySeconds: 0
          periodSeconds: 5
          timeoutSeconds: 3
          failureThreshold: 12  # 60 seconds total
```

## Monitoring Recommendations

### Metrics to Track

1. **Liveness Failures**: Alert on repeated liveness failures indicating application crashes
2. **Readiness Failures**: Track dependency health issues (database, Redis)
3. **Recovery Time**: Monitor time from not-ready to ready state
4. **Probe Response Time**: Detect performance degradation

### Alert Examples

```yaml theme={null}
# Prometheus AlertManager rules
groups:
- name: aurora-health
  rules:
  - alert: AuroraLivenessFailure
    expr: probe_success{job="aurora-liveness"} == 0
    for: 1m
    annotations:
      summary: "Aurora liveness probe failing"
      description: "Application may be hung or crashed"
  
  - alert: AuroraNotReady
    expr: probe_success{job="aurora-readiness"} == 0
    for: 3m
    annotations:
      summary: "Aurora not ready to serve traffic"
      description: "Check database and Redis connectivity"
```

## Related Endpoints

* [Health Status](/api/health/status) - Comprehensive health check for all services