Buat pekerjaan scrape Prometheus kustom dari kluster Kubernetes Anda menggunakan CRD

Penyesuaian pengumpulan metrik Prometheus dari kluster Kubernetes Anda menjelaskan cara menggunakan ConfigMap untuk menyesuaikan proses pengikisan metrik Prometheus dari target default di kluster Kubernetes Anda. Artikel ini menjelaskan cara menggunakan definisi sumber daya kustom (CRD) untuk membuat pekerjaan scrape kustom untuk penyesuaian lebih lanjut dan target tambahan.

Definisi sumber daya kustom (CRD)

Mengaktifkan layanan terkelola Azure Monitor untuk Prometheus secara otomatis menyebarkan definisi sumber daya kustom (CRD) untuk monitor pod dan monitor layanan. CRD ini sama seperti monitor Pod OSS dan monitor layanan OSS untuk Prometheus, kecuali untuk perubahan nama grup. Jika Anda memiliki CRD Prometheus dan sumber daya kustom yang ada di kluster Anda, CRD ini tidak akan mengalami konflik dengan CRD yang dibuat oleh add-on. Pada saat yang sama, addon Prometheus terkelola tidak mendeteksi CRD yang dibuat untuk OSS Prometheus. Pemisahan ini disengaja untuk tujuan isolasi tugas scrape.

Membuat Pod atau Monitor Layanan

Gunakan templat Pod dan Service Monitor dan ikuti spesifikasi API untuk membuat sumber daya kustom Anda (PodMonitor dan Service Monitor). Satu-satunya perubahan yang diperlukan pada CR OSS (Sumber Daya Kustom) yang ada agar dapat digunakan oleh Prometheus Terkelola adalah grup API - azmonitoring.coreos.com/v1.

Penting

Pastikan untuk menggunakan labelLimit, labelNameLengthLimit, dan labelValueLengthLimit yang ditentukan dalam templat agar tidak dihilangkan selama pemrosesan. Lihat Pengaturan konfigurasi Scrape di bawah ini untuk detail tentang berbagai bagian file ini.

Monitor pod dan layanan Anda harus terlihat seperti contoh berikut:

Contoh Monitor Pod

# Note the API version is azmonitoring.coreos.com/v1 instead of monitoring.coreos.com/v1
apiVersion: azmonitoring.coreos.com/v1
kind: PodMonitor

# Can be deployed in any namespace
metadata:
  name: reference-app
  namespace: app-namespace
spec:
  labelLimit: 63
  labelNameLengthLimit: 511
  labelValueLengthLimit: 1023

  # The selector specifies which pods to filter for
  selector:

    # Filter by pod labels
    matchLabels:
      environment: test
    matchExpressions:
      - key: app
        operator: In
        values: [app-frontend, app-backend]

    # [Optional] Filter by pod namespace. Required if service is in another namespace.
    namespaceSelector:
      matchNames: [app-frontend, app-backend]

  # [Optional] Labels on the pod with these keys will be added as labels to each metric scraped
  podTargetLabels: [app, region, environment]

  # Multiple pod endpoints can be specified. Port requires a named port.
  podMetricsEndpoints:
    - port: metricscs from the exa

Contoh Pemantau Layanan

# Note the API version is azmonitoring.coreos.com/v1 instead of monitoring.coreos.com/v1
apiVersion: azmonitoring.coreos.com/v1
kind: ServiceMonitor

# Can be deployed in any namespace
metadata:
  name: reference-app
  namespace: app-namespace
spec:
  labelLimit: 63
  labelNameLengthLimit: 511
  labelValueLengthLimit: 1023

  # The selector filters endpoints by service labels.
  selector:
    matchLabels:
      app: reference-app

  # Multiple endpoints can be specified. Port requires a named port.
  endpoints:
  - port: metrics

Menyebarkan Pod atau Monitor Layanan

Sebarkan pod atau monitor layanan menggunakan kubectl apply seperti dalam contoh berikut.

Membuat aplikasi sampel

Sebarkan aplikasi sampel yang mengekspos metrik prometheus untuk dikonfigurasi oleh pod/monitor layanan.

