Manage Fleet configurations with Terraform
Create a Fleet Management configuration group with Terraform, collect CPU and memory metrics with a Docker Supervisor, then add CPU load metrics through a configuration update.
The coralogix_configuration_group resource is in private preview (Beta) and requires Terraform Provider v3.21.0 or later. Your account must have access to Fleet remote configuration. See Fleet Management permissions.
What you need
You need:
- Terraform 1.3.0 or higher, Docker running, and
curl. - A Coralogix personal or team API key with the FleetManagement permission preset for Terraform.
- A Send-Your-Data API key from the same Coralogix account for the Supervisor and metric export. A management API key alone does not provide ingestion access.
- Permission to query metrics in Metric Explorer.
The example uses EU2 (eu2.coralogix.com). For another region, use your Coralogix domain in both the environment variable and the Collector exporter in step 2.
1. Prepare the workspace and credentials
Create a directory for the Terraform configuration and state:
mkdir fleet-terraform-demo
cd fleet-terraform-demo
export CORALOGIX_API_KEY="<management-api-key>"
export CORALOGIX_PRIVATE_KEY="<send-your-data-api-key>"
export CORALOGIX_DOMAIN="eu2.coralogix.com"
unset CORALOGIX_ENV
export TF_VAR_demo_id="fleet-tf-$(date -u +%Y%m%dT%H%M%SZ)"
Supply keys through your secret-management workflow. Keep them out of files and version control. Retain the Terraform state and the TF_VAR_ values used in this guide for updates and cleanup.
2. Define the remote Collector configuration
Create collector.yaml:
receivers:
host_metrics:
collection_interval: 30s
scrapers:
cpu: {}
memory: {}
processors:
resource/demo:
attributes:
- key: service.name
value: fleet-terraform-hostmetrics
action: upsert
batch:
timeout: 1s
exporters:
coralogix:
domain: eu2.coralogix.com
private_key: ${env:CORALOGIX_PRIVATE_KEY}
application_name: fleet-terraform-demo
subsystem_name: hostmetrics
extensions:
health_check:
endpoint: 0.0.0.0:13133
service:
extensions: [health_check]
pipelines:
metrics:
receivers: [host_metrics]
processors: [resource/demo, batch]
exporters: [coralogix]
The receiver collects CPU and memory metrics every 30 seconds and exports them to Coralogix. These scrapers use the Linux /proc files already available inside the container. The Collector reads the ingestion key from its environment.
3. Connect the Supervisor
Download the latest installer:
curl -fsSL \
https://github.com/coralogix/telemetry-shippers/releases/latest/download/docker-install.sh \
-o docker-install.sh
The installer removes and replaces any container named coralogix-otel-collector and writes its local configuration under ~/.coralogix-otel-collector. Run this demo on a disposable host, or back up and stop an existing installation before continuing. Make sure ports 14317, 14318, and 23133 are available.
Run the installer:
OTLP_GRPC_PORT=14317 \
OTLP_HTTP_PORT=14318 \
HEALTH_CHECK_PORT=23133 \
bash docker-install.sh --supervisor
Read the installed agent's hostname and Collector version for Terraform:
export TF_VAR_host_name="$(docker inspect --format '{{.Config.Hostname}}' coralogix-otel-collector)"
export TF_VAR_collector_version="$(docker exec coralogix-otel-collector /otelcol-contrib --version | awk '{print $NF}')"
Verify the values were set:
echo "Host name: $TF_VAR_host_name"
echo "Collector version: $TF_VAR_collector_version"
Both values must be non-empty before proceeding to step 4.
4. Create the configuration group
Create main.tf:
terraform {
required_version = ">= 1.3.0"
required_providers {
coralogix = {
source = "coralogix/coralogix"
version = ">= 3.21.0"
}
}
}
provider "coralogix" {}
variable "demo_id" {
type = string
description = "Unique name for this configuration group."
}
variable "host_name" {
type = string
description = "The host.name attribute reported by the Docker Supervisor."
}
variable "collector_version" {
type = string
description = "The Collector version installed in the Supervisor container."
}
resource "coralogix_configuration_group" "demo" {
name = var.demo_id
description = "Terraform remote configuration walkthrough"
tags = ["terraform-demo"]
family = {
active = true
raw = {
collector_version = var.collector_version
remote_configurations = [
{
name = "docker-collector"
raw_configuration = file("${path.module}/collector.yaml")
agent_selector = {
attributes = {
"cx.agent.type" = "docker"
"host.name" = var.host_name
"service.version" = var.collector_version
}
}
},
]
}
}
}
output "group_id" {
value = coralogix_configuration_group.demo.id
}
output "family_version" {
value = coralogix_configuration_group.demo.family.version
}
The provider uses the exported management key and domain. The selector matches Docker agents reporting the chosen host.name and Collector version.
Create the group:
terraform init
terraform apply
Review and confirm the plan. Terraform creates one group with family version 1. In Fleet Management, select Configurations, then find your group by TF_VAR_demo_id and wait for Active with one healthy agent.
5. Check host metrics
The Collector applies the configuration and begins collection.
In Explore, select Metric Explorer, switch to Query, then run:
{__name__=~"system_cpu_time.*|system_memory_usage.*", service_name="fleet-terraform-hostmetrics"}
Select the last 15 minutes and confirm that new samples arrive. If samples do not appear, check that the group is Active and inspect the Supervisor output for collection or export errors. Exported metric names use underscores in place of dots and can include unit suffixes.
6. Add load metrics
In collector.yaml, add the load scraper under host_metrics.scrapers:
scrapers:
cpu: {}
memory: {}
load: {}
Apply the change:
terraform apply
terraform output family_version
The family advances to version 2. The Supervisor applies the update automatically. Once the group is Active, query the added metrics in Metric Explorer:
{__name__=~"system_cpu_load_average.*", service_name="fleet-terraform-hostmetrics"}
You should see the 1-, 5-, and 15-minute load averages alongside continued CPU and memory collection. No manual container restart is needed.
Run terraform plan to confirm No changes. Make future configuration edits through Terraform.
Troubleshooting
For connection or collection errors, inspect the Supervisor output:
docker logs --since 5m coralogix-otel-collector
- HTTP 403: Check that
CORALOGIX_PRIVATE_KEYis a Send-Your-Data key for the same account and region. - Group stays pending: Check
host.name,cx.agent.type, and Collector version against the Terraform selector and family. - Scrape errors: Check the Collector output for the failing scraper. Additional scrapers, such as
filesystem, can require host bind mounts; see the host metrics receiver documentation.
Cleanup
When finished, deactivate the family before archiving the group. In main.tf, set family.active to false and apply that change. The API rejects archival while a family is active.
docker stop coralogix-otel-collector
docker rm coralogix-otel-collector
terraform apply
terraform destroy
terraform destroy archives the inactive group; its configuration history remains. The local bootstrap files in ~/.coralogix-otel-collector/ remain until you remove them.