mcpField
D
dt-setup-oneagent

dt-setup-oneagent

github.com/dynatraceクラウド・DevOps169518 回インストール今日更新
リポジトリ

dt-setup-oneagent について

運用担当者やエージェント向けの、Dynatrace OneAgent インストール参照スキルです。複数の環境別手順と安全上のルールを示しますが、コマンドは実行しません。

主な機能

  1. 01VM とサーバーの手順
  2. 02SSH と Windows のインストール案内
  3. 03Kubernetes と AWS Lambda の手順
  4. 04Azure VM と VMSS の案内
  5. 05トークン、テナント、書き込みの安全規則

活用シーン

  1. 01対象環境に応じた OneAgent 手順の確認
  2. 02トークンスコープと認証ヘッダーの確認
  3. 03テナントとトークンの取り扱い確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/dynatrace/dynatrace-for-ai --skill dt-setup-oneagent

インストール後、Claude Code で/dt-setup-oneagentを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
aws-lambda.md
azure-vm.md
kubernetes.md
remote-vm-ec2.md
windows.md

詳細

Dynatrace OneAgent のデプロイ — ナレッジリファレンス

このスキルはリファレンス専用です。サポート対象の各ターゲットに OneAgent を手動でインストールする際に、オペレーター（または別のエージェント）が必要とする、文書化されたエンドポイント、環境変数、トークンスコープ、コマンドが含まれています。何も実行しません。

このスキルではコマンドを提供しますが、コマンドの実行は行いません。必要なターゲットの手順に従い、以下の説明にあるとおりに環境 URL とトークンを置き換えてください。

このスキルを利用するすべてのエージェントが守るべき絶対ルール

  • ユーザーが明示したリソースのみを操作してください。 プレースホルダーやテスト用の Lambda、IAM ロール、K8s 名前空間、シークレット、S3 バケット、EC2 インスタンス、その他のフィクスチャを、自分の判断で作成してはいけません。「実演」のためでも、「ついでに」でも、先回りしてもいけません。指定されたリソースが存在せず、ユーザーから作成を依頼されていない場合は、作業を中断して確認してください。追加の Secrets Manager エントリ、監視、ヘルパースタックなどの関連リソースを、黙ってプロビジョニングしてはいけません。まず正確な定義を示し、確認を求めてください。
  • ユーザーが明示的に作成を指定したモードは問題ありません。 ユーザーが --create を渡した場合（または確認を求めた後に「はい、作成してください」と明示した場合）、そのモードについて文書化されたリソースだけをプロビジョニングするのが適切です。文書化されたリソース一式については、references/aws-lambda.md の 新しい関数を作成して OneAgent をインストールする を参照してください。ユーザーが入力した関数名を疑ってはいけません。「test」「demo」「scratch」「tmp」などの名前にパターンマッチして、拒否したり、警告したり、別の名前を強要したりしてはいけません。入力内容が優先されます。上記のルールは、黙って、あるいは依頼されずに作成することを禁じるものであり、ユーザーが依頼した作成を禁じるものではありません。
  • API トークンを絶対に永続化しないでください。 トークンの用途は、（a）OneAgent アーティファクトのダウンロード／レイヤー ARN の検索を認証すること、（b）インストールの一環として対象システム（Lambda の環境変数または Secrets Manager、Linux インストーラー、DynaKube シークレット）に渡すことだけです。ローカルファイルにキャッシュしたり、一時スクリプトに書き込んだり、シェル履歴に残したり、PR の説明にコピーしたり、厳密に必要とする対象システム以外の場所に保存したりしてはいけません。実行のたびに新しいトークンを使ってください。環境変数またはアクセス権限を 0600 に設定したファイルで渡し、使用後は破棄してください。
  • API トークンを絶対に表示またはログ出力しないでください。 コマンドで参照する必要がある場合は、$DT_API_TOKEN または省略したプレフィックス（dt0s16.…、dt0c01.…）を使用してください。実際の値を文章に貼り付けてはいけません。
  • 環境 URL を決めつけず、インストール前にテナントを確認してください。 間違った環境を指定すると、気づかれないまま失敗します。インストール自体は成功し、ホストや関数は誰も監視していないテナントにレポートします。ユーザーが明示した環境 URL は、ツールのデフォルトや前回の実行から導出された値より常に優先されます。キャッシュ値や検出値で上書きしてはいけません。使用するテナントを提示し、ユーザーが訂正できるようにしてください。正しいホストは、テナント ID（abc12345）と labs／prod のどちらを使うかで決まります。
  • コレクションを受け取る書き込みでは、コレクション全体が置き換えられます。読み取り、マージしてから書き込んでください。 ここにある複数の API はコレクション全体を受け取り、既存の内容をすべて上書きします。aws lambda update-function-configuration は --environment と --layers の両方でこの動作をするため、Dynatrace の値だけを送信すると、関数独自の環境変数や他のレイヤーが気づかれないまま削除されます。常に現在の状態を読み取り、追加分をマージしてから、結合した内容を書き戻してください。最初の書き込みの前にロールバック用のスナップショットを取得してください。項目を追加するのではなくセット全体を置き換えようとしている場合は、どこでもこのルールが適用されます。
  • dtctl から環境 URL を導出する場合。 dtctl config current-context が返すのはコンテキスト名（例：my-env）だけで、URL ではありません。URL は dtctl config describe-context <ctx> から取得します。出力をそのまま jq に渡してはいけません。dtctl のバージョンによっては -o json を無視して人間向けの表（Environment: https://…）を出力しながら終了コード 0 を返すことがあります。その場合、jq が解析エラーで失敗し、set -e -o pipefail を設定したスクリプト全体が終了します。出力が本当に JSON であることを確認し、そうでなければ Environment: 行から値を取得してください。
