From b6175282e1c20505d79b3d66517bd0d06226ec78 Mon Sep 17 00:00:00 2001 From: Michael Wan Date: Mon, 26 Mar 2018 10:41:51 -0400 Subject: [PATCH] doc: remove trailing spaces and repace tab to 4 spaces Signed-off-by: Michael Wan --- .circleci/config.yml | 6 +- CHANGELOG.md | 4 +- CONTRIBUTING.md | 14 +- FAQ.md | 30 +- INSTALLATION.md | 476 +++++++++--------- MAINTAINERS.md | 2 +- README.md | 21 +- ROADMAP.md | 2 +- ctrd/README.md | 4 +- docs/README.md | 12 +- docs/architecture.md | 2 +- docs/contributions/code_styles.md | 4 +- docs/features/pouch_with_dragonfly.md | 23 +- docs/features/pouch_with_lxcfs.md | 5 +- docs/features/pouch_with_plugin.md | 63 ++- docs/features/pouch_with_prometheus.md | 6 +- docs/features/pouch_with_rich_container.md | 114 ++--- docs/features/pouch_with_runV.md | 2 +- docs/features/pouch_with_tls.md | 3 +- .../kubernetes/pouch_with_cri_introduction.md | 2 +- .../kubernetes/pouch_with_cri_verification.md | 4 + .../pouch_with_kubernetes_deploying.md | 25 +- docs/test/debug_in_travis.md | 40 +- docs/test/test.md | 66 +-- hack/package/README.md | 18 +- volume/README.md | 59 ++- 26 files changed, 535 insertions(+), 472 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 3415d7603..09f269567 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -7,7 +7,7 @@ jobs: docker: # specify the version - image: allencloud/mdl:v0.4 - + # Specify service dependencies here if necessary # CircleCI maintains a library of pre-built images # documented at https://circleci.com/docs/2.0/circleci-images/ @@ -22,6 +22,6 @@ jobs: - checkout # specify any bash command here prefixed with `run: ` - - run: + - run: name: use markdownlint v0.4.0 to lint markdown file (https://github.com/markdownlint/markdownlint) - command: find ./ -name "*.md" | grep -v vendor | grep -v extra | grep -v commandline | grep -v .github | grep -v swagger | grep -v api | xargs mdl + command: find ./ -name "*.md" | grep -v vendor | grep -v extra | grep -v commandline | grep -v .github | grep -v swagger | grep -v api | xargs mdl -r ~MD013,~MD024,~MD029,~MD036 diff --git a/CHANGELOG.md b/CHANGELOG.md index 8fc097beb..48c8dd44e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,4 @@ -# CHANGELOG +# CHANGELOG ## 0.2.1 (2018-03-09) @@ -74,4 +74,4 @@ Initial experiemental release for public * Be consistent with Moby's 1.12.6 API * Support basic network management and volume management * Make Pouch run as a system service -* Make Pouch installed on distribution CentOS 7.2 and Ubuntu 16.04 +* Make Pouch installed on distribution CentOS 7.2 and Ubuntu 16.04 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a574f0140..11d1ff679 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,7 +38,7 @@ Also we must remind that when filing a new issue, please remember to remove the ## Code and doc contribution -Every action to make project Pouch better is encouraged. On GitHub, every improvement for Pouch could be via a PR (short for pull request). +Every action to make project Pouch better is encouraged. On GitHub, every improvement for Pouch could be via a PR (short for pull request). * If you find a typo, try to fix it! * If you find a bug, try to fix it! @@ -51,7 +51,7 @@ Every action to make project Pouch better is encouraged. On GitHub, every improv * If you find document incorrect, just do it and fix that! * ... -Actually it is impossible to list them completely. Just remember one princinple: +Actually it is impossible to list them completely. Just remember one princinple: > WE ARE LOOKING FORWARD TO ANY PR FROM YOU. @@ -68,15 +68,17 @@ To put forward a PR, we assume you have registered a GitHub ID. Then you could f 1. **FORK** Pouch to your repository. To make this work, you just need to click the button Fork in right-left of [alibaba/pouch](https://github.com/alibaba/pouch) main page. Then you will end up with your repository in `https://github.com//pouch`, in which `your-username` is your GitHub username. -2. **CLONE** your own repository to develop locally. Use `git clone https://github.com//pouch.git` to clone repository to your local machine. Then you can create new branches to finish the change you wish to make. +1. **CLONE** your own repository to develop locally. Use `git clone https://github.com//pouch.git` to clone repository to your local machine. Then you can create new branches to finish the change you wish to make. + +1. **Set Remote** upstream to be `https://github.com/alibaba/pouch.git` using the following two commands: -3. **Set Remote** upstream to be https://github.com/alibaba/pouch.git using the following two commands: ``` git remote add upstream https://github.com/alibaba/pouch.git git remote set-url --push upstream no-pushing ``` With this remote setting, you can check you git remote configuration like this: + ``` $ git remote -v origin https://github.com//pouch.git (fetch) @@ -108,7 +110,7 @@ Actually in Pouch, we take two rules serious when committing: #### Commit Message -Commit message could help reviewers better understand what is the purpose of submitted PR. It could help accelerate the code review procedure as well. We encourage contributors to use **EXPLICIT** commit message rather than ambiguous message. In general, we advocate the following commit message type: +Commit message could help reviewers better understand what is the purpose of submitted PR. It could help accelerate the code review procedure as well. We encourage contributors to use **EXPLICIT** commit message rather than ambiguous message. In general, we advocate the following commit message type: * docs: xxxx. For example, "docs: add docs about storage installation". * feature: xxxx.For example, "feature: make result show in sorted order". @@ -132,7 +134,7 @@ Commit content represents all content changes included in one commit. We had bet In addition, in the code change part, we suggest that all contributors should read the [code style of Pouch](docs/contributions/code_styles.md). -No matter commit message, or commit content, we do take more emphasis on code review. +No matter commit message, or commit content, we do take more emphasis on code review. ### PR Description diff --git a/FAQ.md b/FAQ.md index bc5767279..a49bbf4a0 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,47 +1,47 @@ # Frequently Asked Questions -## What is Pouch project? +## What is Pouch project Pouch is a tool providing container services for developers and operators. It helps to build a successful work flow for IT engineering teams. Pouch also accelerates DevOps innovations for enterprises. -For developers, Pouch provides a standard way to package their applications. With Pouch, developers can pack application with little effort, and run it everywhere. The standarized environment provided by Pouch makes it easier to run Continuous Integration, and improves the efficiency of Continuous Delivery. +For developers, Pouch provides a standard way to package their applications. With Pouch, developers can pack application with little effort, and run it everywhere. The standarized environment provided by Pouch makes it easier to run Continuous Integration, and improves the efficiency of Continuous Delivery. For operators, Pouch enables automation, and largely reduces manual operations. With Pouch, operators no longer worry about the heterogeneous machine architeture and environments. Pouch enables them to focus more on application operation. For data center owners, Pouch is the best choice you ever have. Compared to VM technology, Pouch helps increase the resource utilization with the similar level of isolation. -## Why is it named Pouch? +## Why is it named Pouch Pouch refers to some kinds of small bags. One kind is brood pouch which is used to protect very young life. This is a metaphor that Software Pouch has its responsibilty to take care of applications very closely. In another word, application is the keyword in Pouch's world. -## What is the history of Pouch? +## What is the history of Pouch -Originally in 2011, Pouch is a pure container service in Alibaba. It is used to serve millions of trade business of Taobao. At that time, Pouch is based on a technology named by [LXC](https://en.wikipedia.org/wiki/LXC). +Originally in 2011, Pouch is a pure container service in Alibaba. It is used to serve millions of trade business of Taobao. At that time, Pouch is based on a technology named by [LXC](https://en.wikipedia.org/wiki/LXC). With the evolution of container technology in industry, [Docker](https://www.docker.com/) technology comes up and becomes popular with its inovative layered image technology. In 2015, Pouch introduces docker's images technology to its own architeture to make itself much stronger. As more and more scenes experience, Pouch gets lots of polishes and denifitely turns production-ready. Currently it supports most of the running of business in Alibaba. -## What is the role of Pouch in container ecosystem? +## What is the role of Pouch in container ecosystem Maybe many people would say that container ecosystem has been very mature. What is the role of Pouch? -First, we admit there are so many software in container ecosystem. However, according to container technology experience in Alibaba, current ecosystem is good, but can be better, especially on the attitude towards application as container engine. So Pouch is a lighter and more useful container engine in ecosystem. +First, we admit there are so many software in container ecosystem. However, according to container technology experience in Alibaba, current ecosystem is good, but can be better, especially on the attitude towards application as container engine. So Pouch is a lighter and more useful container engine in ecosystem. In the underlying support of container runtime, Pouch takes such opinion that lighter VM based on hypervisor is as important as container based on kernel support, such as cgroup and namespace. We can say container engine part of Pouch is very pure. More responsibility on container orchestration relies on upper orchestration technologies, like [Kubernetes](https://github.com/kubernetes/kubernetes), [Mesos](https://github.com/apache/mesos). -## What is difference between Pouch and Docker? +## What is difference between Pouch and Docker -Pouch and Docker are both excellent container solution for users. They do similar things if comparing them at a glance. But more specifically, they have different emphasize on each one's target. Pouch takes more emphasis on application experience, while Docker advocates "one process one container" a lot. Pouch cannot ignore isolation threat of container technology in some particular scenes, while Docker relies on kernel to achieve isolation heavily. Pouch brings an open attitude for the surrounding ecosystem, while docker also works on this but maybe not so much. +Pouch and Docker are both excellent container solution for users. They do similar things if comparing them at a glance. But more specifically, they have different emphasize on each one's target. Pouch takes more emphasis on application experience, while Docker advocates "one process one container" a lot. Pouch cannot ignore isolation threat of container technology in some particular scenes, while Docker relies on kernel to achieve isolation heavily. Pouch brings an open attitude for the surrounding ecosystem, while docker also works on this but maybe not so much. -Here we list some additional features of Pouch: +Here we list some additional features of Pouch: * rich container: It means that there is not only one application process in container any more. Each container has its init process, and other systsem services on premise according to user's need. * strong isolation: Pouch can create a VM with hypervisor technology via [runV](https://github.com/hyperhq/runv) and [clearcontainer](https://github.com/clearcontainers/runtime) * high kernel compatibility: Pouch has a wide range of kernel version support. It is a long road for industry to upgrade kernel version to 3.10+. Pouch could help legacy kernel world to enjoy the fresh container technology. * P2P image distribution: In a very large datacenter, image distribution is heavy load for network. Pouch can take advantage of P2P image distribution solutions to improve this. -## What is the difference bewtween Pouch and Kubernetes? +## What is the difference bewtween Pouch and Kubernetes Kubernetes is an open source project for managing containerized applications across multiple hosts, providing basic mechanisms for deployment, maintenance, and scaling of applications. While Pouch mainly focuses on container management with a rich container runtime diversity. For clearer relationship between Pouch and Kubernetes, you can refer to [Ecosystem Architecture](docs/architecture.md#ecosystem-architecture). @@ -49,21 +49,21 @@ If you are choosing overall container solution for a 100+ nodes cluster wide sce What is more, in data center's architecture, Kubernetes and Pouch locate in different layers. We can say that Kubernete is in the upper layer torwards Pouch. Actually we can combine Kubernetes and Pouch in a very efficient way. Pouch takes a role of runtime solution, and Kubernetes plays a role of orchestration. Pouch takes over fine-grained resource from infrastucture, like CPU, memory, network, disk and so on. Then it provides these resource metrics to upper Kubernetes for scheduling usage. When Kubernetes runs to meet application's maintenance demand, it can pass the request down to Pouch to provide secure and isolated container carriers for applications. -## What is Pouch's rich container? +## What is Pouch's rich container Rich container is a very useful container mode when containerizing applications. This mode helps technical staff to complete packaging fat applications almost with no effort. It provides efficient ways to equip more basic software or system services except for target application in a single container . Then applications in containers could be running as smoothly as usual in VM or physical machine. This is a more generlized application-centric mode. This mode brings no invasiveness at all to both developers and operators. Especially for operators, they could have abilities to maintain applications in container with all essential tools or service processes they may need as usual. Rich container mode is not the default mode Pouch provides. It is an additional mode pouch brings to extend users' container experience. Users can still manage ordinary containers by switching rich container flag off. -## What is version rule of Pouch ? +## What is version rule of Pouch We set the version rule of Pouch on the basis of [SemVer](http://semver.org/). Briefly speaking, we follow version number of MAJOR.MINOR.PATCH, such as 0.2.1, 1.1.3. For more details, please refer to [SemVer](http://semver.org/). -## What is the roadmap of Pouch? +## What is the roadmap of Pouch See [ROADMAP.md](./ROADMAP.md) -## How to contribute to Pouch? +## How to contribute to Pouch It is warmly welcomed if you have interest to contribute to Pouch. diff --git a/INSTALLATION.md b/INSTALLATION.md index da0053eac..b2801ed8c 100644 --- a/INSTALLATION.md +++ b/INSTALLATION.md @@ -1,239 +1,237 @@ -# Quick-Start - -Two quick-starts are provided, one for end-users, the other one for developers. - -As an end user who wish to use Pouch, please read [End User Quick-Start](#end-user-quick-start) to install and explore Pouch. - -As a developer who wish to hack on Pouch, please read [Developer Quick-Start](#developer-quick-start) to start hacking and get invloved in the project! - -## End User Quick-Start - -You can install Pouch automatically on your machine with very few steps. Currently we support two kinds of Linux Distribution: Ubuntu and CentOS. - -### Ubuntu - -To install Pouch, you need a maintained version of Ubuntu 16.04 (Xenial LTS). Archived versions aren’t supported or tested. - -Pouch is conflict with Docker, so you must uninstall Docker before installing Pouch. - -**Prerequisites** - -Pouch supports lxcfs to provide strong isolation, so you should install lxcfs firstly. By default, lxcfs is enabled. - - ```bash -sudo apt-get install lxcfs -``` - -Install packages to allow 'apt' to use a repository over HTTPS: - -```bash -sudo apt-get install curl apt-transport-https ca-certificates software-properties-common -``` - -**1. Add Pouch's official GPG key** - -```bash -curl -fsSL http://mirrors.aliyun.com/opsx/pouch/linux/debian/opsx@service.alibaba.com.gpg.key | sudo apt-key add - -``` - -Verify that you now have the key with the fingerprint `B615 DDD7 90C7 0912 582D DC2D D7AE A5ED 439A E9EC`, by searching for the last 8 characters of the fingerprint. - -```bash -$ apt-key fingerprint 439AE9EC - -pub 2048R/439AE9EC 2018-01-31 - Key fingerprint = B615 DDD7 90C7 0912 582D DC2D D7AE A5ED 439A E9EC -uid Pouch Release -sub 2048R/B3D2A915 2018-01-31 -``` - -**2. Set up the pouch repository** - -Before you install Pouch for the first time on a new host machine, you need to set up the Pouch repository. We enabled `stabel` repository by default, you always need the `stable` repository. To add the `test` repository, add the word `test` after the word `stable` in the command line below. Afterward, you can install and update Pouch from the repository. - -```bash -sudo add-apt-repository "deb http://mirrors.aliyun.com/opsx/pouch/linux/debian/ pouch stable" -``` - -**3. Install pouch** - -Install the latest version of Pouch. - -```bash -# update the apt package index -sudo apt-get update - -sudo apt-get install pouch -``` - -After installing Pouch, the `pouch` group is created, but no users are added to the group. - -**4. Start pouch** - -```bash -sudo service pouch start -``` - -Afterwards, you can pull an image and run Pouch containers. - -**5. Uninstall pouch** - -```bash -sudo apt-get purge pouch -``` - -After uninstalling Pouch, images, containers, volumes, or customized configuration files on your host are not automatically removed. To delete all images, containers and volumes, execute the following command: - -```bash -sudo rm -rf /var/lib/pouch -``` - -### CentOS - -To install Pouch, you need a maintained version of CentOS 7. Archived versions aren’t supported or tested. - -We have put rpm package to Aliyun mirrors, you can install pouch using Pouch repository. If you install Pouch for the first on a new host machine, you need to set up the Pouch repository. Then, you can install and update Pouch from repository. - -**1.Install yum-utils** - -Install required packages. yum-utils provides the yum-config-manager utility. - -```bash -sudo yum install -y yum-utils -``` - -**2. Set up the pouch repository** - -Use the following command to add Pouch repository. - -```bash -sudo yum-config-manager --add-repo http://mirrors.aliyun.com/opsx/opsx-centos7.repo -sudo yum update -``` - -Note: The above command set up the `stable` repository, you can enable `test` repository by the following command. - -```bash -sudo yum-config-manager --enable pouch-test -``` -You can disable the `test` repository by running the `yum-config-manager` command with the `--disable` flag. To re-enable it, use the `--enable` flag. The following command disables the test repository. - -```bash -sudo yum-config-manager --disable pouch-test -``` - -**3. Install pouch** - -Run the following command to install the latest version of Pouch. If it's the first time to install Pouch on your host, you will be prompted to accept the GPG key, and the key's fingerprint will be shown. - -```bash -sudo yum install pouch -``` - -After installing Pouch, the `pouch` group is created, but no users are added to the group. - -**4. Start pouch** - -```bash -sudo systemctl start pouch -``` - -Afterwards, you can pull an image and run Pouch containers. - -**5. Uninstall pouch** - -```bash -sudo yum remove pouch -``` - -After running the `remove` command, images, containers, volumes, or customized configuration files on your host are not automatically removed. To delete all images, containers and volumes, execute the following command: - -```bash -sudo rm -rf /var/lib/pouch -``` - -## Developer Quick-Start - -This guide provides step by step instructions to deploy Pouch on bare metal servers or virtual machines. -As a developer, you may need to build and test Pouch binaries via source code. To build pouchd which is so-called "pouch daemon" and pouch which is so-called "pouch cli", the following build system dependencies are required: - -* Linux Kernel 3.10+ -* Go 1.9.0+ -* containerd: 1.0.0 -* runc: 1.0.0-rc4 -* runv: 1.0.0 (option) - -### Prerequisites Installation - -Since pouchd is a kind of container engine, and pouch is a cli tool, if you hope to experience container management ability via Pouch, there are several additional binaries needed: - -* [containerd](https://github.com/containerd/containerd): an industry-standard container runtime; -* [runc](https://github.com/opencontainers/runc): a CLI tool for spawning and running containers according to the OCI specification; -* [runv](https://github.com/hyperhq/runv): a hypervisor-based runtime for OCI. - -Here are the shell scripts to install `containerd` and `runc`: - -``` shell -# install containerd -$ wget https://github.com/containerd/containerd/releases/download/v1.0.0/containerd-1.0.0.linux-amd64.tar.gz -$ tar -xzvf containerd-1.0.0.linux-amd64.tar.gz -C /usr/local -$ -# install runc -$ wget https://github.com/opencontainers/runc/releases/download/v1.0.0-rc4/runc.amd64 -P /usr/local/bin -$ chmod +x /usr/local/bin/runc.amd64 -$ mv /usr/local/bin/runc.amd64 /usr/local/bin/runc - -``` - -### runV Installation - -If you wish to experience hypervisor-based virtualization additionally, you will still need to install [runV](https://github.com/hyperhq/runv). - -More guide on experiencing Pouch with runV including runv Installation, please refer to [pouch run with runv guide](docs/features/pouch_with_runV.md). - -### Pouch Build and Installation - -With all prerequisites installed, you can build and install pouch daemon and pouch cli. Clone the repository and checkout whichever branch you like (in the following example, checkout branch master): - -``` shell -$ mkdir -p $GOPATH/src/github.com/alibaba/ -$ cd $GOPATH/src/github.com/alibaba/; git clone https://github.com/alibaba/pouch.git -$ cd pouch; git checkout master -``` - -Makefile target named `build` will compile the pouch and pouchd binaries in current work directory. Or you can just execute `make install` to build binaries and install them in destination directory (`/usr/local/bin` by default). - -``` shell -$ make install -``` - -### Start Pouch - -With all needed binaries installed, you could start pouchd via: - -``` shell -$ pouchd -INFO[0000] starting containerd module=containerd revision=a543c937eb0a05e1636714ee2be70819d745b960 version=v1.0.0-beta.2 -INFO[0000] setting subreaper... module=containerd -INFO[0000] loading plugin "io.containerd.content.v1.content"... module=containerd type=io.containerd.content.v1 -INFO[0000] loading plugin "io.containerd.snapshotter.v1.btrfs"... module=containerd type=io.containerd.snapshotter.v1 -WARN[0000] failed to load plugin io.containerd.snapshotter.v1.btrfs error="path /var/lib/containerd/io.containerd.snapshotter.v1.btrfs must be a btrfs filesystem to be used with the btrfs snapshotter" module=containerd -INFO[0000] loading plugin "io.containerd.snapshotter.v1.overlayfs"... module=containerd type=io.containerd.snapshotter.v1 -INFO[0000] loading plugin "io.containerd.metadata.v1.bolt"... module=containerd type=io.containerd.metadata.v1 -WARN[0000] could not use snapshotter btrfs in metadata plugin error="path /var/lib/containerd/io.containerd.snapshotter.v1.btrfs must be a btrfs filesystem to be used with the btrfs snapshotter" module="containerd/io.containerd.metadata.v1.bolt" -INFO[0000] loading plugin "io.containerd.differ.v1.walking"... module=containerd type=io.containerd.differ.v1 -INFO[0000] loading plugin "io.containerd.grpc.v1.containers"... module=containerd type=io.containerd.grpc.v1 -``` - -After pouchd's running, you could interact with pouchd by pouch cli: - -``` -$ pouch images -IMAGE ID IMAGE NAME SIZE -3e8fa85ddfef docker.io/library/busybox:latest 2699 -504cf109b492 docker.io/library/redis:alpine 2035 -``` - -## Feedback - -We hope this guide would help you get up and run with Pouch. And feel free to send feedback via [ISSUE](https://github.com/alibaba/pouch/issues/new), if you have any questions. If you wish to contribute to Pouch on this guide, please just submit a pull request. +# Quick-Start + +Two quick-starts are provided, one for end-users, the other one for developers. + +As an end user who wish to use Pouch, please read [End User Quick-Start](#end-user-quick-start) to install and explore Pouch. + +As a developer who wish to hack on Pouch, please read [Developer Quick-Start](#developer-quick-start) to start hacking and get invloved in the project! + +## End User Quick-Start + +You can install Pouch automatically on your machine with very few steps. Currently we support two kinds of Linux Distribution: Ubuntu and CentOS. + +### Ubuntu + +To install Pouch, you need a maintained version of Ubuntu 16.04 (Xenial LTS). Archived versions aren’t supported or tested. + +Pouch is conflict with Docker, so you must uninstall Docker before installing Pouch. + +**Prerequisites** + +Pouch supports lxcfs to provide strong isolation, so you should install lxcfs firstly. By default, lxcfs is enabled. + +``` bash +sudo apt-get install lxcfs +``` + +Install packages to allow 'apt' to use a repository over HTTPS: + +``` bash +sudo apt-get install curl apt-transport-https ca-certificates software-properties-common +``` + +**1. Add Pouch's official GPG key** + +``` bash +curl -fsSL http://mirrors.aliyun.com/opsx/pouch/linux/debian/opsx@service.alibaba.com.gpg.key | sudo apt-key add - +``` + +Verify that you now have the key with the fingerprint `B615 DDD7 90C7 0912 582D DC2D D7AE A5ED 439A E9EC`, by searching for the last 8 characters of the fingerprint. + +``` bash +$ apt-key fingerprint 439AE9EC +pub 2048R/439AE9EC 2018-01-31 + Key fingerprint = B615 DDD7 90C7 0912 582D DC2D D7AE A5ED 439A E9EC +uid Pouch Release +sub 2048R/B3D2A915 2018-01-31 +``` + +**2. Set up the pouch repository** + +Before you install Pouch for the first time on a new host machine, you need to set up the Pouch repository. We enabled `stabel` repository by default, you always need the `stable` repository. To add the `test` repository, add the word `test` after the word `stable` in the command line below. Afterward, you can install and update Pouch from the repository. + +``` bash +sudo add-apt-repository "deb http://mirrors.aliyun.com/opsx/pouch/linux/debian/ pouch stable" +``` + +**3. Install pouch** + +Install the latest version of Pouch. + +``` bash +# update the apt package index +sudo apt-get update +sudo apt-get install pouch +``` + +After installing Pouch, the `pouch` group is created, but no users are added to the group. + +**4. Start pouch** + +``` bash +sudo service pouch start +``` + +Afterwards, you can pull an image and run Pouch containers. + +**5. Uninstall pouch** + +``` bash +sudo apt-get purge pouch +``` + +After uninstalling Pouch, images, containers, volumes, or customized configuration files on your host are not automatically removed. To delete all images, containers and volumes, execute the following command: + +``` bash +sudo rm -rf /var/lib/pouch +``` + +### CentOS + +To install Pouch, you need a maintained version of CentOS 7. Archived versions aren’t supported or tested. + +We have put rpm package to Aliyun mirrors, you can install pouch using Pouch repository. If you install Pouch for the first on a new host machine, you need to set up the Pouch repository. Then, you can install and update Pouch from repository. + +**1.Install yum-utils** + +Install required packages. yum-utils provides the yum-config-manager utility. + +``` bash +sudo yum install -y yum-utils +``` + +**2. Set up the pouch repository** + +Use the following command to add Pouch repository. + +``` bash +sudo yum-config-manager --add-repo http://mirrors.aliyun.com/opsx/opsx-centos7.repo +sudo yum update +``` + +Note: The above command set up the `stable` repository, you can enable `test` repository by the following command. + +``` bash +sudo yum-config-manager --enable pouch-test +``` + +You can disable the `test` repository by running the `yum-config-manager` command with the `--disable` flag. To re-enable it, use the `--enable` flag. The following command disables the test repository. + +``` bash +sudo yum-config-manager --disable pouch-test +``` + +**3. Install pouch** + +Run the following command to install the latest version of Pouch. If it's the first time to install Pouch on your host, you will be prompted to accept the GPG key, and the key's fingerprint will be shown. + +``` bash +sudo yum install pouch +``` + +After installing Pouch, the `pouch` group is created, but no users are added to the group. + +**4. Start pouch** + +``` bash +sudo systemctl start pouch +``` + +Afterwards, you can pull an image and run Pouch containers. + +**5. Uninstall pouch** + +``` bash +sudo yum remove pouch +``` + +After running the `remove` command, images, containers, volumes, or customized configuration files on your host are not automatically removed. To delete all images, containers and volumes, execute the following command: + +``` bash +sudo rm -rf /var/lib/pouch +``` + +## Developer Quick-Start + +This guide provides step by step instructions to deploy Pouch on bare metal servers or virtual machines. +As a developer, you may need to build and test Pouch binaries via source code. To build pouchd which is so-called "pouch daemon" and pouch which is so-called "pouch cli", the following build system dependencies are required: + +* Linux Kernel 3.10+ +* Go 1.9.0+ +* containerd: 1.0.0 +* runc: 1.0.0-rc4 +* runv: 1.0.0 (option) + +### Prerequisites Installation + +Since pouchd is a kind of container engine, and pouch is a cli tool, if you hope to experience container management ability via Pouch, there are several additional binaries needed: + +* [containerd](https://github.com/containerd/containerd): an industry-standard container runtime; +* [runc](https://github.com/opencontainers/runc): a CLI tool for spawning and running containers according to the OCI specification; +* [runv](https://github.com/hyperhq/runv): a hypervisor-based runtime for OCI. + +Here are the shell scripts to install `containerd` and `runc`: + +``` shell +# install containerd +$ wget https://github.com/containerd/containerd/releases/download/v1.0.0/containerd-1.0.0.linux-amd64.tar.gz +$ tar -xzvf containerd-1.0.0.linux-amd64.tar.gz -C /usr/local +$ +# install runc +$ wget https://github.com/opencontainers/runc/releases/download/v1.0.0-rc4/runc.amd64 -P /usr/local/bin +$ chmod +x /usr/local/bin/runc.amd64 +$ mv /usr/local/bin/runc.amd64 /usr/local/bin/runc +``` + +### runV Installation + +If you wish to experience hypervisor-based virtualization additionally, you will still need to install [runV](https://github.com/hyperhq/runv). + +More guide on experiencing Pouch with runV including runv Installation, please refer to [pouch run with runv guide](docs/features/pouch_with_runV.md). + +### Pouch Build and Installation + +With all prerequisites installed, you can build and install pouch daemon and pouch cli. Clone the repository and checkout whichever branch you like (in the following example, checkout branch master): + +``` shell +mkdir -p $GOPATH/src/github.com/alibaba/ +cd $GOPATH/src/github.com/alibaba/; git clone https://github.com/alibaba/pouch.git +cd pouch; git checkout master +``` + +Makefile target named `build` will compile the pouch and pouchd binaries in current work directory. Or you can just execute `make install` to build binaries and install them in destination directory (`/usr/local/bin` by default). + +``` shell +make install +``` + +### Start Pouch + +With all needed binaries installed, you could start pouchd via: + +``` shell +$ pouchd +INFO[0000] starting containerd module=containerd revision=a543c937eb0a05e1636714ee2be70819d745b960 version=v1.0.0-beta.2 +INFO[0000] setting subreaper... module=containerd +INFO[0000] loading plugin "io.containerd.content.v1.content"... module=containerd type=io.containerd.content.v1 +INFO[0000] loading plugin "io.containerd.snapshotter.v1.btrfs"... module=containerd type=io.containerd.snapshotter.v1 +WARN[0000] failed to load plugin io.containerd.snapshotter.v1.btrfs error="path /var/lib/containerd/io.containerd.snapshotter.v1.btrfs must be a btrfs filesystem to be used with the btrfs snapshotter" module=containerd +INFO[0000] loading plugin "io.containerd.snapshotter.v1.overlayfs"... module=containerd type=io.containerd.snapshotter.v1 +INFO[0000] loading plugin "io.containerd.metadata.v1.bolt"... module=containerd type=io.containerd.metadata.v1 +WARN[0000] could not use snapshotter btrfs in metadata plugin error="path /var/lib/containerd/io.containerd.snapshotter.v1.btrfs must be a btrfs filesystem to be used with the btrfs snapshotter" module="containerd/io.containerd.metadata.v1.bolt" +INFO[0000] loading plugin "io.containerd.differ.v1.walking"... module=containerd type=io.containerd.differ.v1 +INFO[0000] loading plugin "io.containerd.grpc.v1.containers"... module=containerd type=io.containerd.grpc.v1 +``` + +After pouchd's running, you could interact with pouchd by pouch cli: + +```bash +$ pouch images +IMAGE ID IMAGE NAME SIZE +3e8fa85ddfef docker.io/library/busybox:latest 2699 +504cf109b492 docker.io/library/redis:alpine 2035 +``` + +## Feedback + +We hope this guide would help you get up and run with Pouch. And feel free to send feedback via [ISSUE](https://github.com/alibaba/pouch/issues/new), if you have any questions. If you wish to contribute to Pouch on this guide, please just submit a pull request. diff --git a/MAINTAINERS.md b/MAINTAINERS.md index c73d6de0c..86cfe3824 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -5,7 +5,7 @@ |[allencloud](https://github.com/allencloud)|Allen Sun|shlallen1990@gmail.com| |[skoo87](https://github.com/skoo87)|Marcky Wu|marckywu@gmail.com| |[Letty5411](https://github.com/Letty5411)|Letty Liu|letty.ll@alibaba-inc.com| -|[rudyfly](https://github.com/rudyfly)|Rudy Zhang|rudyflyzhang@gmail.com| +|[rudyfly](https://github.com/rudyfly)|Rudy Zhang|rudyflyzhang@gmail.com| |[Ace-Tang](https://github.com/Ace-Tang)|Ace Tang|aceapril@126.com| |[YaoZengzeng](https://github.com/YaoZengzeng)|Zengzeng Yao|yaozengzeng@zju.edu.cn| |[sunyuan3](https://github.com/sunyuan3)|Yuan Sun|yile.sy@alibaba-inc.com | diff --git a/README.md b/README.md index 3a5c65908..08f55d63b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,5 @@ -Pouch - An Efficient Enterprise-class Rich Container Engine -================ +# Pouch - An Efficient Enterprise-class Rich Container Engine [![License](https://img.shields.io/badge/license-Apache%202-4EB1BA.svg)](https://www.apache.org/licenses/LICENSE-2.0.html) [![GoDoc](https://godoc.org/github.com/alibaba/pouch?status.svg)](https://godoc.org/github.com/alibaba/pouch) @@ -8,7 +7,7 @@ Pouch - An Efficient Enterprise-class Rich Container Engine [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Falibaba%2Fpouch.svg?type=shield)](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Falibaba%2Fpouch?ref=badge_shield) [![Go Report Card](https://goreportcard.com/badge/github.com/alibaba/pouch)](https://goreportcard.com/report/github.com/alibaba/pouch) - +[Pouch project logo]() ## Main Links @@ -17,8 +16,8 @@ Pouch - An Efficient Enterprise-class Rich Container Engine - [Architecture](#architecture) - [Getting Started](#getting-started) - User Manual - - [CLI Manual](docs/commandline) - - [API Manual](docs/api) + - [CLI Manual](docs/commandline) + - [API Manual](docs/api) - [Contributing](#contributing) ## Introduction @@ -51,17 +50,17 @@ Pouch has lots of advantages over VM technologies. Two of the most impressive on Pouch significantly improves resource utilization: -* Pouch is compatible with OCI image spec. Applications can minimize their storage usage with layered image structure. -* Incremental image distribution, saves datacenter bandwidth consumption. -* Significantly less runtime overhead than VM-based technologies. +- Pouch is compatible with OCI image spec. Applications can minimize their storage usage with layered image structure. +- Incremental image distribution, saves datacenter bandwidth consumption. +- Significantly less runtime overhead than VM-based technologies. ### Application Centric Pouch offers a more "application centric" approach for application development: -* Pouch provides strong runtime isolation between applications, with cutting-edge technology both within kernel support and beyond kernel mode. -* Pouch enables cross-platform and cross-OS application delivery. -* Pouch supports standardized application image spec, so application sharing and reusing becomes trivial for developers and operators. +- Pouch provides strong runtime isolation between applications, with cutting-edge technology both within kernel support and beyond kernel mode. +- Pouch enables cross-platform and cross-OS application delivery. +- Pouch supports standardized application image spec, so application sharing and reusing becomes trivial for developers and operators. ## Getting Started diff --git a/ROADMAP.md b/ROADMAP.md index cd62126f6..953fc030b 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -20,5 +20,5 @@ A lot of work has been done to improve container's security in industry. But con ## Enhancement to Ecosystem -For being open to container ecosystem, Pouch will be designed to be scalable. As a container engine, pouch will support pod and be able to integrate upper orchestraion layer with [kubernetes](https://github.com/kubernetes/kubernetes). For fundamental infrastructure management, pouch will embrace [CNI](https://github.com/containernetworking/cni) and [CSI](https://github.com/container-storage-interface). In the aspect of monitoring, logging and so on, Pouch takes an open role to approach cloud native. +For being open to container ecosystem, Pouch will be designed to be scalable. As a container engine, pouch will support pod and be able to integrate upper orchestraion layer with [kubernetes](https://github.com/kubernetes/kubernetes). For fundamental infrastructure management, pouch will embrace [CNI](https://github.com/containernetworking/cni) and [CSI](https://github.com/container-storage-interface). In the aspect of monitoring, logging and so on, Pouch takes an open role to approach cloud native. diff --git a/ctrd/README.md b/ctrd/README.md index a7b771010..f09167c04 100644 --- a/ctrd/README.md +++ b/ctrd/README.md @@ -1,4 +1,4 @@ -ctrd +# ctrd ctrd is a package to interact with containerd using containerd's exposed API. Pouch will vendor package containerd in repo [containerd/containerd](https://github.com/containerd/containerd) and [alibaba/containerd](https://github.com/containerd/containerd). @@ -12,4 +12,4 @@ Every time releasing Pouch to launch a new version, we vendor containerd/contain To check if the package we use is containerd/containerd or alibaba/containerd, we can refer to [vendor.json](../vendor/vendor.json). - + diff --git a/docs/README.md b/docs/README.md index 2b8b2b942..056531070 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,10 +8,10 @@ Organization of document is as following: * [Get Started](#get-started) * [Commandline](#commandline) * [API](#api) - * [HTTP API](#http-api) - * [HTTP API changelog](#http-api-changelog) - * [CRI gRPC API](#grpc-api) - * [CRI gRPC changelog](#grpc-api-changelog) + * [HTTP API](#http-api) + * [HTTP API changelog](#http-api-changelog) + * [CRI gRPC API](#grpc-api) + * [CRI gRPC changelog](#grpc-api-changelog) * [Kubernetes](#kubernetes) * [Contributions](#contributions) * [Test Guide](#test-guide) @@ -20,7 +20,7 @@ Organization of document is as following: ## Features -[Features](features) contains all features of Pouch. To enable a satisfying environment for user's applications, Pouch provides plenty of features, such as strong-isolation technology including hyper-based containers and lxcfs-base resource view isolation, rich container, P2P image distribution and so on. For more aspects, TLS-based security, prometheus supporting and more features also help Pouch be adoptive for enterprises. In addition, in all the document we illustrate what is the best scenario of the corresponding feature. +[Features](features) contains all features of Pouch. To enable a satisfying environment for user's applications, Pouch provides plenty of features, such as strong-isolation technology including hyper-based containers and lxcfs-base resource view isolation, rich container, P2P image distribution and so on. For more aspects, TLS-based security, prometheus supporting and more features also help Pouch be adoptive for enterprises. In addition, in all the document we illustrate what is the best scenario of the corresponding feature. ## Get Started @@ -32,7 +32,7 @@ For almost all of users, [commandline](./commandline) is the first reference you ## API -Commandline is the easiest way to extend Pouch's ability. And API extension will bring more powerful experience for users. +Commandline is the easiest way to extend Pouch's ability. And API extension will bring more powerful experience for users. ### HTTP API diff --git a/docs/architecture.md b/docs/architecture.md index 993511c76..c3766e182 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -22,7 +22,7 @@ Runtime layer is located on right-top in the architecture picture. This dimensio * runV * clear containers -With runC, Pouch creates common containers like other container engine does, for example docker. With runlxc, Pouch creates containers based on LXC. runlxc helps a lot when users need to run containers on a wide variety of Linux kernels with the ability to be compatible with kernel 2.6.32+. Hypervisor-based containers have many application scenarios as well. Pouch will support it with runV and clear container. +With runC, Pouch creates common containers like other container engine does, for example docker. With runlxc, Pouch creates containers based on LXC. runlxc helps a lot when users need to run containers on a wide variety of Linux kernels with the ability to be compatible with kernel 2.6.32+. Hypervisor-based containers have many application scenarios as well. Pouch will support it with runV and clear container. All these four runtimes mentioned above are supported under containerd. Containerd takes over all detailed container management, including creation, start, stop, deletion and so on. diff --git a/docs/contributions/code_styles.md b/docs/contributions/code_styles.md index a8c6c5a74..dec5c3634 100644 --- a/docs/contributions/code_styles.md +++ b/docs/contributions/code_styles.md @@ -18,7 +18,7 @@ When collaborating in Pouch project, we follow the style from [Go Code Review Co ## Additional Style Rules -For a project, existing tools and rules may not be sufficient. To align more in styles, we recommend contributors taking a thorough look at the following additional style rules: +For a project, existing tools and rules may not be sufficient. To align more in styles, we recommend contributors taking a thorough look at the following additional style rules: * When constructing a struct, if comments needed for fields in struct, keep a blank line between fields; * When defining interface functions, we should always explicitly add formal parameter, and this helps a lot to code readability; @@ -28,5 +28,5 @@ For a project, existing tools and rules may not be sufficient. To align more in * When generating error in an action failure, we should generally use the way of `fmt.Errorf("failed to do something: %v", err)`; * No matter log or error, first letter of the message must be lower-case; * When occuring nesting errors, we recommend first considering using package `github.com/pkg/errors`; -* Every comment should begin with `// `, and please don't forget the whitespace, and end with a `.`; +* Every comment should begin with `//` plus a space, and please don't forget the whitespace, and end with a `.`; * We should take `DRY(Don't Repeat Yourself)` into more consideration. diff --git a/docs/features/pouch_with_dragonfly.md b/docs/features/pouch_with_dragonfly.md index 292728229..bff7b38ee 100644 --- a/docs/features/pouch_with_dragonfly.md +++ b/docs/features/pouch_with_dragonfly.md @@ -2,7 +2,6 @@ Container technology is helpful to facilitate IT operation and maintenance, but the distribution of images has brought a huge challenge at the same time. The images can be as large as serveral Gibs, pulling images will be very slow, not to mention the situation lots of pulling requests simultaneously or low network bandwidth. Dragonfly can play an important role here, as a P2P technology, it provides very efficient distribution, avoiding images distribution as a bottleneck in container technology. - ## What is Dragonfly [Dragonfly](https://github.com/alibaba/Dragonfly#installation) is a P2P file distribution system. It solves the problems of time-consuming distribution, low success rate, and wasteful bandwidth in large-scale file distribution scenarios. Dragonfly significantly improves service capabilities such as data preheating, and large-scale container image distribution. @@ -17,18 +16,18 @@ Server consists of cluster managers, it download files from source and construct Client concludes two part: dfget and proxy. dfget is a host-side tool for downloading files, proxy is used for intercepted the http requests and route them to dfget. - ## Install dragonfly -1. install server +1.install server server can be deployed in two way, on the physical mechaine or on a container, the steps is simple in the [install dragonfly server](https://github.com/alibaba/Dragonfly/blob/master/docs/install_server.md) -2. install client +2.install client - Downloading [client package](https://github.com/alibaba/Dragonfly/blob/master/package/df-client.linux-amd64.tar.gz). -- untar the package `tar xzvf df-client.linux-amd64.tar.gz -C /usr/local/bin`, or you can untar it to any directory you like, but remember to add client path into PATH enviroment, `export PATH=$PATH:/usr/local/bin/df-client`. -- add server ip into client config file, `/etc/dragonfly.conf`, nodeIp is the host ip which you deploy server +- untar the package `tar xzvf df-client.linux-amd64.tar.gz -C /usr/local/bin`, or you can untar it to any directory you like, but remember to add client path into PATH enviroment, `export PATH=$PATH:/usr/local/bin/df-client`. +- add server ip into client config file, `/etc/dragonfly.conf`, nodeIp is the host ip which you deploy server + ``` [node] address=nodeIp1,nodeIp2,... @@ -38,21 +37,23 @@ about detail install information, you can find in [install dragonfly client](htt ## Run pouch with dragonfly -1. start dragonfly proxy +1.start dragonfly proxy -Start dragonfly proxy, `/usr/local/bin/df-client/df-daemon --registry https://reg.docker.alibaba-inc.com`, you can add flag `--verbose` to get debug log. Dragonfly logs can be found in +Start dragonfly proxy, `/usr/local/bin/df-client/df-daemon --registry https://reg.docker.alibaba-inc.com`, you can add flag `--verbose` to get debug log. Dragonfly logs can be found in directory `~/.small-dragonfly/logs`. More dragonfly usage information you can find in [dragonfly usage](https://github.com/alibaba/Dragonfly/blob/master/docs/usage.md) -2. add the following configuration in pouch config file `/etc/pouch/config.json` +2.add the following configuration in pouch config file `/etc/pouch/config.json` + ``` { - "image-proxy": "http://127.0.0.1:65001" + "image-proxy": "http://127.0.0.1:65001" } ``` -3. pull a image `reg.docker.alibaba-inc.com/base/busybox:latest`, you can find the following ouput in `~/.small-dragonfly/logs/dfdaemon.log`, which means dragonfly works. +3.pull a image `reg.docker.alibaba-inc.com/base/busybox:latest`, you can find the following ouput in `~/.small-dragonfly/logs/dfdaemon.log`, which means dragonfly works. + ``` time="2018-03-06 20:08:00" level=debug msg="pre access:http://storage.docker.aliyun-inc.com/docker/registry/v2/blobs/sha256/1b/1b5110ff48b0aa7112544e1666cc7199f812243ded4128f0a1b2be027c7 38bec/data?Expires=1520339335&OSSAccessKeyId=LTAIfYaNrksx0ktL&Signature=fVEYIQzIaXyqIcAhypbmzaUx5x8%3D" time="2018-03-06 20:08:00" level=debug msg="post access:http://storage.docker.aliyun-inc.com" diff --git a/docs/features/pouch_with_lxcfs.md b/docs/features/pouch_with_lxcfs.md index aaae2ea44..661b753b0 100644 --- a/docs/features/pouch_with_lxcfs.md +++ b/docs/features/pouch_with_lxcfs.md @@ -27,7 +27,6 @@ Resource view isolation will influence system-level applications in container. > Containers can also be used to package system-level applications, and system-level applications would usually need to get system information via Virtual File System `/proc`. If uptime is not the correct one of container but the host, system-level applications would be out of control or running in an unexpected way. `cpuinfo` and `meminfo` and some further system resource views are other aspects these applications need to consider. - ## What is LXCFS [LXCFS](https://github.com/lxc/lxcfs) is a small [FUSE filesystem](https://en.wikipedia.org/wiki/Filesystem_in_Userspace) written with the intention of making Linux containers feel more like a virtual machine. It started as a side-project of LXC but is useable by any runtime. LXCFS is compatible on Linux kernel 2.6+. And LXCFS will take care that the information provided by crucial files in `procfs` such as: @@ -47,13 +46,13 @@ Here is the architeture of LXCFS and container: ## Get Started -It is quite transparent and easy for users to enjoy resource view isolation by enabling LXCFS. Actually, software LXCFS would be automatically installed on host along with pouch software if it does not exist in $PATH. +It is quite transparent and easy for users to enjoy resource view isolation by enabling LXCFS. Actually, software LXCFS would be automatically installed on host along with pouch software if it does not exist in $PATH. Before experiencing LXCFS guranteed resouce view isolation, user needs to make sure that LXCFS mode is enabled in pouchd. If LXCFS mode has not been set, user needs to stop pouchd and start pouchd via command `pouchd --enable-lxcfs`. Only by enabling LXCFS mode in pouchd can users make use of LXCFS functionality in containers. With LXCFS mode enabled in pouchd, pouchd has extra ability to create containers which has isolated resource view. Besides this, pouchd is still capable to create general ones without resource view isolation. -At last, `--enableLxcfs` flag in command `pouch run` is the only way to make LXCFS work for created containers under pouch daemon which is already enabled LXCFS mode. Here we create a container with 200 MB memory limit on the host of 2 GB memory. +At last, `--enableLxcfs` flag in command `pouch run` is the only way to make LXCFS work for created containers under pouch daemon which is already enabled LXCFS mode. Here we create a container with 200 MB memory limit on the host of 2 GB memory. ``` shell $ pouch run -m 200m --enableLxcfs registry.hub.docker.com/library/ubuntu:16.04 free -h diff --git a/docs/features/pouch_with_plugin.md b/docs/features/pouch_with_plugin.md index be096b4af..f1d3299cc 100644 --- a/docs/features/pouch_with_plugin.md +++ b/docs/features/pouch_with_plugin.md @@ -1,36 +1,41 @@ # Pouch with plugin + In order to run custom code provided by users which will be triggered at some point, we support a plugin framework which introduced from golang 1.8. At this time in this plugin framework we enable users to add custom code at four point: + * pre-start daemon point * pre-stop daemon point * pre-create container point * pre-start container point Above four points are organized by two Plugin interfaces, which are DaemonPlugin and ContainerPlugin, defined as follow: + ``` // DaemonPlugin defines in which place does pouch daemon support plugin type DaemonPlugin interface { - // PreStartHook is invoked by pouch daemon before real start, in this hook user could start dfget proxy or other - // standalone process plugins - PreStartHook() error + // PreStartHook is invoked by pouch daemon before real start, in this hook user could start dfget proxy or other + // standalone process plugins + PreStartHook() error - // PreStopHook is invoked by pouch daemon before daemon process exit, not a promise if daemon is killed, in this - // hook user could stop the process or plugin started by PreStartHook - PreStopHook() error + // PreStopHook is invoked by pouch daemon before daemon process exit, not a promise if daemon is killed, in this + // hook user could stop the process or plugin started by PreStartHook + PreStopHook() error } // ContainerPlugin defines in which place a plugin will be triggered in container lifecycle type ContainerPlugin interface { - // PreCreate defines plugin point where receives an container create request, in this plugin point user - // could change the container create body passed-in by http request body - PreCreate(io.ReadCloser) (io.ReadCloser, error) + // PreCreate defines plugin point where receives an container create request, in this plugin point user + // could change the container create body passed-in by http request body + PreCreate(io.ReadCloser) (io.ReadCloser, error) - // PreStart returns an array of priority and args which will pass to runc, the every priority - // used to sort the pre start array that pass to runc, network plugin hook always has priority value 0. - PreStart(interface{}) ([]int, [][]string, error) + // PreStart returns an array of priority and args which will pass to runc, the every priority + // used to sort the pre start array that pass to runc, network plugin hook always has priority value 0. + PreStart(interface{}) ([]int, [][]string, error) } ``` + These two Plugin symbols will be fetch by name `DaemonPlugin` and `ContainerPlugin` from shared object file like this: + ``` p, _ := plugin.Open("path_to_shared_object_file") daemonPlugin, _ := p.Lookup("DaemonPlugin") @@ -38,13 +43,15 @@ containerPlugin, _ := p.Lookup("ContainerPlugin") ``` ## example + define two plugin symbols which only print some logs at correspond point: + ``` package main import ( - "fmt" - "io" + "fmt" + "io" ) var ContainerPlugin ContPlugin @@ -56,41 +63,47 @@ var DaemonPlugin DPlugin type DPlugin int func (d DPlugin) PreStartHook() error { - fmt.Println("pre-start hook in daemon is called") - return nil + fmt.Println("pre-start hook in daemon is called") + return nil } func (d DPlugin) PreStopHook() error { - fmt.Println("pre-stop hook in daemon is called") - return nil + fmt.Println("pre-stop hook in daemon is called") + return nil } func (c ContPlugin) PreCreate(in io.ReadCloser) (io.ReadCloser, error) { - fmt.Println("pre create method called") - return in, nil + fmt.Println("pre create method called") + return in, nil } func (c ContPlugin) PreStart(interface{}) ([]int, [][]string, error) { - fmt.Println("pre start method called") - // make this pre-start hook run after network in container setup - return []int{-4}, [][]string{{"/usr/bin/touch", "touch", "/tmp/pre_start_hook"}}, nil + fmt.Println("pre start method called") + // make this pre-start hook run after network in container setup + return []int{-4}, [][]string{{"/usr/bin/touch", "touch", "/tmp/pre_start_hook"}}, nil } func main() { - fmt.Println(ContainerPlugin, DaemonPlugin) + fmt.Println(ContainerPlugin, DaemonPlugin) } ``` + then build it with command line like: + ``` go build -buildmode=plugin -ldflags "-pluginpath=plugins_$(date +%s)" -o hook_plugin.so ``` + to use the shared object file generated, start pouchd which flag `--plugin=path_to_hook_plugin.so`, then when you start stop daemon and create container, in the log there will be some logs like: + ``` pre-start hook in daemon is called pre create method called pre-stop hook in daemon is called ``` + when you start a container, the config.json file (whose place is $home_dir/containerd/state/io.containerd.runtime.v1.linux/default/$container_id/config.json) will contains the pre-start hook specified in above code, eg: + ``` "hooks": { "prestart": [ @@ -120,4 +133,4 @@ and if you use the exact code above, every time you start a container the file a at pre-start daemon point you can start assist processes like network plugins and dfget proxy which need by pouchd and whose life cycle is the same as pouchd. at pre-stop daemon point you can stop the assist processes gracefully, but the trigger of this point is not a promise, because pouchd may be killed by SIGKILL. at pre-create container point you can change the input stream by some rules, in some company they have some stale orchestration system who use env to pass-in some limit which is an attribute in pouch, then you can use this point to convert value in env to attribute in ContainerConfig or HostConfig of pouch create api. -at pre-start container point you can set more pre-start hooks to oci spec, where you can do some special thing before container entrypoint start, priority decide the order of executing of the hook. libnetwork hook has priority 0, so if the hook is expected to run before network in container setup you should set priority to a value big then 0, and vice versa. \ No newline at end of file +at pre-start container point you can set more pre-start hooks to oci spec, where you can do some special thing before container entrypoint start, priority decide the order of executing of the hook. libnetwork hook has priority 0, so if the hook is expected to run before network in container setup you should set priority to a value big then 0, and vice versa. diff --git a/docs/features/pouch_with_prometheus.md b/docs/features/pouch_with_prometheus.md index 1997fcef0..a0a5217a0 100644 --- a/docs/features/pouch_with_prometheus.md +++ b/docs/features/pouch_with_prometheus.md @@ -11,8 +11,8 @@ We tend to use prometheus's [METRIC AND LABEL NAMING](https://prometheus.io/docs We use prometheus [go-sdk](https://github.com/prometheus/client_golang) to monitor pouchd. It supports counter, gauge and summary metric types. For more info, please refer to [METRIC TYPES](https://prometheus.io/docs/concepts/metric_types/). -## How to use - +## How to use + Users can start pouchd listening on `0.0.0.0:4243` via `pouchd -l tcp://0.0.0.0:4243`, then issue `GET http://127.0.0.1:4243/metrics` request to get a full list of prometheus-formatted metrics as below: ``` @@ -73,4 +73,4 @@ process_start_time_seconds 1.51064406778e+09 process_virtual_memory_bytes 4.91610112e+08 ``` -Then we can set up a new target to scrape this metric endpoint in prometheus. So that's it. \ No newline at end of file +Then we can set up a new target to scrape this metric endpoint in prometheus. So that's it. diff --git a/docs/features/pouch_with_rich_container.md b/docs/features/pouch_with_rich_container.md index 619304a54..77867c9f5 100644 --- a/docs/features/pouch_with_rich_container.md +++ b/docs/features/pouch_with_rich_container.md @@ -10,7 +10,7 @@ Container technology and orchestration platforms have turned quite popular right Developers have their own programming style. Their work is to create useful applications, not to design absolute decoupled ones, so they usually take advantages of tools or system services to make it. When containerizing these applications, it is quite weak if only setting one application one process in container. Rich container mode finds out ways to make users configure the inner startup sequence of processes in container including application and system services around. -Operators have a sacred duty to guard normal running of the applications. For the sake of business running in applications, technology must show enough respect for operator's tradition. Environment change is not a good message when debugging and solving issue online. Rich container mode can ensure that environment in rich container in totally the same as that in traditional VM or physical machine. If operator needs some system tools, they are located there still. If some pre and post hooks should take effect, just set them when starting rich containers. If some issues happen inside, system services started by rich container can fix them just like self-healing. +Operators have a sacred duty to guard normal running of the applications. For the sake of business running in applications, technology must show enough respect for operator's tradition. Environment change is not a good message when debugging and solving issue online. Rich container mode can ensure that environment in rich container in totally the same as that in traditional VM or physical machine. If operator needs some system tools, they are located there still. If some pre and post hooks should take effect, just set them when starting rich containers. If some issues happen inside, system services started by rich container can fix them just like self-healing. ## Get started @@ -24,75 +24,77 @@ In fact, pouch team plans to add another flag `--initcmd` to make users input pr If user specifies `--rich` flag and no `--initscript` flag is provided, rich container mode will still be enbaled, but no initscript will be executed. If `-rich` flag misses in command line, while `--initscript` is there, Pouch CLI or pouch daemon will return an error to show that `--initscipt` can only be used along with `--rich` flag. -If a container is running with `--rich` flag, then every start or restart of this container will trigger the corresponding initscipt if there is any. +If a container is running with `--rich` flag, then every start or restart of this container will trigger the corresponding initscipt if there is any. ### Using dumb-init Here is a simple example for rich container mode using dumb-init to init contaienr: 1. Insatll dumb-init as following: - - ```shell - # wget -O /usr/bin/dumb-init https://github.com/Yelp/dumb-init/releases/download/v1.2.1/dumb-init_1.2.1_amd64 - # chmod +x /usr/bin/dumb-init - - ``` + + ```shell + # wget -O /usr/bin/dumb-init https://github.com/Yelp/dumb-init/releases/download/v1.2.1/dumb-init_1.2.1_amd64 + # chmod +x /usr/bin/dumb-init + + ``` + 2. Run a container with rich mode: - ```shell - #pouch run -d --rich --rich-mode dumb-init registry.hub.docker.com/library/busybox:latest sleep 10000 - f76ac1e49e9407caf5ad33c8988b44ff3690c12aa98f7faf690545b16f2a5cbd + ```shell + #pouch run -d --rich --rich-mode dumb-init registry.hub.docker.com/library/busybox:latest sleep 10000 + f76ac1e49e9407caf5ad33c8988b44ff3690c12aa98f7faf690545b16f2a5cbd + + #pouch exec f76ac1e49e9407caf5ad33c8988b44ff3690c12aa98f7faf690545b16f2a5cbd ps -ef + PID USER TIME COMMAND + 1 root 0:00 /usr/bin/dumb-init -- sleep 10000 + 7 root 0:00 sleep 10000 + 8 root 0:00 ps -ef - #pouch exec f76ac1e49e9407caf5ad33c8988b44ff3690c12aa98f7faf690545b16f2a5cbd ps -ef - PID USER TIME COMMAND - 1 root 0:00 /usr/bin/dumb-init -- sleep 10000 - 7 root 0:00 sleep 10000 - 8 root 0:00 ps -ef - - ``` + ``` ### Using systemd or sbin-init + In order to use systemd or /sbin/init to init container, please make sure install them on image. -As shown below, centos image has both of them. +As shown below, centos image has both of them. Also `--privileged` is required in this situation. An example of systemd and sbin-init is as following: - + ``` - #cat /tmp/1.sh - #! /bin/sh - echo $(cat) >/tmp/xxx - - #pouch run -d -v /tmp:/tmp --privileged --rich --rich-mode systemd --initscript /tmp/1.sh registry.hub.docker.com/library/centos:latest /usr/bin/sleep 10000 - 3054125e44443fd5ee9190ee49bbca0a842724f5305cb05df49f84fd7c901d63 - - #pouch exec 3054125e44443fd5ee9190ee49bbca0a842724f5305cb05df49f84fd7c901d63 ps aux - USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND - root 1 7.4 0.0 42968 3264 ? Ss 05:29 0:00 /usr/lib/systemd/systemd - root 17 0.0 0.0 10752 756 ? Ss 05:29 0:00 /usr/lib/systemd/systemd-readahead collect - root 18 3.2 0.0 32740 2908 ? Ss 05:29 0:00 /usr/lib/systemd/systemd-journald - root 34 0.0 0.0 22084 1456 ? Ss 05:29 0:00 /usr/lib/systemd/systemd-logind - root 36 0.0 0.0 7724 608 ? Ss 05:29 0:00 /usr/bin/sleep 10000 - dbus 37 0.0 0.0 24288 1604 ? Ss 05:29 0:00 /bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation - root 45 0.0 0.0 47452 1676 ? Rs 05:29 0:00 ps aux - - #cat /tmp/xxx - {"ociVersion":"1.0.0","id":"3054125e44443fd5ee9190ee49bbca0a842724f5305cb05df49f84fd7c901d63","status":"","pid":125745,"bundle":"/var/lib/pouch/containerd/state/io.containerd.runtime.v1.linux/default/3054125e44443fd5ee9190ee49bbca0a842724f5305cb05df49f84fd7c901d63"} - - #pouch run -d -v /tmp:/tmp --privileged --rich --rich-mode sbin-init --initscript /tmp/1.sh registry.hub.docker.com/library/centos:latest /usr/bin/sleep 10000 - c5b5eef81749ce00fb68a59ee623777bfecc8e07c617c0601cc56e4ae8b1e69f - - #pouch exec c5b5eef81749ce00fb68a59ee623777bfecc8e07c617c0601cc56e4ae8b1e69f ps aux - USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND - root 1 7.4 0.0 42968 3260 ? Ss 05:30 0:00 /sbin/init - root 17 0.0 0.0 10752 752 ? Ss 05:30 0:00 /usr/lib/systemd/systemd-readahead collect - root 20 3.2 0.0 32740 2952 ? Ss 05:30 0:00 /usr/lib/systemd/systemd-journald - root 34 0.0 0.0 22084 1452 ? Ss 05:30 0:00 /usr/lib/systemd/systemd-logind - root 35 0.0 0.0 7724 612 ? Ss 05:30 0:00 /usr/bin/sleep 10000 - dbus 36 0.0 0.0 24288 1608 ? Ss 05:30 0:00 /bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation - root 45 0.0 0.0 47452 1676 ? Rs 05:30 0:00 ps aux - - #cat /tmp/xxx - {"ociVersion":"1.0.0","id":"c5b5eef81749ce00fb68a59ee623777bfecc8e07c617c0601cc56e4ae8b1e69f","status":"","pid":127183,"bundle":"/var/lib/pouch/containerd/state/io.containerd.runtime.v1.linux/default/c5b5eef81749ce00fb68a59ee623777bfecc8e07c617c0601cc56e4ae8b1e69f"} - + #cat /tmp/1.sh + #! /bin/sh + echo $(cat) >/tmp/xxx + + #pouch run -d -v /tmp:/tmp --privileged --rich --rich-mode systemd --initscript /tmp/1.sh registry.hub.docker.com/library/centos:latest /usr/bin/sleep 10000 + 3054125e44443fd5ee9190ee49bbca0a842724f5305cb05df49f84fd7c901d63 + + #pouch exec 3054125e44443fd5ee9190ee49bbca0a842724f5305cb05df49f84fd7c901d63 ps aux + USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND + root 1 7.4 0.0 42968 3264 ? Ss 05:29 0:00 /usr/lib/systemd/systemd + root 17 0.0 0.0 10752 756 ? Ss 05:29 0:00 /usr/lib/systemd/systemd-readahead collect + root 18 3.2 0.0 32740 2908 ? Ss 05:29 0:00 /usr/lib/systemd/systemd-journald + root 34 0.0 0.0 22084 1456 ? Ss 05:29 0:00 /usr/lib/systemd/systemd-logind + root 36 0.0 0.0 7724 608 ? Ss 05:29 0:00 /usr/bin/sleep 10000 + dbus 37 0.0 0.0 24288 1604 ? Ss 05:29 0:00 /bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation + root 45 0.0 0.0 47452 1676 ? Rs 05:29 0:00 ps aux + + #cat /tmp/xxx + {"ociVersion":"1.0.0","id":"3054125e44443fd5ee9190ee49bbca0a842724f5305cb05df49f84fd7c901d63","status":"","pid":125745,"bundle":"/var/lib/pouch/containerd/state/io.containerd.runtime.v1.linux/default/3054125e44443fd5ee9190ee49bbca0a842724f5305cb05df49f84fd7c901d63"} + + #pouch run -d -v /tmp:/tmp --privileged --rich --rich-mode sbin-init --initscript /tmp/1.sh registry.hub.docker.com/library/centos:latest /usr/bin/sleep 10000 + c5b5eef81749ce00fb68a59ee623777bfecc8e07c617c0601cc56e4ae8b1e69f + + #pouch exec c5b5eef81749ce00fb68a59ee623777bfecc8e07c617c0601cc56e4ae8b1e69f ps aux + USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND + root 1 7.4 0.0 42968 3260 ? Ss 05:30 0:00 /sbin/init + root 17 0.0 0.0 10752 752 ? Ss 05:30 0:00 /usr/lib/systemd/systemd-readahead collect + root 20 3.2 0.0 32740 2952 ? Ss 05:30 0:00 /usr/lib/systemd/systemd-journald + root 34 0.0 0.0 22084 1452 ? Ss 05:30 0:00 /usr/lib/systemd/systemd-logind + root 35 0.0 0.0 7724 612 ? Ss 05:30 0:00 /usr/bin/sleep 10000 + dbus 36 0.0 0.0 24288 1608 ? Ss 05:30 0:00 /bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation + root 45 0.0 0.0 47452 1676 ? Rs 05:30 0:00 ps aux + + #cat /tmp/xxx + {"ociVersion":"1.0.0","id":"c5b5eef81749ce00fb68a59ee623777bfecc8e07c617c0601cc56e4ae8b1e69f","status":"","pid":127183,"bundle":"/var/lib/pouch/containerd/state/io.containerd.runtime.v1.linux/default/c5b5eef81749ce00fb68a59ee623777bfecc8e07c617c0601cc56e4ae8b1e69f"} + ``` ## Underlying Implementation diff --git a/docs/features/pouch_with_runV.md b/docs/features/pouch_with_runV.md index 3c6edff8b..d22b69b02 100644 --- a/docs/features/pouch_with_runV.md +++ b/docs/features/pouch_with_runV.md @@ -118,7 +118,7 @@ $ $ pouch start hypervisor -i / # uname -a Linux 4.12.4-hyper #18 SMP Mon Sep 4 15:10:13 CST 2017 x86_64 GNU/Linux -``` +``` It turns out that in experiment above kernel in host physical machine is 4.4.0-101-generic, and that in hypervisor-based container is 4.12.4-hyper. Obviously, they are isolated from each other in term of kernel. diff --git a/docs/features/pouch_with_tls.md b/docs/features/pouch_with_tls.md index c5702e853..20b1c63f9 100644 --- a/docs/features/pouch_with_tls.md +++ b/docs/features/pouch_with_tls.md @@ -18,7 +18,6 @@ After applying above commands, in current directory there are two files named ca Create a certificate for pouchd, which only can be used as a server certificate, variable name is HOSTNAME of the machine to run pouchd on. - ```shell name=$HOSTNAME mkdir -p ${name} @@ -65,4 +64,4 @@ Then we have a directory which contains all files we needed to use with pouch cl ./pouch -H ${server_hostname}:4243 --tlsverify --tlscacert=${path}/ca.pem --tlscert=${path}/cert.pem --tlskey=${path}/key.pem version ``` -When a client without a certificate or with a certificate not published by the same CA tries to connect to a pouch daemon having a TLS protection, this connection will be refused. \ No newline at end of file +When a client without a certificate or with a certificate not published by the same CA tries to connect to a pouch daemon having a TLS protection, this connection will be refused. diff --git a/docs/kubernetes/pouch_with_cri_introduction.md b/docs/kubernetes/pouch_with_cri_introduction.md index 05d9249a3..87bea47f5 100644 --- a/docs/kubernetes/pouch_with_cri_introduction.md +++ b/docs/kubernetes/pouch_with_cri_introduction.md @@ -2,7 +2,7 @@ ## What is CRI -The Container Runtime Interface (CRI) is a plugin interface which enables kubelet to use a wide variety of container runtimes, without the need to recompile. +The Container Runtime Interface (CRI) is a plugin interface which enables kubelet to use a wide variety of container runtimes, without the need to recompile. CRI (_Container Runtime Interface_) consists of a [protobuf API](https://git.k8s.io/kubernetes/pkg/kubelet/apis/cri/v1alpha1/runtime/api.proto),specifications/requirements and [libraries](https://git.k8s.io/kubernetes/pkg/kubelet/server/streaming)for container runtimes to integrate with kubelet on a node. This diagram explains how the Container Runtime Interface works: diff --git a/docs/kubernetes/pouch_with_cri_verification.md b/docs/kubernetes/pouch_with_cri_verification.md index 1502ae890..816984663 100644 --- a/docs/kubernetes/pouch_with_cri_verification.md +++ b/docs/kubernetes/pouch_with_cri_verification.md @@ -60,6 +60,7 @@ image-endpoint: /var/run/pouchcri.sock timeout: 10 debug: true ``` + ## Examples ### Run sandbox with config file @@ -97,10 +98,13 @@ Image is update to date for 0153c5db97e5 IMAGE TAG IMAGE ID SIZE docker.io/library/redis alpine 0153c5db97e58 10.1MB ``` + ### unsuccessful cases If pouch has not fully or correctly implemented some interfaces in CRI, crictl command execution would fail: + ``` + # crictl ps FATA[0000] listing containers failed: rpc error: code = Unknown desc = ListContainers Not Implemented Yet ``` diff --git a/docs/kubernetes/pouch_with_kubernetes_deploying.md b/docs/kubernetes/pouch_with_kubernetes_deploying.md index 4967ebea3..f936b886f 100644 --- a/docs/kubernetes/pouch_with_kubernetes_deploying.md +++ b/docs/kubernetes/pouch_with_kubernetes_deploying.md @@ -1,15 +1,15 @@ # Pouch with Kubernetes deploying - [Pouch deploying](#pouch-with-kubernetes-deploying) - - [Overview](#overview) - - [Restriction](#restriction) - - [Install and Configure](#install-and-configure) - - [Install Pouch](#install-pouch) - - [Install Kubelet](#install-kubelet) - - [Setting up the master node](#setting-up-the-master-node) - - [Setting up the worker nodes](#setting-up-the-worker-nodes) - - [Start and run](#start-and-run) - - [Run sandbox](#run-sandbox) + - [Overview](#overview) + - [Restriction](#restriction) + - [Install and Configure](#install-and-configure) + - [Install Pouch](#install-pouch) + - [Install Kubelet](#install-kubelet) + - [Setting up the master node](#setting-up-the-master-node) + - [Setting up the worker nodes](#setting-up-the-worker-nodes) + - [Start and run](#start-and-run) + - [Run sandbox](#run-sandbox) ## Overview @@ -17,7 +17,7 @@ This document shows how to easily install a Kubernetes cluster with pouch runtim ![pouch_with_kubernetes](../static_files/pouch_with_kubernetes.png) -## Restriction +## Restriction Kubernetes: Kubernetes 1.6+ @@ -31,7 +31,6 @@ Note: The rest of the restrictions are based on Pouch and Kubernetes. You can easily setup a basic Pouch environment, see [INSTALLATION.md](../../INSTALLATION.md). - ### Install Kubelet On Ubuntu 16.04+: @@ -75,10 +74,13 @@ For other plugins, please check [Installing a pod network](https://kubernetes.io ### Setting up the worker nodes get token on master node: + ``` # token=$(kubeadm token list | grep authentication,signing | awk '{print $1}') ``` + join master on worker nodes: + ``` # kubeadm join --token $token ${master_ip:port} ``` @@ -126,6 +128,7 @@ e7d0384ef3cc7 48 years ago SANDBOX_NOTREADY pouch-75cdc5c4cb-bgz ``` ## Use `Pouch CRI` in production environment + In a production environment, we recommend user to have their own CNI plugin (Flannel, Calico, Neutron etc), and persistent volume provider (GlusterFS, Cephfs, NFS etc). Please follow Kubernetes admin doc for details about integration, and it makes no difference if you are using `pouch CRI`. diff --git a/docs/test/debug_in_travis.md b/docs/test/debug_in_travis.md index 4b4b0bc4c..3f80869a2 100644 --- a/docs/test/debug_in_travis.md +++ b/docs/test/debug_in_travis.md @@ -3,19 +3,20 @@ Pouch uses [Travis](https://travis-ci.com/) as the Continuous Integration tool. Sometimes, tests may pass on local machine while fail on Travis environment. Debug in Travis is provided. This document will give a simple instruction about debugging in Travis. -# Turn on debug feature +## Turn on debug feature For public repository, debug feature is off by default. An email to `support@travis-ci.com ` is needed to ask the Travis staff to turn on debug feature for your public repository. -# A real example +## A real example There is a [guide]( https://docs.travis-ci.com/user/running-build-in-debug-mode/) about how to use debug mode, you should read it before starting. After that, let's give a real example. Take a Travis build from my repository as example: `https://travis-ci.org/Letty5411/pouch/builds/308762622?utm_source=github_status&utm_medium=notification` -## Command to start debug mode +### Command to start debug mode + From the guide provied by Travis, we know that a `curl` request is needed to be constructed to start the debug mode, the command template is as following: ```shell @@ -25,15 +26,16 @@ From the guide provied by Travis, we know that a `curl` request is needed to be -H "Travis-API-Version: 3" \ -H "Authorization: token " \ -d '{ "quiet": true }' \ - https://api.travis-ci.org/job/{ID}/debug -``` + https://api.travis-ci.org/job/{ID}/debug +``` + For the command, the `TOKEN` and `job ID` is needed. How to get them? -### Get token +#### Get token Here is the [guide](https://docs.travis-ci.com/user/triggering-builds/) of how to generate token. It only needs three steps: -1. Install Travis CI command line client according the this [guide](https://github.com/travis-ci/travis.rb). +1.Install Travis CI command line client according the this [guide](https://github.com/travis-ci/travis.rb). ``` # gem install travis -v 1.8.8 --no-rdoc --no-ri @@ -44,8 +46,9 @@ ruby 2.0.0p598 (2014-11-13) [x86_64-linux] # travis -v 1.8.8 -``` -2. Log into Travis, need your GitHub username and password and will get you authenticated. +``` + +2.Log into Travis, need your GitHub username and password and will get you authenticated. ``` #travis login --org @@ -59,7 +62,8 @@ Username: xxxx Password for xxxx: **** Successfully logged in as xxxx! ``` -3. Get an API token using the Travis CI command line client, if everything goes well you will get your token. + +3.Get an API token using the Travis CI command line client, if everything goes well you will get your token. ``` #travis token --org @@ -67,8 +71,9 @@ Successfully logged in as xxxx! Your access token is yourtoken ``` -### Get job ID -In my case, the job ID for this build is: 308880940, which you can find in the build system information section of the log. +#### Get job ID + +In my case, the job ID for this build is: 308880940, which you can find in the build system information section of the log. ``` Build system information @@ -79,7 +84,8 @@ Build id: 308880939 Job id: 308880940 ``` -## Start debug mode +### Start debug mode + Now both token and job ID is ready, a curl command could be run to start debug mode: ``` @@ -119,7 +125,8 @@ Use the following SSH command to access the interactive debugging environment: ssh ukjiuCEkxBBnRAe32Y8xCH0zj@ny2.tmate.io ``` -## SSH the VM and enjoy debugging +### SSH the VM and enjoy debugging + Now you could debug on the Travis VM through SSH command from your computer. Once you're done, just type exit and your build will terminate. ``` @@ -142,7 +149,8 @@ travis@travis-job-885b6c7c-5885-469e-90bb-d3014cc72000:~/gopath/src/github.com/a Finally, once in the SSH session, these [bash functions](https://docs.travis-ci.com/user/running-build-in-debug-mode/#Things-to-do-once-you-are-inside-the-debug-VM) will come in handy to run the different phases in your build. -# Acknowledgements +## Acknowledgements + A lot thanks should give to Carla Iriberri, staff from Travis, who gives me this specific instruction. This doc is extracted from the email between Carla Iriberri and me. -By the way, if you have any question about Travis, please do not hesitate to write email to +By the way, if you have any question about Travis, please do not hesitate to write email to `support@travis-ci.com`, they have really quick response and good support. Thanks again for Carla Iriberri's help. diff --git a/docs/test/test.md b/docs/test/test.md index f4cde05aa..50f35315e 100644 --- a/docs/test/test.md +++ b/docs/test/test.md @@ -4,11 +4,11 @@ In order to provide high quality `pouch`, testing is an important part. This doc will give an introduction about the following three parts: -* the organization of pouch test -* the usage of pouch test -* the development of pouch test +* the organization of pouch test +* the usage of pouch test +* the development of pouch test -# Organization of test +## Organization of test Test in pouch could be divided into following parts: @@ -17,7 +17,7 @@ Test in pouch could be divided into following parts: *Unit testing* uses [go testing](https://golang.org/pkg/testing/) package, named with `_test.go` suffix and always locates in the same directory with the code tested. [client/client_test.go](https://github.com/alibaba/pouch/blob/master/client/client_test.go) is a good example of unit test. -*Integration test* is in `pouch/test`, programmed with `go language`. There are two kinds of integration test, API test named as `api_xxx_test.go` and command line test named as `cli_xxx_test.go` ("xxx" represents the test point). +*Integration test* is in `pouch/test`, programmed with `go language`. There are two kinds of integration test, API test named as `api_xxx_test.go` and command line test named as `cli_xxx_test.go` ("xxx" represents the test point). It uses [go-check](https://labix.org/gocheck) package, a rich testing framework for go language. It provides many useful functions, such as: * SetUpTest: Run before each test to do some common work. @@ -33,16 +33,15 @@ For other files, they are: * `command package`: package command is used to encapsulate CLI lib functions. * `request package`: package request is used to encapsulate http request lib functions. - For pouch developer, if your code is only used in a single module, then the unit test is enough. While if your code is called by multiple modules, integration tests are required. In pouch, both of them are developed using go language. More details could be gotten in [Unit Testing](#unit-testing) and [Integration Testing](#integration-testing). +## Run Tests -# Run Tests -Tests could be run through the target provided by `Makefile` in the root directory of pouch code. Also could be run manually. +Tests could be run through the target provided by `Makefile` in the root directory of pouch code. Also could be run manually. To run the test automatically, the following prerequisites are needed: - - * golang is installed and GOPATH and GOROOT is set correctly - * docker is installed + + * golang is installed and GOPATH and GOROOT is set correctly + * docker is installed Then you could just clone the pouch source to GOPATH and run tests as following: @@ -55,6 +54,7 @@ GOPATH=/go # cd /go/src/github.com/alibaba/pouch # make test ``` + Using `make -n test`, let us take a look at what `make test` has done. ``` @@ -64,8 +64,10 @@ check build unit-test integration-test cri-test" ``` `make test` calls the hack/make.sh script to check code format, build pouch daemon and client, run unit test, run integration test and run cri test. -`hack/make.sh` needs `docker` installed on test machine, as it uses `docker build` to build a test image including tools needed to run `make test`. `go` is also needed to be installed and set `GOPATH` `GOROOT` `PATH` correctly. For more information, you could check the `hack/make.sh` script. -# Run Tests Manually +`hack/make.sh` needs `docker` installed on test machine, as it uses `docker build` to build a test image including tools needed to run `make test`. `go` is also needed to be installed and set `GOPATH` `GOROOT` `PATH` correctly. For more information, you could check the `hack/make.sh` script. + +## Run Tests Manually + As a pouch developer, you may need to run tests manually. If you want to do code format check, you could run `make check` in your code directory, but please make sure the following tools are already installed: @@ -74,7 +76,7 @@ If you want to do code format check, you could run `make check` in your code dir * golint * swagger -In order to run unit-test or integration test, install go and configure go environment first. +In order to run unit-test or integration test, install go and configure go environment first. ``` # go version @@ -85,26 +87,29 @@ go version go1.9.2 linux/amd64 GOROOT=/usr/local/go GOPATH=/go ``` + Then copy or clone or link pouch source code to the GOPATH： ``` # pwd /go/src/github.com/alibaba/pouch ``` + Now you could run unit test as following: ``` # make unit-test -``` +``` Or using go test $testdir to run unit test in a specified directory. ``` #go test ./client -ok github.com/alibaba/pouch/client 0.094s +ok github.com/alibaba/pouch/client 0.094s ``` -There are more works to do for integration test compared with unit test. + +There are more works to do for integration test compared with unit test. First you need to make sure `pouch` and `pouchd` binary is installed or builded. @@ -116,35 +121,40 @@ Next you need to start pouch daemon and pull a busybox image: # pouchd -D --enable-lxcfs=true --lxcfs=/usr/bin/lxcfs >/tmp/log 2>&1 & # pouch pull registry.hub.docker.com/library/busybox:latest ``` + Then integration test could be run as following: -* run entire test: +* run entire test: ``` # cd test -#go test +#go test ``` -* run a single test suite: - + +* run a single test suite: + ``` #go test -check.f PouchCreateSuite OK: 3 passed PASS -ok github.com/alibaba/pouch/test 3.081s +ok github.com/alibaba/pouch/test 3.081s ``` + * run a single test case: - + ``` #go test -check.f PouchHelpSuite.TestHelpWorks OK: 1 passed PASS -ok github.com/alibaba/pouch/test 0.488s -``` +ok github.com/alibaba/pouch/test 0.488s +``` + * run with more information: ``` -#go test -check.vv +#go test -check.vv ``` - -# Development of Test + +## Development of Test + // TODO diff --git a/hack/package/README.md b/hack/package/README.md index c788b88ba..691eed8c0 100644 --- a/hack/package/README.md +++ b/hack/package/README.md @@ -1,4 +1,4 @@ -# Building pouch deb and rpm packages +# Building pouch deb and rpm packages This file shows how to build Pouch packages. @@ -6,18 +6,18 @@ This file shows how to build Pouch packages. Firstly, you should install Docker, as we use Docker to build images and run containers to build packages. -Then, run `date` command to ensure time is right, which is used to set `BuildTime` field. +Then, run `date` command to ensure time is right, which is used to set `BuildTime` field. To build Pouch packages, you should prepare gpg keys and put it in a directory. - + eg: ```bash $ tree /root/packages/ - packages - ├── keys - │ ├── gpg - │ └── secretkey + packages + ├── keys + │ ├── gpg + │ └── secretkey ``` ## Building packages @@ -39,8 +39,8 @@ What's more, you should pass four parameters as follows: ```bash cd pouch/ ./hack/package/package.sh 1.0.0 1.el7.centos /root/test rpm - | | | | + | | | | VSERSION ITERATION KEYDIR PKGTYPE ``` -Finally, packages will be output in `/root/packages/package` in this example. \ No newline at end of file +Finally, packages will be output in `/root/packages/package` in this example. diff --git a/volume/README.md b/volume/README.md index 4392945d2..4a1df17f6 100644 --- a/volume/README.md +++ b/volume/README.md @@ -1,43 +1,55 @@ -## What is Volume? +# Introduction for volume + +## What is Volume + Volume is a universal module that used to provide container storage in pouch. It provides storage service for containers through the interface of file storage. -## What is the architecture of Volume? + +## What is the architecture of Volume + Volume includes these modules is as following: + * VolumeManager: volume manager provides the basic volume interface functions for pouchd. * Core: volume's core module, it is used to associate with several modules, and it achieves a common process that volume operate functions. * Driver: it is used to abstract the basic functions of volume driver. * Modules: Different types of storage provides different modules, it achieves different storage unified access to the pouch volume. + The relationship between each module is as following: ![pouch_volume_architecture | center | 710x515 ](../docs/static_files/pouch_volume_architecture.png) ### VolumeManager + It provides interface is as following: + ```go type VolumeMgr interface { - // Create is used to create volume. - Create(ctx context.Context, name, driver string, options, labels map[string]string) error + // Create is used to create volume. + Create(ctx context.Context, name, driver string, options, labels map[string]string) error - // Remove is used to remove an existing volume. - Remove(ctx context.Context, name string) error + // Remove is used to remove an existing volume. + Remove(ctx context.Context, name string) error - // List returns all volumes on this host. - List(ctx context.Context, labels map[string]string) ([]string, error) + // List returns all volumes on this host. + List(ctx context.Context, labels map[string]string) ([]string, error) - // Get returns the information of volume that specified name/id. - Get(ctx context.Context, name string) (*types.Volume, error) + // Get returns the information of volume that specified name/id. + Get(ctx context.Context, name string) (*types.Volume, error) - // Path returns the mount path of volume. - Path(ctx context.Context, name string) (string, error) + // Path returns the mount path of volume. + Path(ctx context.Context, name string) (string, error) - // Attach is used to bind a volume to container. - Attach(ctx context.Context, name string, options map[string]string) (*types.Volume, error) + // Attach is used to bind a volume to container. + Attach(ctx context.Context, name string, options map[string]string) (*types.Volume, error) - // Detach is used to unbind a volume from container. - Detach(ctx context.Context, name string, options map[string]string) (*types.Volume, error) + // Detach is used to unbind a volume from container. + Detach(ctx context.Context, name string, options map[string]string) (*types.Volume, error) } ``` + ### Core + Core provides these functions is as following: + ```go // GetVolume return a volume's info with specified name, If not errors. func (c *Core) GetVolume(id types.VolumeID) (*types.Volume, error) @@ -67,9 +79,13 @@ func (c *Core) AttachVolume(id types.VolumeID, extra map[string]string) (*types. // DetachVolume to disable a volume on local host. func (c *Core) DetachVolume(id types.VolumeID, extra map[string]string) (*types.Volume, error) ``` + ### Driver + Driver layer provides two types of interfaces, one is the basic interfaces that all modules must implement, the others are optional interfaces for accessing differences provided by different types of storage. + * Basic interfaces + ```go type Driver interface { // Name returns backend driver's name. @@ -88,7 +104,9 @@ type Driver interface { Path(Context, *types.Volume) (string, error) } ``` + * Optional interfaces + ```go // Opt represents volume driver option interface. type Opt interface { @@ -110,10 +128,17 @@ type Formator interface { // Format a volume. Format(Context, *types.Volume, *types.Storage) error } + ``` + ### Modules + As of now, pouch volume supports the following types of storage: local, tmpfs, ceph. If you want to add a new driver, you can refer to the sample code: [demo](volume/examples/demo/demo.go) -## How to use volume? + +## How to use volume + As of now, volume supports the following operations: create/remove/list/inspect, for more details, please refer: [Volume Cli](docs/commandline/pouch_volume.md) + ## Volume roadmap + Pouch volume will implement the interface of [CSI(contianer storage interface)](https://github.com/container-storage-interface/spec), as a node-server integrating with control-server to achieve volume scheduling ability.