第5章 Report

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

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

以下のサンプル Report には、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 接尾辞のある ReportQuery は、より複雑なクエリーを作成するために他の 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 レポートは、クラスターに含まれるノードに基づく総コストと、レポート期間のコストの合計を提供します。

フィールドの詳細の一覧については、oc CLI を使用して 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
...

既存データに対する Report の実行をサポートするには、spec.reportingStart フィールドを RFC3339 タイムスタンプ に設定し、Report が現在の時間ではなく、reportingStart から始まる schedule に基づいて実行するように指示します。1 つの重要な点として、これにより、reporting-operator が reportingStart の時間から現在の時間までの間のスケジュール期間に連続して多数のクエリーを実行する点に留意してください。レポート期間が日次よりも短く区切られ、reportingStart が数ヶ月前に遡る場合、クエリーの数は数千に上る可能性があります。reportingStart が未設定のままの場合、Report はレポート作成後の次の reportingPeriod 全体で実行されます。

このフィールドの使い方を示す一例として、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: "2019-01-01T00:00:00Z"

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

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

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

Report の spec.inputs フィールドは、ReportQuery の spec.inputs フィールドで定義された値を上書きまたは設定するために使用できます。

名前と値のペアの一覧です。

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

inputs の name は ReportQuery の inputs 一覧に存在している必要があります。inputs の value は inputs の type に適切なタイプである必要があります。

Report データはメトリクス自体と同様にデータベースに保存されるため、集計またはロールアップレポートで使用できます。ロールアップレポートの単純なユースケースとして、レポートの生成のタイミングを長期間にまたがって分散し、月次レポートで月全体のすべてのデータをクエリーし、追加するのではなく、タスクを日次レポートに分割し、それぞれのレポートが 30 番目のデータに対して実行されるようにします。

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

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

# 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"