API REF docs formatting improvements

[lpiwowar]

1. (non-blocking) They contain ¶ symbols.
2. (non-blocking) They are missing any sense of hierarchy. There is no indication for headers and so on. I'm wondering why we do not convert to rst or md:

pandoc -f html -t plain --wrap=preserve "$html_file" -o "$text_file" || {
                        echo "ERROR: Failed to convert $html_file"
                        return 1
                    }

Originally posted by @lpiwowar in #83 (review)

[lpiwowar]

ojoshi@ojoshi-mac rag-content % podman run --rm -it local-api-proof-pandoc:latest /bin/bash
(app-root) ls
openstack-docs-plaintext  scripts
(app-root) cd openstack-docs-plaintext
(app-root) ls
adjutant  heat	magnum	masakari  neutron-lib  nova  zaqar  zun
(app-root) cd zun
(app-root) ls
2025.2_api-ref	2025.2_docs
(app-root) cd 2025.2_api-ref
(app-root) ls
index.txt
(app-root) cat index.txt
[]

Toggle navigation

Search

-   

-   Software
    -   Overview
    -   OpenStack Components
    -   SDKs
    -   Deployment Tools
    -   OpenStack Map
    -   Sample Configs

-   Use Cases
    -   Users in Production

    -   

        ------------------------------------------------------------------------

    -   Ironic Bare Metal

    -   Edge Computing

    -   Telecom & NFV

    -   Science and HPC

    -   Containers

    -   Enterprise

    -   User Survey

-   Events
    -   OpenInfra Summit
    -   Project Teams Gathering
    -   OpenDev
    -   Community Events
    -   OpenStack & OpenInfra Days
    -   Summit Videos

-   Community
    -   Welcome! Start Here

    -   OpenStack Technical Committee

    -   Speakers Bureau

    -   OpenStack Wiki

    -   Get Certified (COA)

    -   Jobs

    -   Marketing Resources

    -   Community News

    -   Superuser Magazine

    -   

        ------------------------------------------------------------------------

    -   OpenInfra Foundation Supporting Organizations

    -   OpenInfra Foundation

-   Marketplace
    -   Training
    -   Distros & Appliances
    -   Public Clouds
    -   Hosted Private Clouds
    -   Remotely Managed Private Clouds
    -   Consulting & Integrators
    -   Drivers

-   Blog

-   Docs

-   Join
    -   Sign up for Foundation Membership
    -   Sponsor the Foundation
    -   More about the Foundation

-   Log In

Containers Service API

Containers Service API¶

Show All

Zun Base URLs¶

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

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

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

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

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

Manage Capsules (Pods)¶

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

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

POST

/v1/capsules/

Create new capsule

detail

Create new capsule.

Response Codes¶

Success¶

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

Error¶

  Code                 Reason
  -------------------- ----------------------------------------------------------
  400 - Bad Request    Some content in the request was invalid.
  401 - Unauthorized   User must authenticate before making a request.
  403 - Forbidden      Policy does not allow current user to do this operation.

Request¶

Capsule Template¶

