[lxc-devel] [lxd/master] Use JSON markdown blocks in docs
j8r on Github
lxc-bot at linuxcontainers.org
Sat Dec 21 15:25:25 UTC 2019
A non-text attachment was scrubbed...
Name: not available
Type: text/x-mailbox
Size: 481 bytes
Desc: not available
URL: <http://lists.linuxcontainers.org/pipermail/lxc-devel/attachments/20191221/6715add4/attachment-0001.bin>
-------------- next part --------------
From d78f48c516839258fd318f33e5ac966964fe53af Mon Sep 17 00:00:00 2001
From: Julien Reichardt <git at jrei.ch>
Date: Sat, 21 Dec 2019 15:43:30 +0100
Subject: [PATCH] Use JSON markdown blocks in docs
---
doc/dev-lxd.md | 40 +-
doc/rest-api.md | 3061 ++++++++++++++++++++++++++---------------------
2 files changed, 1694 insertions(+), 1407 deletions(-)
diff --git a/doc/dev-lxd.md b/doc/dev-lxd.md
index 123e8e8615..00f9cb2fcf 100644
--- a/doc/dev-lxd.md
+++ b/doc/dev-lxd.md
@@ -114,28 +114,32 @@ The notification types are:
This never returns. Each notification is sent as a separate JSON dict:
- {
- "timestamp": "2017-12-21T18:28:26.846603815-05:00",
- "type": "device",
- "metadata": {
- "name": "kvm",
- "action": "added",
- "config": {
- "type": "unix-char",
- "path": "/dev/kvm"
- }
+```json
+{
+ "timestamp": "2017-12-21T18:28:26.846603815-05:00",
+ "type": "device",
+ "metadata": {
+ "name": "kvm",
+ "action": "added",
+ "config": {
+ "type": "unix-char",
+ "path": "/dev/kvm"
}
}
+}
+```
- {
- "timestamp": "2017-12-21T18:28:26.846603815-05:00",
- "type": "config",
- "metadata": {
- "key": "user.foo",
- "old_value": "",
- "value": "bar"
- }
+```json
+{
+ "timestamp": "2017-12-21T18:28:26.846603815-05:00",
+ "type": "config",
+ "metadata": {
+ "key": "user.foo",
+ "old_value": "",
+ "value": "bar"
}
+}
+```
#### `/1.0/images/<FINGERPRINT>/export`
##### GET
diff --git a/doc/rest-api.md b/doc/rest-api.md
index ba65997fc2..b28300f4d2 100644
--- a/doc/rest-api.md
+++ b/doc/rest-api.md
@@ -32,12 +32,14 @@ There are three standard return types:
#### Standard return value
For a standard synchronous operation, the following dict is returned:
- {
- "type": "sync",
- "status": "Success",
- "status_code": 200,
- "metadata": {} # Extra resource/action specific metadata
- }
+```json
+{
+ "type": "sync",
+ "status": "Success",
+ "status_code": 200,
+ "metadata": {} # Extra resource/action specific metadata
+}
+```
HTTP code must be 200.
@@ -47,37 +49,41 @@ and the Location HTTP header is set to the operation URL.
The body is a dict with the following structure:
- {
- "type": "async",
- "status": "OK",
- "status_code": 100,
- "operation": "/1.0/containers/<id>", # URL to the background operation
- "metadata": {} # Operation metadata (see below)
- }
+```json
+{
+ "type": "async",
+ "status": "OK",
+ "status_code": 100,
+ "operation": "/1.0/containers/<id>", # URL to the background operation
+ "metadata": {} # Operation metadata (see below)
+}
+```
The operation metadata structure looks like:
- {
- "id": "a40f5541-5e98-454f-b3b6-8a51ef5dbd3c", # UUID of the operation
- "class": "websocket", # Class of the operation (task, websocket or token)
- "created_at": "2015-11-17T22:32:02.226176091-05:00", # When the operation was created
- "updated_at": "2015-11-17T22:32:02.226176091-05:00", # Last time the operation was updated
- "status": "Running", # String version of the operation's status
- "status_code": 103, # Integer version of the operation's status (use this rather than status)
- "resources": { # Dictionary of resource types (container, snapshots, images) and affected resources
- "containers": [
- "/1.0/containers/test"
- ]
- },
- "metadata": { # Metadata specific to the operation in question (in this case, exec)
- "fds": {
- "0": "2a4a97af81529f6608dca31f03a7b7e47acc0b8dc6514496eb25e325f9e4fa6a",
- "control": "5b64c661ef313b423b5317ba9cb6410e40b705806c28255f601c0ef603f079a7"
- }
- },
- "may_cancel": false, # Whether the operation can be canceled (DELETE over REST)
- "err": "" # The error string should the operation have failed
- }
+```json
+{
+ "id": "a40f5541-5e98-454f-b3b6-8a51ef5dbd3c", # UUID of the operation
+ "class": "websocket", # Class of the operation (task, websocket or token)
+ "created_at": "2015-11-17T22:32:02.226176091-05:00", # When the operation was created
+ "updated_at": "2015-11-17T22:32:02.226176091-05:00", # Last time the operation was updated
+ "status": "Running", # String version of the operation's status
+ "status_code": 103, # Integer version of the operation's status (use this rather than status)
+ "resources": { # Dictionary of resource types (container, snapshots, images) and affected resources
+ "containers": [
+ "/1.0/containers/test"
+ ]
+ },
+ "metadata": { # Metadata specific to the operation in question (in this case, exec)
+ "fds": {
+ "0": "2a4a97af81529f6608dca31f03a7b7e47acc0b8dc6514496eb25e325f9e4fa6a",
+ "control": "5b64c661ef313b423b5317ba9cb6410e40b705806c28255f601c0ef603f079a7"
+ }
+ },
+ "may_cancel": false, # Whether the operation can be canceled (DELETE over REST)
+ "err": "" # The error string should the operation have failed
+}
+```
The body is mostly provided as a user friendly way of seeing what's
going on without having to pull the target operation, all information in
@@ -87,12 +93,14 @@ the body can also be retrieved from the background operation URL.
There are various situations in which something may immediately go
wrong, in those cases, the following return value is used:
- {
- "type": "error",
- "error": "Failure",
- "error_code": 400,
- "metadata": {} # More details about the error
- }
+```json
+{
+ "type": "error",
+ "error": "Failure",
+ "error_code": 400,
+ "metadata": {} # More details about the error
+}
+```
HTTP code must be one of of 400, 401, 403, 404, 409, 412 or 500.
@@ -182,54 +190,54 @@ won't work and PUT needs to be used instead.
## API structure
* [`/`](#)
* [`/1.0`](#10)
- * [`/1.0/certificates`](#10certificates)
- * [`/1.0/certificates/<fingerprint>`](#10certificatesfingerprint)
- * [`/1.0/containers`](#10containers)
- * [`/1.0/containers/<name>`](#10containersname)
- * [`/1.0/containers/<name>/console`](#10containersnameconsole)
- * [`/1.0/containers/<name>/exec`](#10containersnameexec)
- * [`/1.0/containers/<name>/files`](#10containersnamefiles)
- * [`/1.0/containers/<name>/snapshots`](#10containersnamesnapshots)
- * [`/1.0/containers/<name>/snapshots/<name>`](#10containersnamesnapshotsname)
- * [`/1.0/containers/<name>/state`](#10containersnamestate)
- * [`/1.0/containers/<name>/logs`](#10containersnamelogs)
- * [`/1.0/containers/<name>/logs/<logfile>`](#10containersnamelogslogfile)
- * [`/1.0/containers/<name>/metadata`](#10containersnamemetadata)
- * [`/1.0/containers/<name>/metadata/templates`](#10containersnamemetadatatemplates)
- * [`/1.0/containers/<name>/backups`](#10containersnamebackups)
- * [`/1.0/containers/<name>/backups/<name>`](#10containersnamebackupsname)
- * [`/1.0/containers/<name>/backups/<name>/export`](#10containersnamebackupsnameexport)
- * [`/1.0/events`](#10events)
- * [`/1.0/images`](#10images)
- * [`/1.0/images/<fingerprint>`](#10imagesfingerprint)
- * [`/1.0/images/<fingerprint>/export`](#10imagesfingerprintexport)
- * [`/1.0/images/<fingerprint>/refresh`](#10imagesfingerprintrefresh)
- * [`/1.0/images/<fingerprint>/secret`](#10imagesfingerprintsecret)
- * [`/1.0/images/aliases`](#10imagesaliases)
- * [`/1.0/images/aliases/<name>`](#10imagesaliasesname)
- * [`/1.0/networks`](#10networks)
- * [`/1.0/networks/<name>`](#10networksname)
- * [`/1.0/networks/<name>/state`](#10networksnamestate)
- * [`/1.0/operations`](#10operations)
- * [`/1.0/operations/<uuid>`](#10operationsuuid)
- * [`/1.0/operations/<uuid>/wait`](#10operationsuuidwait)
- * [`/1.0/operations/<uuid>/websocket`](#10operationsuuidwebsocket)
- * [`/1.0/profiles`](#10profiles)
- * [`/1.0/profiles/<name>`](#10profilesname)
- * [`/1.0/projects`](#10projects)
- * [`/1.0/projects/<name>`](#10projectsname)
- * [`/1.0/storage-pools`](#10storage-pools)
- * [`/1.0/storage-pools/<name>`](#10storage-poolsname)
- * [`/1.0/storage-pools/<name>/resources`](#10storage-poolsnameresources)
- * [`/1.0/storage-pools/<name>/volumes`](#10storage-poolsnamevolumes)
- * [`/1.0/storage-pools/<name>/volumes/<type>`](#10storage-poolsnamevolumestype)
- * [`/1.0/storage-pools/<pool>/volumes/<type>/<name>`](#10storage-poolspoolvolumestypename)
- * [`/1.0/storage-pools/<pool>/volumes/<type>/<name>/snapshots`](#10storage-poolspoolvolumestypenamesnapshots)
- * [`/1.0/storage-pools/<pool>/volumes/<type>/<volume>/snapshots/<name>`](#10storage-poolspoolvolumestypevolumesnapshotsname)
- * [`/1.0/resources`](#10resources)
- * [`/1.0/cluster`](#10cluster)
- * [`/1.0/cluster/members`](#10clustermembers)
- * [`/1.0/cluster/members/<name>`](#10clustermembersname)
+ * [`/1.0/certificates`](#10certificates)
+ * [`/1.0/certificates/<fingerprint>`](#10certificatesfingerprint)
+ * [`/1.0/containers`](#10containers)
+ * [`/1.0/containers/<name>`](#10containersname)
+ * [`/1.0/containers/<name>/console`](#10containersnameconsole)
+ * [`/1.0/containers/<name>/exec`](#10containersnameexec)
+ * [`/1.0/containers/<name>/files`](#10containersnamefiles)
+ * [`/1.0/containers/<name>/snapshots`](#10containersnamesnapshots)
+ * [`/1.0/containers/<name>/snapshots/<name>`](#10containersnamesnapshotsname)
+ * [`/1.0/containers/<name>/state`](#10containersnamestate)
+ * [`/1.0/containers/<name>/logs`](#10containersnamelogs)
+ * [`/1.0/containers/<name>/logs/<logfile>`](#10containersnamelogslogfile)
+ * [`/1.0/containers/<name>/metadata`](#10containersnamemetadata)
+ * [`/1.0/containers/<name>/metadata/templates`](#10containersnamemetadatatemplates)
+ * [`/1.0/containers/<name>/backups`](#10containersnamebackups)
+ * [`/1.0/containers/<name>/backups/<name>`](#10containersnamebackupsname)
+ * [`/1.0/containers/<name>/backups/<name>/export`](#10containersnamebackupsnameexport)
+ * [`/1.0/events`](#10events)
+ * [`/1.0/images`](#10images)
+ * [`/1.0/images/<fingerprint>`](#10imagesfingerprint)
+ * [`/1.0/images/<fingerprint>/export`](#10imagesfingerprintexport)
+ * [`/1.0/images/<fingerprint>/refresh`](#10imagesfingerprintrefresh)
+ * [`/1.0/images/<fingerprint>/secret`](#10imagesfingerprintsecret)
+ * [`/1.0/images/aliases`](#10imagesaliases)
+ * [`/1.0/images/aliases/<name>`](#10imagesaliasesname)
+ * [`/1.0/networks`](#10networks)
+ * [`/1.0/networks/<name>`](#10networksname)
+ * [`/1.0/networks/<name>/state`](#10networksnamestate)
+ * [`/1.0/operations`](#10operations)
+ * [`/1.0/operations/<uuid>`](#10operationsuuid)
+ * [`/1.0/operations/<uuid>/wait`](#10operationsuuidwait)
+ * [`/1.0/operations/<uuid>/websocket`](#10operationsuuidwebsocket)
+ * [`/1.0/profiles`](#10profiles)
+ * [`/1.0/profiles/<name>`](#10profilesname)
+ * [`/1.0/projects`](#10projects)
+ * [`/1.0/projects/<name>`](#10projectsname)
+ * [`/1.0/storage-pools`](#10storage-pools)
+ * [`/1.0/storage-pools/<name>`](#10storage-poolsname)
+ * [`/1.0/storage-pools/<name>/resources`](#10storage-poolsnameresources)
+ * [`/1.0/storage-pools/<name>/volumes`](#10storage-poolsnamevolumes)
+ * [`/1.0/storage-pools/<name>/volumes/<type>`](#10storage-poolsnamevolumestype)
+ * [`/1.0/storage-pools/<pool>/volumes/<type>/<name>`](#10storage-poolspoolvolumestypename)
+ * [`/1.0/storage-pools/<pool>/volumes/<type>/<name>/snapshots`](#10storage-poolspoolvolumestypenamesnapshots)
+ * [`/1.0/storage-pools/<pool>/volumes/<type>/<volume>/snapshots/<name>`](#10storage-poolspoolvolumestypevolumesnapshotsname)
+ * [`/1.0/resources`](#10resources)
+ * [`/1.0/cluster`](#10cluster)
+ * [`/1.0/cluster/members`](#10clustermembers)
+ * [`/1.0/cluster/members/<name>`](#10clustermembersname)
## API details
### `/`
@@ -241,9 +249,11 @@ won't work and PUT needs to be used instead.
Return value:
- [
- "/1.0"
- ]
+```json
+[
+ "/1.0"
+]
+```
### `/1.0/`
#### GET
@@ -254,48 +264,52 @@ Return value:
Return value (if trusted):
- {
- "api_extensions": [], # List of API extensions added after the API was marked stable
- "api_status": "stable", # API implementation status (one of, development, stable or deprecated)
- "api_version": "1.0", # The API version as a string
- "auth": "trusted", # Authentication state, one of "guest", "untrusted" or "trusted"
- "config": { # Host configuration
- "core.trust_password": true,
- "core.https_address": "[::]:8443"
- },
- "environment": { # Various information about the host (OS, kernel, ...)
- "addresses": [
- "1.2.3.4:8443",
- "[1234::1234]:8443"
- ],
- "architectures": [
- "x86_64",
- "i686"
- ],
- "certificate": "PEM certificate",
- "driver": "lxc",
- "driver_version": "1.0.6",
- "kernel": "Linux",
- "kernel_architecture": "x86_64",
- "kernel_version": "3.16",
- "server": "lxd",
- "server_pid": 10224,
- "server_version": "0.8.1"}
- "storage": "btrfs",
- "storage_version": "3.19",
- },
- "public": false, # Whether the server should be treated as a public (read-only) remote by the client
- }
+```json
+{
+ "api_extensions": [], # List of API extensions added after the API was marked stable
+ "api_status": "stable", # API implementation status (one of, development, stable or deprecated)
+ "api_version": "1.0", # The API version as a string
+ "auth": "trusted", # Authentication state, one of "guest", "untrusted" or "trusted"
+ "config": { # Host configuration
+ "core.trust_password": true,
+ "core.https_address": "[::]:8443"
+ },
+ "environment": { # Various information about the host (OS, kernel, ...)
+ "addresses": [
+ "1.2.3.4:8443",
+ "[1234::1234]:8443"
+ ],
+ "architectures": [
+ "x86_64",
+ "i686"
+ ],
+ "certificate": "PEM certificate",
+ "driver": "lxc",
+ "driver_version": "1.0.6",
+ "kernel": "Linux",
+ "kernel_architecture": "x86_64",
+ "kernel_version": "3.16",
+ "server": "lxd",
+ "server_pid": 10224,
+ "server_version": "0.8.1"}
+ "storage": "btrfs",
+ "storage_version": "3.19",
+ },
+ "public": false, # Whether the server should be treated as a public (read-only) remote by the client
+}
+```
Return value (if guest or untrusted):
- {
- "api_extensions": [], # List of API extensions added after the API was marked stable
- "api_status": "stable", # API implementation status (one of, development, stable or deprecated)
- "api_version": "1.0", # The API version as a string
- "auth": "guest", # Authentication state, one of "guest", "untrusted" or "trusted"
- "public": false, # Whether the server should be treated as a public (read-only) remote by the client
- }
+```json
+{
+ "api_extensions": [], # List of API extensions added after the API was marked stable
+ "api_status": "stable", # API implementation status (one of, development, stable or deprecated)
+ "api_version": "1.0", # The API version as a string
+ "auth": "guest", # Authentication state, one of "guest", "untrusted" or "trusted"
+ "public": false, # Whether the server should be treated as a public (read-only) remote by the client
+}
+```
#### PUT (ETag supported)
* Description: Replaces the server configuration or other properties
@@ -305,12 +319,14 @@ Return value (if guest or untrusted):
Input (replaces any existing config with the provided one):
- {
- "config": {
- "core.trust_password": "my-new-password",
- "core.https_address": "1.2.3.4:8443"
- }
+```json
+{
+ "config": {
+ "core.trust_password": "my-new-password",
+ "core.https_address": "1.2.3.4:8443"
}
+}
+```
#### PATCH (ETag supported)
* Description: Updates the server configuration or other properties
@@ -321,11 +337,13 @@ Input (replaces any existing config with the provided one):
Input (updates only the listed keys, rest remains intact):
- {
- "config": {
- "core.trust_password": "my-new-password"
- }
+```json
+{
+ "config": {
+ "core.trust_password": "my-new-password"
}
+}
+```
### `/1.0/certificates`
#### GET
@@ -336,9 +354,11 @@ Input (updates only the listed keys, rest remains intact):
Return:
- [
- "/1.0/certificates/3ee64be3c3c7d617a7470e14f2d847081ad467c8c26e1caad841c8f67f7c7b09"
- ]
+```json
+[
+ "/1.0/certificates/3ee64be3c3c7d617a7470e14f2d847081ad467c8c26e1caad841c8f67f7c7b09"
+]
+```
#### POST
* Description: add a new trusted certificate
@@ -348,12 +368,14 @@ Return:
Input:
- {
- "type": "client", # Certificate type (keyring), currently only client
- "certificate": "PEM certificate", # If provided, a valid x509 certificate. If not, the client certificate of the connection will be used
- "name": "foo", # An optional name for the certificate. If nothing is provided, the host in the TLS header for the request is used.
- "password": "server-trust-password" # The trust password for that server (only required if untrusted)
- }
+```json
+{
+ "type": "client", # Certificate type (keyring), currently only client
+ "certificate": "PEM certificate", # If provided, a valid x509 certificate. If not, the client certificate of the connection will be used
+ "name": "foo", # An optional name for the certificate. If nothing is provided, the host in the TLS header for the request is used.
+ "password": "server-trust-password" # The trust password for that server (only required if untrusted)
+}
+```
### `/1.0/certificates/<fingerprint>`
#### GET
@@ -364,12 +386,14 @@ Input:
Output:
- {
- "type": "client",
- "certificate": "PEM certificate",
- "name": "foo",
- "fingerprint": "SHA256 Hash of the raw certificate"
- }
+```json
+{
+ "type": "client",
+ "certificate": "PEM certificate",
+ "name": "foo",
+ "fingerprint": "SHA256 Hash of the raw certificate"
+}
+```
#### PUT (ETag supported)
* Description: Replaces the certificate properties
@@ -380,10 +404,12 @@ Output:
Input:
- {
- "type": "client",
- "name": "bar"
- }
+```json
+{
+ "type": "client",
+ "name": "bar"
+}
+```
#### PATCH (ETag supported)
* Description: Updates the certificate properties
@@ -394,9 +420,11 @@ Input:
Input:
- {
- "name": "baz"
- }
+```json
+{
+ "name": "baz"
+}
+```
#### DELETE
@@ -407,8 +435,10 @@ Input:
Input (none at present):
- {
- }
+```json
+{
+}
+```
HTTP code for this should be 202 (Accepted).
@@ -421,10 +451,12 @@ HTTP code for this should be 202 (Accepted).
Return value:
- [
- "/1.0/containers/blah",
- "/1.0/containers/blah1"
- ]
+```json
+[
+ "/1.0/containers/blah",
+ "/1.0/containers/blah1"
+]
+```
#### POST (optional `?target=<member>`)
* Description: Create a new container
@@ -434,192 +466,210 @@ Return value:
Input (container based on a local image with the "ubuntu/devel" alias):
- {
- "name": "my-new-container", # 64 chars max, ASCII, no slash, no colon and no comma
- "architecture": "x86_64",
- "profiles": ["default"], # List of profiles
- "ephemeral": true, # Whether to destroy the container on shutdown
- "config": {"limits.cpu": "2"}, # Config override.
- "devices": { # optional list of devices the container should have
- "kvm": {
- "path": "/dev/kvm",
- "type": "unix-char"
- },
+```json
+{
+ "name": "my-new-container", # 64 chars max, ASCII, no slash, no colon and no comma
+ "architecture": "x86_64",
+ "profiles": ["default"], # List of profiles
+ "ephemeral": true, # Whether to destroy the container on shutdown
+ "config": {"limits.cpu": "2"}, # Config override.
+ "devices": { # optional list of devices the container should have
+ "kvm": {
+ "path": "/dev/kvm",
+ "type": "unix-char"
},
- "instance_type": "c2.micro", # An optional instance type to use as basis for limits
- "source": {"type": "image", # Can be: "image", "migration", "copy" or "none"
- "alias": "ubuntu/devel"}, # Name of the alias
- }
+ },
+ "instance_type": "c2.micro", # An optional instance type to use as basis for limits
+ "source": {"type": "image", # Can be: "image", "migration", "copy" or "none"
+ "alias": "ubuntu/devel"}, # Name of the alias
+}
+```
Input (container based on a local image identified by its fingerprint):
- {
- "name": "my-new-container", # 64 chars max, ASCII, no slash, no colon and no comma
- "architecture": "x86_64",
- "profiles": ["default"], # List of profiles
- "ephemeral": true, # Whether to destroy the container on shutdown
- "config": {"limits.cpu": "2"}, # Config override.
- "devices": { # optional list of devices the container should have
- "kvm": {
- "path": "/dev/kvm",
- "type": "unix-char"
- },
+```json
+{
+ "name": "my-new-container", # 64 chars max, ASCII, no slash, no colon and no comma
+ "architecture": "x86_64",
+ "profiles": ["default"], # List of profiles
+ "ephemeral": true, # Whether to destroy the container on shutdown
+ "config": {"limits.cpu": "2"}, # Config override.
+ "devices": { # optional list of devices the container should have
+ "kvm": {
+ "path": "/dev/kvm",
+ "type": "unix-char"
},
- "source": {"type": "image", # Can be: "image", "migration", "copy" or "none"
- "fingerprint": "SHA-256"}, # Fingerprint
- }
+ },
+ "source": {"type": "image", # Can be: "image", "migration", "copy" or "none"
+ "fingerprint": "SHA-256"}, # Fingerprint
+}
+```
Input (container based on most recent match based on image properties):
- {
- "name": "my-new-container", # 64 chars max, ASCII, no slash, no colon and no comma
- "architecture": "x86_64",
- "profiles": ["default"], # List of profiles
- "ephemeral": true, # Whether to destroy the container on shutdown
- "config": {"limits.cpu": "2"}, # Config override.
- "devices": { # optional list of devices the container should have
- "kvm": {
- "path": "/dev/kvm",
- "type": "unix-char"
- },
+```json
+{
+ "name": "my-new-container", # 64 chars max, ASCII, no slash, no colon and no comma
+ "architecture": "x86_64",
+ "profiles": ["default"], # List of profiles
+ "ephemeral": true, # Whether to destroy the container on shutdown
+ "config": {"limits.cpu": "2"}, # Config override.
+ "devices": { # optional list of devices the container should have
+ "kvm": {
+ "path": "/dev/kvm",
+ "type": "unix-char"
},
- "source": {"type": "image", # Can be: "image", "migration", "copy" or "none"
- "properties": { # Properties
- "os": "ubuntu",
- "release": "14.04",
- "architecture": "x86_64"
- }},
- }
+ },
+ "source": {"type": "image", # Can be: "image", "migration", "copy" or "none"
+ "properties": { # Properties
+ "os": "ubuntu",
+ "release": "14.04",
+ "architecture": "x86_64"
+ }},
+}
+```
Input (container without a pre-populated rootfs, useful when attaching to an existing one):
- {
- "name": "my-new-container", # 64 chars max, ASCII, no slash, no colon and no comma
- "architecture": "x86_64",
- "profiles": ["default"], # List of profiles
- "ephemeral": true, # Whether to destroy the container on shutdown
- "config": {"limits.cpu": "2"}, # Config override.
- "devices": { # optional list of devices the container should have
- "kvm": {
- "path": "/dev/kvm",
- "type": "unix-char"
- },
+```json
+{
+ "name": "my-new-container", # 64 chars max, ASCII, no slash, no colon and no comma
+ "architecture": "x86_64",
+ "profiles": ["default"], # List of profiles
+ "ephemeral": true, # Whether to destroy the container on shutdown
+ "config": {"limits.cpu": "2"}, # Config override.
+ "devices": { # optional list of devices the container should have
+ "kvm": {
+ "path": "/dev/kvm",
+ "type": "unix-char"
},
- "source": {"type": "none"}, # Can be: "image", "migration", "copy" or "none"
- }
+ },
+ "source": {"type": "none"}, # Can be: "image", "migration", "copy" or "none"
+}
+```
Input (using a public remote image):
- {
- "name": "my-new-container", # 64 chars max, ASCII, no slash, no colon and no comma
- "architecture": "x86_64",
- "profiles": ["default"], # List of profiles
- "ephemeral": true, # Whether to destroy the container on shutdown
- "config": {"limits.cpu": "2"}, # Config override.
- "devices": { # optional list of devices the container should have
- "kvm": {
- "path": "/dev/kvm",
- "type": "unix-char"
- },
+```json
+{
+ "name": "my-new-container", # 64 chars max, ASCII, no slash, no colon and no comma
+ "architecture": "x86_64",
+ "profiles": ["default"], # List of profiles
+ "ephemeral": true, # Whether to destroy the container on shutdown
+ "config": {"limits.cpu": "2"}, # Config override.
+ "devices": { # optional list of devices the container should have
+ "kvm": {
+ "path": "/dev/kvm",
+ "type": "unix-char"
},
- "source": {"type": "image", # Can be: "image", "migration", "copy" or "none"
- "mode": "pull", # One of "local" (default) or "pull"
- "server": "https://10.0.2.3:8443", # Remote server (pull mode only)
- "protocol": "lxd", # Protocol (one of lxd or simplestreams, defaults to lxd)
- "certificate": "PEM certificate", # Optional PEM certificate. If not mentioned, system CA is used.
- "alias": "ubuntu/devel"}, # Name of the alias
- }
+ },
+ "source": {"type": "image", # Can be: "image", "migration", "copy" or "none"
+ "mode": "pull", # One of "local" (default) or "pull"
+ "server": "https://10.0.2.3:8443", # Remote server (pull mode only)
+ "protocol": "lxd", # Protocol (one of lxd or simplestreams, defaults to lxd)
+ "certificate": "PEM certificate", # Optional PEM certificate. If not mentioned, system CA is used.
+ "alias": "ubuntu/devel"}, # Name of the alias
+}
+```
Input (using a private remote image after having obtained a secret for that image):
- {
- "name": "my-new-container", # 64 chars max, ASCII, no slash, no colon and no comma
- "architecture": "x86_64",
- "profiles": ["default"], # List of profiles
- "ephemeral": true, # Whether to destroy the container on shutdown
- "config": {"limits.cpu": "2"}, # Config override.
- "devices": { # optional list of devices the container should have
- "kvm": {
- "path": "/dev/kvm",
- "type": "unix-char"
- },
+```json
+{
+ "name": "my-new-container", # 64 chars max, ASCII, no slash, no colon and no comma
+ "architecture": "x86_64",
+ "profiles": ["default"], # List of profiles
+ "ephemeral": true, # Whether to destroy the container on shutdown
+ "config": {"limits.cpu": "2"}, # Config override.
+ "devices": { # optional list of devices the container should have
+ "kvm": {
+ "path": "/dev/kvm",
+ "type": "unix-char"
},
- "source": {"type": "image", # Can be: "image", "migration", "copy" or "none"
- "mode": "pull", # One of "local" (default) or "pull"
- "server": "https://10.0.2.3:8443", # Remote server (pull mode only)
- "secret": "my-secret-string", # Secret to use to retrieve the image (pull mode only)
- "certificate": "PEM certificate", # Optional PEM certificate. If not mentioned, system CA is used.
- "alias": "ubuntu/devel"}, # Name of the alias
- }
+ },
+ "source": {"type": "image", # Can be: "image", "migration", "copy" or "none"
+ "mode": "pull", # One of "local" (default) or "pull"
+ "server": "https://10.0.2.3:8443", # Remote server (pull mode only)
+ "secret": "my-secret-string", # Secret to use to retrieve the image (pull mode only)
+ "certificate": "PEM certificate", # Optional PEM certificate. If not mentioned, system CA is used.
+ "alias": "ubuntu/devel"}, # Name of the alias
+}
+```
Input (using a remote container, sent over the migration websocket):
- {
- "name": "my-new-container", # 64 chars max, ASCII, no slash, no colon and no comma
- "architecture": "x86_64",
- "profiles": ["default"], # List of profiles
- "ephemeral": true, # Whether to destroy the container on shutdown
- "config": {"limits.cpu": "2"}, # Config override.
- "devices": { # optional list of devices the container should have
- "kvm": {
- "path": "/dev/kvm",
- "type": "unix-char"
- },
+```json
+{
+ "name": "my-new-container", # 64 chars max, ASCII, no slash, no colon and no comma
+ "architecture": "x86_64",
+ "profiles": ["default"], # List of profiles
+ "ephemeral": true, # Whether to destroy the container on shutdown
+ "config": {"limits.cpu": "2"}, # Config override.
+ "devices": { # optional list of devices the container should have
+ "kvm": {
+ "path": "/dev/kvm",
+ "type": "unix-char"
},
- "source": {"type": "migration", # Can be: "image", "migration", "copy" or "none"
- "mode": "pull", # "pull" and "push" is supported for now
- "operation": "https://10.0.2.3:8443/1.0/operations/<UUID>", # Full URL to the remote operation (pull mode only)
- "certificate": "PEM certificate", # Optional PEM certificate. If not mentioned, system CA is used.
- "base-image": "<fingerprint>", # Optional, the base image the container was created from
- "container_only": true, # Whether to migrate only the container without snapshots. Can be "true" or "false".
- "secrets": {"control": "my-secret-string", # Secrets to use when talking to the migration source
- "criu": "my-other-secret",
- "fs": "my third secret"}
- }
- }
+ },
+ "source": {"type": "migration", # Can be: "image", "migration", "copy" or "none"
+ "mode": "pull", # "pull" and "push" is supported for now
+ "operation": "https://10.0.2.3:8443/1.0/operations/<UUID>", # Full URL to the remote operation (pull mode only)
+ "certificate": "PEM certificate", # Optional PEM certificate. If not mentioned, system CA is used.
+ "base-image": "<fingerprint>", # Optional, the base image the container was created from
+ "container_only": true, # Whether to migrate only the container without snapshots. Can be "true" or "false".
+ "secrets": {"control": "my-secret-string", # Secrets to use when talking to the migration source
+ "criu": "my-other-secret",
+ "fs": "my third secret"}
+ }
+}
+```
Input (using a local container):
- {
- "name": "my-new-container", # 64 chars max, ASCII, no slash, no colon and no comma
- "profiles": ["default"], # List of profiles
- "ephemeral": true, # Whether to destroy the container on shutdown
- "config": {"limits.cpu": "2"}, # Config override.
- "devices": { # optional list of devices the container should have
- "kvm": {
- "path": "/dev/kvm",
- "type": "unix-char"
- },
+```json
+{
+ "name": "my-new-container", # 64 chars max, ASCII, no slash, no colon and no comma
+ "profiles": ["default"], # List of profiles
+ "ephemeral": true, # Whether to destroy the container on shutdown
+ "config": {"limits.cpu": "2"}, # Config override.
+ "devices": { # optional list of devices the container should have
+ "kvm": {
+ "path": "/dev/kvm",
+ "type": "unix-char"
},
- "source": {"type": "copy", # Can be: "image", "migration", "copy" or "none"
- "container_only": true, # Whether to copy only the container without snapshots. Can be "true" or "false".
- "source": "my-old-container"} # Name of the source container
- }
+ },
+ "source": {"type": "copy", # Can be: "image", "migration", "copy" or "none"
+ "container_only": true, # Whether to copy only the container without snapshots. Can be "true" or "false".
+ "source": "my-old-container"} # Name of the source container
+}
+```
Input (using a remote container, in push mode sent over the migration websocket via client proxying):
- {
- "name": "my-new-container", # 64 chars max, ASCII, no slash, no colon and no comma
- "architecture": "x86_64",
- "profiles": ["default"], # List of profiles
- "ephemeral": true, # Whether to destroy the container on shutdown
- "config": {"limits.cpu": "2"}, # Config override.
- "devices": { # optional list of devices the container should have
- "kvm": {
- "path": "/dev/kvm",
- "type": "unix-char"
- },
+```json
+{
+ "name": "my-new-container", # 64 chars max, ASCII, no slash, no colon and no comma
+ "architecture": "x86_64",
+ "profiles": ["default"], # List of profiles
+ "ephemeral": true, # Whether to destroy the container on shutdown
+ "config": {"limits.cpu": "2"}, # Config override.
+ "devices": { # optional list of devices the container should have
+ "kvm": {
+ "path": "/dev/kvm",
+ "type": "unix-char"
},
- "source": {"type": "migration", # Can be: "image", "migration", "copy" or "none"
- "mode": "push", # "pull" and "push" are supported
- "base-image": "<fingerprint>", # Optional, the base image the container was created from
- "live": true, # Whether migration is performed live
- "container_only": true} # Whether to migrate only the container without snapshots. Can be "true" or "false".
- }
+ },
+ "source": {"type": "migration", # Can be: "image", "migration", "copy" or "none"
+ "mode": "push", # "pull" and "push" are supported
+ "base-image": "<fingerprint>", # Optional, the base image the container was created from
+ "live": true, # Whether migration is performed live
+ "container_only": true} # Whether to migrate only the container without snapshots. Can be "true" or "false".
+}
+```
Input (using a backup):
- Raw compressed tarball as provided by a backup download.
+Raw compressed tarball as provided by a backup download.
### `/1.0/containers/<name>`
#### GET
@@ -630,47 +680,49 @@ Input (using a backup):
Output:
- {
- "architecture": "x86_64",
- "config": {
- "limits.cpu": "3",
- "volatile.base_image": "97d97a3d1d053840ca19c86cdd0596cf1be060c5157d31407f2a4f9f350c78cc",
- "volatile.eth0.hwaddr": "00:16:3e:1c:94:38"
- },
- "created_at": "2016-02-16T01:05:05Z",
- "devices": {
- "rootfs": {
- "path": "/",
- "type": "disk"
- }
- },
- "ephemeral": false,
- "expanded_config": { # the result of expanding profiles and adding the container's local config
- "limits.cpu": "3",
- "volatile.base_image": "97d97a3d1d053840ca19c86cdd0596cf1be060c5157d31407f2a4f9f350c78cc",
- "volatile.eth0.hwaddr": "00:16:3e:1c:94:38"
- },
- "expanded_devices": { # the result of expanding profiles and adding the container's local devices
- "eth0": {
- "name": "eth0",
- "nictype": "bridged",
- "parent": "lxdbr0",
- "type": "nic"
- },
- "root": {
- "path": "/",
- "type": "disk"
- }
+```json
+{
+ "architecture": "x86_64",
+ "config": {
+ "limits.cpu": "3",
+ "volatile.base_image": "97d97a3d1d053840ca19c86cdd0596cf1be060c5157d31407f2a4f9f350c78cc",
+ "volatile.eth0.hwaddr": "00:16:3e:1c:94:38"
+ },
+ "created_at": "2016-02-16T01:05:05Z",
+ "devices": {
+ "rootfs": {
+ "path": "/",
+ "type": "disk"
+ }
+ },
+ "ephemeral": false,
+ "expanded_config": { # the result of expanding profiles and adding the container's local config
+ "limits.cpu": "3",
+ "volatile.base_image": "97d97a3d1d053840ca19c86cdd0596cf1be060c5157d31407f2a4f9f350c78cc",
+ "volatile.eth0.hwaddr": "00:16:3e:1c:94:38"
+ },
+ "expanded_devices": { # the result of expanding profiles and adding the container's local devices
+ "eth0": {
+ "name": "eth0",
+ "nictype": "bridged",
+ "parent": "lxdbr0",
+ "type": "nic"
},
- "last_used_at": "2016-02-16T01:05:05Z",
- "name": "my-container",
- "profiles": [
- "default"
- ],
- "stateful": false, # If true, indicates that the container has some stored state that can be restored on startup
- "status": "Running",
- "status_code": 103
- }
+ "root": {
+ "path": "/",
+ "type": "disk"
+ }
+ },
+ "last_used_at": "2016-02-16T01:05:05Z",
+ "name": "my-container",
+ "profiles": [
+ "default"
+ ],
+ "stateful": false, # If true, indicates that the container has some stored state that can be restored on startup
+ "status": "Running",
+ "status_code": 103
+}
+```
#### PUT (ETag supported)
* Description: replaces container configuration or restore snapshot
@@ -680,24 +732,26 @@ Output:
Input (update container configuration):
- {
- "architecture": "x86_64",
- "config": {
- "limits.cpu": "4",
- "volatile.base_image": "97d97a3d1d053840ca19c86cdd0596cf1be060c5157d31407f2a4f9f350c78cc",
- "volatile.eth0.hwaddr": "00:16:3e:1c:94:38"
- },
- "devices": {
- "rootfs": {
- "path": "/",
- "type": "disk"
- }
- },
- "ephemeral": true,
- "profiles": [
- "default"
- ]
- }
+```json
+{
+ "architecture": "x86_64",
+ "config": {
+ "limits.cpu": "4",
+ "volatile.base_image": "97d97a3d1d053840ca19c86cdd0596cf1be060c5157d31407f2a4f9f350c78cc",
+ "volatile.eth0.hwaddr": "00:16:3e:1c:94:38"
+ },
+ "devices": {
+ "rootfs": {
+ "path": "/",
+ "type": "disk"
+ }
+ },
+ "ephemeral": true,
+ "profiles": [
+ "default"
+ ]
+}
+```
Takes the same structure as that returned by GET but doesn't allow name
changes (see POST below) or changes to the status sub-dict (since that's
@@ -705,9 +759,11 @@ read-only).
Input (restore snapshot):
- {
- "restore": "snapshot-name"
- }
+```json
+{
+ "restore": "snapshot-name"
+}
+```
#### PATCH (ETag supported)
* Description: update container configuration
@@ -718,17 +774,19 @@ Input (restore snapshot):
Input:
- {
- "config": {
- "limits.cpu": "4"
- },
- "devices": {
- "rootfs": {
- "size": "5GB"
- }
- },
- "ephemeral": true
- }
+```json
+{
+ "config": {
+ "limits.cpu": "4"
+ },
+ "devices": {
+ "rootfs": {
+ "size": "5GB"
+ }
+ },
+ "ephemeral": true
+}
+```
#### POST (optional `?target=<member>`)
* Description: used to rename/migrate the container
@@ -740,17 +798,21 @@ Renaming to an existing name must return the 409 (Conflict) HTTP code.
Input (simple rename):
- {
- "name": "new-name"
- }
+```json
+{
+ "name": "new-name"
+}
+```
Input (migration across lxd instances or lxd cluster members):
- {
- "name": "new-name"
- "migration": true
- "live": "true"
- }
+```json
+{
+ "name": "new-name"
+ "migration": true
+ "live": "true"
+}
+```
The migration does not actually start until someone (i.e. another lxd instance)
connects to all the websockets and begins negotiation with the source.
@@ -759,11 +821,13 @@ To migrate between cluster members the `?target=<member>` option is required.
Output in metadata section (for migration):
- {
- "control": "secret1", # Migration control socket
- "criu": "secret2", # State transfer socket (only if live migrating)
- "fs": "secret3" # Filesystem transfer socket
- }
+```json
+{
+ "control": "secret1", # Migration control socket
+ "criu": "secret2", # State transfer socket (only if live migrating)
+ "fs": "secret3" # Filesystem transfer socket
+}
+```
These are the secrets that should be passed to the create call.
@@ -775,8 +839,10 @@ These are the secrets that should be passed to the create call.
Input (none at present):
- {
- }
+```json
+{
+}
+```
HTTP code for this should be 202 (Accepted).
@@ -795,23 +861,27 @@ HTTP code for this should be 202 (Accepted).
Input (attach to /dev/console):
- {
- "width": 80, # Initial width of the terminal (optional)
- "height": 25, # Initial height of the terminal (optional)
- }
+```json
+{
+ "width": 80, # Initial width of the terminal (optional)
+ "height": 25, # Initial height of the terminal (optional)
+}
+```
The control websocket can be used to send out-of-band messages during a console session.
This is currently used for window size changes.
Control (window size change):
- {
- "command": "window-resize",
- "args": {
- "width": "80",
- "height": "50"
- }
+```json
+{
+ "command": "window-resize",
+ "args": {
+ "width": "80",
+ "height": "50"
}
+}
+```
#### DELETE
* Description: empty the container's console log
@@ -828,18 +898,20 @@ Control (window size change):
Input (run bash):
- {
- "command": ["/bin/bash"], # Command and arguments
- "environment": {}, # Optional extra environment variables to set
- "wait-for-websocket": false, # Whether to wait for a connection before starting the process
- "record-output": false, # Whether to store stdout and stderr (only valid with wait-for-websocket=false) (requires API extension container_exec_recording)
- "interactive": true, # Whether to allocate a pts device instead of PIPEs
- "width": 80, # Initial width of the terminal (optional)
- "height": 25, # Initial height of the terminal (optional)
- "user": 1000, # User to run the command as (optional)
- "group: 1000, # Group to run the command as (optional)
- "cwd": "/tmp" # Current working directory (optional)
- }
+```json
+{
+ "command": ["/bin/bash"], # Command and arguments
+ "environment": {}, # Optional extra environment variables to set
+ "wait-for-websocket": false, # Whether to wait for a connection before starting the process
+ "record-output": false, # Whether to store stdout and stderr (only valid with wait-for-websocket=false) (requires API extension container_exec_recording)
+ "interactive": true, # Whether to allocate a pts device instead of PIPEs
+ "width": 80, # Initial width of the terminal (optional)
+ "height": 25, # Initial height of the terminal (optional)
+ "user": 1000, # User to run the command as (optional)
+ "group": 1000, # Group to run the command as (optional)
+ "cwd": "/tmp" # Current working directory (optional)
+}
+```
`wait-for-websocket` indicates whether the operation should block and wait for
a websocket connection to start (so that users can pass stdin and read
@@ -865,57 +937,69 @@ This is currently used for window size changes and for forwarding of signals.
Control (window size change):
- {
- "command": "window-resize",
- "args": {
- "width": "80",
- "height": "50"
- }
+```json
+{
+ "command": "window-resize",
+ "args": {
+ "width": "80",
+ "height": "50"
}
+}
+```
Control (SIGUSR1 signal):
- {
- "command": "signal",
- "signal": 10
- }
+```json
+{
+ "command": "signal",
+ "signal": 10
+}
+```
Return (with wait-for-websocket=true and interactive=false):
- {
- "fds": {
- "0": "f5b6c760c0aa37a6430dd2a00c456430282d89f6e1661a077a926ed1bf3d1c21",
- "1": "464dcf9f8fdce29d0d6478284523a9f26f4a31ae365d94cd38bac41558b797cf",
- "2": "25b70415b686360e3b03131e33d6d94ee85a7f19b0f8d141d6dca5a1fc7b00eb",
- "control": "20c479d9532ab6d6c3060f6cdca07c1f177647c9d96f0c143ab61874160bd8a5"
- }
+```json
+{
+ "fds": {
+ "0": "f5b6c760c0aa37a6430dd2a00c456430282d89f6e1661a077a926ed1bf3d1c21",
+ "1": "464dcf9f8fdce29d0d6478284523a9f26f4a31ae365d94cd38bac41558b797cf",
+ "2": "25b70415b686360e3b03131e33d6d94ee85a7f19b0f8d141d6dca5a1fc7b00eb",
+ "control": "20c479d9532ab6d6c3060f6cdca07c1f177647c9d96f0c143ab61874160bd8a5"
}
+}
+```
Return (with wait-for-websocket=true and interactive=true):
- {
- "fds": {
- "0": "f5b6c760c0aa37a6430dd2a00c456430282d89f6e1661a077a926ed1bf3d1c21",
- "control": "20c479d9532ab6d6c3060f6cdca07c1f177647c9d96f0c143ab61874160bd8a5"
- }
+```json
+{
+ "fds": {
+ "0": "f5b6c760c0aa37a6430dd2a00c456430282d89f6e1661a077a926ed1bf3d1c21",
+ "control": "20c479d9532ab6d6c3060f6cdca07c1f177647c9d96f0c143ab61874160bd8a5"
}
+}
+```
Return (with interactive=false and record-output=true):
- {
- "output": {
- "1": "/1.0/containers/example/logs/exec_b0f737b4-2c8a-4edf-a7c1-4cc7e4e9e155.stdout",
- "2": "/1.0/containers/example/logs/exec_b0f737b4-2c8a-4edf-a7c1-4cc7e4e9e155.stderr"
- },
- "return": 0
- }
+```json
+{
+ "output": {
+ "1": "/1.0/containers/example/logs/exec_b0f737b4-2c8a-4edf-a7c1-4cc7e4e9e155.stdout",
+ "2": "/1.0/containers/example/logs/exec_b0f737b4-2c8a-4edf-a7c1-4cc7e4e9e155.stderr"
+ },
+ "return": 0
+}
+```
When the exec command finishes, its exit status is available from the
operation's metadata:
- {
- "return": 0
- }
+```json
+{
+ "return": 0
+}
+```
### `/1.0/containers/<name>/files`
#### GET (`?path=/path/inside/the/container`)
@@ -965,8 +1049,10 @@ browser.
Input (none at present):
- {
- }
+```json
+{
+}
+```
### `/1.0/containers/<name>/snapshots`
#### GET
@@ -977,9 +1063,11 @@ Input (none at present):
Return value:
- [
- "/1.0/containers/blah/snapshots/snap0"
- ]
+```json
+[
+ "/1.0/containers/blah/snapshots/snap0"
+]
+```
#### POST
* Description: create a new snapshot
@@ -989,10 +1077,12 @@ Return value:
Input:
- {
- "name": "my-snapshot", # Name of the snapshot
- "stateful": true # Whether to include state too
- }
+```json
+{
+ "name": "my-snapshot", # Name of the snapshot
+ "stateful": true # Whether to include state too
+}
+```
### `/1.0/containers/<name>/snapshots/<name>`
#### GET
@@ -1003,52 +1093,54 @@ Input:
Return:
- {
- "architecture": "x86_64",
- "config": {
- "security.nesting": "true",
- "volatile.base_image": "a49d26ce5808075f5175bf31f5cb90561f5023dcd408da8ac5e834096d46b2d8",
- "volatile.eth0.hwaddr": "00:16:3e:ec:65:a8",
- "volatile.last_state.idmap": "[{\"Isuid\":true,\"Isgid\":false,\"Hostid\":100000,\"Nsid\":0,\"Maprange\":65536},{\"Isuid\":false,\"Isgid\":true,\"Hostid\":100000,\"Nsid\":0,\"Maprange\":65536}]",
+```json
+{
+ "architecture": "x86_64",
+ "config": {
+ "security.nesting": "true",
+ "volatile.base_image": "a49d26ce5808075f5175bf31f5cb90561f5023dcd408da8ac5e834096d46b2d8",
+ "volatile.eth0.hwaddr": "00:16:3e:ec:65:a8",
+ "volatile.last_state.idmap": "[{\"Isuid\":true,\"Isgid\":false,\"Hostid\":100000,\"Nsid\":0,\"Maprange\":65536},{\"Isuid\":false,\"Isgid\":true,\"Hostid\":100000,\"Nsid\":0,\"Maprange\":65536}]",
+ },
+ "created_at": "2016-03-08T23:55:08Z",
+ "devices": {
+ "eth0": {
+ "name": "eth0",
+ "nictype": "bridged",
+ "parent": "lxdbr0",
+ "type": "nic"
},
- "created_at": "2016-03-08T23:55:08Z",
- "devices": {
- "eth0": {
- "name": "eth0",
- "nictype": "bridged",
- "parent": "lxdbr0",
- "type": "nic"
- },
- "root": {
- "path": "/",
- "type": "disk"
- },
+ "root": {
+ "path": "/",
+ "type": "disk"
},
- "ephemeral": false,
- "expanded_config": {
- "security.nesting": "true",
- "volatile.base_image": "a49d26ce5808075f5175bf31f5cb90561f5023dcd408da8ac5e834096d46b2d8",
- "volatile.eth0.hwaddr": "00:16:3e:ec:65:a8",
- "volatile.last_state.idmap": "[{\"Isuid\":true,\"Isgid\":false,\"Hostid\":100000,\"Nsid\":0,\"Maprange\":65536},{\"Isuid\":false,\"Isgid\":true,\"Hostid\":100000,\"Nsid\":0,\"Maprange\":65536}]",
+ },
+ "ephemeral": false,
+ "expanded_config": {
+ "security.nesting": "true",
+ "volatile.base_image": "a49d26ce5808075f5175bf31f5cb90561f5023dcd408da8ac5e834096d46b2d8",
+ "volatile.eth0.hwaddr": "00:16:3e:ec:65:a8",
+ "volatile.last_state.idmap": "[{\"Isuid\":true,\"Isgid\":false,\"Hostid\":100000,\"Nsid\":0,\"Maprange\":65536},{\"Isuid\":false,\"Isgid\":true,\"Hostid\":100000,\"Nsid\":0,\"Maprange\":65536}]",
+ },
+ "expanded_devices": {
+ "eth0": {
+ "name": "eth0",
+ "nictype": "bridged",
+ "parent": "lxdbr0",
+ "type": "nic"
},
- "expanded_devices": {
- "eth0": {
- "name": "eth0",
- "nictype": "bridged",
- "parent": "lxdbr0",
- "type": "nic"
- },
- "root": {
- "path": "/",
- "type": "disk"
- },
+ "root": {
+ "path": "/",
+ "type": "disk"
},
- "name": "blah",
- "profiles": [
- "default"
- ],
- "stateful": false
- }
+ },
+ "name": "blah",
+ "profiles": [
+ "default"
+ ],
+ "stateful": false
+}
+```
#### POST
* Description: used to rename/migrate the snapshot
@@ -1058,24 +1150,30 @@ Return:
Input (rename the snapshot):
- {
- "name": "new-name"
- }
+```json
+{
+ "name": "new-name"
+}
+```
Input (setup the migration source):
- {
- "name": "new-name"
- "migration": true
- "live": "true"
- }
+```json
+{
+ "name": "new-name"
+ "migration": true
+ "live": "true"
+}
+```
Return (with migration=true):
- {
- "control": "secret1", # Migration control socket
- "fs": "secret3" # Filesystem transfer socket
- }
+```json
+{
+ "control": "secret1", # Migration control socket
+ "fs": "secret3" # Filesystem transfer socket
+}
+```
Renaming to an existing name must return the 409 (Conflict) HTTP code.
@@ -1087,8 +1185,10 @@ Renaming to an existing name must return the 409 (Conflict) HTTP code.
Input (none at present):
- {
- }
+```json
+{
+}
+```
#### PUT
* Description: update the snapshot
@@ -1098,9 +1198,11 @@ Input (none at present):
Input:
- {
- "expires_at": "2019-01-16T12:34:56+02:00"
- }
+```json
+{
+ "expires_at": "2019-01-16T12:34:56+02:00"
+}
+```
HTTP code for this should be 202 (Accepted).
@@ -1113,147 +1215,149 @@ HTTP code for this should be 202 (Accepted).
Output:
- {
- "type": "sync",
- "status": "Success",
- "status_code": 200,
- "metadata": {
- "status": "Running",
- "status_code": 103,
- "cpu": {
- "usage": 4986019722
- },
- "disk": {
- "root": {
- "usage": 422330368
- }
- },
- "memory": {
- "usage": 51126272,
- "usage_peak": 70246400,
- "swap_usage": 0,
- "swap_usage_peak": 0
+```json
+{
+ "type": "sync",
+ "status": "Success",
+ "status_code": 200,
+ "metadata": {
+ "status": "Running",
+ "status_code": 103,
+ "cpu": {
+ "usage": 4986019722
+ },
+ "disk": {
+ "root": {
+ "usage": 422330368
+ }
+ },
+ "memory": {
+ "usage": 51126272,
+ "usage_peak": 70246400,
+ "swap_usage": 0,
+ "swap_usage_peak": 0
+ },
+ "network": {
+ "eth0": {
+ "addresses": [
+ {
+ "family": "inet",
+ "address": "10.0.3.27",
+ "netmask": "24",
+ "scope": "global"
+ },
+ {
+ "family": "inet6",
+ "address": "fe80::216:3eff:feec:65a8",
+ "netmask": "64",
+ "scope": "link"
+ }
+ ],
+ "counters": {
+ "bytes_received": 33942,
+ "bytes_sent": 30810,
+ "packets_received": 402,
+ "packets_sent": 178
+ },
+ "hwaddr": "00:16:3e:ec:65:a8",
+ "host_name": "vethBWTSU5",
+ "mtu": 1500,
+ "state": "up",
+ "type": "broadcast"
},
- "network": {
- "eth0": {
- "addresses": [
- {
- "family": "inet",
- "address": "10.0.3.27",
- "netmask": "24",
- "scope": "global"
- },
- {
- "family": "inet6",
- "address": "fe80::216:3eff:feec:65a8",
- "netmask": "64",
- "scope": "link"
- }
- ],
- "counters": {
- "bytes_received": 33942,
- "bytes_sent": 30810,
- "packets_received": 402,
- "packets_sent": 178
+ "lo": {
+ "addresses": [
+ {
+ "family": "inet",
+ "address": "127.0.0.1",
+ "netmask": "8",
+ "scope": "local"
},
- "hwaddr": "00:16:3e:ec:65:a8",
- "host_name": "vethBWTSU5",
- "mtu": 1500,
- "state": "up",
- "type": "broadcast"
+ {
+ "family": "inet6",
+ "address": "::1",
+ "netmask": "128",
+ "scope": "local"
+ }
+ ],
+ "counters": {
+ "bytes_received": 86816,
+ "bytes_sent": 86816,
+ "packets_received": 1226,
+ "packets_sent": 1226
},
- "lo": {
- "addresses": [
- {
- "family": "inet",
- "address": "127.0.0.1",
- "netmask": "8",
- "scope": "local"
- },
- {
- "family": "inet6",
- "address": "::1",
- "netmask": "128",
- "scope": "local"
- }
- ],
- "counters": {
- "bytes_received": 86816,
- "bytes_sent": 86816,
- "packets_received": 1226,
- "packets_sent": 1226
+ "hwaddr": "",
+ "host_name": "",
+ "mtu": 65536,
+ "state": "up",
+ "type": "loopback"
+ },
+ "lxdbr0": {
+ "addresses": [
+ {
+ "family": "inet",
+ "address": "10.0.3.1",
+ "netmask": "24",
+ "scope": "global"
},
- "hwaddr": "",
- "host_name": "",
- "mtu": 65536,
- "state": "up",
- "type": "loopback"
+ {
+ "family": "inet6",
+ "address": "fe80::68d4:87ff:fe40:7769",
+ "netmask": "64",
+ "scope": "link"
+ }
+ ],
+ "counters": {
+ "bytes_received": 0,
+ "bytes_sent": 570,
+ "packets_received": 0,
+ "packets_sent": 7
},
- "lxdbr0": {
- "addresses": [
- {
- "family": "inet",
- "address": "10.0.3.1",
- "netmask": "24",
- "scope": "global"
- },
- {
- "family": "inet6",
- "address": "fe80::68d4:87ff:fe40:7769",
- "netmask": "64",
- "scope": "link"
- }
- ],
- "counters": {
- "bytes_received": 0,
- "bytes_sent": 570,
- "packets_received": 0,
- "packets_sent": 7
+ "hwaddr": "6a:d4:87:40:77:69",
+ "host_name": "",
+ "mtu": 1500,
+ "state": "up",
+ "type": "broadcast"
+ },
+ "zt0": {
+ "addresses": [
+ {
+ "family": "inet",
+ "address": "29.17.181.59",
+ "netmask": "7",
+ "scope": "global"
},
- "hwaddr": "6a:d4:87:40:77:69",
- "host_name": "",
- "mtu": 1500,
- "state": "up",
- "type": "broadcast"
- },
- "zt0": {
- "addresses": [
- {
- "family": "inet",
- "address": "29.17.181.59",
- "netmask": "7",
- "scope": "global"
- },
- {
- "family": "inet6",
- "address": "fd80:56c2:e21c:0:199:9379:e711:b3e1",
- "netmask": "88",
- "scope": "global"
- },
- {
- "family": "inet6",
- "address": "fe80::79:e7ff:fe0d:5123",
- "netmask": "64",
- "scope": "link"
- }
- ],
- "counters": {
- "bytes_received": 0,
- "bytes_sent": 806,
- "packets_received": 0,
- "packets_sent": 9
+ {
+ "family": "inet6",
+ "address": "fd80:56c2:e21c:0:199:9379:e711:b3e1",
+ "netmask": "88",
+ "scope": "global"
},
- "hwaddr": "02:79:e7:0d:51:23",
- "host_name": "",
- "mtu": 2800,
- "state": "up",
- "type": "broadcast"
- }
- },
- "pid": 13663,
- "processes": 32
- }
+ {
+ "family": "inet6",
+ "address": "fe80::79:e7ff:fe0d:5123",
+ "netmask": "64",
+ "scope": "link"
+ }
+ ],
+ "counters": {
+ "bytes_received": 0,
+ "bytes_sent": 806,
+ "packets_received": 0,
+ "packets_sent": 9
+ },
+ "hwaddr": "02:79:e7:0d:51:23",
+ "host_name": "",
+ "mtu": 2800,
+ "state": "up",
+ "type": "broadcast"
+ }
+ },
+ "pid": 13663,
+ "processes": 32
}
+}
+```
#### PUT
* Description: change the container state
@@ -1263,12 +1367,14 @@ Output:
Input:
- {
- "action": "stop", # State change action (stop, start, restart, freeze or unfreeze)
- "timeout": 30, # A timeout after which the state change is considered as failed
- "force": true, # Force the state change (currently only valid for stop and restart where it means killing the container)
- "stateful": true # Whether to store or restore runtime state before stopping or startiong (only valid for stop and start, defaults to false)
- }
+```json
+{
+ "action": "stop", # State change action (stop, start, restart, freeze or unfreeze)
+ "timeout": 30, # A timeout after which the state change is considered as failed
+ "force": true, # Force the state change (currently only valid for stop and restart where it means killing the container)
+ "stateful": true # Whether to store or restore runtime state before stopping or startiong (only valid for stop and start, defaults to false)
+}
+```
### `/1.0/containers/<name>/logs`
#### GET
@@ -1281,11 +1387,13 @@ Input:
Return:
- [
- "/1.0/containers/blah/logs/forkstart.log",
- "/1.0/containers/blah/logs/lxc.conf",
- "/1.0/containers/blah/logs/lxc.log"
- ]
+```json
+[
+ "/1.0/containers/blah/logs/forkstart.log",
+ "/1.0/containers/blah/logs/lxc.conf",
+ "/1.0/containers/blah/logs/lxc.log"
+]
+```
### `/1.0/containers/<name>/logs/<logfile>`
#### GET
@@ -1310,27 +1418,29 @@ Return:
Return:
- {
+```json
+{
+ "architecture": "x86_64",
+ "creation_date": 1477146654,
+ "expiry_date": 0,
+ "properties": {
"architecture": "x86_64",
- "creation_date": 1477146654,
- "expiry_date": 0,
- "properties": {
- "architecture": "x86_64",
- "description": "Busybox x86_64",
- "name": "busybox-x86_64",
- "os": "Busybox"
- },
- "templates": {
- "/template": {
- "when": [
- ""
- ],
- "create_only": false,
- "template": "template.tpl",
- "properties": {}
- }
+ "description": "Busybox x86_64",
+ "name": "busybox-x86_64",
+ "os": "Busybox"
+ },
+ "templates": {
+ "/template": {
+ "when": [
+ ""
+ ],
+ "create_only": false,
+ "template": "template.tpl",
+ "properties": {}
}
}
+}
+```
#### PUT (ETag supported)
* Description: Replaces container metadata
@@ -1341,27 +1451,29 @@ Return:
Input:
- {
+```json
+{
+ "architecture": "x86_64",
+ "creation_date": 1477146654,
+ "expiry_date": 0,
+ "properties": {
"architecture": "x86_64",
- "creation_date": 1477146654,
- "expiry_date": 0,
- "properties": {
- "architecture": "x86_64",
- "description": "Busybox x86_64",
- "name": "busybox-x86_64",
- "os": "Busybox"
- },
- "templates": {
- "/template": {
- "when": [
- ""
- ],
- "create_only": false,
- "template": "template.tpl",
- "properties": {}
- }
+ "description": "Busybox x86_64",
+ "name": "busybox-x86_64",
+ "os": "Busybox"
+ },
+ "templates": {
+ "/template": {
+ "when": [
+ ""
+ ],
+ "create_only": false,
+ "template": "template.tpl",
+ "properties": {}
}
}
+}
+```
### `/1.0/containers/<name>/metadata/templates`
#### GET
@@ -1373,10 +1485,12 @@ Input:
Return:
- [
- "template.tpl",
- "hosts.tpl"
- ]
+```json
+[
+ "template.tpl",
+ "hosts.tpl"
+]
+```
#### GET (`?path=<template>`)
* Description: Content of a container template
@@ -1424,10 +1538,12 @@ Input:
Return value:
- [
- "/1.0/containers/c1/backups/c1/backup0",
- "/1.0/containers/c1/backups/c1/backup1",
- ]
+```json
+[
+ "/1.0/containers/c1/backups/c1/backup0",
+ "/1.0/containers/c1/backups/c1/backup1",
+]
+```
#### POST
* Description: Create a new backup
@@ -1438,12 +1554,14 @@ Return value:
Input:
- {
- "name": "backupName", # unique identifier for the backup
- "expiry": 3600, # when to delete the backup automatically
- "container_only": true, # if True, snapshots aren't included
- "optimized_storage": true # if True, btrfs send or zfs send is used for container and snapshots
- }
+```json
+{
+ "name": "backupName", # unique identifier for the backup
+ "expiry": 3600, # when to delete the backup automatically
+ "container_only": true, # if True, snapshots aren't included
+ "optimized_storage": true # if True, btrfs send or zfs send is used for container and snapshots
+}
+```
### `/1.0/containers/<name>/backups/<name>`
#### GET
@@ -1455,13 +1573,15 @@ Input:
Output:
- {
- "name": "backupName",
- "creation_date": "2018-04-23T12:16:09+02:00",
- "expiry_date": "2018-04-23T12:16:09+02:00",
- "container_only": false,
- "optimized_storage": false
- }
+```json
+{
+ "name": "backupName",
+ "creation_date": "2018-04-23T12:16:09+02:00",
+ "expiry_date": "2018-04-23T12:16:09+02:00",
+ "container_only": false,
+ "optimized_storage": false
+}
+```
#### DELETE
* Description: remove the backup
@@ -1479,9 +1599,11 @@ Output:
Input:
- {
- "name": "new-name"
- }
+```json
+{
+ "name": "new-name"
+}
+```
### `/1.0/containers/<name>/backups/<name>/export`
#### GET
@@ -1493,9 +1615,11 @@ Input:
Output:
- {
- "data": <byte-stream>
- }
+```json
+{
+ "data": <byte-stream>
+}
+```
### `/1.0/events`
This URL isn't a real REST API endpoint, instead doing a GET query on it
@@ -1520,25 +1644,29 @@ The notification types are:
This never returns. Each notification is sent as a separate JSON dict:
- {
- "timestamp": "2015-06-09T19:07:24.379615253-06:00", # Current timestamp
- "type": "operation", # Notification type
- "metadata": {} # Extra resource or type specific metadata
- }
-
- {
- "timestamp": "2016-02-17T11:44:28.572721913-05:00",
- "type": "logging",
- "metadata": {
- "context": {
- "ip": "@",
- "method": "GET"
- "url": "/1.0/containers/xen/snapshots",
- },
- "level": "info",
- "message": "handling"
- }
+```json
+{
+ "timestamp": "2015-06-09T19:07:24.379615253-06:00", # Current timestamp
+ "type": "operation", # Notification type
+ "metadata": {} # Extra resource or type specific metadata
+}
+```
+
+```json
+{
+ "timestamp": "2016-02-17T11:44:28.572721913-05:00",
+ "type": "logging",
+ "metadata": {
+ "context": {
+ "ip": "@",
+ "method": "GET"
+ "url": "/1.0/containers/xen/snapshots",
+ },
+ "level": "info",
+ "message": "handling"
}
+}
+```
### `/1.0/images`
#### GET
@@ -1549,12 +1677,14 @@ This never returns. Each notification is sent as a separate JSON dict:
Return:
- [
- "/1.0/images/54c8caac1f61901ed86c68f24af5f5d3672bdc62c71d04f06df3a59e95684473",
- "/1.0/images/97d97a3d1d053840ca19c86cdd0596cf1be060c5157d31407f2a4f9f350c78cc",
- "/1.0/images/a49d26ce5808075f5175bf31f5cb90561f5023dcd408da8ac5e834096d46b2d8",
- "/1.0/images/c9b6e738fae75286d52f497415463a8ecc61bbcb046536f220d797b0e500a41f"
- ]
+```json
+[
+ "/1.0/images/54c8caac1f61901ed86c68f24af5f5d3672bdc62c71d04f06df3a59e95684473",
+ "/1.0/images/97d97a3d1d053840ca19c86cdd0596cf1be060c5157d31407f2a4f9f350c78cc",
+ "/1.0/images/a49d26ce5808075f5175bf31f5cb90561f5023dcd408da8ac5e834096d46b2d8",
+ "/1.0/images/c9b6e738fae75286d52f497415463a8ecc61bbcb046536f220d797b0e500a41f"
+]
+```
#### POST
* Description: create and publish a new image
@@ -1578,65 +1708,71 @@ In the http file upload case, The following headers may be set by the client:
In the source image case, the following dict must be used:
- {
- "filename": filename, # Used for export (optional)
- "public": true, # Whether the image can be downloaded by untrusted users (defaults to false)
- "auto_update": true, # Whether the image should be auto-updated (optional; defaults to false)
- "properties": { # Image properties (optional, applied on top of source properties)
- "os": "Ubuntu"
- },
- "aliases": [ # Set initial aliases ("image_create_aliases" API extension)
- {"name": "my-alias",
- "description": "A description"}
- ],
- "source": {
- "type": "image",
- "mode": "pull", # Only pull is supported for now
- "server": "https://10.0.2.3:8443", # Remote server (pull mode only)
- "protocol": "lxd", # Protocol (one of lxd or simplestreams, defaults to lxd)
- "secret": "my-secret-string", # Secret (pull mode only, private images only)
- "certificate": "PEM certificate", # Optional PEM certificate. If not mentioned, system CA is used.
- "fingerprint": "SHA256", # Fingerprint of the image (must be set if alias isn't)
- "alias": "ubuntu/devel", # Name of the alias (must be set if fingerprint isn't)
- }
- }
+```json
+{
+ "filename": filename, # Used for export (optional)
+ "public": true, # Whether the image can be downloaded by untrusted users (defaults to false)
+ "auto_update": true, # Whether the image should be auto-updated (optional; defaults to false)
+ "properties": { # Image properties (optional, applied on top of source properties)
+ "os": "Ubuntu"
+ },
+ "aliases": [ # Set initial aliases ("image_create_aliases" API extension)
+ {"name": "my-alias",
+ "description": "A description"}
+ ],
+ "source": {
+ "type": "image",
+ "mode": "pull", # Only pull is supported for now
+ "server": "https://10.0.2.3:8443", # Remote server (pull mode only)
+ "protocol": "lxd", # Protocol (one of lxd or simplestreams, defaults to lxd)
+ "secret": "my-secret-string", # Secret (pull mode only, private images only)
+ "certificate": "PEM certificate", # Optional PEM certificate. If not mentioned, system CA is used.
+ "fingerprint": "SHA256", # Fingerprint of the image (must be set if alias isn't)
+ "alias": "ubuntu/devel", # Name of the alias (must be set if fingerprint isn't)
+ }
+}
+```
In the source container case, the following dict must be used:
- {
- "compression_algorithm": "xz", # Override the compression algorithm for the image (optional)
- "filename": filename, # Used for export (optional)
- "public": true, # Whether the image can be downloaded by untrusted users (defaults to false)
- "properties": { # Image properties (optional)
- "os": "Ubuntu"
- },
- "aliases": [ # Set initial aliases ("image_create_aliases" API extension)
- {"name": "my-alias",
- "description": "A description"}
- ],
- "source": {
- "type": "container", # One of "container" or "snapshot"
- "name": "abc"
- }
- }
+```json
+{
+ "compression_algorithm": "xz", # Override the compression algorithm for the image (optional)
+ "filename": filename, # Used for export (optional)
+ "public": true, # Whether the image can be downloaded by untrusted users (defaults to false)
+ "properties": { # Image properties (optional)
+ "os": "Ubuntu"
+ },
+ "aliases": [ # Set initial aliases ("image_create_aliases" API extension)
+ {"name": "my-alias",
+ "description": "A description"}
+ ],
+ "source": {
+ "type": "container", # One of "container" or "snapshot"
+ "name": "abc"
+ }
+}
+```
In the remote image URL case, the following dict must be used:
- {
- "filename": filename, # Used for export (optional)
- "public": true, # Whether the image can be downloaded by untrusted users (defaults to false)
- "properties": { # Image properties (optional)
- "os": "Ubuntu"
- },
- "aliases": [ # Set initial aliases ("image_create_aliases" API extension)
- {"name": "my-alias",
- "description": "A description"}
- ],
- "source": {
- "type": "url",
- "url": "https://www.some-server.com/image" # URL for the image
- }
- }
+```json
+{
+ "filename": filename, # Used for export (optional)
+ "public": true, # Whether the image can be downloaded by untrusted users (defaults to false)
+ "properties": { # Image properties (optional)
+ "os": "Ubuntu"
+ },
+ "aliases": [ # Set initial aliases ("image_create_aliases" API extension)
+ {"name": "my-alias",
+ "description": "A description"}
+ ],
+ "source": {
+ "type": "url",
+ "url": "https://www.some-server.com/image" # URL for the image
+ }
+}
+```
After the input is received by LXD, a background operation is started
which will add the image to the store and possibly do some backend
@@ -1651,37 +1787,39 @@ filesystem-specific optimizations.
Output:
- {
- "aliases": [
- {
- "name": "trusty",
- "description": "",
- }
- ],
+```json
+{
+ "aliases": [
+ {
+ "name": "trusty",
+ "description": "",
+ }
+ ],
+ "architecture": "x86_64",
+ "auto_update": true,
+ "cached": false,
+ "fingerprint": "54c8caac1f61901ed86c68f24af5f5d3672bdc62c71d04f06df3a59e95684473",
+ "filename": "ubuntu-trusty-14.04-amd64-server-20160201.tar.xz",
+ "properties": {
"architecture": "x86_64",
- "auto_update": true,
- "cached": false,
- "fingerprint": "54c8caac1f61901ed86c68f24af5f5d3672bdc62c71d04f06df3a59e95684473",
- "filename": "ubuntu-trusty-14.04-amd64-server-20160201.tar.xz",
- "properties": {
- "architecture": "x86_64",
- "description": "Ubuntu 14.04 LTS server (20160201)",
- "os": "ubuntu",
- "release": "trusty"
- },
- "update_source": {
- "server": "https://10.1.2.4:8443",
- "protocol": "lxd",
- "certificate": "PEM certificate",
- "alias": "ubuntu/trusty/amd64"
- },
- "public": false,
- "size": 123792592,
- "created_at": "2016-02-01T21:07:41Z",
- "expires_at": "1970-01-01T00:00:00Z",
- "last_used_at": "1970-01-01T00:00:00Z",
- "uploaded_at": "2016-02-16T00:44:47Z"
- }
+ "description": "Ubuntu 14.04 LTS server (20160201)",
+ "os": "ubuntu",
+ "release": "trusty"
+ },
+ "update_source": {
+ "server": "https://10.1.2.4:8443",
+ "protocol": "lxd",
+ "certificate": "PEM certificate",
+ "alias": "ubuntu/trusty/amd64"
+ },
+ "public": false,
+ "size": 123792592,
+ "created_at": "2016-02-01T21:07:41Z",
+ "expires_at": "1970-01-01T00:00:00Z",
+ "last_used_at": "1970-01-01T00:00:00Z",
+ "uploaded_at": "2016-02-16T00:44:47Z"
+}
+```
#### PUT (ETag supported)
* Description: Replaces the image properties, update information and visibility
@@ -1691,16 +1829,18 @@ Output:
Input:
- {
- "auto_update": true,
- "properties": {
- "architecture": "x86_64",
- "description": "Ubuntu 14.04 LTS server (20160201)",
- "os": "ubuntu",
- "release": "trusty"
- },
- "public": true,
- }
+```json
+{
+ "auto_update": true,
+ "properties": {
+ "architecture": "x86_64",
+ "description": "Ubuntu 14.04 LTS server (20160201)",
+ "os": "ubuntu",
+ "release": "trusty"
+ },
+ "public": true,
+}
+```
#### PATCH (ETag supported)
* Description: Updates the image properties, update information and visibility
@@ -1711,13 +1851,15 @@ Input:
Input:
- {
- "properties": {
- "os": "ubuntu",
- "release": "trusty"
- },
- "public": true,
- }
+```json
+{
+ "properties": {
+ "os": "ubuntu",
+ "release": "trusty"
+ },
+ "public": true,
+}
+```
#### DELETE
* Description: Remove an image
@@ -1727,8 +1869,10 @@ Input:
Input (none at present):
- {
- }
+```json
+{
+}
+```
HTTP code for this should be 202 (Accepted).
@@ -1765,14 +1909,18 @@ This creates an operation to refresh the specified image from its origin.
Input:
- {
- }
+```json
+{
+}
+```
Return:
- {
- "secret": "52e9ec5885562aa24d05d7b4846ebb8b5f1f7bf5cd6e285639b569d9eaf54c9b"
- }
+```json
+{
+ "secret": "52e9ec5885562aa24d05d7b4846ebb8b5f1f7bf5cd6e285639b569d9eaf54c9b"
+}
+```
Standard backround operation with "secret" set to the generated secret
string in metadata.
@@ -1790,11 +1938,13 @@ then hit /export with the same secret.
Return:
- [
- "/1.0/images/aliases/sl6",
- "/1.0/images/aliases/trusty",
- "/1.0/images/aliases/xenial"
- ]
+```json
+[
+ "/1.0/images/aliases/sl6",
+ "/1.0/images/aliases/trusty",
+ "/1.0/images/aliases/xenial"
+]
+```
#### POST
* Description: create a new alias
@@ -1804,11 +1954,13 @@ Return:
Input:
- {
- "description": "The alias description",
- "target": "SHA-256",
- "name": "alias-name"
- }
+```json
+{
+ "description": "The alias description",
+ "target": "SHA-256",
+ "name": "alias-name"
+}
+```
### `/1.0/images/aliases/<name>`
#### GET
@@ -1819,11 +1971,13 @@ Input:
Output:
- {
- "name": "test",
- "description": "my description",
- "target": "c9b6e738fae75286d52f497415463a8ecc61bbcb046536f220d797b0e500a41f"
- }
+```json
+{
+ "name": "test",
+ "description": "my description",
+ "target": "c9b6e738fae75286d52f497415463a8ecc61bbcb046536f220d797b0e500a41f"
+}
+```
#### PUT (ETag supported)
* Description: Replaces the alias target or description
@@ -1833,10 +1987,12 @@ Output:
Input:
- {
- "description": "New description",
- "target": "54c8caac1f61901ed86c68f24af5f5d3672bdc62c71d04f06df3a59e95684473"
- }
+```json
+{
+ "description": "New description",
+ "target": "54c8caac1f61901ed86c68f24af5f5d3672bdc62c71d04f06df3a59e95684473"
+}
+```
#### PATCH (ETag supported)
* Description: Updates the alias target or description
@@ -1847,9 +2003,11 @@ Input:
Input:
- {
- "description": "New description"
- }
+```json
+{
+ "description": "New description"
+}
+```
#### POST
* Description: rename an alias
@@ -1859,9 +2017,11 @@ Input:
Input:
- {
- "name": "new-name"
- }
+```json
+{
+ "name": "new-name"
+}
+```
Renaming to an existing name must return the 409 (Conflict) HTTP code.
@@ -1873,8 +2033,10 @@ Renaming to an existing name must return the 409 (Conflict) HTTP code.
Input (none at present):
- {
- }
+```json
+{
+}
+```
### `/1.0/networks`
#### GET
@@ -1885,10 +2047,12 @@ Input (none at present):
Return:
- [
- "/1.0/networks/eth0",
- "/1.0/networks/lxdbr0"
- ]
+```json
+[
+ "/1.0/networks/eth0",
+ "/1.0/networks/lxdbr0"
+]
+```
#### POST
* Description: define a new network
@@ -1899,15 +2063,17 @@ Return:
Input:
- {
- "name": "my-network",
- "description": "My network",
- "config": {
- "ipv4.address": "none",
- "ipv6.address": "2001:470:b368:4242::1/64",
- "ipv6.nat": "true"
- }
+```json
+{
+ "name": "my-network",
+ "description": "My network",
+ "config": {
+ "ipv4.address": "none",
+ "ipv6.address": "2001:470:b368:4242::1/64",
+ "ipv6.nat": "true"
}
+}
+```
### `/1.0/networks/<name>`
#### GET
@@ -1918,15 +2084,17 @@ Input:
Return:
- {
- "config": {},
- "name": "lxdbr0",
- "managed": false,
- "type": "bridge",
- "used_by": [
- "/1.0/containers/blah"
- ]
- }
+```json
+{
+ "config": {},
+ "name": "lxdbr0",
+ "managed": false,
+ "type": "bridge",
+ "used_by": [
+ "/1.0/containers/blah"
+ ]
+}
+```
#### PUT (ETag supported)
* Description: replace the network information
@@ -1937,13 +2105,15 @@ Return:
Input:
- {
- "config": {
- "bridge.driver": "openvswitch",
- "ipv4.address": "10.0.3.1/24",
- "ipv6.address": "fd1:6997:4939:495d::1/64"
- }
+```json
+{
+ "config": {
+ "bridge.driver": "openvswitch",
+ "ipv4.address": "10.0.3.1/24",
+ "ipv6.address": "fd1:6997:4939:495d::1/64"
}
+}
+```
Same dict as used for initial creation and coming from GET. Only the
config is used, everything else is ignored.
@@ -1957,11 +2127,13 @@ config is used, everything else is ignored.
Input:
- {
- "config": {
- "dns.mode": "dynamic"
- }
+```json
+{
+ "config": {
+ "dns.mode": "dynamic"
}
+}
+```
#### POST
* Description: rename a network
@@ -1972,9 +2144,11 @@ Input:
Input (rename a network):
- {
- "name": "new-name"
- }
+```json
+{
+ "name": "new-name"
+}
+```
HTTP return value must be 204 (No content) and Location must point to
the renamed resource.
@@ -1990,8 +2164,10 @@ Renaming to an existing name must return the 409 (Conflict) HTTP code.
Input (none at present):
- {
- }
+```json
+{
+}
+```
HTTP code for this should be 202 (Accepted).
@@ -2004,38 +2180,40 @@ HTTP code for this should be 202 (Accepted).
Return:
- {
- "addresses": [
- {
- "family": "inet",
- "address": "10.87.252.1",
- "netmask": "24",
- "scope": "global"
- },
- {
- "family": "inet6",
- "address": "fd42:6e0e:6542:a212::1",
- "netmask": "64",
- "scope": "global"
- },
- {
- "family": "inet6",
- "address": "fe80::3419:9ff:fe9b:f9aa",
- "netmask": "64",
- "scope": "link"
- }
- ],
- "counters": {
- "bytes_received": 0,
- "bytes_sent": 17724,
- "packets_received": 0,
- "packets_sent": 95
+```json
+{
+ "addresses": [
+ {
+ "family": "inet",
+ "address": "10.87.252.1",
+ "netmask": "24",
+ "scope": "global"
},
- "hwaddr": "36:19:09:9b:f9:aa",
- "mtu": 1500,
- "state": "up",
- "type": "broadcast"
- }
+ {
+ "family": "inet6",
+ "address": "fd42:6e0e:6542:a212::1",
+ "netmask": "64",
+ "scope": "global"
+ },
+ {
+ "family": "inet6",
+ "address": "fe80::3419:9ff:fe9b:f9aa",
+ "netmask": "64",
+ "scope": "link"
+ }
+ ],
+ "counters": {
+ "bytes_received": 0,
+ "bytes_sent": 17724,
+ "packets_received": 0,
+ "packets_sent": 95
+ },
+ "hwaddr": "36:19:09:9b:f9:aa",
+ "mtu": 1500,
+ "state": "up",
+ "type": "broadcast"
+}
+```
### `/1.0/operations`
#### GET
@@ -2045,14 +2223,16 @@ Return:
* Return: dict representing a list of URLs for operations that are currently going on/queued according to their status
Return:
- {
- "success": [
- "/1.0/operations/c0fc0d0d-a997-462b-842b-f8bd0df82507"
- ],
- "running": [
- "/1.0/operations/092a8755-fd90-4ce4-bf91-9f87d03fd5bc"
- ]
- }
+```json
+{
+ "success": [
+ "/1.0/operations/c0fc0d0d-a997-462b-842b-f8bd0df82507"
+ ],
+ "running": [
+ "/1.0/operations/092a8755-fd90-4ce4-bf91-9f87d03fd5bc"
+ ]
+}
+```
### `/1.0/operations/<uuid>`
#### GET
@@ -2063,24 +2243,26 @@ Return:
Return:
- {
- "id": "b8d84888-1dc2-44fd-b386-7f679e171ba5",
- "class": "token", # One of "task" (background task), "websocket" (set of websockets and crendentials) or "token" (temporary credentials)
- "created_at": "2016-02-17T16:59:27.237628195-05:00", # Creation timestamp
- "updated_at": "2016-02-17T16:59:27.237628195-05:00", # Last update timestamp
- "status": "Running",
- "status_code": 103,
- "resources": { # List of affected resources
- "images": [
- "/1.0/images/54c8caac1f61901ed86c68f24af5f5d3672bdc62c71d04f06df3a59e95684473"
- ]
- },
- "metadata": { # Extra information about the operation (action, target, ...)
- "secret": "c9209bee6df99315be1660dd215acde4aec89b8e5336039712fc11008d918b0d"
- },
- "may_cancel": true, # Whether it's possible to cancel the operation (DELETE)
- "err": ""
- }
+```json
+{
+ "id": "b8d84888-1dc2-44fd-b386-7f679e171ba5",
+ "class": "token", # One of "task" (background task), "websocket" (set of websockets and crendentials) or "token" (temporary credentials)
+ "created_at": "2016-02-17T16:59:27.237628195-05:00", # Creation timestamp
+ "updated_at": "2016-02-17T16:59:27.237628195-05:00", # Last update timestamp
+ "status": "Running",
+ "status_code": 103,
+ "resources": { # List of affected resources
+ "images": [
+ "/1.0/images/54c8caac1f61901ed86c68f24af5f5d3672bdc62c71d04f06df3a59e95684473"
+ ]
+ },
+ "metadata": { # Extra information about the operation (action, target, ...)
+ "secret": "c9209bee6df99315be1660dd215acde4aec89b8e5336039712fc11008d918b0d"
+ },
+ "may_cancel": true, # Whether it's possible to cancel the operation (DELETE)
+ "err": ""
+}
+```
#### DELETE
* Description: cancel an operation. Calling this will change the state to "cancelling" rather than actually removing the entry.
@@ -2090,8 +2272,10 @@ Return:
Input (none at present):
- {
- }
+```json
+{
+}
+```
HTTP code for this should be 202 (Accepted).
@@ -2129,9 +2313,11 @@ Input (similar but times out after 30s): ?timeout=30
Return:
- [
- "/1.0/profiles/default"
- ]
+```json
+[
+ "/1.0/profiles/default"
+]
+```
#### POST
* Description: define a new profile
@@ -2141,19 +2327,21 @@ Return:
Input:
- {
- "name": "my-profilename",
- "description": "Some description string",
- "config": {
- "limits.memory": "2GB"
- },
- "devices": {
- "kvm": {
- "type": "unix-char",
- "path": "/dev/kvm"
- }
+```json
+{
+ "name": "my-profilename",
+ "description": "Some description string",
+ "config": {
+ "limits.memory": "2GB"
+ },
+ "devices": {
+ "kvm": {
+ "type": "unix-char",
+ "path": "/dev/kvm"
}
}
+}
+```
### `/1.0/profiles/<name>`
#### GET
@@ -2164,22 +2352,24 @@ Input:
Output:
- {
- "name": "test",
- "description": "Some description string",
- "config": {
- "limits.memory": "2GB"
- },
- "devices": {
- "kvm": {
- "path": "/dev/kvm",
- "type": "unix-char"
- }
- },
- "used_by": [
- "/1.0/containers/blah"
- ]
- }
+```json
+{
+ "name": "test",
+ "description": "Some description string",
+ "config": {
+ "limits.memory": "2GB"
+ },
+ "devices": {
+ "kvm": {
+ "path": "/dev/kvm",
+ "type": "unix-char"
+ }
+ },
+ "used_by": [
+ "/1.0/containers/blah"
+ ]
+}
+```
#### PUT (ETag supported)
* Description: replace the profile information
@@ -2189,18 +2379,20 @@ Output:
Input:
- {
- "config": {
- "limits.memory": "4GB"
- },
- "description": "Some description string",
- "devices": {
- "kvm": {
- "path": "/dev/kvm",
- "type": "unix-char"
- }
+```json
+{
+ "config": {
+ "limits.memory": "4GB"
+ },
+ "description": "Some description string",
+ "devices": {
+ "kvm": {
+ "path": "/dev/kvm",
+ "type": "unix-char"
}
}
+}
+```
Same dict as used for initial creation and coming from GET. The name
property can't be changed (see POST for that).
@@ -2214,18 +2406,20 @@ property can't be changed (see POST for that).
Input:
- {
- "config": {
- "limits.memory": "4GB"
- },
- "description": "Some description string",
- "devices": {
- "kvm": {
- "path": "/dev/kvm",
- "type": "unix-char"
- }
+```json
+{
+ "config": {
+ "limits.memory": "4GB"
+ },
+ "description": "Some description string",
+ "devices": {
+ "kvm": {
+ "path": "/dev/kvm",
+ "type": "unix-char"
}
}
+}
+```
#### POST
* Description: rename a profile
@@ -2235,9 +2429,11 @@ Input:
Input (rename a profile):
- {
- "name": "new-name"
- }
+```json
+{
+ "name": "new-name"
+}
+```
HTTP return value must be 204 (No content) and Location must point to
the renamed resource.
@@ -2254,8 +2450,10 @@ Attempting to rename the `default` profile will return the 403 (Forbidden) HTTP
Input (none at present):
- {
- }
+```json
+{
+}
+```
HTTP code for this should be 202 (Accepted).
@@ -2271,9 +2469,11 @@ Attempting to delete the `default` profile will return the 403 (Forbidden) HTTP
Return:
- [
- "/1.0/projects/default"
- ]
+```json
+[
+ "/1.0/projects/default"
+]
+```
#### POST
* Description: define a new project
@@ -2284,14 +2484,16 @@ Return:
Input:
- {
- "name": "test",
- "config": {
- "features.images": "true",
- "features.profiles": "true",
- },
- "description": "Some description string"
- }
+```json
+{
+ "name": "test",
+ "config": {
+ "features.images": "true",
+ "features.profiles": "true",
+ },
+ "description": "Some description string"
+}
+```
### `/1.0/projects/<name>`
#### GET
@@ -2303,17 +2505,19 @@ Input:
Output:
- {
- "name": "test",
- "config": {
- "features.images": "true",
- "features.profiles": "true",
- },
- "description": "Some description string",
- "used_by": [
- "/1.0/containers/blah"
- ]
- }
+```json
+{
+ "name": "test",
+ "config": {
+ "features.images": "true",
+ "features.profiles": "true",
+ },
+ "description": "Some description string",
+ "used_by": [
+ "/1.0/containers/blah"
+ ]
+}
+```
#### PUT (ETag supported)
* Description: replace the project information
@@ -2324,13 +2528,15 @@ Output:
Input:
- {
- "config": {
- "features.images": "true",
- "features.profiles": "true",
- },
- "description": "Some description string"
- }
+```json
+{
+ "config": {
+ "features.images": "true",
+ "features.profiles": "true",
+ },
+ "description": "Some description string"
+}
+```
Same dict as used for initial creation and coming from GET. The name
property can't be changed (see POST for that).
@@ -2344,12 +2550,14 @@ property can't be changed (see POST for that).
Input:
- {
- "config": {
- "features.images": "true",
- },
- "description": "Some description string"
- }
+```json
+{
+ "config": {
+ "features.images": "true",
+ },
+ "description": "Some description string"
+}
+```
#### POST
* Description: rename a project
@@ -2360,9 +2568,11 @@ Input:
Input (rename a project):
- {
- "name": "new-name"
- }
+```json
+{
+ "name": "new-name"
+}
+```
HTTP return value must be 204 (No content) and Location must point to
the renamed resource.
@@ -2380,8 +2590,10 @@ Attempting to rename the `default` project will return the 403 (Forbidden) HTTP
Input (none at present):
- {
- }
+```json
+{
+}
+```
HTTP code for this should be 202 (Accepted).
@@ -2397,13 +2609,15 @@ Attempting to delete the `default` project will return the 403 (Forbidden) HTTP
Return:
- [
- "/1.0/storage-pools/default",
- "/1.0/storage-pools/pool1"
- "/1.0/storage-pools/pool2"
- "/1.0/storage-pools/pool3"
- "/1.0/storage-pools/pool4"
- ]
+```json
+[
+ "/1.0/storage-pools/default",
+ "/1.0/storage-pools/pool1",
+ "/1.0/storage-pools/pool2",
+ "/1.0/storage-pools/pool3",
+ "/1.0/storage-pools/pool4"
+]
+```
#### POST
* Description: create a new storage pool
@@ -2414,13 +2628,15 @@ Return:
Input:
- {
- "config": {
- "size": "10GB"
- },
- "driver": "zfs",
- "name": "pool1"
- }
+```json
+{
+ "config": {
+ "size": "10GB"
+ },
+ "driver": "zfs",
+ "name": "pool1"
+}
+```
### `/1.0/storage-pools/<name>`
#### GET
@@ -2432,47 +2648,49 @@ Input:
Return:
- {
- "type": "sync",
- "status": "Success",
- "status_code": 200,
- "operation": "",
- "error_code": 0,
- "error": "",
- "metadata": {
- "name": "default",
- "driver": "zfs",
- "used_by": [
- "/1.0/containers/alp1",
- "/1.0/containers/alp10",
- "/1.0/containers/alp11",
- "/1.0/containers/alp12",
- "/1.0/containers/alp13",
- "/1.0/containers/alp14",
- "/1.0/containers/alp15",
- "/1.0/containers/alp16",
- "/1.0/containers/alp17",
- "/1.0/containers/alp18",
- "/1.0/containers/alp19",
- "/1.0/containers/alp2",
- "/1.0/containers/alp20",
- "/1.0/containers/alp3",
- "/1.0/containers/alp4",
- "/1.0/containers/alp5",
- "/1.0/containers/alp6",
- "/1.0/containers/alp7",
- "/1.0/containers/alp8",
- "/1.0/containers/alp9",
- "/1.0/images/62e850a334bb9d99cac00b2e618e0291e5e7bb7db56c4246ecaf8e46fa0631a6"
- ],
- "config": {
- "size": "61203283968",
- "source": "/home/chb/mnt/l2/disks/default.img",
- "volume.size": "0",
- "zfs.pool_name": "default"
- }
+```json
+{
+ "type": "sync",
+ "status": "Success",
+ "status_code": 200,
+ "operation": "",
+ "error_code": 0,
+ "error": "",
+ "metadata": {
+ "name": "default",
+ "driver": "zfs",
+ "used_by": [
+ "/1.0/containers/alp1",
+ "/1.0/containers/alp10",
+ "/1.0/containers/alp11",
+ "/1.0/containers/alp12",
+ "/1.0/containers/alp13",
+ "/1.0/containers/alp14",
+ "/1.0/containers/alp15",
+ "/1.0/containers/alp16",
+ "/1.0/containers/alp17",
+ "/1.0/containers/alp18",
+ "/1.0/containers/alp19",
+ "/1.0/containers/alp2",
+ "/1.0/containers/alp20",
+ "/1.0/containers/alp3",
+ "/1.0/containers/alp4",
+ "/1.0/containers/alp5",
+ "/1.0/containers/alp6",
+ "/1.0/containers/alp7",
+ "/1.0/containers/alp8",
+ "/1.0/containers/alp9",
+ "/1.0/images/62e850a334bb9d99cac00b2e618e0291e5e7bb7db56c4246ecaf8e46fa0631a6"
+ ],
+ "config": {
+ "size": "61203283968",
+ "source": "/home/chb/mnt/l2/disks/default.img",
+ "volume.size": "0",
+ "zfs.pool_name": "default"
}
}
+}
+```
#### PUT (ETag supported)
* Description: replace the storage pool information
@@ -2483,17 +2701,19 @@ Return:
Input:
- {
- "config": {
- "size": "15032385536",
- "source": "pool1",
- "volume.block.filesystem": "xfs",
- "volume.block.mount_options": "discard",
- "lvm.thinpool_name": "LXDThinPool",
- "lvm.vg_name": "pool1",
- "volume.size": "10737418240"
- }
+```json
+{
+ "config": {
+ "size": "15032385536",
+ "source": "pool1",
+ "volume.block.filesystem": "xfs",
+ "volume.block.mount_options": "discard",
+ "lvm.thinpool_name": "LXDThinPool",
+ "lvm.vg_name": "pool1",
+ "volume.size": "10737418240"
}
+}
+```
#### PATCH
* Description: update the storage pool configuration
@@ -2504,11 +2724,13 @@ Return:
Input:
- {
- "config": {
- "volume.block.filesystem": "xfs",
- }
+```json
+{
+ "config": {
+ "volume.block.filesystem": "xfs",
}
+}
+```
#### DELETE
* Description: delete a storage pool
@@ -2519,8 +2741,10 @@ Input:
Input (none at present):
- {
- }
+```json
+{
+}
+```
### `/1.0/storage-pools/<name>/resources`
#### GET
@@ -2532,24 +2756,26 @@ Input (none at present):
Return:
- {
- "type": "sync",
- "status": "Success",
- "status_code": 200,
- "operation": "",
- "error_code": 0,
- "error": "",
- "metadata": {
- "space": {
- "used": 207111192576,
- "total": 306027577344
- },
- "inodes": {
- "used": 3275333,
- "total": 18989056
- }
+```json
+{
+ "type": "sync",
+ "status": "Success",
+ "status_code": 200,
+ "operation": "",
+ "error_code": 0,
+ "error": "",
+ "metadata": {
+ "space": {
+ "used": 207111192576,
+ "total": 306027577344
+ },
+ "inodes": {
+ "used": 3275333,
+ "total": 18989056
}
}
+}
+```
### `/1.0/storage-pools/<name>/volumes`
@@ -2562,29 +2788,31 @@ Return:
Return:
- [
- "/1.0/storage-pools/default/volumes/container/alp1",
- "/1.0/storage-pools/default/volumes/container/alp10",
- "/1.0/storage-pools/default/volumes/container/alp11",
- "/1.0/storage-pools/default/volumes/container/alp12",
- "/1.0/storage-pools/default/volumes/container/alp13",
- "/1.0/storage-pools/default/volumes/container/alp14",
- "/1.0/storage-pools/default/volumes/container/alp15",
- "/1.0/storage-pools/default/volumes/container/alp16",
- "/1.0/storage-pools/default/volumes/container/alp17",
- "/1.0/storage-pools/default/volumes/container/alp18",
- "/1.0/storage-pools/default/volumes/container/alp19",
- "/1.0/storage-pools/default/volumes/container/alp2",
- "/1.0/storage-pools/default/volumes/container/alp20",
- "/1.0/storage-pools/default/volumes/container/alp3",
- "/1.0/storage-pools/default/volumes/container/alp4",
- "/1.0/storage-pools/default/volumes/container/alp5",
- "/1.0/storage-pools/default/volumes/container/alp6",
- "/1.0/storage-pools/default/volumes/container/alp7",
- "/1.0/storage-pools/default/volumes/container/alp8",
- "/1.0/storage-pools/default/volumes/container/alp9",
- "/1.0/storage-pools/default/volumes/image/62e850a334bb9d99cac00b2e618e0291e5e7bb7db56c4246ecaf8e46fa0631a6"
- ]
+```json
+[
+ "/1.0/storage-pools/default/volumes/container/alp1",
+ "/1.0/storage-pools/default/volumes/container/alp10",
+ "/1.0/storage-pools/default/volumes/container/alp11",
+ "/1.0/storage-pools/default/volumes/container/alp12",
+ "/1.0/storage-pools/default/volumes/container/alp13",
+ "/1.0/storage-pools/default/volumes/container/alp14",
+ "/1.0/storage-pools/default/volumes/container/alp15",
+ "/1.0/storage-pools/default/volumes/container/alp16",
+ "/1.0/storage-pools/default/volumes/container/alp17",
+ "/1.0/storage-pools/default/volumes/container/alp18",
+ "/1.0/storage-pools/default/volumes/container/alp19",
+ "/1.0/storage-pools/default/volumes/container/alp2",
+ "/1.0/storage-pools/default/volumes/container/alp20",
+ "/1.0/storage-pools/default/volumes/container/alp3",
+ "/1.0/storage-pools/default/volumes/container/alp4",
+ "/1.0/storage-pools/default/volumes/container/alp5",
+ "/1.0/storage-pools/default/volumes/container/alp6",
+ "/1.0/storage-pools/default/volumes/container/alp7",
+ "/1.0/storage-pools/default/volumes/container/alp8",
+ "/1.0/storage-pools/default/volumes/container/alp9",
+ "/1.0/storage-pools/default/volumes/image/62e850a334bb9d99cac00b2e618e0291e5e7bb7db56c4246ecaf8e46fa0631a6"
+]
+```
#### POST
* Description: create a new storage volume on a given storage pool
@@ -2595,38 +2823,44 @@ Return:
Input:
- {
- "config": {},
- "name": "vol1",
- "type": "custom"
- }
+```json
+{
+ "config": {},
+ "name": "vol1",
+ "type": "custom"
+}
+```
Input (when copying a volume):
- {
- "config": {},
- "name": "vol1",
- "type": "custom"
- "source": {
- "pool": "pool2",
- "name": "vol2",
- "type": "copy"
- }
+```json
+{
+ "config": {},
+ "name": "vol1",
+ "type": "custom"
+ "source": {
+ "pool": "pool2",
+ "name": "vol2",
+ "type": "copy"
}
+}
+```
Input (when migrating a volume):
- {
- "config": {},
- "name": "vol1",
- "type": "custom"
- "source": {
- "pool": "pool2",
- "name": "vol2",
- "type": "migration"
- "mode": "pull", # One of "pull" (default), "push", "relay"
- }
+```json
+{
+ "config": {},
+ "name": "vol1",
+ "type": "custom"
+ "source": {
+ "pool": "pool2",
+ "name": "vol2",
+ "type": "migration",
+ "mode": "pull" # One of "pull" (default), "push", "relay"
}
+}
+```
### `/1.0/storage-pools/<pool>/volumes/<type>`
#### POST
@@ -2638,35 +2872,41 @@ Input (when migrating a volume):
Input:
- {
- "config": {},
- "name": "vol1",
- }
+```json
+{
+ "config": {},
+ "name": "vol1",
+}
+```
Input (when copying a volume):
- {
- "config": {},
- "name": "vol1",
- "source": {
- "pool": "pool2",
- "name": "vol2",
- "type": "copy"
- }
+```json
+{
+ "config": {},
+ "name": "vol1",
+ "source": {
+ "pool": "pool2",
+ "name": "vol2",
+ "type": "copy"
}
+}
+```
Input (when migrating a volume):
- {
- "config": {},
- "name": "vol1",
- "source": {
- "pool": "pool2",
- "name": "vol2",
- "type": "migration"
- "mode": "pull", # One of "pull" (default), "push", "relay"
- }
+```json
+{
+ "config": {},
+ "name": "vol1",
+ "source": {
+ "pool": "pool2",
+ "name": "vol2",
+ "type": "migration"
+ "mode": "pull", # One of "pull" (default), "push", "relay"
}
+}
+```
### `/1.0/storage-pools/<pool>/volumes/<type>/<name>`
#### POST
@@ -2678,28 +2918,34 @@ Input (when migrating a volume):
Input:
- {
- "name": "vol1",
- "pool": "pool3"
- }
+```json
+{
+ "name": "vol1",
+ "pool": "pool3"
+}
+```
Input (migration across lxd instances):
- {
- "name": "vol1"
- "pool": "pool3"
- "migration": true
- }
+```json
+{
+ "name": "vol1"
+ "pool": "pool3"
+ "migration": true
+}
+```
The migration does not actually start until someone (i.e. another lxd instance)
connects to all the websockets and begins negotiation with the source.
Output in metadata section (for migration):
- {
- "control": "secret1", # Migration control socket
- "fs": "secret2" # Filesystem transfer socket
- }
+```json
+{
+ "control": "secret1", # Migration control socket
+ "fs": "secret2" # Filesystem transfer socket
+}
+```
These are the secrets that should be passed to the create call.
@@ -2712,23 +2958,25 @@ These are the secrets that should be passed to the create call.
Return:
- {
- "type": "sync",
- "status": "Success",
- "status_code": 200,
- "error_code": 0,
- "error": "",
- "metadata": {
- "type": "custom",
- "used_by": [],
- "name": "vol1",
- "config": {
- "block.filesystem": "ext4",
- "block.mount_options": "discard",
- "size": "10737418240"
- }
+```json
+{
+ "type": "sync",
+ "status": "Success",
+ "status_code": 200,
+ "error_code": 0,
+ "error": "",
+ "metadata": {
+ "type": "custom",
+ "used_by": [],
+ "name": "vol1",
+ "config": {
+ "block.filesystem": "ext4",
+ "block.mount_options": "discard",
+ "size": "10737418240"
}
}
+}
+```
#### PUT (ETag supported)
@@ -2740,22 +2988,26 @@ Return:
Input:
- {
- "config": {
- "size": "15032385536",
- "source": "pool1",
- "used_by": "",
- "volume.block.filesystem": "xfs",
- "volume.block.mount_options": "discard",
- "lvm.thinpool_name": "LXDThinPool",
- "lvm.vg_name": "pool1",
- "volume.size": "10737418240"
- }
- }
-
- {
- "restore": "snapshot-name"
- }
+```json
+{
+ "config": {
+ "size": "15032385536",
+ "source": "pool1",
+ "used_by": "",
+ "volume.block.filesystem": "xfs",
+ "volume.block.mount_options": "discard",
+ "lvm.thinpool_name": "LXDThinPool",
+ "lvm.vg_name": "pool1",
+ "volume.size": "10737418240"
+ }
+}
+```
+
+```json
+{
+ "restore": "snapshot-name"
+}
+```
#### PATCH (ETag supported)
* Description: update the storage volume information
@@ -2766,11 +3018,13 @@ Return:
Input:
- {
- "config": {
- "volume.block.mount_options": "",
- }
+```json
+{
+ "config": {
+ "volume.block.mount_options": "",
}
+}
+```
#### DELETE
* Description: delete a storage volume of a given type on a given storage pool
@@ -2781,9 +3035,10 @@ Return:
Input (none at present):
- {
- }
-
+```json
+{
+}
+```
### `/1.0/storage-pools/<pool>/volumes/<type>/<name>/snapshots`
#### GET
@@ -2794,9 +3049,11 @@ Input (none at present):
Return value:
- [
- "/1.0/storage-pools/default/volumes/custom/foo/snapshots/snap0"
- ]
+```json
+[
+ "/1.0/storage-pools/default/volumes/custom/foo/snapshots/snap0"
+]
+```
#### POST
* Description: create a new volume snapshot
@@ -2806,9 +3063,11 @@ Return value:
Input:
- {
- "name": "my-snapshot", # Name of the snapshot
- }
+```json
+{
+ "name": "my-snapshot", # Name of the snapshot
+}
+```
### `/1.0/storage-pools/<pool>/volumes/<type>/<volume>/snapshots/name`
#### GET
@@ -2819,11 +3078,13 @@ Input:
Return:
- {
- "config": {},
- "description": "",
- "name": "snap0"
- }
+```json
+{
+ "config": {},
+ "description": "",
+ "name": "snap0"
+}
+```
#### PUT
* Description: Volume snapshot information
@@ -2833,9 +3094,11 @@ Return:
Input:
- {
- "description": "new-description"
- }
+```json
+{
+ "description": "new-description"
+}
+```
#### POST
* Description: used to rename the volume snapshot
@@ -2845,9 +3108,11 @@ Input:
Input:
- {
- "name": "new-name"
- }
+```json
+{
+ "name": "new-name"
+}
+```
#### DELETE
* Description: remove the volume snapshot
@@ -2867,33 +3132,35 @@ HTTP code for this should be 202 (Accepted).
Return:
- {
- "type": "sync",
- "status": "Success",
- "status_code": 200,
- "operation": "",
- "error_code": 0,
- "error": "",
- "metadata": {
- "cpu": {
- "sockets": [
- {
- "cores": 2,
- "frequency": 2691,
- "frequency_turbo": 3400,
- "name": "GenuineIntel",
- "vendor": "Intel(R) Core(TM) i5-3340M CPU @ 2.70GHz",
- "threads": 4
- }
- ],
- "total": 4
- },
- "memory": {
- "used": 4454240256,
- "total": 8271765504
- }
+```json
+{
+ "type": "sync",
+ "status": "Success",
+ "status_code": 200,
+ "operation": "",
+ "error_code": 0,
+ "error": "",
+ "metadata": {
+ "cpu": {
+ "sockets": [
+ {
+ "cores": 2,
+ "frequency": 2691,
+ "frequency_turbo": 3400,
+ "name": "GenuineIntel",
+ "vendor": "Intel(R) Core(TM) i5-3340M CPU @ 2.70GHz",
+ "threads": 4
+ }
+ ],
+ "total": 4
+ },
+ "memory": {
+ "used": 4454240256,
+ "total": 8271765504
}
}
+}
+```
### `/1.0/cluster`
#### GET
@@ -2905,24 +3172,26 @@ Return:
Return:
- {
- "server_name": "node1",
- "enabled": true,
- "member_config": [
- {
- "entity": "storage-pool",
- "name": "local",
- "key": "source",
- "description": "\"source\" property for storage pool \"local\"",
- },
- {
- "entity": "network",
- "name": "lxdbr0",
- "key": "bridge.external_interfaces",
- "description": "\"bridge.external_interfaces\" property for network \"lxdbr0\"",
- },
- ],
- }
+```json
+{
+ "server_name": "node1",
+ "enabled": true,
+ "member_config": [
+ {
+ "entity": "storage-pool",
+ "name": "local",
+ "key": "source",
+ "description": "\"source\" property for storage pool \"local\"",
+ },
+ {
+ "entity": "network",
+ "name": "lxdbr0",
+ "key": "bridge.external_interfaces",
+ "description": "\"bridge.external_interfaces\" property for network \"lxdbr0\"",
+ },
+ ],
+}
+```
#### PUT
* Description: bootstrap or join a cluster, or disable clustering on this node
@@ -2933,42 +3202,48 @@ Return:
Input (bootstrap a new cluster):
- {
- "server_name": "lxd1",
- "enabled": true,
- }
+```json
+{
+ "server_name": "lxd1",
+ "enabled": true,
+}
+```
Return background operation or standard error.
Input (request to join an existing cluster):
- {
- "server_name": "node2",
- "server_address": "10.1.1.102:8443",
- "enabled": true,
- "cluster_address": "10.1.1.101:8443",
- "cluster_certificate": "-----BEGIN CERTIFICATE-----MIFf\n-----END CERTIFICATE-----",
- "cluster_password": "sekret",
- "member_config": [
- {
- "entity": "storage-pool",
- "name": "local",
- "key": "source",
- "value": "/dev/sdb",
- },
- {
- "entity": "network",
- "name": "lxdbr0",
- "key": "bridge.external_interfaces",
- "value": "vlan0",
- },
- }
+```json
+{
+ "server_name": "node2",
+ "server_address": "10.1.1.102:8443",
+ "enabled": true,
+ "cluster_address": "10.1.1.101:8443",
+ "cluster_certificate": "-----BEGIN CERTIFICATE-----MIFf\n-----END CERTIFICATE-----",
+ "cluster_password": "sekret",
+ "member_config": [
+ {
+ "entity": "storage-pool",
+ "name": "local",
+ "key": "source",
+ "value": "/dev/sdb",
+ },
+ {
+ "entity": "network",
+ "name": "lxdbr0",
+ "key": "bridge.external_interfaces",
+ "value": "vlan0",
+ },
+}
+```
Input (disable clustering on the node):
- {
- "enabled": false,
- }
+```json
+{
+ "enabled": false,
+}
+```
### `/1.0/cluster/members`
#### GET
@@ -2980,10 +3255,12 @@ Input (disable clustering on the node):
Return:
- [
- "/1.0/cluster/members/lxd1",
- "/1.0/cluster/members/lxd2"
- ]
+```json
+[
+ "/1.0/cluster/members/lxd1",
+ "/1.0/cluster/members/lxd2"
+]
+```
### `/1.0/cluster/members/<name>`
#### GET
@@ -2995,13 +3272,15 @@ Return:
Return:
- {
- "server_name": "lxd1",
- "url": "https://10.1.1.101:8443",
- "database": true,
- "status": "Online",
- "message":"fully operational"
- }
+```json
+{
+ "server_name": "lxd1",
+ "url": "https://10.1.1.101:8443",
+ "database": true,
+ "status": "Online",
+ "message":"fully operational"
+}
+```
#### POST
* Description: rename a cluster member
@@ -3012,9 +3291,11 @@ Return:
Input:
- {
- "server_name": "node1",
- }
+```json
+{
+ "server_name": "node1",
+}
+```
#### DELETE (optional `?force=1`)
* Description: remove a member of the cluster
@@ -3025,5 +3306,7 @@ Input:
Input (none at present):
- {
- }
+```json
+{
+}
+```
More information about the lxc-devel
mailing list