Related pages:

このページでは、コンテナ化された環境に Node.js エージェントをインストールするオプションについて説明します。

自動インストゥルメンテーションを使用する

このシナリオは、クラスタエージェントがインストールされている Kubernetes で実行されているコンテナに適用されます。

このオプションでは、クラスタエージェントの自動インストゥルメンテーション機能を使用します。これは、KubernetesクラスタでNode.jsアプリケーションを実装するための最高レベルの自動化と最もシンプルな操作エクスペリエンスを提供するため、推奨されるオプションです。

開始するには、「クラスタエージェントを使用したアプリケーションの自動インストゥルメンテーション」を参照してください。

Init コンテナを使用する

このオプションは、Kubernetes で実行されているコンテナに適用されます。

このオプションでは、アプリケーションの起動時に、Kubernetes init コンテナを使用して Node.js エージェントバイナリをアプリケーションコンテナにコピーします。これは、Node.js エージェントバイナリのないアプリケーションイメージが構築され、Node.js エージェントバイナリを含む 2 番目の init コンテナイメージが構築されることを前提としています。アプリケーションの導入仕様が構成され、実行中のアプリケーションコンテナにエージェントバイナリをコピーして送信します。

init コンテナを使用してエージェントバイナリをコピーするには、次の手順を実行します。

  1. Node.js アプリケーションイメージの構築
  2. Node.js エージェント Init コンテナイメージの構築
  3. 導入仕様への Init コンテナの追加
  4. Node.js エージェント環境変数の設定
  5. UNIQUE_HOST_ID 環境変数の設定
  6. （オンプレミスコントローラのみ）コンテナへのコントローラ証明書のコピー

これらの手順は、NODE_OPTIONS 環境変数をサポートする Node.js バージョン 8 以降を使用してアプリケーションイメージが構築されることを前提としています。この環境変数は ConfigMap で設定されます。Node.js バージョン 7 以前の場合は、起動スクリプトを使用して appdynamics パッケージを含めるこの例を参照してください。

Node.js アプリケーションイメージの構築

アプリケーションのバイナリと依存関係に基づいて、Node.js アプリケーションイメージを構築します。Node.js エージェントのバイナリまたは設定をアプリケーションイメージに含めないでください。

Node.js エージェント Init コンテナイメージの構築

エージェント init コンテナイメージは、アプリケーションイメージとは別に構築され、複数の Node.js アプリケーションの展開時に再利用できます。 

Linux および Alpine 環境の場合、Node.js エージェントの init コンテナイメージは Dockerhub で使用できます。他のすべての展開環境の場合は、次の手順に従って init コンテナイメージを構築します。

init コンテナイメージの Node.js およびオペレーティングシステムのバージョンが、アプリケーションイメージの Node.js およびオペレーティングシステムのバージョンと一致する必要があります。これにより、npm install を実行するときに、互換性のある Node.js エージェントバイナリが選択されます。詳細については、「Node.js Supported Environments」を参照してください。

Node.js およびオペレーティングシステムのバージョンは、Dockerfile の FROM node:14.4-alpine ステートメントによって決定されます。

FROM node:14.4-alpine
…
JS


次の手順に従って、init コンテナイメージを構築します。

  1. appdynamics の require ステートメントを含む shim.js ファイルを作成します。reuseNode プロパティを true に設定します。reuseNodePrefix を、後の手順で ConfigMap で提供される環境変数の値に設定します。

    require("appdynamics").profile({
  reuseNode: true,
  reuseNodePrefix: process.env.APPDYNAMICS_AGENT_REUSE_NODE_NAME_PREFIX
});
    JS

  2. Node.js エージェントがトランザクション分析データを報告する必要がある場合は、require ステートメントに分析プロパティを追加し、後の手順で ConfigMap で提供される環境変数に値を設定します。詳細については、Node.js設定参考資料を参照してください。

    require("appdynamics").profile({
  reuseNode: true,
  reuseNodePrefix: process.env.APPDYNAMICS_AGENT_REUSE_NODE_NAME_PREFIX,
  analytics: {
    host: process.env.APPDYNAMICS_ANALYTICS_HOST_NAME,
    port: process.env.APPDYNAMICS_ANALYTICS_PORT,
    ssl: process.env.APPDYNAMICS_ANALYTICS_SSL_ENABLED  
  }
});
    JS

  3. Node.js エージェントがオンプレミスコントローラと通信する場合は、certificateFile プロパティを追加し、後の手順で cert ファイルをコピーする場所に設定します。

    require("appdynamics").profile({
  reuseNode: true,
  reuseNodePrefix: process.env.APPDYNAMICS_AGENT_REUSE_NODE_NAME_PREFIX,
  certificateFile: /opt/appdynamics/cacerts
});
    JS

  4. Dockerfile で、shim.js をイメージにコピーします。

    COPY ./shim.js /opt/appdynamics/shim.js
    JS

  5. npm install コマンドを実行して、appdynamics パッケージを解決します。

    $ cd appdynamics
