Instal agen Python untuk Container Service for Kubernetes (ACK) dan Container Compute Service (ACS) menggunakan komponen ack-onepilot - Application Real-Time Monitoring Service

Saat menjalankan aplikasi Python di kluster Container Service for Kubernetes (ACK) atau Container Compute Service (ACS), Application Real-Time Monitoring Service (ARMS) menyediakan pelacakan terdistribusi, peta topologi aplikasi, dan analisis panggilan API. Untuk mengumpulkan data tersebut, instal agen Python ARMS menggunakan komponen ack-onepilot.

Tersedia dua metode instalasi:

Metode	Versi ack-onepilot	Perubahan Dockerfile
Auto-injection (disarankan)	Lebih baru dari 5.0.0	Tidak diperlukan
Instalasi manual	3.2.4 atau lebih baru	Diperlukan

Catatan

Untuk pertanyaan mengenai agen Python, lihat FAQ tentang agen Python. Anda juga dapat menghubungi kami melalui grup DingTalk (ID: 159215000379).

Prasyarat

Kluster ACK atau ACS telah dibuat
- Kluster ACK: Buat kluster ACK yang dikelola, Buat kluster khusus ACK (pembuatan baru telah dihentikan), atau Buat kluster ACK Serverless
- Kluster ACS: Buat kluster ACS
Namespace telah dibuat. Lihat Kelola namespace dan kuota. Contoh dalam panduan ini menggunakan arms-demo.
Versi Python dan framework Anda didukung. Lihat Library Python yang didukung oleh Pemantauan Aplikasi.

Kompatibilitas framework Python

Tinjau persyaratan khusus framework berikut sebelum melanjutkan.

uvicorn

Jika aplikasi Anda dimulai dengan uvicorn, pilih salah satu pendekatan berikut:

Pendekatan A: Impor agen dalam kode. Tambahkan pernyataan impor berikut pada baris pertama file entri uvicorn Anda:

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

Pendekatan B: Beralih ke gunicorn dengan awalan aliyun-instrument. Ganti perintah uvicorn Anda:

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

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

Catatan

Awalan aliyun-instrument menangani inisialisasi dan instrumentasi non-intrusif agen Python ARMS.

uWSGI

Jika aplikasi Anda dimulai dengan uWSGI, lihat Instal agen Python untuk proyek Django atau Flask yang dimulai dengan uWSGI.

gevent

Jika Anda menggunakan korutin gevent, atur variabel lingkungan GEVENT_ENABLE ke true.

Misalnya, jika kode Anda berisi:

from gevent import monkey
monkey.patch_all()

Atur variabel lingkungan berikut dalam deployment Anda:

GEVENT_ENABLE=true

Langkah 1: Instal ack-onepilot

ack-onepilot adalah komponen sisi kluster yang mengelola instalasi agen ARMS.

Masuk ke Konsol ACK. Pada halaman Clusters, klik nama kluster Anda.
Di panel navigasi kiri, klik Add-ons. Cari ack-onepilot di pojok kanan atas.
Penting
Pastikan versi ack-onepilot adalah 3.2.4 atau lebih baru.
Klik Install pada kartu ack-onepilot.
Catatan
Secara default, ack-onepilot mendukung 1.000 Pod. Untuk setiap tambahan 1.000 Pod, tambahkan 0,5 core CPU dan 512 MB memori ke komponen tersebut.
Pada kotak dialog, konfigurasikan parameter dan klik OK. Nilai default disarankan.
Catatan
Setelah instalasi, Anda dapat melakukan peningkatan, konfigurasi, atau menguninstal ack-onepilot dari halaman Add-ons.
Pilih langkah berikutnya berdasarkan versi ack-onepilot:
- Versi lebih baru dari 5.0.0: Lanjutkan ke Langkah 3: Berikan izin. Tidak diperlukan perubahan Dockerfile. Ini memberikan pengalaman instalasi sepenuhnya non-intrusif untuk aplikasi Python.
- Versi lainnya (3.2.4 atau lebih baru): Lanjutkan ke Langkah 2: Modifikasi Dockerfile.

Langkah 2: Modifikasi Dockerfile (ack-onepilot 5.0.0 atau lebih lama)

Catatan

Lewati langkah ini jika versi ack-onepilot Anda lebih baru dari 5.0.0.

Tambahkan agen Python ARMS ke Dockerfile Anda dan perbarui perintah startup.

Instal installer agen dari PyPI:
```
   RUN pip3 install aliyun-bootstrap
```
Instal agen. Ganti <region-id> dengan ID wilayah Alibaba Cloud Anda (misalnya, cn-hangzhou):
Catatan
Untuk menginstal versi agen tertentu, jalankan: aliyun-bootstrap -a install -v <version> . Untuk semua versi yang dirilis, lihat Catatan rilis agen Python.
```
   RUN ARMS_REGION_ID=<region-id> aliyun-bootstrap -a install
```
Perbarui perintah startup untuk menggunakan awalan aliyun-instrument:
```
   CMD ["aliyun-instrument", "python", "app.py"]
```
Buat image.

