Configuring Observability (Vector)

Relevant source files

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

• charts/agh3/values.yaml
• charts/agh3/README.md
• charts/agh3/templates/captain/vector-configmap.yaml
• charts/agh3/templates/actionloop/vector-configmap.yaml
• charts/agh3/templates/controller/vector-configmap.yaml
• charts/agh3/templates/captain/captain-deployment.yml
• charts/agh3/templates/actionloop/actionloop-deployment.yml
• charts/agh3/templates/controller/controller-deployment.yml
• charts/agh3/files/vector.toml

The AGH3 Helm chart integrates Vector as an optional observability agent. When enabled, Vector is deployed as a sidecar container alongside the captain, actionloop, and controller services. This allows for the collection, transformation, and routing of logs generated by these components, providing a unified observability pipeline.

The entire Vector integration is controlled by a set of values in the values.yaml file, allowing users to easily enable or disable it and configure the agent's image. The architecture relies on shared volumes for log collection and Kubernetes ConfigMaps for dynamic configuration management.

Enabling and Configuring Vector

Vector can be enabled and configured through the vector section in the charts/agh3/values.yaml file.

Sources: charts/agh3/values.yaml:1004-1013, charts/agh3/README.md:321-326

Configuration Parameters

The following table details the configuration options available for Vector in the values.yaml file.

Parameter	Description	Default Value
vector.enabled	A boolean flag to enable or disable the Vector observability agent.	false
vector.image.repository	The repository for the Vector container image.	timberio/vector
vector.image.tag	The tag for the Vector container image.	latest-debian

Sources: charts/agh3/values.yaml:1004-1013, charts/agh3/README.md:321-326

Example values.yaml Configuration

To enable Vector, you would set enabled to true:

## charts/agh3/values.yaml

# ...
vector:
  ## @param vector.enabled Enable Vector observability agent for captain, action-loop and controller
  ##
  enabled: true
  ## @param vector.image.repository Vector image repository
  ## @param vector.image.tag Vector image tag (immutable tags are recommended)
  ##
  image:
    repository: timberio/vector
    tag: latest-debian
# ...

Sources: charts/agh3/values.yaml:1004-1013

Architecture

When vector.enabled is true, the Helm chart deploys Vector as a sidecar container within the pods for the captain, actionloop, and controller deployments.

Key architectural features include:

• Sidecar Pattern: The vector container runs alongside the main application container (e.g., captain) in the same pod.
• Shared Log Volume: An emptyDir volume named logs is mounted into both the application container and the Vector sidecar. The application writes its logs to /logs, and Vector reads from the same directory.
• Configuration via ConfigMap: Each Vector sidecar gets its configuration from a dedicated Kubernetes ConfigMap, which is mounted as a volume.

Sources: charts/agh3/templates/captain/captain-deployment.yml:92-105, charts/agh3/templates/actionloop/actionloop-deployment.yml:95-108, charts/agh3/templates/controller/controller-deployment.yml:71-84

The following diagram illustrates the sidecar architecture within a captain pod.

This diagram shows how the captain container and vector sidecar share the logs volume, and how the Vector container is configured via a mounted ConfigMap.
Sources: charts/agh3/templates/captain/captain-deployment.yml:92-120

Configuration Management

Vector's configuration is managed through a combination of a base template file and component-specific ConfigMaps generated by Helm.

1. Base Configuration File: A generic vector.toml file is stored at charts/agh3/files/vector.toml. This file contains placeholders for environment-specific values.
2. ConfigMap Generation: For each component (captain, actionloop, controller), a dedicated ConfigMap template (e.g., charts/agh3/templates/captain/vector-configmap.yaml) reads the base vector.toml file.
3. Value Substitution: During Helm rendering, these templates replace the placeholders ${NAMESPACE} and ${APP_NAME} with the appropriate values for the specific component.
4. Mounting: The generated ConfigMap is then mounted into the corresponding pod, making the customized vector.toml available to the Vector sidecar.

Sources: charts/agh3/templates/captain/vector-configmap.yaml:1-10, charts/agh3/templates/actionloop/vector-configmap.yaml:1-10, charts/agh3/templates/controller/vector-configmap.yaml:1-10

The diagram below shows the configuration generation and mounting process.

This flow illustrates how a single base configuration file is used to generate specific configurations for each service's Vector sidecar.
Sources: charts/agh3/templates/captain/vector-configmap.yaml:7-8, charts/agh3/templates/actionloop/vector-configmap.yaml:7-8, charts/agh3/templates/controller/vector-configmap.yaml:7-8

Example ConfigMap Template

This is the template for the captain component's Vector ConfigMap. It dynamically populates the vector.toml data key.

{{- if .Values.vector.enabled }}
apiVersion: v1
kind: ConfigMap
metadata:
  name: vector-captain-config
  namespace: {{ .Release.Namespace }}
data:
  vector.toml: |-
    {{- $content := .Files.Get "files/vector.toml" }}
    {{ $content | replace "${NAMESPACE}" .Release.Namespace | replace "${APP_NAME}" "AGH3-Captain" | nindent 4 }}
{{- end }}

Sources: charts/agh3/templates/captain/vector-configmap.yaml:1-10

Deployment Integration

The Vector sidecar is injected into the captain, actionloop, and controller deployments if vector.enabled is true. The following snippets from the captain deployment manifest demonstrate this integration.

Volume Definitions

Two volumes are defined in the pod spec: one for the Vector configuration and one for sharing logs.

# charts/agh3/templates/captain/captain-deployment.yml
      {{- if .Values.vector.enabled }}
      volumes:
        - name: vector-captain-config
          configMap:
            name: vector-captain-config
        - name: logs
          emptyDir: {}
      {{- end }}

Sources: charts/agh3/templates/captain/captain-deployment.yml:92-99

Vector Sidecar Container

The vector container is defined to use the timberio/vector image and is configured to start Vector using the mounted configuration file. It also mounts the shared logs volume.

# charts/agh3/templates/captain/captain-deployment.yml
      containers:
        {{- if .Values.vector.enabled }}
        - name: vector
          image: {{ .Values.vector.image.repository }}:{{ .Values.vector.image.tag }}
          command: [ "vector", "--config", "/etc/vector/vector.toml" ]
          volumeMounts:
            - name: vector-captain-config
              mountPath: /etc/vector
            - name: logs
              mountPath: /logs
        {{- end }}

Sources: charts/agh3/templates/captain/captain-deployment.yml:101-112

Application Container Volume Mount

The main application container (captain) also mounts the shared logs volume to write its log files.

# charts/agh3/templates/captain/captain-deployment.yml
        - name: captain
          image: {{ include "captain.image" . }}
          {{- if .Values.vector.enabled }}
          volumeMounts:
            - name: logs
              mountPath: /logs
          {{- end }}

Sources: charts/agh3/templates/captain/captain-deployment.yml:113-119

Summary

The AGH3 Helm chart provides a robust and configurable integration with Vector for observability. By leveraging the sidecar pattern, shared volumes, and Helm's templating capabilities, it offers a streamlined way to collect logs from key application components. The system is disabled by default but can be easily activated and customized via the values.yaml file, allowing operators to pipe application logs to their preferred monitoring and analysis backends.