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

Cloud Monitor: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 アプリケーションを監視するには、ack-onepilot アプリケーション監視コンポーネントをインストールし、対応する Dockerfile を変更する必要があります。その後、Cloud Monitor 2.0 で、アプリケーションのトポロジー、API 呼び出し、呼び出しチェーン分析などのモニタリングデータを表示できます。このトピックでは、Container Service for Kubernetes (ACK) および Container Compute Service (ACS) にデプロイされた Python アプリケーションにエージェントをインストールする方法について説明します。

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

ack-onepilot コンポーネントについて

アプリケーション監視エージェントインストールアシスタント (ack-onepilot) は、さまざまなプログラミング言語のエージェントをインストールする主要なコンポーネントです。コンテナー内でアプリケーション監視エージェントパッケージを自動的に準備し、エージェントのレポート環境を構成します。ack-onepilot の仕組みの詳細については、「ack-onepilot コンポーネントの基本原則」をご参照ください。

エージェントのインストール後、アプリケーションが再起動すると、ack-onepilot はエージェントを最新バージョンに自動的にアップグレードします。エージェントを自動的にアップグレードしたくない場合は、エージェントのバージョンを制御できます。詳細については、「エージェントのバージョンを制御する」をご参照ください。

前提条件

注意

  • アプリケーションが 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: エージェントインストールアシスタント (ack-onepilot) のインストール

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

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

    重要

    ack-onepilot のバージョンは 5.1.0 以降である必要があります。アプリケーションの監視を有効にすると、このバージョンのコンポーネントは Python エージェントパッケージを自動的にダウンロードして挿入します。これにより、起動コマンドを手動で変更する必要のない、非侵入型の監視エクスペリエンスが提供されます。ack-onepilot コンポーネントのバージョン 5.1.0 はグレースケールリリース中です。このバージョンを使用するには、DingTalk グループ (ID: 35568145) を通じてお問い合わせください。

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

    説明

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

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

    説明

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

(オプション) ステップ 2: Dockerfile の変更

重要

ack-onepilot コンポーネントのバージョン 5.1.0 以降では、アプリケーションの監視を有効にすると、コンポーネントが Python エージェントパッケージを自動的にダウンロードして挿入します。これにより、起動コマンドを手動で変更する必要のない、非侵入型の監視エクスペリエンスが提供されます。

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

方法 1: Helm での入力

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

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

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

    説明

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

    image

  4. Deployment を再起動します。

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

  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_ACCESSKEY および ONE_PILOT_ACCESSKEY_SECRET を追加し、Kubernetes Secrets の Secret を参照して、[OK] をクリックします。

    image

ASK/ECI クラスター

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

ステップ 4: Python アプリケーションのアプリケーション監視を有効にする

説明

Python エージェントパッケージは、init コンテナーによってダウンロードおよび挿入されます。デフォルトのリソース設定では、init コンテナーの実行に約 10 秒かかる場合があります。デフォルトでは、init コンテナーは 0.5 コアと 250 MB のリソースを消費し、これらは初期化後に解放されます。次の環境変数を使用して 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。

以下は、ステートレス (デプロイメント) アプリケーションを作成し、アプリケーション監視を有効にするための完全なサンプル 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 でのアプリケーションの表示名。
        armsPilotAppWorkspace: "workspace"   # ワークスペースが指定されていない場合、データはデフォルトのワークスペースにレポートされます。
    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 でのアプリケーションの表示名。
        armsPilotAppWorkspace: "workspace"  # お使いのワークスペース名に置き換えてください。
    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 でのアプリケーションの表示名。
      armsPilotAppWorkspace: "workspace"    # お使いのワークスペース名に置き換えてください。
    重要

    Python の非侵入型挿入機能を使用したくない場合は、次のラベルで無効にできます。

    labels:
      armsAutoInstrumentationEnable: "off"  # Python アプリケーションの非侵入型挿入機能を無効にします。

    image

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

モニタリング詳細の表示

  1. Cloud Monitor 2.0 コンソールにログインし、ワークスペースを選択します。左側のナビゲーションウィンドウで、[アプリケーションセンター] > [アプリケーション可観測性] > [アプリケーション監視] を選択します。

  2. [アプリケーションリスト] ページで、アプリケーション名をクリックして、その詳細なモニタリングデータを表示します。