Struct WorkloadSpec 

pub struct WorkloadSpec {

    pub schema_version: SchemaVersion,
    pub name: String,
    pub image: ImageRef,
    pub tier: TierTag,
    pub tenant: TenantId,
    pub namespace: NamespaceId,
    pub replicas: u32,
    pub command: Option<Vec<String>>,
    pub entrypoint: Option<Vec<String>>,
    pub workdir: Option<PathBuf>,
    pub user: Option<String>,
    pub env: Vec<EnvVar>,
    pub secrets: Vec<SecretMount>,
    pub volumes: Vec<VolumeMount>,
    pub resources: ResourceLimits,
    pub depends_on: Vec<MeshIdent>,
    pub healthcheck: Option<Healthcheck>,
    pub restart_policy: RestartPolicy,
    pub archetype: Option<LifecycleArchetype>,
    pub stop_policy: StopPolicy,
    pub expose: ExposeSpec,
    pub labels: HashMap<String, String>,
    pub annotations: HashMap<String, String>,
}

Complete typed description of a containerd workload handed to yubaba over RPC. This is also the payload of the kind = "container" variant of Workload on disk.

Yubaba never accepts compose YAML on its RPC surface — agents, the desktop, and operator CLIs all hand yubaba WorkloadSpec values. See the arch doc for the validation layers and evolution rules.

Fields

schema_version: SchemaVersion

Wire-format version; always V1 today. Present at the top level so rolling clusters can detect and migrate across schema generations.

name: String

DNS-friendly workload name, e.g. "noisetable-api". Regex: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$, length ≤ 63.

image: ImageRef

Container image to pull.

tier: TierTag

Tier tag controlling admission control and mesh filtering.

tenant: TenantId

Tenant isolation axis (W206). Separates operators’ workloads at the network / DB / mesh-identity level. Defaults to TenantId::singleton for specs that predate the axis, so single-tenant clusters keep every isolation primitive a no-op. Orthogonal to Self::tier (class) and Self::namespace (routing).

namespace: NamespaceId

Namespace routing/naming axis (W206). A pure naming key — never affects isolation; disambiguates DNS names and selects config root / provider zone within a tenant. Defaults to NamespaceId::singleton.

replicas: u32

Target replica count. 0 registers the workload without deploying it. Range: 0–100 (cluster-wide cap; operator can raise it).

command: Option<Vec<String>>

Override the image’s CMD. None leaves the image default.

entrypoint: Option<Vec<String>>

Override the image’s ENTRYPOINT. None leaves the image default.

workdir: Option<PathBuf>

Working directory inside the container.

user: Option<String>

User to run as, e.g. "1000:1000" or "appuser".

env: Vec<EnvVar>

Environment variables. Values may be literals, secret refs, or mesh-address references resolved by yubaba at deploy time.

secrets: Vec<SecretMount>

Secret mounts. Values never appear in the spec JSON — only references.

volumes: Vec<VolumeMount>

Volume mounts.

resources: ResourceLimits

Hard resource caps enforced by containerd/cgroups.

depends_on: Vec<MeshIdent>

Mesh idents that must reach Ready before this workload starts.

healthcheck: Option<Healthcheck>

Container liveness/readiness probe.

restart_policy: RestartPolicy

What yubaba does when the container exits.

archetype: Option<LifecycleArchetype>

Explicit lifecycle archetype (R572-F1 / W244): server, appliance, or job. None means the spec predates this field (or the author didn’t set it) — callers MUST NOT read this directly to decide drainability; use WorkloadSpec::effective_archetype, which falls back to the pre-R572 volumes/restart_policy inference so no existing spec’s effective meaning changes.

Additive: this field did not exist before R572-F1. Reconciler (F4) and scheduler (F5) branching on the resolved archetype are separate, later tickets — this field alone changes no runtime behavior.

stop_policy: StopPolicy

Graceful shutdown configuration.

expose: ExposeSpec

Network exposure configuration — mesh, public, and operator channels are independent and can be set in any combination.

labels: HashMap<String, String>

OCI-style labels, passed through to the container. Opaque to yubaba.

annotations: HashMap<String, String>

Yah-specific metadata, conventionally prefixed yah.*. Opaque to yubaba beyond yah.forge=true which suppresses the Never-restart guard.

Implementations

impl WorkloadSpec

pub fn for_forge( forge_id: &str, image: ImageRef, tier: TierTag, ports: Vec<u16>, ) -> Self

Build a WorkloadSpec for a forge run.

Sets the conventional forge fields in one place so callers cannot forget any of them:

• restart_policy = Never
• archetype = Some(LifecycleArchetype::Job) — a forge run is exactly the container-kind instance of the job archetype (W244); set explicitly rather than left to infer since this constructor knows its own shape
• expose.public = None, expose.operator = None
• expose.mesh.identity = "forge.<forge_id>"
• annotations["yah.forge"] = "true" (suppresses the shape warning)
• tier and image come from the caller; ports becomes the mesh port list (empty is valid — forge jobs often don’t expose ports)

All other fields are set to safe defaults. Callers can mutate the returned value to fill in command, env, resources, etc.

pub fn wants_host_network(&self) -> bool

Whether this workload requests the host network namespace rather than an isolated one.

