Container Management Service API

Container Management 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 container management 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 container management 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 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.

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 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.
image_pull_policy (Optional) body string The policy which determines if the image should be pulled prior to starting the container. Allowed values are ifnotpresent that means pull the image if it does not already exist on the node, always means always pull the image from repository and never mean never pull the image.
labels (Optional) body array Adds a map of labels to a container.
environment (Optional) body array The environment variables.
restart_policy (Optional) body string Restart policy to apply when a container exits. Allowed values are no, on-failure[:max-retry], always, unless-stopped.
interactive (Optional) body boolean Keep STDIN open even if not attached, allocate a pseudo-TTY.
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.

The special values auto and can be specified for networks. auto tells the Containers service to use a network that is available to the project, if one exists. If one does not exist, the Containers service will attempt to automatically allocate a network for the project (if possible). none tells the Containers service to not allocate a network for the instance. The auto and none values cannot be used with any other network values, including other network uuids, ports, fixed IPs or device tags. These are requested as strings for the networks value, not in a list.

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.

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",
    "image_pull_policy": "always",
    "restart_policy":{
      "Name": "no",
      "MaximumRetryCount": 0
    },
    "interactive": "False",
    "image_driver": "docker",
    "security_groups": null,
    "nets": [
        {
            "v4-fixed-ip": "",
            "network": "",
            "v6-fixed-ip": "",
            "port": "890699a9-4690-4bd6-8b70-3a9c1be77ecb"
        }
    ],
    "runtime": "runc",
    "hostname": "testhost",
    "auto_remove": "False"
}

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 (Optional) body array Adds a map of labels to a container.
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.
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.
image_pull_policy (Optional) body string The policy which determines if the image should be pulled prior to starting the container. Allowed values are ifnotpresent that means pull the image if it does not already exist on the node, always means always pull the image from repository and never mean never pull the image.
environment (Optional) body array The environment variables.
restart_policy (Optional) body string Restart policy to apply when a container exits. Allowed values are no, on-failure[:max-retry], always, unless-stopped.
interactive (Optional) body boolean Keep STDIN open even if not attached, allocate a pseudo-TTY.
uuid body UUID UUID of the resource.
hostname (Optional) 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 (Optional) body boolean enable auto-removal of the container on daemon side when the container’s process exits.

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": null,
     "image_pull_policy": "always",
     "uuid": "b0694d40-70af-4488-b104-10f66b593347",
     "hostname": null,
     "environment": {
         "foo": "bar"
     },
     "memory": "500M",
     "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,
     "runtime": "runc",
     "hostname": "testhost",
     "auto_remove": "False"
}
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.

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 (Optional) body array Adds a map of labels to a container.
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.
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.
image_pull_policy (Optional) body string The policy which determines if the image should be pulled prior to starting the container. Allowed values are ifnotpresent that means pull the image if it does not already exist on the node, always means always pull the image from repository and never mean never pull the image.
environment (Optional) body array The environment variables.
restart_policy (Optional) body string Restart policy to apply when a container exits. Allowed values are no, on-failure[:max-retry], always, unless-stopped.
interactive (Optional) body boolean Keep STDIN open even if not attached, allocate a pseudo-TTY.
uuid body UUID UUID of the resource.
hostname (Optional) 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.

Response Example

