env.yaml

Overview

env.yaml is a Kubernetes Secret manifest template designed for use within a Helm chart deployment. Its primary purpose is to centralize and securely manage environment variables for the Ragflow application pods. This file dynamically generates secret data based on Helm values, ensuring that each pod receives the necessary configuration and sensitive credentials, such as passwords and host connection details, without exposing them in plain text.

The template selectively includes environment variables, validates required secrets, and configures service connection endpoints using Kubernetes internal DNS conventions. It also enforces configuration correctness by failing the Helm release if mandatory environment variables are missing or misconfigured.

Detailed Explanation

File Type

• Type: Kubernetes Secret manifest (Helm template)

• Kubernetes Kind: Secret (Opaque type)

• Purpose: Store sensitive environment variables (passwords, hosts) for Ragflow pods securely

Key Sections and Logic

Metadata

metadata:
  name: {{ include "ragflow.fullname" . }}-env-config

• The secret's name is dynamically generated using the Helm helper ragflow.fullname combined with the suffix -env-config.

• This naming convention ensures uniqueness and consistency across the Ragflow deployment.

Secret Type

type: Opaque

• The secret uses the Opaque type, which is the generic secret type for arbitrary user-defined data.

stringData Field

This field holds key-value pairs representing environment variables as strings. Kubernetes converts these automatically into base64-encoded data.

stringData:
  {{- range $key, $val := .Values.env }}
  {{- if $val }}
  {{ $key }}: {{ quote $val }}
  {{- end }}
  {{- end }}

• Iterates over .Values.env map from Helm values, including each non-empty key-value pair.

• Values are quoted to ensure proper YAML syntax.

Cluster Service Hostnames

REDIS_HOST: {{ printf "%s-redis.%s.svc" (include "ragflow.fullname" .) .Release.Namespace }}
MYSQL_HOST: {{ printf "%s-mysql.%s.svc" (include "ragflow.fullname" .) .Release.Namespace }}
MINIO_HOST: {{ printf "%s-minio.%s.svc" (include "ragflow.fullname" .) .Release.Namespace }}

• Defines service hostnames using internal Kubernetes DNS format: <release-name>-<service>.<namespace>.svc.

• This approach allows pods to connect to dependent services reliably within the cluster.

Required Password Validation

REDIS_PASSWORD: {{ .Values.env.REDIS_PASSWORD | required "REDIS_PASSWORD is required" }}

• Uses Helm's required function to enforce the presence of critical passwords.

• If missing, Helm installation/upgrade will fail with the provided error message.

Special Handling for MySQL Passwords

{{- with .Values.env.MYSQL_PASSWORD | required "MYSQL_PASSWORD is required" }}
MYSQL_PASSWORD: {{ . }}
MYSQL_ROOT_PASSWORD: {{ . }}
{{- end }}

• Both MYSQL_PASSWORD and MYSQL_ROOT_PASSWORD are set to the same value because:

  • MySQL expects MYSQL_ROOT_PASSWORD.

  • Ragflow container expects MYSQL_PASSWORD.

• Ensures consistency and avoids misconfiguration.

Special Handling for MinIO Passwords

{{- with .Values.env.MINIO_PASSWORD | required "MINIO_PASSWORD is required" }}
MINIO_PASSWORD: {{ . }}
MINIO_ROOT_PASSWORD: {{ . }}
{{- end }}

• Similar approach as MySQL to set MinIO credentials.

Doc Engine Specific Environment Variables

{{- if eq .Values.env.DOC_ENGINE "elasticsearch" }}
ES_HOST: {{ ... }}
ELASTIC_PASSWORD: {{ required "ELASTIC_PASSWORD is required" }}
{{- else if eq .Values.env.DOC_ENGINE "infinity" }}
INFINITY_HOST: {{ ... }}
{{- else if eq .Values.env.DOC_ENGINE "opensearch" }}
OS_HOST: {{ ... }}
OS_PORT: "9201"
OPENSEARCH_PASSWORD: {{ required "OPENSEARCH_PASSWORD is required" }}
OPENSEARCH_INITIAL_ADMIN_PASSWORD: {{ required "OPENSEARCH_PASSWORD is required" }}
{{- else }}
{{ fail "env.DOC_ENGINE must be either 'elasticsearch', 'opensearch' or 'infinity'" }}
{{- end }}

• Conditionally includes environment variables depending on the configured document engine.

• Ensures only relevant secrets are included per engine.

• Validates presence of engine-specific passwords.

• Fails Helm deployment if DOC_ENGINE is misconfigured.

Usage Example

Assuming you have a Helm values file values.yaml like:

env:
  REDIS_PASSWORD: "redis-secret"
  MYSQL_PASSWORD: "mysql-secret"
  MINIO_PASSWORD: "minio-secret"
  DOC_ENGINE: "elasticsearch"
  ELASTIC_PASSWORD: "elastic-secret"
  SOME_OTHER_VAR: "value"

During helm install or helm upgrade, this template will generate a Kubernetes Secret named <release-name>-env-config containing:

• All non-empty environment variables, including SOME_OTHER_VAR: "value"

• Hostnames for services like Redis, MySQL, MinIO

• Required passwords for Redis, MySQL, MinIO, and Elasticsearch

• Fail if any required password is missing or DOC_ENGINE is invalid

This secret can then be mounted or injected as environment variables into Ragflow pods.

Important Implementation Details

• Helm Template Logic: The file uses Helm's Go templating language with conditionals, loops, and functions such as required, include, and printf.

• Secret Segregation TODO: The file header includes a TODO comment suggesting splitting environment variables into separate secrets so that pods only get the secrets they need, improving security.

• Internal DNS Usage: By constructing hostnames based on release name and namespace, the file leverages Kubernetes service discovery for intra-cluster communication.

• Fail Fast on Missing Secrets: The use of required function ensures that Helm deployments do not proceed unless critical secrets are provided, preventing runtime errors.

• Conditional Engine Configuration: Supports multiple document engines, enabling flexible deployments with tailored environment variables.

• Opaque Secret: Data is stored as string data, Kubernetes encodes it to base64 automatically.

Interaction with Other System Components

• Ragflow Application Pods: These pods consume the generated secret as environment variables to configure connections to Redis, MySQL, MinIO, and the document engine.

• Kubernetes Services: The hostnames refer to cluster services managing Redis, MySQL, MinIO, Elasticsearch/OpenSearch/Infinity.

• Helm Chart: This template is part of the Ragflow Helm chart, dynamically adapting to the release name and namespace.

• Secret Injection: The secret is typically referenced in pod specs under envFrom or individual env entries to inject configuration.

Visual Diagram

flowchart TD
    A[Helm Values (.Values.env)] --> B[env.yaml Template]
    B --> C[Generate Kubernetes Secret]
    C --> D[Secret: <release>-env-config]
    D --> E[Ragflow Pods]
    E --> F{Use Environment Variables}
    F --> G[Connect to Redis Service]
    F --> H[Connect to MySQL Service]
    F --> I[Connect to MinIO Service]
    F --> J[Connect to Document Engine Service]
    subgraph DocEngine
        J --> K[Elasticsearch]
        J --> L[OpenSearch]
        J --> M[Infinity]
    end

Summary

env.yaml is a critical Helm template that consolidates environment variable secrets for the Ragflow application. It dynamically builds Kubernetes secrets with required credentials and service hostnames, enforces configuration correctness, and supports multiple document engines. Its design promotes secure, reliable, and flexible application configuration within Kubernetes. The TODO note indicates plans for future improvement by splitting secrets to enhance security.