Menggunakan kebijakan agen

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dalam Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Kebijakan agen memungkinkan penginstalan dan pemeliharaan otomatis agen Google Cloud Observability di seluruh fleet VM Compute Engine yang cocok dengan kriteria yang ditentukan pengguna. Anda dapat membuat kebijakan untuk project Google Cloud yang mengatur VM lama dan baru yang terkait dengan project Google Cloud tersebut, sehingga memastikan penginstalan, penguninstalan, dan upgrade otomatis opsional yang tepat dari semua agen Google Cloud Observability di VM tersebut.

Anda membuat dan mengelola kebijakan agen menggunakan grup perintah gcloud beta compute instances ops-agents policies di Google Cloud CLI atau modul Terraform agent-policy. Kebijakan agen menggunakan rangkaian alat VM Manager di Compute Engine untuk mengelola kebijakan OS, yang dapat mengotomatiskan deployment dan pemeliharaan konfigurasi software seperti agen Observabilitas Google Cloud: Agen Operasional, agen Pemantauan lama, dan agen Logging lama.

Sistem operasi yang didukung

Anda dapat menerapkan kebijakan agen ke instance VM Compute Engine yang menjalankan sistem operasi yang ditampilkan dalam tabel berikut:

Sistem operasi	Agen Operasional (kebijakan GA &^† beta)	Agen logging (khusus kebijakan^† beta)	Agen pemantauan (khusus kebijakan^† beta)
CentOS 8
Rocky Linux 8
RHEL 6
RHEL 7: rhel-7, rhel-7-6-sap-ha, rhel-7-7-sap-ha, rhel-7-9-sap-ha			^‡
RHEL 8: rhel-8, rhel-8-4-sap-ha, rhel-8-6-sap-ha, rhel-8-8-sap-ha			^‡
Debian 9 (Stretch)
Debian 11 (Bullseye)
Deep Learning VM Image berdasarkan Debian 11 (Bullseye)
Ubuntu LTS 18.04 (Bionic Beaver): ubuntu-1804-lts, ubuntu-minimal-1804-lts
Ubuntu LTS 20.04 (Focal Fossa): ubuntu-2004-lts, ubuntu-minimal-2004-lts
Ubuntu LTS 22.04 (Jammy Jellyfish): buntu-2204-lts, ubuntu-minimal-2204-lts
SLES 12: sles-12, sles-12-sp5-sap
SLES 15: sles-15, sles-15-sp2-sap, sles-15-sp3-sap, sles-15-sp4-sap, sles-15-sp5-sap, sles-15-sp6-sap
OpenSUSE Leap 15: opensuse-leap (opensuse-leap-15-3-*, opensuse-leap-15-4-*)
Windows Server: 2016, 2019, 2022, Core 2016, Core 2019, Core 2022

^†  Dalam kebijakan agen versi beta, kolom agen dipetakan ke jenis agen yang ditentukan untuk pemanggilan gcloud beta compute instances ops-agents policies create:

• Agen Operasional dipetakan ke jenis agen ops-agent.
• Agen logging dipetakan ke jenis agen logging.
• Agen pemantauan dipetakan ke jenis agen metrics.

^‡ Agen Pemantauan tidak didukung di rhel-7-9-sap-ha, rhel-8-2-sap-ha, atau rhel-8-4-sap-ha.

Membuat kebijakan agen

Bagian ini menjelaskan penggunaan Google Cloud SDK untuk mengelola kebijakan agen. Untuk informasi tentang penggunaan Terraform, lihat Integrasi Terraform.

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

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

   Kebijakan agen yang dijelaskan dalam dokumen ini menggunakan grup perintah beta.

2. Jika Anda belum melakukannya, instal komponen beta gcloud CLI:

   gcloud components install beta
   

   Untuk memeriksa apakah Anda memiliki komponen beta untuk yang diinstal, jalankan:

   gcloud components list
   

   Jika sebelumnya Anda menginstal komponen beta, pastikan Anda memiliki versi terbaru:

   gcloud components update
   

3. Download dan gunakan skrip berikut untuk mengaktifkan API dan menetapkan izin yang sesuai untuk menggunakan Google Cloud CLI: set-permissions.sh.

   Untuk mengetahui informasi tentang skrip, lihat Skrip set-permissions.sh.

   Catatan: Skrip set-permissions.sh dirancang untuk berjalan di Linux. Jika Anda menggunakan mesin di sistem operasi yang berbeda, jalankan skrip dari Cloud Shell.

