Workloads

LatticeService

The primary developer-facing resource. Defines a workload's containers, network dependencies (bilateral agreements), volumes, secrets, autoscaling, and deploy strategy in a single manifest.

group: lattice.dev version: v1alpha1 scope: namespaced

Examples

A media server ecosystem demonstrating volume ownership vs. reference, sidecars with capabilities, bilateral agreements, ingress with TLS, secrets, and health probes.

Media Server with Ingress and Shared Volumes

jellyfin.yaml 
apiVersion: lattice.dev/v1alpha1
kind: LatticeService
metadata:
  name: jellyfin
  namespace: media
spec:
  workload:
    containers:
      main:
        image: jellyfin/jellyfin:10.9.6
        variables:
          JELLYFIN_DATA_DIR: /config
          JELLYFIN_CACHE_DIR: /cache
        volumes:
          /config:
            source: ${resources.config}
          /media:
            source: ${resources.media}
            readOnly: true
        resources:
          requests:
            cpu: 500m
            memory: 1Gi
          limits:
            cpu: 4000m
            memory: 4Gi
        livenessProbe:
          httpGet:
            path: /health
            port: 8096
        readinessProbe:
          httpGet:
            path: /health
            port: 8096

    service:
      ports:
        http:
          port: 8096

    resources:
      sonarr:                   # sonarr calls me for webhooks
        type: service
        direction: inbound

      jellyfin-creds:           # API key from Vault
        type: secret
        params:
          provider: vault-media
          keys: [api-key]
          refreshInterval: 24h

      config:                   # owned volume
        type: volume
        id: jellyfin-config
        params:
          size: 10Gi

      media:                    # shared volume (ref, no size)
        type: volume
        id: media-downloads

  ingress:
    routes:
      public:
        hosts: [media.example.com]
        tls:
          issuerRef:
            name: letsencrypt-prod
        port: http

  imagePullSecrets:
    - registry-creds

  replicas: 1

  deploy:
    strategy: rolling

Downloader with VPN Sidecar

nzbget.yaml 
apiVersion: lattice.dev/v1alpha1
kind: LatticeService
metadata:
  name: nzbget
  namespace: media
spec:
  workload:
    containers:
      main:
        image: nzbgetcom/nzbget:v24.1
        volumes:
          /downloads:
            source: ${resources.downloads}
          /config:
            source: ${resources.config}
        resources:
          requests:
            cpu: 200m
            memory: 512Mi
          limits:
            cpu: 2000m
            memory: 2Gi
        readinessProbe:
          exec:
            command: ["/usr/bin/test", "-f", "/config/nzbget.conf"]

    service:
      ports:
        http:
          port: 6789

    resources:
      sonarr:                   # sonarr calls me to trigger downloads
        type: service
        direction: inbound

      nzbget-creds:
        type: secret
        params:
          provider: vault-media
          keys: [username, password, api-key]

      downloads:                # owned volume (shared with others)
        type: volume
        id: media-downloads
        params:
          size: 500Gi
          storageClass: fast-nvme

      config:
        type: volume
        id: nzbget-config
        params:
          size: 1Gi

  sidecars:
    vpn:
      image: ghcr.io/qdm12/gluetun:v3.38
      variables:
        VPN_SERVICE_PROVIDER: mullvad
        VPN_TYPE: wireguard
      security:
        capabilities: [NET_ADMIN, SYS_MODULE]

  replicas: 1

  deploy:
    strategy: rolling

Orchestrator with Multiple Dependencies

sonarr.yaml 
apiVersion: lattice.dev/v1alpha1
kind: LatticeService
metadata:
  name: sonarr
  namespace: media
