Struct ServiceSpec 

pub struct ServiceSpec {

    pub rtype: ResourceType,
    pub schedule: Option<String>,
    pub image: ImageSpec,
    pub resources: ResourcesSpec,
    pub env: HashMap<String, String>,
    pub command: CommandSpec,
    pub network: ServiceNetworkSpec,
    pub endpoints: Vec<EndpointSpec>,
    pub scale: ScaleSpec,
    pub replica_groups: Option<Vec<ReplicaGroup>>,
    pub depends: Vec<DependsSpec>,
    pub health: HealthSpec,
    pub init: InitSpec,
    pub errors: ErrorsSpec,
    pub lifecycle: LifecycleSpec,
    pub isolation: Option<IsolationMode>,
    pub devices: Vec<DeviceSpec>,
    pub storage: Vec<StorageSpec>,
    pub port_mappings: Vec<PortMapping>,
    pub capabilities: Vec<String>,
    pub cap_drop: Vec<String>,
    pub privileged: bool,
    pub node_mode: NodeMode,
    pub node_selector: Option<NodeSelector>,
    pub affinity: Option<GroupAffinity>,
    pub platform: Option<TargetPlatform>,
    pub service_type: ServiceType,
    pub wasm: Option<WasmConfig>,
    pub logs: Option<LogsConfig>,
    pub host_network: bool,
    pub hostname: Option<String>,
    pub dns: Vec<String>,
    pub extra_hosts: Vec<String>,
    pub restart_policy: Option<ContainerRestartPolicy>,
    pub labels: HashMap<String, String>,
    pub user: Option<String>,
    pub stop_signal: Option<String>,
    pub stop_grace_period: Option<Duration>,
    pub sysctls: HashMap<String, String>,
    pub ulimits: HashMap<String, UlimitSpec>,
    pub security_opt: Vec<String>,
    pub pid_mode: Option<String>,
    pub ipc_mode: Option<String>,
    pub network_mode: NetworkMode,
    pub extra_groups: Vec<String>,
    pub read_only_root_fs: bool,
    pub init_container: Option<bool>,
    pub tty: bool,
    pub stdin_open: bool,
    pub userns_mode: Option<String>,
    pub cgroup_parent: Option<String>,
    pub expose: Vec<String>,
    pub overlay: Option<OverlayConfig>,
    pub localhost_reachability: LocalhostReachability,
}

Per-service specification

Fields

rtype: ResourceType

Resource type (service, job, cron)

schedule: Option<String>

Cron schedule expression (only for rtype: cron) Uses 7-field cron syntax: “sec min hour day-of-month month day-of-week year” Examples:

• “0 0 0 * * * *” (daily at midnight)
• “0 */5 * * * * *” (every 5 minutes)
• “0 0 12 * * MON-FRI *” (weekdays at noon)

image: ImageSpec

Container image specification

resources: ResourcesSpec

Resource limits

env: HashMap<String, String>

Environment variables for the service

Values can be:

• Plain strings: "value"
• Host env refs: $E:VAR_NAME
• Secret refs: $S:secret-name or $S:@service/secret-name

command: CommandSpec

Command override (entrypoint, args, workdir)

network: ServiceNetworkSpec

Network configuration

endpoints: Vec<EndpointSpec>

Endpoint definitions (proxy bindings)

scale: ScaleSpec

Scaling configuration

replica_groups: Option<Vec<ReplicaGroup>>

Heterogeneous replica groups within this service.

When set, the service is composed of multiple named groups (e.g. primary + read + cache) instead of a flat scale.replicas. Each group inherits ServiceSpec defaults (image, env, command, resources) and overrides per-group fields.

When None (default), the service uses scale directly with an implicit single group {role: "default", count: <scale.replicas>}. This is the backward-compatible path used by all existing specifications.

Cross-group role uniqueness is validated separately by validate_unique_replica_group_roles from the deploy handler.

depends: Vec<DependsSpec>

Dependency specifications

health: HealthSpec

Health check configuration

init: InitSpec

Init actions (pre-start lifecycle steps)

errors: ErrorsSpec

Error handling policies

lifecycle: LifecycleSpec

Container lifecycle policy (e.g., delete-on-exit).

