このページでは、クラスタエージェントが展開されているクラスタで実行されている Kubernetes ワークロードを自動でインストゥルメント化する方法について説明します。「クラスタエージェントのインストール」を参照してください。

インストゥルメンテーション オプションについては、「コンテナのインストールオプション」を参照してください。 

操作を簡素化するため、自動インストゥルメンテーションの使用を推奨します。

自動インストゥルメンテーションでは、次のアプリケーションタイプのワークロードにアプリケーション サーバ エージェントを動的に追加できます。

  • Java
  • Linux 上の .NET Core
  • Node.js

サポート対象となる Kubernetes ワークロードは、Deployments、DeploymentConfigs、StatefulSets です。

自動インストゥルメンテーションの概要

自動インストゥルメンテーションを有効にするには、次の操作を行います。

次に、kubectl を使用して変更を適用するか、クラスタエージェントの Helm チャートをアップグレードすることができます。

クラスタエージェントがサポートされているワークロードを検出し、そのワークロードが設定された自動インストゥルメンテーション ルールと一致すると、クラスタエージェントは Kubernetes API を使用してワークロードの仕様を変更します。クラスタエージェントは、Splunk AppDynamics .NET Core、Node.js、または Java エージェントイメージを含む init コンテナをワークロードにアタッチします。ボリュームに appd というプレフィックスが付いている場合、クラスタエージェントはワークロードからボリュームを削除して、次の自動インストゥルメンテーション中にエラーが発生しないようにします。アプリケーションが再起動すると、必須エージェントがアプリケーションコンテナにコピーされます。これで、アプリケーションコンテナが自動インストゥルメント化されたアプリケーションで Splunk AppDynamics エージェント（Node.js エージェント、Linux エージェント上の .NET Core、または Java エージェント）を参照するようになります。 

要件

Splunk AppDynamics の要件

  • クラスタエージェント 20.5 以降。「クラスタエージェントの要件およびサポート対象環境」を参照してください。

  • クラスタに最新バージョンのクラスタエージェントとオペレータがインストールされている。cluster-agent-operator.yaml で、クラスタエージェントが自動インストゥルメンテーションを実行するために必要な権限を設定します。「クラスタエージェントのインストール」を参照してください。
  • 以前に必須の Splunk AppDynamics エージェントでインストゥルメント化されなかったアプリケーションが 1 つ以上クラスタに展開されている。
  • 自動インストゥルメント化されるアプリケーションの数に基づいた十分なエージェントライセンスがコントローラにある。
  • [Server Monitoring Administrator] ロールがあるコントローラでローカルユーザーを作成する。クラスタエージェントで、このユーザーのログイン情報が使用されて、自動インストゥルメント化されたポッドが削除されたときにノードが履歴としてマークされます。これらのログイン情報を使用して、クラスタエージェントの自動インストゥルメンテーションを有効にする際の最初の手順で api-user を設定します。Helm チャートを使用して自動インストゥルメンテーションを有効にする場合、これらのログイン情報を使用してユーザー名とパスワードの値を設定することもできます。
  • ポッドの再起動を処理するのに十分なクラスタ容量があることを確認する。「ポッドの再起動の影響を最小化」を参照してください。
  • アプリケーション、階層、およびノード名のタプルがすべての Kubernetes インスタンスで一意になるように指定したことを確認する。名前が一意でない場合、ノードが適切にレポートされない可能性があります。これは、Java エージェントや Node.js エージェントなどの、アプリケーション、階層、およびノードの一意性が必要なエージェントに適用されます。

