mirror of https://github.com/containers/podman.git synced 2025-10-25 10:16:43 +08:00

Files

W. Trevor King 68eb128fb0 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-05-11 16:26:35 +00:00

3.3 KiB

Raw Blame History

libpod - library for running OCI-based containers in Pods

Status: Active Development

What is the scope of this project?

libpod provides a library for applications looking to use the Container Pod concept popularized by Kubernetes. libpod also contains a tool called podman for managing Pods, Containers, and Container Images.

At a high level, the scope of libpod and podman is the following:

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).
Full management of container lifecycle
Support for pods to manage groups of containers together
Resource isolation of containers and pods.

What is not in scope for this project?

Signing and pushing images to various image storages. See Skopeo.
Container Runtimes daemons for working with Kubernetes CRIs. See CRI-O. We are working to integrate libpod into CRI-O to share containers and backend code with Podman.

OCI Projects Plans

The plan is to use OCI projects and best of breed libraries for different aspects:

Runtime: runc (or any OCI compliant runtime) and oci runtime tools to generate the spec
Images: Image management using containers/image
Storage: Container and image storage is managed by containers/storage
Networking: Networking support through use of CNI
Builds: Builds are supported via Buildah.
Conmon: Conmon is a tool for monitoring OCI runtimes. It is part of the CRI-O package

Podman Information for Developers

Installation notes Information on how to install Podman in your environment.

OCI Hooks Support Information on how Podman configures OCI Hooks to run when launching a container.

Podman Commands A list of the Podman commands with links to their man pages and in many cases videos showing the commands in use.

Podman Usage Transfer 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.

Podman API Documentation on the Podman API using Varlink.

Tutorials Tutorials on using Podman.

Contributing Information about contributing to this project.

Current Roadmap

Varlink API for Podman
Integrate libpod into CRI-O to replace its existing container management backend
Pod commands for Podman
Rootless containers
Support for cleaning up containers via post-run hooks

3.3 KiB Raw Blame History