第 4 章 Reports

以下报告示例将包含每个 Pod 的 CPU 请求信息，将每小时运行一次，每次运行时均会添加最后几小时的数据。

apiVersion: metering.openshift.io/v1
kind: Report
metadata:
  name: pod-cpu-request-hourly
spec:
  query: "pod-cpu-request"
  reportingStart: "2019-07-01T00:00:00Z"
  schedule:
    period: "hourly"
    hourly:
      minute: 0
      second: 0

以下报告示例将包含 7 月份所有 Pod 的 CPU 请求信息。完成后，便不会再运行。

apiVersion: metering.openshift.io/v1
kind: Report
metadata:
  name: pod-cpu-request-hourly
spec:
  query: "pod-cpu-request"
  reportingStart: "2019-07-01T00:00:00Z"
  reportingEnd: "2019-07-31T00:00:00Z"

ReportQuery 用于生成报告的名称。报告查询会控制报告的架构以及结果的处理方式。

query 为必填字段。

使用 oc CLI 获取可用 ReportQuery 对象列表：

$ oc -n openshift-metering get reportqueries
NAME                                         AGE
cluster-cpu-capacity                         23m
cluster-cpu-capacity-raw                     23m
cluster-cpu-usage                            23m
cluster-cpu-usage-raw                        23m
cluster-cpu-utilization                      23m
cluster-memory-capacity                      23m
cluster-memory-capacity-raw                  23m
cluster-memory-usage                         23m
cluster-memory-usage-raw                     23m
cluster-memory-utilization                   23m
cluster-persistentvolumeclaim-request        23m
namespace-cpu-request                        23m
namespace-cpu-usage                          23m
namespace-cpu-utilization                    23m
namespace-memory-request                     23m
namespace-memory-usage                       23m
namespace-memory-utilization                 23m
namespace-persistentvolumeclaim-request      23m
namespace-persistentvolumeclaim-usage        23m
node-cpu-allocatable                         23m
node-cpu-allocatable-raw                     23m
node-cpu-capacity                            23m
node-cpu-capacity-raw                        23m
node-cpu-utilization                         23m
node-memory-allocatable                      23m
node-memory-allocatable-raw                  23m
node-memory-capacity                         23m
node-memory-capacity-raw                     23m
node-memory-utilization                      23m
persistentvolumeclaim-capacity               23m
persistentvolumeclaim-capacity-raw           23m
persistentvolumeclaim-phase-raw              23m
persistentvolumeclaim-request                23m
persistentvolumeclaim-request-raw            23m
persistentvolumeclaim-usage                  23m
persistentvolumeclaim-usage-raw              23m
persistentvolumeclaim-usage-with-phase-raw   23m
pod-cpu-request                              23m
pod-cpu-request-raw                          23m
pod-cpu-usage                                23m
pod-cpu-usage-raw                            23m
pod-memory-request                           23m
pod-memory-request-raw                       23m
pod-memory-usage                             23m
pod-memory-usage-raw                         23m

带有 -raw 后缀的 ReportQueries 会被其他 ReportQueries 用于构建更为复杂的查询，而不该直接用于报告。

带有 namespace- 前缀的查询会按命名空间聚合 Pod CPU/内存请求，根据资源请求提供命名空间及其总体使用量列表。

带有 pod- 前缀的查询与带有 namespace- 前缀的查询类似，区别在于前者通过 Pod 而非命名空间来聚合信息。这些查询包含 Pod 的命名空间和节点。

带有 node- 前缀的查询会返回有关各个节点总可用资源的信息。

带有 aws- 前缀的查询为 AWS 特定查询。带有 -aws 后缀的查询返回的数据与无此后缀的同名查询返回的数据相同，并会将使用量与 EC2 计费数据相关联。

aws-ec2-billing-data 报告可供其他查询使用，但不应用作独立报告。aws-ec2-cluster-cost 报告根据集群中所含节点提供总成本，以及所报告时间段的成本总额。

要获取完整字段列表，请使用 oc CLI 以 YAMl 格式获取 ReportQuery，并检查 spec.columns 字段：

例如，运行：

$ oc -n openshift-metering get reportqueries namespace-memory-request -o yaml

您应看到如下输出：

apiVersion: metering.openshift.io/v1
kind: ReportQuery
metadata:
  name: namespace-memory-request
  labels:
    operator-metering: "true"
