Datadog Admission Controller

概要

Datadog Admission Controller は Datadog Cluster Agent のコンポーネントで、アプリケーションポッドのコンフィギュレーションを簡略化できる便利なツールです。Admission Controller には以下の 2 つの機能が備わっています。

  • 環境変数 (DD_AGENT_HOSTDD_TRACE_AGENT_URLDD_ENTITY_ID) をユーザーのアプリケーションコンテナに挿入し、DogStatsD および APM トレーサーライブラリを構成する。
  • アプリケーションラベルから取得した Datadog の標準タグ (envserviceversion) をコンテナ環境変数に挿入する。

Datadog Admission Controller は MutatingAdmissionWebhook 型に属します。Admission Controller について詳しくは、Kubernetes ガイドを参照してください。

要件

  • Datadog Cluster Agent v7.39+

コンフィギュレーション

Helm チャート

Helm チャート v2.35.0 から、Datadog アドミッションコントローラーがデフォルトで有効化されるようになりました。アドミッションコントローラーを有効にするための追加構成は必要ありません。

Admission Controller で v2.34.6 以前の Helm チャートを有効にするには、パラメーター clusterAgent.admissionController.enabledtrue に設定してください。

values.yaml

[...]
 clusterAgent:
[...]
  ## @param admissionController - オブジェクト - 必須
  ## admissionController での自動 APM 挿入を有効化
  ## DogStatsD config および標準タグ (env、service、version) を
  ## ポッドに挿入
  #
  admissionController:
    enabled: true

    ## @param mutateUnlabelled - boolean - optional
    ## ポッドラベルなしで config の挿入を有効化:
    ## admission.datadoghq.com/enabled="true"
    #
    mutateUnlabelled: false
[...]

Datadog 演算子

Admission Controller で Datadog 演算子を有効にするには、カスタムリソースでパラメーター clusterAgent.config.admissionController.enabledtrue に設定します。

[...]
 clusterAgent:
[...]
    config:
      admissionController:
        enabled: true
        mutateUnlabelled: false
[...]

手動セットアップ

Helm または Datadog 演算子を使用せずに Admission Controller を有効にするには、コンフィギュレーションに以下を追加します。

まず、Cluster Agent RBAC アクセス許可のマニフェストをダウンロードし、rules の下に以下を追加します。

cluster-agent-rbac.yaml

- apiGroups:
  - admissionregistration.k8s.io
  resources:
  - mutatingwebhookconfigurations
  verbs: ["get", "list", "watch", "update", "create"]
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["get", "list", "watch", "update", "create"]
- apiGroups: ["batch"]
  resources: ["jobs", "cronjobs"]
  verbs: ["get"]
- apiGroups: ["apps"]
  resources: ["statefulsets", "replicasets", "deployments"]
  verbs: ["get"]

agent-services.yaml の下に以下を追加します。

agent-services.yaml

apiVersion: v1
kind: Service
metadata:
  name: datadog-cluster-agent-admission-controller
  labels:
    app: "datadog"
    app.kubernetes.io/name: "datadog"
spec:
  selector:
    app: datadog-cluster-agent
  ports:
  - port: 443
    targetPort: 8000

Cluster Agent のデプロイに環境変数を追加し、Admission Controller を有効にします。

cluster-agent-deployment.yaml

- name: DD_ADMISSION_CONTROLLER_ENABLED
  value: "true"
- name: DD_ADMISSION_CONTROLLER_SERVICE_NAME
  value: "datadog-cluster-agent-admission-controller"

# このコメントを解除して自動的に APM トレーサーを構成します (以下を参照)
# - name: DD_ADMISSION_CONTROLLER_MUTATE_UNLABELLED
#   value: "true"

最期に、次のコマンドを実行します。

  • kubectl apply -f cluster-agent-rbac.yaml
  • kubectl apply -f agent-services.yaml
  • kubectl apply -f cluster-agent-deployment.yaml

APM

Cluster Agent (バージョン 7.39 以降)では、APM トレーシングライブラリを自動的に挿入するように構成することができます。

Cluster Agent をインストールしたら、次のいずれかを実行します。

  • ラベル admission.datadoghq.com/enabled: "true" をポッドに追加する。
  • mutateUnlabelled (コンフィギュレーションメソッドによっては DD_ADMISSION_CONTROLLER_MUTATE_UNLABELLED) を true に設定して Cluster Agent の Admission Controller を構成します。

ライブラリ挿入のためにコンテナをオプトインするには、アプリケーションの YAML ファイル内で Pod アノテーションを使用して、言語トレーサーとバージョンを指定します。

アノテーションは、次の形式の key: value のペアです。

