github.com/containers/podman/v2@v2.2.2-0.20210501105131-c1e07d070c4c/pkg/hooks/docs/oci-hooks.5.md (about)

     1  % oci-hooks(5) OCI Hooks Configuration
     2  % W. Trevor King
     3  % MAY 2018
     4  
     5  # NAME
     6  
     7  oci-hooks - OCI hooks configuration directories
     8  
     9  # SYNOPSIS
    10  
    11  `/usr/share/containers/oci/hooks.d/*.json`
    12  
    13  # DESCRIPTION
    14  
    15  Provides a way for users to configure the intended hooks for Open Container Initiative containers so they will only be executed for containers that need their functionality, and then only for the stages where they're needed.
    16  
    17  ## Directories
    18  
    19  Hooks are configured with JSON files (ending with a `.json` extension) in a series of hook directories.
    20  The default directory is `/usr/share/containers/oci/hooks.d`, but tools consuming this format may change that default, include additional directories, or provide their callers with ways to adjust the configuration directories.
    21  
    22  If multiple directories are configured, a JSON filename in a preferred directory masks entries with the same filename in directories with lower precedence.  For example, if a consuming tool watches for hooks in `/etc/containers/oci/hooks.d` and `/usr/share/containers/oci/hooks.d` (in order of decreasing precedence), then a hook definition in `/etc/containers/oci/hooks.d/01-my-hook.json` will mask any definition in `/usr/share/containers/oci/hooks.d/01-my-hook.json`.
    23  
    24  Tools consuming this format may also opt to monitor the hook directories for changes, in which case they will notice additions, changes, and removals to JSON files without needing to be restarted or otherwise signaled.  When the tool monitors multiple hooks directories, the precedence discussed in the previous paragraph still applies.  For example, if a consuming tool watches for hooks in `/etc/containers/oci/hooks.d` and `/usr/share/containers/oci/hooks.d` (in order of decreasing precedence), then writing a new hook definition to `/etc/containers/oci/hooks.d/01-my-hook.json` will mask the hook previously loaded from `/usr/share/containers/oci/hooks.d/01-my-hook.json`.  Subsequent changes to `/usr/share/containers/oci/hooks.d/01-my-hook.json` will have no effect on the consuming tool as long as `/etc/containers/oci/hooks.d/01-my-hook.json` exists.  Removing `/etc/containers/oci/hooks.d/01-my-hook.json` will reload the hook from `/usr/share/containers/oci/hooks.d/01-my-hook.json`.
    25  
    26  Hooks are injected in the order obtained by sorting the JSON file names, after converting them to lower case, based on their Unicode code points.
    27  For example, 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`.
    28  It is strongly recommended to make the sort order unambiguous depending on an ASCII-only prefix (like the `01`/`02` above).
    29  
    30  Each JSON file should contain an object with one of the following schemas.
    31  
    32  ## 1.0.0 Hook Schema
    33  
    34  `version` (required string)
    35    Sets the hook-definition version.  For this schema version, the value be `1.0.0`.
    36  
    37  `hook` (required object)
    38    The hook to inject, with the hook-entry schema defined by the 1.0.1 OCI Runtime Specification.
    39  
    40  `when` (required object)
    41    Conditions under which the hook is injected.  The following properties can be specified, and at least one must be specified:
    42  
    43    * `always` (optional boolean)
    44        If set `true`, this condition matches.
    45    * `annotations` (optional object)
    46        If all `annotations` key/value pairs match a key/value pair from the configured annotations, this condition matches.
    47        Both keys and values must be POSIX extended regular expressions.
    48    * `commands` (optional array of strings)
    49        If the configured `process.args[0]` matches an entry, this condition matches.
    50        Entries must be POSIX extended regular expressions.
    51    * `hasBindMounts` (optional boolean)
    52        If `hasBindMounts` is true and the caller requested host-to-container bind mounts, this condition matches.
    53  
    54  `stages` (required array of strings)
    55    Stages when the hook must be injected.  Entries must be chosen from the 1.0.1 OCI Runtime Specification hook stages or from extension stages supported by the package consumer.
    56  
    57  If *all* of the conditions set in `when` match, then the `hook` must be injected for the stages set in `stages`.
    58  
    59  ## 0.1.0 Hook Schema
    60  
    61  `hook` (required string)
    62    Sets `path` in the injected hook.
    63  
    64  `arguments` (optional array of strings)
    65    Additional arguments to pass to the hook.  The injected hook's `args` is `hook` with `arguments` appended.
    66  
    67  `stages` (required array of strings)
    68    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 the 1.0.1 OCI Runtime Specification hook stages or from extension stages supported by the package consumer.
    69  
    70  `cmds` (optional array of strings)
    71    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.
    72  
    73  `annotations` (optional array of strings)
    74    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.
    75  
    76  `hasbindmounts` (optional boolean)
    77    The hook must be injected if `hasBindMounts` is true and the caller requested host-to-container bind mounts.
    78  
    79  # EXAMPLE
    80  
    81  ## 1.0.0 Hook Schema
    82  
    83  The following configuration injects `oci-systemd-hook` in the pre-start and post-stop stages if `process.args[0]` ends with `/init` or `/systemd`:
    84  
    85  ```console
    86  $ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
    87  {
    88    "version": "1.0.0",
    89    "hook": {
    90      "path": "/usr/libexec/oci/hooks.d/oci-systemd-hook"
    91    },
    92    "when": {
    93      "commands": [".*/init$" , ".*/systemd$"]
    94    },
    95    "stages": ["prestart", "poststop"]
    96  }
    97  ```
    98  
    99  The following example injects `oci-umount --debug` in the pre-start stage if the container is configured to bind-mount host directories into the container.
   100  
   101  ```console
   102  $ cat /etc/containers/oci/hooks.d/oci-umount.json
   103  {
   104    "version": "1.0.0",
   105    "hook": {
   106      "path": "/usr/libexec/oci/hooks.d/oci-umount",
   107      "args": ["oci-umount", "--debug"],
   108    },
   109    "when": {
   110      "hasBindMounts": true
   111    },
   112    "stages": ["prestart"]
   113  }
   114  ```
   115  
   116  The following example injects `nvidia-container-runtime-hook prestart` with particular environment variables in the pre-start stage if the container is configured with an `annotations` entry whose key matches `^com\.example\.department$` and whose value matches `.*fluid-dynamics.*`.
   117  
   118  ```console
   119  $ cat /etc/containers/oci/hooks.d/nvidia.json
   120  {
   121    "version": "1.0.0",
   122    "hook": {
   123      "path": "/usr/sbin/nvidia-container-runtime-hook",
   124      "args": ["nvidia-container-runtime-hook", "prestart"],
   125      "env": [
   126        "NVIDIA_REQUIRE_CUDA=cuda>=9.1",
   127        "NVIDIA_VISIBLE_DEVICES=GPU-fef8089b"
   128      ]
   129    },
   130    "when": {
   131      "annotations": {
   132        "^com\\.example\\.department$": ".*fluid-dynamics$"
   133      }
   134    },
   135    "stages": ["prestart"]
   136  }
   137  ```
   138  
   139  ## 0.1.0 Hook Schema
   140  
   141  The following configuration injects `oci-systemd-hook` in the pre-start and post-stop stages if `process.args[0]` ends with `/init` or `/systemd`:
   142  
   143  ```console
   144  $ cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
   145  {
   146    "cmds": [".*/init$" , ".*/systemd$"],
   147    "hook": "/usr/libexec/oci/hooks.d/oci-systemd-hook",
   148    "stages": ["prestart", "poststop"]
   149  }
   150  ```
   151  
   152  The following example injects `oci-umount --debug` in the pre-start stage if the container is configured to bind-mount host directories into the container.
   153  
   154  ```console
   155  $ cat /etc/containers/oci/hooks.d/oci-umount.json
   156  {
   157    "hook": "/usr/libexec/oci/hooks.d/oci-umount",
   158    "arguments": ["--debug"],
   159    "hasbindmounts": true,
   160    "stages": ["prestart"]
   161  }
   162  ```
   163  
   164  The following example injects `nvidia-container-runtime-hook prestart` in the pre-start stage if the container is configured with an `annotations` entry whose value matches `.*fluid-dynamics.*`.
   165  
   166  ```console
   167  $ cat /etc/containers/oci/hooks.d/osystemd-hook.json
   168  {
   169    "hook": "/usr/sbin/nvidia-container-runtime-hook",
   170    "arguments": ["prestart"],
   171    "annotations: [".*fluid-dynamics.*"],
   172    "stages": ["prestart"]
   173  }
   174  ```
   175  
   176  # SEE ALSO
   177  
   178  `oci-systemd-hook(1)`, `oci-umount(1)`, `locale(7)`
   179  
   180  * [OCI Runtime Specification, 1.0.1, POSIX-platform hooks](https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#posix-platform-hooks)
   181  * [OCI Runtime Specification, 1.0.1, process](https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#process)
   182  * [POSIX extended regular expressions (EREs)](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04)