現在表示しているのは、次のバージョン向けのドキュメントです。Kubernetesバージョン: v1.27

Kubernetes v1.27 のドキュメントは積極的にメンテナンスされていません。現在表示されているバージョンはスナップショットです。最新のドキュメントはこちらです: 最新バージョン

監査

Kubernetesの監査はクラスター内の一連の行動を記録するセキュリティに関連した時系列の記録を提供します。クラスターはユーザー、Kubernetes APIを使用するアプリケーション、およびコントロールプレーン自体によって生成されたアクティビティなどを監査します。

監査により、クラスター管理者は以下の質問に答えることができます:

何が起きたのか？
いつ起こったのか？
誰がそれを始めたのか？
何のために起こったのか？
それはどこで観察されたのか？
それはどこから始まったのか？
それはどこへ向かっていたのか？

監査記録のライフサイクルはkube-apiserverコンポーネントの中で始まります。各リクエストの実行の各段階で、監査イベントが生成されます。ポリシーに従って前処理され、バックエンドに書き込まれます。ポリシーが何を記録するかを決定し、バックエンドがその記録を永続化します。現在のバックエンドの実装はログファイルやWebhookなどがあります。

各リクエストは関連する stage で記録されます。定義されたステージは以下の通りです:

RequestReceived - 監査ハンドラーがリクエストを受信すると同時に生成されるイベントのステージ。つまり、ハンドラーチェーンに委譲される前に生成されるイベントのステージです。
ResponseStarted - レスポンスヘッダーが送信された後、レスポンスボディが送信される前のステージです。このステージは長時間実行されるリクエスト(watchなど)でのみ発生します。
ResponseComplete - レスポンスボディの送信が完了して、それ以上のバイトは送信されません。
Panic - パニックが起きたときに発生するイベント。

備考: Audit Event configurationの設定はEventAPIオブジェクトとは異なります。

監査ログ機能は、リクエストごとに監査に必要なコンテキストが保存されるため、APIサーバーのメモリー消費量が増加します。メモリーの消費量は、監査ログ機能の設定によって異なります。

監査ポリシー

監査ポリシーはどのようなイベントを記録し、どのようなデータを含むべきかについてのルールを定義します。監査ポリシーのオブジェクト構造は、audit.k8s.io API groupで定義されています。

イベントが処理されると、そのイベントは順番にルールのリストと比較されます。最初のマッチングルールは、イベントの監査レベルを設定します。

定義されている監査レベルは:

None - ルールに一致するイベントを記録しません。
Metadata - リクエストのメタデータ(リクエストしたユーザー、タイムスタンプ、リソース、動作など)を記録しますが、リクエストやレスポンスのボディは記録しません。
Request - ログイベントのメタデータとリクエストボディは表示されますが、レスポンスボディは表示されません。これは非リソースリクエストには適用されません。
RequestResponse - イベントのメタデータ、リクエストとレスポンスのボディを記録しますが、非リソースリクエストには適用されません。

audit-policy-fileフラグを使って、ポリシーを記述したファイルを kube-apiserverに渡すことができます。このフラグが省略された場合イベントは記録されません。監査ポリシーファイルでは、rulesフィールドが必ず指定されることに注意してください。ルールがない(0)ポリシーは不当なものとして扱われます。

以下は監査ポリシーファイルの例です:

audit/audit-policy.yaml

apiVersion: audit.k8s.io/v1 # This is required.
kind: Policy
# Don't generate audit events for all requests in RequestReceived stage.
omitStages:
  - "RequestReceived"
rules:
  # Log pod changes at RequestResponse level
  - level: RequestResponse
    resources:
    - group: ""
      # Resource "pods" doesn't match requests to any subresource of pods,
      # which is consistent with the RBAC policy.
      resources: ["pods"]
  # Log "pods/log", "pods/status" at Metadata level
  - level: Metadata
    resources:
    - group: ""
      resources: ["pods/log", "pods/status"]

  # Don't log requests to a configmap called "controller-leader"
  - level: None
    resources:
    - group: ""
      resources: ["configmaps"]
      resourceNames: ["controller-leader"]

  # Don't log watch requests by the "system:kube-proxy" on endpoints or services
  - level: None
    users: ["system:kube-proxy"]
    verbs: ["watch"]
    resources:
    - group: "" # core API group
      resources: ["endpoints", "services"]

  # Don't log authenticated requests to certain non-resource URL paths.
  - level: None
    userGroups: ["system:authenticated"]
    nonResourceURLs:
    - "/api*" # Wildcard matching.
    - "/version"

  # Log the request body of configmap changes in kube-system.
  - level: Request
    resources:
    - group: "" # core API group
      resources: ["configmaps"]
    # This rule only applies to resources in the "kube-system" namespace.
    # The empty string "" can be used to select non-namespaced resources.
    namespaces: ["kube-system"]

  # Log configmap and secret changes in all other namespaces at the Metadata level.
  - level: Metadata
    resources:
    - group: "" # core API group
      resources: ["secrets", "configmaps"]

  # Log all other resources in core and extensions at the Request level.
  - level: Request
    resources:
    - group: "" # core API group
    - group: "extensions" # Version of group should NOT be included.

  # A catch-all rule to log all other requests at the Metadata level.
  - level: Metadata
    # Long-running requests like watches that fall under this rule will not
    # generate an audit event in RequestReceived.
    omitStages:
      - "RequestReceived"

最小限の監査ポリシーファイルを使用して、すべてのリクエストを Metadataレベルで記録することができます。

# Log all requests at the Metadata level.
apiVersion: audit.k8s.io/v1
kind: Policy
rules:
- level: Metadata

独自の監査プロファイルを作成する場合は、Google Container-Optimized OSの監査プロファイルを出発点として使用できます。監査ポリシーファイルを生成するconfigure-helper.shスクリプトを確認することができます。スクリプトを直接見ることで、監査ポリシーファイルのほとんどを見ることができます。

