AGH3 Component: Captain
Relevant source files
The following files were used as context for generating this wiki page:- charts/agh3/templates/captain/captain-deployment.yml
- charts/agh3/templates/captain/captain-oidc-secret.yml
- charts/agh3/templates/captain/captain-clusterrole.yml
- charts/agh3/values.yaml
- charts/agh3/templates/captain/captain-service.yml
- charts/agh3/templates/captain/captain-db-secret.yml
- charts/agh3/templates/captain/captain-superadmin-secret.yml
- charts/agh3/README.md
The Captain component is a core module within the ArgusHack3 (AGH3) platform, acting as a central control and management service. It is responsible for handling various aspects of the system, including managing custom resources, interacting with backend services, and providing an API for the user interface. Its deployment is conditional on being enabled in the Helm chart values.
Captain integrates with multiple other services such as PostgreSQL, Redis, Minio, and RabbitMQ to perform its functions. It also has extensive RBAC permissions to manage Kubernetes resources like Actions, Jobs, Pods, and Secrets, highlighting its role as a key operator within the AGH3 ecosystem.
Deployment Architecture
The Captain component is deployed as a Kubernetes Deployment. Its architecture includes several init containers to ensure dependencies are ready, a main application container, and an optional sidecar for log shipping.
Sources: charts/agh3/templates/captain/captain-deployment.yml
Pod Initialization and Dependencies
Before the main Captain container starts, a series of init containers run to verify that all required external services are available. This prevents the application from starting in a faulty state.
The diagram below shows the startup sequence for the Captain pod.
The init containers use simple commands to check for service availability:
- Redis:
redis-cli -h redis-master... ping - Minio:
curl http://minio... - RabbitMQ:
curl ... /api/health/checks/virtual-hosts - PostgreSQL:
pg_isready -d $PG_CONN_STR
Sources: charts/agh3/templates/captain/captain-deployment.yml:18-68
Container Specification
The Captain pod consists of one primary container and one optional sidecar container.
| Container | Purpose | Image Source |
|---|---|---|
captain | The main application logic for the Captain service. | leukocyte-lab/argushack3/ctr-captain:v1.16.4 (from values.yaml) |
vector | An optional sidecar for log collection and forwarding. Enabled by vector.enabled. | timberio/vector:latest-debian (from values.yaml) |
Sources: charts/agh3/values.yaml:636-641, 915-920, charts/agh3/templates/captain/captain-deployment.yml:78-91, 92-225
Health Probes
To ensure the Captain service is running correctly, a liveness probe is configured.
| Probe Type | Endpoint | Port | Initial Delay | Period | Timeout | Failure Threshold |
|---|---|---|---|---|---|---|
| Liveness | GET /api/healthz | 8080 | 15s | 20s | 10s | 3 |
If the probe fails three consecutive times, the container will be restarted.
Sources: charts/agh3/templates/captain/captain-deployment.yml:209-216
Configuration
Captain's configuration is managed through Helm values.yaml and passed to the container as environment variables.
values.yaml Parameters
The following table details the configuration options available for the Captain component in values.yaml.
| Parameter | Description | Default Value |
|---|---|---|
captain.enabled | Enable the Captain module. | true |
captain.image.repository | Captain container image repository. | leukocyte-lab/argushack3/ctr-captain |
captain.image.tag | Captain container image tag. | v1.16.4 |
captain.secret.enabled | Master switch to enable secret generation for Captain. | true |
captain.secret.db.enabled | Enable secret generation for the Captain database. | true |
captain.secret.db.secretName | Name of the Kubernetes secret for DB credentials. | capt-db-secret |
captain.secret.minio.enabled | Enable secret generation for Minio. | true |
captain.secret.minio.secretName | Name of the Kubernetes secret for Minio credentials. | capt-minio-secret |
captain.secret.jwt.enabled | Enable secret generation for JWT. | true |
captain.secret.jwt.secretName | Name of the Kubernetes secret for the JWT secret. | capt-jwt-secret |
captain.secret.superadmin.enabled | Enable secret generation for the Super Admin password. | true |
captain.secret.superadmin.secretName | Name of the secret for the Super Admin password. | capt-superadmin-password |
captain.secret.oidc.enabled | Enable OIDC integration and secret generation. | false |
captain.secret.oidc.secretName | Name of the secret for OIDC configuration. | capt-oidc-secret |
captain.serviceAccount.create | Create a ServiceAccount for Captain. | true |
captain.serviceAccount.name | Name of the ServiceAccount. | captain-sa |
captain.rbac.create | Create RBAC ClusterRole and ClusterRoleBinding. | true |
captain.extraEnv | A map of additional environment variables to inject. | {} |
Sources: charts/agh3/values.yaml:631-700, charts/agh3/README.md:377-410
Environment Variables
The Captain container is configured via a set of environment variables, which are sourced from values.yaml, Kubernetes secrets, and the pod's own metadata.
| Environment Variable | Description | Source |
|---|---|---|
IMAGE_REGISTRY_URL | The URL of the global image registry. | values.global.imageRegistry |
NAMESPACE | The Kubernetes namespace the pod is running in. | fieldRef: metadata.namespace |
OTEL_COLLECTOR_URL | OpenTelemetry collector endpoint (if Grafana Tempo is enabled). | grafana-tempo-distributor... |
REDIS_URL | The connection URL for Redis. | redis-master.$(NAMESPACE)... |
REDIS_PASSWORD | The password for Redis authentication. | Secret: agh-redis-secret |
SUPERADMIN_PASSWORD | The password for the superadmin account. | Secret: capt-superadmin-password |
REPORT_URL | The internal URL for the report service. | http://report.$(NAMESPACE)... |
SMTP_HOST / SMTP_PORT | SMTP server details (if Postfix is enabled). | postfix.$(NAMESPACE)... |
KEYGEN_URL | The endpoint URL for the Keygen licensing service. | values.keygen.url |
DB_Conn | The PostgreSQL connection string. | Secret: capt-db-secret |
Web_Host_Port | The address and port the web server listens on. | 0.0.0.0:8080 |
SECRET_JWT | The secret key for signing JWTs. | Secret: capt-jwt-secret |
MINIO_URL / USER / PASSWORD | Minio connection details. | Secrets: minio-secret, capt-minio-secret |
RABBITMQ_QUEUE | The name of the RabbitMQ queue to use. | values.rabbitmq.queueName |
RABBITMQ_Conn | The RabbitMQ connection string. | Secret: agh-rabbitmq-secret-connection |
APP_VERSION / CHART_VERSION | Application and Helm chart versions. | Chart.AppVersion, Chart.Version |
OIDC_* | OIDC configuration (URL, Client ID/Secret, Realm). | Secret: capt-oidc-secret (optional) |
Sources: charts/agh3/templates/captain/captain-deployment.yml:100-202
Security and Access Control
Secrets Management
Captain relies on several Kubernetes Secrets for its operation. These secrets are either pre-created or generated by the Helm chart based on values provided.
The diagram below illustrates the secrets consumed by the Captain pod.
- Database Secret: Contains the
DB_CONN_STRfor connecting to PostgreSQL.
Sources: charts/agh3/templates/captain/captain-db-secret.yml - Superadmin Secret: Contains the
SUPERADMIN_PASSWORD.
Sources: charts/agh3/templates/captain/captain-superadmin-secret.yml - OIDC Secret: Optionally contains OIDC provider details (
url,client-id,client-secret,realm).
Sources: charts/agh3/templates/captain/captain-oidc-secret.yml - Other Secrets: Credentials for Minio, JWT, Redis, and RabbitMQ are drawn from their respective secrets defined in
values.yaml.
Sources: charts/agh3/templates/captain/captain-deployment.yml:120-202
RBAC Permissions
If captain.rbac.create is true, a ClusterRole is created to grant Captain the necessary permissions to manage various resources across the Kubernetes cluster.
| API Group | Resources | Verbs |
|---|---|---|
agh.lkc-lab.com | actions, actions/status | create, delete, get, list, patch, update, watch |
"" (core) | pods, pods/log, pods/status | get, list, watch |
"" (core) | secrets | create, delete, get, list, patch, update, watch |
helm.cattle.io | helmcharts | get, patch, update, watch |
batch | jobs, jobs/status | create, delete, get, list, patch, update, watch |
apps | deployments | get, list, watch |
These permissions allow Captain to orchestrate complex workflows involving custom resources (actions), execute batch jobs, and monitor their status.
Sources: charts/agh3/templates/captain/captain-clusterrole.yml:7-73
Networking
The Captain deployment is exposed within the cluster via a Service resource.
- Service Name:
captain - Service Type:
ClusterIP(default) - Port: The service listens on port
8080. - Target Port: Traffic is forwarded to the
httpport on the Captain pods, which is8080.
This allows other components within the same Kubernetes cluster to communicate with the Captain API at the address captain.<namespace>.svc.cluster.local:8080.
Sources: charts/agh3/templates/captain/captain-service.yml
OIDC Integration
Captain supports OpenID Connect (OIDC) for authentication. This feature is disabled by default but can be enabled by setting captain.secret.oidc.enabled to true. When enabled, the chart expects several values to be provided to configure the OIDC connection.
A validation check ensures that if OIDC is enabled, all required fields are provided.
{{- if and .Values.captain.enabled .Values.captain.secret.oidc.enabled -}}
{{- $errorMsg = printf "%s\n%s"
$errorMsg
(
include "validations.required" (
dict
"path" "captain.secret.oidc"
"fields" (list "url" "clientID" "clientSecret" "realm")
"msg" "Must provide when captain.secret.oidc.enabled is true"
"context" $
)
)
-}}
{{- end -}}
The configuration is stored in a secret named capt-oidc-secret and mounted as environment variables (OIDC_LOGIN_URL, OIDC_CLIENT_ID, etc.) in the Captain container.
Sources: charts/agh3/values.yaml:686-694, charts/agh3/templates/validations/index.yaml:63-76, charts/agh3/templates/captain/captain-deployment.yml:181-202