Secret Manager Python 示例速查:从项目初始化到密钥全生命周期管理(python-docs-samples 实战指南)

原创2026-10-05 10:06:571,885 阅读
文章标签:示例工程

Secret Manager Python 示例速查:从项目初始化到密钥全生命周期管理(python-docs-samples 实战指南)

导读

本文基于 python-docs-samples 仓库中的 secretmanager/README.md 及其配套的数十个 Python 代码片段,完整梳理 Google Cloud Secret Manager 的接入流程、核心 API 调用方式与最佳实践。读者将掌握:如何完成项目、计费、API 与认证的四大前置准备,如何使用 google-cloud-secret-manager 客户端创建密钥、添加版本、访问明文、配置标签/注解/TTL/延迟销毁,以及如何通过 IAM 授权、事件通知与区域级密钥(Regional Secret)实现生产级密钥管理。


一、前置准备:四个必做步骤

运行仓库中任何 Secret Manager 示例前,都需要按 README 指引依次完成以下初始化步骤,这也是所有 Google Cloud Python 示例(google-api-core 认证体系)的通用前提:

  1. 创建或选择一个 Google Cloud 项目:在 Cloud Console 中创建项目,或复用已有项目,记录下 PROJECT_ID。仓库所有脚本均以 projects/{project_id} 作为资源命名空间。
  2. 为项目启用结算(Billing):Secret Manager 属于计费服务,未启用结算时 API 调用会失败。
  3. 启用 Secret Manager API:在 Cloud Console 的 API 库中启用 Secret Manager API。这是调用 SecretManagerServiceClient 的前置条件,未启用时会返回 403 Permission Denied。
  4. 配置认证(Authentication):设置环境变量 GOOGLE_APPLICATION_CREDENTIALS 指向服务账号 JSON 密钥文件,或在本地通过 gcloud auth application-default login 建立 ADC(Application Default Credentials)。认证细节可参考 google-api-core 的 auth 文档。

完成以上步骤后,安装依赖即可开始运行示例。仓库 secretmanager/snippets/requirements.txt 明确锁定了客户端版本,建议按此安装以保证 API 行为一致:

protobuf==6.33.6
google-cloud-resource-manager==1.18.0
google-cloud-secret-manager==2.29.0
google-crc32c==1.8.0

其中 google-crc32c 用于计算与校验载荷校验和,google-cloud-resource-manager 用于标签(Tag)相关示例。


二、一分钟上手:创建并读取第一个密钥

quickstart.py 演示了最核心的三步流程:创建 Secret → 添加 Version → 读取明文。完整代码如下(secretmanager_quickstart 代码块):

from google.cloud import secretmanager

project_id = "YOUR_PROJECT_ID"
secret_id = "YOUR_SECRET_ID"

# 创建客户端
client = secretmanager.SecretManagerServiceClient()

# 构造父资源名
parent = f"projects/{project_id}"

# 创建 Secret(采用自动复制策略)
secret = client.create_secret(
    request={
        "parent": parent,
        "secret_id": secret_id,
        "secret": {"replication": {"automatic": {}}},
    }
)

# 添加第一个版本
version = client.add_secret_version(
    request={"parent": secret.name, "payload": {"data": b"hello world!"}}
)

# 访问该版本
response = client.access_secret_version(request={"name": version.name})

# 解码明文并打印
payload = response.payload.data.decode("UTF-8")
print(f"Plaintext: {payload}")

关键点解读:

  • replication: {"automatic": {}} 表示采用 Google 自动管理的多区域复制策略(默认行为);若需指定区域,可改用 user_managed(详见下文)。
  • Secret 是"容器",Version 才是"内容":create_secret 只创建逻辑包装,真正的敏感数据由 add_secret_version 写入,二者必须配合使用。
  • 源码中特别注释了警告:生产环境严禁打印密钥明文,示例中 print(f"Plaintext: {payload}") 仅用于演示如何取回密钥材料。

从测试 snippets_test.py 的 test_quickstart 可见,其验证逻辑是直接调用 quickstart(project_id, secret_id),并通过 fixture 自动创建、清理测试密钥,说明该流程在真实项目中可端到端跑通。


三、密钥的生命周期管理:创建、更新、删除与版本控制

3.1 创建 Secret(含 TTL 参数)

create_secret.py 支持可选的 ttl 参数,用于为密钥设置存活时间(Time-to-Live):

def create_secret(project_id: str, secret_id: str, ttl: Optional[str] = None) -> secretmanager.Secret:
    client = secretmanager.SecretManagerServiceClient()
    parent = f"projects/{project_id}"
    response = client.create_secret(
        request={
            "parent": parent,
            "secret_id": secret_id,
            "secret": {"replication": {"automatic": {}}, "ttl": ttl},
        }
    )
    print(f"Created secret: {response.name}")
    return response

命令行运行方式(所有示例脚本均内置 argparse 参数解析):

python create_secret.py YOUR_PROJECT_ID YOUR_SECRET_ID
python create_secret.py YOUR_PROJECT_ID YOUR_SECRET_ID --ttl 7776000s   # 30 天 TTL