+-----------------+-----------------+-----------------+-----------------+
| Name            | In              | Type            | Description     |
+=================+=================+=================+=================+
| template        | body            | object          | A template for  |
|                 |                 |                 | capsule.        |
+-----------------+-----------------+-----------------+-----------------+
| kind            | body            | string          | A string value  |
|                 |                 |                 | representing    |
|                 |                 |                 | the type of     |
|                 |                 |                 | this object.    |
|                 |                 |                 | Its value is    |
|                 |                 |                 | capsule.        |
+-----------------+-----------------+-----------------+-----------------+
| metadata        | body            | object          | Capsule         |
| (Optional)      |                 |                 | metadata in     |
|                 |                 |                 | key-value       |
|                 |                 |                 | format.         |
|                 |                 |                 | Keys can be     |
|                 |                 |                 | name, labels    |
|                 |                 |                 | and             |
|                 |                 |                 | annotations.    |
|                 |                 |                 | An example      |
|                 |                 |                 | format would    |
|                 |                 |                 | look as         |
|                 |                 |                 | follows:        |
|                 |                 |                 |                 |
|                 |                 |                 |                 |
|                 |                 |                 |   "metadata": { |
|                 |                 |                 |                 |
|                 |                 |                 |      "labels":  |
|                 |                 |                 | {"app": "web"}, |
|                 |                 |                 |                 |
|                 |                 |                 | "name": "demo", |
|                 |                 |                 |           "an   |
|                 |                 |                 | notations": {"k |
|                 |                 |                 | ey1": "value1"} |
|                 |                 |                 |       }         |
+-----------------+-----------------+-----------------+-----------------+
| metadata.labels | body            | object          | The labels      |
| (Optional)      |                 |                 | added to the    |
|                 |                 |                 | capsule.        |
+-----------------+-----------------+-----------------+-----------------+
| metadata.name   | body            | string          | The name of the |
| (Optional)      |                 |                 | capsule.        |
+-----------------+-----------------+-----------------+-----------------+
| metad           | body            | object          | The annotations |
| ata.annotations |                 |                 | added to the    |
| (Optional)      |                 |                 | capsule.        |
|                 |                 |                 | Annotations is  |
|                 |                 |                 | an unstructured |
|                 |                 |                 | key value map   |
|                 |                 |                 | stored with a   |
|                 |                 |                 | resource        |
|                 |                 |                 | that may be set |
|                 |                 |                 | by external     |
|                 |                 |                 | tools to store  |
|                 |                 |                 | and retrieve    |
|                 |                 |                 | arbitrary       |
|                 |                 |                 | metadata.       |
+-----------------+-----------------+-----------------+-----------------+
| spec            | body            | object          | Specification   |
|                 |                 |                 | of the desired  |
|                 |                 |                 | behavior of the |
|                 |                 |                 | capsule.        |
|                 |                 |                 | See Capsule     |
|                 |                 |                 | Spec.           |
+-----------------+-----------------+-----------------+-----------------+

Capsule Spec¶

  Name                        In     Type     Description
  --------------------------- ------ -------- -------------------------------------------------------
  containers                  body   array    A list of containers objects.
  initContainers (Optional)   body   array    A list of init containers objects.
  restartPolicy (Optional)    body   string   Restart policy for all containers within the capsule.
                                              Its value can be Always, OnFailure, or Never.
  volumes (Optional)          body   array    List of volumes that can be mounted by
                                              containers in this capsule.

Capsule Container¶

