Running Cribl Stream on Kubernetes with Helm

Cribl publishes Helm charts that boot fully provisioned Leader and Worker Nodes to a Kubernetes cluster. This post follows the documented path: prerequisites, the leader install and the values worth setting, the worker group install, and what we verify afterwards. It is based on the Kubernetes Leader Deployment page, the Kubernetes Worker Deployment page, and the Considerations for Cribl Stream on Kubernetes guide.

Prerequisites

The AWS and Kubernetes prerequisites below come from the leader deployment page; the worker deployment page lists the same set, with a bias toward the EKS-oriented approach Cribl uses for its own deployments.

Set up AWS CLI, version 2, and create or modify ~/.aws/config so it contains a [profile] section with your SSO start URL, SSO region, SSO account ID, SSO role name, and region.
Set up kubectl on your local machine or VM, following the Kubernetes installation instructions.
Add your cluster to ~/.kube/config by running aws --profile <profile-name> eks update-kubeconfig --name <cluster-name>, then insert the --profile= argument as the new first child of the args section and change the command entry to the full path of the aws executable, usually /usr/local/bin/aws.
Install Helm (preferably 3.x), then add Cribl's repository to Helm:

helm repo add cribl https://criblio.github.io/helm-charts/

The charts require persistent storage. The leader chart uses your default StorageClass, or the class you set in config.scName; Cribl tested it primarily with AWS EBS via the CSI EBS driver, with ReadWriteOnce claims. On EKS, use Availability Zone-specific node groups and do not let a node group span AZs, because EBS volumes are AZ-specific.

Installing the leader

The leader chart installs what the page describes as "a deployment, two services, and a number of persistent volumes." The main service is named after the Helm release and serves as the primary interface for users, while the "internal" service, named <helm-release>-internal, is intended for worker-group-to-leader communication. The page notes the chart is "a work in progress, provided as-is," and Cribl recommends deploying the Leader on stable, highly available infrastructure because of its role coordinating all Worker instances.

The documented values workflow: copy the chart's default values.yaml from the Cribl helm-charts repository, save it locally (for example /bar/values.yaml), modify it, and install with that file. The basic install commands, verbatim from the page:

helm install logstream-leader cribl/logstream-leader

helm install logstream-leader cribl/logstream-leader --set config.scName='ebs-sc'

Without overrides, the chart effectively creates a single-instance deployment of Cribl Stream using the standard container image; licensing, passwords, and distributed mode can be configured later from the UI. The values the leader page documents for setting upfront:

Match versions. Cribl recommends the same Cribl Stream version on Worker Nodes as on the Leader Node. If your Workers are not yet on the version in the Leader's default values.yaml > criblImage.tag, override that value to match.
Service account. You can configure the Leader deployment to use a Kubernetes ServiceAccount for accessing cloud resources, an approach the page calls especially beneficial when you need to grant IAM roles directly to the Leader pod. The documented options are serviceAccount.create (default false), serviceAccount.name (defaults to <release>-leader when create is true and the name is unset; when create is false, the name must match an existing ServiceAccount), and serviceAccount.annotations, where you can declare the IAM roles the service account may access. The page's example:

serviceAccount:
  create: true
  name: "cribl-leader-sa"
  annotations:
    eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/cribl-leader-role"

License. If you have a Standard or Enterprise license, pass it as an override to your install; the page's example already redacts the license string:

helm install logstream-leader cribl/logstream-leader --set config.license="<long encoded license string redacted>"

If you do not specify a license with config.license and want to run distributed, go to Cribl Stream's Settings > Licensing page and accept the Free license there. The Free license allows one Worker Group or Fleet.
Admin password. Normally, when you first install Cribl Stream and log into the UI, it prompts you to change the default admin password. Set config.adminPassword to skip that challenge:

helm install logstream-leader cribl/logstream-leader --set config.adminPassword="<new password>"

Worker groups and mappings. If your Helm configuration includes the config.groups option, the Leader is configured as a distributed Leader; if you omit it, it is configured as a single instance. Each group in the list is created as a Worker Group, with a Mapping Rule to seek a tag with that Worker Group's name in it:

helm install logstream-leader cribl/logstream-leader --set config.groups={group1,group2,group3}

On EKS, the page shows a typical set of load balancer annotations, such as S3 access-log settings, as values under the service.annotations key.

One post-install note from the page: Cribl Stream will not automatically deploy configuration changes to the Worker Nodes or Edge Nodes. You will need to commit and deploy changes to all of your Worker Groups and Fleets.

Workers

The logstream-workergroup chart deploys "a deployment, a service, a horizontal pod autoscaler configuration, and a secret used for configuration," and its functioning depends on the presence of a Cribl Stream Leader Node. The install commands, verbatim from the worker deployment page:

helm install logstream-wg cribl/logstream-workergroup

helm install logstream-wg cribl/logstream-workergroup --set config.host='logstream.lab.cribl.io' -n cribl-helm

Point config.host at the Leader's internal service, whose name ends in -internal. The leader page's worker-group values file, with the token redacted:

config:
  host: logstream-master-internal
  group: kubernetes
  token: <your-token>
  rejectSelfSignedCerts: 0

