dockerfile: implement hooks for RUN instructions

Close issue 4576

- - -

e.g.,
```bash
buildctl build \
  --frontend dockerfile.v0 \
  --opt hook="$(cat hook.json)"
```
with `hook.json` as follows:
```json
{
  "RUN": {
    "entrypoint": ["/dev/.dfhook/entrypoint"],
    "mounts": [
      {"from": "example.com/hook", "target": "/dev/.dfhook"},
      {"type": "secret", "source": "something", "target": "/etc/something"}
    ]
  }
}
```

This will let the frontend treat `RUN foo` as:
```dockerfile
RUN \
  --mount=from=example.com/hook,target=/dev/.dfhook \
  --mount=type=secret,source=something,target=/etc/something \
  /dev/.dfhook/entrypoint foo
```

`docker history` will still show this as `RUN foo`.

Signed-off-by: Akihiro Suda <[email protected]>

Author: AkihiroSuda

docs/reference/buildctl.md

@@ -181,6 +181,45 @@ $ buildctl build --frontend dockerfile.v0 --local context=. --local dockerfile=.
 $ buildctl build --frontend dockerfile.v0 --local context=. --local dockerfile=. --oci-layout foo2=/home/dir/oci --opt context:alpine=oci-layout://foo2@sha256:bd04a5b26dec16579cd1d7322e949c5905c4742269663fcbc84dcb2e9f4592fb
 ```
 
+##### Instruction hooks
+<!-- TODO: s/master/v0.14/ -->
+In the master branch, the Dockerfile frontend also supports "instruction hooks".
+
+e.g.,
+
+```bash
+buildctl build \
+  --frontend dockerfile.v0 \
+  --opt hook="$(cat hook.json)"
+```
+with `hook.json` as follows:
+```json
+{
+  "RUN": {
+    "entrypoint": ["/dev/.dfhook/entrypoint"],
+    "mounts": [
+       {"from": "example.com/hook", "target": "/dev/.dfhook"},
+       {"type": "secret", "source": "something", "target": "/etc/something"}
+    ]
+  }
+}
+```
+
+This will let the frontend treat `RUN foo` as:
+```dockerfile
+RUN \
+  --mount=from=example.com/hook,target=/dev/.dfhook \
+  --mount=type=secret,source=something,target=/etc/something \
+  /dev/.dfhook/entrypoint foo
+```
+
+`docker history` will still show this as `RUN foo`.
+
+<!--
+TODO: add example hook images to show concrete use-cases
+https://github.com/moby/buildkit/issues/4576
+-->
+
 #### gateway-specific options
 
 The `gateway.v0` frontend passes all of its `--opt` options on to the OCI image that is called to convert the

frontend/dockerfile/dockerfile2llb/convert.go

@@ -26,6 +26,7 @@ import (
 	"github.com/moby/buildkit/frontend/dockerfile/parser"
 	"github.com/moby/buildkit/frontend/dockerfile/shell"
 	"github.com/moby/buildkit/frontend/dockerui"
+	"github.com/moby/buildkit/frontend/dockerui/types"
 	"github.com/moby/buildkit/frontend/subrequests/lint"
 	"github.com/moby/buildkit/frontend/subrequests/outline"
 	"github.com/moby/buildkit/frontend/subrequests/targets"
@@ -139,7 +140,7 @@ func ListTargets(ctx context.Context, dt []byte) (*targets.List, error) {
 		return nil, err
 	}
 
-	stages, _, err := instructions.Parse(dockerfile.AST, nil)
+	stages, _, err := instructions.Parse(dockerfile.AST, nil, instructions.ParseOpts{})
 	if err != nil {
 		return nil, err
 	}
@@ -222,7 +223,10 @@ func toDispatchState(ctx context.Context, dt []byte, opt ConvertOpt) (*dispatchS
 
 	proxyEnv := proxyEnvFromBuildArgs(opt.BuildArgs)
 
-	stages, metaArgs, err := instructions.Parse(dockerfile.AST, opt.Warn)
+	parseOpts := instructions.ParseOpts{
+		InstructionHook: opt.InstructionHook,
+	}
+	stages, metaArgs, err := instructions.Parse(dockerfile.AST, opt.Warn, parseOpts)
 	if err != nil {
 		return nil, err
 	}
@@ -612,6 +616,7 @@ func toDispatchState(ctx context.Context, dt []byte, opt ConvertOpt) (*dispatchS
 			llbCaps:           opt.LLBCaps,
 			sourceMap:         opt.SourceMap,
 			lintWarn:          opt.Warn,
+			instHook:          opt.InstructionHook,
 		}
 
 		if err = dispatchOnBuildTriggers(d, d.image.Config.OnBuild, opt); err != nil {
@@ -748,6 +753,7 @@ type dispatchOpt struct {
 	llbCaps           *apicaps.CapSet
 	sourceMap         *llb.SourceMap
 	lintWarn          linter.LintWarnFunc
+	instHook          *types.InstructionHook
 }
 
 func dispatch(d *dispatchState, cmd command, opt dispatchOpt) error {
@@ -958,6 +964,9 @@ type command struct {
 }
 
 func dispatchOnBuildTriggers(d *dispatchState, triggers []string, opt dispatchOpt) error {
+	parseOpts := instructions.ParseOpts{
+		InstructionHook: opt.instHook,
+	}
 	for _, trigger := range triggers {
 		ast, err := parser.Parse(strings.NewReader(trigger))
 		if err != nil {
@@ -966,7 +975,7 @@ func dispatchOnBuildTriggers(d *dispatchState, triggers []string, opt dispatchOp
 		if len(ast.AST.Children) != 1 {
 			return errors.New("onbuild trigger should be a single expression")
 		}
-		ic, err := instructions.ParseCommand(ast.AST.Children[0])
+		ic, err := instructions.ParseCommand(ast.AST.Children[0], parseOpts)
 		if err != nil {
 			return err
 		}
@@ -1058,6 +1067,12 @@ func dispatchRun(d *dispatchState, c *instructions.RunCommand, proxy *llb.ProxyE
 		args = withShell(d.image, args)
 	}
 
+	argsForHistory := args
+	if dopt.instHook != nil && dopt.instHook.Run != nil {
+		args = append(dopt.instHook.Run.Entrypoint, args...)
+		// leave argsForHistory unmodified
+	}
+
 	env, err := d.state.Env(context.TODO())
 	if err != nil {
 		return err
@@ -1124,7 +1139,7 @@ func dispatchRun(d *dispatchState, c *instructions.RunCommand, proxy *llb.ProxyE
 	}
 
 	d.state = d.state.Run(opt...).Root()
-	return commitToHistory(&d.image, "RUN "+runCommandString(args, d.buildArgs, shell.BuildEnvs(env)), true, &d.state, d.epoch)
+	return commitToHistory(&d.image, "RUN "+runCommandString(argsForHistory, d.buildArgs, shell.BuildEnvs(env)), true, &d.state, d.epoch)
 }
 
 func dispatchWorkdir(d *dispatchState, c *instructions.WorkdirCommand, commit bool, opt *dispatchOpt) error {

frontend/dockerfile/dockerfile_insthook_test.go

@@ -0,0 +1,76 @@
+package dockerfile
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/containerd/continuity/fs/fstest"
+	"github.com/moby/buildkit/client"
+	"github.com/moby/buildkit/frontend/dockerui"
+	"github.com/moby/buildkit/util/testutil/integration"
+	"github.com/stretchr/testify/require"
+	"github.com/tonistiigi/fsutil"
+)
+
+var instHookTests = integration.TestFuncs(
+	testInstructionHook,
+)
+
+func testInstructionHook(t *testing.T, sb integration.Sandbox) {
+	integration.SkipOnPlatform(t, "windows")
+	f := getFrontend(t, sb)
+
+	dockerfile := []byte(`
+FROM busybox AS base
+RUN echo "$FOO" >/foo
+
+FROM scratch
+COPY --from=base /foo /foo
+`)
+
+	dir := integration.Tmpdir(
+		t,
+		fstest.CreateFile("Dockerfile", dockerfile, 0600),
+	)
+	destDir := t.TempDir()
+
+	c, err := client.New(sb.Context(), sb.Address())
+	require.NoError(t, err)
+	defer c.Close()
+
+	build := func(attrs map[string]string) string {
+		_, err = f.Solve(sb.Context(), c, client.SolveOpt{
+			FrontendAttrs: attrs,
+			Exports: []client.ExportEntry{
+				{
+					Type:      client.ExporterLocal,
+					OutputDir: destDir,
+				},
+			},
+			LocalMounts: map[string]fsutil.FS{
+				dockerui.DefaultLocalNameDockerfile: dir,
+				dockerui.DefaultLocalNameContext:    dir,
+			},
+		}, nil)
+		require.NoError(t, err)
+		p := filepath.Join(destDir, "foo")
+		b, err := os.ReadFile(p)
+		require.NoError(t, err)
+		return strings.TrimSpace(string(b))
+	}
+
+	require.Equal(t, "", build(nil))
+
+	const hook = `
+{
+  "RUN": {
+    "entrypoint": ["/dev/.dfhook/bin/busybox", "env", "FOO=BAR"],
+    "mounts": [
+      {"from": "busybox:uclibc", "target": "/dev/.dfhook"}
+    ]
+  }
+}`
+	require.Equal(t, "BAR", build(map[string]string{"hook": hook}))
+}

frontend/dockerfile/dockerfile_test.go

@@ -255,6 +255,7 @@ func TestIntegration(t *testing.T) {
 			"amd64/bullseye-20230109-slim": "docker.io/amd64/debian:bullseye-20230109-slim@sha256:1acb06a0c31fb467eb8327ad361f1091ab265e0bf26d452dea45dcb0c0ea5e75",
 		}),
 	)...)
+	integration.Run(t, instHookTests, opts...)
 }
 
 func testDefaultEnvWithArgs(t *testing.T, sb integration.Sandbox) {

frontend/dockerfile/instructions/commands.go

@@ -4,6 +4,7 @@ import (
 	"strings"
 
 	"github.com/moby/buildkit/frontend/dockerfile/parser"
+	"github.com/moby/buildkit/frontend/dockerui/types"
 	dockerspec "github.com/moby/docker-image-spec/specs-go/v1"
 	"github.com/pkg/errors"
 )
@@ -338,7 +339,7 @@ type ShellDependantCmdLine struct {
 //	RUN ["echo", "hi"]  # echo hi
 type RunCommand struct {
 	withNameAndCode
-	withExternalData
+	WithInstructionHook
 	ShellDependantCmdLine
 	FlagsUsed []string
 }
@@ -549,3 +550,21 @@ func (c *withExternalData) setExternalValue(k, v interface{}) {
 	}
 	c.m[k] = v
 }
+
+type WithInstructionHook struct {
+	withExternalData
+}
+
+const instHookKey = "dockerfile/run/instruction-hook"
+
+func (c *WithInstructionHook) GetInstructionHook() *types.InstructionHook {
+	x := c.getExternalValue(instHookKey)
+	if x == nil {
+		return nil
+	}
+	return x.(*types.InstructionHook)
+}
+
+func (c *WithInstructionHook) SetInstructionHook(h *types.InstructionHook) {
+	c.setExternalValue(instHookKey, h)
+}

frontend/dockerfile/instructions/commands_runmount.go

@@ -86,6 +86,15 @@ func setMountState(cmd *RunCommand, expander SingleWordExpander) error {
 		return errors.Errorf("no mount state")
 	}
 	var mounts []*Mount
+	if hook := cmd.GetInstructionHook(); hook != nil && hook.Run != nil {
+		for _, m := range hook.Run.Mounts {
+			m := m
+			if err := validateMount(&m, false); err != nil {
+				return err
+			}
+			mounts = append(mounts, &m)
+		}
+	}
 	for _, str := range st.flag.StringValues {
 		m, err := parseMount(str, expander)
 		if err != nil {

frontend/dockerfile/instructions/parse.go

@@ -15,13 +15,18 @@ import (
 	"github.com/moby/buildkit/frontend/dockerfile/command"
 	"github.com/moby/buildkit/frontend/dockerfile/linter"
 	"github.com/moby/buildkit/frontend/dockerfile/parser"
+	"github.com/moby/buildkit/frontend/dockerui/types"
 	"github.com/moby/buildkit/util/suggest"
 	dockerspec "github.com/moby/docker-image-spec/specs-go/v1"
 	"github.com/pkg/errors"
 )
 
 var excludePatternsEnabled = false
 
+type ParseOpts struct {
+	InstructionHook *types.InstructionHook
+}
+
 type parseRequest struct {
 	command    string
 	args       []string
@@ -31,6 +36,7 @@ type parseRequest struct {
 	original   string
 	location   []parser.Range
 	comments   []string
+	opts       ParseOpts
 }
 
 var parseRunPreHooks []func(*RunCommand, parseRequest) error
@@ -66,16 +72,17 @@ func newParseRequestFromNode(node *parser.Node) parseRequest {
 	}
 }
 
-func ParseInstruction(node *parser.Node) (v interface{}, err error) {
-	return ParseInstructionWithLinter(node, nil)
+func ParseInstruction(node *parser.Node, opts ParseOpts) (v interface{}, err error) {
+	return ParseInstructionWithLinter(node, nil, opts)
 }
 
 // ParseInstruction converts an AST to a typed instruction (either a command or a build stage beginning when encountering a `FROM` statement)
-func ParseInstructionWithLinter(node *parser.Node, lintWarn linter.LintWarnFunc) (v interface{}, err error) {
+func ParseInstructionWithLinter(node *parser.Node, lintWarn linter.LintWarnFunc, opts ParseOpts) (v interface{}, err error) {
 	defer func() {
 		err = parser.WithLocation(err, node.Location())
 	}()
 	req := newParseRequestFromNode(node)
+	req.opts = opts
 	switch strings.ToLower(node.Value) {
 	case command.Env:
 		return parseEnv(req)
@@ -130,8 +137,8 @@ func ParseInstructionWithLinter(node *parser.Node, lintWarn linter.LintWarnFunc)
 }
 
 // ParseCommand converts an AST to a typed Command
-func ParseCommand(node *parser.Node) (Command, error) {
-	s, err := ParseInstruction(node)
+func ParseCommand(node *parser.Node, opts ParseOpts) (Command, error) {
+	s, err := ParseInstruction(node, opts)
 	if err != nil {
 		return nil, err
 	}
@@ -166,9 +173,9 @@ func (e *parseError) Unwrap() error {
 
 // Parse a Dockerfile into a collection of buildable stages.
 // metaArgs is a collection of ARG instructions that occur before the first FROM.
-func Parse(ast *parser.Node, lint linter.LintWarnFunc) (stages []Stage, metaArgs []ArgCommand, err error) {
+func Parse(ast *parser.Node, lint linter.LintWarnFunc, opts ParseOpts) (stages []Stage, metaArgs []ArgCommand, err error) {
 	for _, n := range ast.Children {
-		cmd, err := ParseInstructionWithLinter(n, lint)
+		cmd, err := ParseInstructionWithLinter(n, lint, opts)
 		if err != nil {
 			return nil, nil, &parseError{inner: err, node: n}
 		}
@@ -490,6 +497,7 @@ func parseShellDependentCommand(req parseRequest, emptyAsNil bool) (ShellDependa
 
 func parseRun(req parseRequest) (*RunCommand, error) {
 	cmd := &RunCommand{}
+	cmd.SetInstructionHook(req.opts.InstructionHook)
 
 	for _, fn := range parseRunPreHooks {
 		if err := fn(cmd, req); err != nil {

frontend/dockerfile/instructions/parse_heredoc_test.go

@@ -28,7 +28,7 @@ func TestErrorCasesHeredoc(t *testing.T) {
 			t.Fatalf("Error when parsing Dockerfile: %s", err)
 		}
 		n := ast.AST.Children[0]
-		_, err = ParseInstruction(n)
+		_, err = ParseInstruction(n, ParseOpts{})
 		require.Error(t, err)
 		require.Contains(t, err.Error(), c.expectedError)
 	}
@@ -166,7 +166,7 @@ EOF`,
 		require.NoError(t, err)
 
 		n := ast.AST.Children[0]
-		comm, err := ParseInstruction(n)
+		comm, err := ParseInstruction(n, ParseOpts{})
 		require.NoError(t, err)
 
 		sd := comm.(*CopyCommand).SourcesAndDest
@@ -248,7 +248,7 @@ EOF`,
 		require.NoError(t, err)
 
 		n := ast.AST.Children[0]
-		comm, err := ParseInstruction(n)
+		comm, err := ParseInstruction(n, ParseOpts{})
 		require.NoError(t, err)
 		require.Equal(t, c.shell, comm.(*RunCommand).PrependShell)
 		require.Equal(t, c.command, comm.(*RunCommand).CmdLine)