+-----------------+-----------------+-----------------+-----------------+
| Name            | In              | Type            | Description     |
+=================+=================+=================+=================+
| image           | body            | string          | The name or ID  |
|                 |                 |                 | of the image.   |
+-----------------+-----------------+-----------------+-----------------+
| command         | body            | array           | The command of  |
| (Optional)      |                 |                 | the container.  |
+-----------------+-----------------+-----------------+-----------------+
| args (Optional) | body            | array           | The arguments   |
|                 |                 |                 | to the command. |
+-----------------+-----------------+-----------------+-----------------+
| env (Optional)  | body            | object          | The environment |
|                 |                 |                 | variables to    |
|                 |                 |                 | set in the      |
|                 |                 |                 | container.      |
+-----------------+-----------------+-----------------+-----------------+
| name (Optional) | body            | string          | The name of the |
|                 |                 |                 | container.      |
+-----------------+-----------------+-----------------+-----------------+
| ports           | body            | array           | List of ports   |
| (Optional)      |                 |                 | to expose from  |
|                 |                 |                 | the container.  |
|                 |                 |                 | Each item is a  |
|                 |                 |                 | dictionary must |
|                 |                 |                 | contain a       |
|                 |                 |                 | containerPort   |
|                 |                 |                 | key.            |
|                 |                 |                 | Optionally, it  |
|                 |                 |                 | can contain a   |
|                 |                 |                 | protocol key.   |
|                 |                 |                 | An example      |
|                 |                 |                 | format would    |
|                 |                 |                 | look as         |
|                 |                 |                 | follows:        |
|                 |                 |                 |                 |
|                 |                 |                 |                 |
|                 |                 |                 |     "ports": [{ |
|                 |                 |                 |           "pr   |
|                 |                 |                 | otocol": "TCP", |
|                 |                 |                 |           "con  |
|                 |                 |                 | tainerPort": 80 |
|                 |                 |                 |       }]        |
+-----------------+-----------------+-----------------+-----------------+
| port            | body            | integer         | The port to     |
| s.containerPort |                 |                 | open in         |
| (Optional)      |                 |                 | container.      |
|                 |                 |                 | Its value must  |
|                 |                 |                 | be a number     |
|                 |                 |                 | between 1 and   |
|                 |                 |                 | 65535.          |
+-----------------+-----------------+-----------------+-----------------+
| ports.protocol  | body            | string          | The protocol.   |
| (Optional)      |                 |                 | Its value can   |
|                 |                 |                 | be TCP or UDP.  |
|                 |                 |                 | Default is TCP. |
+-----------------+-----------------+-----------------+-----------------+
| resources       | body            | object          | Compute         |
| (Optional)      |                 |                 | Resources       |
|                 |                 |                 | required by     |
|                 |                 |                 | this container. |
|                 |                 |                 | Supported       |
|                 |                 |                 | compute         |
|                 |                 |                 | resources are   |
|                 |                 |                 | cpu and memory. |
|                 |                 |                 | An example      |
|                 |                 |                 | format would    |
|                 |                 |                 | look as         |
|                 |                 |                 | follows:        |
|                 |                 |                 |                 |
|                 |                 |                 |                 |
|                 |                 |                 |  "resources": { |
|                 |                 |                 |                 |
|                 |                 |                 |   "requests": { |
|                 |                 |                 |                 |
|                 |                 |                 |     "cpu": 0.1, |
|                 |                 |                 |                 |
|                 |                 |                 |   "memory": 128 |
|                 |                 |                 |       }}        |
+-----------------+-----------------+-----------------+-----------------+
| resources.cpu   | body            | float           | The number of   |
| (Optional)      |                 |                 | virtual CPU.    |
+-----------------+-----------------+-----------------+-----------------+
| r               | body            | integer         | The amount of   |
| esources.memory |                 |                 | memory in MiB.  |
| (Optional)      |                 |                 |                 |
+-----------------+-----------------+-----------------+-----------------+
| volumeMounts    | body            | array           | List of volumes |
| (Optional)      |                 |                 | to mount into   |
|                 |                 |                 | the container’s |
|                 |                 |                 | filesystem.     |
|                 |                 |                 | Each item must  |
|                 |                 |                 | contain a name  |
|                 |                 |                 | key and a       |
|                 |                 |                 | mountPath key.  |
|                 |                 |                 | An example      |
|                 |                 |                 | format would    |
|                 |                 |                 | look as         |
|                 |                 |                 | follows:        |
|                 |                 |                 |                 |
|                 |                 |                 |       "vo       |
|                 |                 |                 | lumeMounts": [{ |
|                 |                 |                 |                 |
|                 |                 |                 |      "mountPath |
|                 |                 |                 | ": "/work-dir", |
|                 |                 |                 |           "n    |
|                 |                 |                 | ame": "workdir" |
|                 |                 |                 |       }]        |
+-----------------+-----------------+-----------------+-----------------+
| vo              | body            | string          | The name of the |
| lumeMounts.name |                 |                 | volume          |
| (Optional)      |                 |                 |                 |
+-----------------+-----------------+-----------------+-----------------+
| volumeM         | body            | string          | The path within |
| ounts.mountPath |                 |                 | the container   |
| (Optional)      |                 |                 | at which the    |
|                 |                 |                 | volume should   |
|                 |                 |                 | be mounted.     |
+-----------------+-----------------+-----------------+-----------------+
| workDir         | body            | string          | The working     |
| (Optional)      |                 |                 | directory for   |
|                 |                 |                 | commands to run |
|                 |                 |                 | in.             |
+-----------------+-----------------+-----------------+-----------------+

Capsule Volume¶

