summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMatthew Heon <matthew.heon@gmail.com>2017-11-01 15:38:08 -0400
committerGitHub <noreply@github.com>2017-11-01 15:38:08 -0400
commit843eede735fb55e27aaf26d9feda92f81aaa7525 (patch)
tree9adfa4ac0ef502de73038b8f2c3fef665c276847
parentd7782cc31e809d8e1551f47a0ddb0ff8073005fc (diff)
parent03d933d6cd8600cd6eeb8a125a2764f4bb9ed386 (diff)
downloadpodman-843eede735fb55e27aaf26d9feda92f81aaa7525.tar.gz
podman-843eede735fb55e27aaf26d9feda92f81aaa7525.tar.bz2
podman-843eede735fb55e27aaf26d9feda92f81aaa7525.zip
Merge pull request #3 from rhatdan/readme
Create README for libpod
-rw-r--r--README.md231
-rw-r--r--transfer.md20
2 files changed, 239 insertions, 12 deletions
diff --git a/README.md b/README.md
index f790da179..235163251 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,230 @@
-Under construction! \ No newline at end of file
+![KPOD logo](https://cdn.rawgit.com/kubernetes-incubator/cri-o/master/logo/crio-logo.svg)
+# 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 |[![...](/docs/play.png)](https://asciinema.org/a/FXfWB9CKYFwYM4EfqW3NSZy1G)|
+| [kpod-export(1)](/docs/kpod-export.1.md) | Export container's filesystem contents as a tar archive |[![...](/docs/play.png)](https://asciinema.org/a/913lBIRAg5hK8asyIhhkQVLtV)|
+| [kpod-history(1)](/docs/kpod-history.1.md) | Shows the history of an image |[![...](/docs/play.png)](https://asciinema.org/a/bCvUQJ6DkxInMELZdc5DinNSx)|
+| [kpod-images(1)](/docs/kpod-images.1.md) | List images in local storage |[![...](/docs/play.png)](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 |[![...](/docs/play.png)](https://asciinema.org/a/133418)|
+| [kpod-kill(1)](/docs/kpod-kill.1.md) | Kill the main process in one or more running containers |[![...](/docs/play.png)](https://asciinema.org/a/3jNos0A5yzO4hChu7ddKkUPw7)|
+| [kpod-load(1)](/docs/kpod-load.1.md) | Load an image from docker archive or oci |[![...](/docs/play.png)](https://asciinema.org/a/kp8kOaexEhEa20P1KLZ3L5X4g)|
+| [kpod-login(1)](/docs/kpod-login.1.md) | Login to a container registry |[![...](/docs/play.png)](https://asciinema.org/a/oNiPgmfo1FjV2YdesiLpvihtV)|
+| [kpod-logout(1)](/docs/kpod-logout.1.md) | Logout of a container registry |[![...](/docs/play.png)](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 |[![...](/docs/play.png)](https://asciinema.org/a/141292)|
+| [kpod-ps(1)](/docs/kpod-ps.1.md) | Prints out information about containers |[![...](/docs/play.png)](https://asciinema.org/a/bbT41kac6CwZ5giESmZLIaTLR)|
+| [kpod-pull(1)](/docs/kpod-pull.1.md) | Pull an image from a registry |[![...](/docs/play.png)](https://asciinema.org/a/lr4zfoynHJOUNu1KaXa1dwG2X)|
+| [kpod-push(1)](/docs/kpod-push.1.md) | Push an image to a specified destination |[![...](/docs/play.png)](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 |[![...](/docs/play.png)](https://asciinema.org/a/7EMk22WrfGtKWmgHJX9Nze1Qp)|
+| [kpod-rmi(1)](/docs/kpod-rmi.1.md) | Removes one or more images |[![...](/docs/play.png)](https://asciinema.org/a/133799)|
+| [kpod-save(1)](/docs/kpod-save.1.md) | Saves an image to an archive |[![...](/docs/play.png)](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 |[![...](/docs/play.png)](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 |[![...](/docs/play.png)](https://asciinema.org/a/141292)|
+| [kpod-version(1)](/docs/kpod-version.1.md) | Display the version information |[![...](/docs/play.png)](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) |