Purely declarative on this type; downstream layers (agent / API / scheduler) read this field to decide whether to clean up the container record after termination.

isolation: Option<IsolationMode>

Container isolation mode (Windows containers only; ignored on Linux/macOS).

devices: Vec<DeviceSpec>

Device passthrough (e.g., /dev/kvm for VMs)

storage: Vec<StorageSpec>

Storage mounts for the container

port_mappings: Vec<PortMapping>

Host-to-container port mappings (Docker’s -p host:container/proto).

Each entry publishes a container port on the host. When host_port is None (or zero), the daemon assigns an ephemeral host port.

capabilities: Vec<String>

Linux capabilities to add (e.g., SYS_ADMIN, NET_ADMIN).

Also accepts the Docker-compatible alias cap_add on input.

cap_drop: Vec<String>

Linux capabilities to drop (Docker --cap-drop).

privileged: bool

Run container in privileged mode (all capabilities + all devices)

node_mode: NodeMode

Node allocation mode (shared, dedicated, exclusive)

node_selector: Option<NodeSelector>

Node selection constraints (required/preferred labels)

affinity: Option<GroupAffinity>

Placement affinity for this service’s replicas when the service is NOT composed of replica_groups (each group carries its own affinity).

None (the default) preserves historical shared-mode behavior: bin-pack / concentrate consecutive replicas onto the fewest nodes that fit. Set to spread for same-service anti-affinity (replicas land on distinct nodes for higher availability), pack to concentrate explicitly, or pin to bind all replicas to one node.

Note: capacity always wins — a replica that does not fit on a node is placed elsewhere regardless of affinity.

platform: Option<TargetPlatform>

Target platform for this service. When None (default), the service is eligible to run on any agent regardless of OS/architecture. When Some, the scheduler will only place replicas on agents whose platform matches.

service_type: ServiceType

Service type (standard, wasm_http, wasm_plugin, etc.)

wasm: Option<WasmConfig>

WASM configuration (used when service_type is any Wasm* variant) Also accepts the deprecated wasm_http key for backward compatibility.

logs: Option<LogsConfig>

Log output configuration. If not set, uses platform defaults.

host_network: bool

Use host networking (container shares host network namespace)

When true, the container will NOT get its own network namespace. This is set programmatically via the --host-network CLI flag, not in YAML specs.

hostname: Option<String>

Container hostname (maps to Docker’s --hostname).

When set, the container’s /etc/hostname and initial kernel hostname are configured to this value. Ignored when host_network is true (the container inherits the host’s hostname).

dns: Vec<String>

Additional DNS servers for the container (maps to Docker’s --dns).

Each entry must be a plausible IPv4 or IPv6 address. Forwarded to the container runtime as resolver addresses ahead of the platform defaults. Ignored when host_network is true.

extra_hosts: Vec<String>

Extra hostname:ip entries appended to /etc/hosts (maps to Docker’s --add-host).

Each entry must be in the form "<hostname>:<ip>". The special literal host-gateway is accepted as the <ip> half (resolved by Docker / bollard to the host-visible gateway address, commonly used with host.docker.internal:host-gateway).

restart_policy: Option<ContainerRestartPolicy>

Container restart policy (Docker-style).

Controls when the runtime should automatically restart the container after it exits. Maps to Docker’s HostConfig.RestartPolicy. Named ContainerRestartPolicy to avoid colliding with ZLayer’s existing PanicPolicy (which controls post-panic behavior, not runtime-level restarts).

labels: HashMap<String, String>

Free-form key/value labels attached to the container (Docker --label).

user: Option<String>

User and group override for the container’s main process (Docker --user uid:gid).

stop_signal: Option<String>

Signal sent to the container’s main process to request a graceful shutdown (Docker --stop-signal). Accepts e.g. "SIGTERM" or "15".

stop_grace_period: Option<Duration>

Grace period to wait between the stop signal and a forced kill (Docker --stop-timeout).

sysctls: HashMap<String, String>

Kernel sysctl overrides (Docker --sysctl).

ulimits: HashMap<String, UlimitSpec>

Per-process ulimits (Docker --ulimit).

security_opt: Vec<String>

Security options such as apparmor=..., seccomp=..., no-new-privileges:true (Docker --security-opt).

pid_mode: Option<String>

