Important: If you’re using or looking to use Opik or Comet enterprise version please reach out to Sales@comet.com to gain access to the correct deployment documentation.

For production deployments, we recommend using our Kubernetes Helm chart. This chart is designed to be highly configurable and has been battle-tested in Comet’s managed cloud offering.

Prerequisites

In order to install Opik on a Kubernetes cluster, you will need to have the following tools installed:

Helm
kubectl
Optional: kubectx and kubens to switch between Kubernetes clusters and namespaces.

Installation

You can install Opik using the helm chart maintained by the Opik team by running the following commands:

Add Opik Helm repo

$ helm repo add opik https://comet-ml.github.io/opik/
> helm repo update

You can set VERSION to the specific Opik version or leave it as ‘latest’

$ VERSION=latest
> helm upgrade --install opik -n opik --create-namespace opik/opik \
>     --set component.backend.image.tag=$VERSION \
>     --set component.python-backend.image.tag=$VERSION \
>     --set component.python-backend.env.PYTHON_CODE_EXECUTOR_IMAGE_TAG="$VERSION" \
>     --set component.frontend.image.tag=$VERSION

You can port-forward any service you need to your local machine:

$ kubectl port-forward -n opik svc/opik-frontend 5173

Opik will be available at http://localhost:5173.

Configuration

You can find a full list the configuration options in the helm chart documentation.

Advanced deployment options

Configure external access

Configure ingress for opik-frontend

1 component:
2     frontend:
3       ingress:
4         enabled: true
5         ingressClassName: <your ingress class>
6         annotations:
7             <your annotations>
8         hosts:
9             - host: opik.example.com
10             paths:
11                 - path: /opik
12                   port: 5173
13                   pathType: Prefix
14                 - path: /opik/api
15                   port: 5173
16                   pathType: Prefix

Configure LoadBalancer service for clickhouse

1 clickhouse:
2   service:
3     serviceTemplate: clickhouse-cluster-svc-lb-template
4     annotations: <your clickhouse LB service annotations>

Configure Clickhouse backup on S3 (or minio)

With AWS Key and Secret key

You will need to create a secret with the credentials for the S3 bucket you want to use for backup with following values:

1 access_key_id: <your access key id>
2 access_key_secret: <your access key secret>

Add to your configuration

1 clickhouse:
2   backup:
3     enabled: true
4     bucketURL: https://<your bucket.s3.<region>.amazonaws.com
5     secretName: <your secret name with credential for clickhouse backup>
6     schedule: <your cron schedule, like "00 03 * * *">
7     baseBackup: ""

With IAM Role

1 clickhouse:
2   backup:
3     enabled: true
4     bucketURL: https://<your bucket>.s3.<region>.amazonaws.com
5     schedule: <your cron schedule, like "00 03 * * *">
6     baseBackup: ""
7     serviceAccount:
8       enabled: true
9       create: true
10       annotations:
11         eks.amazonaws.com/role-arn: <your IAM role arn>

Configure replication for Clickhouse

Important Limitation:
You must have Opik running before you enable replication for ClickHouse.
Attempting to set up replication before Opik is running may result in errors or misconfiguration.

1 clickhouse:
2   replicasCount: 2

Use S3 bucket for Opik

Using AWS key and secret keys

1 component:
2   backend:
3     env:
4       S3_BUCKET: <your_bucket_name>
5       S3_REGION: <aws_region>
6       AWS_ACCESS_KEY_ID: <your AWS Key>
7       AWS_SECRET_ACCESS_KEY: <your AWS Secret>

Use IAM Role

If your IAM role is configured for the k8s nodes, the only things you will need is to set for opik-backend:

1 component:
2   backend:
3     env:
4       S3_BUCKET: <your_bucket_name>
5       S3_REGION: <aws_region>

If your role should be used by opik-backend serviceAccount, in addition you need to set:

1 component:
2   backend:
3     serviceAccount:
4       enabled: true
5       annotations:
6         eks.amazonaws.com/role-arn: <your IAM Role arn>

Use external Clickhouse installation

Supported from Opik chart version 1.4.2

Configuration snippet for using external Clickhouse:

1 component:
2     backend:
3       ...
4       env:
5         ANALYTICS_DB_MIGRATIONS_URL: "jdbc:clickhouse://<YOUR CLICKHOUSE HOST>:8123"
6         ANALYTICS_DB_HOST: "<YOUR CLICKHOUSE HOST>"
7         ANALYTICS_DB_DATABASE_NAME: "opik"
8         ANALYTICS_DB_MIGRATIONS_USER: "opik"
9         ANALYTICS_DB_USERNAME: "opik"
10         ANALYTICS_DB_MIGRATIONS_PASS: "xxx"
11         ANALYTICS_DB_PASS: "xxx"
12     ...
13 clickhouse:
14     enabled: false

The passwords can be handled in the secret, and then you should configure it as following

1 component:
2     backend:
3       ...
4       envFrom:
5         - configMapRef:
6             name: opik-backend
7         - secretRef:
8             name: <your secret name>
9       env:
10         ANALYTICS_DB_MIGRATIONS_URL: "jdbc:clickhouse://<YOUR CLICKHOUSE HOST>:8123"
11         ANALYTICS_DB_HOST: "<YOUR CLICKHOUSE HOST>"
12         ANALYTICS_DB_DATABASE_NAME: "opik"
13         ANALYTICS_DB_MIGRATIONS_USER: "opik"
14         ANALYTICS_DB_USERNAME: "opik"
15 ...
16 clickhouse:
17     enabled: false

Delete your installation

Before deleting opik installation with helm, make sure to remove finilizer on the clickhouse resource:

$ kubectl patch -n opik chi opik-clickhouse --type json --patch='[ { "op": "remove", "path": "/metadata/finalizers" } ]'

Then, uninstall the opik:

$ helm uninstall opik -n opik

Troubleshooting

If you get this error when running helm

$ ERROR: Exception Primary Reason:  Code: 225. DB::Exception: Can't create replicated table without ZooKeeper. (NO_ZOOKEEPER) (version 24.3.5.47.altinitystable (altinity build))

Please make sure you use the latest Opik helm chart version that runs zookeeper by default