Manage Fleet configurations with Coralogix Operator
Monitor your local host by installing a Supervisor in Docker with otel-installer, then manage its Collector configuration through a Kubernetes ConfigurationGroup custom resource. This walkthrough runs Coralogix Operator in a local kind cluster. Start with CPU and memory metrics, then add CPU load metrics by updating the custom resource.
Your account must have access to Fleet remote configuration. See Fleet Management permissions.
What you need
- Docker running, kind,
kubectl, Helm, andcurl. - Bash 4.4 or later (
brew install bashon macOS). - A Coralogix personal or team API key with the FleetManagement permission preset for the operator.
- A Send-Your-Data API key from the same account for the Supervisor and metric export.
- Permission to query metrics in Metric Explorer.
This example uses EU2. For another region, change the operator's region and the Coralogix domain in CORALOGIX_DOMAIN and the Collector exporter.
1. Create the cluster and credentials
Create a workspace and a local cluster:
mkdir fleet-operator-demo
cd fleet-operator-demo
export KUBECONFIG="$PWD/kubeconfig"
kind create cluster --name fleet-operator-docs --image kindest/node:v1.34.0 \
--kubeconfig "$KUBECONFIG"
kubectl create namespace fleet-demo
Supply keys through your secret-management workflow and create the operator's Kubernetes Secret:
export CORALOGIX_API_KEY="<management-api-key>"
export CORALOGIX_PRIVATE_KEY="<send-your-data-api-key>"
export CORALOGIX_DOMAIN="eu2.coralogix.com"
printf '%s' "$CORALOGIX_API_KEY" | kubectl -n fleet-demo create secret generic coralogix-management \
--from-file=apiKey=/dev/stdin
2. Install Coralogix Operator
Create operator-values.yaml:
secret:
create: false
secretKeyReference:
name: coralogix-management
key: apiKey
coralogixOperator:
region: EU2
prometheusRules:
enabled: false
serviceMonitor:
create: false
These settings turn off the Prometheus integrations for this demo cluster.
Install the latest Operator chart:
helm repo add coralogix https://cgx.jfrog.io/artifactory/coralogix-charts-virtual
helm repo update coralogix
helm upgrade --install coralogix-operator coralogix/coralogix-operator \
--namespace fleet-demo \
--values operator-values.yaml --wait --timeout 5m
3. Connect a Docker Supervisor
Download and run the Docker installer:
curl -fsSL \
https://github.com/coralogix/telemetry-shippers/releases/latest/download/docker-install.sh \
-o docker-install.sh
OTLP_GRPC_PORT=14317 \
OTLP_HTTP_PORT=14318 \
HEALTH_CHECK_PORT=23133 \
bash docker-install.sh --supervisor \
--opamp-attribute fleet.test.id=fleet-operator-demo
The --opamp-attribute option (Open Agent Management Protocol) sets a custom agent attribute that the configuration group's selector uses below.
4. Create the configuration group
Create configuration-group.yaml:
apiVersion: coralogix.com/v1alpha1
kind: ConfigurationGroup
metadata:
name: host-metrics
namespace: fleet-demo
spec:
name: Operator host metrics
description: Host metrics managed by Coralogix Operator.
family:
active: true
remoteConfigurations:
- name: host-metrics
agentSelector:
cx.agent.type: docker
fleet.test.id: fleet-operator-demo
rawConfiguration: |
receivers:
host_metrics:
collection_interval: 30s
scrapers:
cpu: {}
memory: {}
processors:
resource/demo:
attributes:
- key: service.name
value: fleet-operator-hostmetrics
action: upsert
batch:
timeout: 1s
exporters:
coralogix:
domain: eu2.coralogix.com
private_key: ${env:CORALOGIX_PRIVATE_KEY}
application_name: fleet-operator-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 selector matches Docker agents with fleet.test.id=fleet-operator-demo. The receiver collects CPU and memory metrics every 30 seconds. service.name is an example label used to find these metrics in Coralogix.
Apply the resource and wait for the operator to sync it:
kubectl apply -f configuration-group.yaml
kubectl -n fleet-demo wait configurationgroup/host-metrics \
--for=condition=RemoteSynced --timeout=5m
kubectl -n fleet-demo get configurationgroup host-metrics
In Fleet Management, select Configurations, find Operator host metrics, and verify the status shows Active with 1 healthy agent. RemoteSynced confirms that the operator saved the group. The agent status in Fleet Management confirms that the Supervisor applied it.
5. Check host metrics
In Explore, select Metric Explorer, switch to Query, and run:
{__name__=~"system_cpu_time.*|system_memory_usage.*", service_name="fleet-operator-hostmetrics"}
Select the last 15 minutes and confirm new samples arrive. Allow up to 5 minutes for the configuration and first samples.
6. Add load metrics
Replace configuration-group.yaml with the complete configuration below, which adds the load scraper:
apiVersion: coralogix.com/v1alpha1
kind: ConfigurationGroup
metadata:
name: host-metrics
namespace: fleet-demo
spec:
name: Operator host metrics
description: Host metrics managed by Coralogix Operator.
family:
active: true
remoteConfigurations:
- name: host-metrics
agentSelector:
cx.agent.type: docker
fleet.test.id: fleet-operator-demo
rawConfiguration: |
receivers:
host_metrics:
collection_interval: 30s
scrapers:
cpu: {}
memory: {}
load: {}
processors:
resource/demo:
attributes:
- key: service.name
value: fleet-operator-hostmetrics
action: upsert
batch:
timeout: 1s
exporters:
coralogix:
domain: eu2.coralogix.com
private_key: ${env:CORALOGIX_PRIVATE_KEY}
application_name: fleet-operator-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]
Apply the change:
kubectl apply -f configuration-group.yaml
kubectl -n fleet-demo get configurationgroup host-metrics -o yaml
Wait until the RemoteSynced condition is True and its observedGeneration matches metadata.generation. In Fleet Management, the family advances to version 2 and returns to Active. The Supervisor applies the update automatically, without a manual container restart.
Query the added metrics in Metric Explorer:
{__name__=~"system_cpu_load_average.*", service_name="fleet-operator-hostmetrics"}
Confirm that the 1-, 5-, and 15-minute load averages appear alongside continued CPU and memory collection. Reapplying the unchanged manifest leaves the family version unchanged. Make future configuration edits through the Kubernetes resource.
Troubleshooting
kubectl -n fleet-demo get configurationgroup host-metrics -o yaml
kubectl -n fleet-demo logs deploy/coralogix-operator --since=5m
docker logs --since 5m coralogix-otel-collector
- RemoteUnsynced: Check the condition message and the management key's permissions.
- Group stays pending: Check that the Docker Supervisor's
cx.agent.typeandfleet.test.idattributes match the selector. - HTTP 403 from the Supervisor or exporter: Check that
CORALOGIX_PRIVATE_KEYis a Send-Your-Data key for the same account and region.
Cleanup
Stop the Docker Supervisor, delete the configuration group while the operator is still running, then remove the demo cluster:
docker stop coralogix-otel-collector
docker rm coralogix-otel-collector
kubectl -n fleet-demo delete configurationgroup host-metrics --timeout=5m
kind delete cluster --name fleet-operator-docs
The operator deactivates the family and archives the remote group before completing deletion.