+-----------------+-----------------+-----------------+-----------------+
| Name            | In              | Type            | Description     |
+=================+=================+=================+=================+
| name            | body            | string          | The name of the |
|                 |                 |                 | volume.         |
+-----------------+-----------------+-----------------+-----------------+
| cinder          | body            | object          | The Cinder      |
|                 |                 |                 | volume          |
|                 |                 |                 | configuration.  |
|                 |                 |                 | There are two   |
|                 |                 |                 | options to      |
|                 |                 |                 | configure the   |
|                 |                 |                 | volume: use an  |
|                 |                 |                 | existing volume |
|                 |                 |                 | or dynamically  |
|                 |                 |                 | create one.     |
|                 |                 |                 | To specify an   |
|                 |                 |                 | existing        |
|                 |                 |                 | volume, set the |
|                 |                 |                 | volumeID key    |
|                 |                 |                 | with            |
|                 |                 |                 | the UUID of the |
|                 |                 |                 | Cinder volume   |
|                 |                 |                 | as value. For   |
|                 |                 |                 | example:        |
|                 |                 |                 |                 |
|                 |                 |                 |                 |
|                 |                 |                 |     "cinder": { |
|                 |                 |                 |                 |
|                 |                 |                 |          "volum |
|                 |                 |                 | eID": "9e5b5387 |
|                 |                 |                 | -ed3b-4b9d-ab1e |
|                 |                 |                 | -0ce1e9dd86a1", |
|                 |                 |                 |           "aut  |
|                 |                 |                 | oRemove": false |
|                 |                 |                 |       }         |
|                 |                 |                 |                 |
|                 |                 |                 | To create a     |
|                 |                 |                 | volume, set the |
|                 |                 |                 | size key with   |
|                 |                 |                 | its size as     |
|                 |                 |                 | value.          |
|                 |                 |                 | For example:    |
|                 |                 |                 |                 |
|                 |                 |                 |                 |
|                 |                 |                 |     "cinder": { |
|                 |                 |                 |                 |
|                 |                 |                 |      "size": 1, |
|                 |                 |                 |           "au   |
|                 |                 |                 | toRemove": true |
|                 |                 |                 |       }         |
|                 |                 |                 |                 |
|                 |                 |                 | The autoRemove  |
|                 |                 |                 | key is optional |
|                 |                 |                 | for deciding    |
|                 |                 |                 | the cleanup of  |
|                 |                 |                 | the             |
|                 |                 |                 | volume.         |
+-----------------+-----------------+-----------------+-----------------+
| cinder.volumeID | body            | string          | The UUID of the |
| (Optional)      |                 |                 | Cinder volume.  |
+-----------------+-----------------+-----------------+-----------------+
| cinder.size     | body            | string          | The size of the |
| (Optional)      |                 |                 | Cinder volume.  |
+-----------------+-----------------+-----------------+-----------------+
| ci              | body            | string          | Whether to      |
| nder.autoRemove |                 |                 | remove the      |
| (Optional)      |                 |                 | volume when the |
|                 |                 |                 | capsule is      |
|                 |                 |                 | deleted.        |
+-----------------+-----------------+-----------------+-----------------+

Request Example¶

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

Response¶

Capsule¶

