From 3cc70453b29239e9d640dc3071b6922629d7a729 Mon Sep 17 00:00:00 2001 From: pouchrobot Date: Tue, 13 Mar 2018 01:13:53 +0000 Subject: [PATCH] docs: auto generate pouch cli docs via code Signed-off-by: pouchrobot --- docs/api/HTTP_API.md | 73 ++++++++++++++++++++- docs/commandline/pouch.md | 1 + docs/commandline/pouch_create.md | 2 + docs/commandline/pouch_image_inspect.md | 3 +- docs/commandline/pouch_network_inspect.md | 3 +- docs/commandline/pouch_run.md | 2 + docs/commandline/pouch_update.md | 15 ++++- docs/commandline/pouch_upgrade.md | 77 +++++++++++++++++++++++ docs/commandline/pouch_volume_inspect.md | 3 +- 9 files changed, 174 insertions(+), 5 deletions(-) create mode 100644 docs/commandline/pouch_upgrade.md diff --git a/docs/api/HTTP_API.md b/docs/api/HTTP_API.md index f416e1d6e..676d788e7 100644 --- a/docs/api/HTTP_API.md +++ b/docs/api/HTTP_API.md @@ -590,6 +590,36 @@ POST /containers/{id}/update * Container + +### Upgrade a container with new image and args +``` +POST /containers/{id}/upgrade +``` + + +#### Parameters + +|Type|Name|Description|Schema| +|---|---|---|---| +|**Path**|**id**
*required*|ID or name of the container|string| +|**Body**|**upgradeConfig**
*optional*||[ContainerUpgradeConfig](#containerupgradeconfig)| + + +#### Responses + +|HTTP Code|Description|Schema| +|---|---|---| +|**200**|no error|No Content| +|**400**|bad parameter|[Error](#error)| +|**404**|An unexpected 404 error occured.|[Error](#error)| +|**500**|An unexpected server error occured.|[Error](#error)| + + +#### Tags + +* Container + + ### Start an exec instance ``` @@ -1388,6 +1418,47 @@ GET "/containers/{id}/json" |**Status**
*optional*||[Status](#status)| + +### ContainerUpgradeConfig +ContainerUpgradeConfig is used for API "POST /containers/upgrade". +It wraps all kinds of config used in container upgrade. +It can be used to encode client params in client and unmarshal request body in daemon side. + +*Polymorphism* : Composition + + +|Name|Description|Schema| +|---|---|---| +|**ArgsEscaped**
*optional*|Command is already escaped (Windows only)|boolean| +|**AttachStderr**
*optional*|Whether to attach to `stderr`.
**Default** : `true`|boolean| +|**AttachStdin**
*optional*|Whether to attach to `stdin`.|boolean| +|**AttachStdout**
*optional*|Whether to attach to `stdout`.
**Default** : `true`|boolean| +|**Cmd**
*optional*|Command to run specified an array of strings.|< string > array| +|**Domainname**
*optional*|The domain name to use for the container.|string| +|**Entrypoint**
*optional*|The entry point for the container as a string or an array of strings.
If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by pouch when there is no `ENTRYPOINT` instruction in the `Dockerfile`).|< string > array| +|**Env**
*optional*|A list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.|< string > array| +|**ExposedPorts**
*optional*|An object mapping ports to an empty object in the form:`{/: {}}`|< string, object > map| +|**HostConfig**
*optional*||[HostConfig](#hostconfig)| +|**Hostname**
*optional*|The hostname to use for the container, as a valid RFC 1123 hostname.
**Minimum length** : `1`|string (hostname)| +|**Image**
*required*|The name of the image to use when creating the container|string| +|**InitScript**
*optional*|Initial script executed in container. The script will be executed before entrypoint or command|string| +|**Labels**
*optional*|User-defined key/value metadata.|< string, string > map| +|**MacAddress**
*optional*|MAC address of the container.|string| +|**NetworkDisabled**
*optional*|Disable networking for the container.|boolean| +|**OnBuild**
*optional*|`ONBUILD` metadata that were defined in the image's `Dockerfile`.|< string > array| +|**OpenStdin**
*optional*|Open `stdin`|boolean| +|**Rich**
*optional*|Whether to start container in rich container mode. (default false)|boolean| +|**RichMode**
*optional*|Choose one rich container mode.(default dumb-init)|enum (dumb-init, sbin-init, systemd)| +|**Shell**
*optional*|Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.|< string > array| +|**StdinOnce**
*optional*|Close `stdin` after one attached client disconnects|boolean| +|**StopSignal**
*optional*|Signal to stop a container as a string or unsigned integer.
**Default** : `"SIGTERM"`|string| +|**StopTimeout**
*optional*|Timeout to stop a container in seconds.|integer| +|**Tty**
*optional*|Attach standard streams to a TTY, including `stdin` if it is not closed.|boolean| +|**User**
*optional*|The user that commands are run as inside the container.|string| +|**Volumes**
*optional*|An object mapping mount point paths inside the container to empty objects.|< string, object > map| +|**WorkingDir**
*optional*|The working directory for commands to run in.|string| + + ### DeviceMapping A device mapping between the host and container @@ -1549,7 +1620,7 @@ Container configuration that depends on the host we are running on |**OomScoreAdj**
*optional*|An integer value containing the score given to the container in order to tune OOM killer preferences.
**Example** : `500`|integer| |**PidMode**
*optional*|Set the PID (Process) Namespace mode for the container. It can be either:
- `"container:"`: joins another container's PID namespace
- `"host"`: use the host's PID namespace inside the container|string| |**PidsLimit**
*optional*|Tune a container's pids limit. Set -1 for unlimited. Only on Linux 4.4 does this paramter support.|integer (int64)| -|**PortBindings**
*optional*|A map of exposed container ports and the host port they should map to.|< string, [PortBinding](#portbinding) > map| +|**PortBindings**
*optional*|A map of exposed container ports and the host port they should map to.|[PortMap](#portmap)| |**Privileged**
*optional*|Gives the container full access to the host.|boolean| |**PublishAllPorts**
*optional*|Allocates a random host port for all of a container's exposed ports.|boolean| |**ReadonlyRootfs**
*optional*|Mount the container's root filesystem as read only.|boolean| diff --git a/docs/commandline/pouch.md b/docs/commandline/pouch.md index 5fa3b334a..5cbf5113b 100644 --- a/docs/commandline/pouch.md +++ b/docs/commandline/pouch.md @@ -39,6 +39,7 @@ pouch is a client side tool pouch to interact with daemon side process pouchd. F * [pouch stop](pouch_stop.md) - Stop a running container * [pouch unpause](pouch_unpause.md) - Unpause a paused container * [pouch update](pouch_update.md) - Update the configurations of a container +* [pouch upgrade](pouch_upgrade.md) - Upgrade a container with new image and args * [pouch version](pouch_version.md) - Print versions about Pouch CLI and Pouchd * [pouch volume](pouch_volume.md) - Manage pouch volumes diff --git a/docs/commandline/pouch_create.md b/docs/commandline/pouch_create.md index c9677eb8c..8f70564cf 100644 --- a/docs/commandline/pouch_create.md +++ b/docs/commandline/pouch_create.md @@ -36,6 +36,7 @@ container ID: e1d541722d68dc5d133cca9e7bd8fd9338603e1763096c8e853522b60d11f7b9, --enableLxcfs Enable lxcfs for the container, only effective when enable-lxcfs switched on in Pouchd --entrypoint string Overwrite the default ENTRYPOINT of the image -e, --env strings Set environment variables for container + --expose strings Set expose container's ports -h, --help help for create --hostname string Set container's hostname --initscript string Initial script executed in container @@ -51,6 +52,7 @@ container ID: e1d541722d68dc5d133cca9e7bd8fd9338603e1763096c8e853522b60d11f7b9, --name string Specify name of container --net strings Set networks to container --pid string PID namespace to use + -p, --port strings Set container ports mapping --privileged Give extended privileges to the container --restart string Restart policy to apply when container exits --rich Start container in rich container mode. (default false) diff --git a/docs/commandline/pouch_image_inspect.md b/docs/commandline/pouch_image_inspect.md index a418d983a..d9432f415 100644 --- a/docs/commandline/pouch_image_inspect.md +++ b/docs/commandline/pouch_image_inspect.md @@ -27,7 +27,8 @@ $ pouch image inspect docker.io/library/busybox ### Options ``` - -h, --help help for inspect + -f, --format string Format the output using the given go template + -h, --help help for inspect ``` ### Options inherited from parent commands diff --git a/docs/commandline/pouch_network_inspect.md b/docs/commandline/pouch_network_inspect.md index 03c1a66b1..41b960eb6 100644 --- a/docs/commandline/pouch_network_inspect.md +++ b/docs/commandline/pouch_network_inspect.md @@ -25,7 +25,8 @@ Internal: false ### Options ``` - -h, --help help for inspect + -f, --format string Format the output using the given go template + -h, --help help for inspect ``` ### Options inherited from parent commands diff --git a/docs/commandline/pouch_run.md b/docs/commandline/pouch_run.md index d3fa57edb..823dd96c8 100644 --- a/docs/commandline/pouch_run.md +++ b/docs/commandline/pouch_run.md @@ -50,6 +50,7 @@ crw-rw-rw- 1 root root 1, 3 Jan 8 09:40 /dev/testnull --enableLxcfs Enable lxcfs for the container, only effective when enable-lxcfs switched on in Pouchd --entrypoint string Overwrite the default ENTRYPOINT of the image -e, --env strings Set environment variables for container + --expose strings Set expose container's ports -h, --help help for run --hostname string Set container's hostname --initscript string Initial script executed in container @@ -66,6 +67,7 @@ crw-rw-rw- 1 root root 1, 3 Jan 8 09:40 /dev/testnull --name string Specify name of container --net strings Set networks to container --pid string PID namespace to use + -p, --port strings Set container ports mapping --privileged Give extended privileges to the container --restart string Restart policy to apply when container exits --rich Start container in rich container mode. (default false) diff --git a/docs/commandline/pouch_update.md b/docs/commandline/pouch_update.md index f317abe2c..c7ce230f1 100644 --- a/docs/commandline/pouch_update.md +++ b/docs/commandline/pouch_update.md @@ -4,12 +4,25 @@ Update the configurations of a container ### Synopsis -Update the configurations of a container +Update a container's configurations, including memory, cpu and diskquota etc. You can update a container when it is running. ``` pouch update [OPTIONS] CONTAINER ``` +### Examples + +``` +$ pouch run -d -m 20m --name test-update registry.hub.docker.com/library/busybox:latest +8649804cb63ff9713a2734d99728b9d6d5d1e4d2fbafb2b4dbdf79c6bbaef812 +$ cat /sys/fs/cgroup/memory/8649804cb63ff9713a2734d99728b9d6d5d1e4d2fbafb2b4dbdf79c6bbaef812/memory.limit_in_bytes +20971520 +$ pouch update -m 30m test-update +$ cat /sys/fs/cgroup/memory/8649804cb63ff9713a2734d99728b9d6d5d1e4d2fbafb2b4dbdf79c6bbaef812/memory.limit_in_bytes +31457280 + +``` + ### Options ``` diff --git a/docs/commandline/pouch_upgrade.md b/docs/commandline/pouch_upgrade.md new file mode 100644 index 000000000..d65f2d93f --- /dev/null +++ b/docs/commandline/pouch_upgrade.md @@ -0,0 +1,77 @@ +## pouch upgrade + +Upgrade a container with new image and args + +### Synopsis + +Upgrade a container with new image and args + +``` +pouch upgrade [OPTIONS] IMAGE [COMMAND] [ARG...] +``` + +### Options + +``` + --blkio-weight uint16 Block IO (relative weight), between 10 and 1000, or 0 to disable + --blkio-weight-device value Block IO weight (relative device weight) (default []) + --cap-add strings Add Linux capabilities + --cap-drop strings Drop Linux capabilities + --cgroup-parent string Optional parent cgroup for the container (default "default") + --cpu-share int CPU shares (relative weight) + --cpuset-cpus string CPUs in which to allow execution (0-3, 0,1) + --cpuset-mems string MEMs in which to allow execution (0-3, 0,1) + --device strings Add a host device to the container + --device-read-bps value Limit read rate (bytes per second) from a device (default []) + --device-read-iops value Limit read rate (IO per second) from a device (default []) + --device-write-bps value Limit write rate (bytes per second) from a device (default []) + --device-write-iops value Limit write rate (IO per second) from a device (default []) + --enableLxcfs Enable lxcfs for the container, only effective when enable-lxcfs switched on in Pouchd + --entrypoint string Overwrite the default ENTRYPOINT of the image + -e, --env strings Set environment variables for container + --expose strings Set expose container's ports + -h, --help help for upgrade + --hostname string Set container's hostname + --initscript string Initial script executed in container + --intel-rdt-l3-cbm string Limit container resource for Intel RDT/CAT which introduced in Linux 4.10 kernel + --ipc string IPC namespace to use + -l, --label strings Set labels for a container + -m, --memory string Memory limit + --memory-extra int Represent container's memory high water mark percentage, range in [0, 100] + --memory-force-empty-ctl int Whether to reclaim page cache when deleting the cgroup of container + --memory-swap string Swap limit equal to memory + swap, '-1' to enable unlimited swap + --memory-swappiness int Container memory swappiness [0, 100] (default -1) + --memory-wmark-ratio int Represent this container's memory low water mark percentage, range in [0, 100]. The value of memory low water mark is memory.limit_in_bytes * MemoryWmarkRatio + --name string Specify name of container + --net strings Set networks to container + --pid string PID namespace to use + -p, --port strings Set container ports mapping + --privileged Give extended privileges to the container + --restart string Restart policy to apply when container exits + --rich Start container in rich container mode. (default false) + --rich-mode string Choose one rich container mode. dumb-init(default), systemd, sbin-init + --runtime string OCI runtime to use for this container + --sche-lat-switch int Whether to enable scheduler latency count in cpuacct + --security-opt strings Security Options + --sysctl strings Sysctl options + -t, --tty Allocate a pseudo-TTY + -u, --user string UID + --uts string UTS namespace to use + -v, --volume strings Bind mount volumes to container + -w, --workdir string Set the working directory in a container +``` + +### Options inherited from parent commands + +``` + -H, --host string Specify connecting address of Pouch CLI (default "unix:///var/run/pouchd.sock") + --tlscacert string Specify CA file of TLS + --tlscert string Specify cert file of TLS + --tlskey string Specify key file of TLS + --tlsverify Use TLS and verify remote +``` + +### SEE ALSO + +* [pouch](pouch.md) - An efficient container engine + diff --git a/docs/commandline/pouch_volume_inspect.md b/docs/commandline/pouch_volume_inspect.md index 0bbbd5eae..9f119ef1a 100644 --- a/docs/commandline/pouch_volume_inspect.md +++ b/docs/commandline/pouch_volume_inspect.md @@ -24,7 +24,8 @@ Driver: local ### Options ``` - -h, --help help for inspect + -f, --format string Format the output using the given go template + -h, --help help for inspect ``` ### Options inherited from parent commands