Containers Service API

Zun Base URLs

All API calls through the rest of this document require authentication with the OpenStack Identity service. They also required a url that is extracted from the Identity token of type container. This will be the root url that every call below will be added to build a full path.

Note that if using OpenStack Identity service API v2, url can be represented via adminURL, internalURL or publicURL in endpoint catalog. In Identity service API v3, url is represented with field interface including admin, internal and public.

For instance, if the url is http://my-zun-url.org/zun/v1 then the full API call for /containers is http://my-zun-url.org/zun/v1/containers.

Depending on the deployment the containers service url might be http or https, a custom port, a custom path, and include your project id. The only way to know the urls for your deployment is by using the service catalog. The containers service URL should never be hard coded in applications, even if they are only expected to work at a single site. It should always be discovered from the Identity token.

As such, for the rest of this document we will be using short hand where GET /containers really means GET {your_zun_url}/containers.

Manage Capsules (Pods)

Lists, creates, shows details for, and deletes capsules.

Capsules is a collection of containers that can run on a host. It is basically a Zun implementation of Kubernetes Pod. Containers inside a capsule share the Neutron network and Cinder volumes.

POST
/v1/capsules/

Create new capsule

Create new capsule.

Response Codes

Success

Code

Reason

202 - Accepted

Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Capsule Template

Name

In

Type

Description

template

body

object

A template for capsule.

kind

body

string

A string value representing the type of this object. Its value is capsule.

metadata (Optional)

body

object

Capsule metadata in key-value format. Keys can be name, labels and annotations. An example format would look as follows:

"metadata": {
    "labels": {"app": "web"},
    "name": "demo",
    "annotations": {"key1": "value1"}
}

metadata.labels (Optional)

body

object

The labels added to the capsule.

metadata.name (Optional)

body

string

The name of the capsule.

metadata.annotations (Optional)

body

object

The annotations added to the capsule. Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata.

spec

body

object

Specification of the desired behavior of the capsule. See Capsule Spec.

Capsule Spec

Name

In

Type

Description

containers

body

array

A list of containers objects.

initContainers (Optional)

body

array

A list of init containers objects.

restartPolicy (Optional)

body

string

Restart policy for all containers within the capsule. Its value can be Always, OnFailure, or Never.

volumes (Optional)

body

array

List of volumes that can be mounted by containers in this capsule.

Capsule Container

Name

In

Type

Description

image

body

string

The name or ID of the image.

command (Optional)

body

array

The command of the container.

args (Optional)

body

array

The arguments to the command.

env (Optional)

body

object

The environment variables to set in the container.

name (Optional)

body

string

The name of the container.

ports (Optional)

body

array

List of ports to expose from the container. Each item is a dictionary must contain a containerPort key. Optionally, it can contain a protocol key. An example format would look as follows:

"ports": [{
    "protocol": "TCP",
    "containerPort": 80
}]

ports.containerPort (Optional)

body

integer

The port to open in container. Its value must be a number between 1 and 65535.

ports.protocol (Optional)

body

string

The protocol. Its value can be TCP or UDP. Default is TCP.

resources (Optional)

body

object

Compute Resources required by this container. Supported compute resources are cpu and memory. An example format would look as follows:

"resources": {
    "requests": {
        "cpu": 0.1,
        "memory": 128
}}

resources.cpu (Optional)

body

float

The number of virtual CPU.

resources.memory (Optional)

body

integer

The amount of memory in MiB.

volumeMounts (Optional)

body

array

List of volumes to mount into the container’s filesystem. Each item must contain a name key and a mountPath key. An example format would look as follows:

"volumeMounts": [{
    "mountPath": "/work-dir",
    "name": "workdir"
}]

volumeMounts.name (Optional)

body

string

The name of the volume

volumeMounts.mountPath (Optional)

body

string

The path within the container at which the volume should be mounted.

workDir (Optional)

body

string

The working directory for commands to run in.

Capsule Volume

Name

In

Type

Description

name

body

string

The name of the volume.

cinder

body

object

The Cinder volume configuration. There are two options to configure the volume: use an existing volume or dynamically create one. To specify an existing volume, set the volumeID key with the UUID of the Cinder volume as value. For example:

"cinder": {
    "volumeID": "9e5b5387-ed3b-4b9d-ab1e-0ce1e9dd86a1",
    "autoRemove": false
}

To create a volume, set the size key with its size as value. For example:

"cinder": {
    "size": 1,
    "autoRemove": true
}

The autoRemove key is optional for deciding the cleanup of the volume.

cinder.volumeID (Optional)

body

string

The UUID of the Cinder volume.

cinder.size (Optional)

body

string

The size of the Cinder volume.

cinder.autoRemove (Optional)

body

string

Whether to remove the volume when the capsule is deleted.

Request Example

{
    "template": {
        "kind": "capsule",
        "spec": {
            "restartPolicy": "Always",
            "initContainers": [
                {
                    "workDir": "/",
                    "command": [
                        "wget",
                        "-O",
                        "/work-dir/index.html",
                        "https://www.openstack.org/"
                    ],
                    "env": {
                        "ENV1": "env1-value1"
                    },
                    "image": "busybox",
                    "volumeMounts": [
                        {
                            "mountPath": "/work-dir",
                            "name": "workdir"
                        }
                    ],
                    "resources": {
                        "requests": {
                            "cpu": 0.1,
                            "memory": 128
                        }
                    }
                }
            ],
            "containers": [
                {
                    "workDir": "/",
                    "env": {
                        "ENV2": "env2-value"
                    },
                    "image": "nginx",
                    "volumeMounts": [
                        {
                            "mountPath": "/usr/share/nginx/html",
                            "name": "workdir"
                        }
                    ],
                    "ports": [
                        {
                            "protocol": "TCP",
                            "containerPort": 80
                        }
                    ],
                    "resources": {
                        "requests": {
                            "cpu": 0.5,
                            "memory": 512
                        }
                    }
                }
            ],
            "volumes": [
                {
                    "cinder": {
                        "size": 1
                    },
                    "name": "workdir"
                }
            ]
        },
        "metadata": {
            "labels": {
                "app": "web"
            },
            "name": "demo",
            "annotations": {
                "key1": "value1"
            },
        }
    }
}

Response

Capsule

Name

In

Type

Description

addresses

body

string

IP address of the capsule. This includes both ipv4 and/or ipv6 addresses.

containers

body

object

List of containers belonging to the capsule. There must be at least one container in a capsule.

cpu

body

float

The number of virtual cpus of the capsule.

memory

body

string

The capsule memory size in MiB.

uuid

body

string

The UUID of the capsule.

name

body

string

The name of the capsule.

labels

body

object

The labels of the capsule.

annotations

body

object

The annotations of the capsule. Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata.

restart_policy

body

object

Restart policy for all containers within the capsule.

created_at

body

string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

updated_at

body

string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

user_id

body

string

The user ID of the user who owns the capsule.

project_id

body

string

The UUID of the project to which this capsule belongs.

status

body

string

The current state of the capsule.

status_reason

body

string

The reason of capsule current status.

links

body

string

A list of relative links.

Capsule Container

Name

In

Type

Description

addresses

body

string

IP address of the container. This includes both ipv4 and/or ipv6 addresses.

image

body

string

The name or ID of the image.

labels

body

object

A map of labels of the container.

disk

body

integer

The container disk size in GiB.

security_groups

body

string

Security groups to be added to the container.

task_state

body

string

The current task of the container.

user_id

body

string

The user ID of the user who owns the container.

uuid

body

string

The UUID of the container.

hostname

body

string

The hostname of container.

environment

body

object

The environment variables to set in the container.

memory

body

integer

The container memory size in MiB.

project_id

body

array

The UUID of the project to which this container belongs.

status

body

string

The current state of the container.

environment

body

object

The environment variables to set in the container.

workdir

body

string

The working directory for commands to run in.

healthcheck

body

object

A dict of health check for the container. Specify a test command to perform to check that the container is healthy. Four parameters are supported:

  • cmd: Command to run to check health.

  • interval: Time between running the check in seconds.

  • retries: Consecutive failures needed to report unhealthy.

  • timeout: Maximum time to allow one check to run in seconds.

auto_remove

body

boolean

Enable auto-removal of the container on daemon side when the container’s process exits.

auto_heal

body

boolean

The flag of healing non-existent container in docker.

cpu_policy

body

string

The CPU policy of the container. Its value can be dedicated or shared.

image_driver

body

string

The image driver to use to pull container image.

status_detail

body

string

The status detail of the container.

status_reason

body

string

The reason of container current status.

name

body

string

The name of the container.

restart_policy

body

object

Restart policy to apply when a container exits. It must contain a Name key and its allowed values are no, on-failure, always, unless-stopped. Optionally, it can contain a MaximumRetryCount key and its value is an integer.

cpu

body

float

The number of virtual cpus of the container.

command

body

array

Send command to the container.

registry_id

body

string

The ID of the image registry used by the container.

ports

body

string

The ports exposed on the container.

interactive

body

boolean

Keep STDIN open even if not attached.

tty

body

boolean

Whether this container allocate a TTY for itself.

Response Example