kubectl apply -f https://raw.githubusercontent.com/Azure/prometheus-collector/refs/heads/main/internal/referenceapp/prometheus-reference-app.yaml

Membuat monitor pod dan/atau monitor layanan untuk mengambil metrik

Terapkan monitor pod yang dikonfigurasi untuk mengambil data aplikasi dari langkah sebelumnya.

Pemantau Pod

kubectl apply -f https://raw.githubusercontent.com/Azure/prometheus-collector/refs/heads/main/otelcollector/deploy/example-custom-resources/pod-monitor/pod-monitor-reference-app.yaml

Pemantau Layanan

kubectl apply -f https://raw.githubusercontent.com/Azure/prometheus-collector/refs/heads/main/otelcollector/deploy/example-custom-resources/service-monitor/service-monitor-reference-app.yaml

Pemecahan Masalah

Ketika pod atau pemantau layanan berhasil diterapkan, addon harus secara otomatis mulai mengumpulkan metrik dari sasaran. Lihat Memecahkan masalah pengumpulan metrik Prometheus di Azure Monitor untuk pemecahan masalah umum terkait sumber daya kustom dan juga untuk memastikan target muncul di 127.0.0.1/targets.

Pengaturan konfigurasi scrape

Bagian berikut menjelaskan pengaturan yang didukung dalam file konfigurasi Prometheus yang digunakan dalam CRD. Lihat referensi konfigurasi Prometheus untuk detail selengkapnya tentang pengaturan ini.

Pengaturan global

Format konfigurasi untuk pengaturan global sama dengan format yang didukung oleh konfigurasi OSS Prometheus

global:
  scrape_interval: <duration>
  scrape_timeout: <duration>
  external_labels:
    <labelname1>: <labelvalue>
    <labelname2>: <labelvalue>
scrape_configs:
  - <job-x>
  - <job-y>

Pengaturan yang disediakan di bagian global berlaku untuk semua pekerjaan pencarian di CRD tetapi digantikan jika ditetapkan dalam pekerjaan individual.

Nota

Jika Anda ingin menggunakan pengaturan global yang khusus diterapkan untuk semua pekerjaan pengambilan data, dan hanya memperoleh sumber daya kustom, Anda tetap perlu membuat ConfigMap yang berisi hanya pengaturan global. Pengaturan untuk masing-masing pengaturan dalam sumber daya kustom akan menggantikan yang ada di bagian global

Konfigurasi ekstraksi

Metode penemuan target yang didukung untuk sumber daya kustom saat ini adalah pod dan pemantau layanan.

Pod dan Monitor Layanan

Target yang ditemukan menggunakan pod dan monitor layanan memiliki label yang berbeda __meta_* tergantung pada monitor apa yang digunakan. Anda dapat menggunakan label di bagian relabelings untuk memfilter target atau mengganti label untuk target. Lihat contoh Pod dan Service Monitor untuk pod dan service monitor.

Pelabelan ulang

Bagian relabelings ini diterapkan pada saat penemuan target dan berlaku untuk setiap target untuk pekerjaan tersebut. Contoh berikut menunjukkan cara untuk menggunakan relabelings.

Menambahkan label Tambahkan label baru yang dipanggil example_label dengan nilai example_value ke setiap metrik pekerjaan. Gunakan __address__ sebagai label sumber hanya karena label tersebut selalu ada dan menambahkan label untuk setiap target pekerjaan.

relabelings:
- sourceLabels: [__address__]
  targetLabel: example_label
  replacement: 'example_value'

Gunakan label Pod atau Service Monitor

Target yang ditemukan menggunakan pod monitor dan service monitor memiliki label __meta_* yang berbeda, bergantung pada monitor yang digunakan. Label __* dihilangkan setelah menemukan target. Untuk memfilter berdasarkan penggunaan di tingkat metrik, pertama-tama pertahankan item tersebut menggunakan relabelings dengan menetapkan nama label. Kemudian gunakan metricRelabelings untuk memfilter.

