astronomerinc/ap-db-bootstrapper

数据库引导初始化容器（Kubernetes Init Container）

镜像概述和主要用途

本镜像为Kubernetes环境下的Init Container，旨在通过Kubernetes Secrets存储的配置信息，自动化完成数据库的初始化流程。其核心功能是在Pod启动阶段，读取 Secrets 中的数据库连接参数（如用户名、密码、地址等），执行必要的初始化操作（如创建数据库、用户、权限配置或SQL脚本执行），确保主应用容器启动前数据库环境已准备就绪。初始化完成后自动退出（符合Init Container生命周期特性），若失败则终止Pod启动并输出错误信息，便于问题排查。

核心功能和特性

• Secrets驱动配置：从Kubernetes Secrets动态读取数据库连接参数（支持自定义 Secrets 键名），避免配置硬编码。
• 多数据库支持：兼容主流关系型数据库，包括MySQL、PostgreSQL、MariaDB、SQL Server等。
• 灵活初始化操作：支持执行自定义SQL脚本（脚本内容可存储于Secrets中）或内置基础初始化逻辑（如创建默认用户、数据库）。
• 生命周期适配：初始化成功后立即退出（退出码0），失败时返回非0退出码并终止Pod启动，符合Kubernetes Init Container规范。
• 可观测性：提供详细日志输出（包含连接过程、执行步骤、错误信息），支持日志级别配置（INFO/WARN/ERROR/DEBUG）。

使用场景和适用范围

典型场景

• 新Pod首次部署：在应用首次启动前，自动初始化数据库（如创建Schema、默认用户、基础数据）。
• 环境隔离部署：通过不同环境的Secrets注入差异化配置（如开发/测试/生产环境的数据库地址、凭证），实现初始化流程标准化。
• 数据库迁移/升级：在应用版本迭代时，执行Schema变更脚本（如表结构更新、索引创建），确保数据库与应用版本兼容。

适用范围

• 环境：Kubernetes集群（v1.12+，支持Init Container和Secrets挂载）。
• 数据库类型：MySQL（5.7+）、PostgreSQL（10+）、MariaDB（10.2+）、SQL Server（2017+）。
• 使用限制：仅用于Kubernetes Pod的Init Container阶段，不支持独立运行（需依赖Kubernetes Secrets和数据库网络可达性）。

使用方法和配置说明

前置条件

1. Kubernetes集群环境（v1.12+），且Pod所在命名空间已创建存储数据库配置的Secrets。
2. 数据库服务已部署且网络可被Pod访问（需确保Pod与数据库间网络打通，如通过Service暴露数据库）。
3. 若使用自定义SQL脚本，需将脚本内容存储于Kubernetes Secrets中（支持单行或多行脚本，需Base64编码）。

1. Secrets配置示例

需提前创建存储数据库连接参数的Secrets（以下以MySQL为例），包含数据库地址、端口、用户名、密码等关键信息。若需执行SQL脚本，可额外创建存储脚本的Secrets。

数据库连接参数Secrets（必填）

yaml
# db-credentials-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: db-credentials
  namespace: default  # 与Pod同命名空间
type: Opaque
data:
  # 注意：值需Base64编码（可通过 echo -n "value" | base64 生成）
  db_host: bXlzcWwubG9jYWw=  # 示例：mysql.local（Base64编码后）
  db_port: NTQzMg==          # 示例：5432（PostgreSQL默认端口）或3306（MySQL）
  db_user: dXNlcjE=          # 示例：user1
  db_password: cGFzc3dvcmQxMjM=  # 示例：password123
  db_name: bXlkYg==          # 示例：mydb（需初始化的数据库名称）

SQL脚本Secrets（可选，若需执行自定义脚本）

yaml
# init-sql-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: init-sql-scripts
  namespace: default
