Cloud Custodian OCI 日志输出实战:对象存储归档与 OCI Logging 服务的完整配置
Cloud Custodian OCI 日志输出实战:对象存储归档与 OCI Logging 服务的完整配置
本文围绕 Cloud Custodian 的 OCI(Oracle Cloud Infrastructure)Provider 讲清两件事:如何用 -s oci://<Bucket_Name>/<Optional_Prefix_Name>/ 把策略运行日志与资源记录归档到 Object Storage,如何用 --log-group=oci://<log_group_name> 把运行日志实时推送到 OCI Logging Service,包括 compartment ID 的两种指定方式、profile 查询参数、桶/日志组不存在时的报错行为。读完本文,你不仅能直接复制命令落地配置,还能对照 c7n_oci 的源码理解输出目录的拼接规则、日志组自动创建逻辑与鉴权会话的解析过程。
输出机制总览:oci:// 协议背后的注册机制
Cloud Custodian 的输出(output)体系按用途划分为多个插件注册表:对象存储类结果文件走 blob_outputs,运行日志走 log_outputs。OCI Provider 在这两个注册表上都以 "oci" 为协议名注册了实现类,这正是命令行中 oci:// 前缀能同时被 -s(storage)和 --log-group(log group)识别的原因:
- OCIObjectStorageOutput:
@blob_outputs.register("oci"),负责把本地临时目录里的结果文件上传到 Object Storage 桶; - OCILogOutput:
@log_outputs.register("oci"),负责把策略执行的日志接入 OCI Logging Service。
URL 的解析复用核心框架 c7n/output.py 中的 BlobOutput 与 LogOutput 基类:netloc(主机部分)被识别为桶名或日志组名,path 作为 key 前缀,?key=value 查询参数(如 profile、OCI_LOG_COMPARTMENT_ID)进入 config 字典供子类消费。
把日志和资源记录写入 Object Storage
文档 logging.rst 给出的基本用法是:
custodian run -s oci://<Bucket_Name>/<Optional_Prefix_Name>/ <policy file>
执行结束后,Custodian 会把策略运行日志和资源记录(policy logs / resource records)上传到该桶。有几点需要明确:
1. 对象 key 的命名规则:策略名 + 日期自动拼接前缀。
如果 -s 后没有 {...} 格式化占位符,核心基类 BlobOutput.get_output_path 会把输出路径拼接为 <output_url>/<policy_name>/<UTC的YYYY/MM/DD/HH>,即“策略名 + 日期”自动成为对象前缀。OCI 子类在此基础上再叠加 URL 中已有的 <Optional_Prefix_Name> 路径段,最终对象 key 形如:
<Optional_Prefix_Name>/<policy_name>/2026/10/09/14/custodian-run.json.gz
2. 上传过程与桶存在性校验。
OCIObjectStorageOutput.upload_file 采用惰性初始化:首次上传时才创建 ObjectStorageClient,先通过 get_namespace() 解析租户命名空间,再用 head_bucket() 校验目标桶:
- 桶不存在(404):抛出
ValueError: The bucket <name> does not exist.—— 这就是文档中“bucket must already exist otherwise an error will be thrown”的出处,Custodian 不会替你自动建桶; - 其他连接错误:抛出
ValueError: Unable to connect to the bucket ...。
上传前 BlobOutput.__exit__ 还会先对临时目录中的文件逐个 gzip 压缩(compress),再遍历本地临时目录逐个 put_object,因此最终桶里看到的是压缩后的 .gz 对象。
3. 跨 profile 投递:profile 查询参数。
要把数据写到另一个 OCI CLI profile 对应的桶,可以在 URL 上加查询参数:
custodian run -s oci://<Bucket_Name>/<Optional_Prefix_Name>/?profile=<NAME> <policy file>
OCIObjectStorageOutput 构造时通过 SessionFactory(profile=self.config.get(PROFILE))() 把 profile 传入会话工厂(constants.py 中 PROFILE = "profile")。SessionFactory 的凭证解析优先级为:
- 若
OCI_CLI_AUTH=instance_principal,使用实例主体(Instance Principal)签名器,无需本地配置文件; - 否则若
OCI_FINGERPRINT、OCI_KEY_FILE、OCI_REGION、OCI_TENANCY、OCI_USER五个环境变量齐备,直接以环境变量构造配置; - 否则若有
profile参数,调用oci.config.from_file(profile_name=...)读取该 profile; - 最终回落到默认 profile
oci.config.from_file()。
把日志发送到 OCI Logging Service
除了对象存储归档,Custodian 还支持把策略运行日志直接写入 OCI Logging Service。使用前提是告知 Custodian 日志要发送到的 compartment ID,文档提供了两种等效方式:
方式一:作为查询参数 OCI_LOG_COMPARTMENT_ID 传入。
custodian run --output-dir . --log-group=oci://custodian-test?OCI_LOG_COMPARTMENT_ID=ocid1.test.oc1..<unique_ID>EXAMPLE-compartmentId-Value <policy file>
方式二:设置环境变量 OCI_LOG_COMPARTMENT_ID。
export OCI_LOG_COMPARTMENT_ID=ocid1.test.oc1..<unique_ID>EXAMPLE-compartmentId-Value
custodian run --output-dir . --log-group=oci://custodian-test <policy file>
源码 OCILogOutput.get_handler 明确了优先级:查询参数优先于环境变量——先取 self.config.get(OCI_LOG_COMPARTMENT_ID),取不到再查 os.environ.get(OCI_LOG_COMPARTMENT_ID),两者都缺则抛出 ValueError,提示必须通过 query param 或 environment variable 提供。
上面两条命令的效果是:创建一个名为 custodian-test 的日志组(log group),并把日志推送到其中的一个日志流(log)。日志流名与策略名相同(OCILogOutput.init 中 self.log_stream = ctx.policy.data['name'],取不到时回退为 DEFAULT)。日志保留期使用 OCI 的默认值(创建时未显式指定 retention,与文档“log retention period will be the default value”一致)。
跨 profile 推送日志: 与对象存储一样支持 profile 查询参数:
export OCI_LOG_COMPARTMENT_ID=ocid1.test.oc1..<unique_ID>EXAMPLE-compartmentId-Value
custodian run --output-dir . --log-group=oci://custodian-test?profile=<NAME> <policy file>
OCILogOutput 构造时 SessionFactory(profile=self.config.get(PROFILE)) 会把该 profile 用于后续所有 Logging Management / Logging Ingestion API 调用。
源码级原理:日志组与日志流的自动创建
真正干活的是 OCILogHandler,它是一个 logging.Handler,由 OCILogOutput.get_handler() 返回后挂到 custodian logger 上。其初始化流程 init_oci_logging 按以下顺序执行:
- 创建
LoggingManagementClient(管理面:建组/建日志)与LoggingClient(数据面:put_logs投递)两个客户端; - 日志组:用
list_log_groups(compartment_id, display_name=<log_group>)按名查找。- 不存在 → 调用
create_log_group_and_wait_for_state,以description="Cloud Custodian Logs"创建并等待到达SUCCEEDED状态(create_log_group); - 存在但
lifecycle_state不是ACTIVE→ 抛出ValueError: Log group <name> is not ACTIVE;
- 不存在 → 调用
- 日志流:用
list_logs(log_group_id, display_name=<log_stream>)按名查找,不存在则create_log_and_wait_for_state创建,参数为log_type="CUSTOM"、is_enabled=True(create_log);同样对非 ACTIVE 状态直接报错。
日志投递发生在 emit:首条日志触发懒初始化(log_stream_id 为空时先跑 init_oci_logging),随后每条日志以 OCI 结构化日志规范(CloudEvents 风格,携带 specversion)调用 put_logs,其中 source 固定为 "Cloud-Custodian"、type 为日志级别名(DEBUG/INFO/ERROR…),每条日志条目带独立 UUID 与时间戳(emit)。日志行格式由 OCILogOutput.log_format 定义为 '%(asctime)s - %(levelname)s - %(name)s - %(message)s'。
需要注意的异常边界:所有 OCI API 的 ServiceError 会被包装成 ValueError: Unable to instantiate OCI logging handler: ... 抛出;投递过程中的异常则记录 log.exception 后吞掉,不会中断策略执行——即 Logging Service 侧故障最多丢日志,不会让 custodian run 失败。这些行为在测试 test_output.py 中有对应断言,例如非 ACTIVE 日志流的用例直接 pytest.raises(ValueError, match=r'Log stream [^\s]+ is not ACTIVE'),缺失桶的用例验证了 404 场景。
适用前提与注意事项
- 对象存储路径要求桶已存在,且当前凭证对桶具备读写权限;策略名+时间戳前缀由框架自动追加,
<Optional_Prefix_Name>可省略。 - Logging Service 路径必须提供 compartment ID(查询参数或环境变量二选一),且当前 profile/凭证要有该 compartment 下创建日志组、日志流与投递日志的权限;compartment ID 形如
ocid1.compartment.oc1...。 - 日志组/日志流按显示名幂等查找:同名且 ACTIVE 则复用,不存在则自动创建;非 ACTIVE 同名资源会直接报错而非重建。
- 鉴权依赖标准 OCI CLI 配置文件(
~/.oci/config)的 profile 机制、五要素环境变量或OCI_CLI_AUTH=instance_principal实例主体,三者按 SessionFactory 的优先级生效。 - 参考文档 docs/source/oci/advanced/logging.rst;核心实现见 tools/c7n_oci/c7n_oci/output.py、tools/c7n_oci/c7n_oci/log.py、tools/c7n_oci/c7n_oci/session.py。