PID namespace mode (Docker --pid). Accepts e.g. "host" or "container:<id>".

ipc_mode: Option<String>

IPC namespace mode (Docker --ipc). Accepts e.g. "host", "shareable", "private", or "container:<id>".

network_mode: NetworkMode

Network mode (Docker --network). Accepts both the enum-tagged form and the Docker-style strings ("host", "none", "bridge", "bridge:<name>", "container:<id>").

extra_groups: Vec<String>

Additional groups to add to the container process (Docker --group-add).

read_only_root_fs: bool

Mount the container’s root filesystem read-only (Docker --read-only).

init_container: Option<bool>

Run a Docker-supplied init process (PID 1) inside the container (Docker --init). Distinct from ServiceSpec::init which controls ZLayer’s pre-start init actions.

tty: bool

Allocate a TTY for the container’s main process (Docker --tty, compose tty: true).

stdin_open: bool

Keep STDIN open even when nothing is attached (Docker --interactive, compose stdin_open: true).

userns_mode: Option<String>

User namespace mode (Docker --userns). Accepts e.g. "host" or a remap-spec name configured on the daemon.

cgroup_parent: Option<String>

Cgroup parent path (Docker --cgroup-parent). When set, the runtime places the container under the given cgroup hierarchy.

expose: Vec<String>

Container ports exposed but not published to the host (compose expose:). Each entry is a port string, optionally port/proto (e.g. "3000", "8080/tcp"). Treated as documentation by the runtime; downstream networking layers may use this list to allow inter-service traffic without publishing to the host.

overlay: Option<OverlayConfig>

Per-service overlay-network configuration.

When None (default), the daemon uses the cluster-level overlay default. When Some, the service opts into an explicit mode / parent. See crate::overlay::OverlayConfig for the v0.51 implementation status.

localhost_reachability: LocalhostReachability

Policy for making this service’s exposed ports reachable on the node’s loopback (127.0.0.1:<port>) for same-node consumers — the GitHub Actions “service published to localhost” convention. See LocalhostReachability. Default LocalhostReachability::Auto.

Implementations

impl ServiceSpec

pub fn is_single_member(&self) -> bool

True when this service is effectively a single member: it has no (multi-member) replica groups and a scale policy that cannot exceed one replica (Fixed { 0 | 1 }, Adaptive { max <= 1 }, or Manual).

Used by LocalhostReachability::Auto to decide whether publishing the service’s ports on the node loopback is unambiguous — a genuine multi-member service would put several backends behind one loopback port, so name-based overlay DNS is the correct addressing for those instead.

pub fn publish_to_node_loopback(&self) -> bool

Whether the daemon should publish this service’s exposed ports on the node loopback (127.0.0.1:<port>), per its LocalhostReachability policy. Auto publishes only for effectively single-member services (see ServiceSpec::is_single_member).

pub fn minimal(_name: impl Into<String>, image: impl Into<String>) -> Self

Construct a minimally-populated ServiceSpec with just the two fields callers always have to supply explicitly: the logical service name (used for diagnostics / labels at the call site — this struct does not carry the service name itself; it is the key in DeploymentSpec::services) and the container image. Every other field is filled in from Default::default.

Intended for tests and one-off in-memory fixtures. Production code paths that build a ServiceSpec from user input should still go through serde deserialization or an explicit struct literal so that every field is consciously set.

Examples

let spec = ServiceSpec::minimal("api", "ghcr.io/acme/api:1.2");

Panics

Panics only if the fixed fallback string "scratch:latest" cannot be parsed as an [ImageReference] — which would indicate a bug in the OCI reference parser, not in caller input.

Trait Implementations

impl Clone for ServiceSpec

fn clone(&self) -> ServiceSpec

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ServiceSpec

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ServiceSpec

fn default() -> ServiceSpec

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ServiceSpec

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for ServiceSpec

fn eq(&self, other: &ServiceSpec) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for ServiceSpec

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for ServiceSpec

impl Validate for ServiceSpec

fn validate(&self) -> Result<(), ValidationErrors>

impl<'v_a> ValidateArgs<'v_a> for ServiceSpec

type Args = ()

fn validate_with_args(&self, args: Self::Args) -> Result<(), ValidationErrors>