Configuring Sarus for OCI hooks

In order to extend the core functionality provided by a container runtime, the OCI Runtime Specification allows for components to be hooked into the container’s lifecycle, performing custom actions. These OCI hooks are especially amenable to HPC use cases, where the dedicated hardware and highly-tuned software adopted by high-performance systems are in contrast with the platform-agnostic nature of software containers. Effectively, OCI hooks provide solutions for the container runtime to allow access to system-specific features and specialized resources within container instances.

The enable the use of hooks in Sarus, the OCIHooks field in sarus.json must be populated. The OCIHooks object will be copied as-is into the configuration file of the OCI bundle generated by Sarus. The hooks will effectively be called by the OCI-compliant runtime specified with the runcPath parameter.

All the hooks entered in the configuration file must satisfy the security requirements for critical files and directories.

OCIHooks object format

The value of the OCIHooks field must be a JSON object with the same format specified by the OCI Runtime Specification for configuring POSIX-platform hooks. To ensure compatibility with the recommended OCI runtime (runc v1.0.0-rc5), we recommend the revision of the specification at commit f3be7d2032.

A brief description of the format follows.

The OCIHooks object can contain any of the following properties:

  • prestart (array of objects, OPTIONAL): array of prestart hooks. Entries in the array contain the following properties:

    • path (string, REQUIRED): absolute path to the hook program on the host.
    • args (array of strings, OPTIONAL): the elements of this list will be passed to the hook as arguments. As such, the first list element should be the hook program name.
    • env (array of strings, OPTIONAL): list strings using the key=value format, which will constitute the environment variables during hook execution. The hook’s environment will only be populated with these variables, and will not inherit anything from the runtime environment or the container environment.
    • timeout (int, OPTIONAL): the number of seconds before aborting the hook. If set, must be greater than zero.

  • poststart (array of objects, OPTIONAL): array of poststart hooks. Entries have the same format as prestart entries.

  • poststop (array of objects, OPTIONAL): array of poststop hooks. Entries have the same format as prestart entries.

Hooks are programs which will be run before or after various events in the lifecycle of the container. The hooks will be called by the runtime in the listed order, and they will be executed in the runtime namespace (i.e. on the host, and not inside the container). The state of the container will be passed to hooks over stdin, as detailed in the OCI Runtime Spec.

Prestart hooks will be called after the container namespaces have been set up, but before the user-specified program command is executed. These hooks provide an opportunity to customize the container, for example with specific bind-mounts or injecting non-standard resources.

Poststart hooks will be called immediately after the user-specified process is executed. For example, this hook can notify the user that the container process is spawned.

Poststop hooks will be called after the container is deleted but before the container runtime exits. For example, this hook can notify the user that the container process is spawned.

Hooks use cases

In the following pages, we will provide guidance on how to enable hooks for specific use cases: