diff options
| -rw-r--r-- | README.md | 231 | ||||
| -rw-r--r-- | transfer.md | 20 |
2 files changed, 239 insertions, 12 deletions
@@ -1 +1,230 @@ -Under construction!
\ No newline at end of file + +# libpod - library for running OCI-based containers in Pods + +### Status: Development + +## What is the scope of this project? + +libpod is meant to provide an library for applications lookint the user the Container Pod concept popularized by Kubernetes. +libpod also contains a tool kpod, which allows you to manage Pods, Containers, and Container Images. + +At a high level, we expect the scope of libpod/kpod to the following functionalities: + +* Support multiple image formats including the existing Docker image format +* Support for multiple means to download images including trust & image verification +* Container image management (managing image layers, overlay filesystems, etc) +* Container and POD process lifecycle management +* Resource isolation of containers and PODS. + +## What is not in scope for this project? + +* Building container images. See Buildah +* Signing and pushing images to various image storages. See Skopeo. +* Container Runtimes daemons for working with Kubernetes CRIs See CRI-O. + +The plan is to use OCI projects and best of breed libraries for different aspects: +- Runtime: [runc](https://github.com/opencontainers/runc) (or any OCI runtime-spec implementation) and [oci runtime tools](https://github.com/opencontainers/runtime-tools) +- Images: Image management using [containers/image](https://github.com/containers/image) +- Storage: Storage and management of image layers using [containers/storage](https://github.com/containers/storage) +- Networking: Networking support through use of [CNI](https://github.com/containernetworking/cni) + +libpod is currently in active development. + +## Commands +| Command | Description | Demo| +| ---------------------------------------------------- | --------------------------------------------------------------------------|-----| +| [kpod(1)](/docs/kpod.1.md) | Simple management tool for pods and images || +| [kpod-attach(1)](/docs/kpod-attach.1.md) | Instead of providing a `kpod attach` command, the man page `kpod-attach` describes how to use the `kpod logs` and `kpod exec` commands to achieve the same goals as `kpod attach`.|| +| [kpod-cp(1)](/docs/kpod-cp.1.md) | Instead of providing a `kpod cp` command, the man page `kpod-cp` describes how to use the `kpod mount` command to have even more flexibility and functionality.|| +| [kpod-diff(1)](/docs/kpod-diff.1.md) | Inspect changes on a container or image's filesystem |[](https://asciinema.org/a/FXfWB9CKYFwYM4EfqW3NSZy1G)| +| [kpod-export(1)](/docs/kpod-export.1.md) | Export container's filesystem contents as a tar archive |[](https://asciinema.org/a/913lBIRAg5hK8asyIhhkQVLtV)| +| [kpod-history(1)](/docs/kpod-history.1.md) | Shows the history of an image |[](https://asciinema.org/a/bCvUQJ6DkxInMELZdc5DinNSx)| +| [kpod-images(1)](/docs/kpod-images.1.md) | List images in local storage |[](https://asciinema.org/a/133649)| +| [kpod-info(1)](/docs/kpod-info.1.md) | Display system information || +| [kpod-inspect(1)](/docs/kpod-inspect.1.md) | Display the configuration of a container or image |[](https://asciinema.org/a/133418)| +| [kpod-kill(1)](/docs/kpod-kill.1.md) | Kill the main process in one or more running containers |[](https://asciinema.org/a/3jNos0A5yzO4hChu7ddKkUPw7)| +| [kpod-load(1)](/docs/kpod-load.1.md) | Load an image from docker archive or oci |[](https://asciinema.org/a/kp8kOaexEhEa20P1KLZ3L5X4g)| +| [kpod-login(1)](/docs/kpod-login.1.md) | Login to a container registry |[](https://asciinema.org/a/oNiPgmfo1FjV2YdesiLpvihtV)| +| [kpod-logout(1)](/docs/kpod-logout.1.md) | Logout of a container registry |[](https://asciinema.org/a/oNiPgmfo1FjV2YdesiLpvihtV)| +| [kpod-logs(1)](/docs/kpod-logs.1.md) | Display the logs of a container || +| [kpod-mount(1)](/docs/kpod-mount.1.md) | Mount a working container's root filesystem || +| [kpod-pause(1)](/docs/kpod-pause.1.md) | Pause one or more running containers |[](https://asciinema.org/a/141292)| +| [kpod-ps(1)](/docs/kpod-ps.1.md) | Prints out information about containers |[](https://asciinema.org/a/bbT41kac6CwZ5giESmZLIaTLR)| +| [kpod-pull(1)](/docs/kpod-pull.1.md) | Pull an image from a registry |[](https://asciinema.org/a/lr4zfoynHJOUNu1KaXa1dwG2X)| +| [kpod-push(1)](/docs/kpod-push.1.md) | Push an image to a specified destination |[](https://asciinema.org/a/133276)| +| [kpod-rename(1)](/docs/kpod-rename.1.md) | Rename a container || +| [kpod-rm(1)](/docs/kpod-rm.1.md) | Removes one or more containers |[](https://asciinema.org/a/7EMk22WrfGtKWmgHJX9Nze1Qp)| +| [kpod-rmi(1)](/docs/kpod-rmi.1.md) | Removes one or more images |[](https://asciinema.org/a/133799)| +| [kpod-save(1)](/docs/kpod-save.1.md) | Saves an image to an archive |[](https://asciinema.org/a/kp8kOaexEhEa20P1KLZ3L5X4g)| +| [kpod-stats(1)](/docs/kpod-stats.1.md) | Display a live stream of one or more containers' resource usage statistics|| +| [kpod-stop(1)](/docs/kpod-stop.1.md) | Stops one or more running containers || +| [kpod-tag(1)](/docs/kpod-tag.1.md) | Add an additional name to a local image |[](https://asciinema.org/a/133803)| +| [kpod-umount(1)](/docs/kpod-umount.1.md) | Unmount a working container's root filesystem || +| [kpod-unpause(1)](/docs/kpod-unpause.1.md) | Unpause one or more running containers |[](https://asciinema.org/a/141292)| +| [kpod-version(1)](/docs/kpod-version.1.md) | Display the version information |[](https://asciinema.org/a/mfrn61pjZT9Fc8L4NbfdSqfgu)| +| [kpod-wait(1)](/docs/kpod-wait.1.md) | Wait on one or more containers to stop and print their exit codes|| + +## OCI Hooks Support + +[KPOD configures OCI Hooks to run when launching a container](./hooks.md) + +## KPOD Usage Transfer + +[Useful information for ops and dev transfer as it relates to infrastructure that utilizes KPOD](/transfer.md) + +## Communication + +For async communication and long running discussions please use issues and pull requests on the github repo. This will be the best place to discuss design and implementation. + +For sync communication we have an IRC channel #KPOD, on chat.freenode.net, that everyone is welcome to join and chat about development. + +## Getting started + +### Prerequisites + +Latest version of `runc` is expected to be installed on the system. It is picked up as the default runtime by kpod. + +### Build and Run Dependencies + +**Required** + +Fedora, CentOS, RHEL, and related distributions: + +```bash +yum install -y \ + btrfs-progs-devel \ + device-mapper-devel \ + git \ + glib2-devel \ + glibc-devel \ + glibc-static \ + go \ + golang-github-cpuguy83-go-md2man \ + gpgme-devel \ + libassuan-devel \ + libgpg-error-devel \ + libseccomp-devel \ + libselinux-devel \ + ostree-devel \ + pkgconfig \ + runc \ + skopeo-containers +``` + +Debian, Ubuntu, and related distributions: + +```bash +apt-get install -y \ + btrfs-tools \ + git \ + golang-go \ + libassuan-dev \ + libdevmapper-dev \ + libglib2.0-dev \ + libc6-dev \ + libgpgme11-dev \ + libgpg-error-dev \ + libseccomp-dev \ + libselinux1-dev \ + pkg-config \ + runc \ + skopeo-containers +``` + +Debian, Ubuntu, and related distributions will also need a copy of the development libraries for `ostree`, either in the form of the `libostree-dev` package from the [flatpak](https://launchpad.net/~alexlarsson/+archive/ubuntu/flatpak) PPA, or built [from source](https://github.com/ostreedev/ostree) (more on that [here](https://ostree.readthedocs.io/en/latest/#building)). + +If using an older release or a long-term support release, be careful to double-check that the version of `runc` is new enough (running `runc --version` should produce `spec: 1.0.0`), or else build your own. + +**NOTE** + +Be careful to double-check that the version of golang is new enough, version 1.8.x or higher is required. If needed, golang kits are avaliable at https://golang.org/dl/ + +**Optional** + +Fedora, CentOS, RHEL, and related distributions: + +(no optional packages) + +Debian, Ubuntu, and related distributions: + +```bash +apt-get install -y \ + libapparmor-dev +``` + +### Get Source Code + +As with other Go projects, KPOD must be cloned into a directory structure like: + +``` +GOPATH +└── src + └── github.com + └── projectatomic + └── libpod +``` + +First, configure a `GOPATH` (if you are using go1.8 or later, this defaults to `~/go`). + +```bash +export GOPATH=~/go +mkdir -p $GOPATH +``` + +Next, clone the source code using: + +```bash +mkdir -p $GOPATH/src/github.com/projectatomic +cd $_ # or cd $GOPATH/src/github.com/projectatomic +git clone https://github.com/projectatomic/libpod # or your fork +cd libpod +``` + +### Build + +```bash +make install.tools +make +sudo make install +``` + +Otherwise, if you do not want to build `kpod` with seccomp support you can add `BUILDTAGS=""` when running make. + +```bash +make BUILDTAGS="" +sudo make install +``` + +#### Build Tags + +`kpod` supports optional build tags for compiling support of various features. +To add build tags to the make option the `BUILDTAGS` variable must be set. + +```bash +make BUILDTAGS='seccomp apparmor' +``` + +| Build Tag | Feature | Dependency | +|-----------|------------------------------------|-------------| +| seccomp | syscall filtering | libseccomp | +| selinux | selinux process and mount labeling | libselinux | +| apparmor | apparmor profile support | libapparmor | + +### Running pods and containers + +Follow this [tutorial](tutorial.md) to get started with KPOD. + +### Setup CNI networking + +A proper description of setting up CNI networking is given in the +[`contrib/cni` README](contrib/cni/README.md). But the gist is that you need to +have some basic network configurations enabled and CNI plugins installed on +your system. + +### Current Roadmap + +1. Basic pod/container lifecycle, basic image pull (done) +1. Support for tty handling and state management (done) +1. Basic integration with kubelet once client side changes are ready (done) +1. Support for log management, networking integration using CNI, pluggable image/storage management (done) +1. Support for exec/attach (done) diff --git a/transfer.md b/transfer.md index 95fd7a2e7..3f188cf84 100644 --- a/transfer.md +++ b/transfer.md @@ -1,12 +1,12 @@ -# CRI-O Usage Transfer +# KPOD Usage Transfer -This document outlines useful information for ops and dev transfer as it relates to infrastructure that utilizes CRI-O. +This document outlines useful information for ops and dev transfer as it relates to infrastructure that utilizes KPOD. ## Operational Transfer ## Abstract -The `crio` daemon is intended to provide the [CRI](https://github.com/kubernetes/community/blob/master/contributors/devel/container-runtime-interface.md) socket needed for Kubernetes to use for automating deployment, scaling, and management of containerized applications (See the document for [configuring kubernetes to use CRI-O](./kubernetes.md) for more information on that). +The `crio` daemon is intended to provide the [CRI](https://github.com/kubernetes/community/blob/master/contributors/devel/container-runtime-interface.md) socket needed for Kubernetes to use for automating deployment, scaling, and management of containerized applications (See the document for [configuring kubernetes to use KPOD](./kubernetes.md) for more information on that). Therefore the `crioctl` command line is a client that interfaces to the same grpc socket as the kubernetes daemon would, for talking to the `crio` daemon. In many ways `crioctl` is only as feature rich as the Kubernetes CRI requires. There are additional tools e.g. `kpod` and [`buildah`](https://github.com/projectatomic/buildah) that provide a feature rich set of commands for all operational needs in a Kubernetes environment. @@ -20,24 +20,22 @@ As well as some systemd helpers like `systemd-cgls` and `systemd-cgtop` are stil ## Equivalents For many troubleshooting and information collection steps, there may be an existing pattern. -Following provides equivalent with CRI-O tools for gathering information or jumping into containers, for operational use. +Following provides equivalent with KPOD tools for gathering information or jumping into containers, for operational use. -| Existing Step | CRI-O (and friends) | +| Existing Step | KPOD (and friends) | | :---: | :---: | -| `docker exec` | [`crioctl ctr exec`](./docs/crio.8.md) | +| `docker exec` | [`kpod exec`](./docs/kpod-exec.1.md) | | `docker info` | [`kpod info`](./docs/kpod-info.1.md) | | `docker inspect` | [`kpod inspect`](./docs/kpod-inspect.1.md) | | `docker logs` | [`kpod logs`](./docs/kpod-logs.1.md) | -| `docker ps` | [`crioctl ctr list`](./docs/crio.8.md) or [`runc list`](https://github.com/opencontainers/runc/blob/master/man/runc-list.8.md) | -| `docker stats` | [`kpod stats`](./docs/kpod-stats.1.md) or `crioctl ctr status`| - -If you were already using steps like `kubectl exec` (or `oc exec` on OpenShift), they will continue to function the same way. +| `docker ps` | [`kpod ps`](./docs/kpod-ps.1.md) | +| `docker stats` | [`kpod stats`](./docs/kpod-stats.1.md)| ## Development Transfer There are other equivalents for these tools -| Existing Step | CRI-O (and friends) | +| Existing Step | KPOD (and friends) | | :---: | :---: | | `docker attach` | [`kpod exec`](./docs/kpod-attach.1.md) ***| | `docker build` | [`buildah bud`](https://github.com/projectatomic/buildah/blob/master/docs/buildah-bud.md) | |