Zymtrace Helm Charts

https://github.com/zystem-io/zymtrace-charts
Admin
Zymtrace Helm Charts provides Kubernetes Helm charts to deploy Zymtrace self-hosted backend services...
Tokens:11,714
Snippets:104
Trust Score:6.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Backend with License Key

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/backend/README.md

Installs the backend chart without a values file, setting the global license key directly via --set. This is the basic installation method.

```bash
helm install backend zymtrace/backend \
  --namespace zymtrace \
  --create-namespace \
  --set global.licenseKey="your-license-key"
```

--------------------------------

### Upgrade Backend with Values File

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/backend/README.md

Upgrades or installs the backend chart using a values file for full configuration. The --install flag ensures installation if not already present, and --debug provides verbose output.

```bash
helm upgrade --install backend zymtrace/backend \
  --namespace zymtrace \
  --create-namespace \
  -f backend-values.yaml \
  --debug
```

--------------------------------

### Install Backend with Values File

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/backend/README.md

Installs the backend chart using a custom values file. The command creates the 'zymtrace' namespace and uses the specified values file for configuration.

```bash
helm install backend zymtrace/backend \
  --namespace zymtrace \
  --create-namespace \
  -f backend-values.yaml
```

--------------------------------

### Install profiler with a values file

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/profiler/README.md

Installs the profiler chart using a custom values file. Creates the namespace if it does not exist.

```bash
helm install profiler zymtrace/profiler \
  --namespace zymtrace \
  --create-namespace \
  -f profiler-values.yaml
```

--------------------------------

### Install profiler without a values file (GPU profiling with metrics)

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/profiler/README.md

Installs the profiler chart with GPU profiling and metrics enabled via --set flags. Use --nvml-path instead of --nvml-auto-scan if you know the exact NVML library path.

```bash
helm install profiler zymtrace/profiler \
  --namespace zymtrace \
  --create-namespace \
  --set profiler.cudaProfiler.enabled=true \
  --set profiler.args[0]="--collection-agent=zymtrace-gateway.zymtrace.svc.cluster.local:80" \
  --set profiler.args[1]="--disable-tls" \
  --set profiler.args[2]="--enable-gpu-metrics" \
  --set profiler.args[3]="--nvml-auto-scan"
```

--------------------------------

### Install profiler without a values file (CPU profiling only)

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/profiler/README.md

Installs the profiler chart for CPU-only profiling. Omit GPU-related options for CPU-only profiling.

```bash
helm install profiler zymtrace/profiler \
  --namespace zymtrace \
  --create-namespace \
  --set profiler.args[0]="--collection-agent=zymtrace-gateway.zymtrace.svc.cluster.local:80" \
  --set profiler.args[1]="--disable-tls"
```

--------------------------------

### Install Backend with External Databases

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/backend/README.md

Installs the backend chart configured to use existing external ClickHouse and PostgreSQL databases. Requires setting host, user, and password for each database.

```bash
helm install backend zymtrace/backend \
  --namespace zymtrace \
  --create-namespace \
  --set clickhouse.mode="use_existing" \
  --set clickhouse.use_existing.host="https://clickhouse.example.com:8443" \
  --set clickhouse.use_existing.user="your-user" \
  --set clickhouse.use_existing.password="your-password" \
  --set postgres.mode="use_existing" \
  --set postgres.use_existing.host="postgres.example.com:5432" \
  --set postgres.use_existing.user="your-user" \
  --set postgres.use_existing.password="your-password"
```

--------------------------------

### Full GPU Configuration Example

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/profiler/README.md

Complete GPU profiling configuration with CUDA enabled, custom host mount path, GPU metrics, NVML auto-scan, custom tags, node selector for GPU nodes, and resource requests/limits.

```yaml
profiler:
  cudaProfiler:
    enabled: true
    hostMountPath: "/var/lib/zymtrace/profiler"
  args:
    - "--collection-agent=zymtrace-gateway.zymtrace.svc.cluster.local:80"
    - "--disable-tls"
    - "--enable-gpu-metrics"
    - "--nvml-auto-scan"
    - "--tags=cloud_region:us-central1;env:production"
  nodeSelector:
    nvidia.com/gpu: "true"
  resources:
    requests:
      cpu: "200m"
      memory: "256Mi"
    limits:
      cpu: "1000m"
      memory: "1Gi"
```

