すべてのプロダクト
Search
ドキュメントセンター

Application Real-Time Monitoring Service:ack-onepilot コンポーネントを使用した Container Service for Kubernetes (ACK) および Container Compute Service (ACS) 向け Python エージェントのインストール

最終更新日:Nov 09, 2025

Container Service for Kubernetes (ACK) および Container Compute Service (ACS) にデプロイされた Python アプリケーションをモニターするには、Application Real-Time Monitoring Service (ARMS) の ack-onepilot コンポーネントをインストールし、対応する Dockerfile を変更する必要があります。これにより、ARMS コンソールでアプリケーションのトポロジー、API 呼び出し、呼び出しトレース分析などのモニタリングデータを表示できます。このトピックでは、Container Service for Kubernetes (ACK) および Container Compute Service (ACS) にデプロイされた Python アプリケーションにエージェントをインストールする方法について説明します。

説明
  • Python エージェントの使用中に質問がある場合は、「Python エージェントに関するよくある質問」をご参照ください。このドキュメントで問題が解決しない場合は、DingTalk グループ (ID: 159215000379) を通じてお問い合わせください。

  • Python エージェントの最新機能を使用できるように、aliyun-bootstrap コンポーネントまたは非侵入型のインストール方法を使用するたびに、デフォルトで最新バージョンのエージェントがインストールされます。エージェントのバージョンを手動で指定するには、「Python エージェントに関するよくある質問」の「特定のリージョンとバージョンのエージェントをインストールするにはどうすればよいですか?」セクションをご参照ください。

前提条件

注意

  • アプリケーションが uvicorn で起動する場合は、次のいずれかの構成方法を選択してください。

    • 方法 1: uvicorn エントリファイルの最初の行に次の文を追加して、Python エージェントをインポートします。

      from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize
    • 方法 2: uvicorn を gunicorn に置き換え、gunicorn コマンドに aliyun-instrument プレフィックスを追加します。

      例:

      uvicorn app:app --workers 4 --port=9090 --host 0.0.0.0

      コマンドを次のように変更します。

      aliyun-instrument gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 app:app
      説明

      aliyun-instrument 命令は、ARMS Python エージェントの初期化と非侵入型イベントトラッキングを処理します。

  • アプリケーションが uWSGI で起動する場合は、「uWSGI で起動する Django または Flask プロジェクトに Python エージェントをインストールする」をご参照ください。

  • gevent コルーチンを使用する場合は、GEVENT_ENABLE=true 環境変数を設定する必要があります。

    たとえば、プログラムに次のコードが含まれている場合:

    from gevent import monkey
    monkey.patch_all()

    次のように環境変数を設定する必要があります。

    GEVENT_ENABLE=true

ステップ 1: ARMS エージェントインストーラー (ack-onepilot) のインストール

  1. ACK コンソールにログインします。 [クラスター] ページで、クラスターの名前をクリックします。

  2. 左側のナビゲーションウィンドウで、[コンポーネント管理] をクリックします。右上隅で ack-onepilot を検索します。

    重要

    ack-onepilot のバージョンが 3.2.4 以降であることを確認してください。

  3. ack-onepilot カードの [インストール] をクリックします。

    説明

    デフォルトでは、ack-onepilot コンポーネントは 1,000 個の Pod をサポートします。クラスターに 1,000 個の Pod を追加するごとに、コンポーネントに 0.5 CPU コアと 512 MB のメモリを追加する必要があります。

  4. 表示されるダイアログボックスで、パラメーターを構成し、[OK] をクリックします。デフォルト値を使用することをお勧めします。

    説明

    ack-onepilot をインストールした後、[アドオン] ページでスペックアップ、構成、またはアンインストールできます。

  5. 重要

    インストールした ack-onepilot コンポーネントのバージョンが 5.0.0 より後の場合は、ステップ 2 をスキップしてステップ 3 に進むことができます。これにより、Python アプリケーションに完全に非侵入型のインストールエクスペリエンスが提供されます。

ステップ 2: Dockerfile の変更

  1. Python Package Index (PyPI) リポジトリからエージェントインストーラーをダウンロードします。

    pip3 install aliyun-bootstrap
  2. aliyun-bootstrap を使用してエージェントをインストールします。

    # Alibaba Cloud アカウントのリージョン ID。
    ARMS_REGION_ID=xxx aliyun-bootstrap -a install
    説明

    特定のバージョンの Python エージェントをインストールするには、次のコマンドを実行します。

    # ${version} を実際のバージョン番号に置き換えます。
    aliyun-bootstrap -a install -v ${version}

    リリースされたすべての Python エージェントのバージョンに関する詳細については、「Python エージェントのリリースノート」をご参照ください。

  3. ARMS Python エージェントを使用してアプリケーションを起動します。

    aliyun-instrument python app.py
  4. イメージをビルドします。