Opt-in via annotations["yah.network"] == "host" (see HOST_NETWORK_ANNOTATION / HOST_NETWORK_VALUE). Default is the isolated netns every other workload gets — host networking is a privileged escape hatch for the few infra workloads that must bind a host port so an on-host ingress (e.g. a Cloudflare tunnel reaching 127.0.0.1:<port>) can route to them without CNI/bridge plumbing.

The backend (kamaji) is responsible for guarding this: host networking is only honoured for tier == "infra" workloads; a non-infra workload that sets the annotation is rejected at deploy. See validate_spec_for_constable.

pub fn effective_archetype(&self) -> LifecycleArchetype

Resolve the lifecycle archetype (R572-F1 / W244): the explicit Self::archetype if set, otherwise the pre-R572 inference from volumes/restart_policy this field replaces.

This is the one seam callers should use to ask “can I kill and reschedule this?” — it is intentionally the only place that implements the fallback, so behavior for pre-existing specs (no archetype on disk) is identical to what it was before this field existed. Consumers (reconciler R572-F4, scheduler R572-F5) branch on the return value; this crate does not itself change any reconciler or scheduler behavior.

pub fn fq_mesh_identity(&self) -> String

Fully-qualified mesh identity <tenant>/<namespace>/<name> (W206 / R558-F3), where <name> is this workload’s MeshExpose::identity.

Within a tenant, workloads still address each other by the short identity (namespace disambiguates only on collision); the FQN is what makes the identity unambiguous across tenants and is exactly what a MeshPeer::CrossTenant grant names.

pub fn requires_taint(&self) -> Option<&str>

The taint this workload requires its node to carry, if any (R594-F2 / W267 sovereign public ingress).

Opt-in via annotations["yah.placement.requires-taint"] = "<taint name>" (see REQUIRES_TAINT_ANNOTATION) — same annotation-based, zero-blast-radius shape as Self::wants_host_network, chosen so declaring this requirement does not force a struct-literal edit at every existing WorkloadSpec { .. } construction site the way a new plain field would (see R572-F1’s handoff: ~26 sites for one field).

This only declares the requirement — nothing matches it yet. The taint itself doesn’t exist on the machine-TOML side until R572-F3 adds a taints list there, and nothing enforces repel-unless-tolerate placement until R572-F5’s scheduler lands. Until then this is inert metadata a future scheduler can read.

The public-ingress appliance (W267) is the first user: a kind = "container" workload with archetype = Some(LifecycleArchetype::Appliance) and requires_taint() == Some(PUBLIC_IP_TAINT), so yubaba may one day place it only on machines carrying the "public-ip" taint and kamaji supervises it like any other container (no new Workload variant — see Workload::Container’s doc comment).

Trait Implementations

impl Clone for WorkloadSpec

fn clone(&self) -> WorkloadSpec

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for WorkloadSpec

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for WorkloadSpec

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for WorkloadSpec

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for WorkloadSpec

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 WorkloadSpec

impl TS for WorkloadSpec

type WithoutGenerics = WorkloadSpec

If this type does not have generic parameters, then WithoutGenerics should just be Self. If the type does have generic parameters, then all generic parameters must be replaced with a dummy type, e.g ts_rs::Dummy or ().
The only requirement for these dummy types is that EXPORT_TO must be None.

type OptionInnerType = WorkloadSpec

If the implementing type is std::option::Option<T>, then this associated type is set to T. All other implementations of TS should set this type to Self instead.

fn ident(cfg: &Config) -> String

Identifier of this type, excluding generic parameters.

fn docs() -> Option<String>

JSDoc comment to describe this type in TypeScript - when TS is derived, docs are automatically read from your doc comments or #[doc = ".."] attributes

fn name(cfg: &Config) -> String

Name of this type in TypeScript, including generic parameters

fn decl_concrete(cfg: &Config) -> String

Declaration of this type using the supplied generic arguments. The resulting TypeScript definition will not be generic. For that, see TS::decl(). If this type is not generic, then this function is equivalent to TS::decl().

fn decl(cfg: &Config) -> String

Declaration of this type, e.g. type User = { user_id: number, ... }. This function will panic if the type has no declaration.

fn inline(cfg: &Config) -> String

Formats this types definition in TypeScript, e.g { user_id: number }. This function will panic if the type cannot be inlined.

fn inline_flattened(cfg: &Config) -> String

Flatten a type declaration. This function will panic if the type cannot be flattened.

fn visit_generics(v: &mut impl TypeVisitor)

where Self: 'static,

Iterates over all type parameters of this type.

fn output_path() -> Option<PathBuf>

Returns the output path to where T should be exported, relative to the output directory. The returned path does not include any base directory.

fn visit_dependencies(v: &mut impl TypeVisitor)

where Self: 'static,

Iterates over all dependency of this type.

fn dependencies(cfg: &Config) -> Vec<Dependency>

where Self: 'static,

Resolves all dependencies of this type recursively.

fn export(cfg: &Config) -> Result<(), ExportError>

where Self: 'static,

Manually export this type to the filesystem. To export this type together with all of its dependencies, use TS::export_all.

fn export_all(cfg: &Config) -> Result<(), ExportError>

where Self: 'static,

Manually export this type to the filesystem, together with all of its dependencies. To export only this type, without its dependencies, use TS::export.

fn export_to_string(cfg: &Config) -> Result<String, ExportError>

where Self: 'static,

Manually generate bindings for this type, returning a String. This function does not format the output, even if the format feature is enabled.