すべてのプロダクト
Search

このプロダクト

    Application Real-Time Monitoring Service:ACK および ACS クラスターへの ARMS Python エージェントのインストール

    ドキュメントセンター

    Application Real-Time Monitoring Service:ACK および ACS クラスターへの ARMS Python エージェントのインストール

    最終更新日:Sep 10, 2026

    Container Service for Kubernetes (ACK) または Container Compute Service (ACS) クラスターで Python アプリケーションを実行する場合、Application Real-Time Monitoring Service (ARMS) は、分散トレーシング、アプリケーショントポロジーマップ、API コール分析を提供します。これらのデータを収集するには、ack-onepilot コンポーネントを使用して ARMS Python エージェントをインストールします。

    次の 2 つのインストール方法が利用できます：

    方法ack-onepilot バージョンDockerfile の変更
    自動インジェクション (推奨)5.0.0 より後のバージョン不要
    手動インストール3.2.4 以降必要
    説明

    Python エージェントに関するご質問は、「Python エージェントに関する FAQ」をご参照ください。DingTalk グループ (ID: 159215000379) からもお問い合わせいただけます。

    前提条件

    Python フレームワークの互換性

    作業を進める前に、以下のフレームワーク固有の要件を確認してください。

    uvicorn

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

    方法 A：コード内でエージェントをインポートする。 uvicorn のエントリーファイルの先頭行に次の import 文を追加します：

    from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

    方法 B: aliyun-instrument プレフィックスを付けて gunicorn に切り替えます。 uvicorn コマンドを置き換えます:

    # 変更前：
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 で起動する場合は、「uWSGI で起動する Django または Flask プロジェクトへの Python エージェントのインストール」をご参照ください。

    gevent

    gevent コルーチンを使用する場合、GEVENT_ENABLE 環境変数を true に設定します。

    たとえば、コードに次の内容が含まれている場合：

    from gevent import monkey
monkey.patch_all()

    デプロイメントで次の環境変数を設定してください：

    GEVENT_ENABLE=true

    ステップ 1：ack-onepilot のインストール

    ack-onepilot は、ARMS エージェントのインストールを管理するクラスター側のコンポーネントです。

    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 より後のバージョン：「ステップ 3：権限の付与」に進みます。Dockerfile の変更は不要です。これにより、Python アプリケーションを完全に非侵入的な方法でインストールできます。

      • その他のバージョン (3.2.4 以降)：「ステップ 2：Dockerfile の変更」に進みます。

    ステップ 2：Dockerfile の変更 (ack-onepilot 5.0.0 以前)

    説明

    ack-onepilot のバージョンが 5.0.0 より後の場合は、このステップをスキップしてください。

    Dockerfile に ARMS Python エージェントを追加し、起動コマンドを更新してください。

    1. PyPI からエージェントインストーラーをインストールしてください：

         RUN pip3 install aliyun-bootstrap

    2. エージェントをインストールします。 <region-id> を、お使いの Alibaba Cloud リージョン ID (例: cn-hangzhou) に置き換えます:

      説明

      特定のエージェントバージョンをインストールするには、 aliyun-bootstrap -a install -v <version> を実行します。 すべてのリリースバージョンについては、「Python エージェントのリリースノート」をご参照ください。

         RUN ARMS_REGION_ID=<region-id> aliyun-bootstrap -a install

    3. aliyun-instrument プレフィックスを使用するように、起動コマンドを更新します:

         CMD ["aliyun-instrument", "python", "app.py"]

    4. イメージをビルドしてください。

    完全な Dockerfile の例

    変更前：

    FROM docker.m.daocloud.io/python:3.10

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY ./app.py /app/app.py
EXPOSE 8000
CMD ["python", "app.py"]

    変更後 (ARMS エージェントを含む)：

    FROM docker.m.daocloud.io/python:3.10

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# ARMS Python エージェントをインストール
RUN pip3 install aliyun-bootstrap \
    && ARMS_REGION_ID=<region-id> aliyun-bootstrap -a install

COPY ./app.py /app/app.py
EXPOSE 8000