$ npm install appdynamics@next
    JS

  6. Dockerfile で、appdynamics パッケージを含むフォルダの格納ファイルをイメージにコピーします。

    COPY appdynamics/ /opt/appdynamics/
    JS

マルチステージビルドを使用して Node.js エージェントの init コンテナイメージを構築する完全な例については、この Dockerfile を参照してください。

導入仕様への Init コンテナの追加

導入仕様を編集して、エージェントバイナリを init コンテナからアプリケーションイメージにコピーするために必要なセクションを追加します。

導入仕様の次のスニペットは、必須の volumes、volumeMounts、および initContainer の定義を示しています。これは、Node.js アプリケーションイメージが myrepo/nodejs-app:v1 にパブリッシュされ、init コンテナイメージが myrepo/appd-nodejs:latest にパブリッシュされることを前提としています。init コンテナイメージの shim.js ファイルがアプリケーションコンテナの /opt/appdynamics/shim.js にコピーされます。

kind: Deployment
spec:
  containers:
  - name: nodejs-app
	image: myrepo/nodejs-app:v1
    volumeMounts:
    - mountPath: /opt/appdynamics
      name: appd-agent-repo
  initContainers:
  - command:
    - cp
    - -r
    - /opt/appdynamics/.
    - /opt/temp
	name: appd-agent
    image: myrepo/appd-nodejs:latest
    volumeMounts:
    - mountPath: /opt/temp
      name: appd-agent-repo
  volumes:
    - name: appd-agent-repo
      emptyDir: {}
YML

Node.js エージェント環境変数の設定

必要なすべての Node.js エージェント環境変数を設定するには、ユースケースに応じて次のオプションを試してください。

詳細については、「Kubernetes でエージェントを設定するためのベストプラクティス」を参照してください。

ConfigMap を使用したアプリケーション サーバ エージェントの設定

  1. ConfigMap を使用して、名前空間内の Node.js アプリケーション間で共有するエージェント環境変数を設定します。たとえば、次の appd-nodejs-config.yaml スニペットを参照してください。

    apiVersion: v1
data:
  APPDYNAMICS_AGENT_APPLICATION_NAME: eCommerce
  APPDYNAMICS_AGENT_ACCOUNT_NAME: <value>
  APPDYNAMICS_CONTROLLER_HOST_NAME: <value>
  APPDYNAMICS_CONTROLLER_PORT: <value>
  APPDYNAMICS_CONTROLLER_SSL_ENABLED: <value>
  APPDYNAMICS_AGENT_REUSE_NODE_NAME_PREFIX: <value>
  APPDYNAMICS_AGENT_NODE_NAME: <value> # not used in node name but required by Node.js agent
  APPDYNAMICS_LOGGER_OUTPUT_TYPE: console
  NODE_OPTIONS: '--require /opt/appdynamics/shim.js'
  # variables required to send transaction analytics data
  APPDYNAMICS_ANALYTICS_HOST_NAME: <value>
  APPDYNAMICS_ANALYTICS_PORT: <value>
  APPDYNAMICS_ANALYTICS_SSL_ENABLED: <value>
kind: ConfigMap
metadata:
  name: appd-nodejs-config 
    YML

    Node.js 8 以降でサポートされている NODE_OPTIONS 環境変数は、init コンテナイメージからコピーされた shim.js ファイルの場所に --require オプションを設定します。分析ホスト、ポート、および ssl の設定は、分析エージェントの展開方法によって異なります。オプションについては、「Kubernetes での分析の展開」を参照してください。

  2. 名前空間に ConfigMap を適用します。

    $ kubectl -n ecommerce apply -f appd-nodejs-config.yaml 
    BASH

  3. 導入仕様を更新して ConfigMap を参照します。

    spec:
  containers:
  - name: nodejs-app
    envFrom:
    - configMapRef:
        name: appd-nodejs-config
 ...
    YML

