第5章 Report

以下のサンプル Report にはすべての Pod の CPU 要求についての情報が含まれ、1 時間に 1 回実行され、レポートが実行されるごとにその 1 時間前からの関連データが追加されます。

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

以下のサンプル Report オブジェクトには、7 月中のすべての Pod の CPU 要求についての情報が含まれます。完了後に再度実行されることはありません。

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

query フィールドは、レポートを生成するために使用される ReportQuery リソースに名前を指定します。レポートクエリーは、結果の処理方法と共にレポートのスキーマを制御します。

query は必須フィールドです。

利用可能な 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 接尾辞のあるレポートクエリーは、より複雑なクエリーを作成するために他の ReportQuery によって使用されます。これらはレポートに直接使用できません。

namespace- の接頭辞が付けられたクエリーは namespace 別に Pod CPU およびメモリー要求を集計し、リソース要求に基づいて namespace およびそれらの全体の使用状況の一覧を提供します。

pod- の接頭辞が付けられたクエリーは namespace- の接頭辞が付けられたクエリーと同様ですが、情報を namespace 別ではなく Pod 別に集計します。これらのクエリーには、Pod の namespace およびノードが含まれます。

node- の接頭辞が付けられたクエリーは各ノードの利用可能な合計リソースについての情報を返します。

aws- の接頭辞が付けられたクエリーは AWS に固有のものです。aws の接尾辞が付けられたクエリーは、接尾辞なしの同じ名前のクエリーと同じデータを返し、使用状況を EC2 請求データに関連付けます。

aws-ec2-billing-data レポートは他のクエリーによって使用され、スタンドアロンのレポートとしては使用できません。aws-ec2-cluster-cost レポートは、クラスターに含まれるノードに基づく総コストと、レポート期間のコストの合計を提供します。

以下のコマンドを使用して ReportQuery リソースを YAML として取得し、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 pm (hour 13) に実行されます。

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

既存データに対するレポートの実行をサポートするには、spec.reportingStart フィールドを RFC3339 タイムスタンプ に設定し、レポートが現在の時間ではなく、reportingStart から始まる schedule に基づいて実行するように指示します。

このフィールドの使い方を示す一例として、Report オブジェクトに組み込む必要のある 2019 年月 1 日まで遡ったデータをすでに収集している場合、以下の値を使用してレポートを作成できます。

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

指定された時点までのみ実行されるようにレポートを設定するには、spec.reportingEnd フィールドを RFC3339 タイムスタンプ に設定できます。このフィールドの値により、レポートは開始時点から reportingEnd までの期間のレポートデータの生成の終了後にスケジュールに基づいて実行を停止します。

スケジュールと reportingEnd は連動しない場合が多いため、スケジュールの最終期間は指定の reportingEnd 時間に終了するように短縮されます。これが未設定のままの場合、レポートは永久に実行されるか、または reportingEnd がレポートに設定されるまで実行されます。

たとえば、7 月に週 1 回実行されるレポートを作成する場合は、以下のようになります。

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

expiration フィールドを追加して、スケジュールされるメータリングレポートに保持期間を設定します。expiration 期間の値を設定すると、レポートを手動で削除することを避けることができます。保持期間はレポートの Report オブジェクトの creationDate に expiration を加えた期間と等しくなります。レポートまたはレポートクエリーが期限切れのレポートに依存しない場合、レポートが保持期間の終了時にクラスターから削除されます。レポートをクラスターから削除するには数分の時間がかかる場合があります。

たとえば、以下のスケジュールされたレポートは、レポートの creationDate の 30 秒後に削除されます。

apiVersion: metering.openshift.io/v1
kind: Report
metadata:
  name: pod-cpu-request-hourly
spec:
  query: "pod-cpu-request"
  schedule:
    period: "weekly"
  reportingStart: "2021-07-01T00:00:00Z"
  expiration: "30m" 1

runImmediately を true に設定すると、レポートは即座に実行されます。この動作により、追加のスケジューリングパラメーターなしにレポートが即座に処理され、キューに入れられます。

Report オブジェクトの spec.inputs フィールドは、 ReportQuery リソースの spec.inputs フィールドで定義された値を上書きまたは設定するために使用できます。

spec.inputs は名前と値のペアの一覧です。

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

レポートデータはメトリクス自体と同様にデータベースに保存されるため、集計またはロールアップレポートで使用できます。ロールアップレポートの単純なユースケースとして、レポートの作成に必要な時間をより長い期間にわたって分散します。これにより、クエリーし、1 カ月全体でのすべてのデータを追加する月次レポートは不要になります。たとえば、タスクは、それぞれがデータの 1/30 に対して実行される日次レポートに分割できます。

カスタムのロールアップレポートには、カスタムレポートクエリーが必要です。ReportQuery リソーステンプレートプロセッサーは、Report オブジェクトの metadata.name から必要なテーブル名を取得できる reportTableName 機能を提供します。

以下は、組み込みクエリーのスニペットです。

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 |}
...

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