run: trigger a job through the engine like a service

`docker compose run <job>` triggers a run of the job on the engine,
starts its dependencies first, streams its logs and returns its exit
code like a one-off service; a job accepts manual triggering unless it
declares manual: false. A scheduled job runs as up registered it: an
override, or a job up never registered, is refused. A manual job is
removed from the engine after its run, so the next run can differ. When
the engine cannot run jobs, run falls back to a one-off service with a
warning. --detach is refused, an interrupted run is cancelled, a dry run
only reports it. A job named by create, start, build, pull or push gets
an error naming run instead.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Guillaume Lours <glours@users.noreply.github.com>
This commit is contained in:
Guillaume Lours 2026-11-10 16:47:28 +01:00 • committed by Nicolas De loof
parent 723ce2bf4e
commit 0aff61809c
19 changed files with 1232 additions and 74 deletions

View file

@ -183,5 +183,6 @@ func runBuild(ctx context.Context, dockerCli command.Cli, backendOptions *Backen
}
apiBuildOptions.Attestations = true
return backend.Build(ctx, project, apiBuildOptions)
err = backend.Build(ctx, project, apiBuildOptions)
return jobTargetErrOr(ctx, dockerCli, opts.ProjectOptions, services, err)
}

View file

@ -205,7 +205,12 @@ func (o *ProjectOptions) WithServices(dockerCli command.Cli, fn ProjectServicesF
project, metrics, err := o.ToProject(ctx, dockerCli, backend, services, warnUnsupportedAttributes, cli.WithoutEnvironmentResolution)
if err != nil {
return err
// a service name among services can genuinely be a declared job:
// every WithServices caller has nothing to act on for it, so
// report that clearly instead of the raw "no such service" — same
// translation projectOrName already centralizes for its own callers
// (start/stop/down/...).
return jobTargetErrOr(ctx, dockerCli, o, services, err)
}
ctx = context.WithValue(ctx, tracing.MetricsKey{}, metrics)

View file

@ -31,7 +31,6 @@ import (
"github.com/spf13/cobra"
"github.com/spf13/pflag"
"github.com/docker/compose/v5/cmd/display"
"github.com/docker/compose/v5/pkg/api"
"github.com/docker/compose/v5/pkg/compose"
)
@ -73,18 +72,9 @@ func createCommand(p *ProjectOptions, dockerCli command.Cli, backendOptions *Bac
}
return nil
}),
RunE: func(cmd *cobra.Command, args []string) error {
err := p.WithServices(dockerCli, func(ctx context.Context, project *types.Project, services []string) error {
return runCreate(ctx, dockerCli, backendOptions, opts, buildOpts, project, services)
})(cmd, args)
if jobErr, replaced := jobTargetErr(cmd.Context(), dockerCli, p, args, err); replaced {
if display.Mode == display.ModeJSON {
return makeJSONError(jobErr)
}
return jobErr
}
return err
},
RunE: p.WithServices(dockerCli, func(ctx context.Context, project *types.Project, services []string) error {
return runCreate(ctx, dockerCli, backendOptions, opts, buildOpts, project, services)
}),
ValidArgsFunction: completeServiceNames(dockerCli, p),
}
flags := cmd.Flags()

View file

