hooks

README

OCI Hooks Configuration

For POSIX platforms, the OCI runtime configuration supports hooks for configuring custom actions related to the life cycle of the container. The way you enable the hooks above is by editing the OCI runtime configuration before running the OCI runtime (e.g. runc). CRI-O and podman create create the OCI configuration for you, and this documentation allows developers to configure them to set their intended hooks.

One problem with hooks is that the runtime actually stalls execution of the container before running the hooks and stalls completion of the container, until all hooks complete. This can cause some performance issues. Also a lot of hooks just check if certain configuration is set and then exit early, without doing anything. For example the oci-systemd-hook only executes if the command is init or systemd, otherwise it just exits. This means if we automatically enabled all hooks, every container would have to execute oci-systemd-hook, even if they don't run systemd inside of the container. Performance would also suffer if we exectuted each hook at each stage (pre-start, post-start, and post-stop).

Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119.

JSON Definition

This package reads all JSON files (ending with a .json extention) from a series of hook directories. For both crio and podman, hooks are read from /usr/share/containers/oci/hooks.d/*.json.

For crio, hook JSON is also read from /etc/containers/oci/hooks.d/*.json. If files of with the same name exist in both directories, the one in /etc/containers/oci/hooks.d takes precedence.

Hooks MUST be injected in the JSON filename case- and width-insensitive collation order. Collation order depends on your locale, as set by LC_ALL, LC_COLLATE, or LANG (in order of decreasing precedence). For example, in the POSIX locale, a matching hook defined in 01-my-hook.json would be injected before matching hooks defined in 02-another-hook.json and 01-UPPERCASE.json.

Each JSON file should contain an object with the following properties:

1.0.0 Hook Schema

• version (REQUIRED, string) Sets the hook-definition version. For this schema version, the value MUST be 1.0.0.

• hook (REQUIRED, object) The hook to inject, with the hook-entry schema defined by the 1.0.1 OCI Runtime Specification.

• when (REQUIRED, object) Conditions under which the hook is injected. The following properties can be specified:

  • always (OPTIONAL, boolean) If set true, this condition matches.
  • annotations (OPTIONAL, object) If all annotations key/value pairs match a key/value pair from the configured annotations, this condition matches. Both keys and values MUST be POSIX extended regular expressions.
  • commands (OPTIONAL, array of strings) If the configured process.args[0] matches an entry, this condition matches. Entries MUST be POSIX extended regular expressions.
  • hasBindMounts (OPTIONAL, boolean) If hasBindMounts is true and the caller requested host-to-container bind mounts (beyond those that CRI-O or libpod use by default), this condition matches.

• stages (REQUIRED, array of strings) Stages when the hook MUST be injected. Entries MUST be chosen from the 1.0.1 OCI Runtime Specification hook stages.

If all of the conditions set in when match, then the hook MUST be injected for the stages set in stages.

Example

The following configuration injects oci-systemd-hook in the pre-start and post-stop stages if process.args[0] ends with /init or /systemd:

$ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
{
  "version": "1.0.0",
  "hook": {
    "path": "/usr/libexec/oci/hooks.d/oci-systemd-hook"
  }
  "when": {
    "args": [".*/init$" , ".*/systemd$"],
  },
  "stages": ["prestart", "poststop"]
}

The following example injects oci-umount --debug in the pre-start phase if the container is configured to bind-mount host directories into the container.

$ cat /etc/containers/oci/hooks.d/oci-umount.json
{
  "version": "1.0.0",
  "hook": {
    "path": "/usr/libexec/oci/hooks.d/oci-umount",
    "args": ["oci-umount", "--debug"],
  }
  "when": {
    "hasBindMounts": true,
  },
  "stages": ["prestart"]
}

The following example injects nvidia-container-runtime-hook prestart with particular environment variables in the pre-start phase if the container is configured with an annotations entry whose key matches ^com\.example\.department$ and whose value matches .*fluid-dynamics.*.

$ cat /etc/containers/oci/hooks.d/nvidia.json
{
  "hook": {
    "path": "/usr/sbin/nvidia-container-runtime-hook",
    "args": ["nvidia-container-runtime-hook", "prestart"],
    "env": [
      "NVIDIA_REQUIRE_CUDA=cuda>=9.1",
      "NVIDIA_VISIBLE_DEVICES=GPU-fef8089b"
    ]
  },
  "when": {
    "annotations": {
      "^com\.example\.department$": ".*fluid-dynamics$"
    }
  },
  "stages": ["prestart"]
}

0.1.0 Hook Schema

Previous versions of CRI-O and libpod supported the 0.1.0 hook schema:

• hook (REQUIRED, string) Sets path in the injected hook.
• arguments (OPTIONAL, array of strings) Additional arguments to pass to the hook. The injected hook's args is hook with arguments appended.
• stages (REQUIRED, array of strings) Stages when the hook MUST be injected. stage is an allowed synonym for this property, but you MUST NOT set both stages and stage. Entries MUST be chosen from:
  • prestart, to inject pre-start.
  • poststart, to inject post-start.
  • poststop, to inject post-stop.
• cmds (OPTIONAL, array of strings) The hook MUST be injected if the configured process.args[0] matches an entry. cmd is an allowed synonym for this property, but you MUST NOT set both cmds and cmd. Entries MUST be POSIX extended regular expressions.
• annotations (OPTIONAL, array of strings) The hook MUST be injected if an annotations entry matches a value from the configured annotations. annotation is an allowed synonym for this property, but you MUST NOT set both annotations and annotation. Entries MUST be POSIX extended regular expressions.
• hasbindmounts (OPTIONAL, boolean) The hook MUST be injected if hasBindMounts is true and the caller requested host-to-container bind mounts (beyond those that CRI-O or libpod use by default).

Example

The following configuration injects oci-systemd-hook in the pre-start and post-stop stages if process.args[0] ends with /init or /systemd:

$ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
{
  "cmds": [".*/init$" , ".*/systemd$"],
  "hook": "/usr/libexec/oci/hooks.d/oci-systemd-hook",
  "stages": ["prestart", "poststop"]
}

The following example injects oci-umount --debug in the pre-start phase if the container is configured to bind-mount host directories into the container.

$ cat /etc/containers/oci/hooks.d/oci-umount.json
{
  "hook": "/usr/libexec/oci/hooks.d/oci-umount",
  "arguments": ["--debug"],
  "hasbindmounts": true,
  "stages": ["prestart"]
}

The following example injects nvidia-container-runtime-hook prestart in the pre-start phase if the container is configured with an annotations entry whose value matches .*fluid-dynamics.*.

$ cat /etc/containers/oci/hooks.d/osystemd-hook.json
{
  "hook": "/usr/sbin/nvidia-container-runtime-hook",
  "arguments": ["prestart"],
  "annotations: [".*fluid-dynamics.*"],
  "stages": ["prestart"]
}

Documentation

Overview

Package hooks implements CRI-O's hook handling.

Package hooks implements CRI-O's hook handling.

Index

• Constants
• Variables
• func Read(path string) (*current.Hook, error)
• func ReadDir(path string, hooks map[string]*current.Hook) error
• type Manager
  • func New(ctx context.Context, directories []string, lang language.Tag) (manager *Manager, err error)
  • func (m *Manager) Hooks(config *rspec.Spec, annotations map[string]string, hasBindMounts bool) (err error)
  • func (m *Manager) Monitor(ctx context.Context, sync chan<- error)

Constants

const (
	// DefaultDir is the default directory containing system hook configuration files.
	DefaultDir = "/usr/share/containers/oci/hooks.d"

	// OverrideDir is the directory for hook configuration files overriding the default entries.
	OverrideDir = "/etc/containers/oci/hooks.d"
)

const Version = current.Version

Version is the current hook configuration version.

Variables

var (
	// ErrNoJSONSuffix represents hook-add attempts where the filename
	// does not end in '.json'.
	ErrNoJSONSuffix = errors.New("hook filename does not end in '.json'")

	// Readers registers per-version hook readers.
	Readers = map[string]reader{}
)

Functions

func Read

func Read(path string) (*current.Hook, error)

Read reads a hook JSON file, verifies it, and returns the hook configuration.

func ReadDir

func ReadDir(path string, hooks map[string]*current.Hook) error

ReadDir reads hook JSON files from a directory into the given map, clobbering any previous entries with the same filenames.

Types

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager provides an opaque interface for managing CRI-O hooks.

func New

func New(ctx context.Context, directories []string, lang language.Tag) (manager *Manager, err error)

New creates a new hook manager. Directories are ordered by increasing preference (hook configurations in later directories override configurations with the same filename from earlier directories).

func (*Manager) Hooks

func (m *Manager) Hooks(config *rspec.Spec, annotations map[string]string, hasBindMounts bool) (err error)

Hooks injects OCI runtime hooks for a given container configuration.

func (*Manager) Monitor

func (m *Manager) Monitor(ctx context.Context, sync chan<- error)

Monitor dynamically monitors hook directories for additions, updates, and removals.

This function write two empty structs to the sync channel: the first is written after the watchers are established and the second when this function exits. The expected usage is:

ctx, cancel := context.WithCancel(context.Background())
sync := make(chan error, 2)
go m.Monitor(ctx, sync)
err := <-sync // block until writers are established
if err != nil {
  return err // failed to establish watchers
}
// do stuff
cancel()
err = <-sync // block until monitor finishes