For all container-based Worker Groups, Cribl recommends directly specifying the Worker Process count with a positive integer (like +3), a convention that "prevents the overprovisioning of Worker Processes" that dynamic values, like the default -2 setting, can cause. For the environment side, the considerations guide shows --set env.CRIBL_MAX_WORKERS=NUMBER_WORKER_PROCESSES to cap Worker Processes per pod, and the worker page documents CRIBL_MAX_WORKERS as an in-product limit that stops Cribl Stream from spawning more Worker Processes than specified, even if the node has available resources. The workergroup chart also sets CRIBL_K8S_CPU_LIMIT to the pod's resources.limits.cpu value so Worker Processes track the allocated CPU rather than the host, and Cribl recommends maintaining that default even with a static process count.

Persistent queue storage

Use persistent volumes with the Worker Group deployment for durable storage of staging files or persistent queues (PQ). Configure PQ storage at the Worker Group level: the local filesystem on each Worker, a shared Network filesystem (NFS) mounted on Worker Nodes and the Leader at the same path, or AWS S3, which the considerations guide calls the recommended shared option where Workers are replaced or scaled frequently. Attach volumes with the chart's extraVolumeMounts option and set CRIBL_VOLUME_DIR to the PVC mount point so the Worker GUID is consistent on each startup; you also need extraVolumeMounts in non-root environments like Anthos and OpenShift. For local or NFS storage, use StatefulSet mode so pods retain stable identities and volume assignments, and define the PVCs in the chart's volumeClaimTemplates, aligned with CRIBL_VOLUME_DIR.

With shared PQ storage, the Leader can detect orphaned PQ data from a disconnected Worker and reassign it to surviving Workers for draining. By default, it waits until a Worker has been absent for 20 minutes before treating its PQ data as orphaned. The window is tunable in Worker Group Settings > System > PQ Orphan Management, or through the /system/pq/orphan-management API. The guide also says to validate scale-down and scale-up in a non-production environment before enabling automatic scale-in, and to give HPA scale-in policies enough time for PQ data to flush before pods terminate.

One networking fact: the chart specifies the service type as LoadBalancer. On self-managed Kubernetes, the cluster must provide a load balancer, or you can enable the chart's optional Ingress controller configuration, which is disabled by default. Both chart pages' known-issue lists state that Worker Group service > ports support only TCP ports for now.

Verification

The pages verify an install with kubectl. The leader page's example, for a release named lsms in the logstream-ht namespace:

kubectl get pods -n logstream-ht

NAME                                           READY   STATUS    RESTARTS   AGE
lsms-leader-659bfccdd6-xsz67                   1/1     Running   0          52m

Next, find the two services the leader created; the leader page runs this with its ls-lead release:

kubectl get service -n <namespace> | grep ls-lead

then uses the service that ends in -internal (in the page's example, ls-lead-leader-internal) as the worker groups' host.

Finally, log in to the Cribl Stream UI through the main load-balanced service. If you did not set config.adminPassword, the first login prompts you to change the default admin password. Check Settings > Licensing to accept the Free license if needed, and Settings > Distributed Settings to select Mode: Leader if you omitted config.groups. Changes made in the UI must be committed and deployed to each Worker Group or Fleet.

What we check on real clusters

This short list is our partner-side guidance from deployments we have stood up, not Cribl documentation.

Confirm the leader created both services, and that every worker group's config.host points at the -internal one, not the main one.
Diff criblImage.tag across the leader and every worker group release before you declare the deployment healthy.
On EKS, check node group AZ placement before the first volume mount, because EBS volumes are AZ-specific and a misplacement shows up as mount trouble later.
Verify the Worker Process count is a positive integer and CRIBL_K8S_CPU_LIMIT still tracks the pod CPU limit after chart upgrades.
Exercise scale-down and scale-up in a non-production environment before autoscaling is enabled, and prefer StatefulSet with shared PQ storage when workers churn.
Watch PQ health alerts and Worker pod volume issues; orphan reassignment recovers shared PQ data, but the default window means you should see the alert first.

Frequently asked questions

Which Helm charts does Cribl Stream deploy on Kubernetes with?

Cribl ships a logstream-leader chart for the Leader and a logstream-workergroup chart for Worker Groups, both installed from the cribl Helm repository. The leader chart installs only a Leader Node by default, as a single instance unless you set the config.groups option.

How do you point a Cribl Stream worker group at its Leader during a Helm install?

Set the config.host value to the Leader's internal service, the one named after the Helm release with -internal appended. In the leader page's values example, that group also sets config.group to the Worker Group name and config.token so the release can join the group.

What storage does the Cribl Stream leader chart use by default?

The leader chart requires persistent storage and uses your default StorageClass unless you override config.scName. Cribl tested it primarily with AWS EBS storage via the CSI EBS driver, creating the volumes as ReadWriteOnce claims.

How does Cribl Stream limit Worker Processes on a Kubernetes pod?

Set the CRIBL_MAX_WORKERS environment variable, for example with the --set env.CRIBL_MAX_WORKERS override shown in the considerations guide, to cap the Worker Processes a pod can run. The workergroup chart also sets CRIBL_K8S_CPU_LIMIT to the pod's CPU limit, and Cribl recommends maintaining that default.

Verified against Cribl Stream 4.20 documentation on October 3, 2026.