# Use the kubernetes namespace as a label called 'kubernetes_namespace'
relabelings:
- sourceLabels: [__meta_kubernetes_namespace]
  action: replace
  targetLabel: kubernetes_namespace

# Keep only metrics with the kubernetes namespace 'default'
metricRelabelings:
- sourceLabels: [kubernetes_namespace]
  action: keep
  regex: 'default'

Pelabelan ulang tugas dan instance

Anda dapat mengubah job nilai label dan instance berdasarkan label sumber, sama seperti label lainnya.

# Replace the job name with the pod label 'k8s app'
relabelings:
- sourceLabels: [__meta_kubernetes_pod_label_k8s_app]
  targetLabel: job

# Replace the instance name with the node name. This is helpful to replace a node IP
# and port with a value that is more readable
relabelings:
- sourceLabels: [__meta_kubernetes_node_name]
  targetLabel: instance

Nota

Jika Anda memiliki konfigurasi pelabelan ulang, pastikan bahwa pelabelan ulang tidak memfilter target, dan label yang dikonfigurasi dengan benar cocok dengan target.

Pelabelan ulang metrik

Pelabelan ulang metrik diterapkan setelah pengikisan dan sebelum penyerapan. Gunakan bagian metricRelabelings untuk memfilter metrik setelah pengikisan. Lihat contoh berikut.

Hilangkan metrik menurut nama

# Drop the metric named 'example_metric_name'
metricRelabelings:
- sourceLabels: [__name__]
  action: drop
  regex: 'example_metric_name'

Simpan hanya metrik tertentu berdasarkan nama

# Keep only the metric named 'example_metric_name'
metricRelabelings:
- sourceLabels: [__name__]
  action: keep
  regex: 'example_metric_name'

# Keep only metrics that start with 'example_'
metricRelabelings:
- sourceLabels: [__name__]
  action: keep
  regex: '(example_.*)'

Memfilter metrik menurut label

# Keep metrics only where example_label = 'example'
metricRelabelings:
- sourceLabels: [example_label]
  action: keep
  regex: 'example'

# Keep metrics only if `example_label` equals `value_1` or `value_2`
metricRelabelings:
- sourceLabels: [example_label]
  action: keep
  regex: '(value_1|value_2)'

# Keep metrics only if `example_label_1 = value_1` and `example_label_2 = value_2`
metricRelabelings:
- sourceLabels: [example_label_1, example_label_2]
  separator: ';'
  action: keep
  regex: 'value_1;value_2'

# Keep metrics only if `example_label` exists as a label
metricRelabelings:
- sourceLabels: [example_label_1]
  action: keep
  regex: '.+'

Mengganti nama metrik Penggantian nama metrik tidak didukung.

Autentikasi Dasar dan Token Pembawa

Nota

Pada Kubernetes 1.37 dan yang lebih baru, Azure Managed Prometheus (atau ama-metrics) menggunakan akses cakupan namespace ke rahasia Kubernetes untuk konfigurasi PodMonitor dan ServiceMonitor. Anda harus mengonfigurasi akses rahasia dengan cakupan namespace jika menjalankan Kubernetes 1.37 atau yang lebih baru dan ServiceMonitor atau PodMonitor Anda menggunakan basicAuth dan konfigurasi apa pun yang mereferensikan rahasia Kubernetes.

Akses Rahasia Terlingkup untuk Pod/ServiceMonitors

Pada Kubernetes 1.37 dan yang lebih baru, Azure Managed Prometheus (atau ama-metrics) akan menggunakan akses cakupan namespace ke rahasia Kubernetes untuk konfigurasi PodMonitor dan ServiceMonitor. Sebelumnya, komponen ama-metrik memiliki izin di seluruh kluster untuk membaca rahasia di semua namespace layanan. Pembaruan ini meningkatkan keamanan dengan mengharuskan akses eksplisit pada tingkat namespace ke secret yang digunakan untuk autentikasi dasar

Dengan perubahan ini:

Akses ke rahasia hanya terbatas pada namespace yang anda konfigurasi secara eksplisit
Anda harus memberikan izin kontrol akses berbasis Peran (RBAC) di setiap namespace tempat rahasia digunakan

