Canonical Cluster Links 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 Cluster Links API
  version: '1.0'
tags:
- name: cluster-links
paths:
  /1.0/cluster/links:
    get:
      description: Returns a list of cluster links (URLs).
      operationId: cluster_links_get
      responses:
        '200':
          description: API endpoints
          content:
            application/json:
              schema:
                description: Sync response
                properties:
                  metadata:
                    description: List of endpoints
                    example: "[\n  \"/1.0/cluster/links/primary\",\n  \"/1.0/cluster/links/backup\"\n]"
                    items:
                      type: string
                    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: Get the cluster links
      tags:
      - cluster-links
    post:
      description: Creates a new cluster link.
      operationId: cluster_links_post
      responses:
        '200':
          description: ''
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Add a cluster link
      tags:
      - cluster-links
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClusterLinksPost'
        description: Cluster link
        required: true
  /1.0/cluster/links/{name}:
    delete:
      description: Deletes the cluster link.
      operationId: cluster_link_delete
      responses:
        '200':
          $ref: '#/components/responses/EmptySyncResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Delete the cluster link
      tags:
      - cluster-links
    get:
      description: Gets a specific cluster link.
      operationId: cluster_link_get
      responses:
        '200':
          description: Cluster link
          content:
            application/json:
              schema:
                description: Sync response
                properties:
                  metadata:
                    $ref: '#/components/schemas/ClusterLink'
                  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 cluster link
      tags:
      - cluster-links
    patch:
      description: Updates a subset of the cluster link configuration.
      operationId: cluster_link_patch
      responses:
        '200':
          $ref: '#/components/responses/EmptySyncResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Update the cluster link
      tags:
      - cluster-links
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClusterLinkPut'
        description: Update cluster link request
        required: true
    post:
      description: Renames the cluster link.
      operationId: cluster_link_post
      responses:
        '200':
          $ref: '#/components/responses/EmptySyncResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Rename the cluster link
      tags:
      - cluster-links
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClusterLinkPost'
        description: Rename cluster link request
        required: true
    put:
      description: Updates the cluster link configuration.
      operationId: cluster_link_put
      responses:
        '200':
          $ref: '#/components/responses/EmptySyncResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Update the cluster link
      tags:
      - cluster-links
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClusterLinkPut'
        description: Update cluster link request
        required: true
  /1.0/cluster/links/{name}/state:
    get:
      description: Get a specific cluster link state.
      operationId: cluster_link_state_get
      parameters:
      - description: Cluster member name
        example: lxd01
        in: query
        name: target
        schema:
          type: string
      responses:
        '200':
          description: Cluster link state
          content:
            application/json:
              schema:
                description: Sync response
                properties:
                  metadata:
                    $ref: '#/components/schemas/ClusterLinkState'
                  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 cluster link state
      tags:
      - cluster-links
  /1.0/cluster/links?recursion=1:
    get:
      description: Returns a list of cluster links (structs).
      operationId: cluster_links_get_recursion1
      responses:
        '200':
          description: Cluster links
          content:
            application/json:
              schema:
                description: Sync response
                properties:
                  metadata:
                    description: List of cluster links
                    items:
                      $ref: '#/components/schemas/ClusterLink'
                    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: Get the cluster links
      tags:
      - cluster-links