spec:
  workload:
    containers:
      main:
        image: linuxserver/sonarr:4.0.4
        variables:
          SONARR__AUTH__APIKEY: ${resources.sonarr-creds.api-key}
        volumes:
          /config:
            source: ${resources.config}
          /downloads:
            source: ${resources.downloads}
          /tv:
            source: ${resources.tv}
        resources:
          requests:
            cpu: 100m
            memory: 256Mi
          limits:
            cpu: 1000m
            memory: 1Gi
        livenessProbe:
          httpGet:
            path: /ping
            port: 8989

    service:
      ports:
        http:
          port: 8989

    resources:
      nzbget:                   # I call nzbget for downloads
        type: service
        direction: outbound

      jellyfin:                 # I call jellyfin for library refresh
        type: service
        direction: outbound

      sonarr-creds:
        type: secret
        params:
          provider: vault-media
          keys: [api-key]

      config:
        type: volume
        id: sonarr-config
        params:
          size: 5Gi

      downloads:                # shared volume reference (no size)
        type: volume
        id: media-downloads

      tv:                       # shared volume reference
        type: volume
        id: media-tv

  ingress:
    routes:
      public:
        hosts: [sonarr.example.com]
        tls:
          issuerRef:
            name: letsencrypt-prod
        port: http

  replicas: 1

  deploy:
    strategy: rolling

Spec

LatticeService spec fields
Field Type Description
workload WorkloadSpec Score-compatible workload specification: containers, resources, and service ports.
replicas u32 Number of pod replicas. Default: 1.
autoscaling AutoscalingSpec? Optional KEDA autoscaling configuration.
deploy DeploySpec Deployment strategy: Rolling or Canary.
ingress IngressSpec? Optional Gateway API ingress configuration.
backup ServiceBackupSpec? Service-level backup configuration: scheduling, hooks, and volume policies. Uses a BackupStore for storage.
sidecars map<string, SidecarSpec> Additional sidecar containers with capability control.
sysctls map<string, string> Kernel parameter overrides for the pod.
hostNetwork bool? Use the host network namespace.
shareProcessNamespace bool? Share a single process namespace between containers.
imagePullSecrets []string Resource names referencing type: secret resources for private image registries.

WorkloadSpec

Score-compatible workload specification shared across LatticeService, LatticeJob, and LatticeModel.

WorkloadSpec fields
Field Type Description
containers map<string, ContainerSpec> Named container definitions. The main container is treated as the primary.
resources map<string, ResourceSpec> Named resource declarations: services, volumes, secrets, models, GPUs.
service ServicePortsSpec? Kubernetes Service port configuration.

ContainerSpec

ContainerSpec fields
Field Type Description
image string Container image with tag.
variables map<string, TemplateString> Environment variables with $${resources.name.key} template support.
files map<string, FileMount> File mounts keyed by path (e.g., /etc/config.yaml). Inline content, binary, or source reference.
volumes map<string, VolumeMount> Volume mounts keyed by mount path (e.g., /config).
resources ResourceRequirements? CPU and memory requests/limits.
command []string? Override container entrypoint.
args []string? Override container arguments.
livenessProbe Probe? Liveness probe configuration.
readinessProbe Probe? Readiness probe configuration.
startupProbe Probe? Startup probe configuration.
security SecurityContext? Container security context. When omitted, the compiler applies Pod Security Standards "restricted" profile defaults.

ResourceSpec

Declares a dependency on another service, a volume, a secret, a GPU, or a custom resource. Score-compatible with Lattice extensions for bilateral networking.

ResourceSpec fields
Field Type Description
type ResourceType Resource type.
direction DependencyDirection Traffic direction for service dependencies.
class string? Optional specialization (Score-compatible).
id string? Resource identifier for sharing volumes or referencing secrets.
namespace string? Cross-namespace reference for service dependencies.
params map<string, any>? Type-specific parameters (volume size, secret keys, GPU count, model URI, etc.).
metadata ResourceMetadata? Optional annotations.

ResourceType

service Internal LatticeService dependency. Creates bilateral agreement.
external-service LatticeExternalService dependency (outside the mesh).
volume Persistent volume. Use params.size to own, or omit to reference.
secret Secret from a SecretProvider. Synced via External Secrets Operator.
gpu GPU resource. Use params.count, params.memory, params.model to configure.
custom Custom resource type (extensible).

DependencyDirection

Defines the traffic direction for bilateral service agreements. Both sides must agree for traffic to flow.