{
    "status": "Creating",
    "user_id": "c863491f37984815bf740836c86e9310",
    "uuid": "a4bad62a-f3ba-4b14-b2ab-2af470a2f32c",
    "links": [
        {
            "href": "http://openstack.example.com/v1/capsules/a4bad62a-f3ba-4b14-b2ab-2af470a2f32c",
            "rel": "self"
        },
        {
            "href": "http://openstack.example.com/capsules/a4bad62a-f3ba-4b14-b2ab-2af470a2f32c",
            "rel": "bookmark"
        }
    ],
    "created_at": "2019-05-18 21:02:12.304734",
    "labels": {
        "app": "web"
    },
    "annotations": {
        "key1": "value1"
    },
    "restart_policy": {
        "MaximumRetryCount": "0",
        "Name": "always"
    },
    "updated_at": null,
    "name": "demo",
    "memory": "512",
    "project_id": "493378c3aa3e4315a39fe8b125f9eaaa",
    "status_reason": null,
    "cpu": 0.5,
    "containers": [
        {
            "addresses": {},
            "image": "nginx",
            "labels": {},
            "disk": 0,
            "security_groups": [],
            "task_state": null,
            "user_id": "c863491f37984815bf740836c86e9310",
            "uuid": "6df062d2-293c-4c35-af81-22d27ce47887",
            "hostname": null,
            "environment": {
                "ENV2": "env2-value"
            },
            "memory": "512",
            "project_id": "493378c3aa3e4315a39fe8b125f9eaaa",
            "status": "Creating",
            "workdir": "/",
            "healthcheck": {},
            "auto_remove": false,
            "auto_heal": false,
            "cpu_policy": "shared",
            "image_driver": null,
            "status_detail": null,
            "status_reason": null,
            "name": "capsule-demo-pi-9",
            "restart_policy": {
                "MaximumRetryCount": "10",
                "Name": "on-failure"
            },
            "cpu": 0.5,
            "command": [],
            "registry_id": null,
            "ports": [],
            "interactive": true
        }
    ],
    "addresses": null
}
GET
/v1/capsules/

List all capsules

List all available capsules in Zun.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

This request does not contain anything in the request body.

Response

Capsule

Name

In

Type

Description

addresses

body

string

IP address of the capsule. This includes both ipv4 and/or ipv6 addresses.

containers

body

object

List of containers belonging to the capsule. There must be at least one container in a capsule.

cpu

body

float

The number of virtual cpus of the capsule.

memory

body

string

The capsule memory size in MiB.

uuid

body

string

The UUID of the capsule.

name

body

string

The name of the capsule.

labels

body

object

The labels of the capsule.

annotations

body

object

The annotations of the capsule. Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata.

restart_policy

body

object

Restart policy for all containers within the capsule.

created_at

body

string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

updated_at

body

string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

user_id

body

string

The user ID of the user who owns the capsule.

project_id

body

string

The UUID of the project to which this capsule belongs.

status

body

string

The current state of the capsule.

status_reason

body

string

The reason of capsule current status.

links

body

string

A list of relative links.

Capsule Container

Name

In

Type

Description

addresses

body

string

IP address of the container. This includes both ipv4 and/or ipv6 addresses.

image

body

string

The name or ID of the image.

labels

body

object

A map of labels of the container.

disk

body

integer

The container disk size in GiB.

security_groups

body

string

Security groups to be added to the container.

task_state

body

string

The current task of the container.

user_id

body

string

The user ID of the user who owns the container.

uuid

body

string

The UUID of the container.

hostname

body

string

The hostname of container.

environment

body

object

The environment variables to set in the container.

memory

body

integer

The container memory size in MiB.

project_id

body

array

The UUID of the project to which this container belongs.

status

body

string

The current state of the container.

environment

body

object

The environment variables to set in the container.

workdir

body

string

The working directory for commands to run in.

healthcheck

body

object

A dict of health check for the container. Specify a test command to perform to check that the container is healthy. Four parameters are supported:

  • cmd: Command to run to check health.

  • interval: Time between running the check in seconds.

  • retries: Consecutive failures needed to report unhealthy.

  • timeout: Maximum time to allow one check to run in seconds.

auto_remove

body

boolean

Enable auto-removal of the container on daemon side when the container’s process exits.

auto_heal

body

boolean

The flag of healing non-existent container in docker.

cpu_policy

body

string

The CPU policy of the container. Its value can be dedicated or shared.

image_driver

body

string

The image driver to use to pull container image.

status_detail

body

string

The status detail of the container.

status_reason

body

string

The reason of container current status.

name

body

string

The name of the container.

restart_policy

body

object

Restart policy to apply when a container exits. It must contain a Name key and its allowed values are no, on-failure, always, unless-stopped. Optionally, it can contain a MaximumRetryCount key and its value is an integer.

cpu

body

float

The number of virtual cpus of the container.

command

body

array

Send command to the container.

registry_id

body

string

The ID of the image registry used by the container.

ports

body

string

The ports exposed on the container.

interactive

body

boolean

Keep STDIN open even if not attached.

tty

body

boolean

Whether this container allocate a TTY for itself.

Response Example

{
    "capsules": [
        {
            "status": "Running",
            "user_id": "c863491f37984815bf740836c86e9310",
            "uuid": "a4bad62a-f3ba-4b14-b2ab-2af470a2f32c",
            "links": [
                {
                    "href": "http://openstack.example.com/v1/capsules/a4bad62a-f3ba-4b14-b2ab-2af470a2f32c",
                    "rel": "self"
                },
                {
                    "href": "http://openstack.example.com/capsules/a4bad62a-f3ba-4b14-b2ab-2af470a2f32c",
                    "rel": "bookmark"
                }
            ],
            "created_at": "2019-05-18 21:02:12",
            "labels": {
                "app": "web"
            },
            "annotations": {
                "key1": "value1"
            },
            "restart_policy": {
                "MaximumRetryCount": "0",
                "Name": "always"
            },
            "updated_at": "2019-05-18 21:02:30",
            "name": "demo",
            "memory": "512",
            "project_id": "493378c3aa3e4315a39fe8b125f9eaaa",
            "status_reason": null,
            "cpu": 0.5,
            "containers": [
                {
                    "addresses": {},
                    "image": "nginx",
                    "labels": {},
                    "disk": 0,
                    "security_groups": [],
                    "task_state": null,
                    "user_id": "c863491f37984815bf740836c86e9310",
                    "uuid": "6df062d2-293c-4c35-af81-22d27ce47887",
                    "hostname": "dce8bbff358a",
                    "environment": {
                        "ENV2": "env2-value"
                    },
                    "memory": "512",
                    "project_id": "493378c3aa3e4315a39fe8b125f9eaaa",
                    "status": "Running",
                    "workdir": "/",
                    "healthcheck": {},
                    "auto_remove": false,
                    "auto_heal": false,
                    "cpu_policy": "shared",
                    "image_driver": null,
                    "status_detail": null,
                    "status_reason": null,
                    "name": "capsule-demo-pi-9",
                    "restart_policy": {
                        "MaximumRetryCount": "10",
                        "Name": "on-failure"
                    },
                    "cpu": 0.5,
                    "command": [
                        "nginx",
                        "-g",
                        "daemon off;"
                    ],
                    "registry_id": null,
                    "ports": [
                        80
                    ],
                    "interactive": true,
                    "tty": true
                }
            ],
            "addresses": {
                "86f0b398-414f-4e6a-b569-21d3452eb769": [
                    {
                        "subnet_id": "48bdf0e5-49d0-4668-9dcf-c47ea69fb4c3",
                        "version": 4,
                        "preserve_on_delete": false,
                        "addr": "10.0.0.21",
                        "port": "d19617f2-6984-4c00-a914-da02b39fdc52"
                    },
                    {
                        "subnet_id": "54f53848-66fc-4697-ab31-a97579691312",
                        "version": 6,
                        "preserve_on_delete": false,
                        "addr": "fddf:ec1e:34b4:0:f816:3eff:feb3:6c0e",
                        "port": "d19617f2-6984-4c00-a914-da02b39fdc52"
                    }
                ]
            }
        }
    ],
    "next": null
}
GET
/v1/capsules/{capsule_ident}

Show details of a capsule

Get all information of a capsule in Zun.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

capsule_ident

path

string

The UUID or name of capsule in Zun.

Response

Capsule

Name

In

Type

Description

addresses

body

string

IP address of the capsule. This includes both ipv4 and/or ipv6 addresses.

containers

body

object

List of containers belonging to the capsule. There must be at least one container in a capsule.

cpu

body

float

The number of virtual cpus of the capsule.

memory

body

string

The capsule memory size in MiB.

uuid

body

string

The UUID of the capsule.

name

body

string

The name of the capsule.

labels

body

object

The labels of the capsule.

annotations

body

object

The annotations of the capsule. Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata.

restart_policy

body

object

Restart policy for all containers within the capsule.

created_at

body

string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

updated_at

body

string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

user_id

body

string

The user ID of the user who owns the capsule.

project_id

body

string

The UUID of the project to which this capsule belongs.

status

body

string

The current state of the capsule.

status_reason

body

string

The reason of capsule current status.

links

body

string

A list of relative links.

Capsule Container

Name

In

Type

Description

addresses

body

string

IP address of the container. This includes both ipv4 and/or ipv6 addresses.

image

body

string

The name or ID of the image.

labels

body

object

A map of labels of the container.

disk

body

integer

The container disk size in GiB.

security_groups

body

string

Security groups to be added to the container.

task_state

body

string

The current task of the container.

user_id

body

string

The user ID of the user who owns the container.

uuid

body

string

The UUID of the container.

hostname

body

string

The hostname of container.

environment

body

object

The environment variables to set in the container.

memory

body

integer

The container memory size in MiB.

project_id

body

array

The UUID of the project to which this container belongs.

status

body

string

The current state of the container.

environment

body

object

The environment variables to set in the container.

workdir

body

string

The working directory for commands to run in.

healthcheck

body

object

A dict of health check for the container. Specify a test command to perform to check that the container is healthy. Four parameters are supported:

  • cmd: Command to run to check health.

  • interval: Time between running the check in seconds.

  • retries: Consecutive failures needed to report unhealthy.

  • timeout: Maximum time to allow one check to run in seconds.

auto_remove

body

boolean

Enable auto-removal of the container on daemon side when the container’s process exits.

auto_heal

body

boolean

The flag of healing non-existent container in docker.

cpu_policy

body

string

The CPU policy of the container. Its value can be dedicated or shared.

image_driver

body