+-----------------+-----------------+-----------------+-----------------+
| Name            | In              | Type            | Description     |
+=================+=================+=================+=================+
| addresses       | body            | string          | IP address of   |
|                 |                 |                 | the capsule.    |
|                 |                 |                 | This includes   |
|                 |                 |                 | both ipv4       |
|                 |                 |                 | and/or ipv6     |
|                 |                 |                 | addresses.      |
+-----------------+-----------------+-----------------+-----------------+
| containers      | body            | object          | List of         |
|                 |                 |                 | containers      |
|                 |                 |                 | belonging       |
|                 |                 |                 | to the capsule. |
|                 |                 |                 | There must be   |
|                 |                 |                 | at least one    |
|                 |                 |                 | container in a  |
|                 |                 |                 | capsule.        |
+-----------------+-----------------+-----------------+-----------------+
| cpu             | body            | float           | The number of   |
|                 |                 |                 | virtual cpus of |
|                 |                 |                 | the capsule.    |
+-----------------+-----------------+-----------------+-----------------+
| memory          | body            | string          | The capsule     |
|                 |                 |                 | memory size in  |
|                 |                 |                 | MiB.            |
+-----------------+-----------------+-----------------+-----------------+
| uuid            | body            | string          | The UUID of the |
|                 |                 |                 | capsule.        |
+-----------------+-----------------+-----------------+-----------------+
| name            | body            | string          | The name of the |
|                 |                 |                 | capsule.        |
+-----------------+-----------------+-----------------+-----------------+
| labels          | body            | object          | The labels of   |
|                 |                 |                 | the capsule.    |
+-----------------+-----------------+-----------------+-----------------+
| annotations     | body            | object          | The annotations |
|                 |                 |                 | of the capsule. |
|                 |                 |                 | Annotations is  |
|                 |                 |                 | an unstructured |
|                 |                 |                 | key value map   |
|                 |                 |                 | stored with a   |
|                 |                 |                 | resource        |
|                 |                 |                 | that may be set |
|                 |                 |                 | by external     |
|                 |                 |                 | tools to store  |
|                 |                 |                 | and retrieve    |
|                 |                 |                 | arbitrary       |
|                 |                 |                 | metadata.       |
+-----------------+-----------------+-----------------+-----------------+
| restart_policy  | body            | object          | Restart policy  |
|                 |                 |                 | for all         |
|                 |                 |                 | containers      |
|                 |                 |                 | within the      |
|                 |                 |                 | capsule.        |
+-----------------+-----------------+-----------------+-----------------+
| created_at      | body            | string          | The date and    |
|                 |                 |                 | time when the   |
|                 |                 |                 | resource was    |
|                 |                 |                 | created.        |
|                 |                 |                 |                 |
|                 |                 |                 | The date and    |
|                 |                 |                 | time stamp      |
|                 |                 |                 | format is ISO   |
|                 |                 |                 | 8601:           |
|                 |                 |                 |                 |
|                 |                 |                 |     CCYY-MM-DD  |
|                 |                 |                 | Thh:mm:ss±hh:mm |
|                 |                 |                 |                 |
|                 |                 |                 | For example,    |
|                 |                 |                 | 2015-08-27T     |
|                 |                 |                 | 09:49:58-05:00. |
|                 |                 |                 |                 |
|                 |                 |                 | The ±hh:mm      |
|                 |                 |                 | value, if       |
|                 |                 |                 | included, is    |
|                 |                 |                 | the time zone   |
|                 |                 |                 | as an offset    |
|                 |                 |                 | from UTC.       |
+-----------------+-----------------+-----------------+-----------------+
| updated_at      | body            | string          | The date and    |
|                 |                 |                 | time when the   |
|                 |                 |                 | resource was    |
|                 |                 |                 | updated.        |
|                 |                 |                 |                 |
|                 |                 |                 | The date and    |
|                 |                 |                 | time stamp      |
|                 |                 |                 | format is ISO   |
|                 |                 |                 | 8601:           |
|                 |                 |                 |                 |
|                 |                 |                 |     CCYY-MM-DD  |
|                 |                 |                 | Thh:mm:ss±hh:mm |
|                 |                 |                 |                 |
|                 |                 |                 | For example,    |
|                 |                 |                 | 2015-08-27T     |
|                 |                 |                 | 09:49:58-05:00. |
|                 |                 |                 |                 |
|                 |                 |                 | The ±hh:mm      |
|                 |                 |                 | value, if       |
|                 |                 |                 | included, is    |
|                 |                 |                 | the time zone   |
|                 |                 |                 | as an offset    |
|                 |                 |                 | from UTC. In    |
|                 |                 |                 | the previous    |
|                 |                 |                 | example, the    |
|                 |                 |                 | offset value is |
|                 |                 |                 | -05:00.         |
|                 |                 |                 |                 |
|                 |                 |                 | If the          |
|                 |                 |                 | updated_at date |
|                 |                 |                 | and time stamp  |
|                 |                 |                 | is not set, its |
|                 |                 |                 | value is        |
|                 |                 |                 | null.           |
+-----------------+-----------------+-----------------+-----------------+
| user_id         | body            | string          | The user ID of  |
|                 |                 |                 | the user who    |
|                 |                 |                 | owns the        |
|                 |                 |                 | capsule.        |
+-----------------+-----------------+-----------------+-----------------+
| project_id      | body            | string          | The UUID of the |
|                 |                 |                 | project to      |
|                 |                 |                 | which this      |
|                 |                 |                 | capsule         |
|                 |                 |                 | belongs.        |
+-----------------+-----------------+-----------------+-----------------+
| status          | body            | string          | The current     |
|                 |                 |                 | state of the    |
|                 |                 |                 | capsule.        |
+-----------------+-----------------+-----------------+-----------------+
| status_reason   | body            | string          | The reason of   |
|                 |                 |                 | capsule current |
|                 |                 |                 | status.         |
+-----------------+-----------------+-----------------+-----------------+
| links           | body            | string          | A list of       |
|                 |                 |                 | relative links. |
+-----------------+-----------------+-----------------+-----------------+

Capsule Container¶

