Skip to main content

Container Service

Category: Infrastructure
Node id: container-service

Manages the lifecycle of sidecar containers within a pipeline execution. Pulls, starts, health-checks, and exposes container endpoints to downstream nodes.

What it does​

  • Pull and start Docker containers as pipeline sidecar services
  • TCP and HTTP health check with configurable timeout
  • Automatic cleanup on execution completion
  • Image allowlist enforcement for security
  • Resource caps: 2048 MB memory, 2.0 CPU cores
  • Max 3 containers per pipeline execution
  • Pipeline inputs injected as HYDRA_INPUTS environment variable
  • Interface resolution maps port names to full endpoint URLs

Use cases​

  • Run HAPI FHIR server as a pipeline-local service
  • Spin up temporary databases for data transformation
  • Launch ML model inference containers on-demand
  • Run custom microservices as pipeline steps

Runtime​

  • Performance tier: slow

Input ports​

NameTypeRequiredDescription
inputanyNoOptional data injected into the container as HYDRA_INPUTS env var

Output ports​

NameTypeRequiredDescription
resultjsonNoContainer metadata: endpoints, interfaces, container_id, image, status
successbooleanNoTrue when container started and passed health check

Settings​

Basic​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Container ImageimagestringYesDocker image to pull and run (must be in allowlist)
Port MappingsportsjsonNoArray of port mappings: [{name, container_port, host_port, protocol}]
Environment Variablesenv_varsjsonNoKey-value map of environment variables to inject
CommandcmdjsonNoOverride container entrypoint with a command array

Resources​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Memory (MB)memory_mbnumberNo512min 64; max 2048Memory limit in megabytes (capped at 2048)
CPU Corescpu_coresnumberNo1min 0.1; max 2CPU core limit (capped at 2.0)

Health​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Health Checkhealth_checkjsonNoHealth check config: {type, port, path, interval, retries}. Types: tcp, http
Health Check Typehealth_check_typeenumNotcptcp, http
Health Check Porthealth_check_portstringNoPort name or number to check
Health Check Pathhealth_check_pathstringNo/HTTP path for health check (only for http type)
Startup Timeout (seconds)startup_timeout_secondsnumberNo60min 5; max 300Maximum time to wait for the container to become healthy

Auth​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Registry Authregistry_authjsonNoCredentials for private registries: {server, username, password}

Advanced​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Pull Policypull_policyenumNoalwaysalways, if-not-present, never
Inject Pipeline Inputsinject_inputsenumNotruetrue, falseWhether to inject upstream data as HYDRA_INPUTS env var
InterfacesinterfacesjsonNoMap of interface names to port names for endpoint resolution
Volume MountsvolumesjsonNoArray of volume mounts: [{name, type, host_path, container_path, read_only}]
Network ConfignetworkjsonNoNetwork configuration: {mode, extra_hosts, dns}
Device RequestsdevicesjsonNoArray of device requests (e.g., GPU): [{type, count}]

Errors​

CodeDescription
IMAGE_REQUIREDimage config field is missing or empty
IMAGE_NOT_ALLOWEDimage is not in the allowed registry list
DOCKER_UNAVAILABLEDocker daemon is not reachable
PULL_FAILEDfailed to pull the container image
START_FAILEDcontainer failed to start
HEALTH_CHECK_FAILEDcontainer did not become healthy within timeout
MAX_CONTAINERSexecution already has the maximum number of containers

Runtime notes​

  • result.endpoints maps port names to full URLs — wire these to downstream API nodes that need the container's address
  • Containers are cleaned up automatically when the pipeline execution ends; max 3 containers per execution
  • Image must match the allowlist (docker.io/library/, hapiproject/, ghcr.io/tiet-ai/, europe-west1-docker.pkg.dev/tietai-*) or the node will reject it
  • Pipeline inputs are JSON-serialized into the HYDRA_INPUTS env var unless inject_inputs is set to 'false'

See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.

Something unclear? Send documentation feedback by email.