AGH3 Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• charts/agh3/crds/actions.crds.yaml
• charts/agh3/values.yaml
• charts/agh3/Chart.yaml
• charts/agh3/templates/captain/captain-deployment.yml
• charts/agh3/templates/actionloop/actionloop-deployment.yml
• charts/agh3/templates/controller/controller-deployment.yml
• charts/agh2/templates/db/postgres-init-configmap.yml
• charts/agh3/templates/validations/index.yaml

AGH3 (ArgusHack3) is a comprehensive system deployed via a Helm chart, designed as a microservices-based application. It leverages Kubernetes-native features, including Custom Resource Definitions (CRDs), to orchestrate complex, container-based tasks. The architecture is composed of several core application services, such as captain, controller, actionLoop, and a ui, which work in concert with a suite of backing services for persistence, messaging, and caching.

The system is highly configurable through the Helm chart's values.yaml, allowing for both internal, chart-managed dependencies and connections to external services. Key dependencies include PostgreSQL for database storage, Minio for object storage, RabbitMQ for message queuing, and Redis for caching. The central orchestration mechanism revolves around the Action CRD, which defines custom workloads that are managed by the agh3-controller and executed as pods within the Kubernetes cluster.

Sources: charts/agh3/Chart.yaml, charts/agh3/values.yaml, charts/agh3/crds/actions.crds.yaml

High-Level Architecture

The AGH3 system is composed of core components that manage application logic and a set of stateful services that provide backend support. The captain service acts as the primary API and control plane, while the controller and actionLoop components manage the lifecycle of custom tasks defined by the Action CRD.

This diagram illustrates the main components and their interactions with backing services.

Core Components

AGH3's functionality is distributed across several microservices, each with a distinct responsibility.

Sources: charts/agh3/values.yaml:633-856

Captain (captain)

The captain service is the central command module. It exposes an API for the UI and other services, manages database records, and orchestrates the creation of Action resources.

• Image: leukocyte-lab/argushack3/ctr-captain
• Responsibilities:
  • Provides the main API endpoint (port 8080).
  • Interacts with PostgreSQL for persistent data storage.
  • Uses Minio for object storage.
  • Communicates with other services via RabbitMQ.
  • Utilizes Redis for caching.
  • Manages authentication and authorization, with optional OIDC integration.
• Dependencies: PostgreSQL, Redis, Minio, RabbitMQ. Init containers ensure these dependencies are ready before the captain container starts.

Sources: charts/agh3/values.yaml:666-757, charts/agh3/templates/captain/captain-deployment.yml:1-182

Controller (controller)

The controller is a Kubernetes operator that watches for Action Custom Resources. Its primary role is to translate an Action CR into a runnable Kubernetes workload (a Pod or Job).

• Image: leukocyte-lab/argushack3/ctr-controller
• Responsibilities:
  • Watches Action resources in the cluster.
  • Creates worker pods/jobs based on the spec of the Action CR.
  • Updates the status of the Action CR to reflect the state of the worker.
• Configuration: It requires RBAC permissions to manage pods and Action resources within the namespace.

Sources: charts/agh3/values.yaml:806-843, charts/agh3/templates/controller/controller-deployment.yml

ActionLoop (actionLoop)

The actionLoop component is a consumer that listens for messages on a RabbitMQ queue. It processes the results of completed actions.

• Image: leukocyte-lab/argushack3/ctr-actionloop
• Responsibilities:
  • Listens to the action_crd_result queue in RabbitMQ.
  • Processes results from worker pods.
• Configuration: It is configured with RabbitMQ connection details and requires RBAC permissions to interact with cluster resources if needed.

Sources: charts/agh3/values.yaml:633-663, charts/agh3/templates/actionloop/actionloop-deployment.yml

Other Components

• UI (ui): A frontend application that provides the user interface for interacting with the AGH3 system. It communicates with the captain service's API.
• Report (report): A service responsible for generating reports. It likely queries the database and object storage for data.
• Playground (agh3-playground): A separate, optional module that provides an interactive environment, connecting to a backend service (like captain) and an AI service endpoint.

Sources: charts/agh3/values.yaml:846-881, charts/playground/values.yaml:1-125

Backing Services (Dependencies)

AGH3 relies on several stateful services which can be deployed internally as part of the Helm release or connected to as external services.

Sources: charts/agh3/Chart.yaml:15-58, charts/agh3/values.yaml:166-630

Service	Internal Chart	Default Image	Purpose
PostgreSQL	bitnami/postgresql	docker/bitnamilegacy/postgresql:15.7.0	Primary relational database for storing application data like users, actions, and results.
Minio	bitnami/minio	docker/bitnamilegacy/minio:2024.11.7-debian-12-r2	S3-compatible object storage for files, reports, and other large data.
RabbitMQ	bitnami/rabbitmq	docker/bitnamilegacy/rabbitmq:3.12.13-debian-12-r2	Message broker for asynchronous communication between services, particularly for action results.
Redis	bitnami/redis	docker/bitnamilegacy/redis:7.4.0	In-memory key-value store used for caching and session management.

