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 executed each hook at each stage (pre-start, post-start, and post-stop).

The hooks configuration is documented in oci-hooks.5.

Documentation

Overview

Package hooks implements hook configuration and handling for CRI-O and libpod.

Package hooks implements CRI-O's hook handling.

Index

• Constants
• Variables
• func Read(path string, extensionStages []string) (*current.Hook, error)
• func ReadDir(path string, extensionStages []string, hooks map[string]*current.Hook) error
• type Manager
  • func New(_ context.Context, directories []string, extensionStages []string) (manager *Manager, err error)
  • func (m *Manager) Hooks(config *rspec.Spec, annotations map[string]string, hasBindMounts bool) (extensionStageHooks map[string][]rspec.Hook, 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, extensionStages []string) (*current.Hook, error)

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

func ReadDir

func ReadDir(path string, extensionStages []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(_ context.Context, directories []string, extensionStages []string) (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).

extensionStages allows callers to add additional stages beyond those specified in the OCI Runtime Specification and to control OCI-defined stages instead of delegating to the OCI runtime. See Hooks() for more information.

func (*Manager) Hooks

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

Hooks injects OCI runtime hooks for a given container configuration.

If extensionStages was set when initializing the Manager, matching hooks requesting those stages will be returned in extensionStageHooks. This takes precedence over their inclusion in the OCI configuration. For example:

manager, err := New(ctx, []string{DefaultDir}, []string{"poststop"})
extensionStageHooks, err := manager.Hooks(config, annotations, hasBindMounts)

will have any matching post-stop hooks in extensionStageHooks and will not insert them into config.Hooks.Poststop.

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 writes 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