MariaDB Operator 配套 Docker 镜像文档

一、镜像概述

本镜像专为配合 MariaDB Operator 使用而设计，提供在 Kubernetes 环境中部署和管理 MariaDB 数据库的容器化支持。作为 MariaDB Operator 的核心组件之一，该镜像实现了与 Operator 的无缝集成，支持自动化数据库生命周期管理、配置同步及高可用部署，适用于云原生环境下的 MariaDB 集群构建与运维。

二、核心功能与特性

2.1 兼容性保障

• 与 MariaDB Operator 官方版本深度兼容，支持 Operator 定义的自定义资源（CR）规范，确保数据库部署与管理流程一致性。

2.2 自动化生命周期管理

• 配合 Operator 实现 MariaDB 实例的自动化部署、扩缩容、版本升级及故障自愈。
• 支持基于 CR 配置的备份策略（定时备份、手动备份）与恢复流程。

2.3 灵活配置支持

• 通过环境变量、ConfigMap 或自定义配置文件注入数据库参数（如字符集、连接数限制等）。
• 支持存储类（StorageClass）动态绑定，适配不同持久化需求（本地存储、云存储等）。

2.4 安全与可靠性

• 集成密码管理机制，支持通过 Kubernetes Secrets 注入敏感信息（如 root 密码、用户密码）。
• 内置健康检查探针（liveness/readiness probe），确保实例可用性监控。

三、使用场景与适用范围

3.1 典型使用场景

• Kubernetes 集群中的 MariaDB 部署：通过 Operator 与本镜像快速搭建单节点或多节点 MariaDB 集群。
• 自动化运维场景：无需手动干预，实现数据库的扩缩容、备份、故障转移等运维操作。
• 高可用架构：配合 Operator 的副本集管理功能，构建主从复制或 Galera 集群，满足业务高可用需求。
• 云原生应用集成：作为微服务架构的后端数据库，通过 Kubernetes Service 提供稳定访问入口。

3.2 适用范围

• 已部署 MariaDB Operator 的 Kubernetes 集群（版本需与镜像兼容）。
• 需要标准化、自动化管理 MariaDB 生命周期的团队或企业。
• 对数据库高可用、数据安全有严格要求的生产环境或测试环境。

四、使用方法与配置说明

4.1 前提条件

• Kubernetes 集群（v1.21+，推荐 v1.24+）。
• MariaDB Operator 已安装（参考 官方安装文档）。
• 集群内已配置可用的 StorageClass（用于数据持久化）。

4.2 基本使用流程

1. 创建 MariaDB 自定义资源（CR）：通过 YAML 文件定义数据库实例配置（如副本数、资源限制、存储大小等）。
2. 应用 CR 配置：使用 kubectl apply 提交配置，Operator 将自动调用本镜像创建数据库实例。
3. 验证部署：通过 kubectl get pods 检查 Pod 状态，通过 kubectl logs 查看日志确认启动正常。

4.3 核心配置参数

4.3.1 环境变量配置

4.3.2 卷挂载配置

4.4 部署示例

4.4.1 Kubernetes YAML 配置示例（MariaDB CR）

# mariadb-instance.yaml
apiVersion: mariadb.mmontes.io/v1alpha1
kind: MariaDB
metadata:
  name: mariadb-example
  namespace: default
spec:
  replicas: 1  # 单节点；多节点需配置 replication
  image: <镜像名称>:<版本>  # 替换为实际镜像名和版本
  imagePullPolicy: IfNotPresent
  rootPasswordSecretKeyRef:
    name: mariadb-secrets
    key: root-password  # 从 Secret 中读取 root 密码
  database: myappdb  # 初始化数据库名称
  username: myappuser  # 初始化普通用户名
  passwordSecretKeyRef:
    name: mariadb-secrets
    key: user-password  # 从 Secret 中读取普通用户密码
  storage:
    size: 10Gi  # 数据存储大小
    storageClass: standard  # 替换为集群内可用的 StorageClass
  resources:
    requests:
      cpu: 200m
      memory: 256Mi
    limits:
      cpu: 1000m
      memory: 1Gi
  livenessProbe:
    initialDelaySeconds: 30
    periodSeconds: 10
  readinessProbe:
    initialDelaySeconds: 5
    periodSeconds: 5

创建 Secret（用于存储密码）：

# mariadb-secrets.yaml
apiVersion: v1
kind: Secret
metadata:
  name: mariadb-secrets
  namespace: default
type: Opaque
data:
  root-password: <base64编码的root密码>  # 例如：echo -n "mypassword" | base64
  user-password: <base64编码的用户密码>

应用配置：

kubectl apply -f mariadb-secrets.yaml
kubectl apply -f mariadb-instance.yaml

4.4.2 本地测试（docker-compose 配置）

适用于本地验证镜像功能（非生产环境）：

# docker-compose.yml
version: '3.8'
services:
  mariadb:
    image: <镜像名称>:<版本>  # 替换为实际镜像名和版本
    environment:
      - MARIADB_ROOT_PASSWORD=rootpass123
      - MARIADB_DATABASE=testdb
      - MARIADB_USER=testuser
      - MARIADB_PASSWORD=userpass123
    ports:
      - "3306:3306"
    volumes:
      - ./mariadb-data:/var/lib/mysql  # 本地目录持久化数据
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u root", "-p$$MARIADB_ROOT_PASSWORD"]
      interval: 10s
      timeout: 5s
      retries: 5

启动容器：

docker-compose up -d

4.4.3 本地单容器测试（docker run）

docker run -d \
  --name mariadb-test \
  -p 3306:3306 \
  -e MARIADB_ROOT_PASSWORD=rootpass123 \
  -e MARIADB_DATABASE=testdb \
  -e MARIADB_USER=testuser \
  -e MARIADB_PASSWORD=userpass123 \
  -v ./mariadb-data:/var/lib/mysql \
  <镜像名称>:<版本>  # 替换为实际镜像名和版本

五、注意事项

1. 版本兼容性：镜像版本需与已安装的 MariaDB Operator 版本匹配（参考 Operator 官方兼容性矩阵），避免因版本不兼容导致部署失败。
2. 资源配置：根据业务负载调整 resources 中的 CPU/内存限制，避免资源不足导致数据库性能下降或 Pod 被驱逐。
3. 数据备份：生产环境需通过 Operator 配置定时备份策略，并将备份数据存储至外部存储（如 S3、NFS），避免数据丢失。
4. 安全加固：
   • 禁止使用弱密码，推荐通过 Kubernetes Secret 管理敏感信息。
   • 限制数据库服务访问范围（如通过 NetworkPolicy 仅允许指定 Pod 访问）。
   • 定期更新镜像版本，修复潜在安全漏洞。

六、故障排除

• Pod 启动失败：检查 Secret 是否正确创建、挂载路径权限是否正常，可通过 kubectl logs <pod-name> 查看具体错误日志。
• 数据库连接超时：确认 Kubernetes Service 配置正确，网络策略未阻止 3306 端口访问，或检查容器健康检查状态。
• 数据持久化异常：验证 StorageClass 是否可用，PVC 是否成功绑定，可通过 kubectl describe pvc <pvc-name> 排查存储问题。

如需进一步支持，可参考 MariaDB Operator 官方文档 或提交 Issue 至镜像维护仓库。