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 :doc:`../Deployment`. * 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: .. code-block:: yaml masterKey: password: "" storage: type: s3 bucket: "" credentials: '{"access_key":"","secret_access_key":"","region":"us-west-2"}' service: type: LoadBalancer http: host: aperturedb.example.com tls: true telemetry: enabled: true authPassword: "" adminPassword: "" 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: .. code-block:: bash chmod 600 my-values.yaml helm install aperturedb oci://registry-1.docker.io/aperturedata/aperturedb-helm \ --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: .. code-block:: bash helm show values oci://registry-1.docker.io/aperturedata/aperturedb-helm \ --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: .. list-table:: Existing Kubernetes secrets :header-rows: 1 * - Helm value - Required secret key * - ``masterKey.existingSecret`` - ``password`` * - ``storage.existingSecret`` - ``credentials`` (the credential JSON) * - ``telemetry.authPasswordSecret`` - ``password`` * - ``telemetry.adminPasswordSecret`` - ``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: .. code-block:: bash 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`` using the Grafana password configured for the deployment. Use ``admin`` with the master key in the runnable client check at :ref:`deployment-verify`. Prometheus uses the separate monitoring bearer password to discover and scrape database metrics through Lenz. See :ref:`configuration-deployment-mapping` for server and gateway settings. If pods remain pending, inspect ``kubectl -n aperturedb describe pod `` and the PVC status for capacity or storage-class problems. For image pull or startup failures, check pod events and ``kubectl -n aperturedb logs --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. Endpoints by service type ------------------------- Choose the native and HTTP endpoint independently: ``service.type`` controls ``lenz-external``, while ``http.service.type`` controls ``http-proxy``. LoadBalancer endpoints ~~~~~~~~~~~~~~~~~~~~~~ Read each Service's external ingress entries: .. code-block:: bash kubectl -n aperturedb get service lenz-external -o jsonpath='{.status.loadBalancer.ingress}' kubectl -n aperturedb get service http-proxy -o jsonpath='{.status.loadBalancer.ingress}' Use the returned IP address or hostname with the Service port. An empty list can mean provisioning is still in progress; non-LoadBalancer Services have no load-balancer ingress entries. NodePort endpoints ~~~~~~~~~~~~~~~~~~ Read the native node port and HTTP/HTTPS node ports: .. code-block:: bash kubectl -n aperturedb get service lenz-external -o jsonpath='{.spec.ports[?(@.name=="tcp")].nodePort}' kubectl -n aperturedb get service http-proxy -o jsonpath='{range .spec.ports[*]}{.name}{"="}{.nodePort}{"\n"}{end}' Use a reachable cluster node address with those ports, including automatically allocated ports. Point ``http.host`` at the node or your external load balancer. The certificate must cover the hostname clients use. ClusterIP endpoints ~~~~~~~~~~~~~~~~~~~ In-cluster native clients can connect to ``lenz.aperturedb.svc.cluster.local`` on ``service.port`` (default ``55555``). The HTTP Service is ``http-proxy.aperturedb.svc.cluster.local``, with Service ports ``80`` and, when TLS is enabled, ``443``. Replace ``aperturedb`` with your release namespace and ``cluster.local`` with your cluster domain if different. These are Service ports, not node ports. Configure ``http.host`` and its DNS for the internal HTTP address, and use a certificate covering the hostname each client uses. ClusterIP addresses are reachable within the cluster. NodePort access ---------------- For direct access through cluster nodes, configure distinct, available HTTP and HTTPS NodePorts and allow them through your firewall: .. code-block:: yaml 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: .. code-block:: yaml 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. Database scratch volume ----------------------- Set one ``dbEphemeralVolume`` object for both database and checkpointer pods: .. code-block:: yaml dbEphemeralVolume: size: 100Gi storageClass: premium-rwo The default ``null`` uses the container filesystem. When enabled, every pod gets a separate ReadWriteOnce claim with the capacity specified by ``size``. Database pods mount the claim at ``/aperturedb/db`` and checkpointer pods at ``/checkpointer/db``. Omit ``storageClass``, or leave it empty, to use ``global.storageClass``, then the cluster default. The class must support dynamic provisioning. Deleting a pod, including scaling it to zero with ``inactive``, deletes its claim; the underlying volume follows the class's reclaim policy. Distributed database content remains in the object storage bucket. See `generic ephemeral volumes `_. 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. In a key such as ``.affinity``, replace ```` with a name from the table in `Workloads and storage`_, for example ``zookeeper.affinity``. The ``http`` workload is the HTTP proxy. Scheduling and pod annotations under ``webui`` apply to the shared Web UI and telemetry pod. Network ~~~~~~~ .. list-table:: Network settings :header-rows: 1 :widths: 35 20 45 * - 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`` - ``{}``, ``""``, ``[]`` - Load balancer annotations, class, and allowed client CIDRs for ``lenz-external``. * - ``http.host`` - ``""`` - 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`` - ``{}``, ``""``, ``[]`` - 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. list-table:: Credential, TLS, and image settings :header-rows: 1 :widths: 35 20 45 * - Value - Default - Purpose * - ``masterKey.password``, ``masterKey.existingSecret`` - ``""``, ``""`` - Supply one of these for the database ``admin`` password. * - ``storage.type`` - ``s3`` - Use ``s3`` or ``gs`` for the distributed deployment's object storage. * - ``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 database and checkpointer 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``, ``https://index.docker.io/v1/``, ``""``, ``""`` - 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 ~~~~~~~~~~~~~~~~~~~~ The package sets a 4096 MiB native message limit and an 8192 MiB shared retained-byte budget (``ADB_QUERY_QUEUE_BYTES_MB``). Concurrent requests and responses share that budget. Use the database extra-environment settings to adjust both limits together; see :doc:`../ConfigFile` for required headroom. .. list-table:: Capacity and logging settings :header-rows: 1 :widths: 35 20 45 * - Value - Default - Purpose * - ``aperturedb.maxConcurrency`` - ``512`` - Query workers per database process (``ADB_QUERY_THREADS``) and the fallback gateway concurrency; independent of accepted connections. * - ``lenz.adbMaxConcurrency`` - ``null`` - Independent gateway concurrency override. Omitted or ``null`` follows ``aperturedb.maxConcurrency``. An override must be a positive integer. * - ``aperturedb.taskExecutorThreads`` - ``100`` - Database executor threads. * - ``aperturedb.storageMaxGi`` - ``4096`` - Graph-store storage limit in GiB. The chart requires a positive integer. * - ``aperturedb.storageOperationsLimit`` - ``100`` - Concurrent object storage operations per database process. * - ``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. * - ``lenz.timeoutFactor`` - ``4`` - Scales the gateway's network timeouts; raise it for slow clients or very large requests. * - ``.extraEnv`` - ``{}`` - Additional environment variables for ``aperturedb``, ``checkpointer``, or ``lenz``, 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`` - Minimum timeout ZooKeeper can negotiate with a client, in milliseconds. * - ``zookeeper.publishNotReadyAddresses`` - ``true`` - Publish each ZooKeeper pod's DNS record before readiness so peers can discover each other during startup. Set to ``false`` to publish only ready pods. * - ``zookeeper.maxTimeToWaitForEpoch`` - ``30000`` - Milliseconds a leader waits for a quorum to agree on an epoch before a voter returning to election can trigger a new election. Use ``0`` to allow a retry as soon as a voter returns to election, or ``-1`` to disable early retries. For example, configure the gateway independently of the database query threads: .. code-block:: yaml aperturedb: maxConcurrency: 256 lenz: adbMaxConcurrency: 128 This sets ``LNZ_ADB_MAX_CONCURRENCY`` to 128 while the database's ``ADB_QUERY_THREADS`` remains 256. Leaving ``lenz.adbMaxConcurrency`` unset or ``null`` preserves the existing fallback; both values retain their defaults when neither setting is changed. The chart sets the other database settings listed for Compose, including ``ADB_LOG_LEVEL=0`` and ``ADB_KVGD_DB_SYNC=false``. See :doc:`../ConfigFile` for database configuration details. Workloads and storage ~~~~~~~~~~~~~~~~~~~~~ .. list-table:: Default replica counts and main container resources :header-rows: 1 :widths: 22 12 32 34 * - Workload - ``replicas`` - ``resources.requests`` - ``resources.limits`` * - ``aperturedb`` - 3 - ``{cpu: "10m", memory: "8Gi"}`` - ``{cpu: "64", memory: "128Gi"}`` * - ``checkpointer`` - 1 - ``{cpu: "10m", memory: "8Gi"}`` - ``{cpu: "64", memory: "128Gi"}`` * - ``http`` - 2 - ``{cpu: "10m", memory: "64Mi"}`` - ``{cpu: "1", memory: "512Mi"}`` * - ``lenz`` - 2 - ``{cpu: "10m", memory: "1Gi"}`` - ``{cpu: "64", memory: "32Gi"}`` * - ``tools`` - 0 - ``{cpu: "25m", memory: "64Mi"}`` - ``{cpu: "1", memory: "256Mi"}`` * - ``webui`` - 1 - ``{cpu: "25m", memory: "32Mi"}`` - ``{cpu: "250m", memory: "128Mi"}`` * - ``zookeeper`` - 3 - ``{cpu: "250m", memory: "1Gi"}`` - ``{cpu: "1", memory: "2Gi"}`` When telemetry is enabled, each ApertureDB pod runs one Promtail sidecar. Grafana, Loki, and Prometheus run in the shared web pod. Each container has independent CPU and memory settings. .. list-table:: Telemetry container defaults :header-rows: 1 :widths: 42 29 29 * - Helm value - Requests (CPU, memory) - Limits (CPU, memory) * - ``telemetry.promtail.resources`` - ``25m``, ``64Mi`` - ``500m``, ``256Mi`` * - ``telemetry.grafana.resources`` - ``100m``, ``256Mi`` - ``1``, ``1Gi`` * - ``telemetry.loki.resources`` - ``100m``, ``256Mi`` - ``2``, ``2Gi`` * - ``telemetry.prometheus.resources`` - ``100m``, ``256Mi`` - ``2``, ``2Gi`` Web UI resources apply to the ``webui`` container in the shared web pod. Use an odd replica count for ZooKeeper. Web UI and Tools each accept 0 or 1. Setting ``webui.replicas`` to 0 disables the Web UI and its HTTP route. Telemetry can still run in the shared web pod. With ``tools.replicas`` at 0, the Tools Deployment stays scaled down. Set it to 1 to run an admin pod with the deployment's ZooKeeper server list and prefix. These Helm values override CPU and memory for each ZooKeeper server and allow its pods to run on nodes tainted ``dedicated=isvi-cpu:NoSchedule``. You can set ``resources`` and ``tolerations`` independently. .. code-block:: yaml zookeeper: resources: requests: cpu: "250m" memory: "512Mi" limits: cpu: "1" memory: "2Gi" tolerations: - key: dedicated operator: Equal value: isvi-cpu effect: NoSchedule .. list-table:: Workload and storage settings :header-rows: 1 :widths: 35 20 45 * - Value - Default - Purpose * - ``inactive`` - ``false`` - Scale all workloads to zero. Managed persistent claims remain; pod-owned generic ephemeral claims are deleted with their pods. * - ``global.storageClass`` - ``""`` - Storage class for the shared 100Gi monitoring claim and fallback for ZooKeeper and database scratch claims. An empty string uses the cluster default. * - ``dbEphemeralVolume`` - ``null`` - Per-pod database/checkpointer claim with required ``size`` and optional ``storageClass``; see `Database scratch volume`_ for its lifecycle. * - ``zookeeper.persistence.size``, ``zookeeper.persistence.storageClass`` - ``1Gi``, ``""`` - Requested capacity and storage class for each ZooKeeper pod's persistent claim. * - ``zookeeper.prefix`` - ``db_root`` - ZooKeeper path for this deployment's coordination data. * - ``.podAnnotations`` - ``{}`` - Map of string annotation keys to string values on the pod template. * - ``.affinity`` - ``{}`` - Kubernetes affinity object. Combine ``nodeAffinity``, ``podAffinity``, and ``podAntiAffinity`` as needed. * - ``.tolerations`` - ``[]`` - List of toleration objects. The fields ``key``, ``operator``, ``value``, and ``effect`` take strings. Use an integer ``tolerationSeconds`` for a timed ``NoExecute`` toleration. * - ``.nodeSelector`` - ``{}`` - Map of node label keys to the string values required by the workload's pods. Monitoring ~~~~~~~~~~ .. list-table:: Monitoring settings :header-rows: 1 :widths: 35 20 45 * - Value - Default - Purpose * - ``telemetry.enabled`` - ``true`` - Deploy Prometheus, Grafana, Loki, and Promtail log collection. * - ``telemetry.retentionDays`` - ``28`` - Metrics and log retention in days. * - ``telemetry.authPassword``, ``telemetry.authPasswordSecret`` - ``""``, ``""`` - Supply one when telemetry is enabled. The monitoring password authenticates metrics collection. * - ``telemetry.adminPassword``, ``telemetry.adminPasswordSecret`` - ``""``, ``""`` - Grafana admin password or the name of an existing Kubernetes Secret with key ``password``. When both are supplied, Helm uses the existing Secret. 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 -------------------- When upgrading older values files, replace ``webui.enabled`` with ``webui.replicas`` (``0`` for false, ``1`` for true). Remove ``tools.enabled`` and set ``tools.replicas`` to the desired number of running pods, either ``0`` or ``1``. In older values files, move ``telemetry.grafana.adminPassword`` to ``telemetry.adminPassword`` and ``telemetry.auth.password`` to ``telemetry.authPassword``. For existing Secrets, move ``telemetry.grafana.existingSecret`` to ``telemetry.adminPasswordSecret`` and ``telemetry.auth.existingSecret`` to ``telemetry.authPasswordSecret``. Each reference takes precedence over its inline password. Move a monitoring storage class configured with ``telemetry.persistence.storageClass`` to ``global.storageClass``. For an existing ``monitoring`` claim, keep its storage class when upgrading. Review the compatibility notes in :doc:`../ReleaseNotes` for your target version, then complete :ref:`deployment-upgrades`. The following command applies the chart with your values file: .. code-block:: bash helm upgrade aperturedb oci://registry-1.docker.io/aperturedata/aperturedb-helm \ --version --namespace aperturedb \ -f my-values.yaml --wait --timeout 30m To remove the deployment: .. code-block:: bash 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.