Docker — image/pull

Private registry authentication: For private registries, configure Docker daemon credentials on the host — the Docker node uses the host's credential store (~/.docker/config.json or the configured credential helper). The node itself does not accept registry username/password fields.

When to Use

CI/CD pre-pull: Pull the updated application image onto the target Docker host before calling container/create in a deployment workflow, ensuring the daemon does not need to pull at container start time.
Security scanning: Pull a specific image version to a scanning host so a vulnerability scanner job container can mount it for analysis.
Scheduled image refresh: Run a nightly workflow that pulls :latest base images on all hosts, keeping local caches current without manual intervention.
Multi-host cache warming: Pull the same versioned image across multiple Docker hosts in parallel before a rolling deployment to minimise per-host pull latency.
Digest-pinned immutable deploy: Pull an image specified by exact digest (e.g., nginx@sha256:593dac…) to guarantee no tag-mutable substitution occurs.

Configuration

Connection

Field	Type	Default	Description
`dockerHost`	string	`unix:///var/run/docker.sock`	Docker daemon socket path or TCP endpoint.
`connectionType`	string	`unixsocket`	One of: `unixsocket`, `tcp`, `tcptls`.
`tlsCertPath`	string	—	TLS certificate directory. Required for `tcptls`. optional
`timeoutSeconds`	int	300	Increase for large images on slow networks. optional

Operation Fields

Field	Type	Badge	Description
`Repository`	string	required	Image reference to pull. Examples: `nginx:1.25`, `myregistry.example.com/app:v2.0`, `nginx@sha256:593dac…`.

Timeout: Large images can take minutes to pull. The default timeoutSeconds of 30 is insufficient for images over ~500 MB. Set timeoutSeconds to at least 300 for production image pulls.

Sample Configuration

{
  "resource": "image",
  "operation": "pull",
  "connection": {
    "dockerHost": "unix:///var/run/docker.sock",
    "connectionType": "unixsocket",
    "timeoutSeconds": 300
  },
  "Repository": "myregistry.example.com/app:v2.3.1"
}

Validation Errors

Error Code	Condition	Resolution
`MISSING_INPUT`	`Repository` field is empty.	Provide a valid image reference including tag or digest.
`NOT_FOUND`	Image or tag does not exist in the registry.	Verify the image name and tag exist in the target registry.
`AUTH_FAILED`	Registry requires authentication and credentials are not available on the host.	Configure `docker login` on the host, or add credentials to the Docker credential store.
`CONFIG_ERROR`	Connection settings are malformed.	Verify `dockerHost` and `connectionType`.
`DOCKER_API_ERROR`	Pull failed mid-stream (network error, disk full, etc.).	Check Docker daemon logs; ensure sufficient disk space on the host.

Output

Success Port

Field	Type	Description
`status`	string	`"ok"` when pull completes successfully.
`resource`	string	`"image"`
`operation`	string	`"pull"`
`repository`	string	The image reference that was pulled.
`pullStatus`	string	Final status message from the Docker daemon (e.g., `"Status: Downloaded newer image for nginx:1.25"`).

Error Port

Fires when the pull fails. Output contains status: "error", errorCode, and errorMessage.

Sample Output

{
  "status": "ok",
  "resource": "image",
  "operation": "pull",
  "repository": "myregistry.example.com/app:v2.3.1",
  "pullStatus": "Status: Downloaded newer image for myregistry.example.com/app:v2.3.1"
}

Expression Reference

Expression	Returns
`{{ $output.status }}`	`"ok"` on success — use in downstream condition to gate deployment.
`{{ $output.repository }}`	The image reference that was pulled — pass to `container/create`.
`{{ $output.pullStatus }}`	Human-readable pull result from Docker daemon.

Node Policies & GuardRails

Policy	Enforcement
Never expose Docker daemon TCP without TLS	Use `tcptls` for remote Docker hosts. Plain `tcp` is blocked in production GuardRail profiles.
Store TLS certificates in Credentials Manager	Reference `tlsCertPath` via `{{ $credentials.dockerTlsCertPath }}`.
Never interpolate user input into the Repository field	Image references must come from trusted workflow variables or fixed configuration — not raw user-supplied strings.
Pin images by digest for production deployments	Use `repo@sha256:digest` format instead of mutable tags to guarantee immutable deploys.
Always handle the error port	Registry unavailability or authentication failures will route to the error port — wire it to alerting nodes.
Increase timeoutSeconds for large images	Default timeout of 30s is insufficient for images > 500 MB. Set at least 300s in production pull workflows.

Examples

Example 1 — CI/CD Pre-Pull Before Deploy

Pull the application image to the target host, then immediately proceed to create and start the container. The pull node's success output feeds the image reference to container/create.

// Step 1 — image/pull
{
  "resource": "image",
  "operation": "pull",
  "Repository": "{{ $vars.releaseImage }}",
  "connection": { "timeoutSeconds": 300 }
}

// Step 2 — container/create (uses same image ref)
{
  "resource": "container",
  "operation": "create",
  "Image": "{{ $node['image-pull'].output.repository }}"
}

Example 2 — Multi-Host Cache Warming

Use a loop node to iterate over a list of Docker host endpoints and pull the same image to each in sequence before the rolling deployment begins.

// Loop item provides the host endpoint:
{
  "resource": "image",
  "operation": "pull",
  "connection": {
    "dockerHost": "{{ $loopItem.endpoint }}",
    "connectionType": "tcptls",
    "tlsCertPath": "{{ $credentials.dockerTlsCertPath }}"
  },
  "Repository": "myapp:v3.0.0"
}

Example 3 — Digest-Pinned Pull

Pull an image using its exact content-addressable digest to guarantee that the exact same image layers are retrieved regardless of tag mutations.

{
  "resource": "image",
  "operation": "pull",
  "connection": { "timeoutSeconds": 300 },
  "Repository": "nginx@sha256:593dac25b7733ffb7afe1a72649a43e574778bf025ad60514ef40f6b5d606247"
}