また、定義されているフィールドの詳細については、Policy` configuration referenceを参照できます。

監査バックエンド

監査バックエンドは監査イベントを外部ストレージに永続化します。 kube-apiserverには2つのバックエンドが用意されています。

イベントをファイルシステムに書き込むログバックエンド
外部のHTTP APIにイベントを送信するWebhookバックエンド

いずれの場合も、監査イベントはKubernetes APIaudit.k8s.io API groupで定義されている構造に従います。

備考:

パッチの場合、リクエストボディはパッチ操作を含むJSON配列であり、適切なKubernetes APIオブジェクトを含むJSONオブジェクトではありません。例えば、以下のリクエストボディは/apis/batch/v1/namespaces/some-namespace/jobs/some-job-nameに対する有効なパッチリクエストです。

[
  {
    "op": "replace",
    "path": "/spec/parallelism",
    "value": 0
  },
  {
    "op": "remove",
    "path": "/spec/template/spec/containers/0/terminationMessagePolicy"
  }
]

ログバックエンド

ログバックエンドは監査イベントをJSONlines形式のファイルに書き込みます。以下の kube-apiserver フラグを使ってログ監査バックエンドを設定できます。

--audit-log-path は、ログバックエンドが監査イベントを書き込む際に使用するログファイルのパスを指定します。このフラグを指定しないと、ログバックエンドは無効になります。- は標準出力を意味します。
--audit-log-maxage は、古い監査ログファイルを保持する最大日数を定義します。
audit-log-maxbackupは、保持する監査ログファイルの最大数を定義します。
--audit-log-maxsize は、監査ログファイルがローテーションされるまでの最大サイズをメガバイト単位で定義します。

クラスターのコントロールプレーンでkube-apiserverをPodとして動作させている場合は、監査記録が永久化されるように、ポリシーファイルとログファイルの場所にhostPathをマウントすることを忘れないでください。例えば:

  - --audit-policy-file=/etc/kubernetes/audit-policy.yaml
  - --audit-log-path=/var/log/kubernetes/audit/audit.log

それからボリュームをマウントします:

...
volumeMounts:
  - mountPath: /etc/kubernetes/audit-policy.yaml
    name: audit
    readOnly: true
  - mountPath: /var/log/audit.log
    name: audit-log
    readOnly: false

最後にhostPathを設定します:

...
volumes:
- name: audit
  hostPath:
    path: /etc/kubernetes/audit-policy.yaml
    type: File

- name: audit-log
  hostPath:
    path: /var/log/audit.log
    type: FileOrCreate

Webhookバックエンド

Webhook監査バックエンドは、監査イベントをリモートのWeb APIに送信しますが、これは認証手段を含むKubernetes APIの形式であると想定されます。

Webhook監査バックエンドを設定するには、以下のkube-apiserverフラグを使用します。

--audit-webhook-config-file は、Webhookの設定ファイルのパスを指定します。 webhookの設定は、事実上特化したkubeconfigです。
--audit-webhook-initial-backoff は、最初に失敗したリクエストの後、再試行するまでに待つ時間を指定します。それ以降のリクエストは、指数関数的なバックオフで再試行されます。

Webhookの設定ファイルは、kubeconfig形式でサービスのリモートアドレスと接続に使用する認証情報を指定します。

イベントバッチ

ログバックエンドとwebhookバックエンドの両方がバッチ処理をサポートしています。 webhookを例に、利用可能なフラグの一覧を示します。ログバックエンドで同じフラグを取得するには、フラグ名のwebhookをlogに置き換えてください。デフォルトでは、バッチングはwebhookでは有効で、logでは無効です。同様に、デフォルトではスロットリングは webhook で有効で、logでは無効です。

--audit-webhook-mode は、バッファリング戦略を定義します。以下のいずれかとなります。
- batch - イベントをバッファリングして、非同期にバッチ処理します。これがデフォルトです。
- blocking - 個々のイベントを処理する際に、APIサーバーの応答をブロックします。
- blocking-strict - blockingと同じですが、RequestReceivedステージでの監査ログに失敗した場合は RequestReceivedステージで監査ログに失敗すると、kube-apiserverへのリクエスト全体が失敗します。

以下のフラグは batch モードでのみ使用されます:

--audit-webhook-batch-buffer-sizeは、バッチ処理を行う前にバッファリングするイベントの数を定義します。入力イベントの割合がバッファをオーバーフローすると、イベントはドロップされます。
--audit-webhook-batch-max-sizeは、1つのバッチに入れるイベントの最大数を定義します。
--audit-webhook-batch-max-waitは、キュー内のイベントを無条件にバッチ処理するまでの最大待機時間を定義します。
--audit-webhook-batch-throttle-qpsは、1秒あたりに生成されるバッチの最大平均数を定義します。
--audit-webhook-batch-throttle-burstは、許可された QPS が低い場合に、同じ瞬間に生成されるバッチの最大数を定義します。

パラメーターチューニング

パラメーターは、APIサーバーの負荷に合わせて設定してください。

例えば、kube-apiserverが毎秒100件のリクエストを受け取り、それぞれのリクエストがResponseStartedとResponseCompleteの段階でのみ監査されるとします。毎秒≅200の監査イベントが発生すると考えてください。 1つのバッチに最大100個のイベントがあるの場合、スロットリングレベルを少なくとも2クエリ/秒に設定する必要があります。バックエンドがイベントを書き込むのに最大で5秒かかる場合、5秒分のイベントを保持するようにバッファーサイズを設定する必要があります。

10バッチ、または1000イベントとなります。

しかし、ほとんどの場合デフォルトのパラメーターで十分であり、手動で設定する必要はありません。 kube-apiserverが公開している以下のPrometheusメトリクスや、ログを見て監査サブシステムの状態を監視することができます。

apiserver_audit_event_totalメトリックには、エクスポートされた監査イベントの合計数が含まれます。
apiserver_audit_error_totalメトリックには、エクスポート中にエラーが発生してドロップされたイベントの総数が含まれます。

ログエントリー・トランケーション

logバックエンドとwebhookバックエンドは、ログに記録されるイベントのサイズを制限することをサポートしています。

例として、logバックエンドで利用可能なフラグの一覧を以下に示します

audit-log-truncate-enabledイベントとバッチの切り捨てを有効にするかどうかです。
audit-log-truncate-max-batch-sizeバックエンドに送信されるバッチのバイト単位の最大サイズ。
audit-log-truncate-max-event-sizeバックエンドに送信される監査イベントのバイト単位の最大サイズです。

デフォルトでは、webhookとlogの両方で切り捨ては無効になっていますが、クラスター管理者は audit-log-truncate-enabledまたはaudit-webhook-truncate-enabledを設定して、この機能を有効にする必要があります。

次の項目

最終更新 June 22, 2023 at 12:13 AM PST: [ja] Update audit.md (647c8a5195)

現在表示しているのは、次のバージョン向けのドキュメントです。Kubernetesバージョン: v1.27

監査

監査ポリシー

監査バックエンド

ログバックエンド

Webhookバックエンド

イベントバッチ

パラメーターチューニング

ログエントリー・トランケーション

次の項目

フィードバック