Perilaku default berdasarkan versi Kubernetes

Versi Kubernetes yang lebih lama dari 1.37

Akses rahasia di seluruh klaster masih diaktifkan demi kompatibilitas dengan versi sebelumnya
Ikuti langkah-langkah di sini untuk mengonfigurasi autentikasi dasar untuk ServiceMonitor dan PodMonitor

Kubernetes versi 1.37 dan yang lebih baru

Akses rahasia di seluruh kluster dihapus
Secara bawaan, tidak ada namespace yang dipantau untuk Secret
Anda harus:
1. Mengonfigurasi namespace yang diizinkan
2. Tambahkan izin RBAC di setiap namespace

Saat Anda perlu mengonfigurasi ini

Anda harus mengonfigurasi akses rahasia dengan cakupan namespace jika menjalankan Kubernetes 1.37 atau yang lebih baru dan ServiceMonitor atau PodMonitor Anda menggunakan basicAuth dan konfigurasi apa pun yang mereferensikan rahasia Kubernetes.

Mengonfigurasi akses rahasia untuk PodMonitor dan ServiceMonitor untuk Autentikasi Dasar

Ikuti langkah-langkah ini untuk memungkinkan Azure Prometheus Terkelola membaca rahasia dengan aman.

Langkah 1: Buat Rahasia Autentikasi Dasar

Buat rahasia di namespace tempat aplikasi Anda berjalan:

apiVersion: v1
kind: Secret
metadata:
  name: my-basic-auth
  namespace: my-app          # <-- your application namespace
type: Opaque
data:
  username: <base64-encoded-username>
  password: <base64-encoded-password>

Langkah 2: Mereferensikan Rahasia di ServiceMonitor/PodMonitor Anda

Contoh ServiceMonitor:

apiVersion: azmonitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: my-service-monitor
  namespace: my-app
spec:
  selector:
    matchLabels:
      app: my-app
  endpoints:
    - port: metrics
      basicAuth:
        username:
          name: my-basic-auth    # Secret name from Step 1
          key: username
        password:
          name: my-basic-auth
          key: password

Contoh PodMonitor:

apiVersion: azmonitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: my-pod-monitor
  namespace: my-app
spec:
  selector:
    matchLabels:
      app: my-app
  podMetricsEndpoints:
    - port: metrics
      basicAuth:
        username:
          name: my-basic-auth
          key: username
        password:
          name: my-basic-auth
          key: password

Langkah 3: Mengonfigurasi `secrets_access_namespaces`

Edit ama-metrics-settings-configmap.yaml untuk menyertakan namespace tempat rahasia Anda berada:

kind: ConfigMap
apiVersion: v1
metadata:
  name: ama-metrics-settings-configmap
  namespace: kube-system
data:
  prometheus-collector-settings: |-
    cluster_alias = ""
    secrets_access_namespaces = "kube-system,my-app"

Nota

Menggunakan daftar namespace yang dipisahkan koma
Sertakan kube-system jika Anda juga memiliki rahasia di sana
Perubahan mulai berlaku setelah pod ama-metrics dimulai ulang

Langkah 4: Buat RBAC di Setiap Namespace (Kubernetes >= 1.37)

Pada Kubernetes >= 1.37, ClusterRole tidak lagi memberikan akses rahasia di seluruh kluster. Anda harus membuat Role dan RoleBinding di setiap namespace yang tercantum di secrets_access_namespaces (termasuk kube-system jika diperlukan). Terapkan hal berikut di setiap namespace. Ganti my-app dengan namespace target:

Buat Peran:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: ama-metrics-secrets-reader
  namespace: my-app              # <-- repeat for each namespace
rules:
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["get", "list", "watch"]

Buat RoleBinding:

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: ama-metrics-secrets-rolebinding
  namespace: my-app              # <-- repeat for each namespace
subjects:
  - kind: ServiceAccount
    name: ama-metrics-serviceaccount
    namespace: kube-system       # <-- SA lives in kube-system
