summaryrefslogtreecommitdiff
path: root/pkg/hooks/0.1.0
diff options
context:
space:
mode:
authorW. Trevor King <wking@tremily.us>2018-04-27 10:35:32 -0700
committerAtomic Bot <atomic-devel@projectatomic.io>2018-05-11 16:26:35 +0000
commit68eb128fb0ad261f48f960547742542584ff1f11 (patch)
tree024e42956545ae7ef59731bebd8cd1f3392039b9 /pkg/hooks/0.1.0
parent9657cd6c15372f8c655ec13ce4f0310ff5d6a7a1 (diff)
downloadpodman-68eb128fb0ad261f48f960547742542584ff1f11.tar.gz
podman-68eb128fb0ad261f48f960547742542584ff1f11.tar.bz2
podman-68eb128fb0ad261f48f960547742542584ff1f11.zip
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
Diffstat (limited to 'pkg/hooks/0.1.0')
-rw-r--r--pkg/hooks/0.1.0/hook.go93
-rw-r--r--pkg/hooks/0.1.0/hook_test.go182
2 files changed, 275 insertions, 0 deletions
diff --git a/pkg/hooks/0.1.0/hook.go b/pkg/hooks/0.1.0/hook.go
new file mode 100644
index 000000000..e10c3d254
--- /dev/null
+++ b/pkg/hooks/0.1.0/hook.go
@@ -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
+}
diff --git a/pkg/hooks/0.1.0/hook_test.go b/pkg/hooks/0.1.0/hook_test.go
new file mode 100644
index 000000000..44cb21e3a
--- /dev/null
+++ b/pkg/hooks/0.1.0/hook_test.go
@@ -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)
+}