Skip to main content

​
Overview

KloudMate Agent uses a dual-configuration approach to separate agent management from OpenTelemetry Collector configuration. This design enables remote configuration updates, platform-specific optimizations, and seamless configuration management.

​
Configuration Architecture

Agent Configuration

Controls agent behavior, authentication, and update mechanisms

Collector Configuration

Defines OpenTelemetry pipelines, receivers, processors, and exporters

​
Configuration Hierarchy

The agent loads configuration from multiple sources in the following priority order:
1

Command-line Flags

Highest priority - overrides all other configuration sources
kmagent start --api-key=<key> --collector-endpoint=<url>
2

Environment Variables

Second priority - useful for containerized deployments
export KM_API_KEY=<key>
export KM_COLLECTOR_ENDPOINT=<url>
3

Agent Configuration File

Third priority - persistent configuration storage
# /etc/kmagent/agent-config.yaml
key: ${KM_API_KEY}
endpoint: https://otel.kloudmate.com:4318
interval: 10s
4

Remote Configuration

Lowest priority - fetched from KloudMate API for dynamic updates

​
File Locations

​
Agent Configuration File

The agent configuration file location varies by deployment mode: 
/etc/kmagent/config.yaml
The agent automatically creates the configuration directory if it doesn’t exist (file permissions: 0755).

​
Collector Configuration File

The OpenTelemetry Collector configuration is platform-specific:
Default path: /etc/kmagent/config.yamlUses host-col-config.yaml template with:
  • Host metrics collection (CPU, memory, disk, network)
  • OTLP receiver for application telemetry
  • Resource detection and enrichment

​
Configuration File Formats

​
Agent Configuration (YAML)

The agent configuration file uses a simplified YAML format:
~/workspace/source/configs/agent-config.yaml
# This config file will be used by the KM-Agent on it's first initialization.

key: ${KM_API_KEY}
debug: basic
endpoint: https://otel.kloudmate.com:4318
interval: 10s
​
key
string
required
API key for authentication with KloudMate backend. Supports environment variable expansion.
​
endpoint
string
required
OpenTelemetry collector endpoint URL (HTTP/S).
​
interval
duration
default:"60s"
Configuration check interval for remote updates.
​
debug
string
default:"none"
Debug exporter verbosity level: none, basic, normal, detailed.

​
Collector Configuration (YAML)

The collector configuration follows the standard OpenTelemetry Collector format:
Structure
receivers:
  # Data ingestion components
  hostmetrics:
    collection_interval: 60s
  otlp:
    protocols:
      grpc:
      http:

processors:
  # Data transformation pipeline
  batch:
    send_batch_size: 10000
  resourcedetection:
    detectors: [system, env]

exporters:
  # Data export destinations
  otlphttp:
    endpoint: ${env:KM_COLLECTOR_ENDPOINT}
    headers:
      Authorization: ${env:KM_API_KEY}

service:
  pipelines:
    metrics:
      receivers: [hostmetrics, otlp]
      processors: [resourcedetection, batch]
      exporters: [otlphttp]
All collector configurations use environment variable substitution for sensitive values like ${env:KM_API_KEY}.

​
Configuration Loading Process

The agent follows this initialization sequence:
1

Parse CLI Arguments

Extract flags and determine configuration file path from --agent-config or KM_AGENT_CONFIG environment variable.See implementation in ~/workspace/source/cmd/kmagent/main.go:179-230
2

Load Agent Config

Read agent configuration file (if exists) and merge with CLI flags and environment variables.See implementation in ~/workspace/source/internal/config/config.go:73-117
3

Determine Collector Config Path

Resolve platform-specific collector configuration path based on OS and deployment mode.
func GetDefaultConfigPath() string {
    if runtime.GOOS == "windows" {
        execPath, _ := os.Executable()
        return filepath.Join(filepath.Dir(execPath), "config.yaml")
    } else if runtime.GOOS == "darwin" {
        return "/Library/Application Support/kmagent/config.yaml"
    } else {
        return "/etc/kmagent/config.yaml"
    }
}
4

Load Collector Config

Read OpenTelemetry Collector configuration YAML and parse into internal structure.
5

Validate Configuration

Ensure all required fields are present and values are valid before starting the collector.
6

Start Remote Config Updates

Initialize background goroutine to check for configuration updates from KloudMate API.

​
Environment Variable Substitution

Both configuration files support environment variable expansion: 
endpoint: ${KM_COLLECTOR_ENDPOINT}
api_key: ${KM_API_KEY}
Environment variables are resolved at runtime. Missing required variables will cause the agent to fail startup.

​
Configuration Validation

The agent performs validation during startup:
Ensures critical configuration fields are present:
  • ExporterEndpoint: Must be a valid HTTP/HTTPS URL
  • APIKey: Must be non-empty for authenticated endpoints
  • OtelConfigPath: Must be readable if specified
Verifies configuration file paths:
  • Configuration directory must be writable
  • Collector config file must exist and be valid YAML
  • Parent directories are created automatically with 0755 permissions
Validates endpoint URLs:
  • Exporter endpoint must use HTTP or HTTPS scheme
  • Update endpoint is derived from exporter endpoint if not explicitly set
  • Hostname extraction follows pattern: otel.kloudmate.dev → api.kloudmate.dev
See implementation in ~/workspace/source/internal/config/config.go:28-52
OpenTelemetry Collector validates:
  • All referenced components are registered
  • Pipeline connections are valid
  • Processor configurations are correct
  • Exporter endpoints are reachable

​
Configuration Update Mechanism

The agent supports dynamic configuration updates without restart: Configuration updates are atomic operations using file rename to prevent corruption. See implementation in ~/workspace/source/internal/updater/updater.go:123-159

​
Next Steps

Agent Configuration

Detailed agent configuration reference

Collector Configuration

OpenTelemetry Collector configuration guide

Build docs developers (and LLMs) love

Get started for freeTalk to us