Docker & Kubernetes Deployment
Relevant source files
The following files were used as context for generating this wiki page:
Hoop deployment infrastructure is designed for containerized environments, supporting both standalone Docker instances and scalable Kubernetes clusters. The deployment architecture separates the core gateway from the distributed agents that connect to target infrastructure. Users can deploy the gateway via Docker Compose or Helm charts, while agents are deployed via Docker containers, Kubernetes sidecars, or standalone pods to facilitate secure access to databases, servers, and APIs.
The deployment process typically involves setting up a core gateway—which handles authentication, session recording, and data masking—and then connecting one or more agents. Agents utilize a unique HOOP_KEY for standard authentication or SPIFFE-based identities for automated workload attestation in Kubernetes environments.
Sources: README.md:12-25, webapp_v2/src/pages/Agents/Create/DeploymentInstructions.jsx:132-155, scripts/local-spiffe-kubernetes.sh:110-140
Core Deployment Components
The Hoop ecosystem consists of two primary deployable units: the Gateway and the Agent.
Hoop Gateway
The gateway serves as the layer 7 entry point. It is responsible for parsing wire protocols (PostgreSQL, MySQL, SSH, etc.), recording sessions, and applying guardrails. It requires a PostgreSQL database for persistent storage and a JWT_SECRET_KEY for authentication.
Hoop Agent
The agent is the internal bridge to your infrastructure. It runs within your private network and communicates outbound to the gateway. It can be deployed as a standalone container or a Kubernetes deployment.
This diagram illustrates the relationship between the gateway, its database, the agent, and the target infrastructure.
Sources: README.md:155-165, deploy/helm-chart/chart/gateway/templates/deployment.yaml:45-75
Docker Deployment
Docker is the recommended method for quick starts and local testing. The project provides an installation script and a Docker Compose configuration to orchestrate the gateway and its dependencies.
Installation via Script
The install.sh script automates the requirement checks (curl, docker, docker-compose) and environment setup. It generates a random JWT_SECRET_KEY and downloads the latest docker-compose.yml.
Sources: scripts/install.sh:90-120
Manual Docker Container Run
Agents can be started manually using the hoophq/hoopdev image. The agent requires the HOOP_KEY environment variable to authenticate with the gateway.
docker container run \
-e HOOP_KEY='<YOUR_HOOP_KEY>' \
--rm -d hoophq/hoopdev
Sources: webapp_v2/src/pages/Agents/Create/DeploymentInstructions.jsx:26-30
Docker Configuration Options
| Variable | Description | Default Value |
|---|---|---|
JWT_SECRET_KEY | Key for signing JWT tokens | Randomly generated by script |
HOOP_KEY | Authentication key for agents | Required for agents |
POSTGRES_DB_URI | Connection string for the gateway DB | Required for gateway |
Sources: scripts/install.sh:135-150, webapp_v2/src/pages/Agents/Create/DeploymentInstructions.jsx:48-60
Kubernetes Deployment (Helm)
Kubernetes deployment is managed through Helm charts, offering configurations for both the Gateway (hoop-chart) and the Agent (hoopagent-chart).
Gateway Deployment
The gateway deployment includes options for persistent storage of session recordings and integrated agents.
- Ports: Grpc (8010), API (8009), RDP (13389), and SSH (12222).
- Persistence: A
walsessionsvolume can be mounted to/opt/hoop/sessionsvia PersistentVolumeClaims. - Default Agent: The gateway chart includes an optional sidecar/secondary container for a
defaultagent.
Sources: deploy/helm-chart/chart/gateway/templates/deployment.yaml:55-100
Agent Deployment
Agents are deployed using the hoopagent-chart. They can be configured with standard environment variables or through SPIFFE for identity-based authentication.
This sequence shows the lifecycle of a Kubernetes agent deployment.
Sources: deploy/helm-chart/chart/agent/templates/deployment.yaml:40-60, webapp_v2/src/pages/Agents/Create/DeploymentInstructions.jsx:105-115
SPIFFE Integration
For advanced security, the agent chart supports SPIFFE (Secure Production Identity Framework for Everyone). This allows agents to authenticate using JWT-SVIDs provided by a SPIFFE Workload API (e.g., SPIRE).
- SPIFFE Workload API: Can be accessed via a hostPath socket or a CSI driver.
- SPIFFE Helper: An auxiliary container (
spiffe-helper) can be deployed alongside the agent to manage token rotation.
Sources: deploy/helm-chart/chart/agent/templates/deployment.yaml:65-115, scripts/local-spiffe-kubernetes.sh:130-150
Configuration Management
Deployment configurations are summarized in the following table:
| Parameter | Type | Source File | Description |
|---|---|---|---|
config.HOOP_KEY | String | Agent Chart | The unique key used to authenticate an agent. |
image.repository | String | Gateway Chart | The Docker image for the gateway (default: hoophq/hoop). |
spiffe.enabled | Boolean | Agent Chart | Enables identity-based authentication for K8s workloads. |
persistence.enabled | Boolean | Gateway Chart | Enables PVC for session logs. |
Sources: deploy/helm-chart/chart/gateway/templates/deployment.yaml:80-95, deploy/helm-chart/chart/agent/templates/deployment.yaml:63, deploy/helm-chart/README.md:15-30
Summary
The Hoop deployment framework provides flexible options ranging from single-command Docker setups to complex Kubernetes deployments with SPIFFE security. By separating the gateway (central control) and agents (local execution), the architecture ensures that internal infrastructure remains protected while allowing engineers and AI agents to access production resources securely through a centralized, audited layer 7 gateway.
Sources: README.md:150-170, scripts/install.sh:180-200