Skip to main content

Deploying the Atlas Agent on Kubernetes with Helm

This guide explains how to deploy the Atlas Agent for database monitoring on Kubernetes using Helm charts. By following these steps, you can automate database monitoring and reporting to Atlas Cloud in your Kubernetes environment.

Prerequisites​

  • An Atlas Cloud account
  • A bot token for your agent
  • A Kubernetes cluster
  • A database accessible from your Kubernetes cluster

Prepare the configuration​

Token secret​

Create a Secret named atlas-agent with your bot token,

kubectl create secret generic atlas-agent-secrets --from-literal token=YOUR_BOT_TOKEN

Agent configurations configmap​

The Atlas Agent is configured using the atlas-agent.hcl file. The full configuration schema is available here.

There are two ways to configure the database authentication:

  • Environment variables: the database password is injected into the agent pod as an environment variable.
  • RDS IAM authentication: the database password is retrieved from AWS Secrets Manager using an IAM role.

First, create a secret for the database password:

kubectl create secret generic atlas-agent-db --from-literal password=YOUR_DATABASE_PASSWORD

Then, create a file named atlas-agent.hcl with the following content:

instance "my-instance" {
  driver = "postgres" # or "mysql", "mssql" etc.
  connection {
    host = "{YOUR_DATABASE_HOST}"
    port = {YOUR_DATABASE_PORT}
    # For Postgres and MsSQL, this is the database name to connect to.
    database = "{YOUR_DATABASE_NAME}"
    user = "{YOUR_DATABASE_USER}"
    # Authenticating to the database using a password stored in an environment variable
    auth {
      env_var "ATLAS_AGENT_DB_PASSWORD" {}
    }
  }
  
  monitor "my-monitor" {
    # For Postgres and MsSQL, this is the database name to monitor.
    database = "{YOUR_DATABASE_NAME}"
    # Optional: list of schemas to monitor
    schemas = ["public"]
    # Optional: list of glob patterns used to filter resources from applying
    # See: https://atlasgo.io/inspect#exclude
    exclude = ["public"]
    # Optional: list of glob patterns used to select which resources to keep in inspection
    # See: https://atlasgo.io/inspect#include-schema-resources-
    include = ["my-schema"]

    statistics {
      # Optional: Enable or disable statistics collection.
      enabled = true
    }
  }
}

Create a configmap for the agent configuration with the following command:

kubectl create configmap atlas-agent-config --from-file atlas-agent.hcl

Install the agent​

Create a values.yaml file with the following content:

image:
  tag: "latest"

apiKeySecret:
  name: atlas-agent-secrets
  key: token

extraEnvs:
  # The path to the agent configuration file
  - name: CONFIG
    value: /etc/atlas-agent/atlas-agent.hcl

  # Add the following only if you are using environment variables for database authentication:
  - name: ATLAS_AGENT_DB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: atlas-agent-db
        key: password

# Create a volume for the agent configuration
volumes:
  - name: atlas-agent-config-volume
    configMap:
      name: atlas-agent-config

# Mount the configmap to the agent container
volumeMounts:
 - name: atlas-agent-config-volume
   mountPath: /etc/atlas-agent

This file:

  • Creates a configmap for the agent configuration
  • Mounts the configmap to the agent container
  • Injects the bot token and (optionally) the database password into the agent container as environment variables

Install the agent using Helm:

helm install atlas-agent oci://ghcr.io/ariga/charts/atlas-agent -f values.yaml

Verify that the agent is running:

kubectl wait --for=condition=Ready pods -l app.kubernetes.io/name=atlas-agent

Finally, check https://<your-organization>.atlasgo.cloud/instances to see the created instance and get immediate visibility into your database schema.