🏦 fix: Require Named Helm Credential Secrets (#16175)

* 🏦 fix: Require Named Helm Credential Secrets

* docs: Clarify Helm Credential Injection and Meilisearch Secrets

---------

Co-authored-by: Lia <lia@librechat.ai>
This commit is contained in:
lia-by-librechat[bot] 2026-09-21 21:43:30 -04:00 • committed by GitHub
parent 1746a4ee9a
commit fe75756fbd
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 123 additions and 3 deletions

View file

@ -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

View file

@ -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

View file

@ -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:

View file

@ -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

View file

@ -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