Menggunakan kebijakan agen (GA)

Anda dapat membuat dan mengelola kebijakan agen menggunakan grup perintah gcloud compute instances ops-agents policies di Google Cloud CLI. Perintah di grup ini menggunakan rangkaian alat VM Manager di Compute Engine untuk mengelola kebijakan OS, yang dapat mengotomatiskan deployment dan pemeliharaan konfigurasi software seperti Agen Operasional. Kebijakan ini tidak dapat diterapkan ke agen Monitoring lama atau agen Logging lama.

Grup perintah gcloud compute instances ops-agents policies menggunakan resource penetapan kebijakan OS di OS Config API. Meskipun terdapat grup perintah gcloud CLI umum untuk mengelola penetapan kebijakan OS, gcloud compute os-config os-policy-assignments, grup perintah gcloud compute instances ops-agents policies dirancang khusus untuk kebijakan agen yang dijelaskan dalam dokumen ini.

Sebelum memulai

Sebelum menggunakan Google Cloud CLI untuk membuat kebijakan agen, selesaikan langkah-langkah berikut:

  1. Jika Anda belum melakukannya, instal Google Cloud CLI.

  2. Download dan jalankan skrip prepare-for-ops-agents-policies.sh untuk mengaktifkan API yang diperlukan dan menetapkan izin yang tepat untuk menggunakan Google Cloud CLI.

    Untuk mengetahui informasi tentang skrip, lihat Skrip prepare-for-ops-agents-policies.sh.

Uninstal agen Monitoring lama dan agen Logging

Jika Anda membuat kebijakan untuk Agen Operasional, pastikan VM Anda tidak memiliki agen Logging atau agen Monitoring lama yang diinstal di VM tersebut. Menjalankan Agen Operasional dan agen lama pada VM yang sama dapat menyebabkan penyerapan log duplikat atau konflik dalam penyerapan metrik. Jika perlu, uninstal agen Monitoring dan uninstal agen Logging sebelum membuat kebijakan untuk menginstal Agen Operasional.

Memastikan agen Konfigurasi OS sudah diinstal

Anda mungkin perlu menginstal dan mengonfigurasi agen OS Config secara manual pada VM yang lebih lama dari Konfigurasi OS. Untuk mengetahui informasi tentang cara menginstal dan memverifikasi agen OS Config secara manual, lihat checklist verifikasi VM Manager.

Membuat kebijakan agen untuk mengelola Agen Operasional

Untuk membuat kebijakan agen, gunakan perintah gcloud compute instances ops-agents policies create. Perintah ini memiliki struktur berikut:

gcloud compute instances ops-agents policies create POLICY_ID \
  --zone ZONE \
  --file path/to/policy-description-file.yaml \
  --project PROJECT_ID

Saat menggunakan perintah ini, ganti variabel sebagai berikut:

  • POLICY_ID adalah nama untuk kebijakan Anda.
  • ZONE adalah zona Compute Engine. Kebijakan agen hanya diterapkan pada VM di zona yang ditentukan. Untuk menerapkan kebijakan di beberapa zona, Anda harus membuat beberapa kebijakan.
  • path/to/policy-description-file.yaml adalah jalur ke file YAML yang mendeskripsikan kebijakan. Untuk mendapatkan informasi tentang struktur file ini, lihat Menjelaskan kebijakan agen.
  • PROJECT_ID adalah ID project Google Cloud Anda.

Untuk informasi tentang perintah lain dalam grup perintah dan opsi yang tersedia, lihat dokumentasi gcloud compute instances ops-agents policies.

Menjelaskan kebijakan agen

Anda memberikan informasi kebijakan ke gcloud compute instances ops-agents policies create dengan membuat file YAML yang menjelaskan kebijakan dan meneruskan file tersebut ke perintah sebagai nilai opsi --file.

Bagian ini menjelaskan struktur file deskripsi kebijakan. Untuk mengetahui informasi tambahan, lihat Contoh file deskripsi kebijakan.

Format file deskripsi kebijakan YAML

File deskripsi untuk kebijakan agen harus menyertakan dua grup kolom:

  • agentsRule, yang memberi tahu kebijakan agen apakah akan menginstal atau menghapus Agen Operasional, dan menentukan versi Agen Operasional yang akan dioperasikan.

  • instanceFilter, yang mendeskripsikan VM tempat kebijakan diterapkan.

Struktur grup kolom agentsRule

Grup kolom agentsRule memiliki struktur berikut:

agentsRule:
  packageState: installed|removed
  version: latest|2.*.*|2.x.y
  • Kolom packageState memberi tahu kebijakan tentang status Agen Operasional yang diinginkan. Nilai yang valid adalah installed dan removed.

  • Kolom version menunjukkan versi Agen Operasional yang akan diinstal atau dihapus. Anda dapat menetapkan nilai berikut:

    • latest adalah versi terbaru Agen Operasional.
    • 2.*.* adalah rilis terbaru dari utama versi 2 Agen Operasional.
    • 2.x.y menunjukkan rilis spesifik dari versi utama 2.

    Untuk mengetahui informasi tentang versi Agen Operasional yang tersedia, lihat repositori GitHub agen.

Struktur grup kolom instanceFilter

Grup kolom instanceFilter menunjukkan VM di zona tempat filter diterapkan. Grup kolom ini adalah representasi YAML dari struktur InstanceFilter yang digunakan oleh resource OSPolicyAssignment di OS Config API.

Grup kolom instanceFilter memiliki salah satu struktur berikut:

  • Untuk menerapkan kebijakan agen ke semua VM dalam suatu zona, gunakan perintah berikut:

    instanceFilter:
  all: True

    Jika menggunakan filter all: True, Anda tidak dapat menentukan kriteria lainnya.

  • Untuk menerapkan kebijakan agen ke serangkaian VM tertentu dalam suatu zona, jelaskan VM dengan menggunakan kombinasi salah satu opsi berikut:

    • Label pada VM, baik untuk disertakan atau dikecualikan:
      • inclusionLabels:
      • exclusionLabels:
    • Sistem operasi: inventories:

    Misalnya, filter berikut menerapkan kebijakan agen ke VM dengan sistem operasi yang ditentukan yang memiliki label "env=prod" dan tidak memiliki label "app=web":

    instanceFilter:
  inclusionLabels:
  - labels:
      env: prod
  exclusionLabels:
  - labels:
      app: web
  inventories:
  - osShortName: rhel
    osVersion: '7.*'
  - osShortName: debian
    osVersion: '11'

    Untuk menemukan nilai kolom osShortName dan osVersion untuk VM, gunakan perintah berikut:

    gcloud compute instances os-inventory describe INSTANCE_NAME \
--zone ZONE | grep "^ShortName: "

    gcloud compute instances os-inventory describe INSTANCE_NAME \
--zone ZONE | grep "^Version: "

    Perintah ini mengharuskan agen Konfigurasi OS diinstal di VM.

Memverifikasi status kebijakan agen

Bagian ini menjelaskan cara memeriksa status kebijakan yang dibuat dan penginstalan Agen Operasional. Informasi ini juga dapat membantu dalam memecahkan masalah kebijakan agen Anda.

Halaman Kebijakan OS Compute Engine

Halaman Kebijakan OS Compute Engine menyediakan informasi tentang kebijakan agen yang mengelola Agen Operasional dan tentang VM di tab VM instances. Contoh:

  • Kolom State menunjukkan apakah kebijakan berhasil diinstal ("Mematuhi"), sedang dalam proses ("Tertunda"), mungkin gagal ("Tidak diketahui"), atau tidak ada ("Tidak ada kebijakan").
  • Kolom VMMonitoring menunjukkan apakah Agen Operasional sedang dikelola oleh OS Config ("Monitored") atau tidak ("NotMonitoring").

    Jika kebijakan ditetapkan "Patuh" tetapi VM menampilkan "Tidak dipantau", mungkin ada masalah saat menginstal Agen Operasional. Misalnya, Anda mungkin sudah menginstal agen lama.

Di konsol Google Cloud, buka halaman OS policies:

Buka Kebijakan OS

Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Compute Engine.

Instance VM di tab Kebijakan OS Compute Engine menampilkan informasi tentang agen yang dikelola oleh semua kebijakan OS di project Google Cloud Anda. Kebijakan ini diberi label goog-ops-agent-policy.

  • Indikator goog-ops-agent-policy mencakup beberapa jenis kebijakan:
    • Kebijakan yang dibuat menggunakan perintah gcloud compute instances ops-agents policies.
    • Kebijakan yang dibuat untuk Anda jika Anda meminta penginstalan Agen Operasional saat Anda membuat VM.
    • Kebijakan yang dibuat menggunakan Terraform untuk mengelola Agen Operasional.

    Untuk membedakan setiap kebijakan, gunakan tab penetapan kebijakan OS di halaman ini guna melihat ID kebijakan untuk semua penetapan kebijakan di project Google Cloud Anda.

  • Kolom VM yang dipantau ini tidak mencerminkan penginstalan Agen Operasional dengan cara lain, seperti penginstalan manual atau dengan kebijakan agen beta.

Halaman VM Instances Cloud Monitoring

