enable-ssi

Single Step Instrumentation による Kubernetes での APM の有効化

何かを始める前に： ## Context to resolve before acting にあるすべての変数を完全に解決してください。すべての変数に具体的な値が設定されるまで、Step 0 を開始しないでください。

---

気づきにくい失敗 — 他の手順に進む前に確認してください：

アプリケーションの依存関係マニフェスト（requirements.txt、package.json、Gemfile、go.mod、pom.xml）に ddtrace、dd-trace、または OpenTelemetry SDK が含まれている場合、コードにインポート文がなくても、SSI は実行時に通知なく無効になります。

この失敗は目に見えません。init コンテナは実行・完了し、Pod は正常な状態で起動します。kubectl や pup にエラーは表示されませんが、トレースは届きません。インジェクターはユーザーがインストールしたトレーサーを検出すると、何もログに記録せず正常終了します。

Claude runs

grep -rE "ddtrace|dd-trace|opentelemetry" \
  requirements.txt package.json Gemfile go.mod pom.xml 2>/dev/null \
  || echo "No tracer dependency found"

1 つでも一致した場合は、作業を中止してください。パッケージをインポート文だけでなく完全に削除し、イメージを再ビルドしてクラスターに再度読み込み、作業を続ける前に Pod を再起動してください。マニフェストにパッケージが存在するだけでこの現象が発生します。インポートされていなくても同様です。

---

トリガー

ユーザーが次のような意図を示した場合に、このスキルを呼び出してください。

• Kubernetes クラスターで APM を有効にする
• Datadog のトレーシングで Kubernetes アプリケーションを計装する
• Single Step Instrumentation（SSI）をセットアップする

次の場合は、このスキルを呼び出さないでください。

• Datadog Agent がまだインストールされていない — 先に agent-install を実行してください
• ユーザーがセットアップ後の SSI の検証を希望している — verify-ssi を使用してください
• ユーザーが Data Streams Monitoring の有効化を希望している — enable-dsm を使用してください
• ユーザーが Profiler または AppSec の有効化を希望している — dd-apm-k8s-sdk-features を使用してください

---

前提条件

これは読むだけの手順ではありません。続行する前に、各項目を必ず実際に確認してください。

環境

• Datadog Agent がインストール済みで、正常に稼働している — agent-install が完了している
• Kubernetes v1.20+
• Linux ノードプールのみ — Windows Pod には明示的な名前空間の除外が必要
• クラスターが ECS Fargate ではない — サポート対象外
• セキュリティ強化された SELinux 環境ではない — サポート対象外
• 非常に小さい VM インスタンス（例：t2.micro）ではない — SSI の init がタイムアウトする可能性があります
• PodSecurity の baseline または restricted ポリシーが適用されていない

言語とランタイム

• アプリケーションの言語が次のいずれかである：Java、Python、Ruby、Node.js、.NET、PHP
• ランタイムのバージョンが SSI のサポート範囲内である — SSI compatibility matrix で確認してください
• Node.js アプリが ESM を使用していない — SSI は ESM をサポートしていません
• Java アプリが -javaagent JVM フラグをすでに使用していない

既存の計装 — このスキルの冒頭にある確認で問題がないことを確認してください。確認を省略した場合は、戻って今すぐ実行してください。

---

作業前に解決するコンテキスト

クラスターから確認してください。自分で確認できる情報をユーザーに尋ねないでください。

変数	解決方法
AGENT_NAMESPACE	agent-install で使用するものと同じ名前空間（例：datadog）
APP_NAMESPACE	kubectl get namespaces --no-headers | awk '{print $1}' | grep -vE '^(kube-system|kube-public|kube-node-lease|datadog|local-path-storage)$' を実行します。システム以外のすべての名前空間を計測するか、ユーザーが指定した名前空間を使用します
TARGET_LANGUAGES	kubectl get pods -A -o jsonpath='{.items[*].spec.containers[*].image}' を実行してイメージ名から言語を推測するか、ワークスペース内の Dockerfile／マニフェストを確認します。不明な場合は、すべての言語を有効にします
DEPLOYMENT_NAME	kubectl get deployments -A --no-headers を実行し、アプリケーションのデプロイメントを特定します（システムコンポーネントは除外）
APP_LABEL	kubectl get deployment <DEPLOYMENT_NAME> -n <APP_NAMESPACE> -o yaml で Deployment マニフェストの spec.selector.matchLabels を確認します
CLUSTER_NAME	datadog-agent.yaml の spec.global.clusterName を確認するか、kubectl config current-context を実行します。Step 0 の kind クラスターで必要です
ENV	eval クラスターで実行している場合は apm-evals を使用します（kind クラスター名に「evalya」が含まれます）。それ以外の場合は、ユーザーが別途指定しない限り production を使用します
SERVICE_NAME	デプロイメント名を使用します（例：python-app → サービス名は python-app）。ユーザーに尋ねないでください
VERSION	デフォルトとして 1.0.0 を使用します。ユーザーに尋ねないでください