string

The image driver to use to pull container image.

status_detail

body

string

The status detail of the container.

status_reason

body

string

The reason of container current status.

name

body

string

The name of the container.

restart_policy

body

object

Restart policy to apply when a container exits. It must contain a Name key and its allowed values are no, on-failure, always, unless-stopped. Optionally, it can contain a MaximumRetryCount key and its value is an integer.

cpu

body

float

The number of virtual cpus of the container.

command

body

array

Send command to the container.

registry_id

body

string

The ID of the image registry used by the container.

ports

body

string

The ports exposed on the container.

interactive

body

boolean

Keep STDIN open even if not attached.

tty

body

boolean

Whether this container allocate a TTY for itself.

Response Example

{
    "status": "Running",
    "user_id": "c863491f37984815bf740836c86e9310",
    "uuid": "a4bad62a-f3ba-4b14-b2ab-2af470a2f32c",
    "links": [
        {
            "href": "http://openstack.example.com/v1/capsules/a4bad62a-f3ba-4b14-b2ab-2af470a2f32c",
            "rel": "self"
        },
        {
            "href": "http://openstack.example.com/capsules/a4bad62a-f3ba-4b14-b2ab-2af470a2f32c",
            "rel": "bookmark"
        }
    ],
    "created_at": "2019-05-18 21:02:12",
    "labels": {
        "app": "web"
    },
    "annotations": {
        "key1": "value1"
    },
    "restart_policy": {
        "MaximumRetryCount": "0",
        "Name": "always"
    },
    "updated_at": "2019-05-18 21:02:30",
    "name": "demo",
    "memory": "512",
    "project_id": "493378c3aa3e4315a39fe8b125f9eaaa",
    "status_reason": null,
    "cpu": 0.5,
    "containers": [
        {
            "addresses": {},
            "image": "nginx",
            "labels": {},
            "disk": 0,
            "security_groups": [],
            "task_state": null,
            "user_id": "c863491f37984815bf740836c86e9310",
            "uuid": "6df062d2-293c-4c35-af81-22d27ce47887",
            "hostname": "dce8bbff358a",
            "environment": {
                "ENV2": "env2-value"
            },
            "memory": "512",
            "project_id": "493378c3aa3e4315a39fe8b125f9eaaa",
            "status": "Running",
            "workdir": "/",
            "healthcheck": {},
            "auto_remove": false,
            "auto_heal": false,
            "cpu_policy": "shared",
            "image_driver": null,
            "status_detail": null,
            "status_reason": null,
            "name": "capsule-demo-pi-9",
            "restart_policy": {
                "MaximumRetryCount": "10",
                "Name": "on-failure"
            },
            "cpu": 0.5,
            "command": [
                "nginx",
                "-g",
                "daemon off;"
            ],
            "registry_id": null,
            "ports": [80],
            "interactive": true,
            "tty": true
        }
    ],
    "addresses": {
        "86f0b398-414f-4e6a-b569-21d3452eb769": [
            {
                "subnet_id": "48bdf0e5-49d0-4668-9dcf-c47ea69fb4c3",
                "version": 4,
                "preserve_on_delete": false,
                "addr": "10.0.0.21",
                "port": "d19617f2-6984-4c00-a914-da02b39fdc52"
            },
            {
                "subnet_id": "54f53848-66fc-4697-ab31-a97579691312",
                "version": 6,
                "preserve_on_delete": false,
                "addr": "fddf:ec1e:34b4:0:f816:3eff:feb3:6c0e",
                "port": "d19617f2-6984-4c00-a914-da02b39fdc52"
            }
        ]
    }
}
DELETE
/v1/capsules/{capsule_ident}

Delete a capsule

Delete a capsule.

Response Codes

Success

Code

Reason

204 - No Content

The server has fulfilled the request by deleting the resource.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

Request

Name

In

Type

Description

capsule_ident

path

string

The UUID or name of capsule in Zun.

Response

This request does not return anything in the response body.

Manage Containers

Lists, creates, shows details for, stats, updates, deletes, starts, resizes, stops, pauses, unpauses, restarts, renames, commits, kills, attaches to containers, gets archive from container, puts archive to container, and adds security group for specified container, executes command in a running container, gets logs of a container, displays the running processes in a container, resizes the tty session used by the exec, list actions and action detail for a container.

POST
/v1/containers/

Create new container

Create new container.

Response Codes

Success

Code

Reason

202 - Accepted

Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

name (Optional)

body

string

The name of the container.

image

body

string

The name or ID of the image.

command (Optional)

body

string

Send command to the container.

cpu (Optional)

body

float

The number of virtual cpus.

memory (Optional)

body

integer

The container memory size in MiB.

workdir (Optional)

body

string

The working directory for commands to run in.

labels (Optional)

body

object

Adds a map of labels to a container.

environment (Optional)

body

object

The environment variables to set in the container.

restart_policy (Optional)

body

object

Restart policy to apply when a container exits. It must contain a Name key and its allowed values are no, on-failure, always, unless-stopped. Optionally, it can contain a MaximumRetryCount key and its value is an integer.

interactive (Optional)

body

boolean

Keep STDIN open even if not attached.

tty (Optional)

body

boolean

Whether this container should allocate a TTY for itself.

image_driver (Optional)

body

string

The image driver to use to pull container image. Allowed values are docker to pull the image from Docker Hub and glance to pull the image from Glance.

security_groups (Optional)

body

string

Security groups to be added to the container.

nets (Optional)

body

object

A list of networks for the container. When you do not specify the nets parameter, the container attaches to the only network created for the current tenant. To provision the container with a NIC for a network, specify the UUID or name of the network in the network attribute. To provision the container with a NIC for an already existing port, specify the port id or name in the port attribute.

If multiple networks are defined, the order in which they appear in the container will not necessarily reflect the order in which they are given in the request. Users should therefore not depend on device order to deduce any information about their network devices.

runtime (Optional)

body

string

The container runtime tool to create container with. You can use the default runtime that is runc or any other runtime configured to use with Docker.

hostname (Optional)

body

string

The hostname of container.

auto_remove (Optional)

body

boolean

enable auto-removal of the container on daemon side when the container’s process exits.

auto_heal (Optional)

body

boolean

The flag of healing non-existent container in docker.

availability_zone (Optional)

body

string

The availability zone from which to run the container. Typically, an admin user will use availability zones to arrange container hosts into logical groups. An availability zone provides a form of physical isolation and redundancy from other availability zones. For instance, if some racks in your data center are on a separate power source, you can put containers in those racks in their own availability zone. By segregating resources into availability zones, you can ensure that your application resources are spread across disparate machines to achieve high availability in the event of hardware or other failure. You can see the available availability zones by calling the services API.

hints (Optional)

body

string

The dictionary of data to send to the scheduler.

mounts (Optional)

body

object

A list of dictionary data to specify how volumes are mounted into the container. The container will mount the volumes at create time. Each item can have an type attribute that specifies the volume type. The supported volume types are volume or bind. If this attribute is not specified, the default is volume. To provision a container with pre-existing Cinder volumes bind-mounted, specify the UUID or name of the volume in the source attribute. Alternatively, Cinder volumes can be dynamically created. In this case, the size of the volume needs to be specified in the size attribute. Another option is to mount a user-provided file into the container. In this case, the type attribute should be ‘bind’ and the content of the file is contained in the source attribute. The volumes will be mounted into the file system of the container and the path to mount the volume needs to be specified in the destination attribute.

privileged (Optional)

body

boolean

Give extended privileges to the container.

healthcheck (Optional)

body

object

A dict of health check for the container. Specify a test command to perform to check that the container is healthy. Four parameters are supported:

  • cmd: Command to run to check health.

  • interval: Time between running the check in seconds.

  • retries: Consecutive failures needed to report unhealthy.

  • timeout: Maximum time to allow one check to run in seconds.

exposed_ports (Optional)

body

object

A list of dictionary data to specify how to expose container’s ports. If this parameter is specified, Zun will create a security group with a set of rules to open the ports that should be exposed, and associate the security group to the container. The value is in the form of {"<port>/<protocol>: {}"}, where the port is the container’s port and protocol is either tcp or udp. If protocol is not provided, tcp will be used.

host (Optional)

body

string

The name of the host on which the container is to be created. The API will return 400 if no host are found with the given host name. By default, it can be specified by administrators only.

entrypoint (Optional)

body

array

The entrypoint which overwrites the default ENTRYPOINT of the image.

Request Example

{
    "environment":{
        "foo": "bar"
    },
    "labels":{
        "app": "hello"
    },
    "image": "ubuntu",
    "command": [
        "/bin/sh",
        "-c",
        "'echo hello'"
    ],
    "name": "test",
    "cpu": 2,
    "memory": 500,
    "workdir": "/home/ubuntu",
    "restart_policy":{
        "Name": "no",
        "MaximumRetryCount": 0
    },
    "interactive": false,
    "tty": false,
    "image_driver": "docker",
    "security_groups": [
        "default"
    ],
    "nets": [
        {
            "v4-fixed-ip": "",
            "network": "",
            "v6-fixed-ip": "",
            "port": "890699a9-4690-4bd6-8b70-3a9c1be77ecb"
        }
    ],
    "runtime": "runc",
    "hostname": "testhost",
    "auto_remove": false,
    "auto_heal": false,
    "availability_zone": "nova",
    "hints": {
        "foo": "bar"
    },
    "mounts": [
        {
            "source": "myvol",
            "destination": "/data"
        }
    ],
    "privileged": false,
    "healthcheck": {
        "cmd": "stat /etc/passwd || exit 1",
        "interval": 3,
        "retries": 2,
        "timeout": 5
    }
}

Response

Name

In

Type

Description

links

body

array

A list of relative links. Includes the self and bookmark links.

addresses

body

string

IP address of the container. This includes both ipv4 and/or ipv6 addresses.

