StackGres Operator Kubernetes Jobs 容器镜像文档

一、镜像概述和主要用途

StackGres Operator Kubernetes Jobs 容器镜像是 StackGres 开源项目（[***] StackGres Operator 管理 PostgreSQL 集群时所需的 Kubernetes Jobs 任务。该镜像与 StackGres Operator 深度集成，负责执行各类数据库运维自动化任务，是 StackGres 实现 PostgreSQL 集群生命周期管理的关键支撑。

二、核心功能和特性

核心功能

数据库运维任务执行：支持 PostgreSQL 集群的备份、恢复、初始化配置、升级前置检查、配置同步等核心运维操作。
Operator 协同工作：与 StackGres Operator 实时通信，接收任务指令并反馈执行状态，确保任务与集群状态一致。
任务生命周期管理：自动处理任务的启动、重试、超时控制及资源清理，符合 Kubernetes Jobs 规范。

特性

无缝集成 StackGres 生态：与 StackGres CRD（如 SGCluster、SGBackup、SGRecovery 等）深度联动，支持通过自定义资源配置任务参数。
参数化任务配置：支持通过环境变量或配置文件灵活定义任务行为（如备份保留策略、恢复目标时间点等）。
安全合规：内置对 PostgreSQL 认证信息（如密码、SSL 证书）的安全处理，支持与 Kubernetes Secrets 集成。
轻量级设计：基于 Alpine 或 Distroless 基础镜像构建，体积小、启动快，减少资源占用。

三、使用场景和适用范围

使用场景

自动化备份：配合 StackGres SGBackupConfig CRD，执行定时或手动触发的 PostgreSQL 全量/增量备份。
数据库恢复：通过 SGRecovery CRD 触发数据恢复任务，支持基于备份集或时间点的恢复。
集群初始化：在新建 PostgreSQL 集群时，执行初始配置（如扩展安装、参数调优、用户创建等）。
配置更新：当集群参数（如 postgresql.conf）变更后，执行配置同步与服务重载任务。
升级前置检查：在 PostgreSQL 版本升级前，执行兼容性检查、数据一致性校验等预备任务。

适用范围

环境：基于 Kubernetes 的 StackGres Operator 部署环境（Kubernetes 1.21+）。
依赖：需与 StackGres Operator（v1.3+ 推荐）及 PostgreSQL 集群（12+）配合使用。
用户：StackGres 集群管理员、数据库运维人员，通过 StackGres CRD 或 Operator API 间接使用。

四、使用方法和配置说明

该镜像通常由 StackGres Operator 自动调度和管理，无需用户手动运行。任务触发及参数配置通过 StackGres 自定义资源（CRD）完成。以下为关键使用流程和配置项说明。

4.1 任务触发方式

通过创建/更新 StackGres CRD 触发对应任务，Operator 会自动生成并调度 Kubernetes Job，使用本镜像执行具体操作。常见触发场景：

任务类型	触发方式	关联 CRD
备份任务	创建 `SGBackup` 资源或配置 `SGBackupConfig` 自动备份	`SGBackup`、`SGBackupConfig`
恢复任务	创建 `SGRecovery` 资源指定恢复源	`SGRecovery`
初始化配置	创建 `SGCluster` 资源时指定初始化脚本	`SGCluster`

4.2 配置参数

任务参数通过 CRD 字段定义，Operator 会将其转换为环境变量或配置文件注入 Job 容器。核心参数示例：

参数类别	说明	CRD 配置路径示例
数据库连接信息	PostgreSQL 实例地址、端口、用户名、密码（由 Operator 从 Secrets 自动注入）	`SGCluster.spec.postgres.exporter.user`
备份任务参数	备份类型（全量/增量）、存储位置（S3/GCS/本地）、压缩算法	`SGBackup.spec.backupType`、`SGBackupConfig.spec.storage`
恢复任务参数	恢复源（备份 ID 或时间点）、目标集群	`SGRecovery.spec.source`、`SGRecovery.spec.target`

4.3 环境变量

Job 容器运行时由 Operator 注入的关键环境变量（部分示例）：

环境变量名	说明	示例值
`POSTGRES_HOST`	目标 PostgreSQL 实例地址	`my-postgres-cluster-primary`
`POSTGRES_PORT`	数据库端口	`5432`
`POSTGRES_USER`	数据库用户名（具备运维权限）	`stackgres_replication`
`BACKUP_TYPE`	备份类型	`full`（全量）/ `incremental`（增量）
`STORAGE_BACKEND`	备份存储后端	`s3` / `gcs` / `local`

五、部署示例

5.1 通过 StackGres CRD 触发备份任务

创建 SGBackup 资源触发手动备份（需提前配置 SGBackupConfig）：

yaml
apiVersion: stackgres.io/v1
kind: SGBackup
metadata:
  name: manual-backup-01
  namespace: stackgres
spec:
  sgCluster: my-postgres-cluster  # 目标集群名称
  sgBackupConfig: default-backup-config  # 引用的备份配置

应用后，StackGres Operator 会自动创建 Kubernetes Job，使用本镜像执行备份任务，可通过 kubectl get jobs -n stackgres 查看任务状态。

5.2 调试场景：手动运行容器（不推荐生产环境）

如需调试，可手动运行镜像（需挂载必要的 Secrets 和配置文件）：

bash
docker run -it --rm \
  -e POSTGRES_HOST=my-postgres-cluster-primary \
  -e POSTGRES_PORT=5432 \
  -e POSTGRES_USER=stackgres_replication \
  -e POSTGRES_PASSWORD=$(kubectl get secret -n stackgres my-postgres-cluster-postgres-secret -o jsonpath='{.data.password}' | base64 -d) \
  -e BACKUP_TYPE=full \
  stackgres/jobs:latest  # 替换为实际镜像标签（如 1.5.0）

六、注意事项

版本兼容性：镜像版本需与 StackGres Operator 版本匹配（如 Operator v1.5.0 对应 jobs 镜像 v1.5.0），避免功能不兼容。
资源限制：根据任务类型（如全量备份）调整 Job 资源请求（CPU/内存），避免资源不足导致任务失败。
权限控制：Job 需通过 RBAC 配置获取访问 Kubernetes API 和集群资源的权限，由 StackGres Operator 自动配置。
日志查看：任务日志可通过 kubectl logs <job-pod-name> -n <namespace> 查看，用于故障排查。