Halaman VM Instances di Cloud Monitoring mencakup kolom Agen yang mencantumkan agen yang diinstal di setiap VM, dan untuk Agen Operasional menyertakan indikator untuk agen terinstal yang lebih lama dari versi terbaru.

Di Konsol Google Cloud, buka halaman dasbor Instance VM:

Buka dasbor Instance VM

Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Monitoring.

Contoh file deskripsi kebijakan

Bagian ini memberikan beberapa contoh file deskripsi kebijakan YAML untuk berbagai skenario. Contoh ini mengasumsikan bahwa Anda menempatkan YAML dalam file bernama agent-policy-description.yaml dan bahwa Anda membuat kebijakan di zona us-central1-a menggunakan perintah seperti berikut:

gcloud compute instances ops-agents policies create POLICY_ID \
  --zone us-central1-a \
  --file agent-policy-description.yaml \
  --project PROJECT_ID

Instal di semua VM

Untuk menginstal Agen Operasional versi terbaru di semua VM di zona us-central1-a, gunakan deskripsi kebijakan berikut:

agentsRule:
  packageState: installed
  version: latest
instanceFilter:
  all: True

Hapus dari semua VM

Untuk menghapus Agen Operasional versi terbaru di semua VM di zona us-central1-a, gunakan deskripsi kebijakan berikut:

agentsRule:
  packageState: removed
  version: latest
instanceFilter:
  all: True

Menginstal di VM berdasarkan label

Untuk menginstal Agen Operasional versi terbaru pada semua VM di zona us-central1-a dengan label "env=prod" atau "app=web", gunakan deskripsi kebijakan berikut:

agentsRule:
  packageState: installed
  version: latest
instanceFilter:
  inclusionLabels:
  - labels:
      env: prod
  - labels:
      app: web

Saat Anda menentukan beberapa entri labels: untuk disertakan atau dikecualikan, VM akan cocok jika ada label yang ada; yaitu, kumpulan label untuk penyertaan atau pengecualian dicocokkan sebagai operasi OR logis, bukan operasi AND logis.

Menginstal di VM berdasarkan label lain

Untuk menginstal Agen Operasional versi terbaru pada semua VM di zona us-central1-a yang menjalankan Debian 11, kecuali VM dengan label "env=prod" dan "app=web6", gunakan deskripsi kebijakan berikut:

agentsRule:
  packageState: installed
  version: latest
instanceFilter:
  exclusionLabels:
  - labels:
      env: prod
      app: web6
  inventories:
  - osShortName: debian
    osVersion: '11'

Saat Anda menentukan beberapa key-value pair dalam satu entri labels: untuk disertakan atau dikecualikan, VM akan cocok jika semua label ada; yaitu, label dicocokkan sebagai operasi AND logis, bukan operasi OR logis.

Menginstal di VM berdasarkan sistem operasi

Untuk menginstal Agen Operasional versi 2 terbaru di semua VM yang menjalankan Debian 11 atau RHEL 7.* di zona us-central1-a, gunakan deskripsi kebijakan berikut:

agentsRule:
  packageState: installed
  version: 2.*.*
instanceFilter:
  inventories:
  - osShortName: rhel
    osVersion: '7.*'
  - osShortName: debian
    osVersion: '11'

Memecahkan masalah kebijakan agen GA

Bagian ini memberikan informasi untuk membantu Anda menyelesaikan masalah terkait kebijakan agen GA untuk Agen Operasional. Informasi yang dijelaskan dalam Memverifikasi status kebijakan agen juga dapat membantu.

Perintah ops-agents policy gagal

Jika perintah gcloud compute instances ops-agents policies gagal, respons akan menampilkan error validasi. Perbaiki error dengan memperbaiki argumen dan flag perintah seperti yang disarankan oleh pesan error.

Selain error validasi, Anda mungkin melihat error yang menunjukkan kondisi berikut:

Bagian berikut menjelaskan kondisi ini secara lebih mendetail.

Izin IAM tidak memadai

Jika perintah gcloud compute instances ops-agents policies gagal disertai error izin, pastikan Anda telah menjalankan skrip prepare-for-ops-agents-policies.sh seperti yang dijelaskan dalam Sebelum memulai untuk menyiapkan peran kebijakan OS Config:

Untuk informasi selengkapnya tentang skrip prepare-for-ops-agents-policies.sh, lihat Skrip prepare-for-ops-agents-policies.sh.

OS Config API tidak diaktifkan

Contoh error akan terlihat seperti berikut:

API [osconfig.googleapis.com] not enabled on project PROJECT_ID.
Would you like to enable and retry (this will take a few minutes)?
(y/N)?