--------------------------------

### Upgrade with a values file (full config)

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/profiler/README.md

Performs an install or upgrade of the profiler chart using a values file for full configuration. Creates the namespace if it does not exist and enables debug output.

```bash
helm upgrade --install profiler zymtrace/profiler \
  --namespace zymtrace \
  --create-namespace \
  -f profiler-values.yaml \
  --debug
```

--------------------------------

### Helm release management commands

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/backend/templates/NOTES.txt

Commands to view status, get release details, and upgrade the release.

```bash
$ helm status {{ .Release.Name }} -n {{ .Release.Namespace }}
```

```bash
$ helm get all {{ .Release.Name }} -n {{ .Release.Namespace }}
```

```bash
$ helm upgrade {{ .Release.Name }} . -n {{ .Release.Namespace }}
```

--------------------------------

### GPU Profiling with Custom Tags

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/profiler/README.md

Enables CUDA profiling with GPU metrics and adds custom tags (cloud_region and env) to the profiled data. Useful for labeling metrics in multi-environment setups.

```yaml
profiler:
  cudaProfiler:
    enabled: true
  args:
    - "--collection-agent=zymtrace-gateway.zymtrace.svc.cluster.local:80"
    - "--disable-tls"
    - "--enable-gpu-metrics"
    - "--nvml-auto-scan"
    - "--tags=cloud_region:us-central1;env:staging"
```

--------------------------------

### Disable NetworkPolicies

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/backend/README.md

NetworkPolicies are enabled by default to restrict database access. Set services.activateNetworkPolicies to false to disable them, for example when using Flannel clusters.

```yaml
services:
  activateNetworkPolicies: false
```

--------------------------------

### Verify deployment and services

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/backend/templates/NOTES.txt

Check all resources and verify core services with app label. Commands use placeholders for release namespace and global namePrefix.

```bash
$ kubectl get all -n {{ .Release.Namespace }}
```

```bash
$ kubectl get pods -n {{ .Release.Namespace }} -l app={{ .Values.global.namePrefix }}
$ kubectl get svc -n {{ .Release.Namespace }} -l app={{ .Values.global.namePrefix }}
```

```bash
$ kubectl get pods -n {{ .Release.Namespace }} -l app=clickhouse
$ kubectl get pods -n {{ .Release.Namespace }} -l app=postgres
```

```bash
$ kubectl logs -f -n {{ .Release.Namespace }} -l app={{ include "zymtrace.resourceName" (list $ "web") }}
$ kubectl logs -f -n {{ .Release.Namespace }} -l app={{ include "zymtrace.resourceName" (list $ "ingest") }}
```

--------------------------------

### Basic configuration with Ingress

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/backend/README.md

Configures the global license key and enables ingress with an nginx class, a gateway host, and TLS for the specified domain.

```yaml
global:
  licenseKey: "your-license-key"

ingress:
  enabled: true
  className: "nginx"
  hosts:
    gateway:
      enabled: true
      host: "zymtrace.company.com"
  tls:
    - secretName: zymtrace-tls
      hosts:
        - zymtrace.company.com
```

--------------------------------

### Troubleshooting commands

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/backend/templates/NOTES.txt

Commands to diagnose common issues: ImagePullBackOff, service connections, and storage problems.

```bash
$ kubectl get pods -n {{ .Release.Namespace }}
$ kubectl describe pod <pod-name> -n {{ .Release.Namespace }}
Check registry credentials and connectivity
```

```bash
$ kubectl get endpoints -n {{ .Release.Namespace }}
Verify service discovery and network policies
```

```bash
$ kubectl get pvc -n {{ .Release.Namespace }}
Check storage class and provisioner
```

--------------------------------

### Upgrade Backend License Key

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/backend/README.md

Upgrades the backend chart to update the global license key. Uses --reset-then-reuse-values to keep existing values and --debug for detailed output.

```bash
helm upgrade backend zymtrace/backend \
  --namespace zymtrace \
  --reset-then-reuse-values \
  --set global.licenseKey="NEW_LICENSE_KEY" \
  --debug
```

--------------------------------

### Connect to Google Cloud SQL PostgreSQL

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/backend/README.md