name

body

string

The name of the container.

image

body

string

The name or ID of the image.

labels

body

object

A map of labels of the container.

image_driver

body

string

The image driver to use to pull container image.

security_groups

body

string

Security groups to be added to the container.

command

body

array

Send command to the container.

cpu

body

float

The number of virtual cpus of the container.

memory

body

integer

The container memory size in MiB.

workdir

body

string

The working directory for commands to run in.

environment

body

object

The environment variables to set in the container.

restart_policy

body

object

Restart policy to apply when a container exits. It must contain a Name key and its allowed values are no, on-failure, always, unless-stopped. Optionally, it can contain a MaximumRetryCount key and its value is an integer.

interactive

body

boolean

Keep STDIN open even if not attached.

tty

body

boolean

Whether this container allocate a TTY for itself.

uuid

body

UUID

UUID of the resource.

hostname

body

string

The hostname of container.

status

body

string

The current state of the container.

status_detail

body

string

The status detail of the container.

host

body

string

The host for the service.

task_state

body

string

The current task of the container.

status_reason

body

string

The reason of container current status.

ports

body

string

The ports exposed on the container.

auto_remove

body

boolean

Enable auto-removal of the container on daemon side when the container’s process exits.

auto_heal

body

boolean

The flag of healing non-existent container in docker.

privileged

body

boolean

Give extended privileges to the container.

healthcheck

body

object

A dict of health check for the container. Specify a test command to perform to check that the container is healthy. Four parameters are supported:

  • cmd: Command to run to check health.

  • interval: Time between running the check in seconds.

  • retries: Consecutive failures needed to report unhealthy.

  • timeout: Maximum time to allow one check to run in seconds.

user_id

body

string

The user ID of the user who owns the container.

project_id

path

string

The UUID of project in a multi-project cloud.

disk

body

integer

The container disk size in GiB.

registry_id

body

string

The ID of the image registry used by the container.

cpu_policy

body

string

The CPU policy of the container. Its value can be dedicated or shared.

entrypoint

body

array

The entrypoint which overwrites the default ENTRYPOINT of the image.

Response Example

{
    "addresses": null,
    "links": [
        {
            "href": "http://openstack.example.com/v1/containers/b0694d40-70af-4488-b104-10f66b593347",
            "rel": "self"
        },
        {
            "href": "http://openstack.example.com/containers/b0694d40-70af-4488-b104-10f66b593347",
            "rel": "bookmark"
        }
    ],
    "image": "ubuntu",
    "labels": {
        "app": "hello"
    },
    "security_groups": [
        "7e4eae5d-8b7b-4673-91b3-70dfb577e620"
    ],
    "uuid": "b0694d40-70af-4488-b104-10f66b593347",
    "environment": {
        "foo": "bar"
    },
    "memory": "500",
    "status": "Creating",
    "workdir": "/home/ubuntu",
    "status_detail": null,
    "host": null,
    "image_driver": "docker",
    "task_state": null,
    "status_reason": null,
    "name": "test",
    "restart_policy": {
        "MaximumRetryCount": "0",
        "Name": "no"
    },
    "ports": null,
    "command": [
        "/bin/sh",
        "-c",
        "'echo hello'"
    ],
    "cpu": 2.0,
    "interactive": false,
    "tty": false,
    "runtime": "runc",
    "hostname": "testhost",
    "auto_remove": false,
    "auto_heal": false,
    "privileged": false,
    "disk": 0,
    "user_id": "0a9cdb65757b4216935e27f333d1c48b",
    "project_id": "77a89a275765486d86144caad70825e4",
    "cpu_policy": "shared",
    "registry_id": null,
    "healthcheck": {
        "test": "stat /etc/passwd || exit 1",
        "interval": 3,
        "retries": 2,
        "timeout": 5
    }
}
GET
/v1/containers/

List all containers

List all available containers in Zun.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

name (Optional)

query

string

Filters the response by name.

image (Optional)

query

string

Filters the response by image.

project_id (Optional)

query

string

Filters the response by the ID of the project.

user_id (Optional)

query

string

Filters the response by user ID.

memory (Optional)

query

integer

Filters the response by memory size in Mib.

host (Optional)

query

string

Filters the response by a host name, as a string.

task_state (Optional)

query

string

Filters the response by task state.

status (Optional)

query

string

Filters the response by the current state of the container.

auto_remove (Optional)

query

boolean

Filters the response according to whether they are auto-removed on exiting.

Response

Name

In

Type

Description

containers

body

array

The list of all containers in Zun.

links

body

array

A list of relative links. Includes the self and bookmark links.

addresses

body

string

IP address of the container. This includes both ipv4 and/or ipv6 addresses.

name

body

string

The name of the container.

image

body

string

The name or ID of the image.

labels

body

object

A map of labels of the container.

image_driver

body

string

The image driver to use to pull container image.

security_groups

body

string

Security groups to be added to the container.

command

body

array

Send command to the container.

cpu

body

float

The number of virtual cpus of the container.

memory

body

integer

The container memory size in MiB.

workdir

body

string

The working directory for commands to run in.

environment

body

object

The environment variables to set in the container.

restart_policy

body

object

Restart policy to apply when a container exits. It must contain a Name key and its allowed values are no, on-failure, always, unless-stopped. Optionally, it can contain a MaximumRetryCount key and its value is an integer.

interactive

body

boolean

Keep STDIN open even if not attached.

tty

body

boolean

Whether this container allocate a TTY for itself.

uuid

body

UUID

UUID of the resource.

hostname

body

string

The hostname of container.

status

body

string

The current state of the container.

status_detail

body

string

The status detail of the container.

host

body

string

The host for the service.

task_state

body

string

The current task of the container.

status_reason

body

string

The reason of container current status.

ports

body

string

The ports exposed on the container.

privileged

body

boolean

Give extended privileges to the container.

healthcheck

body

object

A dict of health check for the container. Specify a test command to perform to check that the container is healthy. Four parameters are supported:

  • cmd: Command to run to check health.

  • interval: Time between running the check in seconds.

  • retries: Consecutive failures needed to report unhealthy.

  • timeout: Maximum time to allow one check to run in seconds.

user_id

body

string

The user ID of the user who owns the container.

project_id

path

string

The UUID of project in a multi-project cloud.

disk

body

integer

The container disk size in GiB.

registry_id

body

string

The ID of the image registry used by the container.

cpu_policy

body

string

The CPU policy of the container. Its value can be dedicated or shared.

entrypoint

body

array

The entrypoint which overwrites the default ENTRYPOINT of the image.

Response Example

{
    "containers": [
        {
            "addresses": {
                "2ede1821-1334-4e8b-b731-d3a82b41f42f": [{
                    "subnet_id": "a3162b3e-2f02-432e-a18c-78fe2774d026",
                    "version": 4,
                    "preserve_on_delete": false,
                    "addr": "172.24.4.3",
                    "port": "4b077255-9b4d-4068-b24f-b89594f870c2"
                    }, {
                    "subnet_id": "7ca0d3d5-eeef-489f-8a40-ccb00456628c",
                    "version": 6,
                    "preserve_on_delete": false,
                    "addr": "2001:db8::9",
                    "port": "4b077255-9b4d-4068-b24f-b89594f870c2"
                    }]
            },
            "links": [{
                "href": "http://openstack.example.com/v1/containers/b0694d40-70af-4488-b104-10f66b593347",
                "rel": "self"
                },
                {"href": "http://openstack.example.com/containers/b0694d40-70af-4488-b104-10f66b593347", "rel": "bookmark"}
            ],
            "image": "ubuntu",
            "labels": {
                "app": "hello"
            },
            "disk": 0,
            "security_groups": [],
            "user_id": "06c7fda2e74d4f5084bb8298bf8e313b",
            "uuid": "b0694d40-70af-4488-b104-10f66b593347",
            "hostname": "zun-sandbox-5812822d-6794-4839-85c0-1c01665c0d48",
            "environment": {
                "foo": "bar"
            },
            "memory": "500",
            "project_id": "2cc8ed7104ca427c873cad82411bcebb",
            "status": "Stopped",
            "workdir": "/home/ubuntu",
            "status_detail": "Exited(0) 10 mins ago ",
            "auto_remove": false,
            "auto_heal": false,
            "privileged": false,
            "host": "ubuntu",
            "image_driver": "docker",
            "task_state": null,
            "status_reason": null,
            "name": "test",
            "restart_policy": {
                "MaximumRetryCount": "0",
                "Name": "no"
            },
            "runtime": "runc",
            "ports": [],
            "command": [
                "/bin/sh",
                "-c",
                "'echo hello'"
            ],
            "cpu": 2.0,
            "interactive": false,
	    "tty": false,
            "cpu_policy": "shared",
            "registry_id": null,
            "healthcheck": {
                "test": "stat /etc/passwd || exit 1",
                "interval": 3,
                "retries": 2,
                "timeout": 5
            }
        }
    ],
    "next": null
}
GET
/v1/containers/{container_ident}

Show details of a container

Get all information of a container in Zun.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

Response

Name

In

Type

Description

links

body

array

A list of relative links. Includes the self and bookmark links.

addresses

body

string

IP address of the container. This includes both ipv4 and/or ipv6 addresses.

name

body

string

The name of the container.

image

body

string

The name or ID of the image.

labels

body

object

A map of labels of the container.

image_driver

body

string

The image driver to use to pull container image.

security_groups

body

string

Security groups to be added to the container.

command

body

array

Send command to the container.

cpu

body

float

The number of virtual cpus of the container.

memory

body

integer

The container memory size in MiB.

workdir

body

string

The working directory for commands to run in.

environment

body

object

The environment variables to set in the container.

restart_policy

body

object

Restart policy to apply when a container exits. It must contain a Name key and its allowed values are no, on-failure, always, unless-stopped. Optionally, it can contain a MaximumRetryCount key and its value is an integer.

