Configuration

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.

rewrite-listener-addresses-containers

architect.loopholelabs.io/rewrite-listener-addresses-containers: '["container-1"]'

Rewrites listener socket addresses in CRIU checkpoints during migration. When an application binds to the pod IP (rather than 0.0.0.0), the listener address becomes invalid on the destination pod. This annotation rewrites those addresses to INADDR_ANY (0.0.0.0) or in6addr_any (::) so the restore succeeds. runc-architect only.

rewrite-established-addresses-containers

architect.loopholelabs.io/rewrite-established-addresses-containers: '["container-1"]'

Rewrites the source IP of established TCP connections in CRIU checkpoints during migration. The source pod's IP no longer exists on the destination pod, which causes CRIU's socket restore to fail. This annotation rewrites the source address to the new pod's IP (read from /etc/hosts). Supports both IPv4 and IPv6. runc-architect only.

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

# 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.

When set, this annotation takes priority over pod-template-hash-based Checkpoint CRDs: on any failure (not found, empty, download error, registry storage) the pod starts fresh without falling back to the runc-architect migration path.