ttl 采用 ISO 8601 时长格式(如 "900s" 表示 15 分钟、"7776000s" 表示 30 天)。测试 snippets_test.py 的 test_create_secret 使用 ttl="300s" 并断言 secret.expire_time 存在;而 test_create_secret_without_ttl 传入 None 并断言 not secret.expire_time,验证了 TTL 参数的真实生效行为。TTL 到期后,密钥内所有版本会被自动删除。

3.2 添加与访问 Secret Version(含数据完整性校验)

add_secret_version.py 展示了两点最佳实践:UTF-8 编码转换与 CRC32C 校验和:

from google.cloud import secretmanager
import google_crc32c

def add_secret_version(project_id: str, secret_id: str, payload: str) -> secretmanager.SecretVersion:
    client = secretmanager.SecretManagerServiceClient()
    parent = client.secret_path(project_id, secret_id)

    # 字符串载荷转 bytes
    payload_bytes = payload.encode("UTF-8")

    # 计算 CRC32C 校验和(可选但推荐)
    crc32c = google_crc32c.Checksum()
    crc32c.update(payload_bytes)

    response = client.add_secret_version(
        request={
            "parent": parent,
            "payload": {
                "data": payload_bytes,
                "data_crc32c": int(crc32c.hexdigest(), 16),
            },
        }
    )
    print(f"Added secret version: {response.name}")
    return response

对应地,access_secret_version.py 在读取时验证校验和,用于检测数据传输过程中的损坏:

def access_secret_version(project_id: str, secret_id: str, version_id: str):
    client = secretmanager.SecretManagerServiceClient()
    # version_id 可以是数字版本号(如 "5")或别名(如 "latest")
    name = f"projects/{project_id}/secrets/{secret_id}/versions/{version_id}"
    response = client.access_secret_version(request={"name": name})

    crc32c = google_crc32c.Checksum()
    crc32c.update(response.payload.data)
    if response.payload.data_crc32c != int(crc32c.hexdigest(), 16):
        print("Data corruption detected.")
        return response

    payload = response.payload.data.decode("UTF-8")
    print(f"Plaintext: {payload}")
    return response

运行:

python add_secret_version.py YOUR_PROJECT_ID YOUR_SECRET_ID "my-secret-payload"
python access_secret_version.py YOUR_PROJECT_ID YOUR_SECRET_ID latest

测试 test_access_secret_version 断言 version.payload.data == b"hello world!",直接验证了写入与读取闭环的正确性。

3.3 版本状态管理:启用、禁用与销毁

仓库提供了一整套版本状态操作示例,对应 SecretVersion 的 ENABLED / DISABLED / DESTROYED 状态机:

操作 脚本 说明
禁用版本 disable_secret_version.py 将版本置为 DISABLED,禁止访问
启用版本 enable_secret_version.py 将版本恢复为 ENABLED
销毁版本 destroy_secret_version.py 彻底删除版本数据,不可恢复
带 ETag 并发控制 disable_secret_version_with_etag.py、enable_secret_version_with_etag.py、destroy_secret_version_with_etag.py 通过乐观锁避免并发覆盖

测试 snippets_test.py 的 test_enable_disable_secret_version 断言禁用后 version.state == secretmanager.SecretVersion.State.DISABLED、启用后回到 ENABLED,test_destroy_secret_version 断言 version.destroy_time 被填充。

3.4 查询与过滤:列出 Secrets 和 Versions

仓库提供 list_secrets.py、list_secrets_with_filter.py、list_secret_versions.py、list_secret_versions_with_filter.py 四个查询脚本。过滤语法示例:

  • 按版本状态过滤:list_secret_versions_with_filter(project_id, secret_id, "state:ENABLED")
  • 按标签过滤:list_secrets_with_filter(project_id, "labels.secretmanager:rocks")

测试 test_list_secret_versions_with_filter 验证了"启用版本的名称出现在输出、禁用版本不出现在输出"的行为;test_list_secrets_with_filter 则演示了先给密钥打上 secretmanager:rocks 标签后再过滤能命中的完整链路。


四、元数据管理:标签、注解、别名与高级配置

Secret 支持丰富的元数据,仓库均有对应示例脚本:

从测试 fixture 可以看到这些特性的典型组合用法(snippets_test.py 的 secret fixture):

secret = retry_client_create_secret(
    client,
    request={
        "parent": parent,
        "secret_id": secret_id,
        "secret": {
            "replication": {"automatic": {}},
            "ttl": ttl,
            "labels": {label_key: label_value},
            "annotations": {annotation_key: annotation_value},
        },
    },
)

测试还专门封装了 retry_client_* 系列函数并注释 # Retry to avoid 503 error & flaky issues,提示真实项目中应使用重试策略应对瞬时故障。


五、访问控制:IAM 授权与撤销

iam_grant_access.py 与 iam_revoke_access.py 演示如何为服务账号授予/撤销密钥访问权限:

