Add api-ref for container create

Change-Id: Ib6df2694bff69cb18cb37f42e7aa7f4809b6ae6f
Partial-Implements: bp zun-api-doc

api-ref/source/containers.inc

@@ -0,0 +1,88 @@
+.. -*- rst -*-
+
+===================
+ Manage Containers
+===================
+
+Lists, creates, shows details for, updates, and deletes containers.
+
+Create new container
+====================
+
+.. rest_method:: POST /v1/containers/
+
+Create new container.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 201
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - name: name
+  - image: image
+  - command: command
+  - cpu: cpu
+  - memory: memory
+  - workdir: workdir
+  - image_pull_policy: image_pull_policy
+  - labels: labels
+  - environment: environment
+  - restart_policy: restart_policy
+  - interactive: interactive
+  - image_driver: image_driver
+  - security_groups: security_groups
+
+Request Example
+----------------
+
+.. literalinclude:: samples/container-create-req.json
+   :language: javascript
+
+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-create-resp.json
+   :language: javascript

api-ref/source/parameters.yaml

@@ -5,12 +5,28 @@ request_id:
   description: |
     A unique ID for tracking service request. The request ID associated
     with the request by default appears in the service logs.
-binary:
+addresses:
   type: string
+  description: |
+    IP address of the container. This includes both ipv4 and/or ipv6 addresses.
   in: body
   required: true
+binary:
+  in: body
+  type: string
+  required: true
   description: |
     The name of the binary form of the Zun service.
+command:
+  description: |
+    Send command to the container.
+  in: body
+  type: string
+cpu:
+  description: |
+    The number of virtual cpus.
+  in: body
+  type: float
 created_at:
   description: |
     The date and time when the resource was created.
@@ -42,6 +58,11 @@ disabled_reason:
   in: body
   required: true
   type: string
+environment:
+  description: |
+    The environment variables.
+  in: body
+  type: array
 forced_down:
   description: |
     Whether or not this service was forced down manually by an
@@ -56,21 +77,93 @@ host:
   in: body
   required: true
   type: string
+hostname:
+  description: |
+    The host where container is running.
+  in: body
+  required: true
+  type: string
 id_s:
   description: |
     The ID of the Zun service.
   in: body
   required: true
   type: string
+image:
+  description: |
+    The name or ID of the image.
+  in: body
+  required: true
+  type: string
+image_driver:
+  description: |
+    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.
+  in: body
+  type: string
+image_pull_policy:
+  description: |
+    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.
+  in: body
+  type: string
+interactive:
+  description: |
+    Keep STDIN open even if not attached, allocate a pseudo-TTY.
+  in: body
+  type: boolean
+labels:
+  description: |
+    Adds a map of labels to a container.
+  in: body
+  type: array
+links:
+  description: |
+    A list of relative links. Includes the self and
+    bookmark links.
+  in: body
+  required: true
+  type: array
+memory:
+  description: |
+    The container memory size in MiB.
+  in: body
+  type: integer
+name:
+  description: |
+    The name of the container.
+  in: body
+  required: true
+  type: string
+ports:
+  description: |
+    The ports exposed on the container.
+  in: body
+  required: true
+  type: string
 report_count:
   description: |
     The total number of report.
   in: body
   required: true
   type: integer
+restart_policy:
+  description: |
+    Restart policy to apply when a container exits. Allowed values are
+    no, on-failure[:max-retry], always, unless-stopped.
+  in: body
+  type: string
+security_groups:
+  description: |
+    Security groups to be added to the container.
+  in: body
+  type: string
 service:
   description: |
-    A Zun services.
+    A Zun service.
   in: body
   required: true
   type: dict
@@ -86,6 +179,30 @@ state:
   in: body
   required: true
   type: string
+status:
+  description: |
+    The current state of the container.
+  in: body
+  required: true
+  type: string
+status_detail:
+  description: |
+    The status detail of the container.
+  in: body
+  required: true
+  type: string
+status_reason:
+  description: |
+    The reason of container current status.
+  in: body
+  required: true
+  type: string
+task_state:
+  description: |
+    The current task of the container.
+  in: body
+  required: true
+  type: string
 updated_at:
   description: |
     The date and time when the resource was updated.
@@ -107,3 +224,14 @@ updated_at:
   in: body
   required: true
   type: string
+uuid:
+  description: |
+    UUID of the resource.
+  in: body
+  required: true
+  type: UUID
+workdir:
+  description: |
+    The working directory for commands to run in.
+  in: body
+  type: string

api-ref/source/samples/container-create-req.json

@@ -0,0 +1,17 @@
+{
+    "environment":{
+    },
+    "labels":{
+    },
+    "image": "cirros",
+    "command": "ping -c 4 8.8.8.8",
+    "name": "test",
+    "cpu": 2,
+    "memory": 500,
+    "workdir": null,
+    "image_pull_policy": null,
+    "restart_policy": null,
+    "interactive": "False",
+    "image_driver": "docker",
+    "security_groups": null
+}

api-ref/source/samples/container-create-resp.json

@@ -0,0 +1,33 @@
+{
+    "addresses": null,
+    "links":[{
+        "href": "http://10.223.197.220:9517/v1/containers/2a278cd8-5d89-462e-8453-0ced64564714",
+        "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
+}
+

api-ref/source/services.inc

@@ -78,7 +78,7 @@ Request Parameters
 Response Parameters
 -------------------
 
-.. rest_parameters:: parameters.yaml
+If successful, this method does not return content in the response body.
 
 
 Enable container management service