Sealed Secrets API 接口详解与技术实践

项目概述

Sealed Secrets 是一个 Kubernetes 控制器，它提供了一种安全的方式来管理 Kubernetes 集群中的敏感信息。其核心思想是通过"单向"加密机制，允许任何人创建加密的 Secret（称为 SealedSecret），但只有目标集群中运行的控制器能够解密，恢复出原始的 Secret 对象。

API 架构与版本

Sealed Secrets 控制器提供了 RESTful API 接口，基于 OpenAPI 3.0.3 规范构建。当前文档描述的 API 版本为 0.17.3，基础路径为 /v1。

核心 API 端点解析

1. 获取公钥证书

端点: GET /cert.pem

功能: 获取用于签署 Sealed Secrets 的公钥证书

响应格式: PEM 格式的证书文件

状态码:

• 200: 成功获取证书
• 500: 服务器内部错误

技术要点:

• 该证书用于客户端加密 Secret 数据
• 证书采用 x509 标准格式
• 每个集群的证书是唯一的，确保加密数据只能被目标集群解密

2. 验证 Sealed Secrets 对象

端点: POST /verify

功能: 验证 Sealed Secrets 对象的有效性

请求体: SealedSecret 对象（JSON 格式）

状态码:

• 200: 验证通过
• 400: 请求格式错误
• 409: 验证冲突（如命名空间不匹配等）
• 500: 服务器内部错误

技术实践建议:

• 在 CI/CD 流程中集成此验证步骤
• 验证内容包括但不限于：API 版本兼容性、命名空间有效性、加密数据格式等

3. 重新加密 Sealed Secrets 对象

端点: POST /rotate

功能: 对 Sealed Secrets 对象进行重新加密

请求体: SealedSecret 对象（JSON 格式）

响应: 重新加密后的 SealedSecret 对象（JSON 格式）

状态码:

• 200: 重新加密成功
• 400: 请求格式错误
• 409: 加密冲突
• 500: 服务器内部错误

使用场景:

• 密钥轮换后更新现有的 SealedSecret
• 迁移到新集群时重新加密数据
• 加密策略变更后的批量更新

数据结构详解

SealedSecret 对象结构

apiVersion: bitnami.com/v1alpha1  # API 版本
kind: SealedSecret                # 资源类型
metadata:                         # 元数据
  name: string                    # 资源名称
  namespace: string               # 命名空间
  creationTimestamp: string       # 创建时间戳
spec:                             # 规格定义
  encryptedData: object           # 加密数据
  template:                       # 模板定义
    metadata: object              # 模板元数据
    data: string                  # 模板数据

关键字段说明

1. encryptedData:

   • 类型: 键值对对象
   • 内容: 实际加密后的敏感数据
   • 加密方式: 使用控制器的公钥进行非对称加密

2. template:

   • 用于定义解密后生成的 Secret 的元数据和结构
   • metadata 可以覆盖 SealedSecret 的元数据
   • data 字段定义了 Secret 的基本结构

安全最佳实践

1. 密钥管理:

   • 定期轮换控制器密钥
   • 备份私钥以确保灾难恢复能力
   • 限制对 /cert.pem 端点的访问

2. 访问控制:

   • 使用 Kubernetes RBAC 限制对控制器的访问
   • 在网络层面限制 API 端点的访问范围

3. 审计与监控:

   • 记录所有 API 调用
   • 监控异常的验证或重新加密请求

开发集成指南

客户端实现要点

1. 加密流程:

   • 获取目标集群的公钥证书
   • 使用证书加密敏感数据
   • 构建 SealedSecret 对象
   • 可选步骤：通过 /verify 端点验证对象有效性

2. 错误处理:

   • 处理证书获取失败情况
   • 优雅处理加密/解密错误
   • 实现重试逻辑应对临时性故障

3. 性能考虑:

   • 缓存公钥证书减少网络请求
   • 批量处理多个 Secret 的加密/解密
   • 异步处理长时间运行的操作

常见问题解决方案

1. 证书过期:

   • 通过控制器日志确认证书状态
   • 触发密钥轮换流程
   • 更新所有依赖的 SealedSecret

2. 验证失败:

   • 检查 API 版本兼容性
   • 确认命名空间策略
   • 验证加密数据的完整性

3. 性能瓶颈:

   • 监控 API 响应时间
   • 考虑水平扩展控制器实例
   • 优化客户端请求频率

通过深入理解 Sealed Secrets 的 API 设计和实现原理，开发者可以更安全、高效地在 Kubernetes 环境中管理敏感信息，同时构建可靠的自动化流程。