---
title: Health Checks
description: Monitor and manage upstream health
---

# Health Checks

Octopus can monitor upstream health and remove unhealthy instances from rotation.
Health checks are configured per upstream under `health_check`. Required fields
are `type` (`http`, `tcp`, or `grpc`), `interval`, and `timeout`.

<Callout type="warn" title="Wired on the operator path">
  Active health checking is wired into the live runtime on the
  Kubernetes/operator-driven path. For upstreams registered from a **static
  config file**, the `health_check` block is parsed and validated but not yet
  enforced. See [Upstreams](/docs/octopus/configuration/upstreams). Inside Kubernetes,
  endpoint readiness from EndpointSlice discovery also drives instance health —
  see [Kubernetes discovery](/docs/octopus/kubernetes/discovery).
</Callout>

## Types

### HTTP Health Check

```yaml
upstreams:
  - name: api-service
    health_check:
      type: http
      path: /healthz
      interval: 10s
      timeout: 2s
      healthy_threshold: 2
      unhealthy_threshold: 3
    instances:
      - id: api-1
        host: 10.0.0.11
        port: 8080
```

### TCP Health Check

```yaml
upstreams:
  - name: redis
    health_check:
      type: tcp
      interval: 5s
      timeout: 3s
    instances:
      - id: redis-1
        host: 10.0.0.41
        port: 6379
```

### gRPC Health Check

```yaml
upstreams:
  - name: grpc-service
    health_check:
      type: grpc
      interval: 10s
      timeout: 2s
    instances:
      - id: grpc-1
        host: 10.0.0.51
        port: 50051
```

## Thresholds

`healthy_threshold` (default `2`) is the number of consecutive successes before
an instance is marked healthy; `unhealthy_threshold` (default `3`) is the number
of consecutive failures before it is marked unhealthy. The gateway actively polls
each instance every `interval`, failing a check after `timeout`.

## Health States

- **Healthy**: Passing health checks
- **Unhealthy**: Failing health checks
- **Degraded**: Intermittent failures
- **Unknown**: Not yet checked

## Monitoring

```bash
# View health status
curl http://gateway:9090/_/health

# Prometheus metrics
octopus_upstream_health{upstream="api-service",instance="api-1"}
```

## See Also

- [Load Balancing](/docs/octopus/concepts/load-balancing)
- [Circuit Breaker](/docs/octopus/concepts/circuit-breaker)