Contoh Dockerfile lengkap

Sebelum:

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"]

Setelah (dengan agen ARMS):

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

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

# Install the ARMS Python agent
RUN pip3 install aliyun-bootstrap \
    && ARMS_REGION_ID=<region-id> aliyun-bootstrap -a install

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

# Start the application with the ARMS agent
CMD ["aliyun-instrument", "python", "app.py"]

Ganti <region-id> dengan ID wilayah Alibaba Cloud Anda, seperti cn-hangzhou.

Langkah 3: Berikan izin

Konfigurasi izin bervariasi berdasarkan jenis kluster.

Kluster ACK yang dikelola

Kluster ACK yang dikelola dengan ARMS Addon Token tidak memerlukan konfigurasi izin tambahan.

Periksa keberadaan ARMS Addon Token:

Masuk ke Konsol ACK. Di panel navigasi sebelah kiri, klik Clusters, lalu klik nama kluster Anda.
Di panel navigasi kiri, pilih Configurations > Secrets. Pilih kube-system dari daftar drop-down Namespace.
Periksa apakah addon.arms.token muncul pada halaman Secrets.
- Token ada: Lanjutkan ke Langkah 4: Aktifkan pemantauan ARMS.
- Token tidak ada: Tambahkan kebijakan izin secara manual (lihat di bawah).

Catatan

ARMS Addon Token memungkinkan otorisasi tanpa kata sandi. Beberapa kluster ACK yang dikelola mungkin tidak memiliki token ini. Verifikasi sebelum melanjutkan.

Tambahkan kebijakan izin secara manual:

Masuk ke Konsol ACK. Di panel navigasi kiri, klik Clusters. Klik nama kluster Anda.
Pada tab Basic Information halaman Cluster Information, klik tautan di samping Worker RAM Role di bagian Cluster Resources.
Pada halaman yang muncul, klik Grant Permission pada tab Permissions.
Pada panel Grant Permission, tambahkan kebijakan berikut dan klik Grant permissions:
- AliyunTracingAnalysisFullAccess: Akses penuh ke Managed Service for OpenTelemetry.
- AliyunARMSFullAccess: Akses penuh ke ARMS.

Kluster khusus ACK dan kluster terdaftar

Pastikan izin AliyunARMSFullAccess dan AliyunSTSAssumeRoleAccess telah diberikan kepada Pengguna Resource Access Management (RAM) Anda.

Setelah ack-onepilot diinstal, konfigurasikan ID AccessKey dan AccessKey Secret Anda menggunakan salah satu metode berikut.

Metode 1: Perbarui konfigurasi Helm

Masuk ke Konsol ACK. Di panel navigasi kiri, klik Clusters.
Klik nama kluster Anda. Di panel navigasi kiri, pilih Applications > Helm. Klik Update di samping ack-onepilot.
Ganti nilai accessKey dan accessKeySecret dengan ID AccessKey dan AccessKey Secret Anda, lalu klik OK.
Catatan
AccessKey Secret hanya terlihat saat Anda pertama kali membuat pasangan AccessKey. Simpan dengan aman—tidak dapat diambil kembali nanti.
Restart Deployment.

Metode 2: Gunakan Kubernetes Secrets

Masuk ke Konsol ACK. Di panel navigasi kiri, klik Clusters.
Klik nama kluster Anda. Di panel navigasi kiri, pilih Configurations > Secrets.
Klik Create. Di panel tersebut, klik Add dan masukkan ID AccessKey dan AccessKey Secret Anda.
Catatan
AccessKey Secret hanya terlihat saat Anda pertama kali membuat pasangan AccessKey. Simpan dengan aman—tidak dapat diambil kembali nanti.
Di panel navigasi kiri, pilih Workloads > Deployments. Klik komponen ack-onepilot (biasanya bernama ack-onepilot-ack-onepilot di namespace ack-onepilot).
Di pojok kanan atas, klik Edit.
Gulir ke bagian Environments. Klik Add, lalu tambahkan variabel lingkungan berikut yang mereferensikan Secrets yang telah Anda buat. Klik OK.
- ONE_PILOT_ACCESSKEY
- ONE_PILOT_ACCESSKEY_SECRET

Kluster ACK Serverless (ASK) dan Elastic Container Instance (ECI)

Otorisasi kluster untuk mengakses ARMS pada halaman Cloud Resource Access Authorization.
Restart semua Pod tempat ack-onepilot dideploy.

