Skip to main content

Helm Chart Configuration Values

Every chart value lives under the global namespace so it can be shared across sub-charts. The most common parameters:

The chart does not create or select a Kubernetes namespace — choose one at install time with helm install --namespace <ns> --create-namespace.

ParameterDescriptionDefault
global.mainAddressIP or DNS name Envoy proxies and clients use to reach Elchi. See Choosing mainAddress.required
global.portPort clients use with mainAddress. Empty = derived from the gateway Service: the http NodePort (the https NodePort with tlsEnabled), or 80/443 behind an ingress or load balancer. Set it when a load balancer in front listens on another port. A release installed before chart 2.1.0 keeps the port it runs with."" (derived)
global.tlsEnabledEnable HTTPS for external traffic.false
global.installMongoUse the bundled MongoDB.true
global.installVictoriaMetricsUse the bundled VictoriaMetrics.true
global.installClickhouseUse the bundled ClickHouse (raw API-events store).true
global.installCollectorDeploy the bundled elchi-collector (API discovery).true
global.installGslbDeploy the GSLB DNS component.false
global.internalCommunicationController → control-plane calls stay inside the cluster (through envoy-service:8080) instead of going out to mainAddress:port and back.true
global.versionsList of Elchi backend versions to deploy (illustrative — see Versions & Upgrades for how the current set is resolved).[v1.8.4-v0.14.0-envoy1.40.2]
global.envoy.service.typeGateway Service type: NodePort, LoadBalancer or ClusterIP.NodePort
global.envoy.service.httpNodePortGateway NodePort (30000–32767). Empty = the first free one from 30000 up, kept on upgrades (needs cluster-wide Service read; set it for GitOps / helm template).null (auto)
global.envoy.service.exposeAdminAdd the Envoy admin interface (9901) to the gateway Service. It can stop the gateway, so it stays off; use kubectl port-forward deploy/envoy 9901 instead. Setting adminNodePort also exposes it.false
global.jwt.secretJWT signing secret. Leave empty and the chart generates one; an explicit value needs 32+ characters. See Credentials."" (generated)
global.jwt.accessTokenDurationAccess token lifetime."1h"
global.jwt.refreshTokenDurationRefresh token lifetime."5h"
global.elchiBackend.controlPlaneDefaultReplicasReplica count for control-plane services. Production: 3 or more.1
global.elchiBackend.controllerDefaultReplicasReplica count for controller services. Production: 3 or more.1
envoy.replicas / elchi.replicas / elchi-collector.replicaCountReplica counts of the gateway Envoy, the UI and the collector. Production: 2 or more.1
global.cors.allowedOriginsCORS allowed origins. Comma-separated, or * for all."*"

Choosing mainAddress​

global.mainAddress (with the port the chart derives, or global.port) is the front door that everything outside the cluster uses. It ends up in:

  • every Envoy bootstrap Elchi generates: the elchi-control-plane cluster the proxy dials for its configuration (ADS), and the gRPC authority it sends;
  • the access-log stream (elchi-als) those proxies send to the collector, which uses the same cluster;
  • the self-signed gateway certificate, which is issued for this name;
  • the address you give each elchi-client (--host / --port, see Client installation).

The browser UI does not depend on it: it calls the API on whatever address you opened it on.

Envoy proxies and clients run outside the cluster, so pick an address they can always reach:

ClusterUse as mainAddressPort
One node, a first try, or no load balancer (typical on-premises)The IP of any one nodederived (the http NodePort the chart picked, printed at install)
Several nodes, cloud or MetalLBA DNS name for the gateway's LoadBalancer IP (global.envoy.service.type=LoadBalancer)derived (8080, or 8443 with TLS)
Several nodes, own load balancer or VIP (HAProxy, F5, kube-vip, keepalived)A DNS name for the VIP, which forwards to the gateway NodePort on every nodethe port the VIP listens on: set global.port when it differs from the NodePort

A single node's IP always works, because the gateway NodePort answers on every node. Its only cost: when that node goes down, Envoy proxies keep serving traffic with the configuration they have but stop receiving changes, and clients lose their connection, until the node is back or you move mainAddress to another node. On a cluster of many nodes, a load balancer or VIP in front of all of them (by DNS name) removes that single point; add one when you can.