+-----------------+-----------------+-----------------+-----------------+
| Name            | In              | Type            | Description     |
+=================+=================+=================+=================+
| addresses       | body            | string          | IP address of   |
|                 |                 |                 | the container.  |
|                 |                 |                 | This includes   |
|                 |                 |                 | both ipv4       |
|                 |                 |                 | and/or ipv6     |
|                 |                 |                 | addresses.      |
+-----------------+-----------------+-----------------+-----------------+
| image           | body            | string          | The name or ID  |
|                 |                 |                 | of the image.   |
+-----------------+-----------------+-----------------+-----------------+
| labels          | body            | object          | A map of labels |
|                 |                 |                 | of the          |
|                 |                 |                 | container.      |
+-----------------+-----------------+-----------------+-----------------+
| disk            | body            | integer         | The container   |
|                 |                 |                 | disk size in    |
|                 |                 |                 | GiB.            |
+-----------------+-----------------+-----------------+-----------------+
| security_groups | body            | string          | Security groups |
|                 |                 |                 | to be added to  |
|                 |                 |                 | the container.  |
+-----------------+-----------------+-----------------+-----------------+
| task_state      | body            | string          | The current     |
|                 |                 |                 | task of the     |
|                 |                 |                 | container.      |
+-----------------+-----------------+-----------------+-----------------+
| user_id         | body            | string          | The user ID of  |
|                 |                 |                 | the user who    |
|                 |                 |                 | owns the        |
|                 |                 |                 | container.      |
+-----------------+-----------------+-----------------+-----------------+
| uuid            | body            | string          | The UUID of the |
|                 |                 |                 | container.      |
+-----------------+-----------------+-----------------+-----------------+
| hostname        | body            | string          | The hostname of |
|                 |                 |                 | container.      |
+-----------------+-----------------+-----------------+-----------------+
| environment     | body            | object          | The environment |
|                 |                 |                 | variables to    |
|                 |                 |                 | set in the      |
|                 |                 |                 | container.      |
+-----------------+-----------------+-----------------+-----------------+
| memory          | body            | integer         | The container   |
|                 |                 |                 | memory size in  |
|                 |                 |                 | MiB.            |
+-----------------+-----------------+-----------------+-----------------+
| project_id      | body            | array           | The UUID of the |
|                 |                 |                 | project to      |
|                 |                 |                 | which this      |
|                 |                 |                 | container       |
|                 |                 |                 | belongs.        |
+-----------------+-----------------+-----------------+-----------------+
| status          | body            | string          | The current     |
|                 |                 |                 | state of the    |
|                 |                 |                 | container.      |
+-----------------+-----------------+-----------------+-----------------+
| environment     | body            | object          | The environment |
|                 |                 |                 | variables to    |
|                 |                 |                 | set in the      |
|                 |                 |                 | container.      |
+-----------------+-----------------+-----------------+-----------------+
| workdir         | body            | string          | The working     |
|                 |                 |                 | directory for   |
|                 |                 |                 | commands to run |
|                 |                 |                 | in.             |
+-----------------+-----------------+-----------------+-----------------+
| healthcheck     | body            | object          | A dict of       |
|                 |                 |                 | health check    |
|                 |                 |                 | for the         |
|                 |                 |                 | container.      |
|                 |                 |                 | Specify a test  |
|                 |                 |                 | command to      |
|                 |                 |                 | perform to      |
|                 |                 |                 | check that the  |
|                 |                 |                 | container is    |
|                 |                 |                 | healthy. Four   |
|                 |                 |                 | parameters are  |
|                 |                 |                 | supported:      |
|                 |                 |                 |                 |
|                 |                 |                 | -   cmd:        |
|                 |                 |                 |     Command to  |
|                 |                 |                 |     run to      |
|                 |                 |                 |     check       |
|                 |                 |                 |     health.     |
|                 |                 |                 |                 |
|                 |                 |                 | -   interval:   |
|                 |                 |                 |     Time        |
|                 |                 |                 |     between     |
|                 |                 |                 |     running the |
|                 |                 |                 |     check in    |
|                 |                 |                 |     seconds.    |
|                 |                 |                 |                 |
|                 |                 |                 | -   retries:    |
|                 |                 |                 |     Consecutive |
|                 |                 |                 |     failures    |
|                 |                 |                 |     needed to   |
|                 |                 |                 |     report      |
|                 |                 |                 |     unhealthy.  |
|                 |                 |                 |                 |
|                 |                 |                 | -   timeout:    |
|                 |                 |                 |     Maximum     |
|                 |                 |                 |     time to     |
|                 |                 |                 |     allow one   |
|                 |                 |                 |     check to    |
|                 |                 |                 |     run in      |
|                 |                 |                 |     seconds.    |
+-----------------+-----------------+-----------------+-----------------+
| auto_remove     | body            | boolean         | Enable          |
|                 |                 |                 | auto-removal of |
|                 |                 |                 | the container   |
|                 |                 |                 | on daemon side  |
|                 |                 |                 | when the        |
|                 |                 |                 | container’s     |
|                 |                 |                 | process exits.  |
+-----------------+-----------------+-----------------+-----------------+
| auto_heal       | body            | boolean         | The flag of     |
|                 |                 |                 | healing         |
|                 |                 |                 | non-existent    |
|                 |                 |                 | container in    |
|                 |                 |                 | docker.         |
+-----------------+-----------------+-----------------+-----------------+
| cpu_policy      | body            | string          | The CPU policy  |
|                 |                 |                 | of the          |
|                 |                 |                 | container. Its  |
|                 |                 |                 | value can be    |
|                 |                 |                 | dedicated or    |
|                 |                 |                 | shared.         |
+-----------------+-----------------+-----------------+-----------------+
| image_driver    | body            | string          | The image       |
|                 |                 |                 | driver to use   |
|                 |                 |                 | to pull         |
|                 |                 |                 | container       |
|                 |                 |                 | image.          |
+-----------------+-----------------+-----------------+-----------------+
| status_detail   | body            | string          | The status      |
|                 |                 |                 | detail of the   |
|                 |                 |                 | container.      |
+-----------------+-----------------+-----------------+-----------------+
| status_reason   | body            | string          | The reason of   |
|                 |                 |                 | container       |
|                 |                 |                 | current status. |
+-----------------+-----------------+-----------------+-----------------+
| name            | body            | string          | The name of the |
|                 |                 |                 | container.      |
+-----------------+-----------------+-----------------+-----------------+
| restart_policy  | body            | object          | Restart policy  |
|                 |                 |                 | to apply when a |
|                 |                 |                 | container       |
|                 |                 |                 | exits. It must  |
|                 |                 |                 | contain a       |
|                 |                 |                 | Name key and    |
|                 |                 |                 | its allowed     |
|                 |                 |                 | values are no,  |
|                 |                 |                 | on-failure,     |
|                 |                 |                 | always,         |
|                 |                 |                 | unless-stopped. |
|                 |                 |                 | Optionally, it  |
|                 |                 |                 | can contain a   |
|                 |                 |                 | Ma              |
|                 |                 |                 | ximumRetryCount |
|                 |                 |                 | key             |
|                 |                 |                 | and its value   |
|                 |                 |                 | is an integer.  |
+-----------------+-----------------+-----------------+-----------------+
| cpu             | body            | float           | The number of   |
|                 |                 |                 | virtual cpus of |
|                 |                 |                 | the container.  |
+-----------------+-----------------+-----------------+-----------------+
| command         | body            | array           | Send command to |
|                 |                 |                 | the container.  |
+-----------------+-----------------+-----------------+-----------------+
| registry_id     | body            | string          | The ID of the   |
|                 |                 |                 | image registry  |
|                 |                 |                 | used by the     |
|                 |                 |                 | container.      |
+-----------------+-----------------+-----------------+-----------------+
| ports           | body            | string          | The ports       |
|                 |                 |                 | exposed on the  |
|                 |                 |                 | container.      |
+-----------------+-----------------+-----------------+-----------------+
| interactive     | body            | boolean         | Keep STDIN open |
|                 |                 |                 | even if not     |
|                 |                 |                 | attached.       |
+-----------------+-----------------+-----------------+-----------------+
| tty             | body            | boolean         | Whether this    |
|                 |                 |                 | container       |
|                 |                 |                 | allocate a TTY  |
|                 |                 |                 | for itself.     |
+-----------------+-----------------+-----------------+-----------------+

Response Example¶

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

GET

/v1/capsules/

List all capsules

detail

List all available capsules in Zun.

Response Codes¶

Success¶

  Code       Reason
  ---------- -------------------------
  200 - OK   Request was successful.

Error¶

  Code                 Reason
  -------------------- ----------------------------------------------------------
  401 - Unauthorized   User must authenticate before making a request.
  403 - Forbidden      Policy does not allow current user to do this operation.

Request¶

This request does not contain anything in the request body.

Response¶

Capsule¶