Install the operator

Deploy the OpenLIT Operator to your Kubernetes cluster using Helm, verify the installation, and keep it up to date.

This guide covers everything you need to install the OpenLIT Operator: cluster requirements, Helm-based installation (the primary method), verification steps, upgrades, and uninstallation.

Prerequisites

Cluster requirements

Requirement	Minimum	Recommended	Notes
Kubernetes version	1.19+	1.25+	Required for webhook support
RBAC	Enabled	Enabled	Required for operator permissions
Cluster admin access	Required	Required	To create Custom Resources

Resource requirements

Component	CPU	Memory	Notes
OpenLIT Operator	100m	128Mi	Per replica
Instrumentation init container	100m	128Mi	Per instrumented pod

Verify cluster readiness

Before installing, confirm your cluster is accessible and you have the necessary permissions:

# Check cluster connection and version
kubectl cluster-info
kubectl version

# Verify cluster admin access
kubectl auth can-i create customresourcedefinitions
kubectl auth can-i create clusterroles

Install with Helm

Helm is the recommended installation method. If you don’t have Helm, follow the official Helm installation guide.

1. Add the OpenLIT Helm repository

   helm repo add openlit https://openlit.github.io/helm/
   helm repo update
   
2. Install the operator

   Default install

   helm install openlit-operator openlit/openlit-operator
   
3. Verify the installation

   Check that the operator pod is running:

   kubectl get pods -n openlit -l app.kubernetes.io/name=openlit-operator
   

   Expected output:

   NAME                                READY   STATUS    RESTARTS   AGE
   openlit-operator-7b9c8d5f7b-xyz12   1/1     Running   0          30s
   

   Confirm the CRD was installed:

   kubectl get crd autoinstrumentations.openlit.io
   

   Check the operator logs:

   kubectl logs -n openlit deployment/openlit-operator
   

Install with kubectl

If you prefer to install without Helm, you can apply the manifest directly:

kubectl apply -f https://raw.githubusercontent.com/openlit/openlit/main/operator/deploy/openlit-operator.yaml

Install the CRD separately if needed:

kubectl apply -f https://raw.githubusercontent.com/openlit/openlit/main/operator/deploy/openlit.io_autoinstrumentations.yaml

Upgrade and maintenance

Check for available updates

# Update the Helm repository
helm repo update

# List available versions
helm search repo openlit/openlit-operator --versions

# Check the currently installed version
helm list -n openlit

Upgrade to the latest version

helm upgrade openlit-operator openlit/openlit-operator \
  --namespace openlit \
  --reuse-values

Upgrade to a specific version

Pin to a specific version in production environments:

helm upgrade openlit-operator openlit/openlit-operator \
  --namespace openlit \
  --version 1.2.0 \
  --reuse-values

Verify after upgrade

# Check pod status
kubectl get pods -n openlit -l app.kubernetes.io/name=openlit-operator

# Check operator logs
kubectl logs -n openlit deployment/openlit-operator

# Verify CRDs are updated
kubectl get crd autoinstrumentations.openlit.io -o yaml | grep version

Uninstall

# Remove the operator
helm uninstall openlit-operator -n openlit

# Remove CRDs (this also deletes all AutoInstrumentation resources)
kubectl delete crd autoinstrumentations.openlit.io

# Remove the namespace (optional)
kubectl delete namespace openlit

Deleting the CRD removes all AutoInstrumentation custom resources. Pods that were already instrumented continue to run, but new pods will no longer be instrumented until you reinstall the operator.

Troubleshooting

CRD installation failures

Symptoms: Error creating CustomResourceDefinitions

Solutions:

# Check RBAC permissions
kubectl auth can-i create customresourcedefinitions

# Manually install CRDs if needed
kubectl apply -f https://raw.githubusercontent.com/openlit/openlit/main/operator/deploy/openlit.io_autoinstrumentations.yaml

# Check cluster version compatibility
kubectl version

Webhook certificate errors

Symptoms: Webhook registration fails or returns certificate errors

Solutions:

# Check certificate secret
kubectl get secrets -n openlit | grep webhook

# Restart the operator to regenerate certificates
kubectl rollout restart deployment/openlit-operator -n openlit

# Inspect the webhook configuration
kubectl describe mutatingwebhookconfigurations openlit-operator

Image pull failures

Symptoms: Operator pods stuck in ImagePullBackOff

Solutions:

# Confirm the image is accessible
docker pull ghcr.io/openlit/openlit-operator:latest

# Check image pull secrets
kubectl get secrets -n openlit

# Inspect pod events
kubectl describe pod -n openlit -l app.kubernetes.io/name=openlit-operator