Traefik Mesh Controller API

openapi: 3.1.0
info:
  title: Traefik Mesh Controller 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
externalDocs:
  description: Traefik Mesh API Documentation
  url: https://doc.traefik.io/traefik-mesh/
servers:
  - url: http://controller-pod-ip:9000
    description: Traefik Mesh Controller Pod (direct pod IP access)
tags:
  - name: Configuration
    description: >-
      Endpoints for retrieving the current dynamic Traefik configuration
      generated by the Traefik Mesh controller.
  - name: Status
    description: >-
      Endpoints for checking the readiness and status of the Traefik Mesh
      controller and proxy nodes.
  - name: Topology
    description: >-
      Endpoints for inspecting the mesh topology as seen by the controller.
paths:
  /api/configuration/current:
    get:
      operationId: getCurrentConfiguration
      summary: Get Current Controller Configuration
      description: >-
        Returns the current dynamic Traefik configuration built by the Traefik
        Mesh controller. This is the live configuration that the controller has
        computed from Kubernetes services, SMI resources, and annotations. The
        response may differ between requests as it reflects real-time state.
      tags:
        - Configuration
      responses:
        '200':
          description: Current dynamic configuration as raw JSON.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DynamicConfiguration'
  /api/topology/current:
    get:
      operationId: getCurrentTopology
      summary: Get Current Mesh Topology
      description: >-
        Returns the current mesh topology as seen by the Traefik Mesh
        controller, including all discovered services, pods, and their
        relationships within the Kubernetes cluster.
      tags:
        - Topology
      responses:
        '200':
          description: Current mesh topology as raw JSON.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeshTopology'
  /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
    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
    MeshTopology:
      type: object
      description: >-
        The mesh topology as computed by the Traefik Mesh controller, including
        all discovered Kubernetes services, pods, and traffic relationships.
      properties:
        services:
          type: object
          description: Map of discovered Kubernetes services in the mesh.
          additionalProperties:
            $ref: '#/components/schemas/ServiceEntry'
        pods:
          type: object
          description: Map of pods participating in the mesh.
          additionalProperties:
            type: object
    ServiceEntry:
      type: object
      description: A Kubernetes service entry in the mesh topology.
      properties:
        name:
          type: string
          description: Service name.
        namespace:
          type: string
          description: Kubernetes namespace.
        ports:
          type: array
          items:
            type: integer
          description: Exposed service ports.
        trafficType:
          type: string
          enum: [http, tcp, udp]
          description: Traffic type for this service.
    ErrorResponse:
      type: object
      description: Error response body.
      properties:
        error:
          type: string
          description: Error message.
          example: pod not found