describe the portmapping API and command lines

Author: gnawux

Diff for: SUMMARY.md

@@ -28,6 +28,7 @@
        * [rm](reference/rm.md)
        * [info](reference/info.md)
        * [list](reference/list.md)
+       * [ports](reference/ports.md)
        * [pull](reference/pull.md)
        * [images](reference/images.md)
        * [rmi](reference/rmi.md)

Diff for: reference/api.md

@@ -100,6 +100,37 @@ Send kill signal to containers of a Pod
 
 `POST /pod/kill?podName=pod-xxxxxxxxxx&container=xxxxxxx&signal=9`
 
+##### List Port Mapping Rules
+
+`GET /pod/{pod_id}/portmappings`
+
+Get a list of current port mappings of a pod.
+
+##### Modify Port Mapping Rules
+
+`PUT /pod/{pod_id}/portmappings/{action}`
+
+Update port mapping rules
+
+- `action` could be `add` or `delete`
+
+The request body is an json **array** of `PortMapping`:
+
+```
+{
+	"containerPort": "80",
+	"hostPort": "3000",
+	"protocol": "udp"
+}
+```
+
+Where
+
+- `containerPort` and `hostPort` could be a single port or a range, such as "8000-8080"; and if the `containerPort` is a range, the `hostPort` should be a range in same size;
+- `protocol` could be `tcp` or `udp`.
+
+The request body should be an array even if there is only one rule to be added/deleted.
+
 #### 2.2 Container
 ##### Create container
 `POST /container/create`

Diff for: reference/cli.md

@@ -17,6 +17,7 @@ Command:
   login                  Register or log in to a Docker registry server
   logout                 Log out from a Docker registry server
   pause                  Pause a running pod
+  ports                  List or modify port mapping rules of a Pod
   pull                   Pull an image from a Docker registry server
   push                   Push an image or a repository to a Docker registry server
   rm                     Remove one or more pods or containers

Diff for: reference/containers.md

@@ -11,7 +11,7 @@
 
 - `workdir`: the directory running the container command
 
-- `ports`: the exposed ports of the container
+- *[Deprecated]* `ports`: the exposed ports of the container, the ports now is move to the Pod level
     - `containerPort`: the listening port inside container
     - `hostPort`: the port exposed in host machine
     - `protocol`: `tcp` (default) or `udp`
@@ -62,9 +62,5 @@ example:
     	        "content": ""
     	    }
         }],
-        "ports":[{
-            "containerPort": 80,
-            "hostPort": 8000,
-        }],
         "tty": true
     }]

Diff for: reference/podfile.md

@@ -9,7 +9,6 @@ Podfile is in JSON format. A basic sample looks like the following:
             "vcpu": 1,
             "memory": 128
         },
-
         "containers" : [{
             "image": "nginx:latest",
             "files":  [{
@@ -18,14 +17,17 @@ Podfile is in JSON format. A basic sample looks like the following:
 	            "perm": "0755"
 	        }]
         }],
-
         "files": [{
 	        "name": "filename",
 	        "encoding": "raw",
 	        "uri": "https://s3.amazonaws/bucket/file.conf",
 	        "content": ""
 	      }],
-
+        "portmappings": [{
+          "containerPort": "80",
+          "hostPort": "3000",
+          "protocol": "udp"
+	      }],
         "volumes": []
     }
 
@@ -35,5 +37,8 @@ Podfile is in JSON format. A basic sample looks like the following:
 - `hostname`: the hostname of the Pod
 - `resources`: specify the number of CPU cores and RAM size allocated to the HyperVM instance
 - `containers`: a group of [containers](./containers.md) to run in the Pod. Since 0.8, we could create a Pod with empty containers list, and add containers later.
+- `portmappings`: the port mapping rules, and the portmappings could be `add`/`remove` during runtime with API or command line tools. The fields:
+  - `containerPort` and `hostPort` could be a single port or a range, such as "8000-8080"; and if the `containerPort` is a range, the `hostPort` should be a range in same size;
+  - `protocol` could be `tcp` or `udp`.
 - `files`: [files](./files.md) to be present in the containers
 - `volumes`: [volumes](./volumes.md) to mount from the host to the containers

Diff for: reference/ports.md

@@ -0,0 +1,17 @@
+# ports
+
+List or modify port mapping rules of a Pod
+
+```
+Usage:
+  hyperctl ports ls|add|delete [OPTIONS] POD
+
+List or modify port mapping rules of a Pod
+
+Application Options:
+
+  -p, --publish   Publish a container's port to the host (only valid for add and delete)
+
+Help Options:
+	-h, --help  Show this help message
+```