CloudNativePG 备份对象存储完全指南AWS S3、Azure Blob Storage 与 Google Cloud Storage 的认证配置与实战【免费下载链接】cloudnative-pgThe most popular Kubernetes Operator for PostgreSQL.项目地址: https://gitcode.com/GitHub_Trending/cl/cloudnative-pgCloudNativePG 通过 Barman Cloud 工具链将 PostgreSQL 集群的连续物理备份与 WAL 归档写入任意对象存储服务实现零停机在线备份与任意时间点恢复PITR。本文以仓库文档 object_stores.mdAppendix C为主体完整讲解 AWS S3、Azure Blob Storage、Google Cloud Storage 三大公有云对象存储及其兼容实现的认证方式、Cluster 资源配置与运维要点并结合仓库源码与 CRD 定义揭示底层实现细节帮助你在生产环境快速落地一套可复制的对象存储备份方案。背景CloudNativePG 的对象存储备份模型CloudNativePG 的在线热备份能力基于 Barman Cloud 工具集构建备份文件base backup 以 tar 归档形式存在与 WAL 文件都可以写入任意受 Barman Cloud 支持的对象存储服务即Amazon S3Microsoft Azure Blob StorageGoogle Cloud Storage同时也支持上述服务的任意兼容实现如 MinIO、Linode Object Storage、Digital Ocean Spaces、Azurite 等。整个barmanObjectStore配置段定义在Cluster资源的.spec.backup.barmanObjectStore中对应的类型定义见 api/v1/backup_types.goBarmanObjectStoreConfiguration、S3Credentials、AzureCredentials、GoogleCredentials等类型均来自barman-cloudAPI 包。具体的认证方式取决于所选的存储提供商下文逐节展开。版本提示自 CloudNativePG 1.26 起原生的 Barman Cloud 集成已被标记为弃用deprecated官方推荐逐步迁移到 Barman Cloud Plugin 接口。原生集成当前仍然可用但建议在充分测试后规划渐进式迁移。本文内容基于原生barmanObjectStore配置展开迁移指引可参考 Barman Cloud Plugin 的官方对象存储文档。关于认证方法的边界CloudNativePG 本身并不逐一测试barman-cloud支持的所有认证方法。操作者的职责仅限于把提供的凭据传递给barman-cloud后续的认证行为由 Barman Cloud 自身实现决定。因此使用前请参照 Barman Cloud 官方文档确认所选认证方式受支持且配置正确。Bucket 预创建自 Barman Cloud 3.16 起绝大多数barman-cloud命令不再自动创建目标 bucket仅barman-cloud-check-wal-archive会创建。若对一个空 bucket 首次执行的不是该命令CloudNativePG 会抛出错误。因此强烈建议先创建并配置好对象存储 bucket再创建引用它的Cluster资源参见 backup_barmanobjectstore.md 中的相关说明。AWS S3两种凭据授予方式AWS S3 是亚马逊提供的对象存储服务也是 CloudNativePG 备份场景中最常用的目标。为备份配置 S3 bucket 上传权限有两种方式当 CloudNativePG 运行在 EKS 中时使用IRSAIAM Roles for Service Accounts认证或者使用显式的ACCESS_KEY_ID与ACCESS_SECRET_KEY静态凭据。方式一Access Key 静态凭据你需要准备以下环境信息ACCESS_KEY_ID用于向 S3 上传文件的访问密钥 IDACCESS_SECRET_KEY上述访问密钥的保密部分ACCESS_SESSION_TOKEN可选仅在需要临时会话令牌时提供。所使用的访问密钥必须具备向目标 bucket 上传文件的权限。随后通过kubectl创建包含凭据的 Kubernetes Secretkubectl create secret generic aws-creds \ --from-literalACCESS_KEY_IDaccess key here \ --from-literalACCESS_SECRET_KEYsecret key here # --from-literalACCESS_SESSION_TOKENsession token here # if required凭据会存放在 Kubernetes 中若你的集群开启了静态加密encryption at rest凭据也会被加密。随后在Cluster中通过s3Credentials引用该 SecretapiVersion: postgresql.cnpg.io/v1 kind: Cluster [...] spec: backup: barmanObjectStore: destinationPath: destination path here s3Credentials: accessKeyId: name: aws-creds key: ACCESS_KEY_ID secretAccessKey: name: aws-creds key: ACCESS_SECRET_KEYdestinationPath可以是任意指向实例可写入 WAL 文件目录的 URL例如s3://BUCKET_NAME/path/to/folder。从 CRD 定义config/crd/bases/postgresql.cnpg.io_clusters.yaml可以看出s3Credentials还支持可选的region、sessionToken字段以及基于 IAM Role 的inheritFromIAMRole布尔开关在 EKS 环境通过 Web Identity 自动获得角色身份。方式二IAM Role for Service AccountIRSA使用 IRSA 时需要在 PostgreSQL 集群对应的ServiceAccount上设置 annotation。CloudNativePG 支持通过serviceAccountTemplate配置段自动注入这些 annotation该字段定义于 api/v1/cluster_types.goapiVersion: postgresql.cnpg.io/v1 kind: Cluster metadata: [...] spec: serviceAccountTemplate: metadata: annotations: eks.amazonaws.com/role-arn: arn:[...] [...]S3 生命周期策略lifecycle policyBarman Cloud 向 S3 写入对象后在 Barman Cloud 的保留策略将其删除之前不会更新这些对象。官方推荐的生命周期策略组合如下对当前版本的对象设置比 Barman 保留策略多几天的过期时间开启对象版本化object versioning对非当前版本的对象在若干天后过期删除。这样的策略可以防止意外删除同时允许将 CloudNativePG 工作负载的权限限制为可删除对象但不可永久删除对象降低误操作与安全风险。其他 S3 兼容存储endpointURL 指定使用 S3 兼容的对象存储如MinIO、Linode Object Storage时可以通过endpointURL覆盖默认的 S3 端点。以下示例使用 Linodeus-east1区域的bucketapiVersion: postgresql.cnpg.io/v1 kind: Cluster [...] spec: backup: barmanObjectStore: destinationPath: s3://bucket/ endpointURL: https://us-east1.linodeobjects.com s3Credentials: [...]若使用Digital Ocean Spaces则必须采用Path-style语法。以下示例使用 Digital Ocean Spaces 位于SFO3区域的bucketapiVersion: postgresql.cnpg.io/v1 kind: Cluster [...] spec: backup: barmanObjectStore: destinationPath: s3://[your-bucket-name]/[your-backup-folder]/ endpointURL: https://sfo3.digitaloceanspaces.com s3Credentials: [...]规避 boto3 数据完整性校验问题boto3 对 Amazon S3 Data Integrity Protections 的近期实现变更可能触发x-amz-content-sha256错误。遇到该问题时可通过spec.env在集群级别注入以下环境变量作为规避方案apiVersion: postgresql.cnpg.io/v1 kind: Cluster [...] spec: env: - name: AWS_REQUEST_CHECKSUM_CALCULATION value: when_required - name: AWS_RESPONSE_CHECKSUM_VALIDATION value: when_required使用私有 CA 签发的对象存储端点当对象存储提供商使用私有 CA 签发的证书例如通过 HTTPS 访问 MinIO时需要在barmanObjectStore中设置endpointCA引用一个包含 CA 证书包的 Secret使 Barman 能够正确校验证书。Secret 的创建方式可参考 certificates.md 文档中的示例。创建完成后按如下方式填充apiVersion: postgresql.cnpg.io/v1 kind: Cluster [...] spec: [...] backup: barmanObjectStore: endpointURL: myEndpointURL endpointCA: name: my-ca-secret key: ca.crt凭据热更新提示如果你希望实例自动重载ConfigMap 与 Secret 的变更可以给这些资源打上键为cnpg.io/reload的标签否则需要使用kubectl cnpg reload子命令手动触发实例重载。Azure Blob Storage五种认证方式Azure Blob Storage 是微软提供的对象存储服务。CloudNativePG 支持以下五种认证方法Connection String连接字符串Storage Account Name Storage Account Access Key存储账户访问密钥Storage Account Name Storage Account SAS Token共享访问签名Azure AD Managed Identity托管身份Default Azure Credentials默认 Azure 凭据流无密钥方案Azure AD Managed Identity 与 Default Azure Credentials使用Azure AD Managed Identity时可以完全避免把凭据保存到 Kubernetes Secret 中只需在集群配置中加入inheritFromAzureADapiVersion: postgresql.cnpg.io/v1 kind: Cluster [...] spec: backup: barmanObjectStore: destinationPath: destination path here azureCredentials: inheritFromAzureAD: true或者使用Default Azure Credentials认证机制它通过同时支持环境变量、托管身份、Azure CLI 凭据等多种认证途径提供无缝的认证体验。启用方式是在azureCredentials中加入useDefaultAzureCredentials标志apiVersion: postgresql.cnpg.io/v1 kind: Cluster [...] spec: backup: barmanObjectStore: destinationPath: destination path here azureCredentials: useDefaultAzureCredentials: true从 CRD 与源码api/v1/backup_types.go来看AzureCredentials要求 Connection String、storageKey需搭配storageAccount、storageSasToken需搭配storageAccount、inheritFromAzureAD、useDefaultAzureCredentials中只指定一个认证来源。密钥方案Storage Account Key / SAS Token使用存储账户访问密钥或 SAS Token 时凭据必须保存在 Kubernetes Secret 中并且只需按需添加对应的数据条目。创建命令如下kubectl create secret generic azure-creds \ --from-literalAZURE_STORAGE_ACCOUNTstorage account name \ --from-literalAZURE_STORAGE_KEYstorage account key \ --from-literalAZURE_STORAGE_SAS_TOKENSAS token \ --from-literalAZURE_STORAGE_CONNECTION_STRINGconnection string若集群启用了静态加密这些凭据在静态存储时也会被加密。基于上述 Secret可在集群配置中注入所需凭据apiVersion: postgresql.cnpg.io/v1 kind: Cluster [...] spec: backup: barmanObjectStore: destinationPath: destination path here azureCredentials: connectionString: name: azure-creds key: AZURE_CONNECTION_STRING storageAccount: name: azure-creds key: AZURE_STORAGE_ACCOUNT storageKey: name: azure-creds key: AZURE_STORAGE_KEY storageSasToken: name: azure-creds key: AZURE_STORAGE_SAS_TOKENdestinationPath 的结构使用 Azure Blob Storage 时destinationPath遵循如下结构http|https://account-name.service-name.core.windows.net/resource-path其中resource-path为container/blob**account name存储账户名**包含在主机名中。其他 Azure Blob Storage 兼容实现如果使用 Azure Blob Storage API 的其他实现destinationPath采用以下结构http|https://local-machine-address:port/account-name/resource-path此时account-name是路径的第一个组成部分。这在通过Azure Storage Emulator或Azurite本地测试 Azure 支持时是必需的仓库中的端到端测试 backup_restore_azurite_test.go 即基于 Azurite 验证该场景。Google Cloud Storage两种认证方式CloudNativePG 目前支持两种 Google Cloud Storage 认证方式假设 Pod 运行在 Google Kubernetes EngineGKE集群内部Workload Identity利用环境变量GOOGLE_APPLICATION_CREDENTIALS服务账号 JSON 文件。方式一GKE 环境Workload Identity运行在 GKE 内部时可以完全依赖 Workload Identity无需设置任何凭据。具体需要两步将.spec.backup.barmanObjectStore.googleCredentials.gkeEnvironment设为true在serviceAccountTemplate配置段中设置iam.gke.io/gcp-service-accountannotation。完整参考配置如下apiVersion: postgresql.cnpg.io/v1 kind: Cluster [...] spec: [...] backup: barmanObjectStore: destinationPath: gs://destination path here googleCredentials: gkeEnvironment: true serviceAccountTemplate: metadata: annotations: iam.gke.io/gcp-service-account: [...].iam.gserviceaccount.com [...]方式二应用凭据applicationCredentials按照 Google 的认证指引操作后你会得到一个包含全部认证信息的 JSON 文件。该 JSON 文件的内容必须通过Secret提供可使用以下命令创建kubectl create secret generic backup-creds --from-filegcsCredentialsgcs_credentials_file.json这会在集群中创建名为backup-creds的Secret然后在 YAML 中引用它apiVersion: postgresql.cnpg.io/v1 kind: Cluster [...] spec: backup: barmanObjectStore: destinationPath: gs://destination path here googleCredentials: applicationCredentials: name: backup-creds key: gcsCredentials此后操作者会使用这些凭据向 Google Cloud Storage 进行认证。安全提醒这种认证方式会在容器内创建一个包含访问 Google Cloud Storage bucket 全部所需信息的 JSON 文件。这意味着一旦有人获得了 Pod 的访问权限也就同时获得了对 bucket 的写入权限。请据此评估该方案在敏感环境中的适用性。源码视角barmanObjectStore 的完整配置结构与执行链路为了准确理解上述配置的语义可以对照 CRD 中spec.backup.barmanObjectStore的完整属性清单见 config/crd/bases/postgresql.cnpg.io_clusters.yaml属性说明destinationPath必填备份存储路径如s3://bucket/path/to/folderWAL 与数据会写入该路径下不同的子目录endpointURL覆盖自动端点发现的存储端点用于 S3 兼容存储endpointCA引用包含 CA bundle 的 Secretnamekey用于私有 CA 签发的 HTTPS 端点serverName对象存储中的服务名省略时使用集群名s3CredentialsaccessKeyId/secretAccessKey/sessionToken/region均为 Secret 引用或inheritFromIAMRoleazureCredentialsconnectionString/storageAccountstorageKey/storageAccountstorageSasToken/inheritFromAzureAD/useDefaultAzureCredentialsgoogleCredentialsapplicationCredentialsSecret 引用或gkeEnvironment: truedata基础备份配置compressiongzip/bzip2/lz4/snappy、encryptionAES256/aws:kms、immediateCheckpoint、jobs默认 2、additionalCommandArgs、restoreAdditionalCommandArgswalWAL 备份配置compression额外支持 xz/zstd、encryption、maxParallel≥1、archiveAdditionalCommandArgs、restoreAdditionalCommandArgstags传递给 Barman--tags的键值对标签作用于基础备份、WAL 文件historyTags传递给 Barman--history-tags的键值对标签作用于归档的 history 文件在运行时备份命令的执行链路位于 pkg/management/postgres/backup.goBackupCommand.Start首先校验 WAL 归档是否正常工作接着通过barmanCredentials.EnvSetBackupCloudCredentials从上述 Secret 引用中解析并注入环境变量凭据最后在独立 goroutine 中启动barman-cloud-backup。这解释了为何s3Credentials/azureCredentials中的每个字段都是一个SecretKeySelectornamekey它们本质上只是从哪个 Secret 的哪个键取值注入环境变量的声明式映射而真正的签名、校验与上传逻辑全部由 Barman Cloud 完成。配套能力速览WAL 归档、保留策略、压缩与恢复对象存储认证只是备份体系的一半。仓库中的姊妹文档 backup_barmanobjectstore.mdAppendix B系统阐述了配套能力核心要点如下WAL 归档归档由.spec.backup.barmanObjectStore定义默认archive_timeout为5min保证低负载场景下 WAL 至少每 5 分钟关闭并归档一次为 RPO 提供确定性的时间上限带宽充足时可用wal.maxParallel如 8并行归档多个就绪 WALPostgreSQL 请求归档已被实例管理器预先归档的 WAL 时该请求会被直接以成功状态丢弃。保留策略.spec.backup.retentionPolicy形如30d正则^[1-9][0-9]*[dwm]$即天/周/月驱动自动化删除内部通过barman-cloud-backup-delete --retention-policy RECOVERY WINDOW OF ...实现基于可恢复点PoR 当前时间 - 恢复窗口的滑动窗口模型首个有效备份之前的旧基础备份会被标记为 obsolete 并在下一个备份完成后永久删除。压缩算法备份与 WAL 默认不压缩支持 bzip2、gzip、lz4、snappy、xz、zstd归档时间、恢复时间与体积各有取舍例如相同数据量下无压缩约 395 MB、gzip 压缩至约 91 MB、snappy 压缩至约 166 MB需结合场景选择。备份对象标签Barman 2.18 支持通过tags与historyTags为对象存储中的基础备份、WAL 文件与 history 文件打标签如backupRetentionPolicy: expire便于按标签做生命周期管理。扩展命令参数可通过data.additionalCommandArgsbarman-cloud-backup、data.restoreAdditionalCommandArgsbarman-cloud-restore、wal.archiveAdditionalCommandArgsbarman-cloud-wal-archive、wal.restoreAdditionalCommandArgsbarman-cloud-wal-restore追加参数例如--read-timeout60、--min-chunk-size5MB若参数与该段已声明选项冲突用户提供的值会被忽略。注意恢复参数取自.spec.bootstrap.recovery.source对应的外部集群externalClusters中的barmanObjectStore。从对象存储恢复通过externalClusters定义外部集群并填充barmanObjectStore再由.spec.bootstrap.recovery.source引用即可从 S3/Azure/GCS 恢复serverName用于指定对象存储中的备份主目录名默认取外部集群name恢复细节可参见 recovery.md。小结与最佳实践围绕 CloudNativePG 的对象存储备份可沉淀出以下实践要点先建 bucket后建 ClusterBarman Cloud 3.16 不再自动建桶务必提前创建并配置好存储桶及权限。优先无密钥方案EKS 用 IRSA、GKE 用 Workload Identity、Azure 用 Managed Identity 或 Default Azure Credentials可避免静态凭据落盘与轮换成本静态凭据则统一放入 Secret并借助集群静态加密保护。兼容实现善用endpointURL与endpointCAMinIO、Linode、Digital Ocean Spaces、Azurite 等均通过端点覆盖实现接入私有 CA 场景需配套endpointCA。凭据变更热更新为凭据 Secret 打上cnpg.io/reload标签即可自动重载否则手动执行kubectl cnpg reload。组合使用保留策略、压缩与标签让备份体系具备自清理能力并配合 S3 生命周期策略形成双重防线为 PoR 恢复窗口提供确定性保障。【免费下载链接】cloudnative-pgThe most popular Kubernetes Operator for PostgreSQL.项目地址: https://gitcode.com/GitHub_Trending/cl/cloudnative-pg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考