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 database gateways, two HTTP proxies, 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.

  • LoadBalancer support for separate database TCP and HTTP/HTTPS services, or a plan to expose NodePort or ClusterIP services 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

http:
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. The HTTP service is included; no ingress controller is required.

Select a published package tag 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,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 database and HTTP/HTTPS endpoints:

kubectl -n aperturedb get service lenz-external http-proxy

Point the DNS record for http.host at the http-proxy address. Native clients use the separate lenz-external address. The TLS certificate must cover all hostnames used by web and native clients.

  • 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 telemetry enabled. Log in as admin with telemetry.grafana.adminPassword or the password in its referenced secret.

Use admin with the master key in the runnable client check at Connect and verify the deployment. Prometheus uses the separate monitoring bearer password to discover and scrape database metrics through Lenz. See Deployment settings and process boundaries for server and gateway settings.

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, http.host, and the HTTP service logs.

NodePort access​

For direct access through cluster nodes, configure distinct, available HTTP and HTTPS NodePorts and allow them through your firewall:

http:
host: aperturedb.example.com
service:
type: NodePort
httpNodePort: 30080
httpsNodePort: 30443

Point http.host at a reachable node. With these example ports, the Web UI is at https://aperturedb.example.com:30443/; append api/ or grafana/ for the API or dashboards. HTTP on port 30080 redirects to that HTTPS address. Choose ports from your cluster’s configured NodePort range, normally 30000–32767. To expose native clients through NodePort as well, set service.type to NodePort and inspect lenz-external for its allocated port.

Behind an external load balancer serving ports 80/443, use NodePort and set http.publicPort to 443. Leave the HTTP and HTTPS NodePorts at zero for automatic allocation. Redirects and Grafana URLs use public port 443. Both database and HTTP Services are always created; use ClusterIP for private access.

Workflow routes and request limits​

Use http.routes to expose workflow HTTP services under the deployment’s web hostname. Each route specifies a path prefix, an in-cluster service name, and its HTTP port. For example:

http:
host: aperturedb.example.com
routes:
- path: /notebooks
host: workflow-notebooks-ingresses
port: 8888

Paths must be unique and omit the trailing slash; /api and /grafana are reserved. Requests retain their path prefix and query string. WebSockets and streamed responses are supported, and route updates take effect automatically.

http.bodyLimit limits each request body to 256 MiB by default. Oversized requests receive 413. http.timeoutSeconds controls upstream inactivity and defaults to 300 seconds; workflow routes and Grafana allow one hour between response reads. Active requests have up to five minutes to finish during shutdown. Long-lived sessions should reconnect after an update.

Valid replacements in the configured TLS Secret are loaded automatically. Existing connections can finish with the previous certificate; invalid replacements leave the last valid certificate active.

Settings reference​

Add only the values you want to change to my-values.yaml. Helm merges nested values with the chart defaults, so zookeeper: {minSessionTimeout: 30000} keeps the other ZooKeeper settings. helm show values prints the defaults for a package.

Network​

Network settings

Value

Default

Purpose

service.type

LoadBalancer

Type of the lenz-external native database Service: LoadBalancer, NodePort, or ClusterIP.

service.port

55555

Published native database port.

service.nodePort

""

Fixed node port when service.type is NodePort; empty assigns one automatically.

service.annotations, service.loadBalancerClass, service.loadBalancerSourceRanges

Empty

Load balancer annotations, class, and allowed client CIDRs for lenz-external.

http.host

None; required

Web hostname used for redirects, Grafana URLs, and generated certificates.

http.extraHosts

[]

Additional web hostnames, also included in generated and cert-manager certificates.

http.tls

true

Serve HTTPS and redirect HTTP to it; false serves HTTP only.

http.publicPort

0

Public web port behind an external load balancer; 0 derives it from the Service.

http.bodyLimit

268435456

Maximum HTTP request body size in bytes.

http.timeoutSeconds

300

Upstream inactivity timeout for API and Web UI requests.

http.routes

[]

Workflow routes; see Workflow routes and request limits.

http.service.type

LoadBalancer

Type of the http-proxy Service.

http.service.httpNodePort, http.service.httpsNodePort

0, 0

Fixed HTTP and HTTPS node ports; see NodePort access.

http.service.annotations, http.service.loadBalancerClass, http.service.loadBalancerSourceRanges

Empty

Load balancer annotations, class, and allowed client CIDRs for http-proxy.

Native client connections always require TLS; the chart has no equivalent of the Compose LNZ_FORCE_SSL setting.

Credentials, TLS, and images​

Credential, TLS, and image settings

Value

Default

Purpose

masterKey.password, masterKey.existingSecret

None; one required

Database admin password, inline or from an existing Secret.

storage.type

s3

Object storage provider: s3 or gs.

storage.bucket

""

Object storage bucket for database content.

storage.credentials, storage.existingSecret

"", ""

Storage credential JSON, inline or from an existing Secret.

storage.extraEnv

{}