components:
  schemas:
    ClusterLinksPost:
      properties:
        auth_groups:
          description: List of auth groups this cluster link belongs to.
          example:
          - foo
          - bar
          items:
            type: string
          type: array
          x-go-name: AuthGroups
        cluster_certificate:
          description: The certificate (X509 PEM encoded) for the linked cluster. This is included in server-side POST requests to activate the pending cluster link on the linked cluster that generated the trust token.
          example: X509 PEM certificate
          type: string
          x-go-name: ClusterCertificate
        config:
          additionalProperties:
            type: string
          description: Cluster link configuration map (refer to doc/clustering.md).
          example:
            user.*: ''
          type: object
          x-go-name: Config
        description:
          description: Description of the cluster link.
          example: Linked cluster
          type: string
          x-go-name: Description
        fingerprint:
          description: 'Fingerprint of the remote cluster''s certificate, echoed back to confirm a pending public

            cluster link. It must match the fingerprint returned when the pending link was created; the

            certificate itself is not resubmitted, as the server pins the copy it already holds.

            API extension: cluster_links_public.'
          example: a1b2c3d4..
          type: string
          x-go-name: Fingerprint
        name:
          description: Name of the cluster.
          example: lxd02
          type: string
          x-go-name: Name
        remote_address:
          description: 'RemoteAddress is the address of the remote cluster, used for public links. It is the address

            contacted when creating a pending public cluster link, and is required for that request only.

            Confirming the link pins the address recorded when the pending link was created, so the link

            always points at the address that was verified; setting this field on a confirm request is

            rejected.'
          example: 10.0.0.1:8443
          type: string
          x-go-name: RemoteAddress
        trust_token:
          description: 'TrustToken for creating a cluster link. This is included in requests to create an active cluster link on the local cluster and activate a pending cluster link on the linked cluster.

            API extension: explicit_trust_token'
          type: string
          x-go-name: TrustToken
        type:
          description: 'Type of the cluster link.

            Currently only "bidirectional" is supported.'
          example: bidirectional
          type: string
          x-go-name: Type
      title: ClusterLinksPost represents the fields available for a new cluster link.
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    ClusterLinkPost:
      properties:
        name:
          description: Name of the cluster link.
          example: lxd02
          type: string
          x-go-name: Name
      title: ClusterLinkPost represents the fields available for renaming a cluster link.
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    ClusterLink:
      properties:
        access_entitlements:
          description: AccessEntitlements represents the entitlements that are granted to the requesting user on the attached entity.
          example:
          - can_view
          - can_edit
          items:
            type: string
          type: array
          x-go-name: AccessEntitlements
        config:
          additionalProperties:
            type: string
          description: Cluster link configuration map (refer to doc/clustering.md).
          example:
            user.*: ''
          type: object
          x-go-name: Config
        description:
          description: Description of the cluster link.
          example: Backup LXD cluster
          type: string
          x-go-name: Description
        name:
          description: Name of the cluster link.
          example: lxd02
          type: string
          x-go-name: Name
        type:
          description: Type of cluster link.
          example: bidirectional
          type: string
          x-go-name: Type
        used_by:
          description: 'UsedBy is a list of LXD entity URLs that reference the cluster link.


            API extension: cluster_links_used_by'
          example:
          - /1.0/replicators/my-replicator?project=default
          items:
            type: string
          type: array
          x-go-name: UsedBy
      title: ClusterLink represents high-level information about a cluster link.
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    ClusterLinkMemberState:
      properties:
        address:
          description: Address at which the cluster member can be reached.
          example: 10.0.0.1:8443
          type: string
          x-go-name: Address
        server_name:
          description: Name of the cluster member.
          example: lxd01
          type: string
          x-go-name: ServerName
        status:
          description: Cluster member's status.
          example: Active
          type: string
          x-go-name: Status
      title: ClusterLinkMemberState represents the state of a cluster member on a linked cluster.
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    ClusterLinkState:
      properties:
        cluster_link_members:
          description: ClusterLinkMembers represents the state of cluster members on a linked cluster.
          example:
          - address: 10.0.0.1:8443
            server_name: lxd01
            status: Active
          - address: 10.0.0.2:8443
            server_name: lxd02
            status: Unreachable
          items:
            $ref: '#/components/schemas/ClusterLinkMemberState'
          type: array
          x-go-name: ClusterLinkMembersState
      title: ClusterLinkState represents the state of a linked cluster.
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    ClusterLinkPut:
      properties:
        config:
          additionalProperties:
            type: string
          description: Cluster link configuration map (refer to doc/clustering.md).
          example:
            user.*: ''
          type: object
          x-go-name: Config
        description:
          description: Description of the cluster link.
          example: Linked cluster
          type: string
          x-go-name: Description
      title: ClusterLinkPut represents the modifiable fields of a cluster link.
      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
    EmptySyncResponse:
      description: Empty sync response
      content:
        application/json:
          schema:
            properties:
              status:
                example: Success
                type: string
                x-go-name: Status
              status_code:
                example: 200
                format: int64
                type: integer
                x-go-name: StatusCode
              type:
                example: sync
                type: string
                x-go-name: Type
            type: object
    PreconditionFailed:
      description: Precondition Failed
      content:
        application/json:
          schema:
            properties:
              error:
                example: precondition failed
                type: string
                x-go-name: Error
              error_code:
                example: 412
                format: int64
                type: integer
                x-go-name: ErrorCode
              type:
                example: error
                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