Sources: charts/agh3/Chart.yaml:15-58, charts/agh3/values.yaml:220-630

Minio Configuration

When deployed internally, the Helm chart automatically provisions Minio with specific buckets and access policies for the AGH3 components.

Provisioned Buckets:

• intelli-bridge
• embedding
• packet
• integration
• report-setting
• review

Example Access Policy (agh-ai-policy):
This policy grants permissions to services like the AI parser to read and write to specific buckets.

{
  "effect": "Allow",
  "resources": [
    "arn:aws:s3:::intelli-bridge/*",
    "arn:aws:s3:::intelli-bridge",
    "arn:aws:s3:::embedding/*",
    "arn:aws:s3:::embedding",
    "arn:aws:s3:::integration/*",
    "arn:aws:s3:::integration",
    "arn:aws:s3:::review/*",
    "arn:aws:s3:::review"
  ],
  "actions": [
    "s3:GetBucketLocation",
    "s3:PutObject",
    "s3:GetObject",
    "s3:ListBucket",
    "s3:HeadBucket",
    "s3:ListMultipartUploadParts",
    "s3:AbortMultipartUpload",
    "s3:ListBucketMultipartUploads"
  ]
}

Sources: charts/agh3/values.yaml:372-436

The Action Custom Resource Definition (CRD)

The core of AGH3's dynamic task execution is the Action CRD (actions.agh.lkc-lab.com). This resource allows users to define a multi-container pod specification that can be executed on the cluster.

The diagram below shows the structure of the Action resource.

Key spec Fields

• historyID: A string to group related Action instances.
• containers: An array defining the main containers for the worker pod, following the standard Kubernetes Container spec.
• initContainers: An array defining init containers for the worker pod.
• packet: An object to enable and configure packet capture for the action.
• judgement: A special post-hook action that runs only if the main action containers succeed.
• isRoot: A boolean to identify the first action in a chain.

Sources: charts/agh3/crds/actions.crds.yaml:1040-1170

Action Execution Flow

The execution of a task in AGH3 follows an event-driven flow orchestrated by the Action CRD and its controllers.

This sequence diagram shows how an Action is created and processed.

1. Creation: The captain service (or another authorized entity) creates an Action custom resource via the Kubernetes API.
2. Detection: The agh3-controller is watching for Action resources and detects the newly created instance.
3. Pod Creation: The controller reads the Action.spec and creates a new worker Pod configured with the specified initContainers and containers.
4. Execution: The worker Pod runs its defined command/args. During or after execution, it may interact with Minio for object storage.
5. Result Publishing: Upon completion, the worker pod is expected to publish its results to the action_crd_result queue in RabbitMQ.
6. Result Processing: The agh3-actionloop service, which is subscribed to this queue, receives the result message and performs any necessary follow-up processing.

Sources: charts/agh3/crds/actions.crds.yaml, charts/agh3/templates/controller/controller-deployment.yml, charts/agh3/templates/actionloop/actionloop-deployment.yml, charts/agh3/values.yaml:523-524

Configuration and Validation

The AGH3 Helm chart includes validation logic to ensure that all required values are provided before an installation or upgrade can proceed.

For example, if external databases or message queues are used, the chart requires their connection details to be specified. The following snippet from the validation template checks for external RabbitMQ configuration:

{{- if eq .Values.rabbitmq.connection.type "external" -}}
  {{- $errorMsg = printf "%s\n%s"
      $errorMsg
      (
        include "validations.required" (
          dict
            "path" "rabbitmq.connection"
            "fields" (list "host" "port")
            "msg" "Must provide when rabbitmq.connection is external"
            "context" $
        )
      )
  -}}
{{- end -}}

This ensures that if rabbitmq.connection.type is set to external, the rabbitmq.connection.host and rabbitmq.connection.port values must also be set. Similar checks exist for db, minio, keygen, and OIDC configurations.

Sources: charts/agh3/templates/validations/index.yaml:1-73

Summary

The AGH3 architecture is a robust, cloud-native system that effectively utilizes Kubernetes for orchestrating containerized tasks. By defining its core logic in a set of cooperating microservices and leveraging a custom Action CRD, it provides a flexible and extensible platform. The use of standard backing services like PostgreSQL, Minio, and RabbitMQ ensures reliable data persistence and asynchronous communication, while the Helm chart packaging provides a configurable and reproducible deployment process.

Sources: charts/agh3/Chart.yaml, charts/agh3/values.yaml, charts/agh3/crds/actions.crds.yaml