# ARMS エージェントでアプリケーションを起動
CMD ["aliyun-instrument", "python", "app.py"]

    <region-id> を、cn-hangzhou などの Alibaba Cloud リージョン ID に置き換えます。

    ステップ 3：権限の付与

    権限の設定は、クラスタータイプによって異なります。

    ACK マネージドクラスター

    ARMS Addon Token がある ACK マネージドクラスターでは、追加の権限設定は不要です。

    ARMS Addon Token を確認する：

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

    2. 左側のナビゲーションペインで、[設定] > [シークレット] を選択します。[名前空間] ドロップダウンリストから [kube-system] を選択します。

    3. [シークレット] ページに addon.arms.token が表示されているか確認します。

    説明

    ARMS Addon Token により、パスワード不要の認証が可能になります。一部の ACK マネージドクラスターには、このトークンがない場合があります。作業を進める前に確認してください。

    権限ポリシーを手動で追加する：

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

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

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

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

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

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

    ACK 専用クラスターおよび登録済みクラスター

    AliyunARMSFullAccess および AliyunSTSAssumeRoleAccess の権限がResource Access Management (RAM) ユーザーに付与されていることを確認してください。

    ack-onepilot のインストール後、次のいずれかの方法を使用して AccessKey ID と AccessKey Secret を設定してください。

    方法 1：Helm 設定を更新する

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

    2. クラスター名をクリックします。左側のナビゲーションペインで、[アプリケーション] > [Helm] を選択します。[ack-onepilot] の横にある [更新] をクリックします。

    3. accessKey と accessKeySecret の値を、ご自身の AccessKey ID と AccessKey Secret に置き換えた後、[OK] をクリックします。

      説明

      AccessKey Secret は、AccessKey ペアを最初に作成したときにのみ表示されます。安全に保管してください。後で取得することはできません。

      image

    4. デプロイメントを再起動してください。

    方法 2：Kubernetes Secret を使用する

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

    2. クラスター名をクリックします。左側のナビゲーションペインで、[設定] > [シークレット] を選択します。

    3. [作成] をクリックします。パネルで [追加] をクリックし、アクセスキー ID とアクセスキーシークレットを入力します。

      説明

      AccessKey Secret は、AccessKey ペアを最初に作成したときにのみ表示されます。安全に保管してください。後で取得することはできません。

      image

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

    5. 右上隅の[編集]をクリックします。

    6. [環境] セクションまでスクロールします。[追加] をクリックし、作成した Secret を参照する環境変数を追加して、[OK] をクリックします。

      • ONE_PILOT_ACCESSKEY

      • ONE_PILOT_ACCESSKEY_SECRET

      image

    ACK Serverless (ASK) および Elastic Container Instance (ECI) クラスター

    1. Cloud Resource Access Authorization ページで、クラスターが ARMS にアクセスすることを承認してください。

    2. ack-onepilot がデプロイされているすべての Pod を再起動してください。

    ステップ 4：ARMS モニタリングの有効化

    Kubernetes デプロイメントに ARMS ラベルを追加して、モニタリングを有効化してください。

    重要

    ack-onepilot 5.0.0 より後のバージョンでは、このステップ中にコンポーネントが Python エージェントパッケージを自動的にダウンロードしてインジェクトします。Dockerfile の変更は不要です。init コンテナがエージェントのインジェクションを処理し、次のデフォルト設定を使用します：

    • リソース：0.5 CPU コア、250 MiB のメモリ (初期化後に解放)

    • 実行時間: 約 10 秒。init コンテナのリソースを調整するには、これらの環境変数を設定します: | 環境変数 | 説明 | 例 | |---|---|---| | PYTHON_INIT_RESOURCE_REQUESTS_CPU | CPU リクエスト | 500m | | PYTHON_INIT_RESOURCE_REQUESTS_MEM | メモリリクエスト | 250Mi | | PYTHON_INIT_RESOURCE_LIMIT_CPU | CPU 制限 | 1000m | | PYTHON_INIT_RESOURCE_LIMIT_MEM | メモリ制限 | 500Mi | この自動インジェクション機能はベータ版です。ご不明な点がある場合は、DingTalk グループ (ID: 159215000379) を通じてお問い合わせください。

    デプロイメントへのラベルの追加

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

    2. クラスターの名前をクリックします。左側のナビゲーションペインで、[ワークロード] > [デプロイ] を選択します。

    3. 対象のアプリケーションを探し、[アクション] 列で [image] > [YAML の編集] を選択します。 または、[YAML から作成] をクリックして新しい アプリケーションを作成します。

    4. spec.template.metadata の配下に次のラベルを追加し、<app-name> を my-python-service のようなアプリケーションのわかりやすい名前に置き換えます。

      重要

      ack-onepilot 5.0.0 より後のバージョンを使用しているが、Dockerfile にエージェントを手動でインストール済みの場合は、次のラベルを追加して自動インジェクションを無効にしてください：yaml armsAutoInstrumentationEnable: "off" 

         labels:
     aliyun.com/app-language: python       # 必須。これが Python アプリケーションであることを識別します。
     armsPilotAutoEnable: 'on'             # ARMS モニタリングを有効化します。
     armsPilotCreateAppName: "<app-name>"  # ARMS コンソールでの表示名。

      YAML labels configuration

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

    完全な YAML の例

    次の YAML は、ARMS モニタリングを使用する 2 つのサンプル Python アプリケーションをデプロイします：

    完全なサンプル YAML を表示 (クリックして展開)

    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 アプリケーションであることを識別します。
        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 アプリケーションであることを識別します。
        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
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. ARMS コンソールを開いてください。

    2. 左側のナビゲーションペインで、[アプリケーション監視] > [アプリケーション] を選択します。

    3. Python アプリケーションがリストに表示され、データを報告していることを確認してください。通常、これには約 1 分かかります。

      Application monitoring result

    一般的な問題のトラブルシューティング

    数分経過してもアプリケーションが ARMS コンソールに表示されない場合：

    • ポッドにラベルが適用されていることを確認 (デプロイメントではなく): aliyun.com/app-language、armsPilotAutoEnable、および armsPilotCreateAppName が存在することを確認します。

        kubectl get pod <pod-name> -n <namespace> -o jsonpath='{.metadata.labels}'

    • init コンテナのステータスを確認してください (ack-onepilot 5.0.0 より後)：出力で init コンテナを探してください。正常に完了したことを確認してください。

        kubectl describe pod <pod-name> -n <namespace>

    • ack-onepilot が実行中であることの確認: すべての ack-onepilot ポッドが Running ステータスになっている必要があります。

        kubectl get pods -n ack-onepilot

    • 権限を確認してください：必要な RAM ポリシーがアタッチされていることを確認してください。「ステップ 3：権限の付与」をご参照ください。

    バージョンに関する注意事項

    デフォルトでは、aliyun-bootstrap または自動インジェクション方法を使用するたびに、最新の Python エージェントバージョンがインストールされます。 特定のバージョンを固定するには、「Python エージェントに関する FAQ」の「特定のリージョンとバージョンのエージェントをインストールするにはどうすればよいですか?」セクションをご参照ください。