Lifecycle Sidecar

A lightweight Kubernetes sidecar that monitors the main agent container and handles cleanup when the container exits with a specific exit code indicating idle shutdown.

Purpose

User agent containers self-manage their lifecycle by:

Tracking their own activity (MCP calls, trigger status)
Exiting with code 42 when idle (no triggers + no recent activity)
Delegating deployment cleanup to this sidecar

The sidecar watches the main container and:

On exit code 42: Deletes the deployment (and optionally PVC)
On any other exit code: Allows Kubernetes restart policy to handle it

Architecture

┌─────────────────────────────────────────────────┐
│                    Pod                          │
│  ┌────────────────┐      ┌──────────────────┐  │
│  │ Agent Container│      │ Lifecycle Sidecar│  │
│  │                │      │                  │  │
│  │ - Track activity     │ - Monitor agent  │  │
│  │ - Track triggers     │ - Watch exit code│  │
│  │ - Exit 42 if idle    │ - Delete if 42   │  │
│  └────────────────┘      └──────────────────┘  │
│         │                         │             │
│         │ writes exit_code        │             │
│         └─────────►/var/run/agent/exit_code    │
│                                   │             │
└───────────────────────────────────┼─────────────┘
                                    │
                                    ▼ k8s API
                         ┌──────────────────────┐
                         │  Delete Deployment   │
                         │  (+ PVC if anonymous)│
                         └──────────────────────┘

Environment Variables

Variable	Required	Description
`NAMESPACE`	Yes	Kubernetes namespace (injected via downward API)
`DEPLOYMENT_NAME`	Yes	Name of the deployment to delete (from pod label)
`USER_TYPE`	No	User license tier: `anonymous`, `free`, `paid`, `enterprise`
`MAIN_CONTAINER_PID`	No	PID of main container (for precise monitoring)

Exit Code Contract

The agent container uses exit codes to signal intent:

Exit Code	Meaning	Sidecar Action
`42`	Clean idle shutdown	Delete deployment + optional PVC
Any other	Error or normal restart	Allow Kubernetes to restart

RBAC Requirements

The sidecar requires a ServiceAccount with permission to delete its own deployment:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
rules:
  - apiGroups: ["apps"]
    resources: ["deployments"]
    verbs: ["get", "delete"]
  - apiGroups: [""]
    resources: ["persistentvolumeclaims"]
    verbs: ["get", "delete"]

See deploy/k8s/base/lifecycle-sidecar-rbac.yaml for the full RBAC configuration.

Building

docker build -t ghcr.io/dexorder/lifecycle-sidecar:latest .
docker push ghcr.io/dexorder/lifecycle-sidecar:latest

Example Usage

See deploy/k8s/base/agent-deployment-example.yaml for a complete example of how to configure an agent deployment with the lifecycle sidecar.

Security Considerations

Self-delete only: The sidecar can only delete the deployment it's part of (enforced by label matching in admission policy)
Non-privileged: Runs as non-root user (UID 1000)
Minimal permissions: Only has get and delete on deployments/PVCs in the agents namespace
No cross-namespace access: Scoped to dexorder-agents namespace only
Crash-safe: Only triggers cleanup on exit code 42, never on crashes

4.0 KiB Raw Blame History