From cbcad3b982cd564ba89032c0e6b5400c2cfe1446 Mon Sep 17 00:00:00 2001 From: Madhuri Kumari Date: Thu, 22 Jun 2017 13:51:24 +0530 Subject: [PATCH] Add api-ref for container operations This patch adds api-ref for list, show, delete, update container. Change-Id: Ic736b55bc8e71636b63d56e2984ece8301384a99 Partially-Implements: bp zun-api-doc --- api-ref/source/containers.inc | 230 ++++++++++++++++++ api-ref/source/parameters.yaml | 18 ++ .../source/samples/container-create-req.json | 15 +- .../source/samples/container-create-resp.json | 60 ++--- .../samples/container-get-all-resp.json | 49 ++++ .../source/samples/container-show-resp.json | 47 ++++ .../source/samples/container-update-req.json | 4 + .../source/samples/container-update-resp.json | 47 ++++ 8 files changed, 437 insertions(+), 33 deletions(-) create mode 100644 api-ref/source/samples/container-get-all-resp.json create mode 100644 api-ref/source/samples/container-show-resp.json create mode 100644 api-ref/source/samples/container-update-req.json create mode 100644 api-ref/source/samples/container-update-resp.json diff --git a/api-ref/source/containers.inc b/api-ref/source/containers.inc index 023b3b278..98f80c19a 100644 --- a/api-ref/source/containers.inc +++ b/api-ref/source/containers.inc @@ -86,3 +86,233 @@ Response Example .. literalinclude:: samples/container-create-resp.json :language: javascript + +List all containers +=================== + +.. rest_method:: GET /v1/containers/ + +List all available containers in Zun. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 403 + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - containers: container_list + - links: links + - addresses: addresses + - name: name + - image: image + - labels: labels + - image_driver: image_driver + - security_groups: security_groups + - command: command + - cpu: cpu + - memory: memory + - workdir: workdir + - image_pull_policy: image_pull_policy + - environment: environment + - restart_policy: restart_policy + - interactive: interactive + - uuid: uuid + - hostname: hostname + - status: status + - status_detail: status_detail + - host: host + - task_state: task_state + - status_reason: status_reason + - ports: ports + +Response Example +---------------- + +.. literalinclude:: samples/container-get-all-resp.json + :language: javascript + +Show details of a container +=========================== + +.. rest_method:: GET /v1/containers/{container_ident} + +Get all information of a container in Zun. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 401 + - 403 + - 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - container_ident: container_ident + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - links: links + - addresses: addresses + - name: name + - image: image + - labels: labels + - image_driver: image_driver + - security_groups: security_groups + - command: command + - cpu: cpu + - memory: memory + - workdir: workdir + - image_pull_policy: image_pull_policy + - environment: environment + - restart_policy: restart_policy + - interactive: interactive + - uuid: uuid + - hostname: hostname + - status: status + - status_detail: status_detail + - host: host + - task_state: task_state + - status_reason: status_reason + - ports: ports + +Response Example +---------------- + +.. literalinclude:: samples/container-show-resp.json + :language: javascript + +Delete a container +================== + +.. rest_method:: DELETE /v1/containers/{container_ident} + +Delete a container. To delete a container in `Creating` or `Running` +state, request to /v1/containers/{container_ident}?force=True + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 204 + +.. rest_status_code:: error status.yaml + + - 401 + - 403 + - 404 + - 409 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - container_ident: container_ident + - force: force + +Response +-------- + +This request does not return anything in the response body. + +.. rest_parameters:: parameters.yaml + + - X-Openstack-Request-Id: request_id + +Update information of container +=============================== + +.. rest_method:: PATCH /v1/containers/{container_ident} + +Update information of one container attributes. Currently only `cpu` and +`memory` can be updated. + +Response Codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 400 + - 401 + - 403 + - 404 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - container_ident: container_ident + - memory: memory + - cpu: cpu + +Request Example +---------------- + +.. literalinclude:: samples/container-update-req.json + :language: javascript + +Response +-------- + +Return new container with updated attributes. + +.. rest_parameters:: parameters.yaml + + - links: links + - addresses: addresses + - name: name + - image: image + - labels: labels + - image_driver: image_driver + - security_groups: security_groups + - command: command + - cpu: cpu + - memory: memory + - workdir: workdir + - image_pull_policy: image_pull_policy + - environment: environment + - restart_policy: restart_policy + - interactive: interactive + - uuid: uuid + - hostname: hostname + - status: status + - status_detail: status_detail + - host: host + - task_state: task_state + - status_reason: status_reason + - ports: ports + +Response Example +---------------- + +.. literalinclude:: samples/container-update-resp.json + :language: javascript diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 8876c5f34..fcaaae341 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -5,6 +5,18 @@ request_id: description: | A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs. +container_ident: + description: | + The UUID or name of container in Zun. + in: path + required: true + type: string +force: + description: | + Specify to delete container forcefully. + in: query + required: true + type: string addresses: type: string description: | @@ -22,6 +34,12 @@ command: Send command to the container. in: body type: string +container_list: + type: array + in: body + required: true + description: | + The list of all containers in Zun. cpu: description: | The number of virtual cpus. diff --git a/api-ref/source/samples/container-create-req.json b/api-ref/source/samples/container-create-req.json index 489192765..18ef77dae 100644 --- a/api-ref/source/samples/container-create-req.json +++ b/api-ref/source/samples/container-create-req.json @@ -1,16 +1,21 @@ { "environment":{ + "foo": "bar" }, "labels":{ + "app": "hello" }, - "image": "cirros", - "command": "ping -c 4 8.8.8.8", + "image": "ubuntu", + "command": "/bin/sh -c 'echo hello'", "name": "test", "cpu": 2, "memory": 500, - "workdir": null, - "image_pull_policy": null, - "restart_policy": null, + "workdir": "/home/ubuntu", + "image_pull_policy": "always", + "restart_policy":{ + "Name": "no", + "MaximumRetryCount": 0 + }, "interactive": "False", "image_driver": "docker", "security_groups": null diff --git a/api-ref/source/samples/container-create-resp.json b/api-ref/source/samples/container-create-resp.json index e80f5d1b6..25278aca2 100644 --- a/api-ref/source/samples/container-create-resp.json +++ b/api-ref/source/samples/container-create-resp.json @@ -1,33 +1,37 @@ { "addresses": null, - "links":[{ - "href": "http://10.223.197.220:9517/v1/containers/2a278cd8-5d89-462e-8453-0ced64564714", + "links": [{ + "href": "http://openstack.example.com/v1/containers/b0694d40-70af-4488-b104-10f66b593347", "rel": "self" }, - {"href": "http://10.223.197.220:9517/containers/2a278cd8-5d89-462e-8453-0ced64564714", "rel": "bookmark"} - ], - "image": "cirros", - "labels":{ - }, - "security_groups": null, - "image_pull_policy": null, - "uuid": "2a278cd8-5d89-462e-8453-0ced64564714", - "hostname": null, - "environment": { - }, - "memory": "500M", - "status": "Creating", - "workdir": null, - "status_detail": null, - "host": "ubuntu", - "image_driver": "docker", - "task_state": null, - "status_reason": null, - "name": "test", - "restart_policy": null, - "ports": null, - "command": "ping -c 4 8.8.8.8", - "cpu": 2.0, - "interactive": false + {"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 } - diff --git a/api-ref/source/samples/container-get-all-resp.json b/api-ref/source/samples/container-get-all-resp.json new file mode 100644 index 000000000..5fae6ed36 --- /dev/null +++ b/api-ref/source/samples/container-get-all-resp.json @@ -0,0 +1,49 @@ +{ + "addresses": { + "public": [{ + "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 +} diff --git a/api-ref/source/samples/container-show-resp.json b/api-ref/source/samples/container-show-resp.json new file mode 100644 index 000000000..902ed36ef --- /dev/null +++ b/api-ref/source/samples/container-show-resp.json @@ -0,0 +1,47 @@ +{ + "addresses": { + "public": [{ + "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 +} diff --git a/api-ref/source/samples/container-update-req.json b/api-ref/source/samples/container-update-req.json new file mode 100644 index 000000000..0812f6599 --- /dev/null +++ b/api-ref/source/samples/container-update-req.json @@ -0,0 +1,4 @@ +{ + "memory": "200", + "cpu": "3" +} diff --git a/api-ref/source/samples/container-update-resp.json b/api-ref/source/samples/container-update-resp.json new file mode 100644 index 000000000..64ef43f97 --- /dev/null +++ b/api-ref/source/samples/container-update-resp.json @@ -0,0 +1,47 @@ +{ +"addresses": { + "public": [{ + "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 +}