Secret Manager Python 示例速查:从项目初始化到密钥全生命周期管理(python-docs-samples 实战指南)
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 认证体系)的通用前提:
- 创建或选择一个 Google Cloud 项目:在 Cloud Console 中创建项目,或复用已有项目,记录下
PROJECT_ID。仓库所有脚本均以projects/{project_id}作为资源命名空间。 - 为项目启用结算(Billing):Secret Manager 属于计费服务,未启用结算时 API 调用会失败。
- 启用 Secret Manager API:在 Cloud Console 的 API 库中启用
Secret Manager API。这是调用SecretManagerServiceClient的前置条件,未启用时会返回403 Permission Denied。 - 配置认证(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 支持丰富的元数据,仓库均有对应示例脚本:
- 标签(Labels):键值对,可用于过滤与成本归集。创建见 create_secret_with_labels.py,查看见 view_secret_labels.py,新增/更新见 create_update_secret_label.py,删除见 delete_secret_label.py。
- 注解(Annotations):与标签类似的键值元数据,但不可用于过滤。对应 create_secret_with_annotations.py、view_secret_annotations.py、edit_secret_annotations.py、delete_secret_annotation.py。
- 版本别名(Alias):为版本赋予语义化名称,见 update_secret_with_alias.py,测试断言
secret.version_aliases["test"] == 1。 - 延迟销毁(Delayed Destroy):为版本设置销毁宽限期,防止误删,见 create_secret_with_delayed_destroy.py(测试用 7 天即 604800 秒)、update_secret_with_delayed_destroy.py、disable_secret_with_delayed_destroy.py。测试断言
timedelta(seconds=version_destroy_ttl) == secret.version_destroy_ttl,验证 TTL 值被精确持久化。 - ETag 并发保护:删除/更新时携带 etag,避免并发修改,见 delete_secret_with_etag.py、update_secret_with_etag.py。
- 资源标签(Tags):基于 Cloud Resource Manager 的层级标签体系,创建见 create_secret_with_tags.py,绑定见 bind_tags_to_secret.py,删除 Secret 见 delete_secret.py。
从测试 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):
- 自定义 API Endpoint:区域级服务通过
secretmanager.{location_id}.rep.googleapis.com访问; - 父资源带区域:
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 目录整体结构如下:
- secretmanager/README.md:本文所依据的官方 Quick Start 文档;
- secretmanager/snippets/:全局级密钥全部示例(40+ 脚本)+ 测试 + nox 配置;
- secretmanager/snippets/regional_samples/:区域级密钥示例(30+ 脚本);
- secretmanager/snippets-adk/:面向 Agent Development Kit 的示例(
agent_global/与agent_regional/两个 agent 目录)。
进一步深入学习时,可对照仓库中以下实现细节:测试文件 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 并发控制来保障数据安全。