@ -106,7 +106,7 @@ func runPull(ctx context.Context, dockerCli command.Cli, backendOptions *Backend
project, _, err := opts.ToProject(ctx, dockerCli, backend, services, warnUnsupportedAttributes, cli.WithoutEnvironmentResolution)
if err != nil {
return err
return jobTargetErrOr(ctx, dockerCli, opts.ProjectOptions, services, err)
}
project, err = opts.apply(project, services)

View file

@ -66,7 +66,7 @@ func runPush(ctx context.Context, dockerCli command.Cli, backendOptions *Backend
project, _, err := opts.ToProject(ctx, dockerCli, backend, services, warnUnsupportedAttributes)
if err != nil {
return err
return jobTargetErrOr(ctx, dockerCli, opts.ProjectOptions, services, err)
}
if !opts.IncludeDeps {

View file

@ -91,8 +91,13 @@ func (options runOptions) apply(project *types.Project) (*types.Project, error)
target.Tty = !options.noTty
target.StdinOpen = options.interactive
// A scheduled job runs with the ports it was registered with, unless
// --publish says otherwise: clearing them would make its spec differ from the
// one `up` registered, which the engine refuses.
keepPorts := options.servicePorts || keepsJobPorts(project, options)
// --service-ports and --publish are incompatible
if !options.servicePorts {
if !keepPorts {
if len(target.Ports) > 0 {
logrus.Debug("Running service without ports exposed as --service-ports=false")
}
@ -123,6 +128,14 @@ func (options runOptions) apply(project *types.Project) (*types.Project, error)
return project, nil
}
// keepsJobPorts tells whether run leaves the ports of the job as declared: a
// scheduled job runs as registered, unless --publish says otherwise, and
// --service-ports asks for them.
func keepsJobPorts(project *types.Project, options runOptions) bool {
job, isJob := project.AllJobs()[options.Service]
return isJob && compose.HasSchedule(job) && !options.servicePorts && len(options.publish) == 0
}
func (options runOptions) getEnvironment(resolve func(string) (string, bool)) (types.Mapping, error) {
environment := types.NewMappingWithEquals(options.environment).Resolve(resolve).ToMapping()
for _, file := range options.envFiles {
@ -369,6 +382,17 @@ func jobTargetErr(ctx context.Context, dockerCli command.Cli, p *ProjectOptions,
return err, false
}
// jobTargetErrOr applies jobTargetErr's translation to err when it matches,
// and returns err unchanged otherwise — the wrap every caller loading a
// project outside WithServices/projectOrName's own centralized handling
// (build, pull, push) needs around its own selection error.
func jobTargetErrOr(ctx context.Context, dockerCli command.Cli, p *ProjectOptions, names []string, err error) error {
if jobErr, replaced := jobTargetErr(ctx, dockerCli, p, names, err); replaced {
return jobErr
}
return err
}
func runRun(ctx context.Context, backend api.Compose, project *types.Project, options runOptions, createOpts createOptions, buildOpts buildOptions, dockerCli command.Cli) error {
project, err := options.apply(project)
if err != nil {
@ -439,9 +463,31 @@ func runRun(ctx context.Context, backend api.Compose, project *types.Project, op
Index: 0,
}
if _, ok := project.AllJobs()[options.Service]; ok {
exitCode, err := backend.RunJob(ctx, project, options.Service, runOpts)
// An engine without usable jobs support runs the job like a one-off
// service: fall through, the job is already materialized as one.
if !errors.Is(err, api.ErrJobsNotSupported) {
if exitCode != 0 {
errMsg := ""
if err != nil {
errMsg = err.Error()
}
return cli.StatusError{StatusCode: exitCode, Status: errMsg, Cause: err}
}
return err
}
logrus.Warnf("%v: running %q as a one-off service", err, options.Service)
}
for name, service := range project.Services {
if name == options.Service {
service.StdinOpen = options.interactive
// apply kept the ports of a scheduled job for the engine to run it as
// registered; a one-off service publishes none unless asked to
if keepsJobPorts(project, options) {
service.Ports = []types.ServicePortConfig{}
}
project.Services[name] = service
}
}
@ -476,8 +522,8 @@ func materializeManualJob(project *types.Project, name string) (*types.Project,
if !ok {
return project, nil
}
if job.Triggers != nil && job.Triggers.Manual != nil && !*job.Triggers.Manual {
return nil, fmt.Errorf("job %q is declared with manual: false, it cannot be run manually", name)
if compose.ManualTriggerDisabled(job) {
return nil, compose.ManualTriggerDisabledErr(name)
}
project, err := project.WithSelectedJob(name)
if err != nil {
@ -492,7 +538,7 @@ func materializeManualJob(project *types.Project, name string) (*types.Project,
if err := materializeJobClosure(project, jobs, job, map[string]bool{name: true}); err != nil {
return nil, err
}
project.Services[name] = jobAsService(project, name, job)
project.Services[name] = compose.JobAsService(project, name, job)
return project, nil
}
@ -513,39 +559,13 @@ func materializeJobClosure(project *types.Project, jobs types.Jobs, job types.Jo
if !isJob {
continue
}
if depJob.Triggers != nil && depJob.Triggers.Manual != nil && !*depJob.Triggers.Manual {
if compose.ManualTriggerDisabled(depJob) {
return fmt.Errorf("job %q is declared with manual: false, it cannot be triggered even as a dependency of another job", dep)
}
if err := materializeJobClosure(project, jobs, depJob, seen); err != nil {
return err
}
project.Services[dep] = jobAsService(project, dep, depJob)
project.Services[dep] = compose.JobAsService(project, dep, depJob)
}
return nil
}
// jobAsService materializes a job as a service for the one-off machinery: a
// job is a ContainerSpec+WorkloadSpec, the same layers a service is made of.
// It carries the standard custom labels the loader stamps on every service —
// materialization happens after loading, so without them the containers
// created for a dependency job would be invisible to every label-driven
// path: start would silently skip them, ps/down would not see them, and the
// dependency wait would report the job as a missing dependency.
func jobAsService(project *types.Project, name string, job types.JobConfig) types.ServiceConfig {
svc := types.ServiceConfig{
Name: name,
Profiles: job.Profiles,
Extensions: job.Extensions,
ContainerSpec: job.ContainerSpec,
WorkloadSpec: job.WorkloadSpec,
}
svc.CustomLabels = types.Labels{
api.ProjectLabel: project.Name,
api.ServiceLabel: name,
api.VersionLabel: api.ComposeVersion,
api.WorkingDirLabel: project.WorkingDir,
api.ConfigFilesLabel: strings.Join(project.ComposeFiles, ","),
api.OneoffLabel: "False",
}
return svc
}

View file

@ -17,13 +17,24 @@
package compose
import (
"bytes"
"context"
"errors"
"fmt"
"os"
"path/filepath"
"strings"
"testing"
"github.com/compose-spec/compose-go/v2/types"
"github.com/docker/cli/cli"
cliopts "github.com/docker/cli/opts"
"github.com/sirupsen/logrus"
"go.uber.org/mock/gomock"
"gotest.tools/v3/assert"
"github.com/docker/compose/v5/pkg/api"
"github.com/docker/compose/v5/pkg/mocks"
)
func TestMaterializeManualJob(t *testing.T) {
@ -150,6 +161,45 @@ func TestMaterializeManualJob(t *testing.T) {
// error, ...) must not trigger that retry, since it would only duplicate
// side effects (remote include: fetches, unsupported-attribute warnings)
// before falling through to the same, unrecoverable error anyway.
// `run` publishes no port by default, but a scheduled job runs with the ports it
// was registered with: clearing them would make the spec differ from the one
// `up` registered, and the engine refuse it.
func TestRunOptionsApplyJobPorts(t *testing.T) {
yes := true
ports := []types.ServicePortConfig{{Target: 80, Published: "18080"}}
project := func() *types.Project {
return &types.Project{
Services: types.Services{"db": {Name: "db"}},
Jobs: types.Jobs{
"backup": {
Name: "backup",
Triggers: &types.TriggerConfig{Schedule: []types.ScheduleConfig{{Cron: "0 3 * * *"}}},
ContainerSpec: types.ContainerSpec{Image: "alpine"},
WorkloadSpec: types.WorkloadSpec{Ports: ports},
},
"migrate": {
Name: "migrate",
Triggers: &types.TriggerConfig{Manual: &yes},
ContainerSpec: types.ContainerSpec{Image: "alpine"},
WorkloadSpec: types.WorkloadSpec{Ports: ports},
},
},
}
}
portsAfter := func(t *testing.T, options runOptions) []types.ServicePortConfig {
t.Helper()
applied, err := options.apply(project())
assert.NilError(t, err)
return applied.Services[options.Service].Ports
}
assert.DeepEqual(t, portsAfter(t, runOptions{Service: "backup"}), ports)
assert.Equal(t, len(portsAfter(t, runOptions{Service: "migrate"})), 0, "a manual job is run like a service")
published := portsAfter(t, runOptions{Service: "backup", publish: []string{"9090:80"}})
assert.Equal(t, len(published), 1)
assert.Equal(t, published[0].Published, "9090", "--publish still replaces them")
}
func TestIsNoSuchServiceErr(t *testing.T) {
assert.Assert(t, isNoSuchServiceErr(errors.New("no such service: migrate")))
assert.Assert(t, !isNoSuchServiceErr(errors.New("interpolation error: bad substitution")))
@ -209,3 +259,112 @@ func TestJobTargetErr(t *testing.T) {
assert.Equal(t, err, original)
})
}
// run targets a job through the engine's jobs API when it has one, and
// degrades to a one-off service container, exactly like a service run, when
// it does not.
func TestRunRunJob(t *testing.T) {
yes := true
newProject := func() *types.Project {
return &types.Project{
Name: "prj",
Services: types.Services{},
Jobs: types.Jobs{"migrate": {
Name: "migrate",
Triggers: &types.TriggerConfig{Manual: &yes},
ContainerSpec: types.ContainerSpec{Image: "migrator"},
}},
}
}
run := func(t *testing.T, ctrl *gomock.Controller, backend api.Compose) error {
t.Helper()
return runRun(t.Context(), backend, newProject(),
runOptions{composeOptions: &composeOptions{ProjectOptions: &ProjectOptions{}}, Service: "migrate", noTty: true, capAdd: cliopts.NewListOpts(nil), capDrop: cliopts.NewListOpts(nil)},
createOptions{}, buildOptions{ProjectOptions: &ProjectOptions{}}, mocks.NewMockCli(ctrl))
}
t.Run("an engine with the jobs API runs the job through it", func(t *testing.T) {
ctrl := gomock.NewController(t)
backend := mocks.NewMockCompose(ctrl)
backend.EXPECT().RunJob(gomock.Any(), gomock.Any(), "migrate", gomock.Any()).Return(0, nil)
assert.NilError(t, run(t, ctrl, backend))
})
t.Run("a failing job reports its exit code", func(t *testing.T) {
ctrl := gomock.NewController(t)
backend := mocks.NewMockCompose(ctrl)
backend.EXPECT().RunJob(gomock.Any(), gomock.Any(), "migrate", gomock.Any()).Return(3, nil)
err := run(t, ctrl, backend)
var statusErr cli.StatusError
assert.Assert(t, errors.As(err, &statusErr), err)
assert.Equal(t, statusErr.StatusCode, 3)
})
t.Run("an engine without the jobs API runs the job like a one-off service", func(t *testing.T) {
ctrl := gomock.NewController(t)
backend := mocks.NewMockCompose(ctrl)
backend.EXPECT().RunJob(gomock.Any(), gomock.Any(), "migrate", gomock.Any()).Return(0, api.ErrJobsNotSupported)
backend.EXPECT().RunOneOffContainer(gomock.Any(), gomock.Any(), gomock.Any()).
DoAndReturn(func(_ context.Context, project *types.Project, opts api.RunOptions) (int, error) {
assert.Equal(t, opts.Service, "migrate")
_, materialized := project.Services["migrate"]
assert.Assert(t, materialized, "the job must be materialized as a service")
return 0, nil
})
assert.NilError(t, run(t, ctrl, backend))
})
// apply keeps the ports a scheduled job registered with, for the engine to
// run it as registered: a one-off service publishes none by default
t.Run("the fallback does not publish the ports of a scheduled job", func(t *testing.T) {
ctrl := gomock.NewController(t)
backend := mocks.NewMockCompose(ctrl)
backend.EXPECT().RunJob(gomock.Any(), gomock.Any(), "backup", gomock.Any()).Return(0, api.ErrJobsNotSupported)
backend.EXPECT().RunOneOffContainer(gomock.Any(), gomock.Any(), gomock.Any()).
DoAndReturn(func(_ context.Context, project *types.Project, _ api.RunOptions) (int, error) {
assert.Equal(t, len(project.Services["backup"].Ports), 0)
return 0, nil
})
project := &types.Project{
Name: "prj",
Services: types.Services{"db": {Name: "db"}},
Jobs: types.Jobs{"backup": {
Name: "backup",
Triggers: &types.TriggerConfig{Schedule: []types.ScheduleConfig{{Cron: "0 3 * * *"}}},
ContainerSpec: types.ContainerSpec{Image: "alpine"},
WorkloadSpec: types.WorkloadSpec{Ports: []types.ServicePortConfig{{Target: 80, Published: "18080"}}},
}},
}
options := runOptions{
composeOptions: &composeOptions{ProjectOptions: &ProjectOptions{}}, Service: "backup", noTty: true,
capAdd: cliopts.NewListOpts(nil), capDrop: cliopts.NewListOpts(nil),
}
assert.NilError(t, runRun(t.Context(), backend, project, options, createOptions{},
buildOptions{ProjectOptions: &ProjectOptions{}}, mocks.NewMockCli(ctrl)))
})
t.Run("the fallback warns with the reason the engine cannot run the job", func(t *testing.T) {
var out bytes.Buffer
logrus.SetOutput(&out)
t.Cleanup(func() { logrus.SetOutput(os.Stderr) })
ctrl := gomock.NewController(t)
backend := mocks.NewMockCompose(ctrl)
reason := fmt.Errorf("%w: start dockerd with --extension-enable org.mobyproject.jobs.v0", api.ErrJobsNotSupported)
backend.EXPECT().RunJob(gomock.Any(), gomock.Any(), "migrate", gomock.Any()).Return(0, reason)
backend.EXPECT().RunOneOffContainer(gomock.Any(), gomock.Any(), gomock.Any()).Return(0, nil)
assert.NilError(t, run(t, ctrl, backend))
assert.Assert(t, strings.Contains(out.String(), "level=warning"), out.String())
assert.Assert(t, strings.Contains(out.String(), "--extension-enable org.mobyproject.jobs.v0"), out.String())
assert.Assert(t, strings.Contains(out.String(), "migrate"), out.String())
})
t.Run("an engine whose jobs extension is not ready fails instead of degrading", func(t *testing.T) {
ctrl := gomock.NewController(t)
backend := mocks.NewMockCompose(ctrl) // no RunOneOffContainer expectation: degrading would fail the test
notReady := errors.New("the engine's jobs extension is enabled but not ready")
backend.EXPECT().RunJob(gomock.Any(), gomock.Any(), "migrate", gomock.Any()).Return(0, notReady)
assert.ErrorIs(t, run(t, ctrl, backend), notReady)
})
}

View file

@ -149,6 +149,21 @@ func TestUpRejectsScheduledJobsWithExtensionOff(t *testing.T) {
ServiceNotCreated("web"))
}
// Manual execution never needs the engine's help: without usable jobs support
// run degrades to a one-off service, scheduled jobs included, and says so.
func TestRunJobWithoutJobsExtension(t *testing.T) {
NewScenario(t, "run must execute a job as a one-off service, with a warning, when the engine cannot run jobs").
Requires(JobsExtensionDisabled).
Step("a manual job runs as a one-off service and the warning says so",
ComposeCmd("run", "--rm", "migrate"),
StderrContains("as a one-off service"),
OutputContains("migration done")).
Step("a scheduled job launched by hand degrades the same way",
ComposeCmd("run", "--rm", "backup"),
StderrContains("as a one-off service"),
OutputContains("backup done"))
}
// Without usable jobs support the engine has no job of the project to
// remove: down must not turn that into an error nor into noise.
func TestDownWithoutJobsExtension(t *testing.T) {
@ -179,6 +194,47 @@ func TestUpRegistersScheduledJobs(t *testing.T) {
Eventually(ServiceState("backup", "exited"), 90*time.Second))
}
// run must build the exact same spec `up` already registered a scheduled
// job with: CreateAndRun refuses schedule-trigger jobs outright, so run
// routes through Create (idempotent on SpecHash) then Run instead. A run
// invocation carries CLI/terminal-context defaults (Tty, StdinOpen,
// ContainerName) that up's own registration never does — if those leaked
// into the spec sent to Create, this would spuriously conflict with the
// job up already registered, even though nothing in the compose file
// changed.
func TestRunAlreadyRegisteredScheduledJob(t *testing.T) {
NewScenario(t, "run must not conflict with a scheduled job up already registered with the identical spec").
Requires(JobsExtensionEnabled).
Step("up registers the scheduled job",
ComposeCmd("up", "-d"),
ServiceState("web", "running")).
// no output check: the engine removes a scheduled job's container, logs
// included, as soon as it succeeds, so its output may never be readable
Step("run fires it manually without a SpecHash conflict",
ComposeCmd("run", "--rm", "backup")).
// --no-deps narrows the dependencies the run waits for, not the ones the
// registered spec declares
Step("run --no-deps does not conflict either",
ComposeCmd("run", "--rm", "--no-deps", "backup")).
// the registered job runs as it is: an override would not reach it
Step("run refuses an override rather than ignoring it",
ComposeCmd("run", "-e", "X=1", "backup").MayFail(),
StderrContains("scheduled job \"backup\" runs as registered by up"))
}
// run must not register a job: Create would arm its schedule, which up alone
// decides.
func TestRunUnregisteredScheduledJob(t *testing.T) {
NewScenario(t, "run must refuse a scheduled job up never registered, and leave it unregistered").
Requires(JobsExtensionEnabled).
Step("run says that up comes first",
ComposeCmd("run", "backup").MayFail(),
StderrContains("is not registered with the engine")).
Step("the job was not registered by the failed run",
ComposeCmd("up", "-d"),
OutputContains("Job backup Created"))
}
// up --no-start stops after creating the containers, and must still register
// the scheduled jobs: the engine's cron does not wait for a Start.
func TestUpNoStartRegistersScheduledJobs(t *testing.T) {
@ -227,9 +283,17 @@ func TestRunManualJob(t *testing.T) {
ComposeCmd("run", "--rm", "migrate"),
OutputContains("migration done"),
ServiceState("db", "running")).
Step("a scheduled job without explicit opt-out can be run manually",
ComposeCmd("run", "--rm", "backup"),
OutputContains("backup")).
Step("re-running the same manual job with several env vars must not conflict on spec hash",
ComposeCmd("run", "--rm", "migrate"),
OutputContains("migration done")).
// the engine holds a job to the spec it was registered with: a manual
// job is removed after its run, so another run may carry other options
Step("a manual job can be run again with other options",
ComposeCmd("run", "--rm", "-e", "EXTRA=1", "migrate"),
OutputContains("migration done")).
// a scheduled job is run as up registered it: TestRunAlreadyRegisteredScheduledJob
// and TestRunUnregisteredScheduledJob, and TestRunJobWithoutJobsExtension
// without the extension
Step("manual: false explicitly forbids manual execution",
ComposeCmd("run", "--rm", "rotation").MayFail(),
StderrContains(`job "rotation" is declared with manual: false`))
@ -282,6 +346,15 @@ func TestCreateRefusesJob(t *testing.T) {
ServiceNotCreated("migrate"))
}
// up shares WithServices with create: the same translation must apply there too.
func TestUpRefusesJob(t *testing.T) {
NewScenario(t, "up must refuse a job by name, naming run as the right command").
Step("up fails naming the job",
ComposeCmd("up", "-d", "migrate").MayFail(),
StderrContains(`job "migrate" can only be triggered with "docker compose run"`),
ServiceNotCreated("migrate"))
}
func TestStartRefusesJob(t *testing.T) {
NewScenario(t, "start must refuse a job by name, naming run as the right command").
Step("start fails naming the job",

View file

@ -0,0 +1,16 @@
services:
web:
image: alpine
command: sleep infinity
jobs:
backup:
image: alpine
command: sh -c 'echo backup-ran'
tty: true
depends_on:
- web
ports:
- "80"
triggers:
schedule:
- cron: "0 3 * * *"

View file

@ -0,0 +1,12 @@
jobs:
migrate:
image: alpine
command: sh -c 'echo "migration done"'
triggers:
manual: true
backup:
image: alpine
command: echo backup done
triggers:
schedule:
- cron: "0 3 * * *"

View file

@ -7,6 +7,12 @@ jobs:
migrate:
image: alpine
command: sh -c 'echo "migration done"'
# run is invoked twice below and must build the identical spec hash each time
environment:
A: "1"
B: "2"
C: "3"
D: "4"
triggers:
manual: true
depends_on:

View file

@ -0,0 +1,16 @@
services:
web:
image: alpine
command: sleep infinity
jobs:
backup:
image: alpine
command: sh -c 'echo backup-ran'
tty: true
depends_on:
- web
ports:
- "80"
triggers:
schedule:
- cron: "0 3 * * *"

View file

@ -0,0 +1,10 @@
services:
web:
image: alpine
command: sleep infinity
jobs:
migrate:
image: alpine
command: sh -c 'echo "migration done"'
triggers:
manual: true

View file

@ -176,6 +176,23 @@ type ImageManager interface {
type Runner interface {
// RunOneOffContainer creates a service oneoff container and starts its dependencies
RunOneOffContainer(ctx context.Context, project *types.Project, opts RunOptions) (int, error)
// RunJob triggers a Run of the job on the engine's jobs API, starts its
// dependencies first, streams the logs and returns the Run's exit code
// (124 on timeout, 130 when cancelled). A manual job goes through
// CreateAndRun; a scheduled job is run as `up` or `create` registered it: an
// override in options, or a job the engine does not know, is an error. The job must already be in
// project.Services, the way the CLI materializes it, and options.Service
// must be name. options carries the same CLI overrides RunOneOffContainer
// accepts (User, Command, Entrypoint, WorkingDir, CapAdd/CapDrop,
// Environment, Labels, NoDeps). Name has no effect: the jobs API assigns the
// run container's identity itself. A manual job is registered under the
// project and job name and removed when its run ends, so concurrent runs of
// the same manual job are not supported: the first to end cancels the others.
// Detach is refused, a run is waited for;
// a dry run starts the dependencies and stops there. When the engine cannot
// run jobs, the error wraps ErrJobsNotSupported and nothing was done, so the
// caller can fall back to RunOneOffContainer.
RunJob(ctx context.Context, project *types.Project, name string, options RunOptions) (int, error)
// Exec executes a command in a running service container
Exec(ctx context.Context, projectName string, options RunOptions) (int, error)
// Attach STDIN,STDOUT,STDERR to a running service container

View file

@ -65,6 +65,9 @@ var (
// ErrInvalidOption is returned when an option is set to a value it does
// not accept. See InvalidOptionError.
ErrInvalidOption = errors.New("invalid option")
// ErrJobsNotSupported is returned when a job operation requires an engine with usable jobs support (the jobs API and its extension enabled)
ErrJobsNotSupported = errors.New("jobs are not supported by the engine")
)
// IsNotFoundError returns true if the unwrapped error is ErrNotFound

View file

@ -21,14 +21,18 @@ import (
"encoding/json"
"errors"
"fmt"
"io"
"maps"
"reflect"
"slices"
"strings"
"github.com/compose-spec/compose-go/v2/types"
"github.com/containerd/errdefs"
extensionclient "github.com/moby/extensions/client"
"github.com/moby/moby/api/pkg/stdcopy"
containerType "github.com/moby/moby/api/types/container"
"github.com/moby/moby/client"
"github.com/moby/moby/client/pkg/versions"
"github.com/sirupsen/logrus"
"golang.org/x/sync/errgroup"
@ -238,10 +242,14 @@ func (s *composeService) buildJobSpec(ctx context.Context, project *types.Projec
api.ProjectLabel: project.Name,
api.JobLabel: job.Name,
},
// Successful runs are disposable: drop the container once its
// terminal record is written. Failed ones are kept for postmortem,
// bounded by RunHistoryLimit so repeated failures don't accumulate.
RemoveOnSuccess: true,
// A scheduled job's successful runs are disposable: the engine drops
// the container once its terminal record is written. A manual job's
// are kept, logs included, until RunJob has read them and removed the
// container itself: it is never registered by up, so its spec is free
// to differ, unlike a scheduled job's, which `run` must send exactly as
// up registered it. Failed runs are kept for postmortem, bounded by
// RunHistoryLimit so repeated failures don't accumulate.
RemoveOnSuccess: HasSchedule(job),
RemoveOnFailure: false,
RunHistoryLimit: jobRunHistoryLimit,
}, nil
@ -296,6 +304,13 @@ func ManualTriggerDisabled(job types.JobConfig) bool {
return job.Triggers != nil && job.Triggers.Manual != nil && !*job.Triggers.Manual
}
// ManualTriggerDisabledErr reports that name was declared with
// `manual: false` and so cannot be run manually — the error every caller
// of ManualTriggerDisabled raises on that condition.
func ManualTriggerDisabledErr(name string) error {
return fmt.Errorf("job %q is declared with manual: false, it cannot be run manually", name)
}
// JobAsService materializes a job as a service for the one-off machinery: a
// job is a ContainerSpec+WorkloadSpec, the same layers a service is made of.
// It carries the standard custom labels the loader stamps on every service —
@ -440,10 +455,375 @@ func (s *composeService) registerScheduledJobs(ctx context.Context, project *typ
return eg.Wait()
}
// RunJob triggers a manual-trigger job's Run on the engine, following the
// same dependency-startup path as a one-off service run, then streams the
// Run's container logs and waits for its terminal state. See the RunJob
// doc comment on api.Compose for which options fields have an effect.
func (s *composeService) RunJob(ctx context.Context, project *types.Project, name string, options api.RunOptions) (int, error) {
job, ok := project.AllJobs()[name]
if !ok {
return 0, fmt.Errorf("job %q not found", name)
}
if ManualTriggerDisabled(job) {
return 0, ManualTriggerDisabledErr(name)
}
st, err := s.jobsAvailability(ctx, project.Name)
if err != nil {
return 0, err
}
switch st {
case jobsEngineTooOld:
version, _ := s.RuntimeAPIVersion(ctx) // memoized by jobsAvailability
return 0, fmt.Errorf("%w: this version of the engine (API version %s) predates jobs", api.ErrJobsNotSupported, version)
case jobsExtensionOff:
return 0, fmt.Errorf("%w: the jobs extension is not enabled (start dockerd with %s)", api.ErrJobsNotSupported, jobsv0.EnableFlag)
}
// Past the availability switch so a degraded run, a one-off service, keeps
// honouring -d and dry-run.
if options.Detach {
return 0, errors.New("--detach is not supported for a job: it runs until it is done")
}
if err := refuseScheduledJobOverrides(project, name, job, options); err != nil {
return 0, err
}
if s.dryRun {
return 0, nil // the jobs gRPC dials the real engine, see registerScheduledJobs
}
if options.Name != "" {
logrus.Warnf("--name has no effect on a job: the engine names its run containers itself")
}
// materializeManualJob already put the job into project.Services, so it
// is seen by these project-wide normalization passes exactly like a
// service would be (use_api_socket / models: support).
project, err = s.useAPISocket(project)
if err != nil {
return 0, err
}
if err := s.startDependencies(ctx, project, api.RunOptions{
Service: name,
NoDeps: options.NoDeps,
CreateOptions: options.CreateOptions,
}); err != nil {
return 0, err
}
// The job's own image build (if any) is scoped to just this job, unlike
// startDependencies' unscoped Build above which may also build other
// services the job depends on. RunJob is always called with name ==
// options.Service, so this is the same scoping prepareRun uses.
buildOpts := prepareBuildOptions(options)
if err := s.ensureImagesExists(ctx, project, buildOpts, options.QuietPull, false); err != nil {
return 0, err
}
if err := s.ensureModels(ctx, project, false); err != nil {
return 0, err
}
svc, err := project.GetService(name)
if err != nil {
return 0, err
}
applyRunOptions(project, &svc, options)
// A job has no run-assigned container name: the jobs API owns the run
// container's identity itself. But two independent layers inject
// CLI/terminal-context defaults into the service before RunJob ever
// sees it — prepareRun's own Tty/StdinOpen overrides don't apply here,
// yet cmd/compose/run.go's runOptions.apply still sets
// target.Tty/StdinOpen from the terminal before materializing the job.
// Left in place, that leaks into the spec sent to the engine and
// makes it differ from one run to the next (SpecHash mismatch). Restore
// the job's own declared values (set correctly by JobAsService for both
// materialization paths) rather than the terminal's.
svc.Tty = job.Tty
svc.StdinOpen = job.StdinOpen
svc.ContainerName = ""
observed, err := s.getContainers(ctx, project.Name, oneOffInclude, true)
if err != nil {
return 0, err
}
if err := s.waitDependencies(ctx, project, name, svc.DependsOn, observed); err != nil {
return 0, err
}
// A scheduled job has no spec to send: it runs as `up` registered it.
var spec *jobsv0.JobSpec
// The engine kept the container of a manual job (see buildJobSpec): removing
// it is up to us. An interrupted run leaves it behind, an orphan that
// `down --remove-orphans` sweeps.
keepContainer := false
if !HasSchedule(job) {
spec, err = s.manualJobSpec(ctx, project, svc, job, options.UseNetworkAliases)
if err != nil {
return 0, err
}
keepContainer = !spec.RemoveOnSuccess
}
jc, err := s.jobsClient()
if err != nil {
return 0, err
}
created, err := s.createJobRun(ctx, jc, project, name, job, spec)
if err != nil {
return 0, err
}
// a manual job, which has a spec to send, does not outlive its run
defer s.endJobRun(ctx, jc, name, created.JobID, spec != nil)
containerID, err := runContainerID(ctx, jc, created)
if err != nil {
return 0, err
}
logsDone := make(chan struct{})
go func() {
defer close(logsDone)
if containerID == "" {
return
}
if err := s.streamJobLogs(ctx, containerID, svc.Tty); err != nil && ctx.Err() == nil {
reportJobLogsError(name, err)
}
}()
waited, err := jc.Wait(ctx, &jobsv0.WaitRequest{
JobRef: created.JobID,
RunRef: created.ID,
})
<-logsDone
if err := jobsv0.MapError(err); err != nil {
return 0, err
}
run := waited.Run
if run == nil {
return 1, fmt.Errorf("job %q: Wait returned no run", name)
}
if keepContainer && run.State == jobsv0.RunStateSucceeded {
// ctx may be done: an interrupted run still has its container to remove
s.removeJobRunContainer(context.WithoutCancel(ctx), name, containerID)
}
return jobRunExit(name, run)
}
// endJobRun is what `run` does once it is over, however it ended: stop the run
// if it was interrupted, and remove a manual job from the engine. The job is
// not kept for the next `run`: the engine holds a job to the spec it was
// registered with, and the next `run` may carry other options. Remove keeps the
// run records and the run containers, the failures left for a postmortem.
func (s *composeService) endJobRun(ctx context.Context, jc jobsv0.Jobs, name, jobID string, manual bool) {
cancelInterruptedJobRun(ctx, jc, name, jobID)
if !manual {
return
}
// ctx may be done: an interrupted run still has its job to remove
if err := jc.Remove(context.WithoutCancel(ctx), &jobsv0.RemoveRequest{JobRef: jobID}); err != nil {
if err = jobsv0.MapError(err); !errdefs.IsNotFound(err) {
logrus.Warnf("job %q: could not remove it from the engine: %v", name, err)
}
}
}
// cancelInterruptedJobRun stops the run of a `run` that was interrupted: the
// engine owns the job, and cancelling the context only detaches Wait from it.
// ctx is already done then, so the Cancel runs on a context detached from it.
func cancelInterruptedJobRun(ctx context.Context, jc jobsv0.Jobs, name, jobID string) {
if ctx.Err() == nil {
return
}
if _, err := jc.Cancel(context.WithoutCancel(ctx), &jobsv0.CancelRequest{JobRef: jobID}); err != nil {
logrus.Warnf("could not cancel job %q, it keeps running on the engine: %v", name, jobsv0.MapError(err))
}
}
// runContainerID returns the container backing a just-created run, waiting for
// the engine to create it if it has not yet: callers attach to its logs as soon
// as it exists, since a quick job's container may vanish when it succeeds.
func runContainerID(ctx context.Context, jc jobsv0.Jobs, created *jobsv0.Run) (string, error) {
if created.ContainerID != "" {
return created.ContainerID, nil
}
running, err := jc.Wait(ctx, &jobsv0.WaitRequest{
JobRef: created.JobID,
RunRef: created.ID,
Condition: jobsv0.WaitConditionRunning,
})
if err := jobsv0.MapError(err); err != nil {
return "", err
}
if running.Run == nil {
logrus.Warnf("run %s: the engine reported no container, its output cannot be shown", created.ID)
return "", nil
}
return running.Run.ContainerID, nil
}
// jobRunExit translates a terminal run record into the exit code `run` ends
// with, the way a one-off container's exit status would be.
func jobRunExit(name string, run *jobsv0.Run) (int, error) {
switch run.State {
case jobsv0.RunStateSucceeded:
return 0, nil
case jobsv0.RunStateFailed:
if run.ExitCode != nil {
return int(run.ExitCode.Value), nil
}
return 1, fmt.Errorf("job %q run %s failed: %s", name, run.ID, run.Error)
case jobsv0.RunStateTimedOut:
return 124, fmt.Errorf("job %q timed out", name)
case jobsv0.RunStateCancelled:
return 130, fmt.Errorf("job %q was cancelled", name)
default:
return 1, fmt.Errorf("job %q run %s ended in unexpected state %q", name, run.ID, run.State)
}
}
// manualJobSpec builds the spec a manual job is run with.
func (s *composeService) manualJobSpec(ctx context.Context, project *types.Project, svc types.ServiceConfig, job types.JobConfig, useNetworkAliases bool) (*jobsv0.JobSpec, error) {
// A job may reference a service — volumes_from, or service:-scoped
// network_mode/ipc/pid — exactly like a service run would; the daemon
// knows nothing about compose service names, so these must resolve to
// container names before the spec reaches it.
if err := resolveJobServiceReferences(project, &svc); err != nil {
return nil, err
}
// --no-deps narrowed svc.DependsOn to what this run waits for: the spec
// carries the declared ones, the same on every run.
svc.DependsOn = job.DependsOn
return s.buildJobSpec(ctx, project, svc, job, useNetworkAliases)
}
// refuseScheduledJobOverrides is an error when run asks to change a scheduled job.
func refuseScheduledJobOverrides(project *types.Project, name string, job types.JobConfig, options api.RunOptions) error {
svc, ok := project.Services[name]
if !ok || !HasSchedule(job) {
return nil
}
overrides := scheduledJobOverrides(options, svc, job)
if len(overrides) == 0 {
return nil
}
return fmt.Errorf("scheduled job %q runs as registered by up: it takes no %s, "+
"change the compose file and run up again", name, strings.Join(overrides, ", "))
}
// scheduledJobOverrides names what a `run` asks to change in a scheduled job: it
// runs as `up` registered it. The options of the CLI that the cmd layer applies
// to the service itself, -v and -p, show as a difference from the job as declared.
func scheduledJobOverrides(options api.RunOptions, svc types.ServiceConfig, job types.JobConfig) []string {
var overrides []string
for _, o := range []struct {
name string
set bool
}{
{"a command", len(options.Command) > 0},
{"--entrypoint", len(options.Entrypoint) > 0},
{"--user", options.User != ""},
{"--workdir", options.WorkingDir != ""},
{"--env/--env-from-file", len(options.Environment) > 0},
{"--cap-add", len(options.CapAdd) > 0},
{"--cap-drop", len(options.CapDrop) > 0},
{"--label", len(options.Labels) > 0},
{"--volume", !reflect.DeepEqual(svc.Volumes, job.Volumes)},
{"--publish", !reflect.DeepEqual(svc.Ports, job.Ports)},
} {
if o.set {
overrides = append(overrides, o.name)
}
}
return overrides
}
// createJobRun starts name's Run on the engine, routed on the job's
// declared trigger rather than on how compose happens to invoke it: the
// engine's CreateAndRun refuses a schedule-trigger spec outright
// ("create-and-run serves manual jobs only"), because registering a cron
// must never imply an immediate run. A manual-trigger job (the opt-out
// default included) is still created and run atomically via CreateAndRun.
// A scheduled job is run as `up` registered it, spec is nil: sending one to
// Create would arm the schedule of a job `up` never registered, and a spec
// differing from the registered one is refused. It is Run with Reschedule:
// false, so the manual fire adds to the cron cadence instead of replacing its
// next occurrence.
func (s *composeService) createJobRun(ctx context.Context, jc jobsv0.Jobs, project *types.Project, name string, job types.JobConfig, spec *jobsv0.JobSpec) (*jobsv0.Run, error) {
engineName := engineJobName(project, name)
if !HasSchedule(job) {
reply, err := jc.CreateAndRun(ctx, &jobsv0.CreateAndRunRequest{
Name: engineName,
Spec: spec,
})
if err := mapAlreadyExists(err, name, "run"); err != nil {
return nil, err
}
if reply.Run == nil {
return nil, fmt.Errorf("job %q: engine returned no run", name)
}
return reply.Run, nil
}
reply, err := jc.Run(ctx, &jobsv0.RunRequest{JobRef: engineName, Reschedule: false})
if err := jobsv0.MapError(err); err != nil {
if errdefs.IsNotFound(err) {
return nil, fmt.Errorf("job %q is not registered with the engine: run `docker compose up` (or `create`) first", name)
}
return nil, err
}
if reply.Run == nil {
return nil, fmt.Errorf("job %q: engine returned no run", name)
}
return reply.Run, nil
}
// reportJobLogsError tells why a job's logs could not be shown in full. A
// container gone before its logs were read is the engine's RemoveOnSuccess at
// work on a job that finished too fast: the run succeeded, its output is lost.
func reportJobLogsError(name string, err error) {
if errdefs.IsNotFound(err) {
logrus.Warnf("job %q: its logs are gone, the engine removed the run container before they could be read", name)
return
}
logrus.Debugf("job %q: log stream ended: %v", name, err)
}
// removeJobRunContainer removes the container of a manual job's successful
// run, which RunJob asked the engine to keep so the logs could be read.
func (s *composeService) removeJobRunContainer(ctx context.Context, name, containerID string) {
if _, err := s.apiClient().ContainerRemove(ctx, containerID, client.ContainerRemoveOptions{RemoveVolumes: true}); err != nil && !errdefs.IsNotFound(err) {
logrus.Warnf("job %q: failed to remove its run container %s: %v", name, containerID, err)
}
}
// streamJobLogs follows a job Run's container logs from the start, exactly
// like `docker logs -f`, until the container stops producing output. tty
// must match the container's own Tty setting: with a tty allocated, the
// daemon returns a single raw stream instead of the stdout/stderr-framed
// stream stdcopy expects (see doLogContainer in logs.go for the same split).
func (s *composeService) streamJobLogs(ctx context.Context, containerID string, tty bool) error {
r, err := s.apiClient().ContainerLogs(ctx, containerID, client.ContainerLogsOptions{
ShowStdout: true,
ShowStderr: true,
Follow: true,
})
if err != nil {
return err
}
defer r.Close() //nolint:errcheck
if tty {
_, err = io.Copy(s.stdout(), r)
} else {
_, err = stdcopy.StdCopy(s.stdout(), s.stderr(), r)
}
return err
}
// ensureJobsDown removes the project's jobs from the engine. Run history is
// kept by default (RunsRemoval left empty); each removal tolerates the job
// already being gone, matching removeResource's NotFound handling.
func (s *composeService) ensureJobsDown(ctx context.Context, project *types.Project) []downOp {
// a manual job does not outlive its run, unless `run` was killed before it
// could remove it: every job goes, a missing one is tolerated
names := sortedJobNames(project.Jobs, nil)
if len(names) == 0 {
return nil

View file

@ -27,6 +27,7 @@ import (
"testing"
"github.com/compose-spec/compose-go/v2/types"
"github.com/containerd/errdefs"
"github.com/moby/moby/client"
"github.com/sirupsen/logrus"
"go.uber.org/mock/gomock"
@ -129,6 +130,16 @@ func TestJobChangedErr(t *testing.T) {
`job "migrate" has changed: run `+"`docker compose down`"+` to remove it, then `+"`run`"+` again`)
}
func TestManualTriggerDisabledErr(t *testing.T) {
assert.Error(t, ManualTriggerDisabledErr("rotation"),
`job "rotation" is declared with manual: false, it cannot be run manually`)
}
// scopedProjectForJob is what lets registerScheduledJobs run a scheduled
// job through the same useAPISocket/ensureImagesExists/ensureModels passes
// a manually-run job gets for free from materializeManualJob — without the
// job ever joining the real project.Services the reconciliation loop
// iterates over.
func TestScopedProjectForJob(t *testing.T) {
project := &types.Project{
Name: "myproject",
@ -200,20 +211,32 @@ func TestScopedProjectForJob(t *testing.T) {
})
}
// fakeJobsClient is a minimal jobsv0.Jobs double: only the methods a test
// exercises are implemented, every other one is left to the embedded nil
// interface — calling one would panic, which is exactly the loud failure a
// test relying on it deserves.
// fakeJobsClient is a minimal jobsv0.Jobs double for createJobRun's routing:
// only Create/Run/CreateAndRun are ever exercised by RunJob, so every other
// method is left to the embedded nil interface — calling one would panic,
// which is exactly the loud failure a test relying on it deserves.
type fakeJobsClient struct {
jobsv0.Jobs
mu sync.Mutex // registerScheduledJobs calls Create concurrently
createCalls []*jobsv0.CreateRequest
createErr error
listCalls []*jobsv0.ListRequest
listReply *jobsv0.ListReply
listErr error
removeCalls []*jobsv0.RemoveRequest
mu sync.Mutex // registerScheduledJobs calls Create concurrently
createCalls []*jobsv0.CreateRequest
createErr error
createAndRunCalls []*jobsv0.CreateAndRunRequest
createAndRunReply *jobsv0.CreateAndRunReply
createAndRunErr error
runCalls []*jobsv0.RunRequest
runReply *jobsv0.RunReply
runErr error
listCalls []*jobsv0.ListRequest
listReply *jobsv0.ListReply
listErr error
waitCalls []*jobsv0.WaitRequest
waitReply *jobsv0.WaitReply
waitErr error
removeCalls []*jobsv0.RemoveRequest
cancelCalls []*jobsv0.CancelRequest
cancelErr error
removeErr error
}
func (f *fakeJobsClient) Create(_ context.Context, req *jobsv0.CreateRequest) (*jobsv0.CreateReply, error) {
@ -226,11 +249,31 @@ func (f *fakeJobsClient) Create(_ context.Context, req *jobsv0.CreateRequest) (*
return &jobsv0.CreateReply{Job: &jobsv0.Job{Name: req.Name}}, nil
}
func (f *fakeJobsClient) CreateAndRun(_ context.Context, req *jobsv0.CreateAndRunRequest) (*jobsv0.CreateAndRunReply, error) {
f.createAndRunCalls = append(f.createAndRunCalls, req)
return f.createAndRunReply, f.createAndRunErr
}
func (f *fakeJobsClient) Run(_ context.Context, req *jobsv0.RunRequest) (*jobsv0.RunReply, error) {
f.runCalls = append(f.runCalls, req)
return f.runReply, f.runErr
}
func (f *fakeJobsClient) Remove(_ context.Context, req *jobsv0.RemoveRequest) error {
f.mu.Lock()
defer f.mu.Unlock()
f.removeCalls = append(f.removeCalls, req)
return nil
return f.removeErr
}
func (f *fakeJobsClient) Cancel(_ context.Context, req *jobsv0.CancelRequest) (*jobsv0.CancelReply, error) {
f.cancelCalls = append(f.cancelCalls, req)
return &jobsv0.CancelReply{}, f.cancelErr
}
func (f *fakeJobsClient) Wait(_ context.Context, req *jobsv0.WaitRequest) (*jobsv0.WaitReply, error) {
f.waitCalls = append(f.waitCalls, req)
return f.waitReply, f.waitErr
}
func (f *fakeJobsClient) List(_ context.Context, req *jobsv0.ListRequest) (*jobsv0.ListReply, error) {
@ -244,6 +287,58 @@ func (f *fakeJobsClient) List(_ context.Context, req *jobsv0.ListRequest) (*jobs
return f.listReply, nil
}
// createJobRun routes on the job's declared trigger, not on how it happens
// to be invoked: the engine's CreateAndRun refuses a schedule-trigger spec
// outright ("create-and-run serves manual jobs only"), because registering
// a cron must never imply an immediate run. A manual-trigger job (the
// opt-out default included) still goes through CreateAndRun unchanged.
func TestCreateJobRun(t *testing.T) {
s := &composeService{}
project := &types.Project{Name: "myproject"}
spec := &jobsv0.JobSpec{}
t.Run("a manual-trigger job uses CreateAndRun", func(t *testing.T) {
yes := true
job := types.JobConfig{Name: "migrate", Triggers: &types.TriggerConfig{Manual: &yes}}
fake := &fakeJobsClient{createAndRunReply: &jobsv0.CreateAndRunReply{Run: &jobsv0.Run{ID: "run-1", JobID: "job-1"}}}
run, err := s.createJobRun(t.Context(), fake, project, "migrate", job, spec)
assert.NilError(t, err)
assert.Equal(t, run.ID, "run-1")
assert.Equal(t, len(fake.createAndRunCalls), 1)
assert.Equal(t, fake.createAndRunCalls[0].Name, "myproject.migrate")
assert.Equal(t, len(fake.createCalls), 0, "a manual job must never call Create")
assert.Equal(t, len(fake.runCalls), 0, "a manual job must never call the schedule-job Run path")
})
t.Run("a scheduled job is Run as registered, never Created or CreateAndRun", func(t *testing.T) {
job := types.JobConfig{Name: "backup", Triggers: &types.TriggerConfig{
Schedule: []types.ScheduleConfig{{Cron: "0 3 * * *"}},
}}
fake := &fakeJobsClient{runReply: &jobsv0.RunReply{Run: &jobsv0.Run{ID: "run-2", JobID: "job-2"}}}
run, err := s.createJobRun(t.Context(), fake, project, "backup", job, nil)
assert.NilError(t, err)
assert.Equal(t, run.ID, "run-2")
assert.Equal(t, len(fake.runCalls), 1)
assert.Equal(t, fake.runCalls[0].JobRef, "myproject.backup")
assert.Assert(t, !fake.runCalls[0].Reschedule, "a manual fire must add to the cron cadence, not replace its next occurrence")
assert.Equal(t, len(fake.createCalls)+len(fake.createAndRunCalls), 0, "Create would arm the schedule of a job up never registered")
})
t.Run("a scheduled job the engine does not know says up comes first", func(t *testing.T) {
job := types.JobConfig{Name: "backup", Triggers: &types.TriggerConfig{
Schedule: []types.ScheduleConfig{{Cron: "0 3 * * *"}},
}}
fake := &fakeJobsClient{runErr: status.Error(codes.NotFound, "no such job")}
_, err := s.createJobRun(t.Context(), fake, project, "backup", job, nil)
assert.ErrorContains(t, err, `job "backup" is not registered with the engine`)
assert.ErrorContains(t, err, "docker compose up")
assert.Equal(t, len(fake.createCalls), 0)
})
}
// TestBuildJobSpecIsDeterministic guards against the spec hash churning
// across invocations when a job declares several environment variables:
// buildJobSpec marshals the container spec as JSON and sends it to the
@ -465,6 +560,144 @@ func TestCreateHandlesOrphanJobs(t *testing.T) {
})
}
// A scheduled job runs as `up` registered it: what `run` was asked to change in
// it, on the command line, would not reach the engine, so it is refused rather
// than ignored. The cmd layer applies -v and -p to the service itself.
func TestScheduledJobOverrides(t *testing.T) {
job := types.JobConfig{
Name: "backup",
Triggers: &types.TriggerConfig{Schedule: []types.ScheduleConfig{{Cron: "0 3 * * *"}}},
ContainerSpec: types.ContainerSpec{Image: "alpine", Volumes: []types.ServiceVolumeConfig{{Type: types.VolumeTypeVolume, Target: "/data"}}},
WorkloadSpec: types.WorkloadSpec{Ports: []types.ServicePortConfig{{Target: 80}}},
}
project := &types.Project{Name: "prj"}
declared := JobAsService(project, "backup", job)
assert.Equal(t, len(scheduledJobOverrides(api.RunOptions{}, declared, job)), 0, "a run with no option is the job as registered")
got := scheduledJobOverrides(api.RunOptions{
Command: []string{"sh"},
Entrypoint: []string{"/bin/sh"},
User: "root",
WorkingDir: "/tmp",
Environment: []string{"X=1"},
CapAdd: []string{"NET_ADMIN"},
CapDrop: []string{"ALL"},
Labels: types.Labels{"a": "b"},
}, declared, job)
assert.DeepEqual(t, got, []string{"a command", "--entrypoint", "--user", "--workdir", "--env/--env-from-file", "--cap-add", "--cap-drop", "--label"})
changed := declared
changed.Volumes = append(slices.Clone(declared.Volumes), types.ServiceVolumeConfig{Type: types.VolumeTypeBind, Source: "/a", Target: "/b"})
changed.Ports = []types.ServicePortConfig{{Target: 443}}
assert.DeepEqual(t, scheduledJobOverrides(api.RunOptions{}, changed, job), []string{"--volume", "--publish"})
}
func TestRunJobRefusesOverridesOfAScheduledJob(t *testing.T) {
project := scheduledJobsProject()
project.Services["backup"] = JobAsService(project, "backup", project.Jobs["backup"])
fake := &fakeJobsClient{}
_, err := newJobsTestService(t, apiVersionJobs, fake).RunJob(t.Context(), project, "backup",
api.RunOptions{Service: "backup", Environment: []string{"X=1"}, User: "root"})
assert.ErrorContains(t, err, `scheduled job "backup" runs as registered by up`)
assert.ErrorContains(t, err, "--user, --env")
assert.Equal(t, len(fake.createCalls)+len(fake.createAndRunCalls)+len(fake.runCalls), 0)
}
// A manual job does not outlive its run: removed from the engine, its spec is
// not held against the next `run`, which may carry other options. The run
// containers stay, Remove keeps the history.
func TestEndJobRun(t *testing.T) {
s := &composeService{}
t.Run("a manual job is removed once its run is over", func(t *testing.T) {
fake := &fakeJobsClient{}
s.endJobRun(t.Context(), fake, "migrate", "job-1", true)
assert.Equal(t, len(fake.removeCalls), 1)
assert.Equal(t, fake.removeCalls[0].JobRef, "job-1")
assert.Equal(t, len(fake.cancelCalls), 0)
})
t.Run("an interrupted run is cancelled, then its job removed", func(t *testing.T) {
fake := &fakeJobsClient{}
ctx, interrupt := context.WithCancel(t.Context())
interrupt()
s.endJobRun(ctx, fake, "migrate", "job-1", true)
assert.Equal(t, len(fake.cancelCalls), 1)
assert.Equal(t, len(fake.removeCalls), 1, "the context is done, the removal still goes through")
})
t.Run("a scheduled job stays registered", func(t *testing.T) {
fake := &fakeJobsClient{}
s.endJobRun(t.Context(), fake, "backup", "job-2", false)
assert.Equal(t, len(fake.removeCalls), 0)
})
t.Run("a job already gone is not worth a word, a failure is", func(t *testing.T) {
out := captureWarnings(t)
s.endJobRun(t.Context(), &fakeJobsClient{removeErr: status.Error(codes.NotFound, "no such job")}, "migrate", "job-1", true)
assert.Equal(t, out.String(), "")
s.endJobRun(t.Context(), &fakeJobsClient{removeErr: errors.New("engine unreachable")}, "migrate", "job-1", true)
assert.Assert(t, strings.Contains(out.String(), "engine unreachable"), out.String())
})
}
// Interrupting `run` only detaches its Wait: the engine keeps running the job
// unless it is told to stop, so an interrupted run cancels its run, even though
// the context that carried the interruption is already done.
func TestCancelInterruptedJobRun(t *testing.T) {
t.Run("a run that ended on its own is left alone", func(t *testing.T) {
fake := &fakeJobsClient{}
cancelInterruptedJobRun(t.Context(), fake, "migrate", "job-1")
assert.Equal(t, len(fake.cancelCalls), 0)
})
t.Run("an interrupted run is cancelled", func(t *testing.T) {
fake := &fakeJobsClient{}
ctx, interrupt := context.WithCancel(t.Context())
interrupt()
cancelInterruptedJobRun(ctx, fake, "migrate", "job-1")
assert.Equal(t, len(fake.cancelCalls), 1)
assert.Equal(t, fake.cancelCalls[0].JobRef, "job-1")
})
t.Run("a failed cancel is reported, the job keeps running", func(t *testing.T) {
warnings := captureWarnings(t)
fake := &fakeJobsClient{cancelErr: errors.New("engine unreachable")}
ctx, interrupt := context.WithCancel(t.Context())
interrupt()
cancelInterruptedJobRun(ctx, fake, "migrate", "job-1")
assert.Assert(t, strings.Contains(warnings.String(), "engine unreachable"), warnings.String())
})
}
// The engine drops a scheduled job's container as soon as a run succeeds; a
// manual job's is kept so RunJob can read its logs. The policy is a function of
// the job alone: `run` must send a scheduled job exactly the spec up registered.
func TestBuildJobSpecRemoveOnSuccess(t *testing.T) {
s, _ := newPreStartTestService(t)
project := &types.Project{Name: "myproject"}
svc := types.ServiceConfig{Name: "backup", ContainerSpec: types.ContainerSpec{Image: "alpine"}}
manual := true
for name, tc := range map[string]struct {
job types.JobConfig
want bool
}{
"manual": {job: types.JobConfig{Name: "backup", Triggers: &types.TriggerConfig{Manual: &manual}}, want: false},
"scheduled": {job: types.JobConfig{Name: "backup", Triggers: &types.TriggerConfig{Schedule: []types.ScheduleConfig{{Cron: "0 3 * * *"}}}}, want: true},
} {
t.Run(name, func(t *testing.T) {
spec, err := s.buildJobSpec(t.Context(), project, svc, tc.job, false)
assert.NilError(t, err)
assert.Equal(t, spec.RemoveOnSuccess, tc.want)
})
}
}
// scheduledJobsProject declares one scheduled and one manual job next to a
// service, the shape the degraded-mode tests below run against.
func scheduledJobsProject() *types.Project {
@ -638,6 +871,37 @@ func TestScheduledJobsRefusedWithoutJobsEngine(t *testing.T) {
}
}
// RunJob reports the missing engine support with a sentinel before doing any
// work, so the CLI can fall back to running the job like a one-off service:
// the error says why. An extension that is enabled but not ready is not
// missing support, it is a failure: no sentinel, no fallback.
func TestRunJobWithoutJobsEngine(t *testing.T) {
run := func(t *testing.T, version string, listErr error) error {
t.Helper()
tested := newJobsTestService(t, version, &fakeJobsClient{listErr: listErr})
_, err := tested.RunJob(t.Context(), scheduledJobsProject(), "migrate", api.RunOptions{Service: "migrate"})
return err
}
t.Run("API predates jobs", func(t *testing.T) {
err := run(t, noJobsEngine, nil)
assert.ErrorIs(t, err, api.ErrJobsNotSupported)
assert.ErrorContains(t, err, "API version "+noJobsEngine)
})
t.Run("extension off", func(t *testing.T) {
err := run(t, apiVersionJobs, jobsExtensionOffErr)
assert.ErrorIs(t, err, api.ErrJobsNotSupported)
assert.ErrorContains(t, err, "--extension-enable org.mobyproject.jobs.v0")
})
t.Run("extension not ready", func(t *testing.T) {
err := run(t, apiVersionJobs, jobsExtensionNotReadyErr)
assert.ErrorIs(t, err, errJobsExtensionNotReady)
assert.Assert(t, !errors.Is(err, api.ErrJobsNotSupported), "no sentinel: the CLI must not degrade to a one-off")
})
}
// captureWarnings captures what the code under test tells the user.
func captureWarnings(t *testing.T) *bytes.Buffer {
t.Helper()
@ -647,6 +911,38 @@ func captureWarnings(t *testing.T) *bytes.Buffer {
return &buf
}
// A job runs until it is done and its run is not simulated by a dry run: the
// jobs gRPC dials the real engine, bypassing the dry-run client.
func TestRunJobDetachAndDryRun(t *testing.T) {
options := api.RunOptions{Service: "migrate"}
t.Run("a job cannot be detached", func(t *testing.T) {
fake := &fakeJobsClient{}
options := options
options.Detach = true
_, err := newJobsTestService(t, apiVersionJobs, fake).RunJob(t.Context(), scheduledJobsProject(), "migrate", options)
assert.ErrorContains(t, err, "--detach is not supported for a job")
assert.Equal(t, len(fake.createAndRunCalls), 0)
})
t.Run("a degraded run keeps honouring detach: it is a one-off service", func(t *testing.T) {
options := options
options.Detach = true
_, err := newJobsTestService(t, noJobsEngine, &fakeJobsClient{}).RunJob(t.Context(), scheduledJobsProject(), "migrate", options)
assert.ErrorIs(t, err, api.ErrJobsNotSupported)
})
t.Run("a dry run starts nothing on the real engine", func(t *testing.T) {
fake := &fakeJobsClient{}
tested := newJobsTestService(t, apiVersionJobs, fake)
tested.dryRun = true
code, err := tested.RunJob(t.Context(), scheduledJobsProject(), "migrate", options)
assert.NilError(t, err)
assert.Equal(t, code, 0)
assert.Equal(t, len(fake.createAndRunCalls)+len(fake.createCalls)+len(fake.runCalls), 0)
})
}
// Down only talks to the engine's jobs registry when the engine has one.
func TestDownJobsWithoutJobsEngine(t *testing.T) {
project := scheduledJobsProject()
@ -673,11 +969,13 @@ func TestDownJobsWithoutJobsEngine(t *testing.T) {
assert.Assert(t, strings.Contains(out.String(), jobsExtensionNotReady), out.String())
})
t.Run("with the extension every declared job is removed from the engine", func(t *testing.T) {
// a manual job left behind by a `run` that was killed before it could remove
// it goes too, with the others
t.Run("with the extension the jobs are removed from the engine", func(t *testing.T) {
fake := &fakeJobsClient{}
tested := newJobsTestService(t, apiVersionJobs, fake)
ops := tested.ensureJobsDown(t.Context(), project)
assert.Equal(t, len(ops), len(project.Jobs))
assert.Equal(t, len(ops), 3)
for _, op := range ops {
assert.NilError(t, op())
}
@ -689,6 +987,17 @@ func TestDownJobsWithoutJobsEngine(t *testing.T) {
assert.DeepEqual(t, refs, []string{"prj.backup", "prj.migrate", "prj.sync"})
})
// without a compose file the jobs come from the engine's registry, with no
// trigger to tell: all of them go
t.Run("a job known by its name only is removed", func(t *testing.T) {
fake := &fakeJobsClient{}
tested := newJobsTestService(t, apiVersionJobs, fake)
ops := tested.ensureJobsDown(t.Context(), &types.Project{Name: "prj", Jobs: types.Jobs{"old": {Name: "old"}}})
assert.Equal(t, len(ops), 1)
assert.NilError(t, ops[0]())
assert.Equal(t, fake.removeCalls[0].JobRef, "prj.old")
})
t.Run("a dry run removes nothing from the real engine", func(t *testing.T) {
fake := &fakeJobsClient{}
tested := newJobsTestService(t, apiVersionJobs, fake)
@ -734,6 +1043,107 @@ func TestActualJobs(t *testing.T) {
})
}
// The engine removes a quick job's container, logs included, as soon as it
// succeeds: losing them must be said, anything else going wrong while
// following them stays a debug detail.
func TestReportJobLogsError(t *testing.T) {
t.Run("a container gone before its logs were read is a warning", func(t *testing.T) {
out := captureWarnings(t)
reportJobLogsError("backup", errdefs.ErrNotFound.WithMessage("No such container: abc"))
assert.Assert(t, strings.Contains(out.String(), "level=warning"), out.String())
assert.Assert(t, strings.Contains(out.String(), "its logs are gone"), out.String())
})
t.Run("any other error stays silent", func(t *testing.T) {
out := captureWarnings(t)
reportJobLogsError("backup", errors.New("stream reset"))
assert.Equal(t, out.String(), "")
})
}
// Failing to remove a manual job's kept container is worth a warning, not a
// failed run.
func TestRemoveJobRunContainer(t *testing.T) {
removal := client.ContainerRemoveOptions{RemoveVolumes: true}
t.Run("removes the run container", func(t *testing.T) {
mockAPI, tested := newTestComposeService(t, gomock.NewController(t), apiVersionJobs)
mockAPI.EXPECT().ContainerRemove(gomock.Any(), "abc", removal).Return(client.ContainerRemoveResult{}, nil)
tested.removeJobRunContainer(t.Context(), "backup", "abc")
})
t.Run("a failed removal is a warning", func(t *testing.T) {
out := captureWarnings(t)
mockAPI, tested := newTestComposeService(t, gomock.NewController(t), apiVersionJobs)
mockAPI.EXPECT().ContainerRemove(gomock.Any(), "abc", removal).Return(client.ContainerRemoveResult{}, errors.New("boom"))
tested.removeJobRunContainer(t.Context(), "backup", "abc")
assert.Assert(t, strings.Contains(out.String(), "level=warning"), out.String())
assert.Assert(t, strings.Contains(out.String(), "abc"), out.String())
})
}
func TestRunContainerID(t *testing.T) {
t.Run("a container already created is used without waiting", func(t *testing.T) {
fake := &fakeJobsClient{}
id, err := runContainerID(t.Context(), fake, &jobsv0.Run{ID: "r1", ContainerID: "abc"})
assert.NilError(t, err)
assert.Equal(t, id, "abc")
assert.Equal(t, len(fake.waitCalls), 0)
})
t.Run("a container not created yet is awaited by waiting for the run to leave pending", func(t *testing.T) {
fake := &fakeJobsClient{waitReply: &jobsv0.WaitReply{Run: &jobsv0.Run{ContainerID: "def"}}}
id, err := runContainerID(t.Context(), fake, &jobsv0.Run{ID: "r1", JobID: "j1"})
assert.NilError(t, err)
assert.Equal(t, id, "def")
assert.Equal(t, len(fake.waitCalls), 1)
assert.Equal(t, fake.waitCalls[0].Condition, jobsv0.WaitConditionRunning)
assert.Equal(t, fake.waitCalls[0].RunRef, "r1")
})
t.Run("a run with no container says why its output is missing", func(t *testing.T) {
out := captureWarnings(t)
fake := &fakeJobsClient{waitReply: &jobsv0.WaitReply{}}
id, err := runContainerID(t.Context(), fake, &jobsv0.Run{ID: "r1", JobID: "j1"})
assert.NilError(t, err)
assert.Equal(t, id, "")
assert.Assert(t, strings.Contains(out.String(), "r1"), out.String())
assert.Assert(t, strings.Contains(out.String(), "no container"), out.String())
})
t.Run("a wait failure is returned", func(t *testing.T) {
fake := &fakeJobsClient{waitErr: status.Error(codes.NotFound, "no such run")}
_, err := runContainerID(t.Context(), fake, &jobsv0.Run{ID: "r1"})
assert.Assert(t, errdefs.IsNotFound(err), err)
})
}
// run ends with the exit code a one-off container's exit status would give.
func TestJobRunExit(t *testing.T) {
for name, tc := range map[string]struct {
run *jobsv0.Run
code int
wantErr string
}{
"succeeded": {run: &jobsv0.Run{State: jobsv0.RunStateSucceeded}},
"failed with an exit code": {run: &jobsv0.Run{State: jobsv0.RunStateFailed, ExitCode: &jobsv0.ExitCode{Value: 3}}, code: 3},
"failed without exit code": {run: &jobsv0.Run{ID: "r1", State: jobsv0.RunStateFailed, Error: "oom"}, code: 1, wantErr: `job "backup" run r1 failed: oom`},
"timed out": {run: &jobsv0.Run{State: jobsv0.RunStateTimedOut}, code: 124, wantErr: `job "backup" timed out`},
"cancelled": {run: &jobsv0.Run{State: jobsv0.RunStateCancelled}, code: 130, wantErr: `job "backup" was cancelled`},
"unexpected state": {run: &jobsv0.Run{ID: "r2", State: "bogus"}, code: 1, wantErr: `job "backup" run r2 ended in unexpected state "bogus"`},
} {
t.Run(name, func(t *testing.T) {
code, err := jobRunExit("backup", tc.run)
assert.Equal(t, code, tc.code)
if tc.wantErr == "" {
assert.NilError(t, err)
} else {
assert.Error(t, err, tc.wantErr)
}
})
}
}
func strPtr(s string) *string { return &s }
// A job names the container of the service it shares with, not its ID.

View file

@ -151,6 +151,9 @@ func (s *composeService) doPrepareRun(ctx context.Context, project *types.Projec
return prepareRunResult{}, err
}
service.Tty = options.Tty
service.StdinOpen = options.Interactive
service.ContainerName = options.Name
applyRunOptions(project, &service, options)
if err := s.stdin().CheckTty(options.Interactive, service.Tty); err != nil {
@ -241,11 +244,18 @@ func prepareBuildOptions(options api.RunOptions) *api.BuildOptions {
return &buildOptionsCopy
}
// applyRunOptions applies the CLI overrides shared by a one-off service run
// and a job run — Command, User, CapAdd/CapDrop, WorkingDir, Entrypoint,
// Environment, Labels, exactly the set RunJob's own doc comment on
// api.Compose documents as supported. Tty/StdinOpen/ContainerName are
// deliberately not here: prepareRun (RunOneOffContainer's caller) sets them
// itself for its own container-naming/attach needs, and a job has neither
// (no interactive attach, and the jobs API assigns the run container's
// identity itself) — RunJob restores the job's own declared values right
// after calling this, since CLI-layer code upstream of both (cmd/compose's
// runOptions.apply) already stamped the service with terminal-context
// defaults meant for a one-off container, not a job.
func applyRunOptions(project *types.Project, service *types.ServiceConfig, options api.RunOptions) {
service.Tty = options.Tty
service.StdinOpen = options.Interactive
service.ContainerName = options.Name
if len(options.Command) > 0 {
service.Command = options.Command
}

View file

@ -370,6 +370,21 @@ func (mr *MockComposeMockRecorder) Restart(ctx, projectName, options any) *gomoc
return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Restart", reflect.TypeOf((*MockCompose)(nil).Restart), ctx, projectName, options)
}
// RunJob mocks base method.
func (m *MockCompose) RunJob(ctx context.Context, project *types.Project, name string, options api.RunOptions) (int, error) {
m.ctrl.T.Helper()
ret := m.ctrl.Call(m, "RunJob", ctx, project, name, options)
ret0, _ := ret[0].(int)
ret1, _ := ret[1].(error)
return ret0, ret1
}
// RunJob indicates an expected call of RunJob.
func (mr *MockComposeMockRecorder) RunJob(ctx, project, name, options any) *gomock.Call {
mr.mock.ctrl.T.Helper()
return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "RunJob", reflect.TypeOf((*MockCompose)(nil).RunJob), ctx, project, name, options)
}
// RunOneOffContainer mocks base method.
func (m *MockCompose) RunOneOffContainer(ctx context.Context, project *types.Project, opts api.RunOptions) (int, error) {
m.ctrl.T.Helper()
@ -1050,6 +1065,21 @@ func (mr *MockRunnerMockRecorder) Export(ctx, projectName, options any) *gomock.
return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Export", reflect.TypeOf((*MockRunner)(nil).Export), ctx, projectName, options)
}
// RunJob mocks base method.
func (m *MockRunner) RunJob(ctx context.Context, project *types.Project, name string, options api.RunOptions) (int, error) {
m.ctrl.T.Helper()
ret := m.ctrl.Call(m, "RunJob", ctx, project, name, options)
ret0, _ := ret[0].(int)
ret1, _ := ret[1].(error)
return ret0, ret1
}
// RunJob indicates an expected call of RunJob.
func (mr *MockRunnerMockRecorder) RunJob(ctx, project, name, options any) *gomock.Call {
mr.mock.ctrl.T.Helper()
return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "RunJob", reflect.TypeOf((*MockRunner)(nil).RunJob), ctx, project, name, options)
}
// RunOneOffContainer mocks base method.
func (m *MockRunner) RunOneOffContainer(ctx context.Context, project *types.Project, opts api.RunOptions) (int, error) {
m.ctrl.T.Helper()