クラスタエージェントを使用したアプリケーションの自動インストゥルメンテーション

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

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

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

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

Java
Linux 上の .NET Core
Node.js

サポートされている Kubernetes ワークロードは、Deployments、DeploymentConfigs、および StatefulSets です。

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

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

cluster-agent.yaml ファイルに設定を追加する、または
クラスタエージェント Helm チャートの values.yaml ファイルに設定を追加する。詳細については、Helm チャートを使用したクラスタエージェントのインストールを参照してください。

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

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

要件

クラスタエージェントの要件

クラスタエージェント 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対応環境」を参照してください。

- オンプレミスコントローラと通信する .NET Core および Node.js アプリケーションについては、「オンプレミスコントローラでの自動インストゥルメンテーションの使用」を参照してください。
- トランザクション分析データが必要な場合は、クラスタエージェントの analyticsHost および analyticsPort プロパティを設定する必要があります。

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

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

削除したポッドを [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 が使用されて、ポッドの削除時にコントローラ内の関連付けられたノードが履歴としてマークされます。
cluster-agent.yaml ファイルまたは Helm values.yaml ファイルに自動インストゥルメンテーションの設定を追加します。この設定により、自動インストゥルメンテーションの対象となる、Deployments、DeploymentConfigs および StatefulSets ワークロードと、使用するエージェントのタイプとバージョンが決まります。詳細については、自動インストゥルメンテーションの設定を参照してください。
設定を保存したら、クラスタエージェントの展開を適用またはアップグレードします。アプリケーションに関連付けられた展開ロールアウト戦略に基づいて、関連するポッドとコンテナが再起動されます。
```
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
自動インストゥルメンテーションの検証とトラブルシューティングについては、「Validate the Cluster Agent Installation」を参照してください。

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

設定例

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

Example 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 を使用して、アプリケーションサービスコンテナのみを自動インストゥルメント化するようにクラスタエージェントに指示し、定義されている他のコンテナは無視します。

Example 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] ダッシュボードでは、[APM Node] ダッシュボードへのリンクも [Pod Details] ページで提供されます。自動インストゥルメンテーション中に 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

Splunk AppDynamics アプリケーション名戦略

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

manual：cluster-agent.yaml ファイル内の defaultAppName または appName パラメータを使用して、アプリケーション名を設定します。
label：ワークロードの仕様のラベルをアプリケーション名として使用します。
namespace：Kubernetes 名前空間をアプリケーション名として使用します。

手動戦略

デフォルトでは appNameStrategy が manual となり、 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 がインストゥルメンテーションルールで指定されている場合は、それを使用します。

たとえば、次の仕様では、ワークロード仕様のラベル appname を使用して ecom と groceries 名前空間のアプリケーション名を設定し、ラベル app を 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: label
  appNameLabel: appname
  instrumentationRules:
    - namespaceRegex: books
      appNameLabel: app

YML

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

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

YML

名前空間戦略

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

次の仕様では、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

Splunk AppDynamics 階層名戦略

コントローラの [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 パラメータを使用します。label オプションを使用するには、tierNameLabel パラメータに値を指定します。tierNameLabel 値は、ワークロード仕様で指定されたラベルを参照します。

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

たとえば、次の仕様では、ワークロード仕様のラベル tiername を使用して ecom と groceries 名前空間の階層名を設定し、ラベル tier を 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: label
  tierNameLabel: tiername
  instrumentationRules:
    - namespaceRegex: books
      tierNameLabel: tier

YML

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

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

YML

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

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

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

要件

クラスタエージェントの要件

言語固有の要件

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

設定例

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

Splunk AppDynamics アプリケーション名戦略

手動戦略

ラベル戦略

名前空間戦略

Splunk AppDynamics 階層名戦略

手動戦略

ラベル戦略

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

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