mysql.yaml

Overview

The mysql.yaml file is a Kubernetes manifest template designed for deploying a MySQL database service within a Kubernetes cluster using Helm templating syntax. It defines three primary Kubernetes resources:

PersistentVolumeClaim (PVC) for durable MySQL data storage.
StatefulSet to manage the MySQL pod lifecycle and stateful deployment.
Service to expose the MySQL database internally within the cluster.

This file enables a configurable, replicable, and manageable MySQL deployment that integrates with the overall application (named ragflow in this context), providing persistent storage, initialization scripts, resource allocation, and secure environment management.

Detailed Resource Breakdown

1. PersistentVolumeClaim (PVC)

Purpose

Reserves persistent storage for the MySQL database to ensure data durability beyond pod lifecycles.

Key Fields

apiVersion: v1
kind: PersistentVolumeClaim
metadata.name: Constructed dynamically using Helm template {{ include "ragflow.fullname" . }}-mysql
annotations: Keeps the resource from being deleted by Helm on uninstall ("helm.sh/resource-policy": keep)
labels: Includes common labels plus app.kubernetes.io/component: mysql
spec:
- storageClassName: Optional, configurable storage class.
- accessModes: Set to ReadWriteOnce, allowing single node read/write.
- resources.requests.storage: Requested storage capacity from Helm values (.Values.mysql.storage.capacity).

Usage Example

kubectl apply -f mysql.yaml

This will create a PVC with requested storage capacity defined in the Helm values, e.g., 10Gi.

2. StatefulSet

Purpose

Deploys and manages the MySQL database pod with stable network identity and persistent storage.

Key Fields

apiVersion: apps/v1
kind: StatefulSet
metadata.name: Same naming convention as PVC.
spec:
- replicas: Fixed to 1 (single MySQL instance).
- selector.matchLabels: Matches labels to identify pods.
- strategy: Deployment strategy, optionally configured.
- template:
  - metadata.labels: Pod labels.
  - metadata.annotations: Includes config checksums for rolling updates.
  - spec:
    - imagePullSecrets: Supports private registry secrets.
    - containers:
      - name: mysql
      - image: Configurable repository and tag.
      - imagePullPolicy: Optional pull policy.
      - envFrom: Loads environment variables from a secret.
      - args: MySQL server startup arguments, including:
        Max connections (1000)
        Character set and collation settings (utf8mb4)
        Authentication plugin (mysql_native_password)
        TLS versions (TLSv1.2, TLSv1.3)
        Initialization SQL file path (/data/application/init.sql)
        Disables binary logging.
      - ports: Exposes MySQL port 3306.
      - resources: Configurable CPU/memory limits and requests.
      - volumeMounts:
        Mounts persistent volume at /var/lib/mysql
        Mounts initialization SQL script read-only with subPath init.sql
    - volumes:
      - Persistent volume claim named mysql-data
      - ConfigMap volume for the init script named init-script-volume

Important Implementation Details

The init-file MySQL argument points to an SQL file mounted from a ConfigMap, which is executed on MySQL startup for initialization.
The pod uses a single replica for simplicity and state consistency.
Rolling restarts occur when checksums of configuration files change, ensuring configuration updates trigger pod restarts.
The container environment is securely injected via Kubernetes secrets.
Resource constraints are customizable for cluster resource management.

Usage Example

helm install ragflow ./chart-directory

This command deploys the StatefulSet with associated PVC and Service, using values defined in your Helm values.yaml.

3. Service

Purpose

Provides a stable internal endpoint for accessing the MySQL database within the Kubernetes cluster.

Key Fields

apiVersion: v1
kind: Service
metadata.name: Matches StatefulSet and PVC naming pattern.
spec:
- selector: Matches MySQL pods by labels.
- ports:
  - Protocol TCP
  - Port 3306 (standard MySQL port)
  - TargetPort references the container port named mysql.
- type: Service type (ClusterIP, NodePort, LoadBalancer), configurable via Helm values.

Usage Example

Once deployed, other services/pods can connect to MySQL using the service DNS name:

mysql -h ragflow-mysql -P 3306 -u user -p

Interaction With Other System Components

Helm Templates: This file leverages Helm templating helpers such as ragflow.fullname, ragflow.labels, and ragflow.selectorLabels to maintain consistency and reusability across the deployment.
ConfigMaps and Secrets: The MySQL initialization SQL script is injected from a ConfigMap named mysql-init-script. Environment variables are sourced from a secret named ragflow-env-config.
Persistent Storage: The PVC binds to a PersistentVolume, which is provisioned either statically or dynamically based on the configured StorageClass.
Application Components: The MySQL service is a backend dependency, exposed internally for other application components to connect.

Key Algorithms and Implementation Notes

Rolling Update Trigger: The pod template annotations include SHA256 checksums of configuration files. When these files change, Kubernetes detects a pod spec change and performs a rolling update of the StatefulSet pods.
MySQL Initialization: The --init-file argument points to a mounted SQL script used to bootstrap the DB on first startup.
Volume Mounts: Data persistence and configuration injection are handled carefully through volume mounts and subPaths to ensure files are correctly positioned inside the container.

Mermaid Diagram: Kubernetes Resource Structure and Relationships

flowchart TD
    PVC[PersistentVolumeClaim]
    PVC -->|Bound to| PV[PersistentVolume]

    StatefulSet -->|Uses PVC| PVC
    StatefulSet -->|Mounts ConfigMap| ConfigMap[ConfigMap: mysql-init-script]
    StatefulSet -->|Uses Secret| Secret[Secret: ragflow-env-config]
    StatefulSet -->|Runs container| Container[Container: mysql]

    Service -->|Selects pods by labels| StatefulSet

    style PVC fill:#f9f,stroke:#333,stroke-width:1px
    style PV fill:#bbf,stroke:#333,stroke-width:1px
    style StatefulSet fill:#bfb,stroke:#333,stroke-width:1px
    style Service fill:#ffb,stroke:#333,stroke-width:1px
    style ConfigMap fill:#fbf,stroke:#333,stroke-width:1px
    style Secret fill:#fbb,stroke:#333,stroke-width:1px
    style Container fill:#aff,stroke:#333,stroke-width:1px

Summary

The mysql.yaml file is a Helm-templated Kubernetes manifest that orchestrates a highly available, persistent MySQL deployment tailored for the ragflow application. It leverages Kubernetes StatefulSets for stable pod identity, PVCs for durable storage, and a Service for internal connectivity. The manifest is highly configurable via Helm values, supports secure environment injection, initialization scripting, and resource management, making it a robust solution for containerized MySQL deployment.

If you need further information on Helm templating or Kubernetes StatefulSets, PVCs, and Services, please refer to the official Kubernetes and Helm documentation.