openapi: 3.2.0
info:
  title: HAProxy Data Plane Ring API
  description: 'API for editing and managing haproxy instances. Provides process information, configuration management,

    haproxy stats and logs.'
  version: '3.4'
  contact:
    name: HAProxy Support
    url: https://my.haproxy.com/portal/cust/login
    email: support@haproxy.com
servers:
- url: /v3
security:
- basic_auth: []
tags:
- name: Ring
paths:
  /services/haproxy/configuration/rings:
    get:
      description: Returns an array of all configured rings.
      operationId: getRings
      parameters:
      - $ref: '#/components/parameters/transaction_id'
      - $ref: '#/components/parameters/full_section'
      responses:
        '200':
          description: Successful operation
          headers:
            Configuration-Version:
              description: Configuration file version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rings'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Return an array of rings
      tags:
      - Ring
    post:
      description: Adds a new ring to the configuration file.
      operationId: createRing
      parameters:
      - $ref: '#/components/parameters/transaction_id'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/force_reload'
      - $ref: '#/components/parameters/full_section'
      responses:
        '201':
          description: Ring created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ring'
        '202':
          description: Configuration change accepted and reload requested
          headers:
            Reload-ID:
              description: ID of the requested reload
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ring'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/AlreadyExists'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Add a ring
      tags:
      - Ring
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ring'
        required: true
  /services/haproxy/configuration/rings/{name}:
    delete:
      description: Deletes a ring from the configuration by it's name.
      operationId: deleteRing
      parameters:
      - description: Ring name
        in: path
        name: name
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/transaction_id'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/force_reload'
      responses:
        '202':
          description: Configuration change accepted and reload requested
          headers:
            Reload-ID:
              description: ID of the requested reload
              schema:
                type: string
        '204':
          description: Ring deleted
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Delete a ring
      tags:
      - Ring
    get:
      description: Returns one ring configuration by it's name.
      operationId: getRing
      parameters:
      - description: Ring name
        in: path
        name: name
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/transaction_id'
      - $ref: '#/components/parameters/full_section'
      responses:
        '200':
          description: Successful operation
          headers:
            Configuration-Version:
              description: Configuration file version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ring'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Return a ring
      tags:
      - Ring
    put:
      description: Replaces a ring configuration by it's name.
      operationId: replaceRing
      parameters:
      - description: Ring name
        in: path
        name: name
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/transaction_id'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/force_reload'
      - $ref: '#/components/parameters/full_section'
      responses:
        '200':
          description: Ring replaced
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ring'
        '202':
          description: Configuration change accepted and reload requested
          headers:
            Reload-ID:
              description: ID of the requested reload
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ring'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/DefaultError'
      summary: Replace a ring
      tags:
      - Ring
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ring'
        required: true
