Kubernetes Deployment

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• AGENTS.md
• src/main.rs
• src/config.rs
• src/proxy.rs

Hodor operates as a lightweight reverse proxy designed to run as a sidecar container within Kubernetes pods. It protects upstream web applications by requiring a single shared password while providing native support for orchestrator-level health checks and graceful termination.

Sources: README.md:3-8, AGENTS.md:7-9

Sidecar Architecture

In a Kubernetes environment, Hodor typically sits in front of an application container within the same pod. It intercepts all incoming traffic, enforces authentication, and forwards authorized requests to the application via localhost or a service DNS name.

The diagram shows how Hodor acts as an entry point within a pod to gate access to the main application container.
Sources: README.md:386-387, AGENTS.md:7-9

Health Probes

Hodor provides a dedicated endpoint at /_gate/health for orchestrator liveness probes. This endpoint returns a 200 OK status as long as the Hodor process is active and serving HTTP requests.

• Liveness Probe: Use /_gate/health to monitor process health.
• Readiness Probe: For end-to-end readiness that includes the application, probe a path defined in BYPASS_PATHS.

Probe Type	Path	Purpose
Liveness	/_gate/health	Verifies Hodor process is running.
Readiness	User-defined (via BYPASS_PATHS)	Verifies end-to-end connectivity to upstream.

Sources: README.md:389-405, src/main.rs:24

Kubernetes Probe Configuration Example

livenessProbe:
  httpGet:
    path: /_gate/health
    port: 8080
  initialDelaySeconds: 2
  periodSeconds: 10

Sources: README.md:398-405

Ingress and Proxy Trust

When deployed behind a Kubernetes Ingress or Load Balancer, Hodor must correctly identify the original client IP to apply rate limits and CIDR bypasses. You must configure Hodor to trust the headers provided by the Ingress controller.

1. Trust Headers: Set TRUST_PROXY=true to enable processing of X-Forwarded-For.
2. Restrict CIDRs: Use TRUSTED_PROXY_CIDRS to specify the network ranges of your Ingress controllers.
3. Protocol Preservation: Hodor preserves X-Forwarded-Proto from trusted proxies to ensure the upstream application knows if the connection was HTTPS.

Sources: README.md:173-183, src/config.rs:104-106, src/proxy.rs:200-205

Lifecycle Management

Hodor supports graceful shutdown to ensure active connections are handled correctly during pod termination or deployments.

• SIGTERM Handling: The application listens for SIGTERM signals, which are standard for Kubernetes pod termination.
• Graceful Shutdown: Upon receiving the signal, Hodor initiates a shutdown sequence to stop accepting new requests while allowing current ones to complete.

The diagram illustrates the interaction between the Kubernetes Kubelet and Hodor during a pod deletion event.
Sources: README.md:20, src/main.rs:88-109

Configuration for Kubernetes

Kubernetes deployments typically utilize environment variables to configure Hodor's behavior.

Environment Variable	Description
PASSWORD	The shared password for access.
UPSTREAM	The internal address of the app (e.g., http://localhost:80).
LISTEN	Address to bind (default :8080).
TRUST_PROXY	Set to true when behind an Ingress.
TRUSTED_PROXY_CIDRS	CIDR blocks of the trusted Ingress controllers.

Sources: README.md:76-118, src/config.rs:11-37

Conclusion

Hodor is optimized for Kubernetes deployments as a sidecar proxy. Its minimal footprint (~5MB scratch image), native health check endpoints, and support for standard proxy headers make it a suitable choice for adding a simple authentication layer to internal or preview web services.

Sources: README.md:22, AGENTS.md:7-9