Anda dapat memasukkan y untuk mengaktifkan API, atau menjalankan skrip prepare-for-ops-agents-policies.sh seperti yang dijelaskan dalam Sebelum memulai, untuk memberikan semua izin yang diperlukan. Jika memasukkan y saat ditampilkan dalam pesan error, Anda masih harus menjalankan skrip prepare-for-ops-agents-policies.sh untuk menetapkan izin yang diperlukan.

Untuk memastikan bahwa OS Config API sudah diaktifkan untuk project tersebut, jalankan perintah berikut:

gcloud services list --project PROJECT_ID | grep osconfig.googleapis.com

Output yang diharapkan adalah sebagai berikut:

osconfig.googleapis.com    Cloud OS Config API

Kebijakan tidak ada

Contoh error akan terlihat seperti berikut:

NOT_FOUND: Requested entity was not found

Error ini dapat berarti bahwa kebijakan tidak pernah dibuat, kebijakan telah dihapus, atau ID kebijakan yang ditentukan salah. Pastikan POLICY_ID yang digunakan dalam perintah gcloud compute instances ops-agents policies describe, update, atau delete sesuai dengan kebijakan yang sudah ada. Untuk mendapatkan daftar kebijakan agen, gunakan perintah gcloud compute instances ops-agents policies list.

Kebijakan ini dibuat, tetapi sepertinya tidak berpengaruh

Agen Konfigurasi OS di-deploy ke setiap instance Compute Engine untuk mengelola paket bagi agen Logging dan Monitoring. Kebijakan ini mungkin tampak tidak berpengaruh jika agen Konfigurasi OS yang mendasarinya tidak diinstal.

Linux

Untuk memastikan agen OS Config sudah diinstal, jalankan perintah berikut:

gcloud compute ssh instance-id \
    --project project-id \
    -- sudo systemctl status google-osconfig-agent

