Reference

This page documents the castctl flags available for reliability metrics, explains how castctl automatically sizes components for your cluster, and describes what gets provisioned in the cluster during installation. For an overview of the feature and step-by-step installation instructions, see Reliability metrics.

castctl cluster connect flags

These flags are used with castctl cluster connect to install and configure reliability metrics.

These flags can be combined with flags for other Cast AI features in a single command:

castctl cluster connect \
  --non-interactive \
  --cluster-name production-us-east \
  --reliability-metrics \
  --cluster-optimization \
  --workload-autoscaler

castware upgrade flags

Use castctl castware upgrade to upgrade reliability metrics and all other Cast AI components in your cluster.

castctl castware upgrade --non-interactive

Upgrading with castware preserves your existing configuration and applies any new data migrations automatically when the collector restarts.

How castctl sizes components

When you run castctl cluster connect --reliability-metrics, castctl inspects your cluster before installing anything and automatically determines the right resource allocation for two components: the collector agent that runs on each node, and the metrics database.

You do not need to specify sizing manually. The selections below describe what castctl chooses and why.

Collector agent sizing

The collector agent runs as a DaemonSet (one instance per node) and observes HTTP and gRPC traffic on that node. castctl counts the maximum number of containers running on any single node and selects a sizing profile accordingly.

These profiles reflect expected traffic volume per node at each workload density level. A node running many containers typically serves more concurrent requests and needs more resources to observe them accurately.

Metrics database sizing

castctl also provisions a ClickHouse time-series database in your cluster for temporary metric storage. It sizes the database by summing your cluster's total allocatable CPU across all nodes.

The default persistent volume size for the metrics database is 10 GiB. Data collected in the cluster is retained for up to 7 days before being purged. It is exported to Cast AI continuously and only needs to be stored locally for a short window.

ClickHouse operator detection

castctl checks whether a ClickHouse operator (Altinity) is already running in your cluster before installing. If one is found, castctl skips the operator installation and reuses the existing one. This prevents conflicts on clusters that already use ClickHouse for other workloads.

If your cluster has restricted Custom Resource Definition permissions and the operator cannot be installed automatically, castctl will surface an error. In this case, install the Altinity ClickHouse Operator CRDs manually first, then re-run castctl cluster connect --reliability-metrics.

What gets installed in your cluster

When reliability metrics is enabled, castctl installs the following components in the castai-agent namespace:

All components are managed by castctl and castctl castware upgrade. You do not need to interact with them directly under normal operation.

Default monitored ports

The collector observes traffic on these ports by default:

Services on other ports

Traffic on ports not in this list is not collected. When installing with Helm, you can add ports by setting autoscaler.castai-kvisor.agent.reliabilityMetrics.obi.openPorts (a comma-separated list). For the full set of Helm values, see ArtifactHUB.

Helm charts

Installation via castctl is the recommended method. It takes care of many manual pitfalls and sets up the sizing profiles along with the requested resources properly.

To install the reliability-metrics stack with the Cast AI Helm chart, including for GitOps workflows, first review the generic Helm instructions at Helm charts.

Because castctl is not sizing the components for you, you will need to size the resources properly on your own, see:

• Collector agent sizing
• Metrics database sizing

Prerequisites

If you don't use the ClickHouse operator in your cluster, you need to install the Altinity ClickHouse CRDs:

kubectl apply -f https://raw.githubusercontent.com/Altinity/clickhouse-operator/refs/tags/release-0.27.0/deploy/operator/parts/crd.yaml

If you already use the ClickHouse operator configured to watch all namespaces (including castai-agent), disable the
ClickHouse operator installed by this chart by setting:

--set autoscaler.castai-kvisor.reliabilityMetrics.operator.enabled=false

Installation

helm repo add castai-helm https://castai.github.io/helm-charts
helm repo update

helm upgrade -i castai castai-helm/castai -n castai-agent --create-namespace \
  --set global.castai.apiKey="<apiKey>" \
  --set global.castai.provider="<provider>" \
  --set tags.readonly=true \
  --set autoscaler.castai-kvisor.enabled=true \
  --set autoscaler.castai-kvisor.reliabilityMetrics.enabled=true \
  --set autoscaler.castai-kvisor.reliabilityMetrics.operator.enabled=true \
  --set autoscaler.castai-kvisor.agent.reliabilityMetrics.obi.sizingProfile="<sizingProfile>" \
  --set autoscaler.castai-kvisor.reliabilityMetrics.clickhouse.resources.requests.cpu="<cpu>" \
  --set autoscaler.castai-kvisor.reliabilityMetrics.clickhouse.resources.requests.memory="<memory>" \
  --set autoscaler.castai-kvisor.reliabilityMetrics.clickhouse.resources.limits.memory="<memory>"

📘

Note

We run a Helm lookup check for the ClickHouse operator in your cluster. This lookup doesn't work well with helm template. If you want to run helm template in your setup, consider adding:

Bash

--set autoscaler.castai-kvisor.reliabilityMetrics.clickhouse.skipCRDValidation=true

For all available configuration options, see ArtifactHUB.

Common Helm values

The values below are the ones most Helm and GitOps users need beyond the install command. Paths are relative to the castai-kvisor chart, so prefix each with autoscaler.castai-kvisor. when setting it on the umbrella chart.

Exclusions are easier to set from a values file than from --set:

autoscaler:
  castai-kvisor:
    agent:
      reliabilityMetrics:
        obi:
          exclude:
            - k8s_namespace: "monitoring"
            - exe_path: "*nginx*"

Ensure successful installation

kubectl logs -l app.kubernetes.io/name=castai-kvisor-controller --tail 100 | grep "component=clickhouse_exporter"

Look for a line similar to the one below, which indicates that data was successfully sent to Cast AI:

time=2026-07-29T14:32:58.736Z level=INFO source=worker.go:205 msg="cursor committed: last_exported_time=2026-07-29 14:31:21 +0000 UTC last_exported_pk=16025012183535387539" component=clickhouse_exporter table=reliability_metrics_db

It can take up to 3 minutes for the data to start flowing to Cast AI.
If you don't see this log, ensure you have at least one observable process in your cluster.
To test the installation, rerun it with --set autoscaler.castai-kvisor.trafficGenerator.enabled=true.
It will create a traffic-gen namespace running some arbitrary traffic generators.