次のコードは、Dockerfile の完全な例です。

    変更前の Dockerfile

    # Python 3.10 ベースイメージを使用します。
    FROM docker.m.daocloud.io/python:3.10
    
    # 作業ディレクトリを設定します。
    WORKDIR /app
    
    # requirements.txt ファイルを作業ディレクトリにコピーします。
    COPY requirements.txt .
    
    # pip を使用して依存関係をインストールします。
    RUN pip install --no-cache-dir -r requirements.txt
    
    COPY ./app.py /app/app.py
    # コンテナーのポート 8000 を公開します。
    EXPOSE 8000
    CMD ["python","app.py"]

    変更後の Dockerfile

    # 公式の Python 3.10 ベースイメージを使用します。
    FROM docker.m.daocloud.io/python:3.10
    
    # 作業ディレクトリを設定します。
    WORKDIR /app
    
    # requirements.txt ファイルを作業ディレクトリにコピーします。
    COPY requirements.txt .
    
    # pip を使用して依存関係をインストールします。
    RUN pip install --no-cache-dir -r requirements.txt
    #########################Aliyun Python エージェントをインストールします###############################
    # Alibaba Cloud アカウントのリージョン ID。
    RUN pip3 install aliyun-bootstrap && ARMS_REGION_ID=xxx aliyun-bootstrap -a install 
    ##########################################################
    
    COPY ./app.py /app/app.py
    
    
    # コンテナーのポート 8000 を公開します。
    EXPOSE 8000
    #########################################################
    CMD ["aliyun-instrument","python","app.py"]

ステップ 3: ARMS リソースへのアクセス権限の付与

ACK マネージドクラスター

ACK マネージドクラスターに ARMS Addon Token が存在しない場合は、ARMS リソースにアクセスするための権限を手動で付与します。ARMS Addon Token がすでに存在する場合は、ステップ 4 に進みます。

クラスターに ARMS Addon Token が存在するかどうかの確認

  1. ACK コンソールにログインします。左側のナビゲーションウィンドウで、クラスターをクリックします。[クラスター] ページで、クラスターの名前をクリックしてクラスター詳細ページに移動します。

  2. 左側のナビゲーションウィンドウで、[設定] > [シークレット] を選択します。ページの上部で、[名前空間] ドロップダウンリストから kube-system を選択し、[シークレット] ページに addon.arms.token が表示されるかどうかを確認します。

説明

クラスターに ARMS Addon Token がある場合、ARMS はクラスターに対してパスワードなしの権限付与を実行します。一部の ACK マネージドクラスターには ARMS Addon Token が存在しない場合があります。ARMS を使用してクラスター内のアプリケーションをモニターする前に、ACK マネージドクラスターに ARMS Addon Token があるかどうかを確認することをお勧めします。クラスターに ARMS Addon Token がない場合は、クラスターに ARMS へのアクセスを承認する必要があります。

権限ポリシーの手動追加

  1. ACK コンソールにログインします。左側のナビゲーションウィンドウで、クラスターをクリックします。[クラスター] ページで、クラスターの名前をクリックします。

  2. [クラスター情報] ページの [基本情報] タブで、[クラスターリソース] セクションの [ワーカー RAM ロール] の横にあるリンクをクリックします。

  3. 表示されたページの [権限] タブで、[権限の付与] をクリックします。

  4. [権限の付与] パネルで、次のポリシーを追加し、[権限の付与] をクリックします。

    • AliyunTracingAnalysisFullAccess: Managed Service for OpenTelemetry へのフルアクセス。

    • AliyunARMSFullAccess: ARMS へのフルアクセス。

ACK 専用クラスター/登録済みクラスター

ACK 専用クラスターまたは登録済みクラスターにデプロイされたアプリケーションをモニターするには、AliyunARMSFullAccess および AliyunSTSAssumeRoleAccess 権限がResouce Access Management (RAM) ユーザーに付与されていることを確認してください。

ack-onepilot コンポーネントをインストールした後、アカウントの AccessKey ID と AccessKey Secret を ack-onepilot の構成ファイルに入力します。