CTX="$(dtctl config current-context 2>/dev/null || true)"
OUT="$(dtctl config describe-context "$CTX" -o json 2>/dev/null || true)"
if printf '%s' "$OUT" | jq -e . >/dev/null 2>&1; then
  DT_ENV_URL="$(printf '%s' "$OUT" | jq -r '.environment // .url // empty')"
else
  DT_ENV_URL="$(printf '%s' "$OUT" | awk 'tolower($1) ~ /^(environment|url):$/ {print $2; exit}')"
fi

URL の正規化

Dynatrace の「新しいプラットフォーム」の URL と従来の OneAgent インストーラーエンドポイントは異なります。インストーラー URL を構築する前に、次のように変換してください。

入力（Dynatrace UI／ドキュメント）インストーラーエンドポイントで使用する値
https://<id>.apps.dynatrace.comhttps://<id>.live.dynatrace.com
https://<id>.<region>.apps.dynatracelabs.comhttps://<id>.<region>.dynatracelabs.com
その他変更なし

テナント ID は、ドットで区切られた最初のセグメント（<id>）です。

トークンの種類と Authorization ヘッダー

使用するトークンファミリーは 2 種類あります。Authorization スキームは、呼び出すエンドポイントではなく、トークンのプレフィックスで選択します。

トークンプレフィックスヘッダー
プラットフォームトークンdt0s16.Authorization: Bearer <token>
アクセストークン（従来の API トークン）dt0c01.Authorization: Api-Token <token>
PaaS トークンdt0s01.Authorization: Bearer <token>
OAuth クライアントシークレットdt0s02. / dt0s03.❌ 直接使用できません。先にベアラートークンに交換する必要があります

プラットフォームトークンが、今後の標準です。 Dynatrace はアクセストークンを非推奨にしています。新しいテナントではアクセストークンを作成できなくなっており、Classic API エンドポイントはプラットフォームトークンを受け入れるよう更新されています。トークンが dt0c01. で始まるとは限りません。このルールのリファレンス実装は dtwiz の AuthHeader()（pkg/installer/installer.go）です。dt0c01.* → Api-Token、それ以外 → Bearer となります。

従来 PaaS／アクセストークンを必要としていたコンポーネントにトークンを渡す経路が 1 つあります。プラットフォームトークンが拒否された場合は、そこで dt0c01. アクセストークンを使用してください。

  • Kubernetes — Dynatrace Operator は dynakube シークレットを使用して認証します。

VM、リモート VM／EC2、Windows、Lambda は Deployment API を直接呼び出すため、どちらのトークンファミリーでも動作します。

対象ごとのトークンスコープ

プラットフォームトークン（dt0s16.）の場合、OneAgent に関連するスコープは Fleet management にあります。fleet-management:oneagents:download、fleet-management:oneagent.connection-info:read、fleet-management:oneagent.tokens:read、fleet-management:cluster-id:read です。Kubernetes では、さらに fleet-management:activegates:download と fleet-management:activegate.tokens:create が必要です。Dynatrace の QuickStart アプリでトークンを生成すると、動作に必要なスコープが設定されます。

従来のアクセストークン（dt0c01.）の場合：

対象必要なトークンスコープ
VM／WindowsInstallerDownload（PaaS）
KubernetesInstallerDownload、settings.read、settings.write、activeGateTokenManagement.create — Dynatrace UI の「Kubernetes: Dynatrace Operator」テンプレートですべて設定されます。
Azure VM／VMSSInstallerDownload（PaaS）。Azure 側では、呼び出し元の az ID に、リソースで Microsoft.Compute/.../extensions/write を許可する Contributor または任意のロールが必要です。
AWS Lambda（ランタイムトークン）OneAgent レイヤーがランタイムに使用する接続認証トークンです。インストーラートークンとは別のものです。Dynatrace UI の Access tokens から entities.read を指定して作成するか、Hub → AWS Lambda テンプレートを使用してください。

