From fe75756fbdcc391575ee2d4f5fe089addacc2197 Mon Sep 17 00:00:00 2001 From: "lia-by-librechat[bot]" <328778573+lia-by-librechat[bot]@users.noreply.github.com> Date: Mon, 21 Sep 2026 21:43:30 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=8F=A6=20fix:=20Require=20Named=20Helm=20?= =?UTF-8?q?Credential=20Secrets=20(#16175)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 🏦 fix: Require Named Helm Credential Secrets * docs: Clarify Helm Credential Injection and Meilisearch Secrets --------- Co-authored-by: Lia --- helm/librechat/Chart.yaml | 2 +- helm/librechat/readme.md | 33 ++++++++ helm/librechat/templates/deployment.yaml | 2 +- .../tests/credentials_render_test.sh | 82 +++++++++++++++++++ helm/librechat/values.yaml | 7 +- 5 files changed, 123 insertions(+), 3 deletions(-) create mode 100644 helm/librechat/tests/credentials_render_test.sh diff --git a/helm/librechat/Chart.yaml b/helm/librechat/Chart.yaml index a41a1ff193..33e033be43 100755 --- a/helm/librechat/Chart.yaml +++ b/helm/librechat/Chart.yaml @@ -15,7 +15,7 @@ type: application # This is the chart version. This version number should be incremented each time you make changes # to the chart and its templates, including the app version. # Versions are expected to follow Semantic Versioning (https://semver.org/) -version: 2.0.12 +version: 2.0.13 # This is the version number of the application being deployed. This version number should be # incremented each time you make changes to the application. Versions are not expected to diff --git a/helm/librechat/readme.md b/helm/librechat/readme.md index 583ad7e8a5..2780b9653f 100755 --- a/helm/librechat/readme.md +++ b/helm/librechat/readme.md @@ -8,6 +8,39 @@ In this Chart, LibreChat will only work with environment Variables. You can Spec 1. Generate Variables Generate unique values for `CREDS_KEY`, `JWT_SECRET`, `JWT_REFRESH_SECRET`, and `MEILI_MASTER_KEY` using `openssl rand -hex 32`, and `CREDS_IV` using `openssl rand -hex 16`. Store them in the existing Kubernetes Secret so every replica uses the same values. + +The Secret named by `global.librechat.existingSecretName` must exist before the +LibreChat container can start. A missing or misspelled Secret now blocks container +startup instead of silently falling back to temporary, pod-local credentials. +This does not validate the keys inside the Secret: ensure it contains all four +`CREDS_KEY`, `CREDS_IV`, `JWT_SECRET`, and `JWT_REFRESH_SECRET` values. + +If you supply all LibreChat credentials through alternate environment injection, +set `global.librechat.existingSecretName: ""` to omit the LibreChat container's +bulk Secret reference: + +- `librechat.configEnv` accepts string values only, serialized into ConfigMap + `data`. Do not put `valueFrom` or `secretKeyRef` objects there. +- `global.librechat.env` accepts Kubernetes environment entries, including + `valueFrom.secretKeyRef`. Use this mechanism for per-key Secret injection. + +Clearing the LibreChat reference does **not** clear the bundled Meilisearch +reference. With `meilisearch.enabled: true` (the default), also provision the +Secret named by `meilisearch.auth.existingMasterKeySecret`, which defaults to +`librechat-credentials-env`. It must contain `MEILI_MASTER_KEY`, and LibreChat's +`MEILI_MASTER_KEY` must match it. If you rename that Secret, update +`meilisearch.auth.existingMasterKeySecret` as well. Injecting a key into the +LibreChat container does not inject it into the Meilisearch container. + +For deployments with bundled Meilisearch disabled (`meilisearch.enabled: false`), +there is no bundled Meilisearch Secret dependency. Configure any external search +service and its matching credentials separately. + +Prefer Kubernetes Secrets over literal config values for production. Keep the +same existing encryption keys across upgrades and replicas; do not regenerate +them to resolve a missing Secret. No credential PVC is needed when permanent +credentials are injected through the environment. + place them in a secret like this (If you want to change the secret name, remember to change it in your helm values): ```yaml apiVersion: v1 diff --git a/helm/librechat/templates/deployment.yaml b/helm/librechat/templates/deployment.yaml index 279749185b..aa38d7f5ee 100755 --- a/helm/librechat/templates/deployment.yaml +++ b/helm/librechat/templates/deployment.yaml @@ -101,7 +101,7 @@ spec: {{- if .Values.global.librechat.existingSecretName }} - secretRef: name: {{ .Values.global.librechat.existingSecretName }} - optional: true + optional: false {{- end }} {{- with .Values.global.librechat.env }} env: diff --git a/helm/librechat/tests/credentials_render_test.sh b/helm/librechat/tests/credentials_render_test.sh new file mode 100644 index 0000000000..bccb176d55 --- /dev/null +++ b/helm/librechat/tests/credentials_render_test.sh @@ -0,0 +1,82 @@ +#!/usr/bin/env bash +# Missing named credential Secrets must block startup, not generate per-pod keys. +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +CHART_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)" +REPO_ROOT="$(cd "${CHART_DIR}/../.." && pwd)" +TEST_DIR="$(mktemp -d -t librechat-credentials-chart.XXXXXX)" +trap 'rm -rf "${TEST_DIR}"' EXIT + +command -v helm >/dev/null || { echo 'FAIL: helm not on PATH' >&2; exit 1; } +mkdir -p "${TEST_DIR}/chart/templates" +awk '/^dependencies:/{ exit } { print }' "${CHART_DIR}/Chart.yaml" > "${TEST_DIR}/chart/Chart.yaml" +cp "${CHART_DIR}/values.yaml" "${TEST_DIR}/chart/values.yaml" +for template in _helpers.tpl deployment.yaml configmap.yaml configmap-env.yaml; do + cp "${CHART_DIR}/templates/${template}" "${TEST_DIR}/chart/templates/${template}" +done + +render() { + helm template librechat "${TEST_DIR}/chart" \ + --set mongodb.enabled=false --set meilisearch.enabled=false \ + --set redis.enabled=false --set librechat-rag-api.enabled=false \ + --set-string librechat.configEnv.MONGO_URI=mongodb://database:27017/LibreChat "$@" +} +render > "${TEST_DIR}/default.yaml" +render --set replicaCount=2 --set global.librechat.existingSecretName=shared-credentials > "${TEST_DIR}/replicas.yaml" +# This alternate fixture intentionally excludes bundled Meilisearch's separate Secret. +cat > "${TEST_DIR}/alternate-values.yaml" <<'YAML' +meilisearch: + enabled: false +global: + librechat: + existingSecretName: "" + env: + - name: JWT_SECRET + valueFrom: + secretKeyRef: + name: separately-managed + key: jwt +librechat: + configEnv: + JWT_REFRESH_SECRET: fixture-refresh + CREDS_KEY: fixture-key + CREDS_IV: fixture-iv +YAML +render -f "${TEST_DIR}/alternate-values.yaml" > "${TEST_DIR}/alternate.yaml" + +NODE_PATH="${REPO_ROOT}/node_modules${NODE_PATH:+:${NODE_PATH}}" TEST_DIR="${TEST_DIR}" node <<'NODE' +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const path = require('node:path'); +const yaml = require('js-yaml'); +const docs = (name) => yaml.loadAll(fs.readFileSync(path.join(process.env.TEST_DIR, name), 'utf8')).filter(Boolean); +const deployment = (items) => items.find((doc) => doc.kind === 'Deployment'); +const container = (items) => deployment(items).spec.template.spec.containers[0]; +const defaults = docs('default.yaml'); +assert.deepEqual(container(defaults).envFrom.find((entry) => entry.secretRef), { + secretRef: { name: 'librechat-credentials-env', optional: false }, +}); +const replicas = docs('replicas.yaml'); +assert.equal(deployment(replicas).spec.replicas, 2); +assert.deepEqual(container(replicas).envFrom.find((entry) => entry.secretRef), { + secretRef: { name: 'shared-credentials', optional: false }, +}); +const alternateValues = yaml.load(fs.readFileSync(path.join(process.env.TEST_DIR, 'alternate-values.yaml'), 'utf8')); +assert.equal(alternateValues.meilisearch.enabled, false); +const chartValues = yaml.load(fs.readFileSync(path.join(process.env.TEST_DIR, 'chart/values.yaml'), 'utf8')); +assert.equal(chartValues.meilisearch.enabled, true); +assert.equal(chartValues.meilisearch.auth.existingMasterKeySecret, 'librechat-credentials-env'); +const alternate = docs('alternate.yaml'); +assert.equal(container(alternate).envFrom.some((entry) => entry.secretRef), false); +assert.deepEqual(container(alternate).env, [{ + name: 'JWT_SECRET', valueFrom: { secretKeyRef: { name: 'separately-managed', key: 'jwt' } }, +}]); +const config = alternate.find((doc) => doc.kind === 'ConfigMap' && doc.metadata.name.endsWith('-configenv')); +assert.ok(Object.values(config.data).every((value) => typeof value === 'string')); +assert.equal(Object.hasOwn(config.data, 'JWT_SECRET'), false); +assert.equal(config.data.JWT_REFRESH_SECRET, 'fixture-refresh'); +assert.equal(config.data.CREDS_KEY, 'fixture-key'); +assert.equal(config.data.CREDS_IV, 'fixture-iv'); +console.log('PASS: required default/custom Secrets, shared replica credentials, and alternate environment injection with bundled Meilisearch disabled'); +NODE diff --git a/helm/librechat/values.yaml b/helm/librechat/values.yaml index c72936e1da..a3a7e958a3 100755 --- a/helm/librechat/values.yaml +++ b/helm/librechat/values.yaml @@ -16,6 +16,10 @@ global: # - JWT_REFRESH_SECRET # - MEILI_MASTER_KEY librechat: + # A named Secret is required to exist; a typo must not generate pod-local credentials. + # Set to "" only when all LibreChat credentials are supplied through configEnv (strings) + # or global.librechat.env (supports valueFrom.secretKeyRef). + # Bundled Meilisearch still requires its separate auth.existingMasterKeySecret. existingSecretName: "librechat-credentials-env" # Used for Setting the Right Key, can be something like AZURE_API_KEY, if Azure OpenAI is used existingSecretApiKey: OPENAI_API_KEY @@ -385,7 +389,8 @@ meilisearch: image: tag: "v1.7.3" auth: - # Use an existing Kubernetes secret for the MEILI_MASTER_KEY + # Separate from global.librechat.existingSecretName, even when that reference is cleared. + # Must contain MEILI_MASTER_KEY matching the value supplied to LibreChat. existingMasterKeySecret: "librechat-credentials-env" # Redis Parameters