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).
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 ¶
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 ¶
Types ¶
type Manager ¶ added in v0.5.2
type Manager struct {
// contains filtered or unexported fields
}
Manager provides an opaque interface for managing CRI-O hooks.
func New ¶ added in v0.5.2
func New(ctx context.Context, directories []string, extensionStages []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).
extensionStages allows callers to add additional stages beyond those specified in the OCI Runtime Specification and to control OCI-defined stages instead of delagating to the OCI runtime. See Hooks() for more information.
func (*Manager) Hooks ¶ added in v0.5.2
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"}, lang) 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 ¶ added in v0.5.2
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
Directories
¶
Path | Synopsis |
---|---|
Package hook is the 0.1.0 hook configuration structure.
|
Package hook is the 0.1.0 hook configuration structure. |
Package hook is the 1.0.0 hook configuration structure.
|
Package hook is the 1.0.0 hook configuration structure. |
Package exec provides utilities for executing Open Container Initative runtime hooks.
|
Package exec provides utilities for executing Open Container Initative runtime hooks. |