feat: add pre_start lifecycle hook for init containers

Implements the `pre_start` service field introduced in
compose-spec/compose-spec#647: an ordered list
of init containers run to completion before the service container
starts. Each step runs in its own ephemeral container; a non-zero exit
fails the bring-up of the service and its dependents.

Compose-go owns parsing, validation via JSON schema, and image
inheritance: when a pre_start hook omits `image`, it is normalized
to the parent service's image. Volume/network inheritance and the
runtime execution stay with docker/compose.

Signed-off-by: Guillaume Lours <glours@users.noreply.github.com>

Author: glours

loader/normalize.go

@@ -133,6 +133,9 @@ func Normalize(dict map[string]any, env types.Mapping) (map[string]any, error) {
 			if len(dependsOn) > 0 {
 				service["depends_on"] = dependsOn
 			}
+
+			inheritPreStartImage(service)
+
 			services[name] = service
 		}
 
@@ -143,6 +146,25 @@ func Normalize(dict map[string]any, env types.Mapping) (map[string]any, error) {
 	return dict, nil
 }
 
+// inheritPreStartImage propagates the parent service's image to any pre_start
+// hook that does not declare its own, per compose-spec PR #647.
+func inheritPreStartImage(service map[string]any) {
+	hooks, ok := service["pre_start"].([]any)
+	if !ok {
+		return
+	}
+	image, ok := service["image"].(string)
+	if !ok || image == "" {
+		return
+	}
+	for _, h := range hooks {
+		hook := h.(map[string]any)
+		if _, set := hook["image"]; !set {
+			hook["image"] = image
+		}
+	}
+}
+
 func normalizeNetworks(dict map[string]any) {
 	var networks map[string]any
 	if n, ok := dict["networks"]; ok {

loader/normalize_test.go

@@ -376,3 +376,71 @@ services:
 	assert.NilError(t, err)
 	assert.DeepEqual(t, expect, model)
 }
+
+func TestNormalizePreStartInheritsServiceImage(t *testing.T) {
+	project := `
+name: myProject
+services:
+  app:
+    image: alpine
+    pre_start:
+      - command: ["migrate"]
+      - image: busybox
+        command: ["chown", "-R", "1000:1000", "/data"]
+  builder:
+    build:
+      context: .
+    pre_start:
+      - command: ["init"]
+  hybrid:
+    image: ubuntu
+    build:
+      context: .
+    pre_start:
+      - command: ["bootstrap"]
+`
+	expected := `
+name: myProject
+services:
+  app:
+    image: alpine
+    networks:
+      default: null
+    pre_start:
+      - command: ["migrate"]
+        image: alpine
+      - image: busybox
+        command: ["chown", "-R", "1000:1000", "/data"]
+  builder:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    networks:
+      default: null
+    pre_start:
+      - command: ["init"]
+  hybrid:
+    image: ubuntu
+    build:
+      context: .
+      dockerfile: Dockerfile
+    networks:
+      default: null
+    pre_start:
+      - command: ["bootstrap"]
+        image: ubuntu
+networks:
+  default:
+    name: myProject_default
+`
+	var model map[string]any
+	err := yaml.Unmarshal([]byte(project), &model)
+	assert.NilError(t, err)
+	model, err = Normalize(model, nil)
+	assert.NilError(t, err)
+
+	var expect map[string]any
+	err = yaml.Unmarshal([]byte(expected), &expect)
+	assert.NilError(t, err)
+	assert.DeepEqual(t, expect, model)
+}

loader/tests/service_hooks_test.go

@@ -17,8 +17,10 @@
 package tests
 
 import (
+	"context"
 	"testing"
 
+	"github.com/compose-spec/compose-go/v2/loader"
 	"github.com/compose-spec/compose-go/v2/types"
 	"gotest.tools/v3/assert"
 )
@@ -29,6 +31,17 @@ name: test
 services:
   test:
     image: alpine
+    pre_start:
+      - command: ["./manage.py", "migrate"]
+        user: root
+        working_dir: /app
+        environment:
+          - FOO=BAR
+      - image: busybox
+        command: sh -c 'chown -R 1000:1000 /data'
+        privileged: true
+        per_replica: true
+      - image: migrator:latest
     post_start:
       - command: echo start
         user: root
@@ -43,6 +56,25 @@ services:
         environment:
           FOO: BAR
 `)
+	assert.DeepEqual(t, p.Services["test"].PreStart, []types.ServiceHook{
+		{
+			Command:    types.ShellCommand{"./manage.py", "migrate"},
+			User:       "root",
+			WorkingDir: "/app",
+			Environment: types.MappingWithEquals{
+				"FOO": ptr("BAR"),
+			},
+		},
+		{
+			Image:      "busybox",
+			Command:    types.ShellCommand{"sh", "-c", "chown -R 1000:1000 /data"},
+			Privileged: true,
+			PerReplica: true,
+		},
+		{
+			Image: "migrator:latest",
+		},
+	})
 	assert.DeepEqual(t, p.Services["test"].PostStart, []types.ServiceHook{
 		{
 			Command:    types.ShellCommand{"echo", "start"},
@@ -65,3 +97,23 @@ services:
 		},
 	})
 }
+
+func TestPreStartInheritsServiceImage(t *testing.T) {
+	yaml := `
+name: test
+services:
+  test:
+    image: alpine
+    pre_start:
+      - command: ["migrate"]
+      - image: busybox
+        command: ["echo", "hi"]
+`
+	p, err := loader.LoadWithContext(context.TODO(), types.ConfigDetails{
+		ConfigFiles: []types.ConfigFile{{Filename: "compose.yml", Content: []byte(yaml)}},
+		Environment: map[string]string{},
+	})
+	assert.NilError(t, err)
+	assert.Equal(t, p.Services["test"].PreStart[0].Image, "alpine")
+	assert.Equal(t, p.Services["test"].PreStart[1].Image, "busybox")
+}

schema/compose-spec.json

@@ -688,6 +688,11 @@
           },
           "uniqueItems": true
         },
+        "pre_start": {
+          "type": "array",
+          "items": {"$ref": "#/$defs/pre_start_hook"},
+          "description": "Init containers to run to completion before the service container is started. Each step runs in its own ephemeral container, in declared order; a non-zero exit fails the bring-up of the service and its dependents."
+        },
         "post_start": {
           "type": "array",
           "items": {"$ref": "#/$defs/service_hook"},
@@ -1657,6 +1662,43 @@
       "required": ["command"]
     },
 
+    "pre_start_hook": {
+      "type": "object",
+      "description": "Configuration for a pre_start init container, run to completion before the service container starts.",
+      "properties": {
+        "command": {
+          "$ref": "#/$defs/command",
+          "description": "Command to execute. Optional when the chosen image's entrypoint already runs the intended command."
+        },
+        "image": {
+          "type": "string",
+          "description": "Image used for the ephemeral container. If omitted, the parent service's image is used."
+        },
+        "user": {
+          "type": "string",
+          "description": "User to run the command as. Defaults to the user declared in image (or to the service's user when image is omitted)."
+        },
+        "privileged": {
+          "type": ["boolean", "string"],
+          "description": "Whether to run the command with extended privileges."
+        },
+        "working_dir": {
+          "type": "string",
+          "description": "Working directory for the command. Defaults to the service's working directory."
+        },
+        "environment": {
+          "$ref": "#/$defs/list_or_dict",
+          "description": "Environment variables for the command. Appended to or overriding the service environment."
+        },
+        "per_replica": {
+          "type": ["boolean", "string"],
+          "description": "Whether the hook runs once per service replica (true), or once for the service as a whole before any replica starts (false, the default)."
+        }
+      },
+      "additionalProperties": false,
+      "patternProperties": {"^x-": {}}
+    },
+
     "env_file": {
       "oneOf": [
         {

types/derived.gen.go

@@ -16,13 +16,17 @@
 
 package types
 
-// ServiceHook is a command to exec inside container by some lifecycle events
+// ServiceHook is a hook executed at a service lifecycle event: a command exec'd
+// inside the service container for post_start/pre_stop, or an ephemeral
+// container run before the service starts for pre_start.
 type ServiceHook struct {
 	Command     ShellCommand      `yaml:"command,omitempty" json:"command"`
+	Image       string            `yaml:"image,omitempty" json:"image,omitempty"`
 	User        string            `yaml:"user,omitempty" json:"user,omitempty"`
 	Privileged  bool              `yaml:"privileged,omitempty" json:"privileged,omitempty"`
 	WorkingDir  string            `yaml:"working_dir,omitempty" json:"working_dir,omitempty"`
 	Environment MappingWithEquals `yaml:"environment,omitempty" json:"environment,omitempty"`
+	PerReplica  bool              `yaml:"per_replica,omitempty" json:"per_replica,omitempty"`
 
 	Extensions Extensions `yaml:"#extensions,inline,omitempty" json:"-"`
 }

types/hooks.go

@@ -138,6 +138,7 @@ type ServiceConfig struct {
 	Volumes         []ServiceVolumeConfig            `yaml:"volumes,omitempty" json:"volumes,omitempty"`
 	VolumesFrom     []string                         `yaml:"volumes_from,omitempty" json:"volumes_from,omitempty"`
 	WorkingDir      string                           `yaml:"working_dir,omitempty" json:"working_dir,omitempty"`
+	PreStart        []ServiceHook                    `yaml:"pre_start,omitempty" json:"pre_start,omitempty"`
 	PostStart       []ServiceHook                    `yaml:"post_start,omitempty" json:"post_start,omitempty"`
 	PreStop         []ServiceHook                    `yaml:"pre_stop,omitempty" json:"pre_stop,omitempty"`