ragflow.yaml

Overview

ragflow.yaml is a Kubernetes Helm template manifest that defines the deployment and service resources for the ragflow component of an application. This file is responsible for configuring how the ragflow service is deployed, scaled, exposed, and integrated within the Kubernetes cluster. It uses Helm templating features extensively to allow dynamic customization of deployment parameters, labels, selectors, container images, resource limits, and service exposure based on values provided at deployment time.

The manifest includes:

• A Deployment resource that manages the lifecycle of ragflow pods, specifying container images, ports, volumes, environment variables, and deployment strategies.

• One or two Service resources that expose ragflow's HTTP and optional HTTP API endpoints inside the cluster or externally, depending on configuration.

This file is crucial for orchestrating ragflow's runtime environment and ensuring it is discoverable and scalable within the Kubernetes ecosystem.

Detailed Explanation

Deployment Resource

The Deployment object manages a set of pods running the ragflow application. It ensures the desired number of replicas are running and manages rolling updates.

Key Sections:

• metadata.name: Uses the Helm template function {{ include "ragflow.fullname" . }} to generate a unique name based on the release and chart name.

• metadata.labels: Applies labels for identification and selection, including a component label app.kubernetes.io/component: ragflow.

• spec.replicas: Sets the number of pod replicas to 1 by default; can be customized via Helm values.

• spec.selector.matchLabels: Matches pods based on labels to control which pods belong to this deployment.

• spec.strategy: Optional deployment strategy (e.g., RollingUpdate) provided via Helm values.

• spec.template.metadata.labels & annotations:

  • Labels mirror those in the selector for proper pod matching.

  • Annotations include checksums of configuration files (env.yaml and ragflow_config.yaml) to trigger pod restarts when configs change.

• spec.template.spec:

  • imagePullSecrets: Supports secret references for pulling images from private registries.

  • containers: Defines the main ragflow container:

    • image: Pulled from values, supports repository and tag.

    • imagePullPolicy: Optional, controls image pull behavior.

    • ports: Exposes two ports:

      • 80 named http

      • 9380 named http-api

    • volumeMounts: Mounts several configuration files from ConfigMaps into standard NGINX config paths and ragflow-specific config paths.

    • envFrom: Injects environment variables from a Kubernetes Secret.

    • resources: Optional resource requests and limits.

  • volumes:

    • nginx-config-volume: ConfigMap volume for NGINX configuration files.

    • service-conf-volume: ConfigMap volume for ragflow service configuration files (local.service_conf.yaml, llm_factories.json).

Usage example snippet (values.yaml):

ragflow:
  image:
    repository: myrepo/ragflow
    tag: v1.0.0
    pullPolicy: IfNotPresent
  deployment:
    replicas: 2
    strategy:
      type: RollingUpdate
      rollingUpdate:
        maxSurge: 1
        maxUnavailable: 0
  service_conf: true
  llm_factories: true
  deployment:
    resources:
      limits:
        cpu: "500m"
        memory: "256Mi"
      requests:
        cpu: "250m"
        memory: "128Mi"

Service Resources

Two Kubernetes Service objects are declared to expose ragflow:

1. Primary ragflow Service

• metadata.name: Matches deployment name.

• metadata.labels: Includes ragflow component label.

• spec.selector: Matches pods labeled with ragflow selector labels.

• spec.ports:

  • Exposes TCP port 80 (named http) targeting the container's port 80.

• spec.type: Configurable service type (e.g., ClusterIP, NodePort, LoadBalancer) via Helm values.

2. Optional ragflow API Service

• Conditionally created if .Values.ragflow.api.service.enabled is true.

• Named <release-name>-api.

• Exposes TCP port 80 (named http-api) targeting container port 9380.

• Uses the same selectors and labels as the main service.

• Service type is configurable via .Values.ragflow.api.service.type.

Important Implementation Details

• Helm Templating: The file uses advanced Helm templating features for:

  • Dynamic naming and labeling.

  • Conditional inclusion of deployment strategies, image pull secrets, resource requests/limits.

  • Checksums of configuration files in pod annotations to ensure pods are restarted when config maps change.

• Volume Mount Strategy: Multiple config files (ragflow.conf, proxy.conf, nginx.conf, local.service_conf.yaml, llm_factories.json) are mounted from ConfigMaps. This allows configuration updates without changing container images.

• Multiple Ports and Services: Supporting two ports and corresponding services enables separation of normal HTTP traffic and API traffic, which can be independently exposed and managed.

• Resource Management: The file supports flexible resource management through .Values.ragflow.deployment.resources.

System Interaction

• With Helm: This YAML is a Helm chart template, meaning it requires Helm to render and deploy it. It relies on Helm functions and values injected at deployment time.

• With Kubernetes: Defines core Kubernetes objects (Deployment and Service) that Kubernetes uses to schedule pods and expose them.

• With ConfigMaps and Secrets: The deployment depends on multiple ConfigMaps (nginx-config, ragflow-service-config) and a Secret (for environment variables), which must be created separately or by other Helm templates.

• With NGINX: The container mounts NGINX configuration files, indicating ragflow uses NGINX as a reverse proxy or HTTP server inside the pod.

• With Application Code: The ragflow container image runs the ragflow service exposing two ports for HTTP and API traffic.

Visual Diagram

flowchart TD
    subgraph Deployment "Deployment: ragflow"
        direction TB
        Pod["Pod: ragflow container"]
        Pod -->|mounts| ConfigMap_NGINX["ConfigMap: nginx-config"]
        Pod -->|mounts| ConfigMap_ServiceConf["ConfigMap: ragflow-service-config"]
        Pod -->|envFrom| Secret_Env["Secret: ragflow-env-config"]
        Pod -->|exposes ports| PortHTTP[Port 80 (http)]
        Pod -->|exposes ports| PortAPI[Port 9380 (http-api)]
    end

    subgraph Services "Services"
        ServiceMain["Service: ragflow"]
        ServiceAPI["Service: ragflow-api (optional)"]
    end

    ServiceMain -->|targets port 80| Pod
    ServiceAPI -->|targets port 9380| Pod

    Deployment -->|manages| Pod

Summary

The ragflow.yaml file is a critical Helm template that defines how the ragflow service is deployed and exposed within a Kubernetes cluster. It supports configurable container images, environment injection, resource limits, multiple ports for HTTP and API traffic, and flexible service exposure. It integrates tightly with ConfigMaps and Secrets for configuration management and leverages Helm templating to allow dynamic and reusable deployment configurations.

This file interacts with other parts of the system mainly through the ConfigMaps and Secrets it mounts and by exposing services that other components or external clients can consume.

End of Documentation for ragflow.yaml