interactive

body

boolean

Keep STDIN open even if not attached.

tty

body

boolean

Whether this container allocate a TTY for itself.

uuid

body

UUID

UUID of the resource.

hostname

body

string

The hostname of container.

status

body

string

The current state of the container.

status_detail

body

string

The status detail of the container.

host

body

string

The host for the service.

task_state

body

string

The current task of the container.

status_reason

body

string

The reason of container current status.

ports

body

string

The ports exposed on the container.

privileged

body

boolean

Give extended privileges to the container.

healthcheck

body

object

A dict of health check for the container. Specify a test command to perform to check that the container is healthy. Four parameters are supported:

  • cmd: Command to run to check health.

  • interval: Time between running the check in seconds.

  • retries: Consecutive failures needed to report unhealthy.

  • timeout: Maximum time to allow one check to run in seconds.

user_id

body

string

The user ID of the user who owns the container.

project_id

path

string

The UUID of project in a multi-project cloud.

disk

body

integer

The container disk size in GiB.

registry_id

body

string

The ID of the image registry used by the container.

cpu_policy

body

string

The CPU policy of the container. Its value can be dedicated or shared.

entrypoint

body

array

The entrypoint which overwrites the default ENTRYPOINT of the image.

Response Example

{
    "addresses": {
        "c0c5f8ed-6654-4d25-b0de-c858b9f620be": [{
            "subnet_id": "a3162b3e-2f02-432e-a18c-78fe2774d026",
            "version": 4,
            "preserve_on_delete": false,
            "addr": "172.24.4.3",
            "port": "4b077255-9b4d-4068-b24f-b89594f870c2"
            }, {
            "subnet_id": "7ca0d3d5-eeef-489f-8a40-ccb00456628c",
            "version": 6,
            "preserve_on_delete": false,
            "addr": "2001:db8::9",
            "port": "4b077255-9b4d-4068-b24f-b89594f870c2"
            }]
    },
    "links": [{
        "href": "http://openstack.example.com/v1/containers/b0694d40-70af-4488-b104-10f66b593347",
        "rel": "self"
        },
        {"href": "http://openstack.example.com/containers/b0694d40-70af-4488-b104-10f66b593347", "rel": "bookmark"}
    ],
    "image": "ubuntu",
    "labels": {
        "app": "hello"
    },
    "disk": 0,
    "security_groups": [],
    "user_id": "06c7fda2e74d4f5084bb8298bf8e313b",
    "uuid": "b0694d40-70af-4488-b104-10f66b593347",
    "hostname": "zun-sandbox-5812822d-6794-4839-85c0-1c01665c0d48",
    "environment": {
        "foo": "bar"
    },
    "memory": "500",
    "project_id": "2cc8ed7104ca427c873cad82411bcebb",
    "status": "Stopped",
    "workdir": "/home/ubuntu",
    "auto_remove": false,
    "auto_heal": false,
    "privileged": false,
    "status_detail": "Exited(0) 8 mins ago ",
    "host": "ubuntu",
    "image_driver": "docker",
    "task_state": null,
    "status_reason": null,
    "name": "test",
    "restart_policy": {
        "MaximumRetryCount": "0",
        "Name": "no"
    },
    "ports": [],
    "command": [
        "/bin/sh",
        "-c",
        "'echo hello'"
    ],
    "cpu": 2.0,
    "interactive": false,
    "tty": false,
    "cpu_policy": "shared",
    "registry_id": null,
    "healthcheck": {
        "test": "stat /etc/passwd || exit 1",
        "interval": 3,
        "retries": 2,
        "timeout": 5
    }
}
DELETE
/v1/containers/{container_ident}

Delete a container

Delete a container. To delete a container in Creating or Running state, request to /v1/containers/{container_ident}?force=True To stop and delete a container, request to /v1/containers/{container _ident}?stop=True

Response Codes

Success

Code

Reason

204 - No Content

The server has fulfilled the request by deleting the resource.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

force

query

string

Specify to delete container forcefully.

stop (Optional)

query

string

Whether or not stop a container firstly before deleting it.

Response

This request does not return anything in the response body.

Name

In

Type

Description

X-Openstack-Request-Id

header

UUID

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

POST
/v1/containers/{container_ident}/kill

Kill a container

Kill a running container.

Response Codes

Success

Code

Reason

202 - Accepted

Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

signal (Optional)

query

string

The signal to kill a container.

Response

This request does not return anything in the response body.

Name

In

Type

Description

X-Openstack-Request-Id

header

UUID

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

GET
/v1/containers/{container_ident}/stats

Display stats of a container

Display stats of a container.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

Response

Name

In

Type

Description

stats_info

body

dict

The stats information of a container, including cpu, memory, blk io and net io.

Response Example

{
    "CONTAINER": "test",
    "CPU %": 8.89,
    "MEM USAGE(MiB)": 7,
    "MEM LIMIT(MiB)": 16048,
    "MEM %": 0.0436191425723,
    "BLOCK I/O(B)": "12910592/0",
    "NET I/O(B)": "246614/648"
}
PATCH
/v1/containers/{container_ident}

Update information of container

Update information of one container attributes. Currently only cpu, name and memory can be updated.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

memory

body

integer

The container memory size in MiB.

cpu

body

float

The number of virtual cpus of the container.

name

body

string

The name of the container.

Request Example

{
    "memory": "200",
    "cpu": "3",
    "name": "test_new"
}

Response

Return new container with updated attributes.

Name

In

Type

Description

links

body

array

A list of relative links. Includes the self and bookmark links.

addresses

body

string

IP address of the container. This includes both ipv4 and/or ipv6 addresses.

name

body

string

The name of the container.

image

body

string

The name or ID of the image.

labels

body

object

A map of labels of the container.

image_driver

body

string

The image driver to use to pull container image.

security_groups

body

string

Security groups to be added to the container.

command

body

array

Send command to the container.

cpu

body

float

The number of virtual cpus of the container.

memory

body

integer

The container memory size in MiB.

workdir

body

string

The working directory for commands to run in.

environment

body

object

The environment variables to set in the container.

restart_policy

body

object

Restart policy to apply when a container exits. It must contain a Name key and its allowed values are no, on-failure, always, unless-stopped. Optionally, it can contain a MaximumRetryCount key and its value is an integer.

interactive

body

boolean

Keep STDIN open even if not attached.

tty

body

boolean

Whether this container allocate a TTY for itself.

uuid

body

UUID

UUID of the resource.

hostname

body

string

The hostname of container.

status

body

string

The current state of the container.

status_detail

body

string

The status detail of the container.

host

body

string

The host for the service.

task_state

body

string

The current task of the container.

status_reason

body

string

The reason of container current status.

ports

body

string

The ports exposed on the container.

privileged

body

boolean

Give extended privileges to the container.

healthcheck

body

object

A dict of health check for the container. Specify a test command to perform to check that the container is healthy. Four parameters are supported:

  • cmd: Command to run to check health.

  • interval: Time between running the check in seconds.

  • retries: Consecutive failures needed to report unhealthy.

  • timeout: Maximum time to allow one check to run in seconds.

user_id

body

string

The user ID of the user who owns the container.

project_id

path

string

The UUID of project in a multi-project cloud.

disk

body

integer

The container disk size in GiB.

registry_id

body

string

The ID of the image registry used by the container.

cpu_policy

body

string

The CPU policy of the container. Its value can be dedicated or shared.

entrypoint

body

array

The entrypoint which overwrites the default ENTRYPOINT of the image.

Response Example

{
    "addresses": {
        "eb7a3ee0-ad55-417b-ba11-6c57b1dbd4c6": [
            {
                "subnet_id": "a3162b3e-2f02-432e-a18c-78fe2774d026",
                "version": 4,
                "preserve_on_delete": false,
                "addr": "172.24.4.3",
                "port": "4b077255-9b4d-4068-b24f-b89594f870c2"
            },
            {
                "subnet_id": "7ca0d3d5-eeef-489f-8a40-ccb00456628c",
                "version": 6,
                "preserve_on_delete": false,
                "addr": "2001:db8::9",
                "port": "4b077255-9b4d-4068-b24f-b89594f870c2"
            }
        ]
    },
    "links": [
        {
            "href": "http://openstack.example.com/v1/containers/b0694d40-70af-4488-b104-10f66b593347",
            "rel": "self"
        },
        {
            "href": "http://openstack.example.com/containers/b0694d40-70af-4488-b104-10f66b593347",
            "rel": "bookmark"
        }
    ],
    "image": "ubuntu",
    "labels": {
        "app": "hello"
    },
    "security_groups": [],
    "user_id": "06c7fda2e74d4f5084bb8298bf8e313b",
    "uuid": "b0694d40-70af-4488-b104-10f66b593347",
    "hostname": "zun-sandbox-5812822d-6794-4839-85c0-1c01665c0d48",
    "environment": {
        "foo": "bar"
    },
    "memory": "200",
    "status": "Stopped",
    "workdir": "/home/ubuntu",
    "status_detail": "Exited(0) 18 mins ago ",
    "host": "ubuntu",
    "image_driver": "docker",
    "task_state": null,
    "status_reason": null,
    "name": "test_new",
    "restart_policy": {
        "MaximumRetryCount": "0",
        "Name": "no"
    },
    "ports": [],
    "command": [
        "/bin/sh",
        "-c",
        "'echo hello'"
    ],
    "runtime": "runc",
    "cpu": 3.0,
    "interactive": false,
    "tty": false,
    "privileged": false,
    "project_id": "493378c3aa3e4315a39fe8b125f9eaaa",
    "disk": 0,
    "auto_remove": false,
    "auto_heal": false,
    "cpu_policy": "shared",
    "registry_id": null,
    "healthcheck": {
        "test": "stat /etc/passwd || exit 1",
        "interval": 3,
        "retries": 2,
        "timeout": 5
    }
}
POST
/v1/containers/{container_ident}/start