components:
  parameters:
    transaction_id:
      name: transaction_id
      in: query
      description: ID of the transaction where we want to add the operation. Cannot be used when version is specified.
      required: false
      schema:
        type: string
    full_section:
      name: full_section
      in: query
      description: Indicates if the action affects the specified child resources as well
      required: false
      schema:
        type: boolean
        default: false
    version:
      name: version
      in: query
      description: Version used for checking configuration version. Cannot be used when transaction is specified, transaction has it's own version.
      required: false
      schema:
        type: integer
    force_reload:
      name: force_reload
      in: query
      description: If set, do a force reload, do not wait for the configured reload-delay. Cannot be used when transaction is specified, as changes in transaction are not applied directly to configuration.
      required: false
      schema:
        type: boolean
        default: false
  schemas:
    ring:
      allOf:
      - $ref: '#/components/schemas/ring_base'
      - properties:
          servers:
            additionalProperties:
              $ref: '#/components/schemas/server'
        type: object
      description: Ring with all its children resources
      type: object
      x-go-name: Ring
    ring_base:
      additionalProperties: false
      description: HAProxy ring configuration
      properties:
        description:
          description: The description is an optional description string of the ring
          type: string
        format:
          description: Format used to store events into the ring buffer
          enum:
          - iso
          - local
          - raw
          - rfc3164
          - rfc5424
          - short
          - priority
          - timed
          type: string
        maxlen:
          description: The maximum length of an event message stored into the ring
          type:
          - integer
          - 'null'
        metadata:
          additionalProperties:
            type: object
        name:
          pattern: ^[A-Za-z0-9-_.:]+$
          type: string
        size:
          description: Optional size in bytes for the ring-buffer
          minimum: 0
          type:
          - integer
          - 'null'
          x-size: true
        timeout_connect:
          minimum: 0
          type:
          - integer
          - 'null'
          x-default-unit: ms
          x-duration: true
        timeout_server:
          minimum: 0
          type:
          - integer
          - 'null'
          x-default-unit: ms
          x-duration: true
      required:
      - name
      title: Ring Base
      type: object
    error:
      additionalProperties:
        type: string
      description: API Error
      properties:
        code:
          type:
          - integer
          - 'null'
        message:
          type:
          - string
          - 'null'
      required:
      - code
      - message
      title: Error
      type: object
    rings:
      title: Rings
      description: HAProxy rings array
      type: array
      items:
        $ref: '#/components/schemas/ring'
    server:
      additionalProperties: false
      allOf:
      - $ref: '#/components/schemas/server_params'
      - properties:
          address:
            pattern: ^[^\s]+$
            type: string
          id:
            type:
            - integer
            - 'null'
          metadata:
            additionalProperties:
              type: object
          name:
            pattern: ^[^\s]+$
            type: string
          port:
            maximum: 65535
            minimum: 1
            type:
            - integer
            - 'null'
        required:
        - name
        - address
        type: object
      description: HAProxy backend server configuration
      example:
        address: 10.1.1.1
        name: www
        port: 8080
      title: Server
    server_params:
      properties:
        agent-addr:
          pattern: ^[^\s]+$
          type: string
        agent-check:
          enum:
          - enabled
          - disabled
          type: string
          x-dependency:
            agent-port:
              required: true
        agent-inter:
          minimum: 0
          type:
          - integer
          - 'null'
          x-default-unit: ms
          x-duration: true
        agent-port:
          maximum: 65535
          minimum: 1
          type:
          - integer
          - 'null'
        agent-send:
          type: string
        allow_0rtt:
          type: boolean
        alpn:
          pattern: ^[^\s]+$
          type: string
          x-display-name: ALPN Protocols
        backup:
          enum:
          - enabled
          - disabled
          type: string
        cc:
          type: string
          x-display-name: TCP Congestion Control Algorithm
        check:
          enum:
          - enabled
          - disabled
          type: string
        check-pool-conn-name:
          pattern: ^[^\s]+$
          type: string
        check-reuse-pool:
          enum:
          - enabled
          - disabled
          type: string
        check-send-proxy:
          enum:
          - enabled
          - disabled
          type: string
        check-sni:
          pattern: ^[^\s]+$
          type: string
        check-ssl:
          enum:
          - enabled
          - disabled
          type: string
        check_alpn:
          pattern: ^[^\s]+$
          type: string
          x-display-name: Protocols
        check_proto:
          pattern: ^[^\s]+$
          type: string
          x-display-name: Name
        check_sni_auto:
          enum:
          - enabled
          - disabled
          type: string
        check_via_socks4:
          enum:
          - enabled
          - disabled
          type: string
        ciphers:
          type: string
          x-dependency:
            ssl:
              value: enabled
        ciphersuites:
          type: string
          x-dependency:
            ssl:
              value: enabled
        client_sigalgs:
          type: string
          x-dependency:
            ssl:
              value: true
        cookie:
          pattern: ^[^\s]+$
          type: string
        crl_file:
          type: string
          x-dependency:
            ssl:
              value: enabled
        curves:
          type: string
          x-dependency:
            ssl:
              value: true
        downinter:
          minimum: 0
          type:
          - integer
          - 'null'
          x-default-unit: ms
          x-duration: true
        error_limit:
          type: integer
          x-display-name: Error count
        fall:
          type:
          - integer
          - 'null'
          x-display-name: Nr. of consecutive failed checks
        fastinter:
          minimum: 0
          type:
          - integer
          - 'null'
          x-default-unit: ms
          x-duration: true
        force_sslv3:
          description: This field is deprecated in favor of sslv3, and will be removed in a future release
          enum:
          - enabled
          - disabled
          type: string
          x-deprecated: true
        force_tlsv10:
          description: This field is deprecated in favor of tlsv10, and will be removed in a future release
          enum:
          - enabled
          - disabled
          type: string
          x-deprecated: true
        force_tlsv11:
          description: This field is deprecated in favor of tlsv11, and will be removed in a future release
          enum:
          - enabled
          - disabled
          type: string
          x-deprecated: true
        force_tlsv12:
          description: This field is deprecated in favor of tlsv12, and will be removed in a future release
          enum:
          - enabled
          - disabled
          type: string
          x-deprecated: true
        force_tlsv13:
          description: This field is deprecated in favor of tlsv13, and will be removed in a future release
          enum:
          - enabled
          - disabled
          type: string
          x-deprecated: true
        guid:
          pattern: ^[A-Za-z0-9-_.:]+$
          type: string
        hash_key:
          pattern: ^[^\s]+$
          type: string
        health_check_address:
          pattern: ^[^\s]+$
          type: string
        health_check_port:
          maximum: 65535
          minimum: 1
          type:
          - integer
          - 'null'
        idle_ping:
          minimum: 0
          type:
          - integer
          - 'null'
          x-default-unit: ms
          x-duration: true
        init-addr:
          pattern: ^[^\s]+$
          type:
          - string
          - 'null'
        init-state:
          enum:
          - fully-up
          - up
          - down
          - fully-down
          type: string
        inter:
          minimum: 0
          type:
          - integer
          - 'null'
          x-default-unit: ms
          x-duration: true
        ktls:
          enum:
          - 'on'
          - 'off'
          type: string
          x-display-name: 'Enables or disables ktls for those sockets. If enabled, kTLS will be used if the kernel supports it and the cipher is compatible.

            This is only available on Linux kernel 4.17 and above.

            EXPERIMENTAL OPTION.'
        log-bufsize:
          type:
          - integer
          - 'null'
        log_proto:
          enum:
          - legacy
          - octet-count
          type: string
        maintenance:
          enum:
          - enabled
          - disabled
          type: string
        max_reuse:
          type:
          - integer
          - 'null'
        maxconn:
          type:
          - integer
          - 'null'
          x-display-name: Max Concurrent Connections
        maxqueue:
          type:
          - integer
          - 'null'
          x-display-name: Max Number of Connections
        minconn:
          type:
          - integer
          - 'null'
        namespace:
          type: string
        no_sslv3:
          description: This field is deprecated in favor of sslv3, and will be removed in a future release
          enum:
          - enabled
          - disabled
          type: string
          x-deprecated: true
        no_tlsv10:
          description: This field is deprecated in favor of tlsv10, and will be removed in a future release
          enum:
          - enabled
          - disabled
          type: string
          x-deprecated: true
        no_tlsv11:
          description: This field is deprecated in favor of tlsv11, and will be removed in a future release
          enum:
          - enabled
          - disabled
          type: string
          x-deprecated: true
        no_tlsv12:
          description: This field is deprecated in favor of tlsv12, and will be removed in a future release
          enum:
          - enabled
          - disabled
          type: string
          x-deprecated: true
        no_tlsv13:
          description: This field is deprecated in favor of force_tlsv13, and will be removed in a future release
          enum:
          - enabled
          - disabled
          type: string
          x-deprecated: true
        no_verifyhost:
          enum:
          - enabled
          - disabled
          type: string
        npn:
          type: string
          x-dependency:
            ssl:
              value: enabled
        observe:
          enum:
          - layer4
          - layer7
          type: string
          x-dependency:
            ssl:
              value: enabled
        on-error:
          enum:
          - fastinter
          - fail-check
          - sudden-death
          - mark-down
          type: string
        on-marked-down:
          enum:
          - shutdown-sessions
          type: string
        on-marked-up:
          enum:
          - shutdown-backup-sessions
          type: string
        pool_conn_name:
          pattern: ^[^\s]+$
          type: string
        pool_low_conn:
          type:
          - integer
          - 'null'
        pool_max_conn:
          type:
          - integer
          - 'null'
        pool_purge_delay:
          minimum: 0
          type:
          - integer
          - 'null'
          x-default-unit: ms
          x-duration: true
        proto:
          pattern: ^[^\s]+$
          type: string
        proxy-v2-options:
          items:
            enum:
            - authority
            - cert-cn
            - cert-key
            - cert-sig
            - crc32c
            - ssl
            - ssl-cipher
            - unique-id
            type: string
          type: array
          x-omitempty: true
        quic-cc-algo:
          enum:
          - cubic
          - newreno
          - bbr
          - nocc
          type: string
        quic_cc_algo_max_window:
          maximum: 4194304
          minimum: 10
          type:
          - integer
          - 'null'
          x-default-unit: k
          x-dependency:
            quic-cc-algo: null
          x-size: true
        redir:
          type: string
          x-display-name: Prefix
        renegotiate:
          description: Toggles the secure renegotiation mechanism for an SSL backend.
          enum:
          - enabled
          - disabled
          type: string
        resolve-net:
          pattern: ^([A-Za-z0-9.:/]+)(,[A-Za-z0-9.:/]+)*$
          type: string
        resolve-prefer:
          enum:
          - ipv4
          - ipv6
          type: string
        resolve_opts:
          pattern: ^(allow-dup-ip|ignore-weight|prevent-dup-ip)(,(allow-dup-ip|ignore-weight|prevent-dup-ip))*$
          type: string
        resolvers:
          pattern: ^[^\s]+$
          type: string
          x-dynamic-enum:
            operation: getResolvers
            property: name
        rise:
          type:
          - integer
          - 'null'
        send-proxy:
          enum:
          - enabled
          - disabled
          type: string
        send-proxy-v2:
          enum:
          - enabled
          - disabled
          type: string
        send_proxy_v2_ssl:
          enum:
          - enabled
          - disabled
          type: string
        send_proxy_v2_ssl_cn:
          enum:
          - enabled
          - disabled
          type: string
        set-proxy-v2-tlv-fmt:
          properties:
            id:
              type: string
            value:
              type: string
          required:
          - id
          - value
          type: object
        shard:
          type: integer
        sigalgs:
          type: string
          x-dependency:
            ssl:
              value: true
        slowstart:
          minimum: 0
          type:
          - integer
          - 'null'
          x-default-unit: ms
          x-duration: true
        sni:
          pattern: ^[^\s]+$
          type: string
        sni_auto:
          enum:
          - enabled
          - disabled
          type: string
        socks4:
          pattern: ^[^\s]+$
          type: string
          x-dependency:
            check-via-socks4:
              required: true
        source:
          type: string
        ssl:
          enum:
          - enabled
          - disabled
          type: string
        ssl_cafile:
          pattern: ^[^\s]+$
          type: string
          x-dependency:
            ssl:
              value: enabled
          x-display-name: SSL CA File
        ssl_certificate:
          pattern: ^[^\s]+$
          type: string
          x-dependency:
            ssl:
              value: enabled
        ssl_max_ver:
          enum:
          - SSLv3
          - TLSv1.0
          - TLSv1.1
          - TLSv1.2
          - TLSv1.3
          type: string
        ssl_min_ver:
          enum:
          - SSLv3
          - TLSv1.0
          - TLSv1.1
          - TLSv1.2
          - TLSv1.3
          type: string
        ssl_reuse:
          enum:
          - enabled
          - disabled
          type: string
        sslv3:
          enum:
          - enabled
          - disabled
          type: string
        stick:
          enum:
          - enabled
          - disabled
          type: string
        strict-maxconn:
          type: boolean
        tcp_md5sig:
          pattern: ^[^\s]+$
          type: string
        tcp_ut:
          minimum: 0
          type:
          - integer
          - 'null'
          x-default-unit: ms
          x-duration: true
        tfo:
          enum:
          - enabled
          - disabled
          type: string
        tls_tickets:
          enum:
          - enabled
          - disabled
          type: string
          x-dependency:
            ssl:
              value: enabled
        tlsv10:
          enum:
          - enabled
          - disabled
          type: string
        tlsv11:
          enum:
          - enabled
          - disabled
          type: string
        tlsv12:
          enum:
          - enabled
          - disabled
          type: string
        tlsv13:
          enum:
          - enabled
          - disabled
          type: string
        track:
          type: string
        verify:
          enum:
          - none
          - required
          type: string
          x-dependency:
            ssl:
              value: enabled
        verifyhost:
          type: string
          x-dependency:
            ssl:
              value: enabled
            verify:
              value: required
        weight:
          type:
          - integer
          - 'null'
        ws:
          enum:
          - auto
          - h1
          - h2
          type: string
          x-display-name: Relaying websocket stream protocol
      type: object
  responses:
    DefaultError:
      description: General Error
      headers:
        Configuration-Version:
          description: Configuration file version
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    NotFound:
      description: The specified resource was not found
      headers:
        Configuration-Version:
          description: Configuration file version
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    BadRequest:
      description: Bad request
      headers:
        Configuration-Version:
          description: Configuration file version
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    AlreadyExists:
      description: The specified resource already exists
      headers:
        Configuration-Version:
          description: Configuration file version
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic
externalDocs:
  url: https://docs.haproxy.org/
  description: HAProxy Documentation