方法 1: Helm での入力

  1. ACK コンソールにログインします。左のナビゲーションウィンドウで、クラスターをクリックします。

  2. [クラスター] ページで、管理するクラスターをクリックします。表示されるページの左側のナビゲーションウィンドウで、[アプリケーション] > [Helm] を選択します。次に、ack-onepilot の横にある [更新] をクリックします。

  3. accessKeyaccessKeySecret をアカウントの AccessKey ID と AccessKey Secret に置き換え、[OK] をクリックします。

    説明

    AccessKey Secret は、Alibaba Cloud AccessKey ペアの初回作成時にのみ表示され、その後は取得できません。この設計により、漏洩リスクが軽減されます。Secret はすぐに安全に保管してください。

    image

  4. デプロイメントを再起動します。

方法 2: Kubernetes Secret を介したインポート

  1. ACK コンソールにログインします。左側のナビゲーションウィンドウで、クラスターをクリックします。

  2. [クラスター] ページで、管理するクラスターをクリックします。表示されるページの左側のナビゲーションウィンドウで、[設定] > [シークレット] を選択します。

  3. [作成] をクリックします。表示されるパネルで [追加] をクリックし、ack-onepilot の AccessKey ID と AccessKey Secret を追加します。

    説明

    AccessKey Secret は、Alibaba Cloud AccessKey ペアの初回作成時にのみ表示され、その後は取得できません。この設計により、漏洩リスクが軽減されます。Secret はすぐに安全に保管してください。

    image

  4. 左側のナビゲーションウィンドウで、[ワークロード] > [デプロイメント] を選択します。表示されるページで、ack-onepilot コンポーネントをクリックします。通常、ack-onepilot 名前空間では ack-onepilot-ack-onepilot という名前です。

  5. 表示されるページの右上隅で、[編集] をクリックします。

  6. [環境] セクションが表示されるまで下にスクロールします。[追加] をクリックし、環境変数 ONE_PILOT_ACCESSKEYONE_PILOT_ACCESSKEY_SECRET を追加し、Kubernetes Secret の Secret を参照して、[OK] をクリックします。

    image

ASK/ECI クラスター

サーバーレス Kubernetes (ASK) クラスター内のアプリケーション、または Elastic Container Instance に接続された Kubernetes クラスター内のアプリケーションをモニターするには、まず クラウドリソースアクセス承認ページでクラスターに ARMS へのアクセスを承認する必要があります。次に、ack-onepilot コンポーネントがデプロイされているすべての Pod を再起動します。

ステップ 4: Python アプリケーションの ARMS アプリケーションモニタリングを有効にする

重要
  • インストールした ack-onepilot コンポーネントのバージョンが 5.0.0 より後の場合、このステップでコンポーネントが Python エージェントパッケージを自動的にダウンロードして挿入します。Dockerfile の起動コマンドを手動で変更する必要はありません。これにより、完全に非侵入型のインストールエクスペリエンスが提供されます。

  • Python エージェントパッケージは、init コンテナーによってダウンロードおよび挿入されます。デフォルトでは、init コンテナーは 0.5 コアと 250 MB のリソースを消費し、その実行には約 10 秒かかる場合があります。これらのリソースは、初期化が完了した後に解放されます。次の環境変数を使用して、init コンテナーのリソースクォータを調整して実行速度を変更できます。

    • PYTHON_INIT_RESOURCE_REQUESTS_CPU: Python アプリケーション init コンテナーの CPU リクエスト。例: 500m。

    • PYTHON_INIT_RESOURCE_REQUESTS_MEM: Python アプリケーション init コンテナーのメモリリクエスト。例: 250Mi。

    • PYTHON_INIT_RESOURCE_LIMIT_CPU: Python アプリケーション init コンテナーの CPU 制限。例: 1000m。

    • PYTHON_INIT_RESOURCE_LIMIT_MEM: Python アプリケーション init コンテナーのメモリ制限。例: 500Mi。

  • この機能はベータ版です。この非侵入型挿入機能の使用中に質問がある場合は、DingTalk グループ (ID: 159215000379) を通じてお問い合わせください。

次のテンプレートは、ステートレスアプリケーション (デプロイメント) を作成し、ARMS アプリケーションモニタリングを有効にするための完全な YAML の例です。

完全なサンプル YAML ファイル (Python) を表示

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: arms-python-client
  name: arms-python-client
  namespace: arms-demo
spec:
  progressDeadlineSeconds: 600
  replicas: 1
  revisionHistoryLimit: 10
  selector:
    matchLabels:
      app: arms-python-client
  strategy:
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
    type: RollingUpdate
  template:
    metadata:
      labels:
        app: arms-python-client
        aliyun.com/app-language: python # Python アプリケーションに必須。これが Python アプリケーションであることを指定します。
        armsPilotAutoEnable: 'on'
        armsPilotCreateAppName: "arms-python-client"    # ARMS でのアプリケーションの表示名。
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/arms-default/python-agent:arms-python-client
          imagePullPolicy: Always
          name: client
          resources:
            requests:
              cpu: 250m
              memory: 300Mi
          terminationMessagePath: /dev/termination-log
          terminationMessagePolicy: File
      dnsPolicy: ClusterFirst
      restartPolicy: Always
      schedulerName: default-scheduler
      securityContext: {}
      terminationGracePeriodSeconds: 30

