containers
/
automation-tests
mirror of https://github.com/containers/automation-tests.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

pkg/hooks: Version the hook structure and add 1.0.0 hooks 

This shifts the matching logic out of libpod/container_internal and
into the hook package, where we can reuse it after vendoring into
CRI-O.  It also adds unit tests with almost-complete coverage.  Now
libpod is even more isolated from the hook internals, which makes it
fairly straightforward to bump the hook config file to 1.0.0.  I've
dubbed the old format 0.1.0, although it doesn't specify an explicit
version.  Motivation for some of my changes with 1.0.0:

* Add an explicit version field.  This will make any future JSON
  structure migrations more straightforward by avoiding the need for
  version-guessing heuristics.

* Collect the matching properties in a new When sub-structure.  This
  makes the root Hook structure easier to understand, because you
  don't have to read over all the matching properties when wrapping
  your head around Hook.

* Replace the old 'hook' and 'arguments' with a direct embedding of
  the runtime-spec's hook structure.  This provides access to
  additional upstream properties (args[0], env, and timeout) and
  avoids the complication of a CRI-O-specific analog structure.

* Add a 'when.always' property.  You can usually accomplish this
  effect in another way (e.g. when.commands = [".*"]), but having a
  boolean explicitly for this use-case makes for easier reading and
  writing.

* Replace the previous annotations array with an annotations map.  The
  0.1.0 approach matched only the values regardless of key, and that
  seems unreliable.

* Replace 'cmds' with 'when.commands', because while there are a few
  ways to abbreviate "commands", there's only one way to write it out
  in full ;).  This gives folks one less thing to remember when
  writing hook JSON.

* Replace the old "inject if any specified condition matches" with
  "inject if all specified conditions match".  This allows for more
  precise targeting.  Users that need more generous targeting can
  recover the previous behavior by creating a separate 1.0.0 hook file
  for each specified 0.1.0 condition.

I've added doc-compat support for the various pluralizations of the
0.1.0 properties.  Previously, the docs and code were not in
agreement.  More on this particular facet in [1].

I've updated the docs to point out that the annotations being matched
are the OCI config annotations.  This differs from CRI-O, where the
annotations used are the Kubernetes-supplied annotations [2,3].  For
example, io.kubernetes.cri-o.Volumes [4] is part of CRI-O's runtime
config annotations [5], but not part of the Kubernetes-supplied
annotations CRI-O uses for matching hooks.

The Monitor method supports the CRI-O use-case [6].  podman doesn't
need it directly, but CRI-O will need it when we vendor this package
there.

I've used nvidia-container-runtime-hook for the annotation examples
because Dan mentioned the Nvidia folks as the motivation behind
annotation matching.  The environment variables are documented in [7].
The 0.1.0 hook config, which does not allow for environment variables,
only works because runc currently leaks the host environment into the
hooks [8].  I haven't been able to find documentation for their usual
annotation trigger or hook-install path, so I'm just guessing there.

[1]: https://github.com/kubernetes-incubator/cri-o/pull/1235
[2]: https://github.com/kubernetes-incubator/cri-o/blob/v1.10.0/server/container_create.go#L760
[3]: https://github.com/kubernetes-incubator/cri-o/blob/v1.10.0/server/container_create.go#L772
[4]: https://github.com/kubernetes-incubator/cri-o/blob/v1.10.0/pkg/annotations/annotations.go#L97-L98
[5]: https://github.com/kubernetes-incubator/cri-o/blob/v1.10.0/server/container_create.go#L830-L834
[6]: https://github.com/kubernetes-incubator/cri-o/pull/1345/
[7]: https://github.com/NVIDIA/nvidia-container-runtime/tree/v1.3.0-1#environment-variables-oci-spec
[8]: https://github.com/opencontainers/runc/pull/1738

Signed-off-by: W. Trevor King <wking@tremily.us>

Closes: #686
Approved by: mheon
This commit is contained in:
W. Trevor King 2018-04-27 10:35:32 -07:00 committed by Atomic Bot
parent 9657cd6c15
commit 68eb128fb0
19 changed files with 1828 additions and 261 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
README.md
View File

@ -37,8 +37,8 @@ The plan is to use OCI projects and best of breed libraries for different aspect
**[Installation notes](/install.md)**
Information on how to install Podman in your environment.
**[OCI Hooks Support](/hooks.md)**
Information on how Podman configures OCI Hooks to run when launching a container.
**[OCI Hooks Support](pkg/hooks/README.md)**
Information on how Podman configures [OCI Hooks][spec-hooks] to run when launching a container.
**[Podman Commands](/commands.md)**
A list of the Podman commands with links to their man pages and in many cases videos
@ -64,3 +64,5 @@ Information about contributing to this project.
1. Pod commands for Podman
1. Rootless containers
1. Support for cleaning up containers via post-run hooks
[spec-hooks]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#posix-platform-hooks

3
cmd/podman/main.go
View File