トークンがユーザー名に紐づくことはありません。トークンはテナントに属します。

対象

各対象には、それぞれ専用のリファレンスがあります。共通のルール、URL の正規化、トークンに関するガイダンスは上記のとおりです。まずそれらを読んでから、必要なリファレンスを確認してください。

マネージド Kubernetes ディストリビューションは、個別ではなく Kubernetes のリファレンスで扱います。インストール手順は同じで、異なるのはノードタイプだけなので、その差分は変更対象の手順の近くに記載します。

対象リファレンス
VM／サーバー（Linux、macOS）以下 — ほかのすべての対象の基礎となるケース
リモート VM／EC2（SSH 経由）→ references/remote-vm-ec2.md
Windows ホスト（WSL またはネイティブ）→ references/windows.md
Kubernetes（Operator + DynaKube）— EKS、Fargate、Bottlerocket の制限を含む→ references/kubernetes.md
AWS Lambda（レイヤー + 環境変数）→ references/aws-lambda.md
Azure VM／VM Scale Set（VM 拡張機能）→ references/azure-vm.md
プラットフォーム別

上の表は、手順を決定するインストール方式ごとにまとめています。特定のクラウドを利用している場合は、次を参照してください。

プラットフォームデプロイ先参照先
AWSEC2 インスタンスremote-vm-ec2.md
EKS — EC2 ノードkubernetes.md
EKS — Fargate または Bottlerocket ノードkubernetes.md § AWS EKS specifics — フルスタックは利用できません。applicationMonitoring のみです
Lambda 関数aws-lambda.md
AzureVM または VM Scale Setazure-vm.md
AKSkubernetes.md — ノードプールが VMSS であっても、VM 拡張機能は使用しません
Google CloudGKE（standard）kubernetes.md
GKE AutopilotOperator の手順については kubernetes.md を参照してください。Bottlerocket と同様、フルスタックは利用できません。Autopilot 固有のチューニングは対象外です
Compute Engine VMremote-vm-ec2.md — SSH の手順は AWS 固有ではありません
オンプレミス／その他すべてログインしている Linux または macOS以下
SSH 経由で接続する Linuxremote-vm-ec2.md
Windowswindows.md
Kubernetes、または標準 Operator を使用する OpenShiftkubernetes.md — 従来の OpenShift node-config-operator の手順は対象外です

VM／サーバー（Linux、macOS）

エンドポイント（${DT_ENV_URL_NORMALIZED} と ${ARCH} を置き換えてください。ARCH ∈ x86 | arm | ppc64le | s390）：

GET ${DT_ENV_URL_NORMALIZED}/api/v1/deployment/installer/agent/unix/default/latest?arch=${ARCH}&flavor=default
Header: Authorization: Api-Token ${DT_API_TOKEN}   # dt0c01.… access token
        Authorization: Bearer ${DT_API_TOKEN}      # dt0s16.… platform token

インストールコマンド：

トークンに合わせてスキームを設定してください — dt0c01.… の場合は Api-Token、dt0s16.… の場合は Bearer：

DT_AUTH="Api-Token ${DT_API_TOKEN}"   # platform token: DT_AUTH="Bearer ${DT_API_TOKEN}"

wget -O Dynatrace-OneAgent-Linux.sh \
  --header="Authorization: ${DT_AUTH}" \
  "${DT_ENV_URL_NORMALIZED}/api/v1/deployment/installer/agent/unix/default/latest?arch=${ARCH}&flavor=default"

sudo /bin/sh Dynatrace-OneAgent-Linux.sh \
  --set-monitoring-mode=fullstack \
  --set-app-log-content-access=true \
  [--set-host-group=<name>] \
  [--set-network-zone=<zone>]

再起動に関する注意： OneAgent は、すでに実行中のプロセスにはインジェクトできません。インストール後、監視対象のワークロードを再起動してください。

アンインストール：

sudo /opt/dynatrace/oneagent/agent/uninstall.sh

systemd ユニット、/opt/dynatrace、およびエージェントをインジェクトする /etc/ld.so.preload の行を削除します。

このスキルを使用しないケース

  • ユーザーが説明ではなく、インストールの実行を依頼している場合。→ このスキルが引き続き適用されます。対象の手順に従ってコマンドを実行し、最初にテナントを確認してください。
  • ユーザーがインストールに失敗した理由を尋ね、説明を求めている場合。→ このスキルが適しています。
  • ユーザーがこのスキルの対象外の対象（Azure Functions／App Service／Container Apps、従来の OpenShift node-config-operator、GKE Autopilot 固有の内容、ECS Fargate）を希望している場合。→ https://docs.dynatrace.com を参照してください。このスキルの対象は、VM／サーバー、SSH 経由のリモート VM／EC2、Windows、Kubernetes、AWS Lambda です。

References

コメント

Markdown 対応