type: Opaque
data:
  # 多行SQL脚本示例（创建表、插入初始数据）
  schema.sql: Q1JFQVRFIFRBQkxFIGZvbyAoCmNvZGluZzogdmFyaWFudCwKbmFtZTogc3RyaW5nCik7CgogSU5TRVJUIElOVE8gZm9vICh2YXJpYW50LCAnYmFyJyk7  # Base64编码后的SQL内容

2. Pod配置示例

在Pod定义中，通过initContainers字段配置本镜像，指定所需环境变量（用于关联Secrets和初始化参数）。主应用容器需依赖Init Container完成后启动（通过initContainers默认依赖关系实现）。

yaml
# app-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: app-with-db-init
  namespace: default
spec:
  initContainers:
  - name: db-init
    image: [镜像名称]  # 替换为实际镜像地址（如registry.example.com/db-bootstrap:v1.0）
    env:
      # 数据库类型（必填，支持：mysql/postgresql/mariadb/sqlserver）
      - name: DB_TYPE
        value: "postgresql"
      # 数据库连接参数Secrets配置（必填）
      - name: SECRET_DB_CREDENTIALS
        value: "db-credentials"  # 对应上文创建的db-credentials Secrets名称
      - name: SECRET_DB_HOST_KEY
        value: "db_host"         # Secrets中存储主机地址的键名（对应data.db_host）
      - name: SECRET_DB_PORT_KEY
        value: "db_port"         # Secrets中存储端口的键名
      - name: SECRET_DB_USER_KEY
        value: "db_user"         # Secrets中存储用户名的键名
      - name: SECRET_DB_PASSWORD_KEY
        value: "db_password"     # Secrets中存储密码的键名
      - name: SECRET_DB_NAME_KEY
        value: "db_name"         # Secrets中存储数据库名称的键名
      # SQL脚本配置（可选，若无需脚本则删除以下2项）
      - name: SECRET_SQL_SCRIPTS
        value: "init-sql-scripts"  # 对应上文创建的SQL脚本Secrets名称
      - name: SECRET_SQL_KEY
        value: "schema.sql"        # Secrets中存储SQL脚本的键名
      # 日志级别（可选，默认：info，支持：debug/info/warn/error）
      - name: LOG_LEVEL
        value: "debug"
  containers:
  - name: main-app
    image: [主应用镜像]  # 主应用容器镜像
    # 主应用容器配置（如端口、环境变量等）
    ports:
    - containerPort: 8080

3. 环境变量说明

4. 工作流程

1. Pod启动：Kubernetes调度Pod后，优先启动initContainers中的db-init容器。
2. 读取Secrets：db-init容器通过环境变量指定的Secrets名称和键名，从Kubernetes API获取数据库连接参数和SQL脚本（若配置）。
3. 数据库连接：使用Secrets中的参数连接目标数据库，支持超时重试（通过CONNECT_TIMEOUT和RETRY_MAX_ATTEMPTS控制）。
4. 执行初始化：
   • 若未配置SQL脚本：执行基础初始化（创建SECRET_DB_NAME_KEY指定的数据库、授予用户权限）。
   • 若配置SQL脚本：读取并执行SECRET_SQL_KEY对应的SQL内容（支持多行脚本，按顺序执行）。
5. 完成与退出：初始化成功后，容器以退出码0终止；若失败（如连接超时、SQL执行错误），则以非0退出码终止，Pod状态变为Init:Error，需通过日志排查问题。
6. 主容器启动：Init Container成功退出后，Kubernetes启动containers字段中的主应用容器。

故障排查

• Init Container启动失败：检查Pod事件（kubectl describe pod <pod-name>），确认Secrets是否存在、键名是否正确（如SECRET_DB_HOST_KEY是否与Secrets中的键匹配）。
• 数据库连接失败：查看Init Container日志（kubectl logs <pod-name> -c db-init），确认数据库地址、端口是否可达，用户名/密码是否正确。
• SQL脚本执行错误：日志中会输出具体SQL错误（如语法错误、表已存在），需检查SQL脚本内容（可通过kubectl get secret init-sql-scripts -o jsonpath='{.data.schema.sql}' | base64 -d解码查看原始脚本）。