Prefer a DNS name over an IP. The address is written into every bootstrap, so moving to a new IP is then a DNS change, not a reconfiguration. With global.tlsEnabled: true, put a certificate for that name in global.envoy.tls.secretName.

The control plane speaks long-lived gRPC streams. Use a layer-4 (TCP) load balancer, or a layer-7 one with HTTP/2 to the backend and no stream or idle timeouts.

When mainAddress or the port changes, Elchi updates the default elchi-control-plane cluster when it restarts, unless someone edited that cluster by hand. Proxies that are already running keep their old bootstrap: download it again and redeploy them.

Credentials​

Since chart 2.0.0 every credential the platform needs lives in ONE Kubernetes Secret — elchi-stack-secrets by default — and the chart resolves each one in this order:

  1. the explicit value you set (global.jwt.secret, global.mongodb.password, …);
  2. the value already in the Secret from an earlier install or upgrade;
  3. a generated one, when global.secrets.autoGenerate is true (the default).

So a plain helm install needs no credentials at all, and a later helm upgrade never rotates what is already running. The Secret carries helm.sh/resource-policy: keep, so helm uninstall leaves it behind — reinstalling into the same namespace adopts the existing credentials instead of locking you out of your own MongoDB volume.

Secret keyValueGenerated length
ELCHI_JWT_SECRETglobal.jwt.secret — signs API tokens and derives the license KEK.48
MONGODB_PASSWORDglobal.mongodb.password32
CLICKHOUSE_PASSWORDglobal.clickhouse.password32
HASH_SALTglobal.collector.hashSalt — pseudonymizes client identifiers.48
GSLB_SECRETglobal.gslb.secret48
GRAFANA_PASSWORDglobal.grafana.password24
ParameterDescriptionDefault
global.secrets.nameName of the Secret holding every credential.elchi-stack-secrets
global.secrets.autoGenerateGenerate a missing credential at install time.true
global.secrets.adoptLegacyDefaultsOne-shot seed of the pre-2.0.0 built-in defaults on the first upgrade.false
Two cases that need your attention

GitOps / helm template. Generation reads the cluster through lookup, which returns nothing when the manifests are rendered outside it — every run would then invent new credentials. For Argo CD, Flux or any rendered pipeline, set global.secrets.autoGenerate: false and supply all six values explicitly (from your own secret store).

Upgrading a release installed before 2.0.0. Those chart versions had built-in default passwords and no shared Secret, so the chart cannot know what your datastores are using and refuses to guess. Set global.secrets.adoptLegacyDefaults: true for that one upgrade — it seeds the Secret with those former defaults so the running system keeps working — then rotate each credential.

Because they end up inside connection URIs, MONGODB_PASSWORD and CLICKHOUSE_PASSWORD must be URL-safe: an explicit value is accepted only if it matches [A-Za-z0-9._~-]+ (the unreserved URI characters). Anything else is rejected at render time rather than producing a DSN that silently fails to parse.

External MongoDB parameters​

When global.installMongo: false, point Elchi at your own MongoDB cluster:

ParameterDescription
global.mongodb.hostsConnection hosts (comma-separated for replica sets).
global.mongodb.usernameMongoDB username (default "elchi").
global.mongodb.passwordMongoDB password.
global.mongodb.databaseDatabase name (default "elchi").
global.mongodb.schemeConnection scheme — mongodb or mongodb+srv.
global.mongodb.replicasetReplica set name, if applicable.
global.mongodb.tlsEnabledEnable TLS connection to MongoDB.
global.mongodb.authSourceAuthentication source database.
global.mongodb.authMechanismAuthentication mechanism.

External VictoriaMetrics​

When global.installVictoriaMetrics: false, set:

ParameterDescription
global.victoriametrics.endpointExternal VictoriaMetrics endpoint. Accepts http://host:port or host:port.

External ClickHouse​

When global.installClickhouse: false, point the collector at your own ClickHouse cluster:

ParameterDescription
global.clickhouse.hostsConnection hosts for the raw API-events store.
global.clickhouse.passwordClickHouse password — set your own; do not commit it.
Subchart toggles feed the collector

global.installClickhouse and global.installCollector drive the API discovery pipeline: the collector writes raw events to ClickHouse and the endpoint inventory to MongoDB. Turn installGslb on only when you need the GSLB DNS component. Which datastores each shipped profile bundles vs. externalizes is summarized in Values Profiles.