---

Step 0（既存の計測が検出された場合のみ）：手動計測を削除する

すべてのソースファイルで次の項目を検索します：import ddtrace、from ddtrace、require 'ddtrace'、require("dd-trace")、opentelemetry、tracer.trace(

依存関係マニフェストで ddtrace／dd-trace／OTel SDK パッケージも確認します。

見つかった場合は、インポート／パッケージを削除してから、再ビルドして再読み込みします。

Claude が実行

docker build -f <DOCKERFILE_PATH> -t <IMAGE_NAME> <BUILD_CONTEXT>

[判断：このクラスターでローカルイメージを読み込む方法は？]

リポジトリのセットアップスクリプト（例：create.sh、Makefile、justfile）を確認し、イメージの読み込み方法を調べます。クラスター名やコンテキスト名から推測しないでください。一般的なパターンは次のとおりです。

セットアップスクリプトで見つかった項目	読み込みコマンド
minikube image load または minikube cache add	minikube -p <PROFILE> image load <IMAGE_NAME> — プロファイルにはスクリプト内の -p フラグの値を使用します。kubectl のコンテキスト名とは限りません
kind load docker-image	kind load docker-image <IMAGE_NAME> --name <CLUSTER_NAME>
レジストリへの docker push	新しいイメージをプッシュします。再起動時にクラスターが取得するため、ローカル読み込みはスキップします
k3d image import	k3d image import <IMAGE_NAME> -c <CLUSTER_NAME>
イメージ読み込み手順がない（クラウドクラスターで、常にレジストリから取得する）	スキップします。次回のデプロイ時にイメージが取得されます

セットアップスクリプトの内容が曖昧な場合は、スクリプトに記載された読み込みコマンドをそのまま実行します。

• レジストリベースの場合：スキップします。次回のデプロイ時にイメージが取得されます

再起動する前にユーザーの確認を得てください。 ユーザーに「再ビルドしたイメージを反映するため、<APP_NAMESPACE> の <DEPLOYMENT_NAME> を再起動する必要があります。進めてもよろしいですか？」と伝えてください。確認を待ちます。

Claude が実行

kubectl rollout restart deployment/<DEPLOYMENT_NAME> -n <APP_NAMESPACE>
kubectl wait --for=condition=Ready pod \
  -l app=<APP_LABEL> \
  -n <APP_NAMESPACE> \
  --timeout=120s

---

ステップ 1：DatadogAgent マニフェストを APM で拡張する

SSI は既存の DatadogAgent リソースで設定します。別のマニフェストは作成しないでください。

ユーザーの要望に応じて対象範囲を選択してください：

• ユーザーがすべてのアプリケーションへの計装を希望した場合、または範囲を指定しなかった場合 → オプション A（クラスター全体）を使用
• ユーザーが特定の名前空間のみを希望した場合 → オプション B を使用
• ユーザーがクラスター全体の対象から特定の名前空間を除外したい場合 → オプション C を使用
• ユーザーが特定の Pod／ワークロードを希望した場合 → オプション D を使用

デフォルトはクラスター全体（オプション A）です。 ユーザーが「すべてのアプリケーション」「クラスター全体」と言った場合や、対象範囲を限定していない場合は、enabledNamespaces や targets を指定せずにオプション A を使用してください。

推奨する ddTraceVersions：java: "1"、python: "2"、js: "5"、dotnet: "3"、ruby: "2"、php: "1"

オプション A — クラスター全体（デフォルト）：

features:
  apm:
    instrumentation:
      enabled: true

オプション B — 特定の名前空間のみ：

features:
  apm:
    instrumentation:
      enabled: true
      enabledNamespaces:
        - <APP_NAMESPACE>

オプション C — 除外を含むクラスター全体：

features:
  apm:
    instrumentation:
      enabled: true
      disabledNamespaces:
        - jenkins
        - kube-system

オプション D — 特定のワークロードを対象にする：

features:
  apm:
    instrumentation:
      enabled: true
      targets:
        - name: <TARGET_NAME>
          namespaceSelector:
            matchNames:
              - <APP_NAMESPACE>
          ddTraceVersions:
            <LANGUAGE>: "<MAJOR_VERSION>"

注： ddTraceVersions は targets[] エントリ内（オプション D）でのみ適用されます。enabledNamespaces と併用したり、instrumentation レベルに直接指定したりすることはできません。

Claude の実行内容

kubectl apply -f datadog-agent.yaml

datadogagent.datadoghq.com/datadog configured の場合は、ステップ 2 に進みます。

エラー：検証エラー — YAML を確認してください。enabledNamespaces と disabledNamespaces は同時に設定できません。

---

ステップ 2：統合サービスタグについてユーザーに知らせる

ユーザーの明示的な確認なしに、アプリケーションの Deployment を変更しないでください。 既存のアプリケーションワークロードにラベルを適用することは、顧客が管理するリソースへの変更にあたります。

Deployment に統合サービスタグ（UST）を追加すると、Datadog でサービス／環境／バージョンのタグ付けが適切に行われることをユーザーに伝えてください。SSI の動作に必須ではありませんが、完全なオブザーバビリティを実現するために推奨されます。

# Add to both metadata.labels and spec.template.metadata.labels
tags.datadoghq.com/env: "<ENV>"
tags.datadoghq.com/service: "<SERVICE_NAME>"
tags.datadoghq.com/version: "<VERSION>"

ユーザーが適用を希望する場合は、まず確認を得てください。ラベルを変更すると Pod が直ちにロールアウトされます。ステップ 2b で DSM を有効にする場合は、その後にラベルを適用してください。UST ラベルは APM トレースの送信に必須ではなく、なくても SSI は動作します。

---

ステップ 2b：イベント駆動型サービスを確認する

評価用クラスター（kind クラスター名に「evalya」を含む）または非対話型の実行では、このステップ全体をスキップしてください。何も実行せず、何も尋ねず、次のステップに進みます。

それ以外の場合は、.claude/skills/dd-apm/enable-dsm/SKILL.md の ## Is DSM a fit? セクションを読み、検出コマンドを実行してください。

• 適合するものが見つかった（メッセージングクライアント、ブローカー、キューによってトリガーされる Lambda、またはサービス同士が非同期に処理を受け渡すというユーザーの説明）場合 → enable-dsm に従ってください。ユーザーに一度だけ尋ね、プランのルールを説明し、再起動せずに設定を変更します。
• 適合するものがない場合 → スキップしてください。DSM には触れないでください。

ユーザーが同意した場合、enable-dsm は DatadogAgent の変更を適用し、Cluster Agent が新しい設定になったことを確認します。そのため、ステップ 3 の再起動で SSI と DSM の両方が反映されます。ステップ 3 では、最初に DSM の Deployment を 1 つ再起動し、その Deployment で enable-dsm のステップ 2a にある DD_DATA_STREAMS_ENABLED の確認を実行してから、残りを再起動してください。init コンテナーなしで起動した場合は、30 秒待ってからもう一度再起動してください。

---

ステップ 3：アプリケーションの Pod を再起動する

再起動する前に、ユーザーの確認を得てください。 ユーザーに次のように伝えてください：「Pod に SSI をインジェクトするため、<APP_NAMESPACE> の <DEPLOYMENT_NAME> を再起動する必要があります。短時間の停止が発生します。実行してもよろしいですか？」確認を待ってください。

Claude の実行内容

kubectl rollout restart deployment/<DEPLOYMENT_NAME> -n <APP_NAMESPACE>

kubectl wait --for=condition=Ready pod \
  -l app=<APP_LABEL> \
  -n <APP_NAMESPACE> \
  --timeout=120s

Pod が問題なく再起動すると、Pod の仕様に datadog-lib-<language>-init という名前の init コンテナーが表示されます。

エラー：Pod がクラッシュループしています — 既存のカスタム計装がないか確認してください。troubleshoot-ssi を参照してください。

---

完了

次のすべてを満たしたら終了します。

• 適用された DatadogAgent マニフェストに features.apm.instrumentation がある
• アプリケーションの Pod を再起動する必要があることをユーザーに伝えている
• Unified Service Tags（UST）について、また必要に応じた適用方法をユーザーに伝えている
• 対象範囲を確認している：計装されたワークロード、スキップされたワークロードとその理由

ユーザーに許可を求めず、ただちに verify-ssi に進んでください。

---

セキュリティ上の制約

• 生の API キーをファイルやチャットメッセージに書き込まないでください
• Datadog リソースに default 名前空間を使用しないでください
• admissionController の設定を直接変更しないでください。SSI が Operator 経由で管理します
• アプリケーションのマニフェストに APM 設定を追加しないでください。DatadogAgent 経由でのみ設定してください
• 例外：アプリケーションの Deployment に UST ラベル（tags.datadoghq.com/*）を付けることは必須であり、意図的なものです
• ユーザーの確認なしに kubectl delete を実行しないでください
• レジストリへの docker push は、常にユーザーの確認が必要です
• UST ラベルや Deployment の変更を適用するために、kubectl patch を使用しないでください。 必ず Deployment の YAML ファイルを編集してから、kubectl apply -f を実行してください。kubectl patch で加えた変更は一時的なもので、次回のロールアウト時に上書きされます