datadoghq.com/<language>-lib.version: <lib-version>

このアノテーションを追加すると、その言語とバージョンのトレーサーライブラリが、コンテナ化されたアプリケーションに挿入されます。 有効な <language> の値は以下の通りです。

  • java
  • js

例えば、最新の Java トレーサーを挿入するには

annotations:
    admission.datadoghq.com/java-lib.version: "latest"

: ライブラリのメジャーリリースは、破壊的な変更をもたらす可能性があるため、latest を指定する際には注意が必要です。

あまりないシナリオですが、複数の <language>-lib.version アノテーションを追加して、1 つのコンテナに複数の言語トレーサーを挿入することができます。

例えば、最新の Java トレーサーと Node トレーサー v3.0.0 を挿入するには

annotations:
    admission.datadoghq.com/java-lib.version: "latest"
    admission.datadoghq.com/js-lib.version: "3.0.0"

mutateUnlabelled: true アノテーションを追加すると、Cluster Agent はラベルのないポッドをすべてインターセプトしようとします。

ポッドで環境変数を受信しないようにするには、ラベル admission.datadoghq.com/enabled: "false" を追加します。これは mutateUnlabelled: true を設定している場合でも機能します。

mutateUnlabelledfalse に設定されている場合、ポッドラベルは admission.datadoghq.com/enabled: "true" とします。

利用可能なオプション:

mutateUnlabelledポッドラベル挿入可否
trueラベルなし
trueadmission.datadoghq.com/enabled=true
trueadmission.datadoghq.com/enabled=false
falseラベルなし
falseadmission.datadoghq.com/enabled=true
falseadmission.datadoghq.com/enabled=false

DogStatsD

DogStatsD クライアントやライブラリの挿入をサポートしていない他の APM ライブラリを構成するには、以下のいずれかの方法で環境変数 DD_AGENT_HOSTDD_ENTITY_ID を挿入します。

  • ラベル admission.datadoghq.com/enabled: "true" をポッドに追加する。
  • mutateUnlabelled (コンフィギュレーションメソッドによっては DD_ADMISSION_CONTROLLER_MUTATE_UNLABELLED) を true に設定して Cluster Agent の Admission Controller を構成します。

優先順位

Datadog Admission Controller は環境変数 DD_VERSIONDD_ENV および DD_SERVICE が既に存在する場合は挿入を行いません。

これらの環境変数が設定されていない場合、Admission Controller は以下の順序で標準タグの値を使用します (高い方から順に)。

  • ポッド上のラベル
  • ownerReference のラベル (ReplicaSets、DaemonSets、Deployments…)

APM と DogstatsD の通信モードの構成

Datadog Cluster Agent v1.20.0 以降、Datadog Admission Controller は、アプリケーションと Datadog Agent の間で異なる通信モードを注入するように構成することができるようになりました。

この機能は admission_controller.inject_config.mode を設定するか、ポッドラベル admission.datadoghq.com/config.mode を使用してポッド固有のモードを定義することによって構成することができます。

可能なオプション:

モード説明
hostip (デフォルト)環境変数 DD_AGENT_HOST にホスト IP を注入する
serviceDatadog のローカルサービスの DNS 名を環境変数 DD_AGENT_HOST に注入する (Kubernetes v1.22+で使用可能)
socket環境変数 DD_TRACE_AGENT_URL に Unix ドメインソケットのパスを注入し、対応するパスにアクセスするようにボリュームを定義する

: ポッド固有のモードは、Admission Controller レベルで定義されたグローバルモードより優先されます。

  • 新しいアプリケーションポッドを作成する前に、Admission Controller のデプロイと構成が必要です。既に存在するポッドは更新できません。
  • Admission Controller の挿入機能を無効化するには、Cluster Agent のコンフィギュレーション: DD_ADMISSION_CONTROLLER_INJECT_CONFIG_ENABLED=false を使用します。
  • Datadog Admission Controller を使用すれば、ユーザーは Downward API (Kubernetes トレースコレクション設定のステップ 2 ) を利用してアプリケーションポッドの構成をスキップすることができます。
  • Google Kubernetes Engine (GKE) Private Cluster では、コントロールプレーン用のファイアーウォールルールを追加する必要があります。着信接続を処理する Webhook は、ポート 443 でリクエストを受け取り、ポート 8000 に実装されたサービスに誘導します。デフォルトでは、クラスターのネットワークに gke-<CLUSTER_NAME>-master という名前のファイアーウォールルールが存在するはずです。ルールの “ソースフィルター” は、クラスターの “コントロールプレーンのアドレス範囲” と一致します。このファイアーウォールルールを編集して、TCP ポート 8000 へのイングレッションを許可するようにします。