Cloud Custodian OCI 日志输出实战:对象存储归档与 OCI Logging 服务的完整配置

原创2026-10-09 13:18:411,613 阅读
文章标签:云原生运维安全

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 的凭证解析优先级为:

  1. 若 OCI_CLI_AUTH=instance_principal,使用实例主体(Instance Principal)签名器,无需本地配置文件;
  2. 否则若 OCI_FINGERPRINT、OCI_KEY_FILE、OCI_REGION、OCI_TENANCY、OCI_USER 五个环境变量齐备,直接以环境变量构造配置;
  3. 否则若有 profile 参数,调用 oci.config.from_file(profile_name=...) 读取该 profile;
  4. 最终回落到默认 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 按以下顺序执行:

  1. 创建 LoggingManagementClient(管理面:建组/建日志)与 LoggingClient(数据面:put_logs 投递)两个客户端;
  2. 日志组:用 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;
  3. 日志流:用 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。
登录后查看全文
cloud-custodian