Canonical Network Load Balancer Pools API

openapi: 3.2.0
info:
  contact:
    email: lxd@lists.canonical.com
    name: LXD upstream
    url: https://github.com/canonical/lxd
  description: 'This is the REST API used by all LXD clients.

    Internal endpoints aren''t included in this documentation.


    The LXD API is available over both a local unix+http and remote https API.

    Authentication for local users relies on group membership and access to the unix socket.

    For remote users, the default authentication method is TLS client.'
  license:
    name: AGPL-3.0-only
    url: https://www.gnu.org/licenses/agpl-3.0.en.html
  title: LXD external REST Network Load Balancer Pools API
  version: '1.0'
tags:
- name: network-load-balancer-pools
paths:
  /1.0/networks/{networkName}/load-balancer-pools:
    get:
      description: Retrieves a list of network load balancer pools.
      operationId: network_load_balancer_pools_get
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '200':
          description: API endpoints
          content:
            application/json:
              schema:
                description: Sync response
                properties:
                  metadata:
                    description: List of network load balancer pools
                    items:
                      $ref: '#/components/schemas/NetworkLoadBalancerPool'
                    type: array
                  status:
                    description: Status description
                    example: Success
                    type: string
                  status_code:
                    description: Status code
                    example: 200
                    type: integer
                  type:
                    description: Response type
                    example: sync
                    type: string
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: List network load balancer pools
      tags:
      - network-load-balancer-pools
    post:
      description: Creates a new network load balancer pool.
      operationId: network_load_balancer_pools_post
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '202':
          $ref: '#/components/responses/Operation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Add a network load balancer pool
      tags:
      - network-load-balancer-pools
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NetworkLoadBalancerPoolsPost'
        description: Load balancer pool
        required: true
  /1.0/networks/{networkName}/load-balancer-pools/{poolName}:
    delete:
      description: Removes a specific network load balancer pool.
      operationId: network_load_balancer_pool_delete
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '202':
          $ref: '#/components/responses/Operation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Delete a network load balancer pool
      tags:
      - network-load-balancer-pools
    get:
      description: Retrieves a specific network load balancer pool.
      operationId: network_load_balancer_pool_get
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '200':
          description: API endpoints
          content:
            application/json:
              schema:
                description: Sync response
                properties:
                  metadata:
                    $ref: '#/components/schemas/NetworkLoadBalancerPool'
                  status:
                    description: Status description
                    example: Success
                    type: string
                  status_code:
                    description: Status code
                    example: 200
                    type: integer
                  type:
                    description: Response type
                    example: sync
                    type: string
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get a network load balancer pool
      tags:
      - network-load-balancer-pools
    put:
      description: Updates the configuration of a specific network load balancer pool.
      operationId: network_load_balancer_pool_put
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '202':
          $ref: '#/components/responses/Operation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Update a network load balancer pool
      tags:
      - network-load-balancer-pools
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NetworkLoadBalancerPoolPut'
        description: Address load balancer pool configuration
        required: true
  /1.0/networks/{networkName}/load-balancer-pools/{poolName}/state:
    get:
      description: Retrieves the state of a specific network load balancer pool.
      operationId: network_load_balancer_pool_state_get
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '200':
          description: API endpoints
          content:
            application/json:
              schema:
                description: Sync response
                properties:
                  metadata:
                    $ref: '#/components/schemas/NetworkLoadBalancerPoolState'
                  status:
                    description: Status description
                    example: Success
                    type: string
                  status_code:
                    description: Status code
                    example: 200
                    type: integer
                  type:
                    description: Response type
                    example: sync
                    type: string
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get the state of a network load balancer pool
      tags:
      - network-load-balancer-pools