言語固有の要件

  • Node.js 8.6 以降

  • Java
    • Java アプリケーションで、環境変数を使用して Java コマンドに -javaagent 引数を含めるようサポートしている必要があります。デフォルトでは、クラスタエージェントで JAVA_TOOL_OPTIONS を使用します。ただし、defaultEnv プロパティを使用してこれを変更できます。
    • Java エージェントのリソース要件に基づいて、アプリケーションポッドに設定されるメモリの要求または制限を調整する必要が生じる場合があります（「Javaエージェントのインストール」を参照）。
  • Linux 上の .NET Core および Node.js

    • アプリケーション ベース イメージのオペレーティング システム（OS）がアプリケーション サーバ エージェント ベース イメージ OS と一致することを確認します（Linux と Alpine）。たとえば、Linux 上の .NET Core アプリケーションで Ubuntu のベースイメージを使用している場合は、imageInfo.image タグを Linux バージョンに設定する必要があります。この例のイメージタグは、20.11.0-linux です。
      アプリケーションで Alpine Linux ベースイメージ OS を使用していた場合、タグは 20.11.0-alpine になります。Docker Hub ページを参照してください。

      apiVersion: cluster.appdynamics.com/v1alpha1 kind: Clusteragent metadata: name: k8s-cluster-agent namespace: appdynamics spec: # content removed for brevity instrumentationRules: - namespaceRegex: dev language: dotnetcore appName: MyDotNetAppOnUbuntu imageInfo: image: "docker.io/appdynamics/dotnet-core-agent:20.11.0-linux" agentMountPath: /opt/appdynamics
      YML

      ベースイメージのオペレーティングシステムが一致しないと、アプリケーション サーバ エージェントが起動しない可能性があります。「自動インストゥルメンテーションの検証」を参照してください。Node.js エージェントにも、エージェントの起動を妨げる可能性がある特定の Node.js ランタイム要件があります。Node.js Supported Environmentsを参照してください。

クラスタエージェントの自動インストゥルメンテーションの有効化

クラスタエージェント機能を設定するには、次の手順を実行します。

  1. 削除したポッドを [Tiers & Nodes] コントローラダッシュボードから削除します。次に、「クラスタエージェントのインストール」で作成した cluster-agent-secret を再作成して、api-user を追加します。

    kubectl -n appdynamics delete secret cluster-agent-secret kubectl -n appdynamics create secret generic cluster-agent-secret --from-literal=controller-key=<access-key> --from-literal=api-user="<username>@<customer>:<password>"
    CODE

    [Server Monitoring Administrator] ロールがあるコントローラから、ローカルユーザーに api-user 値を設定します。クラスタエージェントで api-user が使用されて、ポッドの削除時にコントローラ内の関連付けられたノードが履歴としてマークされます。

     

  2. cluster-agent.yaml ファイルまたは Helm の values.yaml ファイルに自動インストゥルメンテーションの設定を追加します。この設定により、自動インストゥルメンテーションの対象となる Deployments、DeploymentConfigs、および StatefulSets ワークロードと、使用するエージェントのタイプとバージョンが決まります。「自動インストゥルメンテーションの設定」を参照してください。

  3. 設定を保存したら、クラスタエージェントの展開を適用またはアップグレードします。アプリケーションに関連付けられた展開ロールアウト戦略に基づいて、関連するポッドとコンテナが再起動されます。

    kubectl apply -f cluster-agent.yaml
    BASH 
    helm upgrade -f ./ca1-values.yaml "<my-cluster-agent-helm-release>" appdynamics-charts/cluster-agent --namespace appdynamics
    BASH


    自動インストゥルメンテーションの検証とトラブルシューティングについては、「クラスタエージェントのインストールの検証」を参照してください。

  • ワークロードが instrumentationRules 内で定義されたプロパティと一致しない場合、自動インストゥルメンテーションは有効になりません。 
  • 自動インストゥルメンテーション プロパティがデフォルトでまたは instrumentationRules で定義されていない場合、クラスタエージェントは「自動インストゥルメンテーションの設定」で指定される、対応するデフォルト値を使用します。対応するデフォルト値がない場合、自動インストゥルメンテーションは有効になりません。

設定例

例 1 は、ecom.* パターンに一致する名前空間の Java アプリケーションをターゲットとしています。一致する各アプリケーションは 20.20.1 Java エージェントでインストゥルメント化され、コントローラの Ecommerce アプリケーションにレポートされます。デフォルトでは、階層名は Kubernetes ワークロードの名前ですが、tierName プロパティを設定することでオーバーライドできます。

例 1：cluster-agent-auto-1.yaml

apiVersion: cluster.appdynamics.com/v1alpha1 kind: Clusteragent metadata: name: k8s-cluster-agent namespace: appdynamics spec: appName: "<cluster-name>" controllerUrl: "<protocol>://<appdynamics-controller-host>:8080" account: "<account-name>" image: "docker.io/appdynamics/cluster-agent:20.12.1" serviceAccountName: appdynamics-cluster-agent nsToMonitorRegex: ecom.* # # auto-instrumentation config # instrumentationMethod: Env nsToInstrumentRegex: ecom.* defaultAppName: Ecommerce instrumentationRules: - language: java imageInfo: image: docker.io/appdynamics/java-agent:20.20.1 agentMountPath: /opt/appdynamics
YML


