swagger: '2.0'
info:
  contact:
    email: lxc-devel@lists.linuxcontainers.org
    name: Incus upstream
    url: https://github.com/lxc/incus
  description: 'This is the REST API used by all Incus clients.

    Internal endpoints aren''t included in this documentation.


    The Incus 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

    certificates.'
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  title: Incus external REST certificates cluster API
  version: '1.0'
tags:
- name: cluster
paths:
  /1.0/cluster:
    get:
      description: Gets the current cluster configuration.
      operationId: cluster_get
      produces:
      - application/json
      responses:
        '200':
          description: Cluster configuration
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/Cluster'
              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
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the cluster configuration
      tags:
      - cluster
    put:
      consumes:
      - application/json
      description: Updates the entire cluster configuration.
      operationId: cluster_put
      parameters:
      - description: Cluster configuration
        in: body
        name: cluster
        required: true
        schema:
          $ref: '#/definitions/ClusterPut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '412':
          $ref: '#/responses/PreconditionFailed'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Update the cluster configuration
      tags:
      - cluster
  /1.0/cluster/certificate:
    put:
      consumes:
      - application/json
      description: Replaces existing cluster certificate and reloads each cluster member.
      operationId: clustering_update_cert
      parameters:
      - description: Cluster certificate replace request
        in: body
        name: cluster
        required: true
        schema:
          $ref: '#/definitions/ClusterCertificatePut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Update the certificate for the cluster
      tags:
      - cluster
  /1.0/cluster/groups:
    post:
      consumes:
      - application/json
      description: Creates a new cluster group.
      operationId: cluster_groups_post
      parameters:
      - description: Cluster group to create
        in: body
        name: cluster
        required: true
        schema:
          $ref: '#/definitions/ClusterGroupsPost'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Create a cluster group.
      tags:
      - cluster
  /1.0/cluster/members:
    get:
      description: Returns a list of cluster members (URLs).
      operationId: cluster_members_get
      parameters:
      - description: Collection filter
        example: default
        in: query
        name: filter
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of endpoints
                example: "[\n  \"/1.0/cluster/members/server01\",\n  \"/1.0/cluster/members/server02\"\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
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the cluster members
      tags:
      - cluster
    post:
      consumes:
      - application/json
      description: Requests a join token to add a cluster member.
      operationId: cluster_members_post
      parameters:
      - description: Cluster member add request
        in: body
        name: cluster
        required: true
        schema:
          $ref: '#/definitions/ClusterMembersPost'
      produces:
      - application/json
      responses:
        '202':
          $ref: '#/responses/Operation'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Request a join token
      tags:
      - cluster
  /1.0/cluster/members/{name}:
    delete:
      description: Removes the member from the cluster.
      operationId: cluster_member_delete
      parameters:
      - description: Cluster member name
        in: path
        name: name
        required: true
        type: string
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Delete the cluster member
      tags:
      - cluster
    get:
      description: Gets a specific cluster member.
      operationId: cluster_member_get
      parameters:
      - description: Cluster member name
        in: path
        name: name
        required: true
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: Cluster member
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/ClusterMember'
              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
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the cluster member
      tags:
      - cluster
    patch:
      consumes:
      - application/json
      description: Updates a subset of the cluster member configuration.
      operationId: cluster_member_patch
      parameters:
      - description: Cluster member name
        in: path
        name: name
        required: true
        type: string
      - description: Cluster member configuration
        in: body
        name: cluster
        required: true
        schema:
          $ref: '#/definitions/ClusterMemberPut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '412':
          $ref: '#/responses/PreconditionFailed'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Partially update the cluster member
      tags:
      - cluster
    post:
      consumes:
      - application/json
      description: Renames an existing cluster member.
      operationId: cluster_member_post
      parameters:
      - description: Cluster member name
        in: path
        name: name
        required: true
        type: string
      - description: Cluster member rename request
        in: body
        name: cluster
        required: true
        schema:
          $ref: '#/definitions/ClusterMemberPost'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Rename the cluster member
      tags:
      - cluster
    put:
      consumes:
      - application/json
      description: Updates the entire cluster member configuration.
      operationId: cluster_member_put
      parameters:
      - description: Cluster member name
        in: path
        name: name
        required: true
        type: string
      - description: Cluster member configuration
        in: body
        name: cluster
        required: true
        schema:
          $ref: '#/definitions/ClusterMemberPut'
      produces:
      - application/json
      responses:
        '200':
          $ref: '#/responses/EmptySyncResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '412':
          $ref: '#/responses/PreconditionFailed'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Update the cluster member
      tags:
      - cluster
  /1.0/cluster/members/{name}/state:
    get:
      description: Gets state of a specific cluster member.
      operationId: cluster_member_state_get
      parameters:
      - description: Cluster member name
        in: path
        name: name
        required: true
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: Cluster member state
          schema:
            description: Sync response
            properties:
              metadata:
                $ref: '#/definitions/ClusterMemberState'
              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
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get state of the cluster member
      tags:
      - cluster
    post:
      consumes:
      - application/json
      description: Evacuates or restores a cluster member.
      operationId: cluster_member_state_post
      parameters:
      - description: Cluster member name
        in: path
        name: name
        required: true
        type: string
      - description: Cluster member state
        in: body
        name: cluster
        required: true
        schema:
          $ref: '#/definitions/ClusterMemberStatePost'
      produces:
      - application/json
      responses:
        '202':
          $ref: '#/responses/Operation'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Evacuate or restore a cluster member
      tags:
      - cluster
  /1.0/cluster/members?recursion=1:
    get:
      description: Returns a list of cluster members (structs).
      operationId: cluster_members_get_recursion1
      parameters:
      - description: Collection filter
        example: default
        in: query
        name: filter
        type: string
      produces:
      - application/json
      responses:
        '200':
          description: API endpoints
          schema:
            description: Sync response
            properties:
              metadata:
                description: List of cluster members
                items:
                  $ref: '#/definitions/ClusterMember'
                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
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'
      summary: Get the cluster members
      tags:
      - cluster