outbound This service calls the target. Generates Cilium egress + Istio outbound policy.
inbound The target calls this service. Generates Cilium ingress + Istio AuthorizationPolicy.
both Bidirectional communication. Generates policies in both directions.
frontend api: outbound api frontend: inbound Both agree → traffic allowed

Volume Parameters

When type: volume, these parameters are available in params. A volume with size is the owner; without size, it references an existing volume by id.

Volume parameters
Param Type Description
size string? PVC size (e.g., "10Gi", "500Gi"). Presence marks this service as volume owner.
storageClass string? Kubernetes StorageClass name.
accessMode string? ReadWriteOnce (default), ReadWriteMany, or ReadOnlyMany.
allowedConsumers []string? Services allowed to consume this volume.

Secret Parameters

Secret parameters
Param Type Description
provider string SecretProvider name.
keys []string? Specific secret keys to sync. If omitted, all keys are synced.
refreshInterval string? How often to re-sync from the secret provider (e.g., "1h", "30m").
secretType string? Kubernetes Secret type (e.g., kubernetes.io/dockerconfigjson).

GPU Parameters

GPU parameters
Param Type Description
count u32 Number of GPUs required. Must be > 0.
memory string? GPU memory requirement (e.g., "8Gi").
compute u32? Compute percentage (HAMi virtual GPU).
model string? GPU model filter (e.g., "A100", "L4").
tolerations bool? Auto-add GPU node tolerations. Default: unset (auto).

ServicePortsSpec

ServicePortsSpec fields
Field Type Description
ports map<string, PortSpec> Named port definitions.

PortSpec

PortSpec fields
Field Type Description
port u16 Service port number.
targetPort u16? Container port (defaults to port).
protocol string? TCP, UDP, HTTP, or HTTPS.

VolumeMount

Volume mount configuration. The map key is the mount path inside the container (e.g., /config).

VolumeMount fields
Field Type Description
source TemplateString? Resource reference (e.g., $${resources.config}).
path string? Sub-path within the volume to mount.
readOnly bool? Mount the volume as read-only.
medium string? Storage medium (e.g., Memory for emptyDir backed by tmpfs).
sizeLimit string? Size limit for emptyDir volumes (e.g., "1Gi").

FileMount

File mount configuration. The map key is the file path inside the container (e.g., /etc/config.yaml). At least one of content, binaryContent, or source must be set.

FileMount fields
Field Type Description
content TemplateString? Inline UTF-8 file content. Supports $${...} placeholders.
binaryContent string? Base64-encoded binary content.
source TemplateString? Path to content file. Supports $${...} placeholders.
mode string? File mode in octal (e.g., "0644"). Setuid, setgid, sticky, and world-writable bits are rejected.
noExpand bool Disable $${...} placeholder expansion entirely. Default: false.
reverseExpand bool Reverse expansion: $${...} stays literal, $$${...} expands. Useful for bash scripts. Default: false.

SidecarSpec

Sidecar container specification. Identical to ContainerSpec with one additional field.

SidecarSpec fields
Field Type Description
init bool? Run as an init container (runs once before main containers start). Default: false.
Plus all ContainerSpec fields: image, command, args, variables, resources, files, volumes, probes, security.

SecurityContext

Container security context. When omitted entirely, the compiler applies Pod Security Standards "restricted" profile defaults: drop ALL capabilities, no privilege escalation, non-root, read-only rootfs, RuntimeDefault seccomp and AppArmor profiles.

SecurityContext fields
Field Type Description
capabilities []string Linux capabilities to add (e.g., NET_ADMIN, SYS_MODULE).
dropCapabilities []string? Capabilities to drop. Default: [ALL].
privileged bool? Run in privileged mode (strongly discouraged).
readOnlyRootFilesystem bool? Mount root filesystem as read-only. Default: true. Generates block-rootfs-write Tetragon policy.
runAsNonRoot bool? Require non-root user. Default: true. Generates block-setuid Tetragon policy.
runAsUser i64? UID to run the container as.
runAsGroup i64? GID to run the container as.
allowPrivilegeEscalation bool? Allow privilege escalation via setuid binaries. Default: false.
seccompProfile string? Seccomp profile: RuntimeDefault, Unconfined, or Localhost.
seccompLocalhostProfile string? Localhost seccomp profile path (when seccompProfile is Localhost).
apparmorProfile string? AppArmor profile: RuntimeDefault, Unconfined, or Localhost.
apparmorLocalhostProfile string? Localhost AppArmor profile name (when apparmorProfile is Localhost).
allowedBinaries []string Binary execution allowlist enforced by Tetragon. Use ["*"] to disable restrictions.