@ -8,6 +8,7 @@ import (
"github.com/containers/storage/pkg/reexec"
"github.com/pkg/errors"
"github.com/projectatomic/libpod/pkg/hooks"
_ "github.com/projectatomic/libpod/pkg/hooks/0.1.0"
"github.com/projectatomic/libpod/version"
"github.com/sirupsen/logrus"
"github.com/urfave/cli"
@ -136,7 +137,7 @@ func main() {
cli.StringFlag{
Name: "hooks-dir-path",
Usage: "set the OCI hooks directory path",
Value: hooks.DefaultHooksDir,
Value: hooks.DefaultDir,
Hidden: true,
},
cli.StringFlag{

91
hooks.md
View File

@ -1,91 +0,0 @@
# OCI Hooks Configuration
[The OCI Runtime Specification defines POSIX-platform Hooks:](
https://github.com/opencontainers/runtime-spec/blob/master/config.md#posix-platform-hooks)
## POSIX-platform Hooks
For POSIX platforms, the configuration structure supports hooks for configuring custom actions related to the life cycle of the container.
hooks (object, OPTIONAL) MAY contain any of the following properties:
* prestart (array of objects, OPTIONAL) is an array of pre-start hooks. Entries in the array contain the following properties:
* path (string, REQUIRED) with similar semantics to [IEEE Std 1003.1-2008 execv's path][ieee-1003.1-2008-functions-exec]. This specification extends the IEEE standard in that path MUST be absolute.
* args (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2008 execv's argv][ieee-1003.1-2008-functions-exec].
* env (array of strings, OPTIONAL) with the same semantics as IEEE Std 1003.1-2008's environ.
* timeout (int, OPTIONAL) is the number of seconds before aborting the hook. If set, timeout MUST be greater than zero.
* poststart (array of objects, OPTIONAL) is an array of post-start hooks. Entries in the array have the same schema as pre-start entries.
* poststop (array of objects, OPTIONAL) is an array of post-stop hooks. Entries in the array have the same schema as pre-start entries.
Hooks allow users to specify programs to run before or after various lifecycle events. Hooks MUST be called in the listed order. The state of the container MUST be passed to hooks over stdin so that they may do work appropriate to the current state of the container.
### Prestart
The Prestart hooks MUST be called after the start operation is called but before the user-specified program command is executed. On Linux, for example, they are called after the container namespaces are created, so they provide an opportunity to customize the container (e.g. the network namespace could be specified in this hook).
### Poststart
The post-start hooks MUST be called after the user-specified process is executed but before the start operation returns. For example, this hook can notify the user that the container process is spawned.
### Poststop
The post-stop hooks MUST be called after the container is deleted but before the delete operation returns. Cleanup or debugging functions are examples of such a hook.
## CRI-O configuration files for automatically enabling Hooks
The way you enable the hooks above is by editing the OCI Specification to add your hook before running the oci runtime, like runc. But this is what `CRI-O` and `podman create` do for you, so we wanted a way for developers to drop configuration files onto the system, so that their hooks would be able to be plugged in.
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](https://github.com/projectatomic/oci-systemd-hook) only executes if the command is `init` or `systemd`, otherwise it just exits. This means if we automatically enable all hooks, every container will have to execute oci-systemd-hook, even if they don't run systemd inside of the container. Also since there are three stages, prestart, poststart, poststop each hook gets executed three times.
### Json Definition
We decided to add a json file for hook builders which allows them to tell CRI-O when to run the hook and in which stage.
CRI-O reads all json files in /usr/share/containers/oci/hooks.d/*.json and /etc/containers/oci/hooks.d and sets up the specified hooks to run. If the same name is in both directories, the one in /etc/containers/oci/hooks.d takes precedence.
The json configuration looks like this in GO
```
// HookParams is the structure returned from read the hooks configuration
type HookParams struct {
Hook string `json:"hook"`
Stage []string `json:"stages"`
Cmds []string `json:"cmds"`
Annotations []string `json:"annotations"`
HasBindMounts bool `json:"hasbindmounts"`
Arguments []string `json:"arguments"`
}
```
| Key | Description | Required/Optional |
| ------ |----------------------------------------------------------------------------------------------------------------------------------- | -------- |
| hook | Path to the hook | Required |
| stages | List of stages to run the hook in: Valid options are `prestart`, `poststart`, `poststop` | Required |
| cmds | List of regular expressions to match the command for running the container. If the command matches a regex, the hook will be run | Optional |
| annotations | List of regular expressions to match against the Annotations in the container runtime spec, if an Annotation matches the hook will be run|optional |
| hasbindmounts | Tells CRI-O to run the hook if the container has bind mounts from the host into the container | Optional |
### Example
```
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" ]
}
```
In the above example CRI-O will only run the oci-systemd-hook in the prestart and poststop stage, if the command ends with /init or /systemd
```
cat /etc/containers/oci/hooks.d/oci-systemd-hook.json
{
"hasbindmounts": true,
"hook": "/usr/libexec/oci/hooks.d/oci-umount",
"stages": [ "prestart" ]
}
```
In this example the oci-umount will only be run during the prestart phase if the container has volume/bind mounts from the host into the container.

58
libpod/container_internal.go
View File

@ -9,7 +9,6 @@ import (
"os"
"path"
"path/filepath"
"regexp"
"strings"
"syscall"
"time"
@ -1064,7 +1063,7 @@ func (c *Container) generateSpec(ctx context.Context) (*spec.Spec, error) {
}
}
if err := c.setupOCIHooks(&g); err != nil {
if err := c.setupOCIHooks(ctx, &g); err != nil {
return nil, errors.Wrapf(err, "error setting up OCI Hooks")
}
// Bind builtin image volumes
@ -1283,58 +1282,15 @@ func (c *Container) saveSpec(spec *spec.Spec) error {
return nil
}
// Add OCI hooks to a container's spec
func (c *Container) setupOCIHooks(g *generate.Generator) error {
addedHooks := map[string]struct{}{}
ocihooks, err := hooks.SetupHooks(c.runtime.config.HooksDir)
if err != nil {
return err
}
addHook := func(hook hooks.HookParams) error {
// Only add a hook once
if _, ok := addedHooks[hook.Hook]; !ok {
if err := hooks.AddOCIHook(g, hook); err != nil {
return err
}
addedHooks[hook.Hook] = struct{}{}
}
func (c *Container) setupOCIHooks(ctx context.Context, g *generate.Generator) error {
if c.runtime.config.HooksDir == "" {
return nil
}
for _, hook := range ocihooks {
logrus.Debugf("SetupOCIHooks", hook)
if hook.HasBindMounts && len(c.config.UserVolumes) > 0 {
if err := addHook(hook); err != nil {
return err
}
continue
}
for _, cmd := range hook.Cmds {
match, err := regexp.MatchString(cmd, c.config.Spec.Process.Args[0])
manager, err := hooks.New(ctx, []string{c.runtime.config.HooksDir})
if err != nil {
logrus.Errorf("Invalid regex %q:%q", cmd, err)
continue
}
if match {
if err := addHook(hook); err != nil {
return err
}
}
}
annotations := c.Spec().Annotations
for _, annotationRegex := range hook.Annotations {
for _, annotation := range annotations {
match, err := regexp.MatchString(annotationRegex, annotation)
if err != nil {
logrus.Errorf("Invalid regex %q:%q", annotationRegex, err)
continue
}
if match {
if err := addHook(hook); err != nil {
return err
}
}
}
}
}
return nil
return manager.Hooks(g.Spec(), c.Spec().Annotations, len(c.config.UserVolumes) > 0)
}

2
libpod/runtime.go
View File

@ -159,7 +159,7 @@ var (
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
},
CgroupManager: CgroupfsCgroupsManager,
HooksDir: hooks.DefaultHooksDir,
HooksDir: hooks.DefaultDir,
StaticDir: filepath.Join(storage.DefaultStoreOptions.GraphRoot, "libpod"),
TmpDir: "/var/run/libpod",
MaxLogSize: -1,

93
pkg/hooks/0.1.0/hook.go Normal file
View File

@ -0,0 +1,93 @@
// Package hook is the 0.1.0 hook configuration structure.
package hook
import (
"encoding/json"
"errors"
"strings"
rspec "github.com/opencontainers/runtime-spec/specs-go"
hooks "github.com/projectatomic/libpod/pkg/hooks"
current "github.com/projectatomic/libpod/pkg/hooks/1.0.0"
)
// Version is the hook configuration version defined in this package.
const Version = "0.1.0"
// Hook is the hook configuration structure.
type Hook struct {
Hook *string `json:"hook"`
Arguments []string `json:"arguments,omitempty"`
// https://github.com/kubernetes-incubator/cri-o/pull/1235
Stages []string `json:"stages"`
Stage []string `json:"stage"`
Cmds []string `json:"cmds,omitempty"`
Cmd []string `json:"cmd,omitempty"`
Annotations []string `json:"annotations,omitempty"`
Annotation []string `json:"annotation,omitempty"`
HasBindMounts *bool `json:"hasbindmounts,omitempty"`
}
func read(content []byte) (hook *current.Hook, err error) {
var raw Hook
if err = json.Unmarshal(content, &raw); err != nil {
return nil, err
}
if raw.Hook == nil {
return nil, errors.New("missing required property: hook")
}
if raw.Stages == nil {
raw.Stages = raw.Stage
} else if raw.Stage != nil {
return nil, errors.New("cannot set both 'stage' and 'stages'")
}
if raw.Stages == nil {
return nil, errors.New("missing required property: stages")
}
if raw.Cmds == nil {
raw.Cmds = raw.Cmd
} else if raw.Cmd != nil {
return nil, errors.New("cannot set both 'cmd' and 'cmds'")
}
if raw.Annotations == nil {
raw.Annotations = raw.Annotation
} else if raw.Annotation != nil {
return nil, errors.New("cannot set both 'annotation' and 'annotations'")
}
hook = &current.Hook{
Version: current.Version,
Hook: rspec.Hook{
Path: *raw.Hook,
},
When: current.When{
Commands: raw.Cmds,
HasBindMounts: raw.HasBindMounts,
Or: true,
},
Stages: raw.Stages,
}
if raw.Arguments != nil {
hook.Hook.Args = append([]string{*raw.Hook}, raw.Arguments...)
}
if raw.Annotations != nil {
hook.When.Annotations = map[string]string{
".*": strings.Join(raw.Annotations, "|"),
}
}
return hook, nil
}
func init() {
hooks.Readers[""] = read
hooks.Readers[Version] = read
}

182
pkg/hooks/0.1.0/hook_test.go Normal file
View File

@ -0,0 +1,182 @@
package hook
import (
"testing"
rspec "github.com/opencontainers/runtime-spec/specs-go"
current "github.com/projectatomic/libpod/pkg/hooks/1.0.0"
"github.com/stretchr/testify/assert"
)
func TestGood(t *testing.T) {
hook, err := read([]byte("{\"hook\": \"/a/b/c\", \"stages\": [\"prestart\"], \"cmds\": [\"sh\"]}"))
if err != nil {
t.Fatal(err)
}
assert.Equal(t, &current.Hook{
Version: current.Version,
Hook: rspec.Hook{
Path: "/a/b/c",
},
When: current.When{
Commands: []string{"sh"},
Or: true,
},
Stages: []string{"prestart"},
}, hook)
}
func TestInvalidJSON(t *testing.T) {
_, err := read([]byte("{"))
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^unexpected end of JSON input$", err.Error())
}
func TestArguments(t *testing.T) {
hook, err := read([]byte("{\"hook\": \"/a/b/c\", \"arguments\": [\"d\", \"e\"], \"stages\": [\"prestart\"], \"cmds\": [\"sh\"]}"))
if err != nil {
t.Fatal(err)
}
assert.Equal(t, &current.Hook{
Version: current.Version,
Hook: rspec.Hook{
Path: "/a/b/c",
Args: []string{"/a/b/c", "d", "e"},
},
When: current.When{
Commands: []string{"sh"},
Or: true,
},
Stages: []string{"prestart"},
}, hook)
}
func TestEmptyObject(t *testing.T) {
_, err := read([]byte("{}"))
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^missing required property: hook$", err.Error())
}
func TestNoStages(t *testing.T) {
_, err := read([]byte("{\"hook\": \"/a/b/c\"}"))
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^missing required property: stages$", err.Error())
}
func TestStage(t *testing.T) {
hook, err := read([]byte("{\"hook\": \"/a/b/c\", \"stage\": [\"prestart\"]}"))
if err != nil {
t.Fatal(err)
}
assert.Equal(t, &current.Hook{
Version: current.Version,
Hook: rspec.Hook{
Path: "/a/b/c",
},
When: current.When{Or: true},
Stages: []string{"prestart"},
}, hook)
}
func TestStagesAndStage(t *testing.T) {
_, err := read([]byte("{\"hook\": \"/a/b/c\", \"stages\": [\"prestart\"], \"stage\": [\"prestart\"]}"))
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^cannot set both 'stage' and 'stages'$", err.Error())
}
func TestCmd(t *testing.T) {
hook, err := read([]byte("{\"hook\": \"/a/b/c\", \"stage\": [\"prestart\"], \"cmd\": [\"sh\"]}"))
if err != nil {
t.Fatal(err)
}
assert.Equal(t, &current.Hook{
Version: current.Version,
Hook: rspec.Hook{
Path: "/a/b/c",
},
When: current.When{
Commands: []string{"sh"},
Or: true,
},
Stages: []string{"prestart"},
}, hook)
}
func TestCmdsAndCmd(t *testing.T) {
_, err := read([]byte("{\"hook\": \"/a/b/c\", \"stages\": [\"prestart\"], \"cmds\": [\"sh\"], \"cmd\": [\"true\"]}"))
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^cannot set both 'cmd' and 'cmds'$", err.Error())
}
func TestAnnotations(t *testing.T) {
hook, err := read([]byte("{\"hook\": \"/a/b/c\", \"stage\": [\"prestart\"], \"annotations\": [\"a\", \"b\"]}"))
if err != nil {
t.Fatal(err)
}
assert.Equal(t, &current.Hook{
Version: current.Version,
Hook: rspec.Hook{
Path: "/a/b/c",
},
When: current.When{
Annotations: map[string]string{".*": "a|b"},
Or: true,
},
Stages: []string{"prestart"},
}, hook)
}
func TestAnnotation(t *testing.T) {
hook, err := read([]byte("{\"hook\": \"/a/b/c\", \"stage\": [\"prestart\"], \"annotation\": [\"a\", \"b\"]}"))
if err != nil {
t.Fatal(err)
}
assert.Equal(t, &current.Hook{
Version: current.Version,
Hook: rspec.Hook{
Path: "/a/b/c",
},
When: current.When{
Annotations: map[string]string{".*": "a|b"},
Or: true,
},
Stages: []string{"prestart"},
}, hook)
}
func TestAnnotationsAndAnnotation(t *testing.T) {
_, err := read([]byte("{\"hook\": \"/a/b/c\", \"stages\": [\"prestart\"], \"annotations\": [\"a\"], \"annotation\": [\"b\"]}"))
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^cannot set both 'annotation' and 'annotations'$", err.Error())
}
func TestHasBindMounts(t *testing.T) {
hook, err := read([]byte("{\"hook\": \"/a/b/c\", \"stage\": [\"prestart\"], \"hasbindmounts\": true}"))
if err != nil {
t.Fatal(err)
}
hasBindMounts := true
assert.Equal(t, &current.Hook{
Version: current.Version,
Hook: rspec.Hook{
Path: "/a/b/c",
},
When: current.When{
HasBindMounts: &hasBindMounts,
Or: true,
},
Stages: []string{"prestart"},
}, hook)
}

78
pkg/hooks/1.0.0/hook.go Normal file
View File

@ -0,0 +1,78 @@
// Package hook is the 1.0.0 hook configuration structure.
package hook
import (
"encoding/json"
"fmt"
"os"
"regexp"
rspec "github.com/opencontainers/runtime-spec/specs-go"
"github.com/pkg/errors"
)
// Version is the hook configuration version defined in this package.
const Version = "1.0.0"
// Hook is the hook configuration structure.
type Hook struct {
Version string `json:"version"`
Hook rspec.Hook `json:"hook"`
When When `json:"when"`
Stages []string `json:"stages"`
}
// Read reads hook JSON bytes, verifies them, and returns the hook configuration.
func Read(content []byte) (hook *Hook, err error) {
if err = json.Unmarshal(content, &hook); err != nil {
return nil, err
}
return hook, nil
}
// Validate performs load-time hook validation.
func (hook *Hook) Validate() (err error) {
if hook == nil {
return errors.New("nil hook")
}
if hook.Version != Version {
return fmt.Errorf("unexpected hook version %q (expecting %v)", hook.Version, Version)
}
if hook.Hook.Path == "" {
return errors.New("missing required property: hook.path")
}
if _, err := os.Stat(hook.Hook.Path); err != nil {
return err
}
for key, value := range hook.When.Annotations {
if _, err = regexp.Compile(key); err != nil {
return errors.Wrapf(err, "invalid annotation key %q", key)
}
if _, err = regexp.Compile(value); err != nil {
return errors.Wrapf(err, "invalid annotation value %q", value)
}
}
for _, command := range hook.When.Commands {
if _, err = regexp.Compile(command); err != nil {
return errors.Wrapf(err, "invalid command %q", command)
}
}
if hook.Stages == nil {
return errors.New("missing required property: stages")
}
validStages := map[string]bool{"prestart": true, "poststart": true, "poststop": true}
for _, stage := range hook.Stages {
if !validStages[stage] {
return fmt.Errorf("unknown stage %q", stage)
}
}
return nil
}

200
pkg/hooks/1.0.0/hook_test.go Normal file
View File

@ -0,0 +1,200 @@
package hook
import (
"os"
"path/filepath"
"runtime"
"testing"
rspec "github.com/opencontainers/runtime-spec/specs-go"
"github.com/stretchr/testify/assert"
)
// path is the path to an example hook executable.
var path string
func TestGoodRead(t *testing.T) {
hook, err := Read([]byte("{\"version\": \"1.0.0\", \"hook\": {\"path\": \"/a/b/c\"}, \"when\": {\"always\": true}, \"stages\": [\"prestart\"]}"))
if err != nil {
t.Fatal(err)
}
always := true
assert.Equal(t, &Hook{
Version: Version,
Hook: rspec.Hook{
Path: "/a/b/c",
},
When: When{
Always: &always,
},
Stages: []string{"prestart"},
}, hook)
}
func TestInvalidJSON(t *testing.T) {
_, err := Read([]byte("{"))
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^unexpected end of JSON input$", err.Error())
}
func TestGoodValidate(t *testing.T) {
always := true
hook := &Hook{
Version: Version,
Hook: rspec.Hook{
Path: path,
},
When: When{
Always: &always,
},
Stages: []string{"prestart"},
}
err := hook.Validate()
if err != nil {
t.Fatal(err)
}
}
func TestNilValidation(t *testing.T) {
var hook *Hook
err := hook.Validate()
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^nil hook$", err.Error())
}
func TestWrongVersion(t *testing.T) {
hook := Hook{Version: "0.1.0"}
err := hook.Validate()
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^unexpected hook version \"0.1.0\" \\(expecting 1.0.0\\)$", err.Error())
}
func TestNoHookPath(t *testing.T) {
hook := Hook{
Version: "1.0.0",
Hook: rspec.Hook{},
}
err := hook.Validate()
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^missing required property: hook.path$", err.Error())
}
func TestUnknownHookPath(t *testing.T) {
hook := Hook{
Version: "1.0.0",
Hook: rspec.Hook{
Path: filepath.Join("does", "not", "exist"),
},
}
err := hook.Validate()
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^stat does/not/exist: no such file or directory$", err.Error())
if !os.IsNotExist(err) {
t.Fatal("opaque wrapping for not-exist errors")
}
}
func TestNoStages(t *testing.T) {
hook := Hook{
Version: "1.0.0",
Hook: rspec.Hook{
Path: path,
},
}
err := hook.Validate()
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^missing required property: stages$", err.Error())
}
func TestInvalidStage(t *testing.T) {
hook := Hook{
Version: "1.0.0",
Hook: rspec.Hook{
Path: path,
},
Stages: []string{"does-not-exist"},
}
err := hook.Validate()
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^unknown stage \"does-not-exist\"$", err.Error())
}
func TestInvalidAnnotationKey(t *testing.T) {
hook := Hook{
Version: "1.0.0",
Hook: rspec.Hook{
Path: path,
},
When: When{
Annotations: map[string]string{
"[": "a",
},
},
Stages: []string{"prestart"},
}
err := hook.Validate()
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^invalid annotation key \"\\[\": error parsing regexp: .*", err.Error())
}
func TestInvalidAnnotationValue(t *testing.T) {
hook := Hook{
Version: "1.0.0",
Hook: rspec.Hook{
Path: path,
},
When: When{
Annotations: map[string]string{
"a": "[",
},
},
Stages: []string{"prestart"},
}
err := hook.Validate()
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^invalid annotation value \"\\[\": error parsing regexp: .*", err.Error())
}
func TestInvalidCommand(t *testing.T) {
hook := Hook{
Version: "1.0.0",
Hook: rspec.Hook{
Path: path,
},
When: When{
Commands: []string{"["},
},
Stages: []string{"prestart"},
}
err := hook.Validate()
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^invalid command \"\\[\": error parsing regexp: .*", err.Error())
}
func init() {
if runtime.GOOS != "windows" {
path = "/bin/sh"
} else {
panic("we need a reliable executable path on Windows")
}
}

92
pkg/hooks/1.0.0/when.go Normal file
View File

@ -0,0 +1,92 @@
package hook
import (
"regexp"
rspec "github.com/opencontainers/runtime-spec/specs-go"
"github.com/pkg/errors"
)
// When holds hook-injection conditions.
type When struct {
Always *bool `json:"always,omitempty"`
Annotations map[string]string `json:"annotation,omitempty"`
Commands []string `json:"commands,omitempty"`
HasBindMounts *bool `json:"hasBindMounts,omitempty"`
// Or enables any-of matching.
//
// Deprecated: this property is for is backwards-compatibility with
// 0.1.0 hooks. It will be removed when we drop support for them.
Or bool `json:"-"`
}
// Match returns true if the given conditions match the configuration.
func (when *When) Match(config *rspec.Spec, annotations map[string]string, hasBindMounts bool) (match bool, err error) {
matches := 0
if when.Always != nil {
if *when.Always {
if when.Or {
return true, nil
}
matches++
} else if !when.Or {
return false, nil
}
}
if when.HasBindMounts != nil {
if *when.HasBindMounts && hasBindMounts {
if when.Or {
return true, nil
}
matches++
} else if !when.Or {
return false, nil
}
}
for keyPattern, valuePattern := range when.Annotations {
match := false
for key, value := range annotations {
match, err = regexp.MatchString(keyPattern, key)
if err != nil {
return false, errors.Wrap(err, "annotation key")
}
if match {
match, err = regexp.MatchString(valuePattern, value)
if err != nil {
return false, errors.Wrap(err, "annotation value")
}
if match {
break
}
}
}
if match {
if when.Or {
return true, nil
}
matches++
} else if !when.Or {
return false, nil
}
}
if config.Process != nil {
command := config.Process.Args[0]
for _, cmdPattern := range when.Commands {
match, err := regexp.MatchString(cmdPattern, command)
if err != nil {
return false, errors.Wrap(err, "command")
}
if match {
return true, nil
}
}
return false, nil
}
return matches > 0, nil
}

289
pkg/hooks/1.0.0/when_test.go Normal file
View File

@ -0,0 +1,289 @@
package hook
import (
"fmt"
"testing"
rspec "github.com/opencontainers/runtime-spec/specs-go"
"github.com/stretchr/testify/assert"
)
func TestNoMatch(t *testing.T) {
config := &rspec.Spec{}
for _, or := range []bool{true, false} {
t.Run(fmt.Sprintf("or %t", or), func(t *testing.T) {
when := When{Or: or}
match, err := when.Match(config, map[string]string{}, false)
if err != nil {
t.Fatal(err)
}
assert.Equal(t, false, match)
})
}
}
func TestAlways(t *testing.T) {
config := &rspec.Spec{}
for _, always := range []bool{true, false} {
for _, or := range []bool{true, false} {
t.Run(fmt.Sprintf("always %t, or %t", always, or), func(t *testing.T) {
when := When{Always: &always, Or: or}
match, err := when.Match(config, map[string]string{}, false)
if err != nil {
t.Fatal(err)
}
assert.Equal(t, always, match)
})
}
}
}
func TestHasBindMountsAnd(t *testing.T) {
hasBindMounts := true
when := When{HasBindMounts: &hasBindMounts}
config := &rspec.Spec{}
for _, containerHasBindMounts := range []bool{false, true} {
t.Run(fmt.Sprintf("%t", containerHasBindMounts), func(t *testing.T) {
match, err := when.Match(config, map[string]string{}, containerHasBindMounts)
if err != nil {
t.Fatal(err)
}
assert.Equal(t, containerHasBindMounts, match)
})
}
}
func TestHasBindMountsOr(t *testing.T) {
hasBindMounts := true
when := When{HasBindMounts: &hasBindMounts, Or: true}
config := &rspec.Spec{}
for _, containerHasBindMounts := range []bool{false, true} {
t.Run(fmt.Sprintf("%t", containerHasBindMounts), func(t *testing.T) {
match, err := when.Match(config, map[string]string{}, containerHasBindMounts)
if err != nil {
t.Fatal(err)
}
assert.Equal(t, containerHasBindMounts, match)
})
}
}
func TestAnnotations(t *testing.T) {
when := When{
Annotations: map[string]string{
"^a$": "^b$",
"^c$": "^d$",
},
}
config := &rspec.Spec{}
for _, test := range []struct {
name string
annotations map[string]string
or bool
match bool
}{
{
name: "matching both, and",
annotations: map[string]string{
"a": "b",
"c": "d",
"e": "f",
},
or: false,
match: true,
},
{
name: "matching one, and",
annotations: map[string]string{
"a": "b",
},
or: false,
match: false,
},
{
name: "matching one, or",
annotations: map[string]string{
"a": "b",
},
or: true,
match: true,
},
{
name: "key-only, or",
annotations: map[string]string{
"a": "bc",
},
or: true,
match: false,
},
{
name: "value-only, or",
annotations: map[string]string{
"ac": "b",
},
or: true,
match: false,
},
} {
t.Run(test.name, func(t *testing.T) {
when.Or = test.or
match, err := when.Match(config, test.annotations, false)
if err != nil {
t.Fatal(err)
}
assert.Equal(t, test.match, match)
})
}
}
func TestCommands(t *testing.T) {
when := When{
Commands: []string{
"^/bin/sh$",
},
}
config := &rspec.Spec{Process: &rspec.Process{}}
for _, test := range []struct {
name string
args []string
match bool
}{
{
name: "good",
args: []string{"/bin/sh", "a", "b"},
match: true,
},
{
name: "extra characters",
args: []string{"/bin/shell", "a", "b"},
match: false,
},
} {
t.Run(test.name, func(t *testing.T) {
config.Process.Args = test.args
match, err := when.Match(config, map[string]string{}, false)
if err != nil {
t.Fatal(err)
}
assert.Equal(t, test.match, match)
})
}
}
func TestHasBindMountsAndCommands(t *testing.T) {
hasBindMounts := true
when := When{
HasBindMounts: &hasBindMounts,
Commands: []string{
"^/bin/sh$",
},
}
config := &rspec.Spec{Process: &rspec.Process{}}
for _, test := range []struct {
name string
command string
hasBindMounts bool
or bool
match bool
}{
{
name: "both, and",
command: "/bin/sh",
hasBindMounts: true,
or: false,
match: true,
},
{
name: "both, and",
command: "/bin/sh",
hasBindMounts: true,
or: true,
match: true,
},
{
name: "bind, and",
command: "/bin/shell",
hasBindMounts: true,
or: false,
match: false,
},
{
name: "bind, or",
command: "/bin/shell",
hasBindMounts: true,
or: true,
match: true,
},
{
name: "command, and",
command: "/bin/sh",
hasBindMounts: false,
or: false,
match: false,
},
{
name: "command, or",
command: "/bin/sh",
hasBindMounts: false,
or: true,
match: true,
},
{
name: "neither, and",
command: "/bin/shell",
hasBindMounts: false,
or: false,
match: false,
},
{
name: "neither, or",
command: "/bin/shell",
hasBindMounts: false,
or: true,
match: false,
},
} {
t.Run(test.name, func(t *testing.T) {
config.Process.Args = []string{test.command}
when.Or = test.or
match, err := when.Match(config, map[string]string{}, test.hasBindMounts)
if err != nil {
t.Fatal(err)
}
assert.Equal(t, test.match, match)
})
}
}
func TestInvalidRegexp(t *testing.T) {
config := &rspec.Spec{Process: &rspec.Process{Args: []string{"/bin/sh"}}}
for _, test := range []struct {
name string
when When
expected string
}{
{
name: "invalid-annotation-key",
when: When{Annotations: map[string]string{"[": "a"}},
expected: "^annotation key: error parsing regexp: .*",
},
{
name: "invalid-annotation-value",
when: When{Annotations: map[string]string{"a": "["}},
expected: "^annotation value: error parsing regexp: .*",
},
{
name: "invalid-command",
when: When{Commands: []string{"["}},
expected: "^command: error parsing regexp: .*",
},
} {
t.Run(test.name, func(t *testing.T) {
_, err := test.when.Match(config, map[string]string{"a": "b"}, false)
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, test.expected, err.Error())
})
}
}

175
pkg/hooks/README.md Normal file
View File

@ -0,0 +1,175 @@
# OCI Hooks Configuration
For POSIX platforms, the [OCI runtime configuration][runtime-spec] supports [hooks][spec-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`][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][rfc2119].
## 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.
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][spec-hooks] 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][spec-annotations], this condition matches.
Both keys and values MUST be [POSIX extended regular expressions][POSIX-ERE].
* **`commands`** (OPTIONAL, array of strings) If the configured [`process.args[0]`][spec-process] matches an entry, this condition matches.
Entries MUST be [POSIX extended regular expressions][POSIX-ERE].
* **`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][spec-hooks].
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`][oci-systemd-hook] in the [pre-start][] and [post-stop][] stages if [`process.args[0]`][spec-process] ends with `/init` or `/systemd`:
```console
$ 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`][oci-umount] in the [pre-start][] phase if the container is configured to bind-mount host directories into the container.
```console
$ 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`][nvidia-container-runtime-hook] 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.*`.
```console
$ 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`][spec-hooks] in the injected hook.
* **`arguments`** (OPTIONAL, array of strings) Additional arguments to pass to the hook.
The injected hook's [`args`][spec-hooks] 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]`][spec-process] 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][POSIX-ERE].
* **`annotations`** (OPTIONAL, array of strings) The hook MUST be injected if an `annotations` entry matches a value from the [configured annotations][spec-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][POSIX-ERE].
* **`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`][oci-systemd-hook] in the [pre-start][] and [post-stop][] stages if [`process.args[0]`][spec-process] ends with `/init` or `/systemd`:
```console
$ 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`][oci-umount] in the [pre-start][] phase if the container is configured to bind-mount host directories into the container.
```console
$ 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`][nvidia-container-runtime-hook] in the [pre-start][] phase if the container is configured with an `annotations` entry whose value matches `.*fluid-dynamics.*`.
```console
$ cat /etc/containers/oci/hooks.d/osystemd-hook.json
{
"hook": "/usr/sbin/nvidia-container-runtime-hook",
"arguments": ["prestart"],
"annotations: [".*fluid-dynamics.*"],
"stages": ["prestart"]
}
```
[JSON]: https://tools.ietf.org/html/rfc8259
[nvidia-container-runtime-hook]: https://github.com/NVIDIA/nvidia-container-runtime/tree/master/hook/nvidia-container-runtime-hook
[oci-systemd-hook]: https://github.com/projectatomic/oci-systemd-hook
[oci-umount]: https://github.com/projectatomic/oci-umount
[POSIX-ERE]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04
[post-start]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#poststart
[post-stop]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#poststop
[pre-start]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#prestart
[rfc2119]: http://tools.ietf.org/html/rfc2119
[runc]: https://github.com/opencontainers/runc
[runtime-spec]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/spec.md
[spec-annotations]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#annotations
[spec-hooks]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#posix-platform-hooks
[spec-process]: https://github.com/opencontainers/runtime-spec/blob/v1.0.1/config.md#process

185
pkg/hooks/hooks.go
View File

@ -1,141 +1,104 @@
// Package hooks implements CRI-O's hook handling.
package hooks
import (
"encoding/json"
"context"
"fmt"
"io/ioutil"
"os"
"path/filepath"
"regexp"
"strings"
"syscall"
"sync"
spec "github.com/opencontainers/runtime-spec/specs-go"
"github.com/opencontainers/runtime-tools/generate"
rspec "github.com/opencontainers/runtime-spec/specs-go"
"github.com/pkg/errors"
"github.com/sirupsen/logrus"
current "github.com/projectatomic/libpod/pkg/hooks/1.0.0"
)
// Version is the current hook configuration version.
const Version = current.Version
const (
// DefaultHooksDir Default directory containing hooks config files
DefaultHooksDir = "/usr/share/containers/oci/hooks.d"
// OverrideHooksDir Directory where admin can override the default configuration
OverrideHooksDir = "/etc/containers/oci/hooks.d"
// 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"
)
// HookParams is the structure returned from read the hooks configuration
type HookParams struct {
Hook string `json:"hook"`
Stage []string `json:"stage"`
Cmds []string `json:"cmd"`
Annotations []string `json:"annotation"`
HasBindMounts bool `json:"hasbindmounts"`
Arguments []string `json:"arguments"`
// Manager provides an opaque interface for managing CRI-O hooks.
type Manager struct {
hooks map[string]*current.Hook
directories []string
lock sync.Mutex
}
// readHook reads hooks json files, verifies it and returns the json config
func readHook(hookPath string) (HookParams, error) {
var hook HookParams
raw, err := ioutil.ReadFile(hookPath)
// 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 New(ctx context.Context, directories []string) (manager *Manager, err error) {
manager = &Manager{
hooks: map[string]*current.Hook{},
directories: directories,
}
for _, dir := range directories {
err = ReadDir(dir, manager.hooks)
if err != nil {
return hook, errors.Wrapf(err, "error Reading hook %q", hookPath)
}
if err := json.Unmarshal(raw, &hook); err != nil {
return hook, errors.Wrapf(err, "error Unmarshalling JSON for %q", hookPath)
}
if _, err := os.Stat(hook.Hook); err != nil {
return hook, errors.Wrapf(err, "unable to stat hook %q in hook config %q", hook.Hook, hookPath)
}
validStage := map[string]bool{"prestart": true, "poststart": true, "poststop": true}
for _, cmd := range hook.Cmds {
if _, err = regexp.Compile(cmd); err != nil {
return hook, errors.Wrapf(err, "invalid cmd regular expression %q defined in hook config %q", cmd, hookPath)
}
}
for _, cmd := range hook.Annotations {
if _, err = regexp.Compile(cmd); err != nil {
return hook, errors.Wrapf(err, "invalid cmd regular expression %q defined in hook config %q", cmd, hookPath)
}
}
for _, stage := range hook.Stage {
if !validStage[stage] {
return hook, errors.Wrapf(err, "unknown stage %q defined in hook config %q", stage, hookPath)
}
}
return hook, nil
}
// readHooks reads hooks json files in directory to setup OCI Hooks
// adding hooks to the passedin hooks map.
func readHooks(hooksPath string, hooks map[string]HookParams) error {
if _, err := os.Stat(hooksPath); err != nil {
if os.IsNotExist(err) {
logrus.Warnf("hooks path: %q does not exist", hooksPath)
return nil
}
return errors.Wrapf(err, "unable to stat hooks path %q", hooksPath)
}
files, err := ioutil.ReadDir(hooksPath)
if err != nil {
return err
}
for _, file := range files {
if !strings.HasSuffix(file.Name(), ".json") {
continue
}
hook, err := readHook(filepath.Join(hooksPath, file.Name()))
if err != nil {
return err
}
for key, h := range hooks {
// hook.Hook can only be defined in one hook file, unless it has the
// same name in the override path.
if hook.Hook == h.Hook && key != file.Name() {
return errors.Wrapf(syscall.EINVAL, "duplicate path, hook %q from %q already defined in %q", hook.Hook, hooksPath, key)
}
}
hooks[file.Name()] = hook
}
return nil
}
// SetupHooks takes a hookspath and reads all of the hooks in that directory.
// returning a map of the configured hooks
func SetupHooks(hooksPath string) (map[string]HookParams, error) {
hooksMap := make(map[string]HookParams)
if err := readHooks(hooksPath, hooksMap); err != nil {
return nil, err
}
if hooksPath == DefaultHooksDir {
if err := readHooks(OverrideHooksDir, hooksMap); err != nil {
return nil, err
}
}
return hooksMap, nil
return manager, nil
}
// AddOCIHook generates OCI specification using the included hook
func AddOCIHook(g *generate.Generator, hook HookParams) error {
for _, stage := range hook.Stage {
h := spec.Hook{
Path: hook.Hook,
Args: append([]string{hook.Hook}, hook.Arguments...),
Env: []string{fmt.Sprintf("stage=%s", stage)},
// Hooks injects OCI runtime hooks for a given container configuration.
func (m *Manager) Hooks(config *rspec.Spec, annotations map[string]string, hasBindMounts bool) (err error) {
m.lock.Lock()
defer m.lock.Unlock()
for name, hook := range m.hooks {
match, err := hook.When.Match(config, annotations, hasBindMounts)
if err != nil {
return errors.Wrapf(err, "matching hook %q", name)
}
logrus.Debugf("AddOCIHook", h)
if match {
if config.Hooks == nil {
config.Hooks = &rspec.Hooks{}
}
for _, stage := range hook.Stages {
switch stage {
case "prestart":
g.AddPreStartHook(h)
config.Hooks.Prestart = append(config.Hooks.Prestart, hook.Hook)
case "poststart":
g.AddPostStartHook(h)
config.Hooks.Poststart = append(config.Hooks.Poststart, hook.Hook)
case "poststop":
g.AddPostStopHook(h)
config.Hooks.Poststop = append(config.Hooks.Poststop, hook.Hook)
default:
return fmt.Errorf("hook %q: unknown stage %q", name, stage)
}
}
}
}
return nil
}
// remove remove a hook by name.
func (m *Manager) remove(hook string) (ok bool) {
m.lock.Lock()
defer m.lock.Unlock()
_, ok = m.hooks[hook]
if ok {
delete(m.hooks, hook)
}
return ok
}
// add adds a hook by path
func (m *Manager) add(path string) (err error) {
m.lock.Lock()
defer m.lock.Unlock()
hook, err := Read(path)
if err != nil {
return err
}
m.hooks[filepath.Base(path)] = hook
return nil
}

143
pkg/hooks/hooks_test.go Normal file
View File

@ -0,0 +1,143 @@
package hooks
import (
"context"
"fmt"
"io/ioutil"
"os"
"path/filepath"
"runtime"
"testing"
rspec "github.com/opencontainers/runtime-spec/specs-go"
current "github.com/projectatomic/libpod/pkg/hooks/1.0.0"
"github.com/stretchr/testify/assert"
)
// path is the path to an example hook executable.
var path string
func TestGoodNew(t *testing.T) {
ctx := context.Background()
dir, err := ioutil.TempDir("", "hooks-test-")
if err != nil {
t.Fatal(err)
}
defer os.RemoveAll(dir)
jsonPath := filepath.Join(dir, "a.json")
err = ioutil.WriteFile(jsonPath, []byte(fmt.Sprintf("{\"version\": \"1.0.0\", \"hook\": {\"path\": \"%s\"}, \"when\": {\"always\": true}, \"stages\": [\"prestart\", \"poststart\", \"poststop\"]}", path)), 0644)
if err != nil {
t.Fatal(err)
}
manager, err := New(ctx, []string{dir})
if err != nil {
t.Fatal(err)
}
config := &rspec.Spec{}
err = manager.Hooks(config, map[string]string{}, false)
if err != nil {
t.Fatal(err)
}
assert.Equal(t, &rspec.Hooks{
Prestart: []rspec.Hook{
{
Path: path,
},
},
Poststart: []rspec.Hook{
{
Path: path,
},
},
Poststop: []rspec.Hook{
{
Path: path,
},
},
}, config.Hooks)
}
func TestBadNew(t *testing.T) {
ctx := context.Background()
dir, err := ioutil.TempDir("", "hooks-test-")
if err != nil {
t.Fatal(err)
}
defer os.RemoveAll(dir)
jsonPath := filepath.Join(dir, "a.json")
err = ioutil.WriteFile(jsonPath, []byte("{\"version\": \"-1\"}"), 0644)
if err != nil {
t.Fatal(err)
}
_, err = New(ctx, []string{dir})
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^parsing hook \"[^\"]*a.json\": unrecognized hook version: \"-1\"$", err.Error())
}
func TestBrokenMatch(t *testing.T) {
manager := Manager{
hooks: map[string]*current.Hook{
"a.json": {
Version: current.Version,
Hook: rspec.Hook{
Path: "/a/b/c",
},
When: current.When{
Commands: []string{"["},
},
Stages: []string{"prestart"},
},
},
}
config := &rspec.Spec{
Process: &rspec.Process{
Args: []string{"/bin/sh"},
},
}
err := manager.Hooks(config, map[string]string{}, false)
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^matching hook \"a\\.json\": command: error parsing regexp: .*", err.Error())
}
func TestInvalidStage(t *testing.T) {
always := true
manager := Manager{
hooks: map[string]*current.Hook{
"a.json": {
Version: current.Version,
Hook: rspec.Hook{
Path: "/a/b/c",
},
When: current.When{
Always: &always,
},
Stages: []string{"does-not-exist"},
},
},
}
err := manager.Hooks(&rspec.Spec{}, map[string]string{}, false)
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^hook \"a\\.json\": unknown stage \"does-not-exist\"$", err.Error())
}
func init() {
if runtime.GOOS != "windows" {
path = "/bin/sh"
} else {
panic("we need a reliable executable path on Windows")
}
}

73
pkg/hooks/monitor.go Normal file
View File

@ -0,0 +1,73 @@
package hooks
import (
"context"
"path/filepath"
"github.com/fsnotify/fsnotify"
"github.com/sirupsen/logrus"
)
// 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
func (m *Manager) Monitor(ctx context.Context, sync chan<- error) {
watcher, err := fsnotify.NewWatcher()
if err != nil {
sync <- err
return
}
defer watcher.Close()
for _, dir := range m.directories {
err = watcher.Add(dir)
if err != nil {
logrus.Errorf("failed to watch %q for hooks", dir)
sync <- err
return
}
logrus.Debugf("monitoring %q for hooks", dir)
}
sync <- nil
for {
select {
case event := <-watcher.Events:
if event.Op&fsnotify.Remove == fsnotify.Remove {
ok := m.remove(filepath.Base(event.Name))
if ok {
logrus.Debugf("removed hook %s", event.Name)
}
}
if event.Op&fsnotify.Create == fsnotify.Create || event.Op&fsnotify.Write == fsnotify.Write {
err = m.add(event.Name)
if err == nil {
logrus.Debugf("added hook %s", event.Name)
} else if err != ErrNoJSONSuffix {
logrus.Errorf("failed to add hook %s: %v", event.Name, err)
}
}
case <-ctx.Done():
err = ctx.Err()
logrus.Debugf("hook monitoring canceled: %v", err)
sync <- err
close(sync)
return
}
}
}

129
pkg/hooks/monitor_test.go Normal file
View File

@ -0,0 +1,129 @@
package hooks
import (
"context"
"fmt"
"io/ioutil"
"os"
"path/filepath"
"testing"
"time"
rspec "github.com/opencontainers/runtime-spec/specs-go"
"github.com/stretchr/testify/assert"
)
func TestMonitorGood(t *testing.T) {
ctx, cancel := context.WithCancel(context.Background())
dir, err := ioutil.TempDir("", "hooks-test-")
if err != nil {
t.Fatal(err)
}
defer os.RemoveAll(dir)
manager, err := New(ctx, []string{dir})
if err != nil {
t.Fatal(err)
}
sync := make(chan error, 2)
go manager.Monitor(ctx, sync)
err = <-sync
if err != nil {
t.Fatal(err)
}
jsonPath := filepath.Join(dir, "a.json")
t.Run("good-addition", func(t *testing.T) {
err = ioutil.WriteFile(jsonPath, []byte(fmt.Sprintf("{\"version\": \"1.0.0\", \"hook\": {\"path\": \"%s\"}, \"when\": {\"always\": true}, \"stages\": [\"prestart\", \"poststart\", \"poststop\"]}", path)), 0644)
if err != nil {
t.Fatal(err)
}
time.Sleep(100 * time.Millisecond) // wait for monitor to notice
config := &rspec.Spec{}
err = manager.Hooks(config, map[string]string{}, false)
if err != nil {
t.Fatal(err)
}
assert.Equal(t, &rspec.Hooks{
Prestart: []rspec.Hook{
{
Path: path,
},
},
Poststart: []rspec.Hook{
{
Path: path,
},
},
Poststop: []rspec.Hook{
{
Path: path,
},
},
}, config.Hooks)
})
t.Run("good-removal", func(t *testing.T) {
err = os.Remove(jsonPath)
if err != nil {
t.Fatal(err)
}
time.Sleep(100 * time.Millisecond) // wait for monitor to notice
config := &rspec.Spec{}
expected := config.Hooks
err = manager.Hooks(config, map[string]string{}, false)
if err != nil {
t.Fatal(err)
}
assert.Equal(t, expected, config.Hooks)
})
t.Run("bad-addition", func(t *testing.T) {
err = ioutil.WriteFile(jsonPath, []byte("{\"version\": \"-1\"]}"), 0644)
if err != nil {
t.Fatal(err)
}
time.Sleep(100 * time.Millisecond) // wait for monitor to notice
config := &rspec.Spec{}
expected := config.Hooks
err = manager.Hooks(config, map[string]string{}, false)
if err != nil {
t.Fatal(err)
}
assert.Equal(t, expected, config.Hooks)
err = os.Remove(jsonPath)
if err != nil {
t.Fatal(err)
}
})
cancel()
err = <-sync
assert.Equal(t, context.Canceled, err)
}
func TestMonitorBadWatcher(t *testing.T) {
ctx := context.Background()
manager, err := New(ctx, []string{})
if err != nil {
t.Fatal(err)
}
manager.directories = []string{"/does/not/exist"}
sync := make(chan error, 2)
go manager.Monitor(ctx, sync)
err = <-sync
if !os.IsNotExist(err) {
t.Fatal("opaque wrapping for not-exist errors")
}
}

83
pkg/hooks/read.go Normal file
View File

@ -0,0 +1,83 @@
// Package hooks implements CRI-O's hook handling.
package hooks
import (
"encoding/json"
"fmt"
"io/ioutil"
"path/filepath"
"strings"
"github.com/pkg/errors"
current "github.com/projectatomic/libpod/pkg/hooks/1.0.0"
)
type reader func(content []byte) (*current.Hook, error)
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{}
)
// Read reads a hook JSON file, verifies it, and returns the hook configuration.
func Read(path string) (*current.Hook, error) {
if !strings.HasSuffix(path, ".json") {
return nil, ErrNoJSONSuffix
}
content, err := ioutil.ReadFile(path)
if err != nil {
return nil, err
}
hook, err := read(content)
if err != nil {
return nil, errors.Wrapf(err, "parsing hook %q", path)
}
err = hook.Validate()
return hook, err
}
func read(content []byte) (hook *current.Hook, err error) {
var ver version
if err := json.Unmarshal(content, &ver); err != nil {
return nil, errors.Wrap(err, "version check")
}
reader, ok := Readers[ver.Version]
if !ok {
return nil, fmt.Errorf("unrecognized hook version: %q", ver.Version)
}
hook, err = reader(content)
if err != nil {
return hook, errors.Wrap(err, ver.Version)
}
return hook, err
}
// ReadDir reads hook JSON files from a directory into the given map,
// clobbering any previous entries with the same filenames.
func ReadDir(path string, hooks map[string]*current.Hook) error {
files, err := ioutil.ReadDir(path)
if err != nil {
return err
}
for _, file := range files {
hook, err := Read(filepath.Join(path, file.Name()))
if err != nil {
if err == ErrNoJSONSuffix {
continue
}
return err
}
hooks[file.Name()] = hook
}
return nil
}
func init() {
Readers[current.Version] = current.Read
}

193
pkg/hooks/read_test.go Normal file
View File

@ -0,0 +1,193 @@
package hooks
import (
"fmt"
"io/ioutil"
"os"
"path/filepath"
"testing"
rspec "github.com/opencontainers/runtime-spec/specs-go"
current "github.com/projectatomic/libpod/pkg/hooks/1.0.0"
"github.com/stretchr/testify/assert"
)
func TestNoJSONSuffix(t *testing.T) {
_, err := Read("abc")
assert.Equal(t, err, ErrNoJSONSuffix)
}
func TestUnknownPath(t *testing.T) {
_, err := Read(filepath.Join("does", "not", "exist.json"))
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^open does/not/exist.json: no such file or directory$", err.Error())
if !os.IsNotExist(err) {
t.Fatal("opaque wrapping for not-exist errors")
}
}
func TestGoodFile(t *testing.T) {
dir, err := ioutil.TempDir("", "hooks-test-")
if err != nil {
t.Fatal(err)
}
defer os.RemoveAll(dir)
jsonPath := filepath.Join(dir, "hook.json")
err = ioutil.WriteFile(jsonPath, []byte(fmt.Sprintf("{\"version\": \"1.0.0\", \"hook\": {\"path\": \"%s\"}, \"when\": {\"always\": true}, \"stages\": [\"prestart\"]}", path)), 0644)
if err != nil {
t.Fatal(err)
}
hook, err := Read(jsonPath)
if err != nil {
t.Fatal(err)
}
always := true
assert.Equal(t, &current.Hook{
Version: current.Version,
Hook: rspec.Hook{
Path: path,
},
When: current.When{
Always: &always,
},
Stages: []string{"prestart"},
}, hook)
}
func TestBadFile(t *testing.T) {
dir, err := ioutil.TempDir("", "hooks-test-")
if err != nil {
t.Fatal(err)
}
defer os.RemoveAll(dir)
path := filepath.Join(dir, "hook.json")
err = ioutil.WriteFile(path, []byte("{\"version\": \"1.0.0\", \"hook\": \"not-a-string\"}"), 0644)
if err != nil {
t.Fatal(err)
}
_, err = Read(path)
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^parsing hook \"[^\"]*hook.json\": 1.0.0: json: cannot unmarshal string into Go struct field Hook.hook of type specs.Hook$", err.Error())
}
func TestGoodBytes(t *testing.T) {
hook, err := read([]byte("{\"version\": \"1.0.0\", \"hook\": {\"path\": \"/a/b/c\"}, \"when\": {\"always\": true}, \"stages\": [\"prestart\"]}"))
if err != nil {
t.Fatal(err)
}
always := true
assert.Equal(t, &current.Hook{
Version: current.Version,
Hook: rspec.Hook{
Path: "/a/b/c",
},
When: current.When{
Always: &always,
},
Stages: []string{"prestart"},
}, hook)
}
func TestInvalidJSON(t *testing.T) {
_, err := read([]byte("{"))
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^version check: unexpected end of JSON input$", err.Error())
}
func TestInvalidVersion(t *testing.T) {
_, err := read([]byte("{\"version\": \"-1\"}"))
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^unrecognized hook version: \"-1\"$", err.Error())
}
func TestInvalidCurrentJSON(t *testing.T) {
_, err := read([]byte("{\"version\": \"1.0.0\", \"hook\": \"not-a-string\"}"))
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^1.0.0: json: cannot unmarshal string into Go struct field Hook.hook of type specs.Hook$", err.Error())
}
func TestGoodDir(t *testing.T) {
dir, err := ioutil.TempDir("", "hooks-test-")
if err != nil {
t.Fatal(err)
}
defer os.RemoveAll(dir)
err = ioutil.WriteFile(filepath.Join(dir, "README"), []byte("not a hook"), 0644)
if err != nil {
t.Fatal(err)
}
jsonPath := filepath.Join(dir, "a.json")
err = ioutil.WriteFile(jsonPath, []byte(fmt.Sprintf("{\"version\": \"1.0.0\", \"hook\": {\"path\": \"%s\"}, \"when\": {\"always\": true}, \"stages\": [\"prestart\"]}", path)), 0644)
if err != nil {
t.Fatal(err)
}
hooks := map[string]*current.Hook{}
err = ReadDir(dir, hooks)
if err != nil {
t.Fatal(err)
}
always := true
assert.Equal(t, map[string]*current.Hook{
"a.json": {
Version: current.Version,
Hook: rspec.Hook{
Path: path,
},
When: current.When{
Always: &always,
},
Stages: []string{"prestart"},
},
}, hooks)
}
func TestUnknownDir(t *testing.T) {
hooks := map[string]*current.Hook{}
err := ReadDir(filepath.Join("does", "not", "exist"), hooks)
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^open does/not/exist: no such file or directory$", err.Error())
if !os.IsNotExist(err) {
t.Fatal("opaque wrapping for not-exist errors")
}
}
func TestBadDir(t *testing.T) {
dir, err := ioutil.TempDir("", "hooks-test-")
if err != nil {
t.Fatal(err)
}
defer os.RemoveAll(dir)
jsonPath := filepath.Join(dir, "a.json")
err = ioutil.WriteFile(jsonPath, []byte("{\"version\": \"-1\"}"), 0644)
if err != nil {
t.Fatal(err)
}
hooks := map[string]*current.Hook{}
err = ReadDir(dir, hooks)
if err == nil {
t.Fatal("unexpected success")
}
assert.Regexp(t, "^parsing hook \"[^\"]*a.json\": unrecognized hook version: \"-1\"$", err.Error())
}

6
pkg/hooks/version.go Normal file
View File

@ -0,0 +1,6 @@
package hooks
// version a structure for checking the version of a hook configuration.
type version struct {
Version string `json:"version"`
}