spec:
  columns:
  - name: period_start
    type: timestamp
    unit: date
  - name: period_end
    type: timestamp
    unit: date
  - name: namespace
    type: varchar
    unit: kubernetes_namespace
  - name: pod_request_memory_byte_seconds
    type: double
    unit: byte_seconds

spec.schedule 配置块用于定义报告的运行时间。schedule 部分的主要字段为 period。根据 period 的值，还可通过 hourly、daily、weekly 和 monthly 字段来微调报告运行时间。

例如：如果 period 设置为 weekly，您则可将 weekly 字段添加至 spec.schedule 块中。以下示例中报告将于每周三下午 1 点 (13:00) 运行一次。

...
  schedule:
    period: "weekly"
    weekly:
      dayOfWeek: "wednesday"
      hour: 13
...

要根据现有数据运行报告，可将 spec.reportingStart 字段设置为 RFC3339 时间戳，以告知报告根据其 schedule 从 reportingStart 而非当前时间开始运行。务必要了解，这会导致 reporting-operator 按照时间表在 reportingStart 时间和当前时间之间的各个间隔内连续运行多个查询。如果周期短于每日，且 reportingStart 在数月之前，则可能会进行数千次查询。如果不设置 reportingStart，则报告将在报告创建后的下一个完整 reportingPeriod 内运行。

例如，如果您已收集 2019 年 1 月 1 日的数据，且希望在报告中添加该数据，则可使用以下值创建报告：

apiVersion: metering.openshift.io/v1
kind: Report
metadata:
  name: pod-cpu-request-hourly
spec:
  query: "pod-cpu-request"
  schedule:
    period: "hourly"
  reportingStart: "2019-01-01T00:00:00Z"

要将报告配置为仅运行至指定时间，您可将 spec.reportingEnd 字段设置为 RFC3339 时间戳。此字段值将导致报告生成从开始时间至 reportingEnd 周期的数据报告后随即按时间表停止运行。因时间表很可能与 reportingEnd 不一致，所以时间表中的最后周期将被缩短至所指定的 reportingEnd 时间。如果不设置此字段，报告将永久运行，直至为报告设置了 reportingEnd。

例如，为 7 月创建每周运行一次的报告，使用以下命令：

apiVersion: metering.openshift.io/v1
kind: Report
metadata:
  name: pod-cpu-request-hourly
spec:
  query: "pod-cpu-request"
  schedule:
    period: "weekly"
  reportingStart: "2019-07-01T00:00:00Z"
  reportingEnd: "2019-07-31T00:00:00Z"

当 runImmediately 设置为 true时，报告将立即运行。这个行为可确保立即处理报告并将报告放入队列，而无需额外的调度参数。

报告的 spec.inputs 字段可用于覆盖或设置 ReportQuery 的 spec.inputs 字段中定义的值。

这是一个“名称-值”对列表：

spec:
  inputs:
  - name: "NamespaceCPUUsageReportName"
    value: "namespace-cpu-usage-hourly"

name 输入值必须存在于 ReportQuery 的 inputs 列表中。Value 输入值必须为正确的输入 type。

报告数据存储在数据库中，与指标数据非常相似，因此可用于聚合或汇总报告。汇总报告的一个简单用例是将生成报告所需时间分散到更长时间内；无需通过每月报告来查询和添加整个月的所有数据，而是可以将任务分成每日报告，每份报告运行三十分之一的数据。

自定义汇总报告需要自定义报告查询。ReportQuery 模板处理器提供 reportTableName 功能，可通过报告的 metadata.name 获取必要表名称。

下面是取自内置查询的一个片段：

# Taken from pod-cpu.yaml
spec:
...
  inputs:
  - name: ReportingStart
    type: time
  - name: ReportingEnd
    type: time
  - name: NamespaceCPUUsageReportName
    type: Report
  - name: PodCpuUsageRawDataSourceName
    type: ReportDataSource
    default: pod-cpu-usage-raw
...

  query: |
...
    {|- if .Report.Inputs.NamespaceCPUUsageReportName |}
      namespace,
      sum(pod_usage_cpu_core_seconds) as pod_usage_cpu_core_seconds
    FROM {| .Report.Inputs.NamespaceCPUUsageReportName | reportTableName |}
...

# aggregated-report.yaml
spec:
  query: "namespace-cpu-usage"
  inputs:
  - name: "NamespaceCPUUsageReportName"
    value: "namespace-cpu-usage-hourly"