Contoh output-nya adalah:

    google-osconfig-agent.service - Google OSConfig Agent
    Loaded: loaded (/lib/systemd/system/google-osconfig-agent.service; enabled; vendor preset:
    Active: active (running) since Wed 2020-01-15 00:14:22 UTC; 6min ago
    Main PID: 369 (google_osconfig)
     Tasks: 8 (limit: 4374)
    Memory: 102.7M
    CGroup: /system.slice/google-osconfig-agent.service
            └─369 /usr/bin/google_osconfig_agent

Windows

Untuk memastikan agen OS Config sudah diinstal, jalankan langkah-langkah berikut:

  1. Hubungkan ke instance Anda menggunakan RDP atau alat serupa, lalu login ke Windows.

  2. Buka terminal PowerShell, lalu jalankan perintah PowerShell berikut. Anda tidak memerlukan hak istimewa administrator.

    Get-Service google_osconfig_agent

Contoh output-nya adalah:

    Status   Name               DisplayName
    ------   ----               -----------
    Running  google_osconfig_a… Google OSConfig Agent

Jika agen OS Config tidak diinstal, Anda mungkin menggunakan sistem operasi yang tidak mendukung VM Manager. Dokumen Detail sistem operasi Compute Engine menunjukkan fitur VM Manager yang didukung untuk setiap sistem operasi Compute Engine.

Jika sistem operasi mendukung VM Manager, Anda dapat menginstal agen Konfigurasi OS secara manual.

Agen Konfigurasi OS sudah diinstal, tetapi tidak menginstal Agen Operasional

Untuk memastikan apakah terjadi error saat agen OS Config menerapkan kebijakan, Anda dapat memeriksa log agen OS Config. Hal ini dapat dilakukan dengan menggunakan Logs Explorer atau SSH atau RDP untuk memeriksa instance Compute Engine satu per satu.

Untuk melihat log agen OS Config di Logs Explorer, gunakan filter berikut:

resource.type="gce_instance"
logId(OSConfigAgent)

Untuk melihat log agen OS Config, lakukan hal berikut:

CentOS, RHEL,
SLES, SUSE

Jalankan perintah berikut: 

gcloud compute ssh INSTANCE_ID \
    --project PROJECT_ID \
    -- sudo cat /var/log/messages \
       | grep "OSConfigAgent\|google-fluentd\|stackdriver-agent"

Debian, Ubuntu

Jalankan perintah berikut: 

gcloud compute ssh INSTANCE_ID \
    --project PROJECT_ID \
    -- sudo cat /var/log/syslog \
       | grep "OSConfigAgent\|google-fluentd\|stackdriver-agent"

Windows

  1. Hubungkan ke instance Anda menggunakan RDP atau alat serupa, lalu login ke Windows.

  2. Buka aplikasi Event Viewer, lalu pilih Windows Logs > Application, dan telusuri log dengan Source sama dengan OSConfigAgent.

Jika terjadi error saat menghubungkan ke layanan OS Config, pastikan Anda menjalankan skrip prepare-for-ops-agents-policies.sh seperti yang dijelaskan di bagian Sebelum memulai untuk menyiapkan metadata OS Config.

Untuk memastikan metadata OS Config sudah diaktifkan, Anda dapat menjalankan perintah berikut:

gcloud compute project-info describe \
    --project PROJECT_ID \
    | grep "enable-osconfig\|enable-guest-attributes" -A 1

Output yang diharapkan adalah sebagai berikut:

- key: enable-guest-attributes
  value: 'TRUE'
- key: enable-osconfig
  value: 'TRUE'

Agen Operasional diinstal tetapi tidak berfungsi dengan baik

Untuk mengetahui informasi selengkapnya tentang cara men-debug masalah Agen Operasional, lihat Memecahkan Masalah Agen Operasional.

Mengaktifkan log tingkat debug untuk agen Konfigurasi OS

Sebaiknya aktifkan logging tingkat debug di agen Konfigurasi OS saat melaporkan masalah.

Anda dapat menetapkan metadata osconfig-log-level: debug guna mengaktifkan logging level debug untuk agen Konfigurasi OS. Log yang dikumpulkan memiliki lebih banyak informasi untuk membantu penyelidikan.

Untuk mengaktifkan logging tingkat debug untuk seluruh project, jalankan perintah berikut:

gcloud compute project-info add-metadata \
    --project PROJECT_ID \
    --metadata osconfig-log-level=debug

Untuk mengaktifkan logging tingkat debug untuk satu VM, jalankan perintah berikut:

gcloud compute instances add-metadata INSTANCE_ID \
    --project PROJECT_ID \
    --metadata osconfig-log-level=debug

Skrip bantuan

Bagian ini memberikan informasi tambahan tentang skrip helper yang dijelaskan dalam dokumen ini:

Skrip prepare-for-ops-agents-policies.sh

Setelah mendownload skrip prepare-for-ops-agents-policies.sh, Anda dapat menggunakan skrip tersebut untuk melakukan tindakan berikut, berdasarkan argumen yang Anda berikan:

Contoh berikut menunjukkan beberapa pemanggilan umum untuk skrip. Untuk mengetahui informasi selengkapnya, lihat komentar dalam skrip.

Untuk mengaktifkan API, berikan peran yang diperlukan ke akun layanan default, dan aktifkan metadata OS Config untuk suatu project, jalankan skrip sebagai berikut:

bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID

Untuk memberikan tambahan salah satu peran OS Config kepada pengguna yang tidak memiliki peran Pemilik (roles/owner) pada project, jalankan skrip sebagai berikut:

bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID \
  --iam-user=USER_EMAIL \
  --iam-policy-access=[admin|editor|viewer]

Untuk memberikan tambahan salah satu peran OS Config ke akun layanan non-default, jalankan skrip sebagai berikut:

bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID \
  --iam-service-account=SERVICE_ACCT_EMAIL \
  --iam-policy-access=[admin|editor|viewer]

Skrip diagnose_policies.sh

Dengan mempertimbangkan project ID, ID instance Compute Engine, zona Compute Engine, dan ID kebijakan agen, skrip diagnose_policies.sh akan otomatis mengumpulkan informasi yang diperlukan untuk membantu mendiagnosis masalah pada kebijakan:

  • Versi agen Konfigurasi OS
  • Penetapan kebijakan OS yang mendasarinya
  • Penetapan kebijakan OS yang berlaku untuk instance Compute Engine ini
  • Deskripsi instance Compute Engine ini

Untuk memanggil skrip, jalankan perintah berikut:

bash diagnose_policies.sh --project-id=PROJECT_ID \ 
  --gce-instance-id=INSTANCE_ID \
  --policy-id=POLICY_ID \
  --zone=ZONE

Harga

Perintah gcloud compute instances ops-agents policies diimplementasikan menggunakan resource penetapan kebijakan OS dari VM Manager. Skrip prepare-for-ops-agents-policies.sh, yang dijelaskan dalam Sebelum memulai, menyiapkan VM Manager dalam mode fitur terbatas (OSCONFIG_B), yang cukup untuk membuat dan mengelola kebijakan agen. Penggunaan VM Manager dalam mode terbatas tidak memerlukan biaya.

Jika telah mengonfigurasi VM Manager dalam mode fitur lengkap (OSCONFIG_C), Anda mungkin dikenai biaya.