roleRef:
  kind: Role
  name: ama-metrics-secrets-reader
  apiGroup: rbac.authorization.k8s.io

Nota

Catatan lintas namespace: RoleBinding dalam my-app merujuk ke ServiceAccount di kube-system. Ini adalah RBAC Kubernetes yang valid — sebuah RoleBinding dapat merujuk ke subjek dari namespace mana pun.

Langkah 5: Verifikasi

ama-metrics Setelah pod dimulai ulang:

Periksa log alokator target untuk:

SecretsAccessNamespaces from configmap: [kube-system my-app]

Pastikan target ServiceMonitor/PodMonitor Anda muncul dalam target yang ditemukan oleh alokator target.
Pastikan bahwa hasil pengambilan data menyertakan metrik dari endpoint yang dilindungi autentikasi dasar.

Contoh: Beberapa Ruang Nama

Jika Anda memiliki rahasia di my-app, backend, dan monitoring:

Pengaturan ConfigMap:

secrets_access_namespaces = "kube-system,my-app,backend,monitoring"

RBAC (>hanya= 1.37): Buat Peran + RoleBinding (dari Langkah 4) di masing-masing my-app, backend, dan monitoring.

Pemecahan Masalah

Gejala	Penyebab	Perbaiki
Target ServiceMonitor tidak ditemukan	Rahasia tidak dapat dibaca oleh pengalokasi target	Pastikan namespace berada di `secrets_access_namespaces` dan Role+RoleBinding tersedia
`forbidden: User "system:serviceaccount:kube-system:ama-metrics-serviceaccount" cannot list resource "secrets"` dalam log TA	RBAC tidak ada di namespace	Buat Role+RoleBinding di namespace tersebut (Langkah 4)
Target ditemukan tetapi pengambilan data gagal dengan kode 401	Rahasia ada tetapi kredensial salah	Pastikan field Secret `data` memiliki nilai berenkode base64 yang benar
Pengaturan diabaikan setelah pembaruan configmap	Pod belum di-restart	`ama-metrics` Mulai ulang pod untuk mengambil nilai configmap baru

Mengonfigurasi Autentikasi Dasar untuk Kubernetes 1.36 dan yang lebih lama

Mengikis target menggunakan token autentikasi dasar atau pembawa didukung menggunakan PodMonitors dan ServiceMonitors. Pastikan bahwa rahasia yang berisi nama pengguna/kata sandi/token berada di namespace yang sama dengan monitor pod/layanan. Perilaku ini sama dengan OSS prometheus-operator.

Pengambilan data berbasis TLS

Jika Anda ingin mengambil metrik Prometheus dari endpoint HTTPS, konfigurasi Prometheus, PodMonitor, atau ServiceMonitor harus menetapkan scheme ke https serta menambahkan pengaturan TLS tambahan.

Buat rahasia di kube-system namespace bernama ama-metrics-mtls-secret. Setiap pasangan kunci-nilai yang ditentukan di bagian data objek rahasia akan dipasang sebagai file terpisah di lokasi /etc/prometheus/certs ini dengan nama file yang sama dengan kunci yang ditentukan di bagian data. Nilai rahasia harus dikodekan base64.

Berikut ini adalah contoh YAML rahasia:
```
apiVersion: v1
kind: Secret
metadata:
  name: ama-metrics-mtls-secret
  namespace: kube-system
type: Opaque
data:
  <certfile>: base64_cert_content    
  <keyfile>: base64_key_content 
```
Rahasia ama-metrics-mtls-secret dipasang pada ama-metrics pod di jalur /etc/prometheus/certs/ dan tersedia untuk scraper Prometheus. Kuncinya adalah nama file. Nilainya adalah base64 yang didekodekan dan ditambahkan sebagai konten file dalam kontainer.

Berikan jalur file dalam konfigurasi Prometheus, PodMonitor, atau ServiceMonitor:

