Traefik Mesh Status API

openapi: 3.2.0
info:
  title: Traefik Mesh Controller Configuration Status API
  description: 'The Traefik Mesh Controller API provides internal debugging and status endpoints for the Traefik Mesh controller pod running in a Kubernetes cluster. It exposes the current dynamic Traefik configuration built by the controller, the mesh topology, the readiness state of the controller, and per-node configuration for each Traefik Mesh proxy node. This API is accessed directly on the controller pod IP at port 9000 and is intentionally not exposed via a Kubernetes Service for security reasons.


    Maintenance status: this surface is documented as of Traefik Mesh v1.4.8 (released 2022-08-19), the most recent tagged release. The project has received only CI and documentation maintenance since then and there is no announced successor from Traefik Labs. Consumers should treat this API as stable in shape but unlikely to evolve.'
  version: 1.4.8
  x-maintenance: dormant
  x-last-release-date: '2022-08-19'
  contact:
    name: Traefik Labs
    url: https://traefik.io/
  license:
    name: Apache 2.0
    url: https://github.com/traefik/mesh/blob/master/LICENSE
servers:
- url: http://controller-pod-ip:9000
  description: Traefik Mesh Controller Pod (direct pod IP access)
tags:
- name: Status
  description: Endpoints for checking the readiness and status of the Traefik Mesh controller and proxy nodes.
paths:
  /api/status/nodes:
    get:
      operationId: getMeshNodes
      summary: Get Mesh Node Status
      description: Returns a JSON array containing details about the readiness and status of all Traefik Mesh proxy nodes visible to the controller. Returns an empty array (HTTP 200) if no nodes are visible.
      tags:
      - Status
      responses:
        '200':
          description: Array of mesh node status objects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PodInfo'
  /api/status/node/{node}/configuration:
    get:
      operationId: getMeshNodeConfiguration
      summary: Get Mesh Node Configuration
      description: Returns the current Traefik configuration running on the specified Traefik Mesh proxy node, identified by its pod name. Returns 404 if the pod cannot be found, or other non-200 status codes on errors. The error message is returned in the body and logged on the controller.
      tags:
      - Status
      parameters:
      - name: node
        in: path
        required: true
        description: The Kubernetes pod name of the Traefik Mesh proxy node.
        schema:
          type: string
        example: traefik-mesh-proxy-abc12
      responses:
        '200':
          description: Current Traefik configuration on the specified node.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DynamicConfiguration'
        '404':
          description: Node pod not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal error retrieving node configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/status/readiness:
    get:
      operationId: getReadiness
      summary: Get Controller Readiness
      description: Returns HTTP 200 if the Traefik Mesh controller has successfully started and is ready to process requests. Returns HTTP 500 if the controller is not yet ready. Used as a readiness probe in Kubernetes deployments.
      tags:
      - Status
      responses:
        '200':
          description: Controller is ready.
          content:
            text/plain:
              schema:
                type: string
                example: OK
        '500':
          description: Controller is not ready.
          content:
            text/plain:
              schema:
                type: string
                example: Not Ready
components:
  schemas:
    PodInfo:
      type: object
      description: Status information about a Traefik Mesh proxy node pod.
      properties:
        Name:
          type: string
          description: Kubernetes pod name of the mesh proxy node.
          example: traefik-mesh-proxy-abc12
        IP:
          type: string
          description: Pod IP address.
          example: 10.0.0.5
        Ready:
          type: boolean
          description: Whether the pod is ready to handle traffic.
          example: true
    ErrorResponse:
      type: object
      description: Error response body.
      properties:
        error:
          type: string
          description: Error message.
          example: pod not found
    DynamicConfiguration:
      type: object
      description: Traefik dynamic configuration object containing HTTP, TCP, and UDP routing rules, middlewares, services, and TLS configuration generated by the Traefik Mesh controller.
      properties:
        http:
          type: object
          description: HTTP routing configuration including routers, services, and middlewares.
          properties:
            routers:
              type: object
              additionalProperties:
                type: object
            services:
              type: object
              additionalProperties:
                type: object
            middlewares:
              type: object
              additionalProperties:
                type: object
        tcp:
          type: object
          description: TCP routing configuration.
          properties:
            routers:
              type: object
              additionalProperties:
                type: object
            services:
              type: object
              additionalProperties:
                type: object
        udp:
          type: object
          description: UDP routing configuration.
          properties:
            routers:
              type: object
              additionalProperties:
                type: object
            services:
              type: object
              additionalProperties:
                type: object
externalDocs:
  description: Traefik Mesh API Documentation
  url: https://doc.traefik.io/traefik-mesh/