例 2 は、Java アプリケーションと Linux 上の .NET Core アプリケーションを含む名前空間をターゲットとし、次の詳細設定を組み込みます。

  • Java アプリケーションと Linux 上の .NET Core アプリケーションをターゲットに、複数の instrumentationRules を使用します。
  • labelMatch 戦略を使用し、以下のワークロード仕様 auto-instrumented-dotnet-app.yaml および auto-instrumented-java-app.yaml の framework ラベルの値に基づいてエージェントタイプと関連するエージェントイメージを決定します。
  • この設定では、YAML ファイルでコントローラのアプリケーション名を割り当てるのではなく、設定で appNameStrategy: label を使用し、ワークロード仕様のラベルに基づいてアプリケーション名を割り当てます。
  • Java アプリケーションの場合は、instrumentContainer: select および containerMatchString: .*service を使用して、アプリケーション サービス コンテナのみを自動インストゥルメント化するようにクラスタエージェントに指示し、定義されている他のコンテナは無視します。

例 2：cluster-agent-auto-2.yaml

apiVersion: cluster.appdynamics.com/v1alpha1 kind: Clusteragent metadata: name: k8s-cluster-agent namespace: appdynamics spec: appName: "<cluster-name>" controllerUrl: "<protocol>://<appdynamics-controller-host>:8080" account: "<account-name>" image: "docker.io/appdynamics/cluster-agent:20.12.1" serviceAccountName: appdynamics-cluster-agent nsToMonitorRegex: ecom.* # # auto-instrumentation config # instrumentationMethod: Env nsToInstrumentRegex: stage appNameStrategy: label instrumentationRules: - namespaceRegex: stage language: dotnetcore labelMatch: - framework: dotnetcore appNameLabel: appName imageInfo: image: "docker.io/appdynamics/dotnet-core-agent:20.11.0-linux" agentMountPath: /opt/appdynamics - namespaceRegex: stage language: java labelMatch: - framework: java appNameLabel: appName instrumentContainer: select containerMatchString: .*service imageInfo: image: "docker.io/appdynamics/java-agent:21.3.0" agentMountPath: /opt/appdynamics
YML

例 3 および例 4 は、.NET および Java サービスの導入仕様を示しています。これらは、cluster-agent-auto-2.yaml: の自動インストゥルメンテーション設定に基づいて appName およびフレームワークラベルを定義します。

.NET

apiVersion: apps/v1 kind: Deployment metadata: name: dotnet-profile-service labels: appName: backend-services framework: dotnetcore spec: containers: - image: myrepo/profile-service:v2 name: profile-service # ...
YML

Java

apiVersion: apps/v1 kind: Deployment metadata: name: java-account-service labels: appName: backend-services framework: java spec: containers: - image: myrepo/account-service:v2 name: account-service - image: myrepo/proxy-util:v1 name: proxy-util # ...
YML

cluster-agent-auto-2.yaml の containerMatchString 値は、account-service コンテナのみが auto-instrumented-java-app.yaml で自動インストゥルメント化されることを示します。

その他の設定例については、「自動インストゥルメンテーションの構成例」を参照してください。

アプリケーションコンテナとアプリケーション エージェントの関連付け（Kubernetes バージョン 1.25 以上）

エージェントとのアプリケーション相関を確立すると、[Application/Container] ビューでモニター対象のアプリケーションコンテナがコントローラに表示されます。[Cluster Agent Pod] ダッシュボードには、[Pod Details] ページの [APM Node] ダッシュボードへのリンクもあります。自動インストゥルメンテーション中に APM とコンテナの相関を有効にするには、構成ファイルの spec セクションで containerAppCorrelationMethod プロパティを構成する必要があります。Kubernetes 1.25 以降では、cgroup v1 ランタイムのサポートが cgroup v2 対応ランタイムに置き換えられているため、このプロパティは Kubernetes 1.25 以降を使用する環境に適用されます。

相関方式には、次のいずれかの値を選択できます。

  • proxy（推奨）：これがデフォルト値です。この値を指定すると、アプリケーション エージェントはクラスタエージェントからコンテナ ID をクエリします。 
  • kubeapi：この値を指定すると、アプリケーション エージェントは Kubernetes API サーバーからコンテナ ID をクエリします。ただし、この方法を使用するには、追加の権限が必要です。権限の詳細については、「Kubernetes API サーバーからのクエリに必要な権限」を参照してください。

  • none：この値を指定すると、相関関係はありません。

例：