IngressSpec

Gateway API-based ingress configuration with named routes.

IngressSpec fields
Field Type Description
gatewayClass string? Gateway class name.
routes map<string, RouteSpec> Named route definitions.

RouteSpec

RouteSpec fields
Field Type Description
kind string? Route kind: HTTPRoute (default), GRPCRoute, or TCPRoute.
hosts []string Hostnames for the route.
port string? Named port reference from service ports.
listenPort u16? Gateway listener port.
rules []RouteRule? Optional routing rules.
tls IngressTls? TLS configuration for this route.

IngressTls

IngressTls fields
Field Type Description
secretName string? Kubernetes Secret containing the TLS certificate.
issuerRef CertIssuerRef? cert-manager issuer reference for automatic certificate provisioning.

AutoscalingSpec

Optional KEDA-based autoscaling configuration.

AutoscalingSpec fields
Field Type Description
max u32 Maximum replica count.
metrics []AutoscalingMetric Metric targets for scaling.

AutoscalingMetric

AutoscalingMetric fields
Field Type Description
metric string Metric name: cpu, memory, or a custom metric.
target u32 Target percentage or value for scaling.

DeploySpec

DeploySpec fields
Field Type Description
strategy DeployStrategy rolling (default) or canary.
canary CanarySpec? Required when strategy is canary.

CanarySpec

CanarySpec fields
Field Type Description
interval string? Interval between canary steps (e.g., "1m", "5m").
threshold u32? Error threshold before triggering rollback.
maxWeight u32? Maximum traffic weight for the canary (e.g., 50 for 50%).
stepWeight u32? Weight increment per canary step.

ServiceBackupSpec

Service-level backup configuration. When schedule is set, a dedicated Velero Schedule is created scoped to this service's namespace and labels.

ServiceBackupSpec fields
Field Type Description
schedule string? Cron schedule for service-level backups (e.g., "0 3 * * *"). Creates a dedicated Velero Schedule.
storeRef string? Reference to a BackupStore. If omitted, the default BackupStore is used.
retention BackupRetentionSpec? Retention policy (daily, ttl). See BackupRetentionSpec.
hooks BackupHooksSpec? Pre and post backup hooks for application-consistent backups.
volumes VolumeBackupSpec? Volume backup inclusion/exclusion policy.

BackupHooksSpec

BackupHooksSpec fields
Field Type Description
pre []BackupHook Hooks to run before the backup (e.g., flush database, freeze filesystem).
post []BackupHook Hooks to run after the backup (e.g., thaw filesystem, resume writes).

BackupHook

BackupHook fields
Field Type Description
name string Hook name for identification in logs.
container string Container to execute the hook in.
command []string Command to execute (e.g., ["pg_dump", "-f", "/backup/dump.sql"]).
timeout string? Maximum hook execution time (e.g., "30s", "5m").
onError HookErrorAction? Continue (default) or Fail. Controls whether backup proceeds on hook failure.

VolumeBackupSpec

VolumeBackupSpec fields
Field Type Description
defaultPolicy VolumeBackupDefault? opt-out (default) — all volumes backed up unless excluded. opt-in — only explicitly included volumes backed up.
include []string Volume names to explicitly include in backups.
exclude []string Volume names to exclude from backups.

Status

LatticeService status fields
Field Type Description
phase ServicePhase Current phase: Pending, Compiling, Ready, or Failed.
message string? Human-readable status message.
conditions []Condition Standard Kubernetes conditions.
lastCompiledAt DateTime? When manifests were last compiled from the spec.
observedGeneration i64? Last observed metadata.generation.
resolvedDependencies map<string, string> Resolved dependency URLs keyed by resource name.