{
    "containers": [
        {
            "addresses": {
                "2ede1821-1334-4e8b-b731-d3a82b41f42f": [{
                    "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": [],
            "image_pull_policy": "always",
            "uuid": "b0694d40-70af-4488-b104-10f66b593347",
            "hostname": "zun-sandbox-5812822d-6794-4839-85c0-1c01665c0d48",
            "environment": {
                "foo": "bar"
            },
            "memory": "500M",
            "status": "Stopped",
            "workdir": "/home/ubuntu",
            "status_detail": "Exited(0) 10 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
        }
    ],
    "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 (Optional) body array Adds a map of labels to a container.
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.
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.
image_pull_policy (Optional) body string The policy which determines if the image should be pulled prior to starting the container. Allowed values are ifnotpresent that means pull the image if it does not already exist on the node, always means always pull the image from repository and never mean never pull the image.
environment (Optional) body array The environment variables.
restart_policy (Optional) body string Restart policy to apply when a container exits. Allowed values are no, on-failure[:max-retry], always, unless-stopped.
interactive (Optional) body boolean Keep STDIN open even if not attached, allocate a pseudo-TTY.
uuid body UUID UUID of the resource.
hostname (Optional) 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.

Response Example

{
    "addresses": {
        "c0c5f8ed-6654-4d25-b0de-c858b9f620be": [{
            "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": [],
     "image_pull_policy": "always",
     "uuid": "b0694d40-70af-4488-b104-10f66b593347",
     "hostname": "zun-sandbox-5812822d-6794-4839-85c0-1c01665c0d48",
     "environment": {
         "foo": "bar"
     },
     "memory": "500M",
     "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",
     "restart_policy": {
         "MaximumRetryCount": "0",
         "Name": "no"
     },
     "ports": [],
     "command": "/bin/sh -c 'echo hello'",
     "cpu": 2.0,
     "interactive": false
}
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?signal={signal}

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 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 (Optional) body integer The container memory size in MiB.
cpu (Optional) body float The number of virtual cpus.

Request Example

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

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 (Optional) body array Adds a map of labels to a container.
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.
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.
image_pull_policy (Optional) body string The policy which determines if the image should be pulled prior to starting the container. Allowed values are ifnotpresent that means pull the image if it does not already exist on the node, always means always pull the image from repository and never mean never pull the image.
environment (Optional) body array The environment variables.
restart_policy (Optional) body string Restart policy to apply when a container exits. Allowed values are no, on-failure[:max-retry], always, unless-stopped.
interactive (Optional) body boolean Keep STDIN open even if not attached, allocate a pseudo-TTY.
uuid body UUID UUID of the resource.
hostname (Optional) 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.

Response Example

{
    "addresses": {
        "eb7a3ee0-ad55-417b-ba11-6c57b1dbd4c6": [{
            "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": [],
     "image_pull_policy": "always",
     "uuid": "b0694d40-70af-4488-b104-10f66b593347",
     "hostname": "zun-sandbox-5812822d-6794-4839-85c0-1c01665c0d48",
     "environment": {
         "foo": "bar"
     },
     "memory": "200M",
     "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",
     "restart_policy": {
         "MaximumRetryCount": "0",
         "Name": "no"
     },
     "ports": [],
     "command": "/bin/sh -c 'echo hello'",
     "cpu": 3.0,
     "interactive": false
}
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?timeout={timeout}

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}/reboot?timeout={timeout}

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?name={new_name}

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 (Optional) body array Adds a map of labels to a container.
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.
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.
image_pull_policy (Optional) body string The policy which determines if the image should be pulled prior to starting the container. Allowed values are ifnotpresent that means pull the image if it does not already exist on the node, always means always pull the image from repository and never mean never pull the image.
environment (Optional) body array The environment variables.
restart_policy (Optional) body string Restart policy to apply when a container exits. Allowed values are no, on-failure[:max-retry], always, unless-stopped.
interactive (Optional) body boolean Keep STDIN open even if not attached, allocate a pseudo-TTY.
uuid body UUID UUID of the resource.
hostname (Optional) 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.

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": [],
     "image_pull_policy": "always",
     "uuid": "b0694d40-70af-4488-b104-10f66b593347",
     "hostname": "zun-sandbox-5812822d-6794-4839-85c0-1c01665c0d48",
     "environment": {
         "foo": "bar"
     },
     "memory": "500M",
     "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,
     "interactive": false
}
GET
/v1/containers/{container_ident}/get_archive?path={source_path}

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?path={destination_path}

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?name={security_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?tag={tag}&repository={repository}

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
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.

Response

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

POST
/v1/containers/{container_ident}/network_detach?network={network}

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.
Name In Type Description
container_ident path string The UUID or name of container in Zun.
network query string Network to be detached of 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?w={width}&h={height}

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?network={network}

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.
Name In Type Description
container_ident path string The UUID or name of container in Zun.
network query string Network to be detached of 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}/execute?command={command}&run={run}&interactive={interactive}

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
exec_output (Optional) body dict The output of the command executed in a container.
exec_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.
exec_url (Optional) body dict The URL to start an exec instance.

Note

There are two possible responses. If the run parameter is set to true, the output will be {“output”: “…”, “exit_code”: “…”}. Otherwise, the output will be {“exec_id”: “…”, “url”: “…”}.

Response Example

{
    "output": "Mon Oct  9 09:09:32 UTC 2017\n",
    "exit_code": 0
}
{
    "url": "tcp://172.16.1.45:2375",
    "exec_id": "3c851c568fc9f21bdb77b7ba98eb1c6ae0c901f56dfb1471de4d6af7c73dbf4d"
}
POST
/v1/containers/{container_ident}/execute_resize?h={height}&&exec_id={exec_id}&w={width}

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?timestamps={timestamps}&&since={since}&tail={tail}&stderr={stderr}&stdout={stdout}

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?ps_args={ps_args}

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"
    ]
}

Manage Zun service

GET
/v1/services

Show container management service status

Enables administrative users to view details for all Zun services.

Container management 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.

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.
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",
        "state":"up",
        "created_at":"2017-02-01 03:25:07+00:00",
        "updated_at":"2017-02-01 06:13:07+00:00",
        "report_count":166,
        "disabled":false,
        "host":"instance-1",
        "forced_down":false,
        "last_seen_up":"2017-02-01 06:13:07+00:00",
        "disabled_reason":null,
        "id": 1
      }
    ]
}
DELETE
/v1/services

Delete container management 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.

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 container management 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.

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 container management 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.

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 container management 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.

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.

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"
                }
           ],
           "labels": {
               "type": "test"
           },
           "cpus": 48,
           "mem_total": 128446,
           "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
uuid body UUID UUID of the resource.
hostname (Optional) body string The hostname of container.

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_total": 128446,
    "total_containers": 3,
    "os_type": "linux",
    "os": "CentOS Linux 7 (Core)",
    "architecture": "x86_64"
}
Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.