Start a container

Start a container.

Response Codes

Success

Code

Reason

202 - Accepted

Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

Response

This request does not return anything in the response body.

Name

In

Type

Description

X-Openstack-Request-Id

header

UUID

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

POST
/v1/containers/{container_ident}/stop

Stop a container

Stop a container.

Response Codes

Success

Code

Reason

202 - Accepted

Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

timeout

query

string

Seconds to wait before operating on container.

Response

This request does not return anything in the response body.

Name

In

Type

Description

X-Openstack-Request-Id

header

UUID

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

POST
/v1/containers/{container_ident}/pause

Pause a container

Pause a container.

Response Codes

Success

Code

Reason

202 - Accepted

Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

Response

This request does not return anything in the response body.

Name

In

Type

Description

X-Openstack-Request-Id

header

UUID

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

POST
/v1/containers/{container_ident}/unpause

Unpause a container

Unpause a container.

Response Codes

Success

Code

Reason

202 - Accepted

Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

Response

This request does not return anything in the response body.

Name

In

Type

Description

X-Openstack-Request-Id

header

UUID

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

POST
/v1/containers/{container_ident}/rebuild

Rebuild a container

Rebuild a container.

Response Codes

Success

Code

Reason

202 - Accepted

Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

image

body

string

The name or ID of the image.

image_driver

body

string

The image driver to use to pull container image.

Response

This request does not return anything in the response body.

Name

In

Type

Description

X-Openstack-Request-Id

header

UUID

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

POST
/v1/containers/{container_ident}/reboot

Restart a container

Restart a container.

Response Codes

Success

Code

Reason

202 - Accepted

Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

timeout

query

string

Seconds to wait before operating on container.

Response

This request does not return anything in the response body.

Name

In

Type

Description

X-Openstack-Request-Id

header

UUID

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

POST
/v1/containers/{container_ident}/rename

Rename a container

Rename a container.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

new_name

query

string

The new name for the container.

Response

Name

In

Type

Description

links

body

array

A list of relative links. Includes the self and bookmark links.

addresses

body

string

IP address of the container. This includes both ipv4 and/or ipv6 addresses.

name

body

string

The name of the container.

image

body

string

The name or ID of the image.

labels

body

object

A map of labels of the container.

image_driver

body

string

The image driver to use to pull container image.

security_groups

body

string

Security groups to be added to the container.

command

body

array

Send command to the container.

cpu

body

float

The number of virtual cpus of the container.

memory

body

integer

The container memory size in MiB.

workdir

body

string

The working directory for commands to run in.

environment

body

object

The environment variables to set in the container.

restart_policy

body

object

Restart policy to apply when a container exits. It must contain a Name key and its allowed values are no, on-failure, always, unless-stopped. Optionally, it can contain a MaximumRetryCount key and its value is an integer.

interactive

body

boolean

Keep STDIN open even if not attached.

tty

body

boolean

Whether this container allocate a TTY for itself.

uuid

body

UUID

UUID of the resource.

hostname

body

string

The hostname of container.

status

body

string

The current state of the container.

status_detail

body

string

The status detail of the container.

host

body

string

The host for the service.

task_state

body

string

The current task of the container.

status_reason

body

string

The reason of container current status.

ports

body

string

The ports exposed on the container.

user_id

body

string

The user ID of the user who owns the container.

project_id

path

string

The UUID of project in a multi-project cloud.

disk

body

integer

The container disk size in GiB.

registry_id

body

string

The ID of the image registry used by the container.

cpu_policy

body

string

The CPU policy of the container. Its value can be dedicated or shared.

entrypoint

body

array

The entrypoint which overwrites the default ENTRYPOINT of the image.

Response Example

{
    "addresses": {
        "f82824cf-bd0e-4c39-9450-3cf802ed262f": [
            {
                "version": 4,
                "addr": "172.24.4.3",
                "port": "4b077255-9b4d-4068-b24f-b89594f870c2"
            },
            {
                "version": 6,
                "addr": "2001:db8::9",
                "port": "4b077255-9b4d-4068-b24f-b89594f870c2"
            }
        ]
    },
    "links": [
        {
            "href": "http://openstack.example.com/v1/containers/b0694d40-70af-4488-b104-10f66b593347",
            "rel": "self"
        },
        {
            "href": "http://openstack.example.com/containers/b0694d40-70af-4488-b104-10f66b593347",
            "rel": "bookmark"
        }
    ],
    "image": "ubuntu",
    "labels": {
        "app": "hello"
    },
    "security_groups": [],
    "uuid": "b0694d40-70af-4488-b104-10f66b593347",
    "hostname": "zun-sandbox-5812822d-6794-4839-85c0-1c01665c0d48",
    "environment": {
        "foo": "bar"
    },
    "memory": "500",
    "status": "Stopped",
    "workdir": "/home/ubuntu",
    "status_detail": "Exited(0) 8 mins ago ",
    "host": "ubuntu",
    "image_driver": "docker",
    "task_state": null,
    "status_reason": null,
    "name": "test-new",
    "restart_policy": {
        "MaximumRetryCount": "0",
        "Name": "no"
    },
    "ports": [],
    "command": [
        "/bin/sh",
        "-c",
        "'echo hello'"
    ],
    "cpu": 2.0,
    "disk": 0,
    "project_id": "493378c3aa3e4315a39fe8b125f9eaaa",
    "user_id": "06c7fda2e74d4f5084bb8298bf8e313b",
    "auto_remove": false,
    "auto_heal": false,
    "cpu_policy": "shared",
    "registry_id": null,
    "interactive": false,
    "tty": false
}
GET
/v1/containers/{container_ident}/get_archive

Get archive from a container

Get a tar archive of a resource in the filesystem of a container.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

source_path

query

string

The file path in a container when getting archive from a container.

Response

Name

In

Type

Description

data

body

string

The content of the tar file which is got from a container or put to a container.

stat

body

string

The stat information when doing get_archive.

Response Example

{
    "stat": {
        "linkTarget": "",
        "size": 129,
        "mode": 493,
        "name": "ip.sh",
        "mtime": "2017-07-25T18:54:50-07:00"
    },
    "data": "ARCHIVE FILE DATA"
}
POST
/v1/containers/{container_ident}/put_archive

Put archive to a container

Upload a tar archive to be extracted to a path in the filesystem of container.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

destination_path

query

string

The destination path in a container when putting archive to a container.

data

body

string

The content of the tar file which is got from a container or put to a container.

Request Example

{
    "data": "ARCHIVE FILE DATA"
}

Response

This request does not return anything in the response body.

Name

In

Type

Description

X-Openstack-Request-Id

header

UUID

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

POST
/v1/containers/{container_ident}/add_securtiy_group

Add security group for specified container

Add security group for specified container.

Response Codes

Success

Code

Reason

202 - Accepted

Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

security_group

query

string

Security groups to be added to the container.

Response

This request does not return anything in the response body.

Name

In

Type

Description

X-Openstack-Request-Id

header

UUID

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

POST
/v1/containers/{container_ident}/commit

Commit a container

Create a new image from a container’s changes.

Response Codes

Success

Code

Reason

202 - Accepted

Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

repository

query

string

The reposiroty of the container image.

tag

query

string

The tag of the container image.

Response

Name

In

Type

Description

image

body

string

The name or ID of the image.

Response Example

{
    "uuid": "64281d85-e9a3-4c54-8d30-9ee72a596d8a"
}
GET
/v1/containers/{container_ident}/attach

Attach to a container

Attach to a running container.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

Response

This request returns websocket url as a response, which is not in json format.

POST
/v1/containers/{container_ident}/network_detach

Detach a network from a container

Detach a network from a container.

Response Codes

Success

Code

Reason

202 - Accepted

Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

network (Optional)

query

string

The ID or name of the network to be attached to the container.

port (Optional)

query

string

The ID or name of the port for which you want to bind to the container. The network and port parameters are mutually exclusive. If you do not specify the port parameter, Zun will allocate a port and bind the port to the container.

Response

This request does not return anything in the response body.

Name

In

Type

Description

X-Openstack-Request-Id

header

UUID

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

POST
/v1/containers/{container_ident}/resize

Resize a container

Resize tty to a container

Warning

This API is primarily designed to be used by zunclient or Zun-UI. The point of this API is to coordinate between client-side tools and Zun to adjust the size of the TTY for the container. Unless you are writing client-side tools you should not be using this API.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This operation conflicted with another operation on this resource.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

width

query

string

The tty width of a container.

height

query

string

The tty height of a container.

Response

This request does not return anything in the response body.

Name

In

Type

Description

X-Openstack-Request-Id

header

UUID

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

POST
/v1/containers/{container_ident}/network_attach

Attach a network to a container

Attach a network to a container.

Response Codes

Success

Code

Reason

202 - Accepted

Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

network (Optional)

query

string

The ID or name of the network to be attached to the container.

port (Optional)

query

string

The ID or name of the port for which you want to bind to the container. The network and port parameters are mutually exclusive. If you do not specify the port parameter, Zun will allocate a port and bind the port to the container.

fixed_ip (Optional)

query

string

Fixed IP addresses. If you request a specific fixed IP address without a network, the request returns a Bad Request (400) response code.

Response

This request does not return anything in the response body.

Name

In

Type

Description

X-Openstack-Request-Id

header

UUID

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

POST
/v1/containers/{container_ident}/execute

Execute command in a running container

Execute command in a running container.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

command

query

string

The command to execute in a container.

run (Optional)

query

boolean

Whether to run the command or not. If this parameter is set to true, Zun will run the command right away. If this parameter is set to false, Zun won’t run the command but return the necessary information (i.e. the URL and execution id) for users to trigger the execution of the command.

interactive (Optional)

query

boolean

Keep STDIN open even if not attached, allocate a pseudo-TTY.