apiVersion: cluster.appdynamics.com/v1alpha1 kind: Clusteragent metadata: name: k8s-cluster-agent namespace: appdynamics spec:  containerAppCorrelationMethod: proxy appName: "<cluster-name>" controllerUrl: "<protocol>://<appdynamics-controller-host>:8080" account: "<account-name>" image: "docker.io/appdynamics/cluster-agent:20.12.1" serviceAccountName: appdynamics-cluster-agent nsToMonitorRegex: ecom.* # # auto-instrumentation config # instrumentationMethod: Env nsToInstrumentRegex: ecom.* defaultAppName: Ecommerce instrumentationRules: - language: java imageInfo: image: docker.io/appdynamics/java-agent:20.20.1 agentMountPath: /opt/appdynamics
YML

Kubernetes API サーバーからコンテナ ID をクエリするために必要な権限

containerAppCorrelationMethod プロパティが kubeapi として指定されている場合、次の権限が必要です。

apiGroupsリソース権限
""serviceaccounts
  • get
  • create
  • delete
rbac.authorization.k8s.io
  •  roles
  • rolebindings 
  • get
  • create 
  • update
  • delete

アプリケーション名戦略

コントローラのアプリケーション ダッシュボードでは、3 つのアプリケーション名戦略を提供しています。次のいずれかの値に appNameStrategy プロパティを割り当てて、戦略を選択します。

  • manual：cluster-agent.yaml ファイル内の defaultAppName または appName パラメータを使用して、アプリケーション名を設定します。

  • label：ワークロードの仕様のラベルをアプリケーション名として使用します。

  • namespace：Kubernetes 名前空間をアプリケーション名として使用します。

手動戦略

デフォルトでは appNameStrategy が手動となり、defaultAppName または appName パラメータを使用してアプリケーション名を設定します。

  • defaultAppName が指定されている場合は、インストゥルメンテーション ルールで上書きされない限り、これを使用します。
  • appName がインストゥルメンテーション ルールで指定されている場合は、それを使用します。

たとえば、次の仕様で、ECommerce は ecom および groceries 名前空間に適用されるデフォルトのアプリケーション名であり、BookStore は books 名前空間に適用されるアプリケーション名です。

apiVersion: cluster.appdynamics.com/v1alpha1 kind: Clusteragent metadata: name: k8s-cluster-agent namespace: appdynamics spec: appName: "<cluster-name>" # ... # auto-instrumentation config instrumentationMethod: Env nsToInstrumentRegex: ecom|books|groceries appNameStrategy: manual defaultAppName: ECommerce instrumentationRules: - namespaceRegex: books appName: BookStore
YML

ラベル戦略

このオプションでは、アプリケーション名の戦略として label パラメータを使用します。ラベルオプションを使用するには、appNameLabel パラメータに値を指定します。appNameLabel 値は、ワークロード仕様で指定されたラベルを参照します。  

  • Spec.appNameLabel が指定されている場合は、仕様レベルの値が使用されます。
  • インストゥルメンテーション ルールで appNameLabel が指定されている場合は、仕様で別の appNameLabel が指定されていない限り、その値が使用されます。
  • インストゥルメンテーション ルールで指定された appNameLabel が展開の仕様で見つからない場合は、仕様レベルの appNameLabel 値が使用されます。

次の仕様例では、appNameLabel: app がインストゥルメンテーション ルールで使用されていますが、展開の仕様には app ラベルがありません。仕様には、値が eCommerce の appname というラベルがあります。
したがって、コントローラには eCommerce アプリケーションにレポートするデータが表示されます。

次の仕様では、ワークロード仕様のラベル appname を使用して ecom および groceries 名前空間のアプリケーション名を設定し、books 名前空間で app ラベルが使用されます。

apiVersion: cluster.appdynamics.com/v1alpha1 kind: Clusteragent metadata: name: k8s-cluster-agent namespace: appdynamics spec: appName: "<cluster-name>" # ... # auto-instrumentation config instrumentationMethod: Env nsToInstrumentRegex: ecom|books|groceries appNameStrategy: label appNameLabel: appname instrumentationRules: - namespaceRegex: books appNameLabel: app
YML

次の導入仕様のスニペットに示すように、appname ラベルを設定する ecom または groceries 名前空間に導入されたアプリケーションの場合、コントローラのアプリケーション ダッシュボードで eCommerce アプリケーションにレポートされます。