python iam_grant_access.py YOUR_PROJECT_ID YOUR_SECRET_ID serviceAccount:your-sa@project.iam.gserviceaccount.com
python iam_revoke_access.py YOUR_PROJECT_ID YOUR_SECRET_ID serviceAccount:your-sa@project.iam.gserviceaccount.com

测试通过环境变量 GCLOUD_SECRETS_SERVICE_ACCOUNT 读取被授权账号(fixture iam_user 统一拼接为 serviceAccount: 前缀),并断言授权后 any(iam_user in b.members for b in policy.bindings) 成立、撤销后不成立。注意:被授权账号需已具备对应 IAM 角色(如 roles/secretmanager.secretAccessor),且自身有权限读取密钥。


六、事件通知:消费 Pub/Sub 变更消息

consume_event_notification.py 展示如何编写 Cloud Function 消费 Secret Manager 的 Pub/Sub 事件通知:

import base64

def consume_event_notification(event: dict, unused_context: None) -> str:
    event_type = event["attributes"]["eventType"]
    secret_id = event["attributes"]["secretId"]
    secret_metadata = base64.b64decode(event["data"]).decode("utf-8")
    event_notification = (
        f"Received {event_type} for {secret_id}. New metadata: {secret_metadata}"
    )
    print(event_notification)
    return event_notification

事件载荷结构为 {attributes: {eventType, secretId}, data: base64编码的元数据}。测试构造的事件包含 eventType: "SECRET_UPDATE" 和 secretId: "projects/p/secrets/s",并断言返回 "Received SECRET_UPDATE for projects/p/secrets/s. New metadata: hello!"。这适用于密钥变更审计、自动轮转等场景。


七、区域级密钥(Regional Secret):多区域合规场景

自 2024 年起,仓库新增 regional_samples 目录,覆盖区域级密钥的完整操作,包括:create_regional_secret.py、access_regional_secret_version.py、regional_quickstart.py 等 30 余个脚本,功能与全局级一一对应(标签、注解、ETag、IAM、延迟销毁等)。

与全局级密钥的关键区别在于两点(见 regional_quickstart.py):

  1. 自定义 API Endpoint:区域级服务通过 secretmanager.{location_id}.rep.googleapis.com 访问;
  2. 父资源带区域:parent = f"projects/{project_id}/locations/{location_id}"。
api_endpoint = f"secretmanager.{location_id}.rep.googleapis.com"
client = secretmanager_v1.SecretManagerServiceClient(
    client_options={"api_endpoint": api_endpoint},
)
parent = f"projects/{project_id}/locations/{location_id}"

区域级密钥适合有数据驻留(Data Residency)合规要求的场景,例如需要将密钥严格限制在特定地理区域。


八、运行与测试:在本地跑通全部示例

8.1 环境与依赖

# 1. 安装依赖(以 snippets 目录为准)
cd secretmanager/snippets
pip install -r requirements.txt

# 2. 设置认证与项目
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

8.2 测试配置说明

仓库为每个示例目录提供 noxfile_config.py,其中 secretmanager/snippets/noxfile_config.py 的关键配置:

  • "ignored_versions":跳过 Python 3.8/3.9/3.11/3.12/3.13,只保留受支持的版本矩阵;
  • "enforce_type_hints": True:新示例强制要求类型注解(符合仓库对所有新样本的规范);
  • "gcloud_project_env": "GOOGLE_CLOUD_PROJECT":指定测试使用的项目 ID 环境变量。

测试依赖见 requirements-test.txt(pytest==9.0.3),测试运行需 GOOGLE_CLOUD_PROJECT 环境变量(见 project_id fixture),部分测试还需 GCLOUD_SECRETS_SERVICE_ACCOUNT。运行方式:

pip install -r requirements-test.txt
pytest

测试会真实调用 Secret Manager API,并通过 fixture 自动创建、清理测试资源(如 python-secret-{uuid4} 命名的密钥),因此建议在独立测试项目或已隔离的项目中执行。


九、仓库结构与后续深入方向

secretmanager 目录整体结构如下:

进一步深入学习时,可对照仓库中以下实现细节:测试文件 snippets_test.py 中 tag_key_and_tag_value fixture 演示了如何在测试中创建/清理 Cloud Resource Manager 的 Tag Key 与 Tag Value;secret_version fixture 展示了 version.name.rsplit("/", 1)[-1] 提取版本号的惯用写法。将示例与测试对照阅读,是掌握 Secret Manager Python API 行为的最快路径。


结语

从 secretmanager/README.md 的四步前置准备出发,python-docs-samples 仓库提供了覆盖 Secret Manager 全生命周期的可运行 Python 代码:快速上手、版本控制、元数据管理、IAM 授权、事件通知与区域级密钥。这些示例既是学习 API 的最佳教材,也可直接改造为生产代码——只需牢记两个底线:生产环境绝不打印密钥明文,以及善用 CRC32C 校验和与 ETag 并发控制来保障数据安全。

登录后查看全文
python-docs-samples