4. Gunakan perintah gcloud beta compute instances ops-agents policies create untuk membuat kebijakan. Untuk sintaksis perintah, lihat dokumentasi gcloud beta compute instances ops-agents policies create.

   Untuk contoh yang menunjukkan cara memformat perintah, lihat bagian Contoh dalam dokumentasi Google Cloud CLI.

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

Praktik terbaik untuk menggunakan kebijakan agen

Untuk mengontrol dampak pada sistem produksi selama peluncuran, sebaiknya Anda menggunakan label dan zona instance untuk memfilter instance yang menjadi tempat berlakunya kebijakan.

Berikut adalah contoh rencana peluncuran bertahap untuk VM Debian 11 dalam project yang disebut my_project:

Fase 1: Buat kebijakan bernama ops-agents-policy-safe-rollout untuk menginstal Agen Logging lama dan Agen Monitoring di semua VM dengan label env=test dan app=myproduct.

gcloud beta compute instances \
    ops-agents policies create ops-agents-policy-safe-rollout \
    --agent-rules="type=logging,version=current-major,package-state=installed,enable-autoupgrade=true;type=metrics,version=current-major,package-state=installed,enable-autoupgrade=true" \
    --os-types=short-name=debian,version=11 \
    --group-labels=env=test,app=myproduct \
    --project=my_project

Untuk mengetahui informasi selengkapnya tentang menentukan sistem operasi, lihat gcloud beta compute instances ops-agents policies create.

Fase 2: Perbarui kebijakan tersebut untuk menargetkan VM dalam satu zona yang memiliki label env=prod dan app=myproduct.

gcloud beta compute instances \
    ops-agents policies update ops-agents-policy-safe-rollout \
    --group-labels=env=prod,app=myproduct \
    --zones=us-central1-c \

Fase 3: Perbarui kebijakan tersebut untuk menghapus filter zona agar diluncurkan secara global

gcloud beta compute instances \
    ops-agents policies update ops-agents-policy-safe-rollout \
    --clear-zones

Kebijakan di VM yang lebih lama dari Konfigurasi OS

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

Memecahkan masalah kebijakan agen beta

Bagian ini memberikan informasi untuk membantu Anda menyelesaikan masalah terkait kebijakan agen beta untuk Ops Agent, agen Monitoring lama, dan agen Logging lama.

Perintah ops-agents policy gagal

Jika perintah gcloud beta 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:

• Izin IAM tidak memadai
• OS Config API tidak diaktifkan
• Kebijakan yang ditentukan tidak ada

Bagian berikut menjelaskan kondisi ini secara lebih mendetail.

Izin IAM tidak memadai

Jika perintah gcloud beta compute instances ops-agents policies gagal dengan error izin, pastikan Anda telah menjalankan skrip set-permissions.sh seperti yang dijelaskan dalam Membuat kebijakan agen untuk menyiapkan peran kebijakan OS Config:

• GuestPolicy Admin (roles/osconfig.guestPolicyAdmin): Memberikan akses penuh ke kebijakan tamu.
• GuestPolicy Editor (roles/osconfig.guestPolicyEditor): Memungkinkan pengguna mendapatkan, memperbarui, dan menampilkan daftar kebijakan tamu.
• GuestPolicy Viewer (roles/osconfig.guestPolicyViewer): Memberikan akses hanya baca untuk mendapatkan dan menampilkan daftar kebijakan tamu.

Untuk mengetahui informasi selengkapnya tentang skrip set-permissions.sh, lihat Skrip set-permissions.sh.

OS Config API tidak diaktifkan

Contoh error 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 set-permissions.sh, yang dijelaskan dalam Membuat kebijakan agen, untuk memberikan semua izin yang diperlukan. Jika Anda memasukkan y di prompt dalam pesan error, Anda masih perlu menjalankan skrip set-permissions.sh untuk menetapkan izin yang diperlukan.

Untuk memverifikasi bahwa OS Config API diaktifkan untuk project, 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 sudah ada

Contoh error terlihat seperti berikut:

ALREADY_EXISTS: Requested entity already exists

Error ini berarti kebijakan ini sudah ada dengan nama, project ID, dan region yang sama. Anda dapat menggunakan perintah gcloud beta compute instances ops-agents policies describe untuk mengonfirmasi hal ini.

Kebijakan tidak ada

