Infrastructure as Code (IaC)

Deploy the KloudMate agent across any cloud provider or on-premises infrastructure using Infrastructure as Code (IaC) and automation tools.

Note

However you install it, each agent starts in managed mode. Once it checks in, it automatically collects host metrics, logs, and eBPF monitoring data. See the configuration model.

If your outbound traffic is restricted, see Before you start for the URLs and permissions to allow first.

Deployment Approaches

Method	Best For	Cloud Support
cloud-init	New VMs, ASGs, Scale Sets	All providers
Ansible	Existing VM fleets	All providers + on-prem
Terraform module	IaaC-managed infrastructure	All providers
Packer	Pre-baked machine images	AWS, GCP, Azure

Decision Matrix

To provision a new VM or Auto-scaling group, use cloud-init through User Data or Custom Data. For faster boot times, use Packer to pre-bake the image and cloud-init for config only.

For an existing fleet, use an Ansible playbook.

If you already use Terraform, use the Terraform module.

1. cloud-init (Universal)

Works on every provider that supports cloud-init (AWS, GCP, Azure, DigitalOcean, Alibaba, Hetzner, Vultr, Linode, etc.).

AWS

# Encode and attach to launch template
base64 -w0 cloud-init/cloud-init.yaml > /tmp/userdata.b64

aws ec2 create-launch-template \
  --launch-template-name kmagent-template \
  --launch-template-data '{
    "UserData": "'$(cat /tmp/userdata.b64)'"
  }'

GCP

gcloud compute instance-templates create kmagent-template \
  --metadata-from-file user-data=cloud-init/cloud-init.yaml \
  --machine-type e2-medium \
  --image-family ubuntu-2204-lts \
  --image-project ubuntu-os-cloud

Azure

az vmss create \
  --name kmagent-vmss \
  --resource-group myResourceGroup \
  --image Ubuntu2204 \
  --custom-data cloud-init/cloud-init.yaml

DigitalOcean

doctl compute droplet create kmagent-node \
  --image ubuntu-22-04-x64 \
  --size s-1vcpu-1gb \
  --user-data-file cloud-init/cloud-init.yaml

Alibaba Cloud

Paste cloud-init.yaml content into: ECS Console → Instance → Advanced Options → User Data

2. Ansible

Use Ansible to deploy the KloudMate agent to existing VM fleets.

Navigate to the Ansible directory

cd ansible/

Set your API key

export KM_API_KEY="your-kloudmate-api-key"

Edit your inventory

Add your hosts to the inventory file:

vim inventories/production.ini

Deploy

All Hosts

ansible-playbook -i inventories/production.ini deploy-kmagent.yml \
  -e "km_api_key=$KM_API_KEY km_endpoint=https://otel.kloudmate.com"

Specific Group

ansible-playbook -i inventories/production.ini deploy-kmagent.yml \
  -e "km_api_key=$KM_API_KEY km_endpoint=https://otel.kloudmate.com" \
  --limit aws

Dry Run

ansible-playbook -i inventories/production.ini deploy-kmagent.yml \
  -e "km_api_key=$KM_API_KEY km_endpoint=https://otel.kloudmate.com" \
  --check --diff

Dynamic Inventory (Auto-discover VMs)

Instead of static inventory files, use cloud-native dynamic inventory plugins:

AWS

pip install boto3
ansible-playbook -i aws_ec2.yml deploy-kmagent.yml

GCP

pip install google-auth
ansible-playbook -i gcp_compute.yml deploy-kmagent.yml

Azure

pip install azure-identity azure-mgmt-compute
ansible-playbook -i azure_rm.yml deploy-kmagent.yml

Example aws_ec2.yml configuration:

AWS

plugin: amazon.aws.aws_ec2
regions:
  - us-east-1
  - us-west-2
  - ap-south-1
filters:
  tag:Environment: production
  instance-state-name: running
keyed_groups:
  - key: tags.Role
    prefix: role
  - key: placement.region
    prefix: region
compose:
  ansible_host: private_ip_address

Useful Ansible Commands

# Upgrade agent on all hosts
ansible-playbook deploy-kmagent.yml --tags upgrade \
  -e "kmagent_version=1.2.0"

# Only reconfigure (no reinstall)
ansible-playbook deploy-kmagent.yml --tags configure

# Uninstall from specific hosts
ansible-playbook deploy-kmagent.yml \
  -e "kmagent_state=absent" --limit "gcp"

# Check agent status across fleet
ansible all -i inventories/production.ini -m shell \
  -a "systemctl status kmagent | head -5"

3. Terraform Module

Embed kmagent into your Terraform deployments across any provider using the user-data module.

Module Usage

module "kmagent" {
  source      = "./modules/user-data"
  km_api_key  = var.km_api_key
  km_endpoint = "https://otel.kloudmate.com"
  kmagent_tags = {
    env  = "production"
    team = "platform"
  }
}

AWS

resource "aws_launch_template" "app" {
  name_prefix = "app-"
  user_data   = base64encode(module.kmagent.cloud_init)
}

resource "aws_autoscaling_group" "app" {
  launch_template {
    id      = aws_launch_template.app.id
    version = "$Latest"
  }
  min_size = 2
  max_size = 20
}

GCP

resource "google_compute_instance_template" "app" {
  metadata = {
    user-data = module.kmagent.cloud_init
  }
}

Azure

resource "azurerm_linux_virtual_machine_scale_set" "app" {
  custom_data = base64encode(module.kmagent.cloud_init)
}

DigitalOcean

resource "digitalocean_droplet" "app" {
  user_data = module.kmagent.cloud_init
}

4. Packer (Pre-baked Images)

Best when boot speed matters. The agent binary is baked into the image, so there’s no install step at boot. Only the config (the API key) is injected.

Navigate to the Packer directory

cd packer/

Build your images

AWS AMI

packer build -only=amazon-ebs.kmagent \
  -var 'kmagent_version=1.2.0' \
  kmagent-image.pkr.hcl

GCP Image

# Add your gcp specific packer build command here

Build All

packer build kmagent-image.pkr.hcl

Deploy

Use the resulting image in your Launch Template / Instance Template, with minimal user-data that only injects the API key.

Secret Management

Caution

Never hardcode API keys! Use your cloud’s native secret store to securely inject credentials at runtime.

Provider	Service	Retrieval Command
AWS	SSM Parameter Store	aws ssm get-parameter --name /kloudmate/api-key --with-decryption
AWS	Secrets Manager	aws secretsmanager get-secret-value --secret-id kloudmate-api-key
GCP	Secret Manager	gcloud secrets versions access latest --secret=kloudmate-api-key
Azure	Key Vault	az keyvault secret show --name kloudmate-api-key --vault-name myvault
DigitalOcean	Reserved env vars	Set via doctl or Terraform
Alibaba	KMS	aliyun kms GetSecretValue --SecretName kloudmate-api-key

Directory Structure

kmagent-deploy/

kmagent-deploy/
├── ansible/
│   ├── ansible.cfg
│   ├── deploy-kmagent.yml          # Main playbook
│   ├── inventories/
│   │   └── production.ini          # Static inventory (edit with your hosts)
│   └── roles/
│       └── kmagent/
│           ├── defaults/main.yml   # Configurable variables
│           ├── handlers/main.yml   # Service reload/restart
│           ├── tasks/main.yml      # Install, configure, upgrade, uninstall
│           └── templates/
│               ├── agent.yaml.j2   # Agent config
│               └── kmagent.service.j2  # systemd unit
└── terraform/
    └── modules/
        └── user-data/
            └── main.tf              # Reusable user-data module