definitions:
  StatusCode:
    format: int64
    title: StatusCode represents a valid operation and container status.
    type: integer
    x-go-package: github.com/lxc/incus/v7/shared/api
  ClusterMemberPost:
    properties:
      server_name:
        description: The new name of the cluster member
        example: server02
        type: string
        x-go-name: ServerName
    title: ClusterMemberPost represents the fields required to rename a cluster member.
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  StoragePoolState:
    properties:
      inodes:
        $ref: '#/definitions/ResourcesStoragePoolInodes'
      space:
        $ref: '#/definitions/ResourcesStoragePoolSpace'
    title: StoragePoolState represents the state of a storage pool.
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  ResourcesStoragePoolSpace:
    description: ResourcesStoragePoolSpace represents the space available to a given storage pool
    properties:
      total:
        description: Total disk space (bytes)
        example: 420100937728
        format: uint64
        type: integer
        x-go-name: Total
      used:
        description: Used disk space (bytes)
        example: 343537419776
        format: uint64
        type: integer
        x-go-name: Used
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  ClusterMemberState:
    properties:
      storage_pools:
        additionalProperties:
          $ref: '#/definitions/StoragePoolState'
        type: object
        x-go-name: StoragePools
      sysinfo:
        $ref: '#/definitions/ClusterMemberSysInfo'
    title: ClusterMemberState represents the state of a cluster member.
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  ClusterMemberStatePost:
    properties:
      action:
        description: The action to be performed. Valid actions are "evacuate" and "restore".
        example: evacuate
        type: string
        x-go-name: Action
      mode:
        description: Override the configured evacuation mode.
        example: stop
        type: string
        x-go-name: Mode
    title: ClusterMemberStatePost represents the fields required to evacuate a cluster member.
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  ClusterGroupsPost:
    properties:
      config:
        description: Cluster group configuration map
        example:
          user.mykey: foo
        type: object
        x-go-name: Config
      description:
        description: The description of the cluster group
        example: amd64 servers
        type: string
        x-go-name: Description
      members:
        description: List of members in this group
        example:
        - server01
        - server02
        items:
          type: string
        type: array
        x-go-name: Members
      name:
        description: The new name of the cluster group
        example: group1
        type: string
        x-go-name: Name
    title: ClusterGroupsPost represents the fields available for a new cluster group.
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  ResourcesStoragePoolInodes:
    description: ResourcesStoragePoolInodes represents the inodes available to a given storage pool
    properties:
      total:
        description: Total inodes
        example: 30709993797
        format: uint64
        type: integer
        x-go-name: Total
      used:
        description: Used inodes
        example: 23937695
        format: uint64
        type: integer
        x-go-name: Used
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  ClusterMemberPut:
    description: ClusterMemberPut represents the modifiable fields of a cluster member
    properties:
      config:
        description: Additional configuration information
        example:
          scheduler.instance: all
        type: object
        x-go-name: Config
      description:
        description: Cluster member description
        example: AMD Epyc 32c/64t
        type: string
        x-go-name: Description
      failure_domain:
        description: Name of the failure domain for this cluster member
        example: rack1
        type: string
        x-go-name: FailureDomain
      groups:
        description: List of cluster groups this member belongs to
        example:
        - group1
        - group2
        items:
          type: string
        type: array
        x-go-name: Groups
      roles:
        description: List of roles held by this cluster member
        example:
        - database
        items:
          type: string
        type: array
        x-go-name: Roles
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  ClusterMembersPost:
    properties:
      server_name:
        description: The name of the new cluster member
        example: server02
        type: string
        x-go-name: ServerName
    title: ClusterMembersPost represents the fields required to request a join token to add a member to the cluster.
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  Cluster:
    properties:
      enabled:
        description: Whether clustering is enabled
        example: true
        type: boolean
        x-go-name: Enabled
      member_config:
        description: List of member configuration keys (used during join)
        example: []
        items:
          $ref: '#/definitions/ClusterMemberConfigKey'
        type: array
        x-go-name: MemberConfig
      server_name:
        description: Name of the cluster member answering the request
        example: server01
        type: string
        x-go-name: ServerName
    title: Cluster represents high-level information about a cluster.
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  ClusterMember:
    properties:
      architecture:
        description: The primary architecture of the cluster member
        example: x86_64
        type: string
        x-go-name: Architecture
      config:
        description: Additional configuration information
        example:
          scheduler.instance: all
        type: object
        x-go-name: Config
      database:
        description: Whether the cluster member is a database server
        example: true
        type: boolean
        x-go-name: Database
      description:
        description: Cluster member description
        example: AMD Epyc 32c/64t
        type: string
        x-go-name: Description
      failure_domain:
        description: Name of the failure domain for this cluster member
        example: rack1
        type: string
        x-go-name: FailureDomain
      groups:
        description: List of cluster groups this member belongs to
        example:
        - group1
        - group2
        items:
          type: string
        type: array
        x-go-name: Groups
      message:
        description: Additional status information
        example: fully operational
        type: string
        x-go-name: Message
      roles:
        description: List of roles held by this cluster member
        example:
        - database
        items:
          type: string
        type: array
        x-go-name: Roles
      server_name:
        description: Name of the cluster member
        example: server01
        type: string
        x-go-name: ServerName
      status:
        description: Current status
        example: Online
        type: string
        x-go-name: Status
      url:
        description: URL at which the cluster member can be reached
        example: https://10.0.0.1:8443
        type: string
        x-go-name: URL
    title: ClusterMember represents a member of a cluster.
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  Operation:
    description: Operation represents a background operation
    properties:
      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
      id:
        description: UUID of the operation
        example: 6916c8a6-9b7d-4abd-90b3-aedfec7ec7da
        type: string
        x-go-name: ID
      location:
        description: What cluster member this record was found on
        example: server01
        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
      resources:
        additionalProperties:
          items:
            type: string
          type: array
        description: Affected resources
        example:
          instances:
          - /1.0/instances/foo
        type: object
        x-go-name: Resources
      status:
        description: Status name
        example: Running
        type: string
        x-go-name: Status
      status_code:
        $ref: '#/definitions/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/lxc/incus/v7/shared/api
  ClusterPut:
    properties:
      cluster_address:
        description: The address of the cluster you wish to join
        example: 10.0.0.1:8443
        type: string
        x-go-name: ClusterAddress
      cluster_certificate:
        description: The expected certificate (X509 PEM encoded) for the cluster
        example: X509 PEM certificate
        type: string
        x-go-name: ClusterCertificate
      cluster_token:
        description: The cluster join token for the cluster you're trying to join
        example: blah
        type: string
        x-go-name: ClusterToken
      enabled:
        description: Whether clustering is enabled
        example: true
        type: boolean
        x-go-name: Enabled
      member_config:
        description: List of member configuration keys (used during join)
        example: []
        items:
          $ref: '#/definitions/ClusterMemberConfigKey'
        type: array
        x-go-name: MemberConfig
      server_address:
        description: The local address to use for cluster communication
        example: 10.0.0.2:8443
        type: string
        x-go-name: ServerAddress
      server_name:
        description: Name of the cluster member answering the request
        example: server01
        type: string
        x-go-name: ServerName
    title: ClusterPut represents the fields required to bootstrap or join a cluster.
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  ClusterMemberSysInfo:
    properties:
      buffered_ram:
        format: uint64
        type: integer
        x-go-name: BufferRAM
      free_ram:
        format: uint64
        type: integer
        x-go-name: FreeRAM
      free_swap:
        format: uint64
        type: integer
        x-go-name: FreeSwap
      load_averages:
        items:
          format: double
          type: number
        type: array
        x-go-name: LoadAverages
      processes:
        format: uint16
        type: integer
        x-go-name: Processes
      shared_ram:
        format: uint64
        type: integer
        x-go-name: SharedRAM
      total_ram:
        format: uint64
        type: integer
        x-go-name: TotalRAM
      total_swap:
        format: uint64
        type: integer
        x-go-name: TotalSwap
      uptime:
        format: int64
        type: integer
        x-go-name: Uptime
    title: ClusterMemberSysInfo represents the sysinfo of a cluster member.
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  ClusterCertificatePut:
    description: ClusterCertificatePut represents the certificate and key pair for all cluster members
    properties:
      cluster_certificate:
        description: The new certificate (X509 PEM encoded) for the cluster
        example: X509 PEM certificate
        type: string
        x-go-name: ClusterCertificate
      cluster_certificate_key:
        description: The new certificate key (X509 PEM encoded) for the cluster
        example: X509 PEM certificate key
        type: string
        x-go-name: ClusterCertificateKey
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
  ClusterMemberConfigKey:
    description: 'The Value field is empty when getting clustering information with GET

      1.0/cluster, and should be filled by the joining server when performing a PUT

      1.0/cluster join request.'
    properties:
      description:
        description: A human friendly description key
        example: '"source" property for storage pool "local"'
        type: string
        x-go-name: Description
      entity:
        description: The kind of configuration key (network, storage-pool, ...)
        example: storage-pool
        type: string
        x-go-name: Entity
      key:
        description: The name of the key
        example: source
        type: string
        x-go-name: Key
      name:
        description: The name of the object requiring this key
        example: local
        type: string
        x-go-name: Name
      value:
        description: The value on the answering cluster member
        example: /dev/sdb
        type: string
        x-go-name: Value
    title: 'ClusterMemberConfigKey represents a single config key that a new member of

      the cluster is required to provide when joining.'
    type: object
    x-go-package: github.com/lxc/incus/v7/shared/api
responses:
  Forbidden:
    description: Forbidden
    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
    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
  BadRequest:
    description: Bad Request
    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
    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
    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
  Operation:
    description: Operation
    schema:
      properties:
        metadata:
          $ref: '#/definitions/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