Contoh error terlihat seperti berikut:

NOT_FOUND: Requested entity was not found

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

Kebijakan dibuat, tetapi sepertinya tidak berpengaruh

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

Linux

Untuk memverifikasi bahwa agen Konfigurasi OS telah 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 bahwa agen Konfigurasi OS 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 OS Config secara manual.

Agen OS Config diinstal, tetapi tidak menginstal agen Logging

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

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 terhubung ke layanan OS Config, pastikan Anda menjalankan skrip set-permissions.sh seperti yang dijelaskan dalam Membuat kebijakan agen untuk menyiapkan metadata OS Config.

Untuk memverifikasi bahwa metadata OS Config 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 observasi diinstal, tetapi tidak berfungsi dengan benar

Untuk informasi tentang proses debug agen tertentu, lihat dokumen berikut:

• Memecahkan masalah Agen Operasional
• Memecahkan masalah agen Logging lama
• Memecahkan masalah agen Monitoring lama

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 untuk mengaktifkan logging tingkat debug untuk agen Konfigurasi OS. Log yang dikumpulkan memiliki informasi lebih lanjut 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 helper

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

• Skrip set-permissions.sh
• Skrip diagnose.sh

Skrip set-permissions.sh

Setelah mendownload skrip set-permissions.sh, Anda dapat menggunakan skrip untuk melakukan tindakan berikut, berdasarkan argumen yang Anda berikan:

• Aktifkan Cloud Logging API, Cloud Monitoring API, dan OS Config API untuk project.

• Berikan peran Identity and Access Management Logs Writer (roles/logging.logWriter) dan Monitoring Metric Writer (roles/monitoring.metricWriter) ke akun layanan default Compute Engine sehingga agen dapat menulis log dan metrik ke Logging dan Cloud Monitoring API.

• Aktifkan metadata OS Config untuk project sehingga agen OS Config di setiap VM aktif.

• Berikan salah satu peran IAM berikut kepada pengguna non-pemilik, pengguna, atau akun layanan yang diperlukan untuk membuat dan mengelola kebijakan. Pemilik project memiliki akses penuh untuk membuat dan mengelola kebijakan; semua pengguna atau akun layanan lainnya harus diberi salah satu peran berikut:

  • GuestPolicy Admin (roles/osconfig.guestPolicyAdmin): Memberikan akses penuh ke kebijakan tamu.
  • GuestPolicy Editor (roles/osconfig.guestPolicyEditor): Memungkinkan pengguna mendapatkan, memperbarui, dan menampilkan daftar kebijakan tamu.
  • GuestPolicy Viewer (roles/osconfig.guestPolicyViewer): Memberikan akses hanya baca untuk mendapatkan dan menampilkan daftar kebijakan tamu.

  Saat menjalankan skrip, Anda hanya perlu menentukan bagian guestPolicy* dari nama peran. Skrip ini menyediakan bagian roles/osconfig. dari nama.

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

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

bash set-permissions.sh --project=PROJECT_ID

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

bash set-permissions.sh --project=PROJECT_ID \
  --iam-user=USER_EMAIL \
  --iam-permission-role=guestPolicy[Admin|Editor|Viewer]

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

bash set-permissions.sh --project=PROJECT_ID \
  --iam-service-account=SERVICE_ACCT_EMAIL \
  --iam-permission-role=guestPolicy[Admin|Editor|Viewer]

Skrip diagnose.sh

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

• Versi agen OS Config
• Kebijakan tamu OS Config yang mendasarinya
• Kebijakan yang berlaku untuk instance Compute Engine ini
• Repositori paket agen yang ditarik ke instance Compute Engine ini

Untuk memanggil skrip, jalankan perintah berikut:

bash diagnose.sh --project-id=PROJECT_ID \ 
  --gce-instance-id=INSTANCE_ID \
  --policy-id=POLICY_ID 

Integrasi Terraform

Untuk mempelajari cara menerapkan atau menghapus konfigurasi Terraform, lihat Perintah dasar Terraform. Untuk mengetahui informasi tentang cara kerja Terraform, lihat artikel Menggunakan Terraform.

Dukungan Terraform untuk kebijakan agen dibuat berdasarkan perintah Google Cloud CLI. Untuk membuat kebijakan agen menggunakan Terraform, ikuti petunjuk agent-policy modul Terraform. Anda juga dapat menemukan contoh kebijakan di direktori examples.