---

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: arms-python-server
  name: arms-python-server
  namespace: arms-demo
spec:
  progressDeadlineSeconds: 600
  replicas: 1
  revisionHistoryLimit: 10
  selector:
    matchLabels:
      app: arms-python-server
  strategy:
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
    type: RollingUpdate
  template:
    metadata:
      labels:
        app: arms-python-server
        aliyun.com/app-language: python # Python アプリケーションに必須。これが Python アプリケーションであることを指定します。
        armsPilotAutoEnable: 'on'
        armsPilotCreateAppName: "arms-python-server"    # ARMS でのアプリケーションの表示名。
    spec:
      containers:
        - env:
          - name: CLIENT_URL
            value: 'http://arms-python-client-svc:8000'
        - image: registry.cn-hangzhou.aliyuncs.com/arms-default/python-agent:arms-python-server
          imagePullPolicy: Always
          name: server
          resources:
            requests:
              cpu: 250m
              memory: 300Mi
          terminationMessagePath: /dev/termination-log
          terminationMessagePolicy: File
      dnsPolicy: ClusterFirst
      restartPolicy: Always
      schedulerName: default-scheduler
      securityContext: {}
      terminationGracePeriodSeconds: 30

---

apiVersion: v1
kind: Service
metadata:
  labels:
    app: arms-python-server
  name: arms-python-server-svc
  namespace: arms-demo
spec:
  internalTrafficPolicy: Cluster
  ipFamilies:
    - IPv4
  ipFamilyPolicy: SingleStack
  ports:
    - name: http
      port: 8000
      protocol: TCP
      targetPort: 8000
  selector:
    app: arms-python-server
  sessionAffinity: None
  type: ClusterIP

apiVersion: v1
kind: Service
metadata:
  name: arms-python-client-svc
  namespace: arms-demo
  uid: 91f94804-594e-495b-9f57-9def1fdc7c1d
spec:
  internalTrafficPolicy: Cluster
  ipFamilies:
    - IPv4
  ipFamilyPolicy: SingleStack
  ports:
    - name: http
      port: 8000
      protocol: TCP
      targetPort: 8000
  selector:
    app: arms-python-client
  sessionAffinity: None
  type: ClusterIP
  1. ACK コンソールにログインします。左のナビゲーションウィンドウで、クラスターをクリックします。

  2. クラスター ページで、管理するクラスターを見つけてその名前をクリックします。左のナビゲーションウィンドウで、ワークロード > 展開 を選択します。

  3. [ステートレス] ページで、ターゲットアプリケーションを見つけ、[アクション] 列から image > [YAML の編集] を選択します。

    新しいアプリケーションを作成するには、[YAML から作成] をクリックします。

  4. YAML ファイルで、`spec.template.metadata` の下に次の labels を追加します。

    labels:
      aliyun.com/app-language: python # Python アプリケーションに必須。これが Python アプリケーションであることを指定します。
      armsPilotAutoEnable: 'on'
      armsPilotCreateAppName: "deployment-name"    # ARMS でのアプリケーションの表示名。
    重要

    インストールした ack-onepilot コンポーネントのバージョンが 5.0.0 より後の場合、このステップでコンポーネントが Python エージェントパッケージを自動的にダウンロードして挿入します。これにより、完全に非侵入型のインストールエクスペリエンスが提供されます。この機能を使用したくない場合、またはコンテナーに Python エージェントを手動でインストール済みの場合は、次のラベルを使用して Python の非侵入型挿入機能を無効にすることをお勧めします。

    labels:
      aliyun.com/app-language: python # Python アプリケーションに必須。これが Python アプリケーションであることを指定します。
      armsPilotAutoEnable: 'on'
      armsPilotCreateAppName: "deployment-name"    # ARMS でのアプリケーションの表示名。
      armsAutoInstrumentationEnable: "off"  # Python アプリケーションの非侵入型挿入機能を無効にします。

    image

  5. [更新] をクリックします。

結果

ARMS コンソール[アプリケーションモニタリング] > [アプリケーション] ページに Python アプリケーションが表示され、約 1 分以内にデータのレポートが開始されると、エージェントのインストールは成功です。

2024-09-23_17-45-22