Additional non-secret storage variables for the database, checkpointer, and tools pods.

tls.existingSecret

""

Existing kubernetes.io/tls Secret for web and native TLS.

tls.cert, tls.key

"", ""

Inline PEM certificate chain and private key.

tls.certManager.enabled, tls.certManager.issuerRef.name, tls.certManager.issuerRef.kind

false, "", ClusterIssuer

Issue the certificate with cert-manager.

imagePullSecrets

[]

Existing registry Secrets for private images.

registryCredentials.enabled, registryCredentials.registry, registryCredentials.username, registryCredentials.password

false, Docker Hub, "", ""

Create the aperturedb-registry pull Secret from inline credentials.

image.pullPolicy

IfNotPresent

Pull policy for ApertureData images.

See Secrets and TLS for Secret keys and certificate precedence. The chart version selects matching versions of all ApertureData service images.

Capacity and logging​

Capacity and logging settings

Value

Default

Purpose

aperturedb.maxConcurrency

512

Database concurrency per gateway process. Each database accepts this many clients plus 8 for internal clients.

aperturedb.taskExecutorThreads

100

Database executor threads.

aperturedb.storageMaxGi

4096

Graph-store storage limit in GiB; 0 means unlimited.

aperturedb.storageOperationsLimit

100

Concurrent object storage operations per database.

aperturedb.descriptorsetFlusherInterval

1800

Seconds between descriptor set cleanup operations.

aperturedb.sessionTokenMaxAgeSec

36000

Session token lifetime in seconds.

aperturedb.refreshTokenMaxAgeSec

360000

Refresh token lifetime in seconds.

aperturedb.healthCheck

true

Enable the database health port and use it for readiness checks.

aperturedb.debuggable

false

Database debug mode.

lenz.timeoutFactor

4

Scales the gateway’s network timeouts; raise it for slow clients or very large requests.

aperturedb.resources

Requests 10m CPU, 8Gi; limits 64 CPU, 128Gi

Resources per database pod.

checkpointer.resources

Requests 10m CPU, 8Gi; limits 64 CPU, 128Gi

Resources for the checkpointer pod.

lenz.resources

Requests 10m CPU, 1Gi; limits 64 CPU, 32Gi

Resources per gateway pod.

http.resources

Requests 10m CPU, 64Mi; memory limit 512Mi

Resources per HTTP proxy pod.

aperturedb.extraEnv, checkpointer.extraEnv, lenz.extraEnv

{}

Additional environment variables for that container, such as ADB_HTTPS_* settings.

lenz.workflowsSecret

""

Existing Secret mounted into each gateway at /etc/lenz/workflows.

zookeeper.tickTime

8000

ZooKeeper tick, in milliseconds, from 1 to 10000.

zookeeper.minSessionTimeout

20000

Lowest ZooKeeper session timeout, in milliseconds. A database that loses ZooKeeper for longer loses its session.

The chart sets the other database settings listed for Compose, including ADB_LOG_LEVEL=0 and ADB_KVGD_DB_SYNC=false. See Configuration File for database configuration details.

Workloads and storage​

Workload and storage settings

Value

Default

Purpose

aperturedb.replicas

3

Database pods.

lenz.replicas

2

Gateway pods.

http.replicas

2

HTTP proxy pods.

checkpointer.replicas

1

Checkpointer pods.

zookeeper.replicas

3

ZooKeeper pods. Use an odd number.

inactive

false

Scale all workloads to zero while keeping their resources and volumes.

global.storageClass

""

Default storage class for all volumes; empty uses the cluster default.

zookeeper.persistence.size, zookeeper.persistence.storageClass

1Gi, ""

Volume size and storage class per ZooKeeper pod.

zookeeper.prefix

db_root

ZooKeeper path for this deployment’s coordination data.

aperturedb.nodeSelector, checkpointer.nodeSelector, lenz.nodeSelector, http.nodeSelector, zookeeper.nodeSelector, webui.nodeSelector

{}

Node labels that each component’s pods require.

webui.enabled

true

Deploy the Web UI.

tools.enabled, tools.replicas

true, 0

Administration pod; scale it up when needed.

Monitoring​

Monitoring settings

Value

Default

Purpose

telemetry.enabled

true

Deploy Prometheus, Grafana, Loki, and Promtail log collection.

telemetry.retentionDays

28

Metrics and log retention in days.

telemetry.auth.password, telemetry.auth.existingSecret

None; one required with telemetry

Monitoring password used to collect metrics, separate from the master key.

telemetry.grafana.adminPassword, telemetry.grafana.existingSecret

None; one required with telemetry

Grafana admin password.

telemetry.persistence.storageClass

""

Storage class for the shared 100Gi monitoring volume.

Grafana, Loki, and Prometheus share the web Pod, alongside the Web UI when it is enabled. Promtail runs in each database Pod and forwards its logs to Loki.

Upgrade and remove​

Review the compatibility notes in Release Notes for your target version, then complete Changing a deployment. The following command applies the chart with 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.