System requirements
-
Coroot relies heavily on eBPF, therefore, the minimum supported Linux kernel version is 4.16.
-
eBPF-based continuous profiling utilizes CO-RE.
CO-RE is supported by most modern Linux distributions, including:
- Ubuntu 20.10 and above
- Debian 11 and above
- RHEL 8.2 and above
-
Coroot gathers metrics, logs, traces, and profiles, with each telemetry signal associated with containers.
In this context, a container refers to a group of processes running within a dedicated cgroup.
The following container types are supported:
-
Kubernetes Pods using Docker, Containerd, or CRI-O as their runtime environment
-
Standalone containers: Docker, Containerd, CRI-O
-
Docker Swarm
-
Systemd units: any systemd service is also considered as a container
-
Supported container orchestrators include:
- Kubernetes: Self-managed, EKS (including basic support for AWS Fargate), GKE, AKS, OKE
- OpenShift
- K3s
- MicroK8s
- Docker Swarm
-
Limitations:
- Coroot doesn't support Docker-in-Docker environments such as MiniKube due to eBPF limitations
- WSL (Windows Subsystem for Linux) is not yet supported
All-in-one installation with Helm
Add the Coroot helm chart repo:
helm repo add coroot https://coroot.github.io/helm-charts
helm repo update coroot
Next, install the chart that includes:
Exposing Coroot for external access:
Ingress host:
{{install}}
Visit Coroot at the Ingress URL: http://{{ingressHostname}}
Get the Coroot URL by running these commands in the same shell:
export NODE_PORT=$(kubectl get --namespace coroot -o jsonpath="{.spec.ports[0].nodePort}" services coroot)
export NODE_IP=$(kubectl get nodes --namespace coroot -o jsonpath="{.items[0].status.addresses[0].address}")
echo http://$NODE_IP:$NODE_PORT
Forward the Coroot port to your machine:
kubectl port-forward -n coroot service/coroot 8080:8080
Then, you can access Coroot at http://localhost:8080
Upgrading
To upgrade Coroot to the latest version:
helm repo update coroot
helm upgrade coroot --namespace coroot coroot/coroot
Docker
To install Coroot on a Linux node using Docker Compose, follow these steps:
Step #1: Install Docker Compose (if not installed)
Use the following commands to install Docker Compose on Ubuntu:
apt update
apt install docker-compose-v2
Step #2: Deploy Coroot
To deploy Coroot using Docker Compose, run the following command.
Before applying it, you can review the configuration file in Coroot's GitHub repository:
docker-compose.yaml
curl -fsS https://raw.githubusercontent.com/coroot/coroot/main/deploy/docker-compose.yaml | docker compose -f - up -d
Step #3: Validate the deployment
Ensure that the Coroot containers are running by executing the following command:
docker ps
You should see an output similar to this if the deployment is successful:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9451a61a8136 ghcr.io/coroot/coroot:latest "/opt/coroot/coroot …" 33 seconds ago Up 31 seconds 0.0.0.0:8080->8080/tcp, :::8080->8080/tcp root-coroot-1
e81fdd93cffc clickhouse/clickhouse-server:24.3 "/entrypoint.sh" 33 seconds ago Up 32 seconds 8123/tcp, 9009/tcp, 127.0.0.1:9000->9000/tcp root-clickhouse-1
9e8b809db618 prom/prometheus:v2.45.4 "/bin/prometheus --c…" 33 seconds ago Up 32 seconds 127.0.0.1:9090->9090/tcp root-prometheus-1
6431fb47f21a ghcr.io/coroot/coroot-node-agent "coroot-node-agent -…" 3 hours ago Up 32 seconds root-coroot-node-agent-1
Step #4: Accessing Coroot
-
If you installed Coroot on your desktop machine, you can access it at http://localhost:8080/.
-
If Coroot is deployed on a remote node, replace <NODE_IP_ADDRESS> with the IP address of the node in the following URL: http://<NODE_IP_ADDRESS>:8080/.
Docker Swarm
To deploy Coroot to a Docker Swarm cluster, follow these steps:
Step #1: Initialize Docker Swarm
If you haven't already initialized Docker Swarm on your manager node, run the following command on the manager node:
docker swarm init
This initializes a new Docker Swarm and joins the current node as a manager.
Step #2: Deploy the Coroot Stack
Deploy the Coroot stack to your cluster by running the following command on the manager node.
Before applying, you can review the configuration file in Coroot's GitHub repository:
docker-swarm-stack.yaml
curl -fsS https://raw.githubusercontent.com/coroot/coroot/main/deploy/docker-swarm-stack.yaml | docker stack deploy -c - coroot
Step #3: Validate the deployment
After deploying the stack, you can use docker stack ls to list the deployed stacks in your Docker Swarm cluster.
Here's an example of how the output might look:
NAME SERVICES
coroot 3
Step #4: Installing coroot-node-agent
Since Docker Swarm doesn't support privileged containers, you'll have to manually deploy
coroot-node-agent on each cluster node.
Just replace <NODE_IP> with any node's IP address in the Docker Swarm cluster.
docker run --detach --name coroot-node-agent \
--pull=always \
--privileged --pid host \
-v /sys/kernel/tracing:/sys/kernel/tracing:rw \
-v /sys/kernel/debug:/sys/kernel/debug:rw \
-v /sys/fs/cgroup:/host/sys/fs/cgroup:ro \
ghcr.io/coroot/coroot-node-agent \
--cgroupfs-root=/host/sys/fs/cgroup \
--collector-endpoint=http://<NODE_IP>:8080
Step #5: Accessing Coroot
Access Coroot through any node in your Docker Swarm cluster using its published port: http://<node_ip>:8080.
Ubuntu / Debian
To deploy Coroot on a Ubuntu or Debian node, follow these steps:
Step #1: Installing ClickHouse
sudo apt install -y apt-transport-https ca-certificates curl gnupg
curl -fsSL 'https://packages.clickhouse.com/rpm/lts/repodata/repomd.xml.key' | sudo gpg --dearmor -o /usr/share/keyrings/clickhouse-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/clickhouse-keyring.gpg] https://packages.clickhouse.com/deb stable main" | sudo tee /etc/apt/sources.list.d/clickhouse.list
sudo apt update
sudo DEBIAN_FRONTEND=noninteractive apt install -y clickhouse-server clickhouse-client
sudo service clickhouse-server start
Step #2: Installing Prometheus
Coroot requires Prometheus with support for Remote Write Receiver, which has been available since v2.25.0.
sudo apt install -y prometheus
sudo service prometheus start
Enable Remote Write Receiver in Prometheus by adding the --enable-feature=remote-write-receiver argument to the /etc/default/prometheus file:
# Set the command-line arguments to pass to the server.
# Due to shell escaping, to pass backslashes for regexes, you need to double
# them (\\d for \d). If running under systemd, you need to double them again
# (\\\\d to mean \d), and escape newlines too.
ARGS="--enable-feature=remote-write-receiver"
Restart Prometheus:
sudo service prometheus restart
Step #3: Installing Coroot
curl -sfL https://raw.githubusercontent.com/coroot/coroot/main/deploy/install.sh | \
BOOTSTRAP_PROMETHEUS_URL="http://127.0.0.1:9090" \
BOOTSTRAP_REFRESH_INTERVAL=15s \
BOOTSTRAP_CLICKHOUSE_ADDRESS=127.0.0.1:9000 \
sh -
Step #4: Installing coroot-node-agent
curl -sfL https://raw.githubusercontent.com/coroot/coroot-node-agent/main/install.sh | \
COLLECTOR_ENDPOINT=http://127.0.0.1:8080 \
SCRAPE_INTERVAL=15s \
sh -
Step #5: Accessing Coroot
Access Coroot at: http://<node_ip>:8080.
CentOS / RHEL
To deploy Coroot on a CentOS or RHEL node, follow these steps:
Step #1: Installing ClickHouse
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://packages.clickhouse.com/rpm/clickhouse.repo
sudo yum install -y clickhouse-server clickhouse-client
sudo systemctl enable clickhouse-server
sudo systemctl start clickhouse-server
Step #2: Installing Prometheus
Coroot requires Prometheus with support for Remote Write Receiver, which has been available since v2.25.0.
Unfortunately, there is no official Prometheus RPM package. Here is a step-by-step guide on how to install Prometheus manually, including creating a systemd service file for it.
Create a Prometheus user:
sudo useradd --no-create-home --shell /bin/false prometheus
Navigate to the Prometheus download page, and find the URL for the latest version of Prometheus for Linux and your architecture.
Use wget to download it:
wget https://github.com/prometheus/prometheus/releases/download/v2.51.2/prometheus-2.51.2.linux-amd64.tar.gz
Extract the downloaded tarball and move the binary to /usr/local/bin/:
sudo yum -y install tar
tar xvfz prometheus-2.51.2.linux-amd64.tar.gz
sudo cp prometheus-2.51.2.linux-amd64/prometheus /usr/local/bin/
Create directories for Prometheus configuration files and data:
sudo mkdir /etc/prometheus
sudo mkdir /var/lib/prometheus
sudo chown -R prometheus:prometheus /etc/prometheus /var/lib/prometheus
Create a Prometheus configuration file:
sudo cat <<EOF >/etc/prometheus/prometheus.yml
global:
scrape_interval: 15s
EOF
Create a systemd service file for Prometheus:
sudo cat <<EOF >/etc/systemd/system/prometheus.service
[Unit]
Description=Prometheus
After=network.target
[Service]
User=prometheus
Group=prometheus
Type=simple
ExecStart=/usr/local/bin/prometheus --config.file /etc/prometheus/prometheus.yml --storage.tsdb.path /var/lib/prometheus --enable-feature=remote-write-receiver
[Install]
WantedBy=multi-user.target
EOF
Reload systemd to load the new service and start Prometheus:
sudo systemctl daemon-reload
sudo systemctl start prometheus
sudo systemctl enable prometheus
Step #3: Installing Coroot
curl -sfL https://raw.githubusercontent.com/coroot/coroot/main/deploy/install.sh | \
BOOTSTRAP_PROMETHEUS_URL="http://127.0.0.1:9090" \
BOOTSTRAP_REFRESH_INTERVAL=15s \
BOOTSTRAP_CLICKHOUSE_ADDRESS=127.0.0.1:9000 \
sh -
Step #4: Installing coroot-node-agent
curl -sfL https://raw.githubusercontent.com/coroot/coroot-node-agent/main/install.sh | \
COLLECTOR_ENDPOINT=http://127.0.0.1:8080 \
SCRAPE_INTERVAL=15s \
sh -
Step #5: Accessing Coroot
Access Coroot at: http://<node_ip>:8080.
CLI arguments
Argument |
Environment variable |
Default value |
Description |
{{a.name}} |
{{a.env}} |
{{a.def}} |
|