Menggunakan kebijakan agen (beta)

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.

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.

  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.

Jika Anda membuat kebijakan untuk Agen Operasional, pastikan VM Anda tidak menginstal Agen Logging atau Agen Pemantauan lama. Menjalankan Ops Agent dan agen lama di VM yang sama dapat menyebabkan penyerapan log duplikat atau konflik dalam penyerapan metrik. Jika perlu, uninstal Agen pemantauan dan uninstal Agen logging sebelum membuat kebijakan untuk menginstal Agen Operasional.

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 Ops Agent 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=ops-agent,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:

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:

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 perintah 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 Operasional

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:

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

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

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.