infinity.yaml

Overview

The infinity.yaml file is a Helm chart template defining Kubernetes resources for deploying the Infinity component of the Ragflow application stack. This component appears to be a stateful service requiring persistent storage and networked access through multiple ports using different protocols.

This file dynamically generates the following Kubernetes manifests when the Helm value env.DOC_ENGINE is set to "infinity":

• PersistentVolumeClaim (PVC): Requests persistent storage for Infinity’s data.

• StatefulSet: Manages the deployment and lifecycle of the Infinity pod(s) with stable network IDs and persistent storage.

• Service: Exposes Infinity’s network ports for internal cluster communication or external access depending on the service type.

This file leverages Helm templating features extensively to insert values from the chart’s values.yaml or other templates, such as labels, storage class names, image details, and deployment strategies.

Detailed Resource Descriptions

PersistentVolumeClaim (PVC)

• Purpose: Reserves persistent storage for Infinity to store its data reliably across pod restarts or rescheduling.

• Kubernetes Kind: PersistentVolumeClaim

• Key Fields:

  • metadata.name: Uses a templated full name appended with -infinity.

  • metadata.annotations: Includes a Helm resource policy to keep the PVC on chart deletion.

  • spec.storageClassName: Optional, set from infinity.storage.className if provided.

  • spec.accessModes: Set to ReadWriteOnce, meaning the volume can be mounted as read-write by a single node.

  • spec.resources.requests.storage: Requested storage capacity from infinity.storage.capacity.

Example usage snippet:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: ragflow-infinity
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi

StatefulSet

• Purpose: Deploys and manages the Infinity application container with persistent storage and stable network identity.

• Kubernetes Kind: StatefulSet

• Key Fields:

  • metadata.name: Chart fullname + -infinity.

  • spec.replicas: Fixed at 1 replica.

  • spec.selector.matchLabels: Matches labels including app.kubernetes.io/component: infinity and custom selector labels.

  • spec.strategy: Deployment strategy, optionally injected from .Values.infinity.deployment.strategy.

  • spec.template:

    • Metadata: Labels and annotations, including a checksum annotation to trigger rolling updates on config change.

    • Spec:

      • imagePullSecrets: Aggregates pull secrets from both global and infinity-specific values.

      • containers: Defines the Infinity container:

        • name: infinity

        • image: Composed from repository and tag values.

        • imagePullPolicy: Optional, from values.

        • envFrom: Loads environment variables from a secret named like <chart-fullname>-env-config.

        • ports:

          • 23817 named thrift

          • 23820 named http

          • 5432 named psql

        • volumeMounts: Mounts the PVC to /var/infinity.

        • resources: Optional CPU/memory resource requests and limits.

        • securityContext: Adds NET_BIND_SERVICE capability and RuntimeDefault seccomp profile.

        • livenessProbe: HTTP GET probe on /admin/node/current over port 23820 with extended failure threshold to handle long startup times.

      • volumes: Mounts the PVC named <chart-fullname>-infinity at infinity-data.

Usage notes:

• The StatefulSet is designed to ensure stable storage and network identity for the Infinity service.

• The liveness probe helps Kubernetes detect pod health and restart if necessary.

• SecurityContext settings allow the container to bind to low-numbered ports securely.

Service

• Purpose: Exposes the Infinity StatefulSet pods internally or externally depending on the service type.

• Kubernetes Kind: Service

• Key Fields:

  • metadata.name: <chart-fullname>-infinity.

  • spec.selector: Matches the same labels as the StatefulSet pods.

  • spec.ports:

    • Port 23817 for thrift protocol.

    • Port 23820 for http protocol.

    • Port 5432 for psql protocol.

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

Example:

spec:
  type: ClusterIP
  ports:
    - port: 23817
      name: thrift
    - port: 23820
      name: http
    - port: 5432
      name: psql

Important Implementation Details and Algorithms

• Helm Condition: The entire manifest is wrapped inside a conditional that renders the resources only if .Values.env.DOC_ENGINE equals "infinity". This allows selective enabling/disabling of the Infinity component.

• Templating: Uses Helm include functions extensively to standardize naming (ragflow.fullname), labels (ragflow.labels), and selectors (ragflow.selectorLabels).

• Checksums for Config Updates: The StatefulSet pod template includes a checksum annotation of another config file (env.yaml). This triggers rolling pods restart when environment variables or configurations change, ensuring the pod always runs with the latest configs.

• Security Context: Explicit capability addition and seccomp profile aim to enhance security while allowing required network operations.

• Extended Liveness Probe: The liveness probe has a high failure threshold (120) and long initial delay (60s) to accommodate potentially slow startups or transient issues without causing premature pod restarts.

• Volume Management: The PersistentVolumeClaim is annotated with helm.sh/resource-policy: keep to preserve data even if the Helm release is deleted, preventing accidental data loss.

Interaction with Other Parts of the System

• Helm Chart Integration: This file is part of the Ragflow Helm chart and depends on common template helpers (ragflow.fullname, ragflow.labels, etc.) defined elsewhere in the chart.

• Configuration and Secrets: The environment variables are injected from a Kubernetes Secret named <chart-fullname>-env-config, which must be created separately, likely by another chart template or external process.

• Storage Backend: The PVC requests storage, which relies on the Kubernetes cluster storage classes and provisioning mechanisms.

• Networking: The Service resource enables other components or external clients to communicate with the Infinity pods via the published ports using defined protocols (Thrift, HTTP, PostgreSQL).

• Deployment Strategy: Custom deployment strategies (e.g., rolling update, recreate) can be specified through Helm values to control pod update behavior.

• Image Pull Secrets: Supports private container registries by allowing image pull secrets globally or specifically for Infinity.

Visual Diagram

flowchart TD
    PVC[PersistentVolumeClaim]
    StatefulSet[StatefulSet: infinity]
    Service[Service: infinity]
    ConfigSecret[Secret: <fullname>-env-config]

    PVC --> StatefulSet
    ConfigSecret --> StatefulSet
    StatefulSet --> Service

    subgraph StatefulSet Pod
        Container[Container: infinity]
        Container -->|Port 23817 (thrift)| Service
        Container -->|Port 23820 (http)| Service
        Container -->|Port 5432 (psql)| Service
        Container -->|Mount /var/infinity| PVC
    end

Summary

The infinity.yaml Helm template file defines the Kubernetes resources necessary to deploy the Infinity data storage and service component within Ragflow. It ensures persistent storage, secure and controlled deployment of the service container, and proper network exposure via a Kubernetes Service. The file is highly configurable through Helm values and integrates with Ragflow’s templating framework to maintain consistent naming and labeling conventions. It includes best practices for lifecycle management, security, and configuration updates.