--- title: Manage Fleet configurations with Terraform description: Create and update Fleet Management configuration groups with Terraform, then verify remote configuration on a Docker-based OpenTelemetry Collector. url: https://coralogix.com/docs/developer-portal/infrastructure-as-code/terraform-provider/fleet-management/configuration-groups/ product: integrations feature: Fleet Management feature_id: fleet-management feature_identifier: integrations/fleet-management last_updated: '2026-10-27' --- # 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. Private preview 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](https://coralogix.com/docs/user-guides/fleet-management/permissions.md). ## 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](https://coralogix.com/docs/user-guides/fleet-management/permissions.md) for Terraform. * A [Send-Your-Data API key](https://coralogix.com/docs/user-guides/account-management/api-keys/send-your-data-api-key.md) 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](https://coralogix.com/docs/user-guides/data_exploration/metrics-explorer.md#what-you-need). The example uses EU2 (`eu2.coralogix.com`). For another region, use your [Coralogix domain](https://coralogix.com/docs/user-guides/account-management/account-settings/coralogix-domain.md) 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="" export CORALOGIX_PRIVATE_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" application_name_attributes: - "cx.application.name" subsystem_name_attributes: - "cx.subsystem.name" timeout: 30s 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 ``` Existing Docker Collector 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_KEY` is 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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/hostmetricsreceiver#collecting-host-metrics-from-inside-a-container-linux-only). ## 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. ## Learn more * [Terraform resource reference](https://registry.terraform.io/providers/coralogix/coralogix/latest/docs/resources/configuration_group) * [Configuration management](https://coralogix.com/docs/user-guides/fleet-management/configuration-management.md) * [Host metrics receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.160.0/receiver/hostmetricsreceiver) * [Docker installer reference](https://github.com/coralogix/telemetry-shippers/blob/master/otel-installer/docker/README.md)