openapi: 3.1.0
info:
  title: CoreDNS Health API
  description: The CoreDNS health plugin exposes an HTTP health check endpoint at /health on port 8080 by default. It reports the overall health of the CoreDNS process and is used by Kubernetes liveness and readiness probes to determine if the DNS server is operational. When lameduck mode is enabled, the health endpoint returns HTTP 503 for a configurable duration before shutdown to allow graceful traffic draining.
  version: 2.x
  contact:
    name: CoreDNS Community
    url: https://coredns.io/community/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://localhost:8080
  description: CoreDNS Health HTTP server (default port, configurable)
tags:
- name: Health
  description: Health check endpoints used by Kubernetes liveness and readiness probes to assess the operational state of the CoreDNS process.
paths:
  /health:
    get:
      operationId: getHealth
      summary: CoreDNS liveness health check
      description: Returns the overall health status of the CoreDNS process. Returns HTTP 200 with body "OK" when CoreDNS is alive and healthy. Returns HTTP 503 during the lameduck shutdown period to signal that the instance is draining and should not receive new traffic. This endpoint is typically used as the Kubernetes liveness probe target.
      tags:
      - Health
      responses:
        '200':
          description: CoreDNS is healthy and alive.
          content:
            text/plain:
              schema:
                type: string
                example: OK
        '503':
          description: CoreDNS is in lameduck mode (shutting down gracefully). The process is still running but draining connections before exit.
          content:
            text/plain:
              schema:
                type: string
                example: lameduck
externalDocs:
  description: CoreDNS Health Plugin Documentation
  url: https://coredns.io/plugins/health/