コントローラのアクセスキーへの秘密の使用

  1. kubectl を使用して秘密を作成します。

    $ kubectl -n ecommerce create secret generic appd-agent-secret --from-literal=access-key=<access-key>
    BASH

  2. 導入仕様を更新して、秘密を参照します。

    spec:
  containers:
  - name: nodejs-app
    env:
    - name: APPDYNAMICS_AGENT_ACCOUNT_ACCESS_KEY
      valueFrom:
        secretKeyRef:
          name: appd-agent-secret
          key: access-key
 ...
    YML

導入仕様でのアプリケーション固有の設定

導入仕様でアプリケーション固有の階層名環境変数 APPDYNAMICS_AGENT_TIER_NAME を設定します。

spec:
  containers:
  - name: nodejs-app
    env:
    - name: APPDYNAMICS_AGENT_TIER_NAME
      value: nodejs-service
YML

UNIQUE_HOST_ID 環境変数の設定

UNIQUE_HOST_ID 環境変数を設定して、クラスタエージェントとの APM 相関を有効にします。この値はランタイム値に依存するため、「アプリケーション エージェントを手動で設定してクラスタエージェントと関連付ける」の値を使用してコンテナのスタートアップコマンドでこの環境変数を設定します。

Docker ランタイムを使用する Kubernetes 環境では、次の例のように環境変数を設定します。

spec:
  containers:
    command: ["/bin/sh"]
    args: ["-c", "export UNIQUE_HOST_ID=$(sed -rn '1s#.*/##; 1s/(.{12}).*/\\1/p' /proc/self/cgroup) && node /nodejsapp/myapp.js"]
YML

（オンプレミスコントローラのみ）コンテナへのコントローラ証明書のコピー

オンプレミスのコントローラ証明書が必要な場合は、ConfigMap を定義して cert ファイルを参照し、導入仕様でボリュームマウントを使用して ConfigMap の内容をコンテナにマウントします。詳細については、コントローラSSLと証明書を参照してください。

$ kubectl create configmap appd-cert --from-file=cacerts
BASH

導入仕様のスニペットに示すように、volumes と volumeMounts を使用して、コンテナファイルシステムに証明書ファイルを追加します。

kind: Deployment
spec:
  containers:
    image: myrepo/nodejs-app:v1
    volumeMounts:
    - name: appd-cert
      subPath: cacerts
      mountPath: /opt/appdynamics/cacerts
  volumes:
    - name: appd-cert
      configMap:
        name: appd-cert
YML

mountPath 値は、init コンテナイメージの構築時に使用される shim.js ファイルの certificateFile プロパティと一致する必要があります。

Init コンテナを使用するための設定例

init コンテナを使用してエージェントバイナリをコピーする完全な例については、この導入仕様を参照してください。

Dockerfile の使用

このオプションは、Docker および Kubernetes で実行されているコンテナに適用されます。

このオプションでは、Dockerfile を使用して、作成時に Node.js エージェントバイナリを Docker イメージに含めます。アプリケーションと Node.js エージェントバイナリを含む単一のイメージが構築されることを前提としています。

イメージの作成時にエージェントをアプリケーションイメージに含めるには、次の手順を実行します。

  1. Node.js エージェントのインストール手順の実行
  2. イメージへのアプリケーションフォルダのコピー
  3. Node.js エージェント環境変数の設定
  4. UNIQUE_HOST_ID 環境変数の設定
  5. （オンプレミスコントローラのみ）コントローラ証明書のイメージへのコピー

Node.js エージェントのインストール手順の実行

「Node.js エージェントのインストール」に記載されているインストール手順を実行します。

  1. NPM コマンドを実行して、アプリケーションフォルダの appdynamics パッケージを含めます。

    $ cd nodejsapp
