mirror of https://github.com/containers/podman.git
175 lines
11 KiB
Markdown
175 lines
11 KiB
Markdown
|
||
|
||
# Podman: A tool for managing OCI containers and pods
|
||
|
||
Podman (the POD MANager) is a tool for managing containers and images, volumes mounted into those containers, and pods made from groups of containers.
|
||
Podman is based on libpod, a library for container lifecycle management that is also contained in this repository. The libpod library provides APIs for managing containers, pods, container images, and volumes.
|
||
|
||
* [Latest Version: 3.1.0](https://github.com/containers/podman/releases/latest)
|
||
* Latest Remote client for Windows
|
||
* Latest Remote client for MacOs
|
||
* Latest Static Remote client for Linux
|
||
|
||
* Continuous Integration: [](https://cirrus-ci.com/github/containers/podman/master)
|
||
* [GoDoc: ](https://godoc.org/github.com/containers/podman/libpod)
|
||
|
||
## Overview and scope
|
||
|
||
At a high level, the scope of Podman and libpod is the following:
|
||
|
||
* Support for multiple container image formats, including OCI and Docker images.
|
||
* Full management of those images, including pulling from various sources (including trust and verification), creating (built via Containerfile or Dockerfile or committed from a container), and pushing to registries and other storage backends.
|
||
* Full management of container lifecycle, including creation (both from an image and from an exploded root filesystem), running, checkpointing and restoring (via CRIU), and removal.
|
||
* Support for pods, groups of containers that share resources and are managed together.
|
||
* Support for running containers and pods without root or other elevated privileges.
|
||
* Resource isolation of containers and pods.
|
||
* Support for a Docker-compatible CLI interface.
|
||
* No manager daemon, for improved security and lower resource utilization at idle.
|
||
* Support for a REST API providing both a Docker-compatible interface and an improved interface exposing advanced Podman functionality.
|
||
* In the future, integration with [CRI-O](https://github.com/cri-o/cri-o) to share containers and backend code.
|
||
|
||
Podman presently only supports running containers on Linux. However, we are building a remote client which can run on Windows and OS X and manage Podman containers on a Linux system via the REST API using SSH tunneling.
|
||
|
||
## Roadmap
|
||
|
||
1. Further improvements to the REST API, with a focus on bugfixes and implementing missing functionality
|
||
1. Integrate libpod into [CRI-O](https://github.com/cri-o/cri-o) to replace its existing container management backend
|
||
1. Improvements on rootless containers, with a focus on improving the user experience and exposing presently-unavailable features when possible
|
||
|
||
## Communications
|
||
|
||
If you think you've identified a security issue in the project, please *DO NOT* report the issue publicly via the GitHub issue tracker, mailing list, or IRC.
|
||
Instead, send an email with as many details as possible to `security@lists.podman.io`. This is a private mailing list for the core maintainers.
|
||
|
||
For general questions and discussion, please use the
|
||
IRC `#podman` channel on `irc.freenode.net`.
|
||
|
||
For discussions around issues/bugs and features, you can use the GitHub
|
||
[issues](https://github.com/containers/podman/issues)
|
||
and
|
||
[PRs](https://github.com/containers/podman/pulls)
|
||
tracking system.
|
||
|
||
There is also a [mailing list](https://lists.podman.io/archives/) at `lists.podman.io`.
|
||
You can subscribe by sending a message to `podman-join@lists.podman.io` with the subject `subscribe`.
|
||
|
||
## Rootless
|
||
Podman can be easily run as a normal user, without requiring a setuid binary.
|
||
When run without root, Podman containers use user namespaces to set root in the container to the user running Podman.
|
||
Rootless Podman runs locked-down containers with no privileges that the user running the container does not have.
|
||
Some of these restrictions can be lifted (via `--privileged`, for example), but rootless containers will never have more privileges than the user that launched them.
|
||
If you run Podman as your user and mount in `/etc/passwd` from the host, you still won't be able to change it, since your user doesn't have permission to do so.
|
||
|
||
Almost all normal Podman functionality is available, though there are some [shortcomings](https://github.com/containers/podman/blob/master/rootless.md).
|
||
Any recent Podman release should be able to run rootless without any additional configuration, though your operating system may require some additional configuration detailed in the [install guide](https://github.com/containers/podman/blob/master/install.md).
|
||
|
||
A little configuration by an administrator is required before rootless Podman can be used, the necessary setup is documented [here](https://github.com/containers/podman/blob/master/docs/tutorials/rootless_tutorial.md).
|
||
|
||
## Out of scope
|
||
|
||
* Specialized signing and pushing of images to various storage backends.
|
||
See [Skopeo](https://github.com/containers/skopeo/) for those tasks.
|
||
* Support for the Kubernetes CRI interface for container management.
|
||
The [CRI-O](https://github.com/cri-o/cri-o) daemon specializes in that.
|
||
|
||
## OCI Projects Plans
|
||
|
||
The plan is to use OCI projects and best of breed libraries for different aspects:
|
||
- Runtime: We use the [OCI runtime tools](https://github.com/opencontainers/runtime-tools) to generate OCI runtime configurations that can be used with any OCI-compliant runtime, like [crun](https://github.com/containers/crun/) and [runc](https://github.com/opencontainers/runc/).
|
||
- Images: Image management uses the [containers/image](https://github.com/containers/image) library.
|
||
- Storage: Container and image storage is managed by [containers/storage](https://github.com/containers/storage).
|
||
- Networking: Networking support through use of [CNI](https://github.com/containernetworking/cni).
|
||
- Builds: Builds are supported via [Buildah](https://github.com/containers/buildah).
|
||
- Conmon: [Conmon](https://github.com/containers/conmon) is a tool for monitoring OCI runtimes, used by both Podman and CRI-O.
|
||
- Seccomp: A unified [Seccomp](https://github.com/seccomp/containers-golang) policy for Podman, Buildah, and CRI-O.
|
||
|
||
## Podman Information for Developers
|
||
|
||
For blogs, release announcements and more, please checkout the [podman.io](https://podman.io) website!
|
||
|
||
**[Installation notes](install.md)**
|
||
Information on how to install Podman in your environment.
|
||
|
||
**[OCI Hooks Support](pkg/hooks/README.md)**
|
||
Information on how Podman configures [OCI Hooks][spec-hooks] to run when launching a container.
|
||
|
||
**[Podman API](http://docs.podman.io/en/latest/_static/api.html)**
|
||
Documentation on the Podman REST API.
|
||
|
||
**[Podman Commands](https://podman.readthedocs.io/en/latest/Commands.html)**
|
||
A list of the Podman commands with links to their man pages and in many cases videos
|
||
showing the commands in use.
|
||
|
||
**[Podman Troubleshooting Guide](troubleshooting.md)**
|
||
A list of common issues and solutions for Podman.
|
||
|
||
**[Podman Usage Transfer](transfer.md)**
|
||
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.
|
||
|
||
**[Tutorials](docs/tutorials)**
|
||
Tutorials on using Podman.
|
||
|
||
**[Remote Client](https://github.com/containers/podman/blob/master/docs/tutorials/remote_client.md)**
|
||
A brief how-to on using the Podman remote-client.
|
||
|
||
**[Basic Setup and Use of Podman in a Rootless environment](https://github.com/containers/podman/blob/master/docs/tutorials/rootless_tutorial.md)**
|
||
A tutorial showing the setup and configuration necessary to run Rootless Podman.
|
||
|
||
**[Release Notes](RELEASE_NOTES.md)**
|
||
Release notes for recent Podman versions.
|
||
|
||
**[Contributing](CONTRIBUTING.md)**
|
||
Information about contributing to this project.
|
||
|
||
[spec-hooks]: https://github.com/opencontainers/runtime-spec/blob/v1.0.2/config.md#posix-platform-hooks
|
||
|
||
## Buildah and Podman relationship
|
||
|
||
Buildah and Podman are two complementary open-source projects that are
|
||
available on most Linux platforms and both projects reside at
|
||
[GitHub.com](https://github.com) with Buildah
|
||
[here](https://github.com/containers/buildah) and Podman
|
||
[here](https://github.com/containers/podman). Both, Buildah and Podman are
|
||
command line tools that work on Open Container Initiative (OCI) images and
|
||
containers. The two projects differentiate in their specialization.
|
||
|
||
Buildah specializes in building OCI images. Buildah's commands replicate all
|
||
of the commands that are found in a Dockerfile. This allows building images
|
||
with and without Dockerfiles while not requiring any root privileges.
|
||
Buildah’s ultimate goal is to provide a lower-level coreutils interface to
|
||
build images. The flexibility of building images without Dockerfiles allows
|
||
for the integration of other scripting languages into the build process.
|
||
Buildah follows a simple fork-exec model and does not run as a daemon
|
||
but it is based on a comprehensive API in golang, which can be vendored
|
||
into other tools.
|
||
|
||
Podman specializes in all of the commands and functions that help you to maintain and modify
|
||
OCI images, such as pulling and tagging. It also allows you to create, run, and maintain those containers
|
||
created from those images. For building container images via Dockerfiles, Podman uses Buildah's
|
||
golang API and can be installed independently from Buildah.
|
||
|
||
A major difference between Podman and Buildah is their concept of a container. Podman
|
||
allows users to create "traditional containers" where the intent of these containers is
|
||
to be long lived. While Buildah containers are really just created to allow content
|
||
to be added back to the container image. An easy way to think of it is the
|
||
`buildah run` command emulates the RUN command in a Dockerfile while the `podman run`
|
||
command emulates the `docker run` command in functionality. Because of this and their underlying
|
||
storage differences, you can not see Podman containers from within Buildah or vice versa.
|
||
|
||
In short, Buildah is an efficient way to create OCI images while Podman allows
|
||
you to manage and maintain those images and containers in a production environment using
|
||
familiar container cli commands. For more details, see the
|
||
[Container Tools Guide](https://github.com/containers/buildah/tree/master/docs/containertools).
|
||
|
||
## Podman Former API (Varlink)
|
||
Podman formerly offered a Varlink-based API for remote management of containers. However, this API
|
||
was replaced by the REST API. Varlink support has been removed as of the 3.0 release.
|
||
For more details, you can see [this blog](https://podman.io/blogs/2020/01/17/podman-new-api.html).
|
||
|
||
## Static Binary Builds
|
||
The Cirrus CI integration within this repository contains a `static_build` job
|
||
which produces a static Podman binary for testing purposes. Please note that
|
||
this binary is not officially supported with respect to feature-completeness
|
||
and functionality and should be only used for testing.
|