AGH3 Configuration
Relevant source files
The following files were used as context for generating this wiki page:The agh3 Helm chart is designed to deploy the ArgusHack3 application, a complex system composed of multiple microservices and backing services. The configuration, primarily managed through the values.yaml file, provides extensive control over the deployment, from global settings like image registries and proxies to the fine-grained tuning of each application module and its dependencies.
This document outlines the architecture, components, and key configuration parameters for deploying AGH3. It covers the setup of core dependencies such as PostgreSQL, Minio, RabbitMQ, and Redis, as well as the configuration of the main AGH3 application modules including Captain, Controller, and the Action Loop.
Chart Architecture and Dependencies
The AGH3 chart is an 'application' type chart that bundles the ArgusHack3 application and its required services. Many of these services are included as conditional sub-charts, allowing for a flexible deployment where external services can be used instead of the internal, containerized ones.
Sources: charts/agh3/Chart.yaml:1-12
The following diagram illustrates the main chart and its conditional dependencies.
This diagram shows the conditional dependencies of the AGH3 Helm chart as defined in Chart.yaml.
Sources: charts/agh3/Chart.yaml:13-48
Global Parameters
Global parameters apply across all components deployed by the chart, including dependencies. They are used to standardize settings like image sources and proxy configurations.
| Parameter | Description | Default Value |
|---|---|---|
global.imageRegistry | The Docker image registry for all images. | registry.lkc-lab.com |
global.imagePullSecrets | An array of secret names for pulling images from a private registry. | [lkc-registry] |
global.proxy.enabled | If true, enables the use of an HTTP/HTTPS proxy for outbound connections. | false |
global.storageClass | The storage class to use for all Persistent Volume Claims. | "" |
global.volumePermissions.enabled | If true, an init container will be used to set permissions on volume mounts. | true |
Sources: charts/agh3/values.yaml:8-41, charts/agh3/README.md:10-27
Core Services Configuration
The AGH3 chart can deploy and manage its own instances of core services or be configured to connect to external ones.
Database (PostgreSQL)
The chart can deploy an internal PostgreSQL instance or connect to an external one, controlled by db.connection.type.
| Parameter | Description | Default Value |
|---|---|---|
db.connection.type | Set to internal or external. | internal |
db.connection.host | Hostname of the external database. | database.example.com |
db.connection.user | The main database user. | argushack |
db.helpers.init.dbs.enabled | If true, enables a helper job to initialize databases for modules. | true |
postgresql.enabled | Must be true if db.connection.type is internal. | true |
postgresql.auth.username | The initial user for the internal database. | argushack |
postgresql.primary.initdb.enabled | If true, enables the execution of initdb scripts. | true |
postgresql.primary.initdb.scriptsConfigMap | Name of the ConfigMap containing initialization scripts. | db-init-scripts |
Sources: charts/agh3/values.yaml:166-240, charts/agh3/README.md:83-120
Database Initialization Flow
When db.helpers.init.dbs.enabled is true, a ConfigMap is created containing a shell script (init.sh). This script generates an SQL file (init.sql) that creates the necessary roles and databases for each enabled AGH3 module (like Captain). The script then executes init.sql against the PostgreSQL instance.
This diagram shows the automated database initialization process.
Sources: charts/agh3/templates/db/postgres-init-configmap.yml:1-92
Object Storage (Minio)
Minio is used for object storage. It can be deployed internally or an external S3-compatible service can be used.
| Parameter | Description | Default Value |
|---|---|---|
minio.connection.type | Set to internal or external. | internal |
minio.internal.enabled | Must be true if minio.connection.type is internal. | true |
minio.auth.rootUser | The root user for the internal Minio instance. | argushack |
minio.provisioning.enabled | If true, enables a job to create buckets and policies. | true |
minio.provisioning.buckets | A list of buckets to create upon initialization. | [intelli-bridge, embedding, ...] |
minio.provisioning.policies | A list of IAM policies to create. | [agh-controller-policy, ...] |
Sources: charts/agh3/values.yaml:242-378, charts/agh3/README.md:122-151
Message Queue (RabbitMQ)
RabbitMQ is used for asynchronous communication between services, particularly for handling results from the Action CRD.
| Parameter | Description | Default Value |
|---|---|---|
rabbitmq.connection.type | Set to internal or external. | internal |
rabbitmq.queueName | Name of the primary queue for action results. | action_crd_result |
rabbitmq.loadDefinition.enabled | If true, loads definitions (queues, exchanges) from a secret. | true |
rabbitmq.internal.enabled | Must be true if rabbitmq.connection.type is internal. | true |
Sources: charts/agh3/values.yaml:423-524, charts/agh3/README.md:167-198
AGH3 Application Modules
The chart deploys several application modules that form the AGH3 system.
Captain
The Captain module is a central component of AGH3. Its deployment is configured via the captain section and relies on several secrets for its operation.
| Parameter | Description | Default Value |
|---|---|---|
captain.enabled | Enables the deployment of the Captain module. | true |
captain.image.repository | The container image for the Captain module. | leukocyte-lab/argushack3/ctr-captain |
captain.secret.db.enabled | If true, a secret with database credentials for Captain is created. | true |
captain.secret.minio.enabled | If true, a secret with Minio credentials for Captain is created. | true |
captain.secret.jwt.enabled | If true, a secret for JWT is created. | true |
captain.secret.superadmin.enabled | If true, a secret for the superadmin password is created. | true |
captain.secret.oidc.enabled | If true, enables OIDC integration and requires OIDC parameters. | false |
Sources: charts/agh3/values.yaml:556-646, charts/agh3/README.md:200-234
The following diagram shows how the Captain pod is initialized and configured.
This sequence shows the startup process for the Captain deployment, including dependency checks by init containers and configuration loading.
Sources: charts/agh3/templates/captain/captain-deployment.yml:1-205
Action Loop & Controller
- Action Loop (
actionLoop): This module is responsible for processing actions. It can be scaled by settingreplicaCount. - Controller (
controller): This module manages the lifecycle ofActioncustom resources.
| Parameter | Description | Default Value |
|---|---|---|
actionLoop.enabled | Enables the Action Loop module. | true |
actionLoop.replicaCount | Number of replicas for the Action Loop deployment. | 3 |
controller.enabled | Enables the Controller module. | true |
controller.secret.minio.enabled | If true, creates a Minio secret for the controller. | true |
Sources: charts/agh3/values.yaml:526-554, charts/agh3/values.yaml:705-748
Action Custom Resource Definition (CRD)
The chart installs the actions.agh.lkc-lab.com CRD, which is fundamental to the system's operation. This resource defines a unit of work to be executed by the system. The CRD has multiple versions (v1, v2, v3alpha1, v3alpha2), with v3alpha2 being the latest storage version.
Sources: charts/agh3/crds/actions.crds.yaml:1-14777
ActionSpec v3alpha2
The spec of the Action resource defines the work to be done.
| Field | Description | Type |
|---|---|---|
containers | Defines the main containers for the worker pod that executes the action. | array |
initContainers | Defines init containers for the worker pod. | array |
historyID | An identifier to group actions from the same historical run. | string |
isRoot | Identifies if this is a root action in a workflow. | boolean |
judgement | A special post-hook that runs only if the main action succeeds. | object |
packet | If enabled, extends the action with a packet capture sidecar. | object |
Sources: charts/agh3/crds/actions.crds.yaml:1044-1471
Configuration Validation
To prevent deployment errors, the chart includes a series of validation checks that run before installation. These checks ensure that required values are provided when certain features are enabled.
The validation logic is defined in templates/validations/index.yaml. If a check fails, the Helm installation will be aborted with an error message.
Examples of validation checks:
- If
keygen.enabledistrue, thenkeygen.accountIDandkeygen.apiTokenmust be set. - If
ingress.tls.enabledistrue, theningress.tls.certandingress.tls.keymust be provided. - If
db.connection.typeisexternal, thendb.connection.hostanddb.connection.portare required.
Sources: charts/agh3/templates/validations/index.yaml:1-73
Conclusion
The AGH3 Helm chart offers a comprehensive and modular way to deploy the ArgusHack3 platform. Its configuration is structured to support both all-in-one internal deployments and integration with existing external services. By leveraging conditional dependencies, automated database initialization, and robust validation, the chart simplifies the management of a complex microservices application in Kubernetes. Understanding the parameters in values.yaml is key to tailoring the deployment to specific infrastructure and security requirements.