components:
  schemas:
    NetworkLoadBalancerPoolsPost:
      properties:
        config:
          additionalProperties:
            type: string
          description: Load balancer pool configuration map (refer to doc/howto/network_load_balancers.md)
          example:
            protocol: tcp
          type: object
          x-go-name: Config
        description:
          description: Description of the load balancer pool.
          example: My HTTPS load balancer pool
          type: string
          x-go-name: Description
        instances:
          description: List of instances in the pool.
          example:
          - name: c1
          - name: c2
            target_port: '8443'
          items:
            $ref: '#/components/schemas/NetworkLoadBalancerPoolInstance'
          type: array
          x-go-name: Instances
        name:
          description: The name of the load balancer pool.
          example: https
          type: string
          x-go-name: Name
      title: NetworkLoadBalancerPoolsPost represents the fields of a new LXD network load balancer pool.
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    StatusCode:
      format: int64
      title: StatusCode represents a valid LXD operation and container status.
      type: integer
      x-go-package: github.com/canonical/lxd/shared/api
    NetworkLoadBalancerPoolState:
      properties:
        targets:
          description: Actual targets in the pool with their status.
          items:
            $ref: '#/components/schemas/NetworkLoadBalancerPoolTarget'
          type: array
          x-go-name: Targets
      title: NetworkLoadBalancerPoolState represents the state of a network load balancer pool.
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    NetworkLoadBalancerPool:
      properties:
        config:
          additionalProperties:
            type: string
          description: Load balancer pool configuration map (refer to doc/howto/network_load_balancers.md)
          example:
            protocol: tcp
          type: object
          x-go-name: Config
        description:
          description: Description of the load balancer pool.
          example: My HTTPS load balancer pool
          type: string
          x-go-name: Description
        instances:
          description: Instances included in the pool.
          example:
          - name: i1
          - name: i2
            target_port: '8443'
          items:
            $ref: '#/components/schemas/NetworkLoadBalancerPoolInstance'
          type: array
          x-go-name: Instances
        name:
          description: The name of the load balancer pool.
          example: https
          type: string
          x-go-name: Name
        used_by:
          description: UsedBy is a list of LXD entity URLs that reference this load balancer pool.
          example:
          - /1.0/networks/default/load-balancers/192.0.2.1
          items:
            type: string
          type: array
          x-go-name: UsedBy
      title: NetworkLoadBalancerPool used for displaying a network load balancer pool.
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    NetworkLoadBalancerPoolTarget:
      description: 'If an instance has both IPv4 and IPv6 addresses on the same network interface,

        those are represented as two targets inside the pool.

        Each target has its own health check with its own status.'
      properties:
        address:
          description: Address represents the address of the target.
          example: 198.51.100.2
          type: string
          x-go-name: Address
        device:
          description: Device represents the target instance's network device.
          example: eth0
          type: string
          x-go-name: Device
        listen_address:
          description: ListenAddress represents the address of the target's parent load balancer.
          example: 1.2.3.4
          type: string
          x-go-name: ListenAddress
        listen_port:
          description: ListenPort represents the port of the target's parent load balancer.
          example: '443'
          type: string
          x-go-name: ListenPort
        name:
          description: Name represents the target instance's name.
          example: c1
          type: string
          x-go-name: Name
        port:
          description: Port represents the port probed on the target's address.
          example: '8443'
          type: string
          x-go-name: Port
        status:
          description: 'Status represents the status of the target address.

            It can be one of:

            error   indicates an error occurred while probing the target address.

            offline indicates the target address is not responding to probes.

            online  indicates the target address is responding to probes.

            pending indicates the target address is pending to being probed.

            unknown indicates that the targeted instance is not running and there is no service monitor configured, or that health checks are disabled on the pool.'
          example: online
          type: string
          x-go-name: Status
      title: NetworkLoadBalancerPoolTarget represents the actual targets on a pool's instance.
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    NetworkLoadBalancerPoolInstance:
      description: An instance can have multiple targets depending on how many addresses it has in the pool's network.
      properties:
        name:
          description: The name of the instance in the pool.
          example: i1
          type: string
          x-go-name: Name
        target_port:
          description: Optional target port to override the pool's default target port.
          example: '8443'
          type: string
          x-go-name: TargetPort
      title: NetworkLoadBalancerPoolInstance represents an instance in a load balancer pool.
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    Operation:
      description: Operation represents a LXD background operation
      properties:
        child_count:
          description: 'Number of child operations.


            API extension: operation_child_count'
          example: 2
          format: int64
          type: integer
          x-go-name: ChildCount
        class:
          description: Type of operation (task, token or websocket)
          example: websocket
          type: string
          x-go-name: Class
        created_at:
          description: Operation creation time
          example: '2021-03-23T17:38:37.753398689-04:00'
          format: date-time
          type: string
          x-go-name: CreatedAt
        description:
          description: Description of the operation
          example: Executing command
          type: string
          x-go-name: Description
        err:
          description: Operation error message
          example: Some error message
          type: string
          x-go-name: Err
        err_code:
          description: 'Operation error code


            API extension: bulk_operations'
          example: 404
          format: int64
          type: integer
          x-go-name: ErrCode
        id:
          description: UUID of the operation
          example: 6916c8a6-9b7d-4abd-90b3-aedfec7ec7da
          type: string
          x-go-name: ID
        location:
          description: 'Which cluster member this record was found on


            API extension: operation_location'
          example: lxd01
          type: string
          x-go-name: Location
        may_cancel:
          description: Whether the operation can be canceled
          example: false
          type: boolean
          x-go-name: MayCancel
        metadata:
          additionalProperties: {}
          description: Operation specific metadata
          example:
            command:
            - bash
            environment:
              HOME: /root
              LANG: C.UTF-8
              PATH: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
              TERM: xterm
              USER: root
            fds:
              '0': da3046cf02c0116febf4ef3fe4eaecdf308e720c05e5a9c730ce1a6f15417f66
              '1': 05896879d8692607bd6e4a09475667da3b5f6714418ab0ee0e5720b4c57f754b
            interactive: true
          type: object
          x-go-name: Metadata
        requestor:
          $ref: '#/components/schemas/OperationRequestor'
        resources:
          additionalProperties:
            items:
              type: string
            type: array
          description: Affected resources
          example:
            instances:
            - /1.0/instances/foo
            - /1.0/instances/bar
          type: object
          x-go-name: Resources
        status:
          description: Status name
          example: Running
          type: string
          x-go-name: Status
        status_code:
          $ref: '#/components/schemas/StatusCode'
        updated_at:
          description: Operation last change
          example: '2021-03-23T17:38:37.753398689-04:00'
          format: date-time
          type: string
          x-go-name: UpdatedAt
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    OperationRequestor:
      description: 'API extension: operation_requestor.'
      properties:
        address:
          description: Address is the origin address of the request.
          example: 10.0.2.15
          type: string
          x-go-name: Address
        protocol:
          description: Protocol represents the method used to authenticate the requestor.
          example: oidc
          type: string
          x-go-name: Protocol
        username:
          description: Username is the username of the requestor. This is the identifier of the identity, or the username if using the unix socket.
          example: jane.doe@example.com
          type: string
          x-go-name: Username
      title: OperationRequestor represents the initial requestor of an operation
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    NetworkLoadBalancerPoolPut:
      properties:
        config:
          additionalProperties:
            type: string
          description: Load balancer pool configuration map (refer to doc/howto/network_load_balancers.md)
          example:
            protocol: tcp
          type: object
          x-go-name: Config
        description:
          description: Description of the load balancer pool.
          example: My HTTPS load balancer pool
          type: string
          x-go-name: Description
        instances:
          description: List of instances in the pool.
          example:
          - name: c1
          - name: c2
            target_port: '8443'
          items:
            $ref: '#/components/schemas/NetworkLoadBalancerPoolInstance'
          type: array
          x-go-name: Instances
      title: NetworkLoadBalancerPoolPut represents the modifiable fields of a LXD network load balancer pool.
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            properties:
              error:
                example: bad request
                type: string
                x-go-name: Error
              error_code:
                example: 400
                format: int64
                type: integer
                x-go-name: ErrorCode
              type:
                example: error
                type: string
                x-go-name: Type
            type: object
    Operation:
      description: Operation
      content:
        application/json:
          schema:
            properties:
              metadata:
                $ref: '#/components/schemas/Operation'
              operation:
                example: /1.0/operations/66e83638-9dd7-4a26-aef2-5462814869a1
                type: string
                x-go-name: Operation
              status:
                example: Operation created
                type: string
                x-go-name: Status
              status_code:
                example: 100
                format: int64
                type: integer
                x-go-name: StatusCode
              type:
                example: async
                type: string
                x-go-name: Type
            type: object
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            properties:
              error:
                example: not authorized
                type: string
                x-go-name: Error
              error_code:
                example: 403
                format: int64
                type: integer
                x-go-name: ErrorCode
              type:
                example: error
                type: string
                x-go-name: Type
            type: object
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            properties:
              error:
                example: internal server error
                type: string
                x-go-name: Error
              error_code:
                example: 500
                format: int64
                type: integer
                x-go-name: ErrorCode
              type:
                example: error
                type: string
                x-go-name: Type
            type: object