Contributing Guide
Relevant source files
The following files were used as context for generating this wiki page:- charts/agh3/Chart.yaml
- charts/agh3/values.yaml
- charts/agh3/README.md
- charts/agh3/templates/captain/captain-deployment.yml
- charts/agh3/templates/db/postgres-init-configmap.yml
- charts/agh3/crds/actions.crds.yaml
- charts/agh3/templates/validations/index.yaml
- charts/agh2/values.yaml
- charts/agh2/templates/db/postgres-init-configmap.yml
This guide provides a technical overview of the helm-charts repository, focusing on the structure, configuration, and deployment logic of the agh2 and agh3 charts. The primary purpose of these charts is to deploy the ArgusHack application suite and its dependencies onto a Kubernetes cluster.
Contributions to this project require an understanding of Helm, Kubernetes, and the specific architecture of the ArgusHack applications. This document outlines the key components, including chart dependencies, configuration through values.yaml, templating logic for generating Kubernetes manifests, and the custom resources that drive application behavior.
Chart Structure and Dependencies
The core of each chart is defined in its Chart.yaml file, which specifies metadata, the application version, and, most importantly, its dependencies on other Helm charts. The agh3 chart, for example, is an 'application' type chart that orchestrates the deployment of numerous services.
Dependencies are conditionally enabled via flags in the values.yaml file. This allows for a flexible deployment where users can choose to use internal, chart-managed instances of services like PostgreSQL and Minio, or connect to external ones.
Sources: charts/agh3/Chart.yaml:1-12, charts/agh2/Chart.yaml:1-12
AGH3 Chart Dependencies
The following diagram illustrates the dependencies for the agh3 chart. Each dependency is only installed if its corresponding condition in Chart.yaml evaluates to true.
This diagram shows the conditional dependencies of the agh3 Helm chart.
Sources: charts/agh3/Chart.yaml:15-51
The dependencies are managed from various repositories and are version-pinned to ensure stable deployments.
| Dependency | Version | Repository | Condition |
|---|---|---|---|
postgresql | 12.1.2 | https://charts.bitnami.com/bitnami | db.internal.enabled |
minio | 14.8.6 | https://charts.bitnami.com/bitnami | minio.internal.enabled |
rabbitmq | 13.0.0 | https://charts.bitnami.com/bitnami | rabbitmq.internal.enabled |
redis | 20.1.0 | https://charts.bitnami.com/bitnami | redis.enabled |
postfix | 0.1.4 | https://charts.lkc-lab.com | postfix.enabled |
grafana | 9.3.0 | https://grafana.github.io/helm-charts | grafana.enabled |
grafana-loki | 6.0.2 | https://charts.bitnami.com/bitnami | grafana-loki.enabled |
grafana-tempo | 4.0.14 | https://charts.bitnami.com/bitnami | grafana-tempo.enabled |
memcached | 7.9.4 | https://charts.bitnami.com/bitnami | memcached.enabled |
Sources: charts/agh3/Chart.yaml:15-51
Configuration (values.yaml)
The values.yaml file is the primary interface for configuring a deployment. It exposes a wide range of parameters that control everything from image registries and application settings to dependency configurations.
Global Parameters
Global parameters apply to the main chart and all its sub-charts, providing a centralized way to configure common settings.
| Parameter | Description | Default Value |
|---|---|---|
global.imageRegistry | Global Docker Image registry. | registry.lkc-lab.com |
global.imagePullSecrets | Global Docker registry secret names. | ["lkc-registry"] |
global.storageClass | Global storage class for dynamic provisioning. | "" |
Sources: charts/agh3/values.yaml:8-14, charts/agh2/values.yaml:8-13
Configuration Validation
Before rendering templates, Helm performs a validation step defined in templates/validations/index.yaml. This template checks for the presence of required values based on which features are enabled. If a required value is missing, the Helm installation will fail with a descriptive error message.
The flowchart below shows the validation logic for several key features.
This diagram depicts the pre-installation validation checks for required configuration values.
Sources: charts/agh3/templates/validations/index.yaml:1-74, charts/agh2/templates/validations/index.yaml:1-55
Templating and Deployment Logic
The templates directory contains the Kubernetes manifest templates. These templates use Go templating syntax to dynamically generate manifests based on the settings in values.yaml.
Captain Deployment
The captain-deployment.yml file is a key component, responsible for deploying the AGH3-Captain module. A notable feature is its use of init containers to ensure that all dependencies (Redis, Minio, RabbitMQ, PostgreSQL) are ready before the main captain container starts.
The following sequence diagram illustrates the startup process for the Captain pod.
This diagram shows the sequence of init containers ensuring service readiness before the main Captain application starts.
Sources: charts/agh3/templates/captain/captain-deployment.yml:10-82
The environment variables for the captain container are dynamically populated from various sources within values.yaml and Kubernetes secrets.
# From charts/agh3/templates/captain/captain-deployment.yml
env:
- name: IMAGE_REGISTRY_URL
value: {{ .Values.global.imageRegistry }}
- name: NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
- name: REDIS_URL
value: "redis-master.$(NAMESPACE).svc.cluster.local:6379"
- name: REDIS_PASSWORD
valueFrom:
secretKeyRef:
name: {{ .Values.redis.secret.secretName }}
key: password
- name: DB_Conn
valueFrom:
secretKeyRef:
name: {{ .Values.captain.secret.db.secretName }}
key: DB_CONN_STR
- name: MINIO_USER
valueFrom:
secretKeyRef:
name: {{ .Values.captain.secret.minio.secretName }}
key: capt-minio-user
Sources: charts/agh3/templates/captain/captain-deployment.yml:100-150
Database Initialization
The charts include a sophisticated database initialization mechanism. When an internal PostgreSQL instance is enabled (db.internal.enabled: true), a ConfigMap is created containing an init.sh script. This script runs inside the PostgreSQL pod on its first startup.
The script dynamically generates SQL commands to:
- Create a main database role (
argushack). - Iterate through all enabled modules in
values.yaml(e.g.,captain,core). - For each module with a
secret.dbconfiguration, it creates a dedicated user and database. - In
agh2, it can also download and import an "attack" dataset and install thepgroongaextension.
The flowchart below outlines this process for the agh3 chart.
This diagram illustrates the logic for generating and executing the database initialization script.
Sources: charts/agh3/templates/db/postgres-init-configmap.yml:1-90, charts/agh2/templates/db/postgres-init-configmap.yml:1-115
Custom Resource Definitions (CRDs)
The agh3 chart installs a CustomResourceDefinition for actions.agh.lkc-lab.com. This CRD defines a new Kubernetes resource kind, Action, which is central to the AGH3-Controller's operation. An Action resource represents a task to be executed in a dedicated worker pod.
The CRD has evolved, with multiple versions (v1, v2, v3alpha1, v3alpha2) defined in the manifest. The storage version is v3alpha2.
Action Spec v3alpha2
The spec of the Action resource defines the desired state of the task.
This diagram shows the main components of the Action.spec field in the v3alpha2 version of the CRD.
Key fields in the spec include:
historyID: Groups actions that belong to the same workflow.containers: Defines the main container(s) for the worker pod, including the image, command, and environment variables.initContainers: Defines init containers for the worker pod.isRoot: Identifies the first action in a chain.packet: Enables a packet capture sidecar.
--judgement: A post-execution hook that runs only if the main action succeeds.
Sources: charts/agh3/crds/actions.crds.yaml:1048-1540
Conclusion
Contributing to the helm-charts repository involves modifying one or more of its core components. Changes to application configuration or default values are made in values.yaml. Adding or altering Kubernetes resources requires editing the templates/ directory. Managing chart dependencies is done in Chart.yaml. For agh3, understanding the Action CRD is crucial for modifying the behavior of the core application logic. Any contribution should be tested to ensure that the validation rules pass and that all components deploy and initialize correctly.