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, resize, stops, pauses, unpauses, restarts, renames, commits containers, and adds security group for specified 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 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

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.

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 body 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
}
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 (Optional) body 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 (Optional) body string The reposiroty of the container image.
tag body string The tag of the container image.

Response

Name In Type Description
image body string The name or ID of the image.
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.

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