docker.pull.execute

Pull a container image to the host.

Usage

task := plan.TaskFunc("pull-image",
    func(ctx context.Context, c *client.Client) (*orchestrator.Result, error) {
        resp, err := c.Docker.Pull(ctx, "_any", gen.DockerPullRequest{
            Image: "nginx:alpine",
        })
        if err != nil {
            return nil, err
        }
        r := resp.Data.Results[0]
        return &orchestrator.Result{
            Changed: true,
            Data:    map[string]any{"image_id": r.ImageID, "tag": r.Tag},
        }, nil
    },
)

Parameters

Param	Type	Required	Description
image	string	Yes	Image reference to pull

Target

Accepts any valid target: _any, _all, a hostname, or a label selector (key:value).

Idempotency

Not idempotent. Always pulls the image. Pull is asynchronous through the job system -- the API returns a job ID immediately and the agent pulls in the background.

Permissions

Requires docker:write permission.

Example

See examples/sdk/orchestrator/features/container-targeting.go for a complete working example.