apiVersion: apps/v1 kind: Deployment metadata: name: ecom-app labels: appname: eCommerce spec: ...
YML

名前空間戦略

このオプションで Kubernetes の namespace パラメータをアプリケーション名戦略として使用すると、コントローラのアプリケーション ダッシュボードでアプリケーションが展開されている名前空間名をアプリケーション名として使用できます。

次の仕様では、ecom、books、および groceries 名前空間の各アプリケーションで、展開先の名前空間に基づいてアプリケーション名を使用します。

apiVersion: cluster.appdynamics.com/v1alpha1 kind: Clusteragent metadata: name: k8s-cluster-agent namespace: appdynamics spec: appName: "<cluster-name>" # ... # auto-instrumentation config instrumentationMethod: Env nsToInstrumentRegex: ecom|books|groceries appNameStrategy: namespace
YML

階層名戦略

コントローラの [Application Dashboard] > [Tiers and Nodes] では、2 つの階層名戦略を提供しています。次のいずれかの値に tierNameStrategy プロパティを割り当てて、戦略を選択します。

  • manual：cluster-agent.yaml ファイル内の tierName パラメータを使用して、階層名を設定します。

  • label：ワークロードの仕様のラベルを階層名として使用します。

手動戦略

デフォルトでは tierNameStrategy が手動となり、デプロイメント名または tierName パラメータを使用して階層名を設定します。

  • tierName が指定されていない場合は、デプロイメント名に tiername を使用します。
  • tierName がインストゥルメンテーション ルールで指定されている場合は、それを使用します。


たとえば、この仕様では、<deployment name> は、ecom および groceries 名前空間に適用されるデフォルトの階層名であり、BookStore は books 名前空間に適用される階層名です。

apiVersion: cluster.appdynamics.com/v1alpha1 kind: Clusteragent metadata: name: k8s-cluster-agent namespace: appdynamics spec: appName: "<cluster-name>" # ... # auto-instrumentation config instrumentationMethod: Env nsToInstrumentRegex: ecom|books|groceries tierNameStrategy: manual instrumentationRules: - namespaceRegex: books tierName: BookStore
YML

ラベル戦略

このオプションでは、階層名の戦略として label パラメータを使用します。ラベルオプションを使用するには、tierNameLabel パラメータに値を指定します。tierNameLabel 値は、ワークロード仕様で指定されたラベルを参照します。

  • spec.tierNameLabel が指定されている場合は、インストゥルメンテーション ルールで上書きされない限り、これを使用します。
  • tierNameLabel がインストゥルメンテーション ルールで指定されている場合は、それを使用します。

たとえば、次の仕様では、ワークロード仕様のラベル tiername を使用して ecom および groceries 名前空間の階層名を設定し、books 名前空間で tier ラベルが使用されます。

apiVersion: cluster.appdynamics.com/v1alpha1 kind: Clusteragent metadata: name: k8s-cluster-agent namespace: appdynamics spec: appName: "<cluster-name>" # ... # auto-instrumentation config instrumentationMethod: Env nsToInstrumentRegex: ecom|books|groceries tierNameStrategy: label tierNameLabel: tiername instrumentationRules: - namespaceRegex: books tierNameLabel: tier
YML

次の導入仕様のスニペットに示すように、tiername ラベルを設定する ecom または groceries 名前空間に導入されたアプリケーションの場合、コントローラのダッシュボードで eCommerce 階層にレポートされます。

apiVersion: apps/v1 kind: Deployment metadata: name: ecom-app labels: tiername: eCommerce spec: ...
YML

ポッドの再起動の影響を最小化

自動インストゥルメンテーションを有効にすると、ワークロードに関連付けられた展開ロールアウト戦略に基づいて、関連するポッドが再起動されます。ポッドを再起動すると、CPU とメモリの使用率が急上昇し、パフォーマンスに悪影響を与えたり、使用可能な容量を使い果たしたりすることがよくあります。ポッドの再起動に対応するには、影響を受ける名前空間に関連付けられているメモリと CPU クォータを増やす必要があります。多数のポッドの再起動による影響を軽減するため、クラスタエージェントではデフォルトで 2 つの同時自動インストゥルメンテーション タスクのみを許可しています。後続のワークロード（resourcesToInstrument）は、インストゥルメント化されたワークロードのロールアウト後に自動インストゥルメント化されます。ただし、パラメータ numberOfTaskWorkers を設定し、クラスタの要件に基づいて同時自動インストゥルメンテーション タスクの数を指定できます。