Configures the chart to use a Google Cloud SQL PostgreSQL instance with Workload Identity and a service account.

```yaml
postgres:
  mode: "gcp_cloudsql"
  gcp_cloudsql:
    instance: "my-project:us-central1:zymtrace-pg"
    user: "zt-db@my-project.iam"
    workloadIdentity:
      enabled: true
    serviceAccount: "zymtrace-cloudsql-sa"
```

--------------------------------

### Search available versions

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/profiler/README.md

Lists available versions of the zymtrace chart.

```bash
helm search repo zymtrace --versions
```

--------------------------------

### Use external object storage with AWS S3 or Google Cloud Storage

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/backend/README.md

Shows two alternative configurations for external object storage: one for AWS S3 and one for Google Cloud Storage. Only one storage block should be used at a time.

```yaml
# AWS S3
storage:
  mode: "use_existing"
  use_existing:
    type: "s3"
    s3:
      region: "us-west-2"
      accessKey: "your-access-key"
      secretKey: "your-secret-key"

# Or Google Cloud Storage
storage:
  mode: "use_existing"
  use_existing:
    type: "gcs"
    gcs:
      accessKey: "your-hmac-access-key"
      secretKey: "your-hmac-secret-key"
```

--------------------------------

### CUDA Profiling with GPU Metrics (explicit NVML path)

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/profiler/README.md

Enables CUDA profiling and GPU metrics with an explicit NVML library path. Use this when the NVML library is not in the default location.

```yaml
profiler:
  cudaProfiler:
    enabled: true  # Enables CUDA/GPU kernel profiling
  args:
    - "--collection-agent=zymtrace-gateway.zymtrace.svc.cluster.local:80"
    - "--disable-tls"
    - "--enable-gpu-metrics"  # Enables GPU metrics collection
    - "--nvml-path=/usr/lib/x86_64-linux-gnu/libnvidia-ml.so.1"
```

--------------------------------

### Enable AI assistant with multiple providers and custom LLM

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/backend/README.md

Configures the AI assistant with optional Anthropic, Gemini, and OpenAI API keys, plus an optional custom LLM endpoint and advanced settings like request size limit and session clear frequency.

```yaml
aiAssistant:
  enabled: true

  # Configure one or more AI providers
  anthropic:
    apiKey: "sk-ant-api03-..."

  gemini:
    apiKey: "AIzaSy..."

  openai:
    apiKey: "sk-proj-..."

  # Optional: Custom LLM endpoint (e.g., Groq, Together AI, self-hosted)
  customLLM:
    url: "https://your-llm-endpoint.com/v1/chat/completions"
    apiKey: "your-custom-api-key"
    models: "model-1,model-2"

  # Optional: Advanced configuration
  requestSizeLimit: 20971520  # 20 MiB
  sessionClearFreq: 3600  # 1 hour
```

--------------------------------

### Upgrade with --reset-then-reuse-values for existing_pvc mode

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/backend/templates/NOTES.txt

Recommended upgrade command for Helm >= 3.14 when using existing_pvc storage type. It reuses only explicit values and picks up new defaults. Must combine with explicit storage flags.

```bash
helm upgrade {{ .Release.Name }} . -n {{ .Release.Namespace }} \
  --reset-then-reuse-values \
  --set clickhouse.create.storage.type=existing_pvc \
  --set clickhouse.create.storage.existing_pvc.pvcName=<your-pvc>
```

--------------------------------

### Upgrade Backend Image Tag

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/backend/README.md

Upgrades the backend chart to a new image tag while reusing existing values. The --reset-then-reuse-values flag preserves current settings, and --debug provides verbose output.

```bash
helm upgrade backend zymtrace/backend \
  --namespace zymtrace \
  --reset-then-reuse-values \
  --set services.common.imageTag="NEW_VERSION" \
  --debug
```

--------------------------------

### Enable Horizontal Pod Autoscaling (HPA)

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/backend/README.md

Enables HPA for automatic scaling based on CPU and memory utilization. Configure minReplicas, maxReplicas, and target utilization percentages.

```yaml
services:
  common:
    hpa:
      enabled: true
      minReplicas: 1
      maxReplicas: 10
      targetCPUUtilizationPercentage: 60
      targetMemoryUtilizationPercentage: 70
```

