The cluster API from Incus — 7 operation(s) for cluster.
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