$ npm install appdynamics@next
    JS

  2. アプリケーションのソースコードに require ステートメントを追加し、reuseNode および reuseNodePrefix プロパティを含めます。後の手順で設定する環境変数を参照するように reuseNodePrefix プロパティを設定します。

    require("appdynamics").profile({
  reuseNode: true,
  reuseNodePrefix: process.env.APPDYNAMICS_AGENT_REUSE_NODE_NAME_PREFIX
});
    JS

    再利用ノード名とプレフィックスのプロパティは、同じアプリケーションイメージの複数のコンテナインスタンスに一意の名前を付けることをサポートするために必要です。「Node.js Settings Reference」を参照してください。

  3. Node.js エージェントがトランザクション分析データを報告する必要がある場合は、require ステートメントに分析プロパティを追加し、後の手順で設定される環境変数に値を設定します。詳細については、Node.js設定参考資料を参照してください。

    require("appdynamics").profile({
  reuseNode: true,
  reuseNodePrefix: process.env.APPDYNAMICS_AGENT_REUSE_NODE_NAME_PREFIX,
  analytics: {
    host: process.env.APPDYNAMICS_ANALYTICS_HOST_NAME,
    port: process.env.APPDYNAMICS_ANALYTICS_PORT,
    ssl: process.env.APPDYNAMICS_ANALYTICS_SSL_ENABLED  
  }
});
    JS

イメージへのアプリケーションフォルダのコピー

アプリケーションフォルダをイメージにコピーするように Docker ファイルを編集します。

COPY nodejsapp/ /nodejsapp/
JS

Node.js エージェント環境変数の設定

非 Kubernetes 環境でアプリケーションを実行している場合（たとえば docker run  を使用）、Dockerfile でエージェント環境変数を設定します。次に例を示します。

ENV APPDYNAMICS_AGENT_APPLICATION_NAME=<value>
ENV APPDYNAMICS_AGENT_TIER_NAME=<value>
ENV APPDYNAMICS_AGENT_ACCOUNT_NAME=<value>
ENV APPDYNAMICS_AGENT_ACCOUNT_ACCESS_KEY=<value>
ENV APPDYNAMICS_CONTROLLER_HOST_NAME=<value>
ENV APPDYNAMICS_CONTROLLER_PORT=<value>
ENV APPDYNAMICS_CONTROLLER_SSL_ENABLED=<value>
ENV APPDYNAMICS_AGENT_REUSE_NODE_NAME_PREFIX=<value>
ENV APPDYNAMICS_AGENT_NODE_NAME=<value> # not used in node name but required by Node.js agent
ENV APPDYNAMICS_LOGGER_OUTPUT_TYPE=console
# variables required to send transaction analytics data
ENV APPDYNAMICS_ANALYTICS_HOST_NAME=<value>
ENV APPDYNAMICS_ANALYTICS_PORT=<value>
ENV APPDYNAMICS_ANALYTICS_SSL_ENABLED=<value>
YML

Kubernetes アプリケーションの場合は、これらの環境変数を Dockerfile から除外し、「Init コンテナを使用する」の説明に従って、ConfigMap、秘密、および導入仕様を使用して設定します。分析ホスト、ポート、および ssl の設定は、分析エージェントの展開方法によって異なります。オプションについては、「Kubernetes での分析の展開」を参照してください。

UNIQUE_HOST_ID 環境変数の設定

UNIQUE_HOST_ID 環境変数を設定して、クラスタエージェントとの APM 相関を有効にします。この値はランタイム値に依存するため、「アプリケーション エージェントを手動で設定してクラスタエージェントと関連付ける」に記載されている値を使用してイメージ スタートアップ スクリプトでこの環境変数を設定します。
Docker ランタイムを使用する Kubernetes 環境では、次の例のように Docker イメージに次のスタートアップスクリプト startup.sh を追加します。

#!/bin/bash
# OpenShift 3.10 or 3.11:
UNIQUE_HOST_ID=$(sed -rn '1s#.*/##; 1s/(.{12}).*/\\1/p' /proc/self/cgroup)
exec node /nodejsapp/myapp.js
BASH

（オンプレミスコントローラのみ）コントローラ証明書のイメージへのコピー

オンプレミスのコントローラと通信する Node.js エージェントの場合は、Dockerfile を編集して、オンプレミスの証明書を含む証明書ファイルをイメージにコピーします。 

例：

COPY ./onprem-cacerts /opt/appdynamics/cacerts
BASH

アプリケーションのソースコードを更新して、require ステートメントに certificateFile プロパティを追加します。certificateFile パスを証明書ファイルの場所に設定します。

require("appdynamics").profile({
  reuseNode: true,
  reuseNodePrefix: process.env.APPDYNAMICS_AGENT_REUSE_NODE_NAME_PREFIX,
  certificateFile: /opt/appdynamics/cacerts
});
BASH