Response

Name

In

Type

Description

output (Optional)

body

dict

The output of the command executed in a container.

exit_code (Optional)

body

dict

The exit code of the command executed in a container.

exec_id (Optional)

body

dict

The ID of the exec instance.

url (Optional)

body

dict

The URL to start an exec instance.

Note

If the run parameter is set to true, the output will be {“output”: “…”, “exit_code”: “…”, “exec_id”: None, “url”: None}. Otherwise, the output will be {“output”: None, “exit_code”: None, “exec_id”: “…”, “url”: “…”}.

Response Example

{
    "output": "Mon Oct  9 09:09:32 UTC 2017\n",
    "exit_code": 0,
    "exec_id": null,
    "url": null
}
{
    "output": null,
    "exit_code": null,
    "url": "tcp://172.16.1.45:2375",
    "exec_id": "3c851c568fc9f21bdb77b7ba98eb1c6ae0c901f56dfb1471de4d6af7c73dbf4d"
}
POST
/v1/containers/{container_ident}/execute_resize

Resize tty when execute command in a container

Resize tty when execute command in a container.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

height

query

string

The tty height of a container.

exec_id

query

string

The ID of the exec instance.

width

query

string

The tty width of a container.

Response

Name

In

Type

Description

exec_resize_output (Optional)

body

array

The output of exec_resize, including exec_id and websocket url.

Response Example

{
    "exec_id": "c75e81815181bb22558306fffcaa7d049f4a79378ea70802ee6c4334d0597860",
    "url": "ws://0.0.0.0:6784/?token=062411f1-7995-413b-988f-ba8f6c553c6c&uuid=b7074d3a-14e4-4d5a-95cc-579fef16e033"
}
GET
/v1/containers/{container_ident}/logs

Get logs of a container

Get logs of a container.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

timestamps (Optional)

query

boolean

Whether to show timestamps in the logs of container.

tail (Optional)

query

string

Number of lines to show from the end of the logs, default is get all logs.

stderr (Optional)

query

boolean

Get standard error if True.

stdout (Optional)

query

boolean

Get standard output if True.

since (Optional)

query

string

Show logs since a given datetime or integer epoch (in seconds).

Request Example

{
    "timestamps": "True",
    "tail": "all",
    "since": "600000",
    "stderr": "True",
    "stdout": "True"
}

Response

This request returns logs string as a response, which is not in json format.

GET
/v1/containers/{container_ident}/top

Display the running processes in a container

Display the running processes in a container.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

ps_args (Optional)

query

string

The arguments of ps command.

Response

Name

In

Type

Description

ps_output

body

dict

The output of zun top.

Response Example

{
    "Processes": [
        ["root", "28363", "28344", "0", "Sep28", "pts/0", "00:00:00", "nginx: master process nginx -g daemon off;"],
        ["systemd+", "28436", "28363", "0", "Sep28", "pts/0", "00:00:00", "nginx: worker process"]
    ],
    "Titles": [
        "UID",
        "PID",
        "PPID",
        "C",
        "STIME",
        "TTY",
        "TIME",
        "CMD"
    ]
}
GET
/v1/containers/{container_ident}/network_list

List networks on a container

List networks on a container

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

Response

Name

In

Type

Description

net_id

body

string

The UUID of network.

subnet_id

body

string

The UUID of subnet.

port_id

body

string

The UUID of port of a container.

version

body

string

The version of the Internet Protocol.

ip_address

body

string

The IP address.

fixed_ips

body

string

A list of fixed IP addresses with subnet IDs and other detailed information.

Response Example

{
    "networks": [
        {
            "port_id": "5be06e49-70dc-4984-94a2-1b946bb136fb",
            "net_id": "7e6b5e1b-9b44-4f55-b4e3-16a1ead98161",
            "fixed_ips": {
                "ip_address": "30.30.30.10",
                "version": 4,
                "subnet_id": "ae8d7cce-859e-432f-8a33-d7d8834ccd14"
            }
        }
    ]
}
GET
/v1/containers/{container_ident}/container_actions

List Actions For Container

List actions for a container

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

Response

Name

In

Type

Description

action

body

string

The name of the action.

container_uuid

body

UUID

UUID of the resource.

message

body

string

The error message about this action when error occurred.

request_id

body

string

The request id generated when execute the API of this action.

start_time

body

string

The date and time when the action was started. The date and time stamp format is ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

project_id

body

string

The UUID of the project that this container belongs to.

user_id

body

string

The user ID of the user who owns the container.

Example List Actions For Container: JSON response

{
    "containerActions": [
        {
            "action": "create",
            "container_uuid": "b48316c5-71e8-45e4-9884-6c78055b9b13",
            "message": null,
            "project_id": "853719b303ef4858a195535eb520e58d",
            "request_id": "req-25517360-b757-47d3-be45-0e8d2a01b36a",
            "start_time": "2018-03-04T19:48:49.000000",
            "finish_time": "2018-03-04T19:48:55.000000",
            "user_id": "22e81669093742b7a74b1d715a9a5813"
        },
        {
            "action": "stop",
            "container_uuid": "b48316c5-71e8-45e4-9884-6c78055b9b13",
            "message": null,
            "project_id": "853719b303ef4858a195535eb520e58d",
            "request_id": "req-3293a3f1-b44c-4609-b8d2-d81b105636b8",
            "start_time": "2018-03-04T17:02:54.000000",
            "finish_time": "2018-03-04T17:02:58.000000",
            "user_id": "22e81669093742b7a74b1d715a9a5813"
        }
    ]
}
GET
/v1/containers/{container_ident}/container_actions/{request_ident}

Show Container Action Details

Show details for a container action.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

container_ident

path

string

The UUID or name of container in Zun.

request_ident

path

string

The ID of the request.

Response

Name

In

Type

Description

action

body

string

The name of the action.

container_uuid

body

UUID

UUID of the resource.

message

body

string

The error message about this action when error occurred.

project_id

body

string

The UUID of the project that this container belongs to.

request_id

body

string

The request id generated when execute the API of this action.

start_time

body

string

The date and time when the action was started. The date and time stamp format is ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

user_id

body

string

The user ID of the user who owns the container.

events

body

array

The events occurred in this action.

events.event

body

string

The name of the event.

events.start_time

body

string

The date and time when the event was started. The date and time stamp format is ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

events.finish_time

body

string

The date and time when the event was finished. The date and time stamp format is ISO 8601

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

events.result

body

string

The result of the event.

events.traceback

body

string

The traceback stack if error occurred in this event.

Example Show Container Action Details: JSON response

{
    "action": "create",
    "events": [
        {
          "event": "container__do_container_start",
          "finish_time": "2018-03-04T17:03:07.000000",
          "result": "Success",
          "start_time": "2018-03-04T17:02:57.000000",
          "traceback": null
        }
    ],
    "container_uuid": "b48316c5-71e8-45e4-9884-6c78055b9b13",
    "message": null,
    "project_id": "853719b303ef4858a195535eb520e58d",
    "request_id": "req-3293a3f1-b44c-4609-b8d2-d81b105636b8",
    "start_time": "2018-03-04T17:02:54.000000",
    "finish_time": "2018-03-04T17:02:57.000000",
    "user_id": "22e81669093742b7a74b1d715a9a5813"
}

Manage Zun service

GET
/v1/services

Show service status

Enables administrative users to view details for all Zun services.

Service status details include service id, binary, host, report count, creation time, last updated time, health status, and the reason for disabling service.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Response Parameters

Name

In

Type

Description

X-Openstack-Request-Id

header

UUID

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

services

body

array

A list of Zun services.

binary

body

string

The name of the binary form of the Zun service.

availability_zone

body

string

The availability zone of the Zun service.

created_at

body

string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

state

body

string

The current state of Zun services.

report_count

body

integer

The total number of report.

updated_at

body

string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

host

body

string

The host for the service.

disabled_reason

body

string

The disable reason of the service, null if the service is enabled or disabled without reason provided.

id

body

string

The ID of the Zun service.

Response Example

{
    "services":[
        {
            "binary": "zun-compute",
            "availability_zone": "nova",
            "state": "up",
            "created_at": "2017-02-01T03:25:07.000000",
            "updated_at": "2017-02-01T06:13:07.000000",
            "report_count": 166,
            "disabled": false,
            "host": "instance-1",
            "forced_down": false,
            "last_seen_up": "2017-02-01T06:13:07.000000",
            "disabled_reason": null,
            "id": 1
        }
    ]
}
DELETE
/v1/services

Delete service

Delete the specified Zun service.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request Parameters

Name

In

Type

Description

binary

body

string

The name of the binary form of the Zun service.

host

body

string

The host for the service.

Response Parameters

If successful, this method does not return content in the response body.

PUT
/v1/services/enable

Enable service

Enable the specified Zun service.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request Parameters

Name

In

Type

Description

binary

body

string

The name of the binary form of the Zun service.

host

body

string

The host for the service.

Response Parameters

Name

In

Type

Description

service

body

dict

A Zun service.

host

body

string

The host for the service.

binary

body

string

The name of the binary form of the Zun service.

disabled

body

boolean

Whether or not this service is disabled or not.

disabled_reason

body

string

The disable reason of the service, null if the service is enabled or disabled without reason provided.

Response Example

{
    "service":{
        "disabled": false,
         "binary": "zun-compute",
         "host": "tecs",
         "disabled_reason": null
    }
}
PUT
/v1/services/disable

Disable service

Disable the specified Zun service.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request Parameters

Name

In

Type

Description

binary

body

string

The name of the binary form of the Zun service.

host

body

string

The host for the service.

disabled_reason

body

string

The disable reason of the service, null if the service is enabled or disabled without reason provided.

Response Parameters

Name

In

Type

Description

service

body

dict

A Zun service.

host

body

string

The host for the service.

binary

body

string

