Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
- charts/agh2/README.md
- charts/agh2/Chart.yaml
- charts/agh2/templates/base/shared-configmap.yml
- charts/agh2/templates/captain/captain-deployment.yml
- charts/agh2/templates/db/postgres-init-configmap.yml
- charts/agh2/templates/validations/index.yaml
- charts/agh2/values.yaml
- charts/agh3/README.md
- charts/agh3/Chart.yaml
- charts/agh3/crds/actions.crds.yaml
- charts/agh3/templates/captain/captain-deployment.yml
- charts/agh3/templates/db/postgres-init-configmap.yml
- charts/agh3/templates/validations/index.yaml
- charts/agh3/values.yaml
- charts/playground/Chart.yaml
- charts/playground/templates/playground-deployment.yml
- charts/playground/values.yaml
This document provides a guide to deploying the applications contained within this Helm repository. The repository primarily hosts charts for agh2 (ArgusHack2) and agh3 (ArgusHack3), which are comprehensive application suites, as well as a playground chart for a frontend user interface. These charts manage the deployment of various microservices, their dependencies like databases and object storage, and Kubernetes resources.
Getting started involves selecting the appropriate chart, configuring its values.yaml file to match your environment's requirements (such as registry credentials, database connections, and ingress settings), and then using the Helm CLI to install the chart into your Kubernetes cluster. The charts are designed to be flexible, supporting both internal, containerized dependencies and connections to external services.
Helm Chart Overview
The repository contains several application charts, each with its own set of components and dependencies.
| Chart Name | Description | App Version (at time of writing) |
|---|---|---|
agh2 | A Helm chart for ArgusHack2. | 240205 |
agh3 | A Helm chart for ArgusHack3. | v3.12.0 |
agh3-playground | A Helm chart for ArgusHack3 Playground. | v1.6.12 |
Sources: charts/agh2/Chart.yaml:2,20, charts/agh3/Chart.yaml:2,20, charts/playground/Chart.yaml:2,18
Prerequisites & Configuration
Before installing any chart, you must configure several key parameters in the values.yaml file. The charts include validation checks that will cause the installation to fail if required values are missing.
Sources: charts/agh2/templates/validations/index.yaml, charts/agh3/templates/validations/index.yaml
Custom Docker Registry
If your container images are hosted in a private registry, you must provide authentication details.
| Parameter | Description | Default Value |
|---|---|---|
customRegistrySecret.enabled | Set to true to generate a registry secret. | true |
customRegistrySecret.auth.registry | The URL of the private Docker registry. | registry.lkc-lab.com |
customRegistrySecret.auth.username | Username for registry authentication. | "" |
customRegistrySecret.auth.password | Password for registry authentication. | "" |
Sources: charts/agh3/values.yaml:63-74, charts/agh2/values.yaml:20-31, charts/playground/values.yaml:22-33
Keygen Configuration
The charts require a Keygen account for licensing and artifact downloads. These values are mandatory if keygen.enabled is true.
| Parameter | Description | Default Value |
|---|---|---|
keygen.enabled | Set to true to enable Keygen integration. | true |
keygen.apiToken | Your Keygen API token. | "" |
keygen.accountID | Your Keygen Account ID. | "" |
keygen.url | The Keygen API endpoint URL (AGH3 only). | https://api.keygen.sh |
Sources: charts/agh3/values.yaml:80-92, charts/agh2/values.yaml:37-50, charts/agh3/templates/validations/index.yaml:3-14
Ingress and TLS
You can configure Ingress to expose the application to external traffic.
| Parameter | Description | Default Value |
|---|---|---|
ingress.enabled | Enables the creation of Ingress resources. | true |
ingress.host | The hostname for the Ingress. | app.argushack.com (agh3) |
ingress.tls.enabled | If true, a TLS secret will be used. | false |
ingress.tls.secretName | The name of the Kubernetes secret for TLS. | agh-tls |
ingress.tls.cert | The server certificate content. | "" |
ingress.tls.key | The server private key content. | "" |
Sources: charts/agh3/values.yaml:94-111, charts/agh2/values.yaml:52-69
Core Dependencies
The charts manage several stateful dependencies. You can use the internally deployed versions or connect to external instances.
Database (PostgreSQL)
Both agh2 and agh3 charts can deploy a PostgreSQL database internally or connect to an external one.
- Internal Mode: If
db.connection.typeisinternal, the chart deploys PostgreSQL as a dependency. - External Mode: If
db.connection.typeisexternal, you must providedb.connection.hostanddb.connection.port.
Sources: charts/agh3/values.yaml:114-121, charts/agh2/values.yaml:72-79
Database Initialization
When an internal database is enabled, a ConfigMap is created to run initialization scripts. This process sets up databases and roles for the various application modules.
The diagram below illustrates the database initialization flow for the agh2 chart.
Key steps in the initialization script include:
- AGH2 Attack Dataset: Downloads and imports an
attack.sqldataset from a Keygen artifact URL. - Role and Database Creation: Iterates through enabled modules (like
captain,core) and creates a dedicated role and database for each, as defined invalues.yaml. - PGroonga Extension (AGH2): If
db.helpers.init.dbs.installPgroongaExtensionsis true, it installs thepgroongaextension in each created database.
Sources: charts/agh2/templates/db/postgres-init-configmap.yml:9-25, 60-66, charts/agh3/templates/db/postgres-init-configmap.yml:9-60
Other Dependencies
The charts also manage other dependencies, configurable via values.yaml.
| Dependency | Chart(s) | Description |
|---|---|---|
| Minio | agh2, agh3 | Object storage. Can be internal or external. The agh3 chart provisions buckets and policies for different services. |
| RabbitMQ | agh3 | Message queue for asynchronous tasks, such as handling Action CRD results. |
| Redis | agh2, agh3 | In-memory data store used for caching. |
| Memcached | agh3 | Optionally enabled for caching with Grafana Loki and Tempo. |
Sources: charts/agh3/Chart.yaml:21-58, charts/agh2/Chart.yaml:21-32, charts/agh3/values.yaml:258, 482, 529, 878
Application Components
The Helm charts deploy a suite of microservices that form the complete application.
AGH3 Components
The agh3 chart deploys a set of controllers and services that work together. The captain service acts as the main API backend, while actionLoop and controller manage custom Kubernetes resources.
The following diagram shows the high-level components of the AGH3 deployment.
| Component | Image Repository | Description |
|---|---|---|
actionLoop | leukocyte-lab/argushack3/ctr-actionloop | A controller that likely processes Action resources. |
captain | leukocyte-lab/argushack3/ctr-captain | The main backend API service. |
controller | leukocyte-lab/argushack3/ctr-controller | A controller that manages the lifecycle of Action workers. |
ui | leukocyte-lab/argushack3/ctr-ui | The frontend user interface. |
report | leukocyte-lab/argushack3/report | A service for generating reports. |
Sources: charts/agh3/values.yaml:640-809
AGH2 Components
The agh2 chart deploys a different set of services.
| Component | Image Repository | Description |
|---|---|---|
captain | leukocyte-lab/argushack2/captain | The main backend API service. |
core | leukocyte-lab/argushack2/core | A core backend service. |
exploitmgr | leukocyte-lab/argushack2/exploitmgr | An exploit manager service. |
ui | leukocyte-lab/argushack2/frontend | The frontend user interface. |
checkinDaemon | leukocyte-lab/argushack2/checkin-daemon | A cronjob associated with the captain service. |
Sources: charts/agh2/values.yaml:261-419
Playground Component
The playground chart deploys a standalone UI that connects to a backend service, typically the captain API from an agh3 deployment.
| Parameter | Description |
|---|---|
playground.service.backendRef.name | The name of the backend Kubernetes service to connect to. |
playground.service.backendRef.port | The port of the backend service. |
playground.service.ai.endpoint | The full URL for the AI service endpoint. |
Sources: charts/playground/values.yaml:104-118, charts/playground/templates/playground-deployment.yml:19-23
Advanced Features (AGH3)
Action Custom Resource (CRD)
The agh3 chart installs a CustomResourceDefinition (CRD) for actions.agh.lkc-lab.com. This resource, Action, allows users to define and execute container-based jobs within the cluster.
The diagram below outlines the structure of the ActionSpec.
Key fields in the ActionSpec (version v3alpha2) include:
containers: Defines the main containers for the worker pod.initContainers: Defines init containers for the worker pod.historyID: An identifier to group related actions.judgement: A special post-hook that runs only if the main action succeeds.packet: Configuration to enable a packet capture sidecar.
Sources: charts/agh3d/crds/actions.crds.yaml:1000-1078
Observability Stack
The agh3 chart includes an optional, extensive observability stack. When enabled, it deploys the following components:
- Vector: A log and metrics agent, configured as a sidecar for
captain,action-loop, andcontroller. - Grafana: For visualization of metrics, logs, and traces.
- Grafana Tempo: A distributed tracing backend.
- Grafana Loki: A log aggregation system.
Sources: charts/agh3/values.yaml:812-928
Installation
Once your values.yaml is configured, you can install the chart using the Helm CLI. First, add the repository:
helm repo add lkclab https://charts.lkc-lab.com/
helm repo update
Then, install the desired chart (e.g., agh3):
helm install agh3 lkclab/agh3 -f my-values.yaml
Sources: charts/agh3/README.md:3-8