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

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

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

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

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

Java
Linux 上の .NET Core
Node.js

次の Kubernetes ワークロードをサポートしています。Deployments、DeploymentConfigs、StatefulSets

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

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

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

その後、kubectl を使用して変更を適用するか、クラスタエージェント Helm チャートをアップグレードします。

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

要　件

AppDynamics の要件

クラスタエージェント 20.5 以降。詳細については、クラスタエージェントの要件およびサポート対象環境を参照してください。
クラスタに最新バージョンのクラスタエージェントとオペレータがインストールされている。cluster-agent-operator.yaml で、クラスタエージェントが自動インストゥルメンテーションを実行するために必要な権限が設定されている。詳細については、クラスタエージェントのインストールを参照してください。
以前に必須の AppDynamics エージェントでインストゥルメント化されなかったアプリケーションが 1 つ以上クラスタに展開されている。
自動インストゥルメント化されるアプリケーションの数に基づいた十分なエージェントライセンスがコントローラにある。
ポッドの再起動を処理するのに十分なクラスタ容量があることを確認する。「ポッドの再起動の影響を最小化」を参照してください。
アプリケーション、階層、およびノード名のタプルがすべての 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 になります。AppDynamics Docker Hub ページを参照してください。
```
apiVersion: 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 を追加します。コントローラで api-user 値を Administrator ロールを持つローカルユーザに設定します。
```
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
クラスタエージェントで 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
自動インストゥルメンテーションの検証とトラブルシューティングについては、「クラスタエージェントのインストールの検証」を参照してください。

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

設定例

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

Example 1: cluster-agent-auto-1.yaml

apiVersion: appdynamics.com/v1alpha1
kind: Clusteragent
metadata:
  name: k8s-cluster-agent
  namespace: appdynamics
spec:
  appName: "<app-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: appdynamics.com/v1alpha1
kind: Clusteragent
metadata:
  name: k8s-cluster-agent
  namespace: appdynamics
spec:
  appName: "<app-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 で自動インストゥルメント化されることを示しています。

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

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: 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: 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: 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

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

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