Gunakan contoh berikut untuk menyediakan pengaturan konfigurasi TLS untuk PodMonitor atau ServiceMonitor:

 tlsConfig:
   ca:
     secret:
       key: "<certfile>"
       name: "ama-metrics-mtls-secret"
   cert:
     secret:
       key: "<certfile>"
       name: "ama-metrics-mtls-secret"
   keySecret:
       key: "<keyfile>"
       name: "ama-metrics-mtls-secret"
   insecureSkipVerify: false

Autentikasi Dasar dan TLS

Jika Anda ingin menggunakan token autentikasi dasar atau token pembawa (kredensial berbasis file) dan pengaturan autentikasi TLS di CRD Anda, pastikan bahwa rahasia ama-metrics-mtls-secret menyertakan semua kunci di bawah bagian data dengan nilai yang dikodekan base64 yang sesuai, seperti yang ditunjukkan di bawah ini:

apiVersion: v1
kind: Secret
metadata:
  name: ama-metrics-mtls-secret
  namespace: kube-system
type: Opaque
data:
  certfile: base64_cert_content    # used for TLS
  keyfile: base64_key_content      # used for TLS
  password1: base64-encoded-string # used for basic auth
  password2: base64-encoded-string # used for basic auth

Nota

Jalur /etc/prometheus/certs/ ini wajib, tetapi password1 dapat berupa string apa pun dan perlu mencocokkan kunci untuk data dalam rahasia yang dibuat di atas. Ini karena rahasia ama-metrics-mtls-secret dipasang di jalur /etc/prometheus/certs/ dalam kontainer.

Nilai yang dienkode dalam base64 secara otomatis didekodekan oleh pod ama-metrics saat secret di-mount sebagai file. Pastikan nama rahasia adalah ama-metrics-mtls-secret dan berada dalam kube-system namespace.

Rahasia harus dibuat terlebih dahulu, lalu ConfigMap, PodMonitor, atau ServiceMonitor harus dibuat di kube-system namespace. Urutan pembuatan rahasia penting. Ketika tidak ada rahasia kecuali ConfigMap, PodMonitor, atau ServiceMonitor yang menunjuk ke rahasia, kesalahan berikut akan ada di log kontainer prometheus-collector ama-metrics: no file found for cert....

Lihat tls_config untuk detail selengkapnya tentang pengaturan konfigurasi TLS.

Langkah berikutnya

Pelajari selengkapnya tentang mengumpulkan metrik Prometheus.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-05-20

Buat pekerjaan scrape Prometheus kustom dari kluster Kubernetes Anda menggunakan CRD

Definisi sumber daya kustom (CRD)

Membuat Pod atau Monitor Layanan

Contoh Monitor Pod

Contoh Pemantau Layanan

Menyebarkan Pod atau Monitor Layanan

Membuat aplikasi sampel

Membuat monitor pod dan/atau monitor layanan untuk mengambil metrik

Pemantau Pod

Pemantau Layanan

Pemecahan Masalah

Pengaturan konfigurasi scrape

Pengaturan global

Konfigurasi ekstraksi

Pod dan Monitor Layanan

Pelabelan ulang

Pelabelan ulang metrik

Autentikasi Dasar dan Token Pembawa

Akses Rahasia Terlingkup untuk Pod/ServiceMonitors

Perilaku default berdasarkan versi Kubernetes

Saat Anda perlu mengonfigurasi ini

Mengonfigurasi akses rahasia untuk PodMonitor dan ServiceMonitor untuk Autentikasi Dasar

Langkah 1: Buat Rahasia Autentikasi Dasar

Langkah 2: Mereferensikan Rahasia di ServiceMonitor/PodMonitor Anda

Langkah 3: Mengonfigurasi secrets_access_namespaces

Langkah 4: Buat RBAC di Setiap Namespace (Kubernetes >= 1.37)

Langkah 5: Verifikasi

Contoh: Beberapa Ruang Nama

Pemecahan Masalah

Mengonfigurasi Autentikasi Dasar untuk Kubernetes 1.36 dan yang lebih lama

Pengambilan data berbasis TLS

Autentikasi Dasar dan TLS

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan:

Langkah 3: Mengonfigurasi `secrets_access_namespaces`