AGH3 Core Concept: The Action CRD
Relevant source files
The following files were used as context for generating this wiki page:
The Action Custom Resource Definition (CRD) is a fundamental component of the AGH3 system, providing a declarative API for defining and executing containerized workloads within a Kubernetes cluster. An Action resource encapsulates the complete specification for a task, including the container images, commands, environment variables, and volumes required for its execution. These resources are managed by controllers within the AGH3 ecosystem, such as the actionLoop and captain modules, which observe Action objects and orchestrate the creation of underlying Kubernetes resources (like Pods or Jobs) to run the defined tasks.
The Action CRD, with the group agh.lkc-lab.com, is designed to be namespaced, allowing for logical separation and management of tasks. It serves as the primary mechanism for triggering ad-hoc or chained operations, with features for defining execution history, post-execution hooks (judgement), and packet capture. The lifecycle of an Action is tracked through its status field, providing visibility into the state of the task, from Pending to completion.
CRD Installation
The Action CRD is not applied directly to the cluster. Instead, its installation is managed by the Helm chart's lifecycle using a pre-install/pre-upgrade hook. This ensures the CRD is available before any other chart resources that depend on it are created.
The installation process is as follows:
- During a
helm installorhelm upgrade, a Helm hook creates aConfigMap. - This
ConfigMapcontains the entireactions.crds.yamldefinition file. - A Kubernetes Job, using a
kubectlimage, is then launched. This job mounts theConfigMapand useskubectl applyto install or update theActionCRD in the cluster.
Sources: charts/agh3/templates/hooks/pre/crds/0-actions-crd-cm.yml, charts/agh3/values.yaml:30-47
This diagram illustrates the CRD installation flow managed by Helm.
Action CRD Schema
The Action CRD has evolved through several versions, with v3alpha2 being the current storage version. It defines the desired state (spec) and the observed state (status) of a task.
Sources: charts/agh3/crds/actions.crds.yaml:1418-1420
Spec (ActionSpec)
The spec field details the task to be executed. The primary fields for the v3alpha2 version are outlined below.
This diagram shows the high-level structure of the ActionSpec.
Key Spec Fields
| Field | Type | Description | Required |
|---|---|---|---|
historyID | string | A unique identifier to group actions that are part of the same execution chain or history. | Yes |
containers | array | Defines the main containers for the worker Pod. At least one container must be specified. | Yes |
initContainers | array | Defines init containers that run to completion before the main containers are started. | No |
isRoot | boolean | Identifies if this action is the first or "root" action in a chain. Defaults to false. | No |
hostAliases | array | A list of host-to-IP mappings to be injected into the worker Pod's /etc/hosts file, similar to the standard Kubernetes hostAliases. | No |
packet | object | Configures the packet capture sidecar. If enabled, network traffic for the action's worker will be captured. | No |
judgement | object | A special post-execution hook. Defines containers that run only if the main action's containers complete successfully. | No |
Sources: charts/agh3/crds/actions.crds.yaml:1422-1876
Container Definition
Both containers and initContainers share the same structure, which is a simplified version of the standard Kubernetes Container spec.
| Field | Type | Description |
|---|---|---|
image | string | The container image to run. This is a required field. |
command | array | The entrypoint of the container. |
args | array | Arguments to the container's entrypoint. |
Envs | array | A list of environment variables to set in the container, supporting direct values and references. |
volumeMounts | object | A map of volume mount paths. The key is the mount path and the value is the name of the volume. |
workingDir | string | The working directory for the container. |
Sources: charts/agh3/crds/actions.crds.yaml:1426-1481
judgement Spec
The judgement field allows for defining a conditional follow-up task. It has its own containers and initContainers fields, which are executed in a new worker only upon the successful completion of the parent Action.
Sources: charts/agh3/crds/actions.crds.yaml:1669-1845
packet Spec
The packet field enables network traffic capture for the worker.
| Field | Type | Description |
|---|---|---|
enabled | boolean | If true, enables the packet capture feature. |
location | string | Specifies the location (e.g., a storage path) where captures are stored. |
Sources: charts/agh3/crds/actions.crds.yaml:1846-1859
Status (ActionStatus)
The status field provides the observed state of the Action resource, updated by the controller.
| Field | Type | Description |
|---|---|---|
activeStatus | string | The current phase of the action. Defaults to Pending. Other potential values include Running, Succeeded, Failed. |
worker | ObjectReference | A reference to the Kubernetes object (e.g., Pod) that is executing the action's workload. |
Sources: charts/agh3/crds/actions.crds.yaml:1878-1925
Controllers and Lifecycle
The Action resources are managed by controllers deployed as part of the AGH3 Helm chart. The actionLoop and captain modules are key components in this process.
captain: This is a high-level controller that likely translates business logic or user requests intoActionCRs. It connects to the database, message queue (RabbitMQ), and object storage (Minio), indicating its central role in orchestration.actionLoop: This controller appears to be the primary processor forActionresources. It also connects to the core infrastructure (DB, Redis, RabbitMQ) and likely watches for new or updatedActionCRs to execute. TheactionLoopdeployment is configured with 3 replicas for high availability.
Sources: charts/agh3/templates/captain/captain-deployment.yml, charts/agh3/templates/actionloop/actionloop-deployment.yml, charts/agh3/values.yaml:630-633
The following diagram shows a simplified sequence of an Action being created and processed.
This diagram is an inferred representation based on the roles of the captain and actionloop controllers and the Action CRD schema.
Sources: charts/agh3/crds/actions.crds.yaml, charts/agh3/templates/actionloop/actionloop-deployment.yml, charts/agh3/templates/captain/captain-deployment.yml
Summary
The Action CRD is a core abstraction in AGH3 for defining and running tasks. It provides a structured, Kubernetes-native way to specify container-based workloads. By defining a clear schema with support for initialization, history tracking, and conditional post-execution hooks (judgement), it enables complex workflows. The execution is handled by dedicated controllers like actionLoop, which ensures that the declarative state defined in an Action resource is reconciled into running pods in the cluster, making it a powerful and extensible tool for automation within the AGH3 platform.