--------------------------------

### CUDA Profiling with GPU Metrics

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/profiler/README.md

Enables CUDA/GPU kernel profiling and GPU metrics collection. Includes flags for GPU metrics and automatic NVML scanning.

```yaml
profiler:
  cudaProfiler:
    enabled: true  # Enables CUDA/GPU kernel profiling
  args:
    - "--collection-agent=zymtrace-gateway.zymtrace.svc.cluster.local:80"
    - "--disable-tls"
    - "--enable-gpu-metrics"  # Enables GPU metrics collection
    - "--nvml-auto-scan"
```

--------------------------------

### Access gateway via port-forward

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/backend/templates/NOTES.txt

Port-forward to the gateway service and access the application at localhost:8080.

```bash
$ kubectl port-forward -n {{ .Release.Namespace }} svc/{{ include "zymtrace.resourceName" (list $ "gateway") }} 8080:{{ .Values.services.gateway.port }}
```

```bash
Then visit: http://localhost:8080
```

```bash
$kubectl get svc -n {{ .Release.Namespace }} - should display a NodePort, if enabled.
```

--------------------------------

### Add zymtrace Helm repository

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/profiler/README.md

Adds the zymtrace Helm repository and updates the local repository cache.

```bash
helm repo add zymtrace https://helm.zystem.io
helm repo update
```

--------------------------------

### Connect to external ClickHouse and PostgreSQL databases

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/backend/README.md

Configures the chart to use existing external ClickHouse and PostgreSQL databases by specifying host, user, password, and optional secure connection.

```yaml
clickhouse:
  mode: "use_existing"
  use_existing:
    host: "https://clickhouse.example.com:8443"
    user: "your-username"
    password: "your-password"

postgres:
  mode: "use_existing"
  use_existing:
    host: "postgres.example.com:5432"
    user: "your-username"
    password: "your-password"
    secure: true
```

--------------------------------

### Upgrade image tag only

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/profiler/README.md

Upgrades the profiler Helm release to a new image tag while reusing existing values. Uses --reset-then-reuse-values to reset and reuse values, and --debug for verbose output.

```bash
helm upgrade profiler zymtrace/profiler \
  --namespace zymtrace \
  --reset-then-reuse-values \
  --set profiler.image.tag="NEW_VERSION" \
  --debug
```

--------------------------------

### Upgrade with --reuse-values for Helm < 3.14

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/backend/templates/NOTES.txt

Alternative upgrade command for Helm versions before 3.14. storage.type is preserved verbatim from previous release, so pass storage flags explicitly to ensure pvcName is applied.

```bash
helm upgrade {{ .Release.Name }} . -n {{ .Release.Namespace }} \
  --reuse-values \
  --set clickhouse.create.storage.type=existing_pvc \
  --set clickhouse.create.storage.existing_pvc.pvcName=<your-pvc>
```

--------------------------------

### CPU Profiling Only

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/profiler/README.md

Configures the profiler for CPU-only profiling by setting the collection agent address and disabling TLS.

```yaml
profiler:
  args:
    - "--collection-agent=zymtrace-gateway.zymtrace.svc.cluster.local:80"
    - "--disable-tls"
```

--------------------------------

### CUDA Profiling Only (without GPU metrics)

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/profiler/README.md

Enables CUDA/GPU kernel profiling without GPU metrics collection. Use this when you only need kernel-level profiling.

```yaml
profiler:
  cudaProfiler:
    enabled: true
  args:
    - "--collection-agent=zymtrace-gateway.zymtrace.svc.cluster.local:80"
    - "--disable-tls"
```

--------------------------------

### Target GPU Nodes Only

Source: https://github.com/zystem-io/zymtrace-charts/blob/main/charts/profiler/README.md

Enables CUDA profiling and restricts the profiler to nodes with the label nvidia.com/gpu: "true" using a nodeSelector. Includes GPU metrics and NVML auto-scan.

```yaml
profiler:
  cudaProfiler:
    enabled: true
  nodeSelector:
    nvidia.com/gpu: "true"
  args:
    - "--collection-agent=zymtrace-gateway.zymtrace.svc.cluster.local:80"
    - "--disable-tls"
    - "--enable-gpu-metrics"
    - "--nvml-auto-scan"
```
Tokens:
Raw