2018-05-15 14:51:56 +00:00
2017-11-01 19:30:09 +00:00
# libpod - library for running OCI-based containers in Pods
2018-01-16 00:26:42 +00:00
### Status: Active Development
2017-11-01 19:30:09 +00:00
## What is the scope of this project?
2017-11-09 15:49:25 +00:00
libpod provides a library for applications looking to use the Container Pod concept popularized by Kubernetes.
2018-05-11 14:37:35 +00:00
libpod also contains a tool called podman for managing Pods, Containers, and Container Images.
2017-11-01 19:30:09 +00:00
2018-05-11 14:37:35 +00:00
At a high level, the scope of libpod and podman is the following:
2017-11-01 19:30:09 +00:00
2018-01-18 20:37:42 +00:00
* Support multiple image formats including the existing Docker/OCI image formats.
* Support for multiple means to download images including trust & image verification.
* Container image management (managing image layers, overlay filesystems, etc).
2018-05-11 14:37:35 +00:00
* Full management of container lifecycle
* Support for pods to manage groups of containers together
* Resource isolation of containers and pods.
2017-11-01 19:30:09 +00:00
## What is not in scope for this project?
2018-08-18 14:50:50 +00:00
* Signing and pushing images to various image storages. See [Skopeo ](https://github.com/containers/skopeo/ ).
2018-05-11 14:37:35 +00:00
* Container Runtimes daemons for working with Kubernetes CRIs. See [CRI-O ](https://github.com/kubernetes-incubator/cri-o ). We are working to integrate libpod into CRI-O to share containers and backend code with Podman.
2017-11-01 19:30:09 +00:00
2018-01-18 20:37:42 +00:00
## OCI Projects Plans
2017-11-01 19:30:09 +00:00
The plan is to use OCI projects and best of breed libraries for different aspects:
2018-05-11 14:37:35 +00:00
- Runtime: [runc ](https://github.com/opencontainers/runc ) (or any OCI compliant runtime) and [oci runtime tools ](https://github.com/opencontainers/runtime-tools ) to generate the spec
2017-11-01 19:30:09 +00:00
- Images: Image management using [containers/image ](https://github.com/containers/image )
2018-05-11 14:37:35 +00:00
- Storage: Container and image storage is managed by [containers/storage ](https://github.com/containers/storage )
2017-11-01 19:30:09 +00:00
- Networking: Networking support through use of [CNI ](https://github.com/containernetworking/cni )
2018-05-11 14:37:35 +00:00
- Builds: Builds are supported via [Buildah ](https://github.com/projectatomic/buildah ).
- Conmon: [Conmon ](https://github.com/kubernetes-incubator/cri-o ) is a tool for monitoring OCI runtimes. It is part of the CRI-O package
2017-11-01 19:30:09 +00:00
2018-01-16 00:26:42 +00:00
## Podman Information for Developers
2018-05-17 15:18:01 +00:00
**[Installation notes](install.md)**
2018-01-16 00:26:42 +00:00
Information on how to install Podman in your environment.
pkg/hooks: Version the hook structure and add 1.0.0 hooks
This shifts the matching logic out of libpod/container_internal and
into the hook package, where we can reuse it after vendoring into
CRI-O. It also adds unit tests with almost-complete coverage. Now
libpod is even more isolated from the hook internals, which makes it
fairly straightforward to bump the hook config file to 1.0.0. I've
dubbed the old format 0.1.0, although it doesn't specify an explicit
version. Motivation for some of my changes with 1.0.0:
* Add an explicit version field. This will make any future JSON
structure migrations more straightforward by avoiding the need for
version-guessing heuristics.
* Collect the matching properties in a new When sub-structure. This
makes the root Hook structure easier to understand, because you
don't have to read over all the matching properties when wrapping
your head around Hook.
* Replace the old 'hook' and 'arguments' with a direct embedding of
the runtime-spec's hook structure. This provides access to
additional upstream properties (args[0], env, and timeout) and
avoids the complication of a CRI-O-specific analog structure.
* Add a 'when.always' property. You can usually accomplish this
effect in another way (e.g. when.commands = [".*"]), but having a
boolean explicitly for this use-case makes for easier reading and
writing.
* Replace the previous annotations array with an annotations map. The
0.1.0 approach matched only the values regardless of key, and that
seems unreliable.
* Replace 'cmds' with 'when.commands', because while there are a few
ways to abbreviate "commands", there's only one way to write it out
in full ;). This gives folks one less thing to remember when
writing hook JSON.
* Replace the old "inject if any specified condition matches" with
"inject if all specified conditions match". This allows for more
precise targeting. Users that need more generous targeting can
recover the previous behavior by creating a separate 1.0.0 hook file
for each specified 0.1.0 condition.
I've added doc-compat support for the various pluralizations of the
0.1.0 properties. Previously, the docs and code were not in
agreement. More on this particular facet in [1].
I've updated the docs to point out that the annotations being matched
are the OCI config annotations. This differs from CRI-O, where the
annotations used are the Kubernetes-supplied annotations [2,3]. For
example, io.kubernetes.cri-o.Volumes [4] is part of CRI-O's runtime
config annotations [5], but not part of the Kubernetes-supplied
annotations CRI-O uses for matching hooks.
The Monitor method supports the CRI-O use-case [6]. podman doesn't
need it directly, but CRI-O will need it when we vendor this package
there.
I've used nvidia-container-runtime-hook for the annotation examples
because Dan mentioned the Nvidia folks as the motivation behind
annotation matching. The environment variables are documented in [7].
The 0.1.0 hook config, which does not allow for environment variables,
only works because runc currently leaks the host environment into the
hooks [8]. I haven't been able to find documentation for their usual
annotation trigger or hook-install path, so I'm just guessing there.
[1]: https://github.com/kubernetes-incubator/cri-o/pull/1235
[2]: https://github.com/kubernetes-incubator/cri-o/blob/v1.10.0/server/container_create.go#L760
[3]: https://github.com/kubernetes-incubator/cri-o/blob/v1.10.0/server/container_create.go#L772
[4]: https://github.com/kubernetes-incubator/cri-o/blob/v1.10.0/pkg/annotations/annotations.go#L97-L98
[5]: https://github.com/kubernetes-incubator/cri-o/blob/v1.10.0/server/container_create.go#L830-L834
[6]: https://github.com/kubernetes-incubator/cri-o/pull/1345/
[7]: https://github.com/NVIDIA/nvidia-container-runtime/tree/v1.3.0-1#environment-variables-oci-spec
[8]: https://github.com/opencontainers/runc/pull/1738
Signed-off-by: W. Trevor King <wking@tremily.us>
Closes: #686
Approved by: mheon
2018-04-27 17:35:32 +00:00
**[OCI Hooks Support](pkg/hooks/README.md)**
Information on how Podman configures [OCI Hooks][spec-hooks] to run when launching a container.
2018-01-16 00:26:42 +00:00
2018-05-17 15:18:01 +00:00
**[Podman API](API.md)**
Documentation on the Podman API using [Varlink ](https://www.varlink.org/ ).
**[Podman Commands](commands.md)**
2018-01-18 20:37:42 +00:00
A list of the Podman commands with links to their man pages and in many cases videos
showing the commands in use.
2018-01-16 00:26:42 +00:00
2018-05-17 15:18:01 +00:00
**[Podman Troubleshooting Guide](troubleshooting.md)**
A list of common issues and solutions for Podman.
**[Podman Usage Transfer](transfer.md)**
2018-01-18 20:37:42 +00:00
Useful information for ops and dev transfer as it relates to infrastructure that utilizes Podman. This page
includes tables showing Docker commands and their Podman equivalent commands.
2018-01-16 00:26:42 +00:00
2018-02-15 12:31:46 +00:00
**[Tutorials](docs/tutorials)**
2018-05-11 14:37:35 +00:00
Tutorials on using Podman.
2018-01-16 00:26:42 +00:00
2018-04-27 18:58:18 +00:00
**[Contributing](CONTRIBUTING.md)**
Information about contributing to this project.
2017-11-01 19:30:09 +00:00
### Current Roadmap
2018-05-11 14:37:35 +00:00
1. Varlink API for Podman
1. Integrate libpod into CRI-O to replace its existing container management backend
1. Pod commands for Podman
1. Rootless containers
1. Support for cleaning up containers via post-run hooks
pkg/hooks: Version the hook structure and add 1.0.0 hooks
This shifts the matching logic out of libpod/container_internal and
into the hook package, where we can reuse it after vendoring into
CRI-O. It also adds unit tests with almost-complete coverage. Now
libpod is even more isolated from the hook internals, which makes it
fairly straightforward to bump the hook config file to 1.0.0. I've
dubbed the old format 0.1.0, although it doesn't specify an explicit
version. Motivation for some of my changes with 1.0.0:
* Add an explicit version field. This will make any future JSON
structure migrations more straightforward by avoiding the need for
version-guessing heuristics.
* Collect the matching properties in a new When sub-structure. This
makes the root Hook structure easier to understand, because you
don't have to read over all the matching properties when wrapping
your head around Hook.
* Replace the old 'hook' and 'arguments' with a direct embedding of
the runtime-spec's hook structure. This provides access to
additional upstream properties (args[0], env, and timeout) and
avoids the complication of a CRI-O-specific analog structure.
* Add a 'when.always' property. You can usually accomplish this
effect in another way (e.g. when.commands = [".*"]), but having a
boolean explicitly for this use-case makes for easier reading and
writing.
* Replace the previous annotations array with an annotations map. The
0.1.0 approach matched only the values regardless of key, and that
seems unreliable.
* Replace 'cmds' with 'when.commands', because while there are a few
ways to abbreviate "commands", there's only one way to write it out
in full ;). This gives folks one less thing to remember when
writing hook JSON.
* Replace the old "inject if any specified condition matches" with
"inject if all specified conditions match". This allows for more
precise targeting. Users that need more generous targeting can
recover the previous behavior by creating a separate 1.0.0 hook file
for each specified 0.1.0 condition.
I've added doc-compat support for the various pluralizations of the
0.1.0 properties. Previously, the docs and code were not in
agreement. More on this particular facet in [1].
I've updated the docs to point out that the annotations being matched
are the OCI config annotations. This differs from CRI-O, where the
annotations used are the Kubernetes-supplied annotations [2,3]. For
example, io.kubernetes.cri-o.Volumes [4] is part of CRI-O's runtime
config annotations [5], but not part of the Kubernetes-supplied
annotations CRI-O uses for matching hooks.
The Monitor method supports the CRI-O use-case [6]. podman doesn't
need it directly, but CRI-O will need it when we vendor this package
there.
I've used nvidia-container-runtime-hook for the annotation examples
because Dan mentioned the Nvidia folks as the motivation behind
annotation matching. The environment variables are documented in [7].
The 0.1.0 hook config, which does not allow for environment variables,
only works because runc currently leaks the host environment into the
hooks [8]. I haven't been able to find documentation for their usual
annotation trigger or hook-install path, so I'm just guessing there.
[1]: https://github.com/kubernetes-incubator/cri-o/pull/1235
[2]: https://github.com/kubernetes-incubator/cri-o/blob/v1.10.0/server/container_create.go#L760
[3]: https://github.com/kubernetes-incubator/cri-o/blob/v1.10.0/server/container_create.go#L772
[4]: https://github.com/kubernetes-incubator/cri-o/blob/v1.10.0/pkg/annotations/annotations.go#L97-L98
[5]: https://github.com/kubernetes-incubator/cri-o/blob/v1.10.0/server/container_create.go#L830-L834
[6]: https://github.com/kubernetes-incubator/cri-o/pull/1345/
[7]: https://github.com/NVIDIA/nvidia-container-runtime/tree/v1.3.0-1#environment-variables-oci-spec
[8]: https://github.com/opencontainers/runc/pull/1738
Signed-off-by: W. Trevor King <wking@tremily.us>
Closes: #686
Approved by: mheon
2018-04-27 17:35:32 +00:00
[spec-hooks]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#posix-platform-hooks