The name of the binary form of the Zun service.

disabled

body

boolean

Whether or not this service is disabled or not.

disabled_reason

body

string

The disable reason of the service, null if the service is enabled or disabled without reason provided.

Response Example

{
    "service": {
        "disabled": true,
        "binary": "zun-compute",
        "host": "host1",
        "disabled_reason": "abc"
    }
}
PUT
/v1/services/force_down

Force down service

Force the specified Zun service to down or unset it.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request Parameters

Name

In

Type

Description

binary

body

string

The name of the binary form of the Zun service.

host

body

string

The host for the service.

forced_down

body

boolean

Whether or not this service was forced down manually by an administrator. This value is useful to know that some 3rd party has verified the service should be marked down.

Response Parameters

Name

In

Type

Description

service

body

dict

A Zun service.

host

body

string

The host for the service.

binary

body

string

The name of the binary form of the Zun service.

forced_down

body

boolean

Whether or not this service was forced down manually by an administrator. This value is useful to know that some 3rd party has verified the service should be marked down.

Response Example

{
    "service": {
        "binary": "zun-compute",
        "host": "tecs",
        "forced_down": true
    }
}

Manage zun host

GET
/v1/hosts

List all compute hosts

Enables administrative users to list all Zun container hosts.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Response Parameters

Name

In

Type

Description

X-Openstack-Request-Id

header

UUID

A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

hosts

body

array

The host information list, including hostname, uuid, links, labels, cpus, mem_total and os.

architecture

body

string

The architecture of the host operating system.

cpus

body

string

The total cpus of the host.

cpu_used

body

string

The used cpus of the host.

disk_used

body

string

The amount of used disk of the host.

disk_total

body

string

The total amount of disk of the host.

hostname

body

string

The hostname.

kernel_version

body

string

The kernel version of the host.

labels

body

string

The labels of the local container engine (i.e. Docker daemon).

mem_used

body

string

The amount of used memory of the host.

mem_total

body

string

The total amount of memory of the host.

os

body

string

The name of host operating system.

os_type

body

string

The type of host operating system.

total_containers

body

string

The total number of containers in the host.

uuid

body

string

The UUID of the host.

enable_cpu_pinning

body

object

Indicate whether this host has cpu pinning enabled.

Response Example

{
    "hosts": [
        {
            "hostname": "testhost",
            "uuid": "d0405f06-101e-4340-8735-d1bf9fa8b8ad",
            "links": [{
                "href": "http://192.168.2.200:9517/v1/hosts/d0405f06-101e-4340-8735-d1bf9fa8b8ad",
                "rel": "self"
                },
                {"href": "http://192.168.2.200:9517/hosts/d0405f06-101e-4340-8735-d1bf9fa8b8ad",
                 "rel": "bookmark"
                }
            ],
            "kernel_version": "4.4.0-109-generic",
            "labels": {
                "type": "test"
            },
            "cpus": 48,
            "mem_used": 512,
            "disk_total": 16,
            "mem_total": 128446,
            "total_containers": 2,
            "cpu_used": 0.2,
            "disk_used": 10,
            "os_type": "linux",
            "architecture": "x86_64"
            "os": "CentOS Linux 7 (Core)"
        }
   ],
   "next": null
}
GET
/v1/hosts/{host_ident}

Show details of a host

Get all information of a host in Zun.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

Request

Name

In

Type

Description

host_ident

path

string

The UUID or name of host in Zun.

Response

Name

In

Type

Description

architecture

body

string

The architecture of the host operating system.

cpus

body

string

The total cpus of the host.

cpu_used

body

string

The used cpus of the host.

disk_used

body

string

The amount of used disk of the host.

disk_total

body

string

The total amount of disk of the host.

hostname

body

string

The hostname.

kernel_version

body

string

The kernel version of the host.

labels

body

string

The labels of the local container engine (i.e. Docker daemon).

mem_used

body

string

The amount of used memory of the host.

mem_total

body

string

The total amount of memory of the host.

os

body

string

The name of host operating system.

os_type

body

string

The type of host operating system.

total_containers

body

string

The total number of containers in the host.

uuid

body

string

The UUID of the host.

enable_cpu_pinning

body

object

Indicate whether this host has cpu pinning enabled.

Response Example

{
    "hostname": "test",
    "uuid": "d0405f06-101e-4340-8735-d1bf9fa8b8ad",
    "links": [{
        "href": "http://192.168.2.22:9517/v1/hosts/d0405f06-101e-4340-8735-d1bf9fa8b8ad",
        "rel": "self"
        },
        {"href": "http://192.168.2.22:9517/hosts/d0405f06-101e-4340-8735-d1bf9fa8b8ad",
         "rel": "bookmark"}
    ],
    "kernel_version": "3.10.0-123.el7.x86_64",
    "labels": {"type": "test"},
    "cpus": 48,
    "mem_used": 512,
    "disk_total": 16,
    "mem_total": 128446,
    "total_containers": 2,
    "cpu_used": 0.2,
    "disk_used": 10,
    "os_type": "linux",
    "architecture": "x86_64"
    "os": "CentOS Linux 7 (Core)"
}

Manage Quotas

Gets, updates, gets default and deletes quotas for a project.

PUT
/v1/quotas/{project_id}

Update quotas for a project

Update the quotas for a project

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id

path

string

The UUID of project in a multi-project cloud.

containers (Optional)

body

int

The number of containers

memory (Optional)

body

integer

The container memory size in MiB.

cpu (Optional)

body

float

The number of virtual cpus.

disk (Optional)

body

int

The number of gigabytes of container disk

Request Example

{
    "disk": 200,
    "cpu": 30,
    "containers": 80,
    "memory": 102400
}

Response

Name

In

Type

Description

containers

body

object

The object of detailed containers quota, including in_use, limit of number of instances.

memory

body

object

The object of detailed memory quota, including in_use, limit number of memory.

cpu

body

object

The object of detailed cpu set quota, including in_use, limit of number of cpu set.

disk

body

object

The object of detailed disk quota, including in_use, limit of disk.

Response Example

{
    "disk": 200,
    "cpu": 30,
    "containers": 80,
    "memory": 102400
}
GET
/v1/quotas/{project_id}

Get quotas for a project

Get quotas for a project

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id

path

string

The UUID of project in a multi-project cloud.

Response

Name

In

Type

Description

usages (Optional)

query

boolean

Whether to show in_use in the quotas

containers

body

object

The object of detailed containers quota, including in_use, limit of number of instances.

memory

body

object

The object of detailed memory quota, including in_use, limit number of memory.

cpu

body

object

The object of detailed cpu set quota, including in_use, limit of number of cpu set.

disk

body

object

The object of detailed disk quota, including in_use, limit of disk.

Response Example

{
    "disk": {
        "limit": 100,
        "in_use": 0
    },
    "cpu": {
        "limit": 20,
        "in_use": 4
    },
    "containers": {
        "limit": 40,
        "in_use": 5
    },
    "memory": {
        "limit": 51200,
        "in_use": 2048
    }
}
GET
/v1/quotas/{project_id}/defaults

Get Default quotas for a project

Get the default quotas for a project

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id

path

string

The UUID of project in a multi-project cloud.

Response

Name

In

Type

Description

usages (Optional)

query

boolean

Whether to show in_use in the quotas

containers

body

object

The object of detailed containers quota, including in_use, limit of number of instances.

memory

body

object

The object of detailed memory quota, including in_use, limit number of memory.

cpu

body

object

The object of detailed cpu set quota, including in_use, limit of number of cpu set.

disk

body

object

The object of detailed disk quota, including in_use, limit of disk.

Response Example

{
    "disk": 100,
    "cpu": 20,
    "containers": 40,
    "memory": 51200
}
DELETE
/v1/quotas/{project_id}

Revert Quotas to defaults

Reverts the quotas to default values for a project

Success

Code

Reason

202 - Accepted

Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

project_id

path

string

The UUID of project in a multi-project cloud.

Response

There is no body content for the response of a successful DELETE operation.

Manage Quota Classes

Get, updates quota classes

PUT
/v1/quota_classes/{quota_class_name}

Create or Update Quotas for Quota Class

Update the quotas for the Quota Class. If the requested Quota Class is not found in the DB, then the API will create the one.

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

quota_class_name

path

string

The name of quota class

containers (Optional)

body

int

The number of containers

memory (Optional)

body

integer

The container memory size in MiB.

cpu (Optional)

body

float

The number of virtual cpus.

disk (Optional)

body

int

The number of gigabytes of container disk

Request Example

{
    "disk": 200,
    "cpu": 30,
    "containers": 50,
    "memory": 102400
}

Response

Name

In

Type

Description

containers

body

object

The object of detailed containers quota, including in_use, limit of number of instances.

memory

body

object

The object of detailed memory quota, including in_use, limit number of memory.

cpu

body

object

The object of detailed cpu set quota, including in_use, limit of number of cpu set.

disk

body

object

The object of detailed disk quota, including in_use, limit of disk.

Response Example

{
    "disk": 200,
    "cpu": 30,
    "containers": 50,
    "memory": 102400
}
GET
/v1/quota_classes/{quota_class_name}

List quotas for Quota Class

List quotas for Quota Class

Response Codes

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

User must authenticate before making a request.

403 - Forbidden

Policy does not allow current user to do this operation.

Request

Name

In

Type

Description

quota_class_name

path

string

The name of quota class

Response

Name

In

Type

Description

containers

body

object

The object of detailed containers quota, including in_use, limit of number of instances.

memory

body

object

The object of detailed memory quota, including in_use, limit number of memory.

cpu

body

object

The object of detailed cpu set quota, including in_use, limit of number of cpu set.

disk

body

object

The object of detailed disk quota, including in_use, limit of disk.

Response Example

{
    "disk": 100,
    "cpu": 20,
    "containers": 40,
    "memory": 51200
}