Skip to main content
The KloudMate Agent uses a multi-layered configuration system that combines local files, environment variables, and remote updates to provide flexible and dynamic observability.

​
Configuration Architecture

The agent’s configuration consists of three main components:

Agent Configuration

Controls agent behavior, update intervals, and service settings

Collector Configuration

OpenTelemetry collector pipeline configuration (receivers, processors, exporters)

Remote Updates

Dynamic configuration updates from KloudMate platform

​
Configuration Hierarchy

The agent resolves configuration in the following order (highest to lowest priority):
1

CLI Flags

Command-line arguments passed when starting the agent
kmagent start --api-key=<key> --collector-endpoint=<url>
2

Environment Variables

System environment variables prefixed with KM_
export KM_API_KEY="your-api-key"
export KM_COLLECTOR_ENDPOINT="https://otel.kloudmate.com:4318"
3

Agent Config File

YAML file specified via --agent-config flag or KM_AGENT_CONFIG environment variable
key: ${KM_API_KEY}
endpoint: https://otel.kloudmate.com:4318
interval: 10s
debug: basic
4

Remote Configuration

Configuration fetched from KloudMate platform (updates collector config dynamically)
5

Default Values

Built-in defaults defined in the source code

​
Configuration File Locations

Default configuration paths vary by deployment mode and operating system:

​
Host Deployment

# Agent configuration
/etc/kmagent/config.yaml

# Collector configuration
/etc/kmagent/otel-config.yaml

​
Docker Deployment

# Both configurations mounted at
/etc/kmagent/config.yaml

​
Kubernetes Deployment

# Daemonset collector config
ConfigMap: km-agent-configmap-daemonset

# Deployment collector config
ConfigMap: km-agent-configmap-deployment

​
Configuration Files

The agent uses different default configurations based on the deployment mode:

Host Mode

host-col-config.yaml - Optimized for bare metal and VM deployments

Docker Mode

docker-col-config.yaml - Includes Docker stats receiver and container log collection

Kubernetes Mode

daemonset-col-config.yaml - Node-level monitoring with kubelet stats

​
Key Configuration Parameters

​
Authentication & Connectivity

​
KM_API_KEY
string
required
API key for authenticating with the KloudMate platform. Obtain from Settings.
​
KM_COLLECTOR_ENDPOINT
string
default:"https://otel.kloudmate.com:4318"
OTLP/HTTP endpoint where telemetry data is sent.

​
Update Configuration

​
KM_CONFIG_CHECK_INTERVAL
integer
default:"60"
Interval in seconds between configuration update checks.
​
KM_UPDATE_ENDPOINT
string
default:"https://api.kloudmate.com/agents/config-check"
Endpoint for fetching configuration updates. Auto-derived from collector endpoint if not set.

​
Deployment Mode

​
KM_DOCKER_MODE
boolean
default:"false"
Enable Docker-specific configuration and receivers.
​
KM_CLUSTER_NAME
string
Kubernetes cluster name (required for Kubernetes deployments).

​
Configuration Validation

The agent validates configuration on startup: 
// LoadConfig loads the configuration from CLI flags, environment variables, and config file
func (c *Config) LoadConfig() error {
    os.Setenv("KM_COLLECTOR_ENDPOINT", c.ExporterEndpoint)
    os.Setenv("KM_API_KEY", c.APIKey)

    if c.ConfigUpdateURL == "" {
        c.ConfigUpdateURL = GetAgentConfigUpdaterURL(c.ExporterEndpoint)
    }

    // Default config file path based on OS
    configPath := c.OtelConfigPath
    if configPath == "" {
        if c.DockerMode {
            configPath = GetDockerConfigPath()
        } else {
            configPath = GetDefaultConfigPath()
        }
    }

    c.OtelConfigPath = configPath
    
    // Load config file if exists
    if _, err := os.Stat(configPath); err == nil {
        configData, err := os.ReadFile(configPath)
        if err != nil {
            return fmt.Errorf("failed to read config file: %w", err)
        }

        if err := yaml.Unmarshal(configData, c); err != nil {
            return fmt.Errorf("failed to parse config file: %w", err)
        }
    }

    return nil
}

​
Environment Variable Expansion

Configuration files support environment variable expansion using the ${env:VAR_NAME} syntax: 
exporters:
  otlphttp:
    endpoint: ${env:KM_COLLECTOR_ENDPOINT}
    headers:
      Authorization: ${env:KM_API_KEY}
This allows sensitive values like API keys to be injected at runtime without storing them in configuration files.
Environment variables are expanded by the OpenTelemetry Collector at startup. If a variable is not set, the collector will fail to start.

​
Configuration Best Practices

Never hardcode API keys or sensitive credentials in configuration files. Always use environment variable expansion:
# Good
headers:
  Authorization: ${env:KM_API_KEY}

# Bad
headers:
  Authorization: km_1234567890abcdef
Use the remote configuration feature to manage collector pipelines centrally:
  • Reduces manual configuration management
  • Enables dynamic updates without agent restarts
  • Supports A/B testing and gradual rollouts
Track configuration changes through agent logs:
INFO  collector configuration updated  {"configPath": "/etc/kmagent/config.yaml"}
INFO  configuration changed, restarting collector
INFO  collector restarted successfully
Validate configuration files before deploying:
# Validate YAML syntax
yamllint /etc/kmagent/otel-config.yaml

# Test with debug exporter
kmagent start --config=/etc/kmagent/otel-config.yaml

​
Next Steps

Environment Variables

Complete reference of all environment variables

Remote Configuration

Learn how dynamic updates work

OpenTelemetry Components

Configure receivers, processors, and exporters

Troubleshooting

Resolve configuration issues

Build docs developers (and LLMs) love

Get started for freeTalk to us