Skip to main content

Deploy with Helm

The aperturedata/aperturedb-helm OCI chart deploys distributed ApertureDB into an existing Kubernetes cluster. The default topology has three database pods, three ZooKeeper pods, two Lenz gateways, one checkpointer, a Web UI, and telemetry.

Prerequisites​

  • Kubernetes 1.23 or later, kubectl configured for the intended cluster, and Helm 3.8 or later.

  • An object storage bucket and credentials; see Deploying ApertureDB.

  • A storage class that can provision persistent volumes for ZooKeeper and, when telemetry is enabled, a shared 100Gi monitoring volume.

  • Enough cluster capacity for the configured workloads. By default, each database pod and the checkpointer requests 8Gi of memory, and each Lenz pod requests 1Gi, in addition to the other components.

  • An ingress controller for HTTP access. The example below uses an existing ingress-nginx controller with class nginx. The chart also has an optional bundled controller.

  • LoadBalancer support for the default external TCP service, or a plan to expose a NodePort or ClusterIP service instead.

Use a separate namespace per deployment: several resource names, including lenz and lenz-external, are fixed within the namespace.

Configure and install​

Save the following as my-values.yaml, replacing the placeholders with credentials, a bucket name, and your hostname:

masterKey:
  password: "<strong-database-password>"

storage:
  type: s3
  bucket: "<your-bucket-name>"
  credentials: '{"access_key":"<access-key>","secret_access_key":"<secret-access-key>","region":"us-west-2"}'

service:
  type: LoadBalancer

ingress:
  enabled: true
  className: nginx
  host: aperturedb.example.com
  tls: true

telemetry:
  enabled: true
  auth:
    password: "<separate-monitoring-password>"
  grafana:
    adminPassword: "<strong-grafana-password>"

For Google Cloud Storage, set storage.type: gs and use the service account JSON as storage.credentials. To provision the bundled ingress controller, set ingress-nginx.enabled: true and remove ingress.className from your values so the chart selects the bundled controller’s class. In shared clusters, set both ingress-nginx.controller.ingressClassResource.name and ingress-nginx.controller.ingressClass to a unique class per deployment.

Select a published package version and install:

chmod 600 my-values.yaml
helm install aperturedb oci://registry-1.docker.io/aperturedata/aperturedb-helm \
  --version <package-version> \
  --namespace aperturedb --create-namespace \
  -f my-values.yaml --wait --timeout 30m
kubectl -n aperturedb get pods,svc,ingress,pvc

Keep this values file for later upgrades. To inspect all settings for the selected package:

helm show values oci://registry-1.docker.io/aperturedata/aperturedb-helm \
  --version <package-version>

Secrets and TLS​

For production, reference existing secrets in the deployment namespace instead of placing credentials in the values file. Set the corresponding reference below and omit its inline password or credentials value:

Existing Kubernetes secrets

Helm value

Required secret key

masterKey.existingSecret

password

storage.existingSecret

credentials (the credential JSON)

telemetry.auth.existingSecret

password

telemetry.grafana.existingSecret

password

tls.existingSecret

tls.crt and tls.key in a kubernetes.io/tls secret

For private workload images, set imagePullSecrets to a list such as [{name: my-registry-secret}]. That secret must exist in the same namespace.

TLS selection, in order of precedence, is an existing secret, inline tls.cert and tls.key, cert-manager via tls.certManager, and an automatically generated self-signed certificate. Supply a trusted certificate covering the hostnames used by both web and TCP clients. The self-signed fallback is for evaluation; clients must explicitly trust it or use an evaluation-only certificate verification override.

Connect and verify​

Find the external TCP endpoint and the HTTP ingress address:

kubectl -n aperturedb get service lenz-external
kubectl -n aperturedb get ingress

Point the DNS record for ingress.host at the ingress controller’s address. The TCP load balancer is a separate endpoint; give it its own DNS record matching the certificate when connecting remotely.

  • Web UI: https://aperturedb.example.com/.

  • REST API: https://aperturedb.example.com/api/.

  • Native clients: the lenz-external address, port 55555, with TLS enabled. In-cluster clients can use the lenz service on that port.

  • Grafana: https://aperturedb.example.com/grafana/, with the default Web UI and telemetry enabled. Log in as admin with telemetry.grafana.adminPassword or the password in its referenced secret.

Log in to ApertureDB as admin with the master key and run GetStatus. Prometheus uses the separate monitoring bearer password to discover and scrape database metrics through Lenz.

If pods remain pending, inspect kubectl -n aperturedb describe pod <pod-name> and the PVC status for capacity or storage-class problems. For image pull or startup failures, check pod events and kubectl -n aperturedb logs <pod-name> --all-containers --tail=100. An external address that stays pending usually requires checking your cluster’s LoadBalancer implementation. For HTTP routing problems, check DNS and the ingress class.

Customize, upgrade, and remove​

Common values include aperturedb.replicas, lenz.replicas, global.storageClass, and telemetry.persistence.storageClass. Telemetry is enabled by default; use telemetry.enabled: false to disable it. The monitoring volume is fixed at 100Gi. Adjust workload resource settings to your dataset and available capacity before installation.

Published packages pin all ApertureData image versions, including the database and Web UI. Select the chart version to use the matching images.

Back up your data and review the target release’s upgrade requirements, then reuse your values file:

helm upgrade aperturedb oci://registry-1.docker.io/aperturedata/aperturedb-helm \
  --version <package-version> --namespace aperturedb \
  -f my-values.yaml --wait --timeout 30m

To remove the deployment:

helm uninstall aperturedb --namespace aperturedb

Uninstall removes the active monitoring PVC and may delete its underlying metrics and log data according to the storage reclaim policy. ZooKeeper PVCs created by StatefulSet claim templates remain. The chart does not delete your object storage bucket. Preserve the bucket and retained claims until you have determined which data must be kept for recovery.