Langkah 4: Aktifkan pemantauan ARMS

Tambahkan label ARMS ke deployment Kubernetes Anda untuk mengaktifkan pemantauan.

Penting

Dengan ack-onepilot versi lebih baru dari 5.0.0, komponen secara otomatis mengunduh dan menyuntikkan paket agen Python selama langkah ini—tidak diperlukan perubahan Dockerfile. Kontainer init menangani penyuntikan agen dengan nilai default berikut:

Sumber daya: 0,5 core CPU, memori 250 MB (dilepas setelah inisialisasi)
Waktu eksekusi: sekitar 10 detik Untuk menyesuaikan sumber daya kontainer init, atur variabel lingkungan berikut: | Variabel lingkungan | Deskripsi | Contoh | |---|---|---| | PYTHON_INIT_RESOURCE_REQUESTS_CPU | Permintaan CPU | 500m | | PYTHON_INIT_RESOURCE_REQUESTS_MEM | Permintaan memori | 250Mi | | PYTHON_INIT_RESOURCE_LIMIT_CPU | Batas CPU | 1000m | | PYTHON_INIT_RESOURCE_LIMIT_MEM | Batas memori | 500Mi | Fitur auto-injection ini sedang dalam tahap beta. Hubungi kami melalui grup DingTalk (ID: 159215000379) jika Anda memiliki pertanyaan.

Tambahkan label ke deployment Anda

Masuk ke Konsol ACK. Di panel navigasi kiri, klik Clusters.
Klik nama kluster Anda. Di panel navigasi kiri, pilih Workloads > Deployments.
Temukan aplikasi Anda, lalu pilih > Edit YAML dari kolom Actions. Atau, klik Create From YAML untuk membuat aplikasi baru.
Tambahkan label berikut di bawah spec.template.metadata. Ganti <app-name> dengan nama deskriptif untuk aplikasi Anda, seperti my-python-service.
Penting
Jika Anda menggunakan ack-onepilot versi lebih baru dari 5.0.0 tetapi telah menginstal agen secara manual di Dockerfile Anda, nonaktifkan auto-injection dengan menambahkan label ini: armsAutoInstrumentationEnable: "off"
```
   labels:
     aliyun.com/app-language: python       # Wajib. Mengidentifikasi ini sebagai aplikasi Python.
     armsPilotAutoEnable: 'on'             # Mengaktifkan pemantauan ARMS.
     armsPilotCreateAppName: "<app-name>"  # Nama tampilan di konsol ARMS.
```
Klik Update.

Contoh YAML lengkap

YAML berikut mendeploy dua aplikasi Python contoh dengan pemantauan ARMS:

Lihat contoh YAML lengkap (klik untuk membuka)

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       # Wajib. Mengidentifikasi ini sebagai aplikasi Python.
        armsPilotAutoEnable: 'on'
        armsPilotCreateAppName: "arms-python-client"    # Nama tampilan di 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       # Wajib. Mengidentifikasi ini sebagai aplikasi Python.
        armsPilotAutoEnable: 'on'
        armsPilotCreateAppName: "arms-python-server"    # Nama tampilan di 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

Verifikasi instalasi

Konfirmasi bahwa agen melaporkan data.

Buka Konsol ARMS.
Di panel navigasi kiri, pilih Application Monitoring > Applications.
Konfirmasi bahwa aplikasi Python Anda muncul dalam daftar dan melaporkan data. Biasanya membutuhkan waktu sekitar satu menit.

Pemecahan masalah umum

Jika aplikasi Anda tidak muncul di konsol ARMS setelah beberapa menit:

Verifikasi label diterapkan pada Pod (bukan deployment): Pastikan aliyun.com/app-language, armsPilotAutoEnable, dan armsPilotCreateAppName ada.
```
  kubectl get pod <pod-name> -n <namespace> -o jsonpath='{.metadata.labels}'
```
Periksa status kontainer init (ack-onepilot versi lebih baru dari 5.0.0): Cari kontainer init dalam output. Pastikan kontainer tersebut berhasil selesai.
```
  kubectl describe pod <pod-name> -n <namespace>
```
Verifikasi ack-onepilot sedang berjalan: Semua Pod ack-onepilot harus berstatus Running.
```
  kubectl get pods -n ack-onepilot
```
Periksa izin: Pastikan kebijakan RAM yang diperlukan telah dilampirkan. Lihat Langkah 3: Berikan izin.

Catatan versi

Secara default, versi agen Python terbaru diinstal setiap kali Anda menggunakan aliyun-bootstrap atau metode auto-injection. Untuk mengunci versi tertentu, lihat bagian Bagaimana cara menginstal agen untuk wilayah dan versi tertentu? dalam FAQ tentang agen Python.