~/DOCS/

Configuration

Configuration

On this page:

──

Basic Configuration

──

Runtime Classes

──

Annotations

Basic Configuration

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
      annotations:
        architect.loopholelabs.io/managed-containers: '["my-app-container"]'
        architect.loopholelabs.io/scaledown-durations: '{"my-app-container":"30s"}'
    spec:
      runtimeClassName: runc-architect
      containers:
        - name: my-app-container
          image: my-app:latest
          resources:
            requests:
              memory: "512Mi"
              cpu: "250m"

Runtime Classes

  • runc-architect: automatic hibernation on idle, wake on network or kubectl exec. Container-scoped checkpoints. Use managed-containers.
  • runsc-architect: gVisor security isolation. Pod-scoped checkpoints created explicitly via PersistentCheckpoint CRDs. Use managed-pod. See Examples.

Annotations

managed-containers

architect.loopholelabs.io/managed-containers: '["container-1", "container-2"]'

Which containers Architect manages. Unlisted containers run normally.

scaledown-durations

architect.loopholelabs.io/scaledown-durations: '{"container-1":"30s", "container-2":"60s"}'

Idle time before hibernation. Default: 60s.

network-monitor

architect.loopholelabs.io/network-monitor: '{"container-1":"packets", "container-2":"connections"}'

Enables network-based wake. Modes:

  • packets: wake on any incoming TCP/UDP packet
  • connections: wake on active TCP connection; stay up while connections are open

Requires managed-containers.

health-check-proxy

architect.loopholelabs.io/health-check-proxy: '{"mappings":[{"containerName":"app","appPort":8080,"shadowPort":9080}]}'

Injects a sidecar that returns HTTP 200 for health probes while the container is hibernated, preventing kubelet restarts. Requires managed-containers and network-monitor.

shadow-ports

architect.loopholelabs.io/shadow-ports: '{"mappings":[{"containerName":"app","appPort":8080,"shadowPort":9080}]}'

Redirects traffic from a shadow port to the application port without counting as activity. Useful for Prometheus scraping without waking containers. Requires managed-containers and network-monitor.

postmigration-autoscaleup-containers

architect.loopholelabs.io/postmigration-autoscaleup-containers: '["container-1"]'

Containers that automatically scale up after migration (by default they stay hibernated to avoid thundering herd).

disable-autoscaledown-containers

architect.loopholelabs.io/disable-autoscaledown-containers: '["container-1"]'

Prevents automatic hibernation. Useful for background jobs that should migrate but not hibernate on idle.

scaleup-timeout-containers

architect.loopholelabs.io/scaleup-timeout-containers: '{"container-1": "60s"}'

How long to wait for a checkpoint during startup. Default: 30s. runc-architect only.

migrate-emptydir-containers

architect.loopholelabs.io/migrate-emptydir-containers: '["container-1"]'

Preserves emptyDir volume data during migration. By default, emptyDir volumes are not migrated.

managed-pod (gVisor only)

architect.loopholelabs.io/managed-pod: "true"

Used with runsc-architect instead of managed-containers. The entire pod is managed and checkpointed together.

start-from-persistent-checkpoint (gVisor only)

# Same namespace (name only):
architect.loopholelabs.io/start-from-persistent-checkpoint: "persistent-checkpoint-name"
# Cross-namespace (namespace/name):
architect.loopholelabs.io/start-from-persistent-checkpoint: "namespace/persistent-checkpoint-name"

Restore from a PersistentCheckpoint CRD on startup. When only a name is provided (no /), the PersistentCheckpoint is looked up in the same namespace as the pod. Use the namespace/name format to reference a checkpoint in a different namespace. If missing or empty, the pod starts fresh.