Menetapkan dan menghapus metadata kustom

Setiap entri metadata disimpan di server metadata sebagai pasangan nilai kunci. Kunci metadata peka huruf besar/kecil. Kunci Anda dapat berupa kunci metadata kustom atau yang telah ditentukan sebelumnya.

Metadata kustom memungkinkan Anda membuat dan menggunakan pasangan nilai kunci metadata Anda sendiri di VM atau project individual. Anda dapat menambahkan kunci metadata kustom baru, memperbarui nilai kunci yang ada, dan menghapus entri metadata kustom jika tidak diperlukan. Menetapkan metadata kustom berguna untuk meneruskan nilai arbitrer ke VM dalam project. Hal ini juga berguna untuk membuat skrip startup dan shutdown.

Dokumen ini memberikan informasi tentang cara melakukan hal berikut:

Sebelum memulai

  • Tinjau dasar-dasar cara metadata VM untuk Compute Engine ditentukan, dikategorikan, dan diatur. Untuk mengetahui informasi selengkapnya, lihat artikel Tentang metadata VM.

  • Jika Anda belum melakukannya, siapkan autentikasi. Autentikasi adalah proses yang digunakan untuk memverifikasi identitas Anda agar dapat mengakses Google Cloud layanan dan API. Untuk menjalankan kode atau contoh dari lingkungan pengembangan lokal, Anda dapat mengautentikasi ke Compute Engine dengan memilih salah satu opsi berikut:

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init
    2. Set a default region and zone.

      3. REST

      Untuk menggunakan contoh REST API di halaman ini dalam lingkungan pengembangan lokal, gunakan kredensial yang Anda berikan ke gcloud CLI.

        Install the Google Cloud CLI, then initialize it by running the following command: 

        gcloud init

      Untuk informasi selengkapnya, lihat Mengautentikasi untuk menggunakan REST dalam Google Cloud dokumentasi autentikasi.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan guna menetapkan atau menghapus metadata kustom di VM, minta administrator untuk memberi Anda peran IAM berikut:

Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk menetapkan atau menghapus metadata kustom di VM. Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk menetapkan atau menghapus metadata kustom di VM:

  • Jika VM Anda menggunakan akun layanan: iam.serviceAccounts.actAs di akun layanan atau project
  • Untuk menambahkan, memperbarui, atau menghapus metadata project kustom:
    • compute.projects.get dalam project
    • compute.projects.setCommonInstanceMetadata dalam project
  • Untuk menambahkan, memperbarui, atau menghapus metadata zona kustom:
    • compute.instanceSettings.get pada setelan instance di zona yang diperlukan dalam project
    • compute.instanceSettings.update pada setelan instance di zona yang diperlukan dalam project
  • Untuk menambahkan, memperbarui, atau menghapus metadata instance kustom:
    • compute.instances.get di VM
    • compute.instances.setMetadata di VM

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Batasan

Compute Engine menerapkan batas total gabungan sebesar 512 KB untuk semua entri metadata. Batas ukuran maksimum juga diterapkan untuk setiap key dan value dengan cara berikut:

  • Setiap metadata key memiliki batas maksimum 128 byte.

  • Setiap metadata key peka huruf besar/kecil.

    Untuk metadata zonal, Compute Engine tidak mengizinkan Anda membuat dua kunci metadata terpisah dengan string yang sama, meskipun ditulis dalam kasus yang berbeda. Misalnya, jika Anda sudah memiliki kunci metadata kustom untuk metadata zonal yang disebut project-zonal-metadata-key, maka untuk metadata zonal di zona tersebut, Anda tidak dapat membuat kunci metadata baru, seperti Project-Zonal-Metadata-Key, PROJECT-ZONAL-METADATA-KEY, atau variasi string yang sama lainnya.

  • Setiap metadata value memiliki batas maksimum 256 KB.

  • Setiap metadata value peka huruf besar/kecil, kecuali untuk nilai boolean.

Contohnya, kunci SSH disimpan sebagai metadata kustom pada kunci ssh-keys. Jika konten metadata Anda atau value untuk kunci ini melebihi batas 256 KB, Anda tidak akan dapat menambahkan lebih banyak kunci SSH. Jika Anda mencapai batas ini, sebaiknya hapus kunci yang tidak digunakan guna mengosongkan ruang metadata untuk kunci baru.

Selain itu, jika Anda memberikan konten skrip startup atau shutdown secara langsung, konten skrip startup dan shutdown ini mungkin juga disimpan sebagai metadata kustom dan diperhitungkan terhadap batasan ukuran ini. Untuk menghindari hal ini, simpan skrip startup atau shutdown Anda sebagai file yang dihosting di lokasi eksternal, seperti Cloud Storage, dan berikan URL skrip startup saat membuat VM. Dengan cara ini, file ini akan didownload ke VM, bukan disimpan di server metadata.

Nilai boolean

Untuk kolom yang menerima nilai boolean, TRUE atau FALSE, nilai berikut juga dapat digunakan:

Status Nilai alternatif
TRUE Y, Yes, 1
FALSE N, No, 0

Nilai Boolean tidak peka huruf besar/kecil. Misalnya, Anda dapat menggunakan False, false, atau FALSE untuk menonaktifkan fitur.

Menetapkan metadata kustom pada VM

Bagian ini memberikan informasi tentang cara menambahkan metadata kustom baru, atau memperbarui nilai metadata kustom yang ada, untuk VM Compute Engine Anda dengan salah satu cara berikut:

Menetapkan metadata project kustom

Anda dapat menambahkan atau memperbarui metadata kustom untuk semua instance dalam project menggunakan Konsol Google Cloud, Google Cloud CLI, atau REST.

Gunakan petunjuk ini untuk menerapkan setelan metadata ke semua VM dalam project. Misalnya, jika Anda menentukan pasangan metadata project baz=bat, pasangan metadata tersebut akan otomatis diterapkan ke semua VM dalam project.

Konsol

  1. Di Konsol Google Cloud, buka halaman Metadata.

    Buka halaman Metadata kustom

  2. Klik Edit di bagian atas halaman.

  3. Untuk menambahkan entri metadata project kustom baru, lakukan hal berikut:

    1. Buka bagian bawah halaman, lalu klik Tambahkan item.
    2. Di kolom Key, masukkan nama kunci metadata kustom Anda.
    3. Di kolom Nilai, masukkan nilai metadata project kustom.
    4. Opsional. Untuk menambahkan lebih banyak entri metadata project kustom, ulangi langkah-langkah sebelumnya untuk setiap entri metadata yang ingin Anda tambahkan.
    5. Untuk menyelesaikan penambahan entri metadata project kustom, klik Simpan.

  4. Untuk mengedit entri metadata project kustom yang ada, lakukan tindakan berikut:

    1. Buka entri metadata yang ingin Anda edit.
    2. Untuk memperbarui nama kunci metadata kustom tertentu, di kolom Key untuk entri tersebut, masukkan nama baru.
    3. Untuk memperbarui nilai entri metadata project kustom, di kolom Value untuk entri tersebut, masukkan nilai baru.
    4. Opsional. Untuk menghapus entri metadata project kustom tertentu, klik ikon hapus di samping entri metadata.
    5. Untuk mengedit beberapa entri metadata project kustom, ulangi langkah-langkah sebelumnya untuk setiap entri metadata yang ingin Anda edit.
    6. Untuk menyelesaikan pengeditan entri metadata project kustom, klik Simpan.

gcloud

Gunakan perintah project-info add-metadata.

gcloud compute project-info add-metadata \
    --metadata=KEY=VALUE

Ganti kode berikut:

  • KEY: nama kunci metadata Anda
  • VALUE: nilai yang disimpan untuk kunci ini

Contoh

Misalnya untuk menetapkan dua entri baru foo=bar dan baz=bat pada sebuah project, jalankan perintah berikut:

gcloud compute project-info add-metadata \
    --metadata=foo=bar,baz=bat

Secara opsional, Anda dapat menentukan satu atau beberapa file yang akan digunakan untuk membaca metadata menggunakan flag --metadata-from-file.

REST

  1. Opsional. Untuk melakukan penguncian optimis, Anda dapat menyediakan sidik jari secara opsional.

    Sidik jari adalah string karakter acak yang dihasilkan oleh Compute Engine. Sidik jari akan berubah setelah setiap permintaan, dan jika Anda memberikan sidik jari yang tidak cocok, permintaan Anda akan ditolak.

    Jika Anda tidak memberikan sidik jari, pemeriksaan konsistensi tidak akan dilakukan, dan permintaan projects().setCommonInstanceMetadata akan berhasil. Perilaku ini berbeda dengan metode instances().setMetadata dan instanceSettings().patch, yang selalu memerlukan sidik jari.

    Untuk mendapatkan sidik jari saat ini dari sebuah project, panggil metode project().get.

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID

    Outputnya mirip dengan yang berikut ini:

    {
  "name": "myproject",
  "commonInstanceMetadata": {
    "kind": "compute#metadata",
    "fingerprint": "FikclA7UBC0=",
    ...
  }
}

  2. Buat permintaan ke metode projects().setCommonInstanceMetadata dan tetapkan key-value pair metadata kustom Anda:

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/setCommonInstanceMetadata

{
  "fingerprint": "FikclA7UBC0=",
  "items": [
    {
    "key": "foo",
    "value": "bar"
    }
  ]
}

Ganti PROJECT_ID dengan project ID Anda.

Menetapkan metadata zona kustom

Saat menetapkan metadata zona kustom, Anda menambahkan atau memperbarui entri metadata zona untuk VM di zona tertentu dalam project. Anda dapat melakukan hal berikut dengan menetapkan metadata zona kustom:

  • Buat kunci metadata kustom baru untuk zona tertentu dalam project dan tetapkan metadata untuk semua VM di zona tersebut dalam project tersebut.
  • Memperbarui nilai entri metadata zona kustom yang ada untuk semua VM di zona tertentu dalam project.
  • Untuk kunci metadata kustom yang ada dan memiliki nilai metadata project, ganti nilai metadata project tersebut di zona tertentu dan tetapkan metadata zona. Setelah Anda menetapkan metadata zonal untuk kunci tersebut di zona tertentu, semua VM di zona tersebut dalam project tersebut akan menggunakan nilai metadata zonal untuk kunci tersebut.

Hal-hal yang perlu diperhatikan sebelum menetapkan metadata zona kustom

Entri metadata project dan zonal disimpan di direktori project/ yang sama. Jika Anda menetapkan nilai yang berbeda untuk kunci metadata kustom yang sama untuk VM di tingkat project dan di tingkat zona, nilai metadata zona untuk kunci tersebut akan lebih diutamakan daripada nilai metadata project di zona masing-masing.

  • Jika Anda menambahkan nilai metadata zonal untuk kunci metadata yang sudah memiliki nilai metadata project, Compute Engine akan mengganti nilai metadata project untuk VM di zona yang ditentukan ini dan memperbarui direktori /project dengan nilai zonal.
  • Jika Anda menambahkan nilai metadata baru di seluruh project untuk kunci metadata yang sudah memiliki nilai metadata zonal, tidak ada yang berubah. Compute Engine mempertahankan nilai metadata zona di direktori /project di zona tertentu.
  • Jika Anda tidak menentukan nilai metadata zonal untuk kunci metadata kustom di zona tertentu, tetapi kunci tersebut memiliki nilai metadata project, VM Anda akan terus memiliki nilai metadata project di zona tersebut.

Prosedur

Anda dapat menambahkan atau memperbarui metadata zona kustom di zona tertentu dalam project menggunakan Google Cloud CLI atau REST.

gcloud

  • Untuk menambahkan atau memperbarui metadata zona kustom, gunakan perintah gcloud compute project-zonal-metadata add.

    gcloud compute project-zonal-metadata add \
  --zone=ZONE \
  --project=PROJECT_ID  \
  --metadata=KEY1=VALUE1,KEY2=VALUE2,...

    Ganti kode berikut:

    • PROJECT_ID: project ID Anda
    • ZONE: zona tempat Anda ingin menambahkan atau memperbarui metadata zonal.
    • KEY1, KEY2...: kunci metadata kustom yang ingin Anda tambahkan atau perbarui nilai metadata zonal.

    • VALUE1, VALUE2...: nilai metadata zonal yang ingin Anda tetapkan untuk kunci metadata kustom yang ada dan baru. Bergantung pada kunci dan nilai metadata kustom Anda, salah satu hal berikut akan terjadi:

    • Jika kunci metadata kustom yang sesuai adalah kunci yang ada dan memiliki metadata project, maka, di zona yang ditentukan, Compute Engine akan mengganti nilai metadata project kunci dengan nilai metadata zona yang Anda tentukan. Semua VM di zona yang ditentukan dalam project mewarisi metadata zona yang baru ditentukan ini untuk kunci tersebut dan VM di zona lain terus mempertahankan nilai metadata zona atau project yang berlaku. Jika Anda melakukan pembaruan pada nilai metadata project untuk kunci ini di masa mendatang, VM di zona ini dalam project tidak akan terpengaruh dan akan terus menggunakan nilai metadata zona untuk kunci ini.

    • Jika kunci metadata kustom yang sesuai adalah kunci metadata baru yang tidak digunakan untuk metadata zonal atau project yang ada, Compute Engine akan membuat kunci metadata kustom dan menetapkan nilai ini sebagai metadata zonal di zona yang ditentukan.

    • Jika kunci metadata kustom yang sesuai adalah kunci metadata yang ada dengan nilai metadata zonal di zona yang ditentukan:

      • Jika nilai metadata yang ditentukan berbeda dengan nilai yang ada, Compute Engine akan memperbarui entri metadata zona dengan nilai baru.
      • Jika nilai metadata yang ditentukan sama dengan nilai yang ada, entri metadata zonal tidak akan berubah.

Contoh: Menambahkan entri metadata zona kustom baru

Misalnya, pertimbangkan project bernama my-project dengan metadata kustom berikut:

  • Metadata project: "key-1":"value-a", "key-2":"value-b", dan "key-3":"value-c"
  • Metadata zonal di zona us-central1-a: "key-1":"value-1" dan "key-2":"value-2"

Untuk menambahkan "key-4":"value-4" sebagai pasangan metadata zona kustom baru di zona us-central1-a, jalankan perintah berikut

gcloud compute project-zonal-metadata add \
    --metadata=key-4=value-4 \
    --project=my-project \
    --zone=us-central1-a

Contoh: Memperbarui nilai entri metadata zona kustom yang ada

Pertimbangkan contoh project my-project yang sama, yang kini memiliki metadata kustom berikut:

  • Metadata project: "key-1":"value-a", "key-2":"value-b", dan "key-3":"value-c"
  • Metadata zona di zona us-central1-a: "key-1":"value-1", "key-2":"value-2", dan "key-4":"value-4"

Untuk memperbarui nilai metadata zonal key-1 dan key-4 di zona us-cerntral1-a dengan nilai baru, jalankan perintah berikut.

gcloud compute project-zonal-metadata add \
    --metadata=key-1=new-value-1,key-4=new-value-4 \
    --project=my-project \
    --zone=us-central1-a

Contoh: Ganti nilai metadata project untuk kunci dan gunakan nilai metadata zona

Pertimbangkan contoh project my-project yang sama, yang kini memiliki metadata kustom berikut:

  • Metadata project: "key-1":"value-a", "key-2":"value-b", dan "key-3":"value-c"
  • Metadata zona di zona us-central1-a: "key-1":"new-value-1", "key-2":"value-2", dan "key-4":"new-value-4"

Dalam contoh project ini, pertimbangkan key-3, yang memiliki nilai metadata project value-c. Misalnya, Anda ingin menetapkan nilai metadata zona value-3 untuk kunci ini bagi semua VM di zona us-central1-a. Saat Anda melakukan operasi, untuk semua VM di zona us-central1-a, Compute Engine akan mengganti nilai metadata project dan menggunakan nilai metadata zona. VM di semua zona lain dalam project akan mempertahankan nilai metadata zona atau project yang berlaku untuk key-3.

Untuk mengganti nilai metadata project untuk key-3 dan menetapkan nilai metadata zona, jalankan perintah berikut:

gcloud compute project-zonal-metadata add \
    --metadata=key-3=value-3 \
    --project=my-project \
    --zone=us-central1-a

REST

  1. Dapatkan sidik jari saat ini dan lihat pasangan nilai kunci yang ada untuk project di zona tersebut.

    Untuk melakukan penguncian optimis, Anda harus memberikan sidik jari. Sidik jari adalah string karakter acak yang dihasilkan oleh Compute Engine. Sidik jari berubah setiap kali Anda membuat permintaan untuk menambahkan, memperbarui, atau menghapus metadata zona, dan jika Anda memberikan sidik jari yang tidak cocok, Compute Engine akan menolak permintaan Anda.

    Jika Anda tidak memberikan sidik jari, pemeriksaan konsistensi akan dilakukan dan permintaan update Anda tidak berhasil. Hal ini berfungsi sehingga hanya satu permintaan yang dapat dilakukan pada satu waktu, sehingga mencegah konflik. Perilaku ini cocok dengan instances().setMetadata, yang selalu memerlukan sidik jari.

    Untuk mendapatkan sidik jari metadata zona saat ini, buat permintaan GET ke metode instanceSettings().get.

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceSettings

    Ganti kode berikut:

    • PROJECT_ID: project ID Anda
    • ZONE: zona tempat Anda ingin menetapkan metadata zonal.

    Berikut adalah contoh output untuk permintaan ini:

        {
      "fingerprint": "VlRIl8dx9vk=",
      "metadata": {
        ...
      }
    }

  2. Untuk menambahkan atau memperbarui metadata zonal, buat permintaan PATCH ke metode instanceSettings().patch. Anda harus memberikan hal berikut dengan permintaan Anda:

    • Mask pembaruan. Gunakan parameter kueri update_mask. Mask update harus berisi kunci metadata untuk hal berikut:

      • Metadata zona kustom baru yang ingin Anda tambahkan
      • Metadata zona kustom yang ada yang nilainya ingin Anda perbarui

      Anda harus menambahkan string metadata.items. sebagai awalan untuk setiap kunci—misalnya, metadata.items.key1,metadata.items.key3.

    • Dalam isi permintaan, berikan hal berikut:

      • Kunci dan nilai metadata untuk metadata zona kustom baru yang ingin Anda tambahkan
      • Kunci dan nilai metadata untuk metadata zona kustom yang ada yang ingin Anda perbarui
      • Nilai sidik jari saat ini

    PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceSettings?update_mask=PREFIXED_METADATA_KEYS
{
  "fingerprint": "FINGER_PRINT",
  "metadata": {
    "items": {
      "KEY1": "VALUE1",
      "KEY2": "VALUE2",
      ...
    }
  }
}

    Ganti kode berikut:

    • PROJECT_ID: ID project.
    • ZONE: zona tempat Anda ingin menetapkan metadata zonal.

    • PREFIXED_METADATA_KEYS: daftar kunci metadata untuk hal berikut, dengan setiap kunci diawali dengan string metadata.items. :

      • Metadata zona kustom baru yang ingin Anda tambahkan
      • Metadata zona kustom yang ada yang nilainya ingin Anda perbarui

      Misalnya, kunci metadata zonal Anda saat ini di zona tertentu adalah key-1 dan key-2. Jika Anda ingin menambahkan kunci baru, key-3, untuk metadata zonal di zona tersebut dan juga memperbarui metadata zonal untuk salah satu kunci yang ada, key-1, maka mask pembaruan Anda harus memiliki string berikut:

      metadata.items.key1,metadata.items.key3

    • FINGER_PRINT: nilai sidik jari saat ini.

    • KEY1, KEY2...: kunci metadata zona kustom yang ingin Anda tambahkan atau perbarui nilainya. Tentukan semua kunci metadata zona kustom yang Anda tentukan dalam mask pembaruan.

    • VALUE1, VALUE2...: nilai metadata zonal yang ingin Anda tetapkan untuk kunci metadata kustom yang ada dan baru. Bergantung pada kunci dan nilai metadata kustom Anda, salah satu hal berikut akan terjadi:

      • Jika kunci metadata kustom yang sesuai adalah kunci yang ada dan memiliki metadata project, maka, di zona yang ditentukan, Compute Engine akan mengganti nilai metadata project kunci dengan nilai metadata zona yang Anda tentukan. Semua VM di zona yang ditentukan dalam project mewarisi metadata zona yang baru ditentukan ini untuk kunci tersebut dan VM di zona lainnya akan terus mempertahankan nilai metadata zona atau project yang berlaku. Jika Anda melakukan pembaruan pada nilai metadata project untuk kunci ini di masa mendatang, VM di zona ini dalam project tidak akan terpengaruh dan akan terus menggunakan nilai metadata zona untuk kunci ini.
      • Jika kunci metadata kustom yang sesuai adalah kunci metadata baru yang tidak digunakan untuk metadata zonal atau project yang ada, Compute Engine akan membuat kunci metadata kustom dan menetapkan nilai ini sebagai metadata zonal di zona yang ditentukan.

      • Jika kunci metadata kustom yang sesuai adalah kunci metadata yang ada dengan nilai metadata zonal di zona yang ditentukan:

      • Jika nilai metadata yang ditentukan berbeda dengan nilai yang ada, Compute Engine akan memperbarui entri metadata zona dengan nilai baru.

      • Jika nilai metadata yang ditentukan sama dengan nilai yang ada, entri metadata zonal tidak akan berubah.

Contoh: Menambahkan entri metadata zona kustom baru

Misalnya, pertimbangkan project bernama my-project dengan metadata kustom berikut:

  • Metadata project: "key-1":"value-a", "key-2":"value-b", dan "key-3":"value-c"
  • Metadata zonal di zona us-central1-a: "key-1":"value-1" dan "key-2":"value-2"

Untuk menambahkan "key-4":"value-4" sebagai pasangan metadata zona kustom baru di zona us-central1-a, buat permintaan PATCH berikut:

PATCH https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-4
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-4": "value-4"
    }
  }
}

Contoh: Memperbarui nilai entri metadata zona kustom yang ada

Pertimbangkan contoh project my-project yang sama, yang kini memiliki metadata kustom berikut:

  • Metadata project: "key-1":"value-a", "key-2":"value-b", dan "key-3":"value-c"
  • Metadata zona di zona us-central1-a: "key-1":"value-1", "key-2":"value-2", dan "key-4":"value-4"

Untuk memperbarui nilai metadata zonal key-1 dan key-4 di zona us-cerntral1-a dengan nilai baru, buat permintaan PATCH berikut:

PATCH https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-1,metadata.items.key-4
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-1": "new-value-1",
    "key-4": "new-value-4"
    }
  }
}

Contoh: Mengganti nilai metadata project untuk kunci dan menetapkan nilai metadata zonal

Pertimbangkan contoh project my-project yang sama, yang kini memiliki metadata kustom berikut:

  • Metadata project: "key-1":"value-a", "key-2":"value-b", dan "key-3":"value-c"
  • Metadata zona di zona us-central1-a: "key-1":"new-value-1", "key-2":"value-2", dan "key-4":"new-value-4"

Dalam contoh project ini, pertimbangkan key-3, yang memiliki nilai metadata project value-c. Misalnya, Anda ingin menetapkan nilai metadata zona value-3 untuk kunci ini bagi semua VM di zona us-central1-a. Saat Anda melakukan operasi, untuk semua VM di zona us-central1-a, Compute Engine akan mengganti nilai metadata project dan menggunakan nilai metadata zona. VM di semua zona lain dalam project akan mempertahankan nilai metadata zona atau project yang berlaku untuk key-3.

Untuk mengganti nilai metadata project untuk key-3 dan menggunakan nilai metadata zona value-3, buat permintaan PATCH berikut:

PATCH https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-3
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-3": "value-3"
    }
  }
}

Menetapkan metadata instance kustom

Anda dapat menambahkan atau memperbarui metadata kustom untuk satu instance VM menggunakan konsol Google Cloud, Google Cloud CLI, atau REST.

Anda dapat menetapkan metadata instance kustom dengan salah satu cara berikut:

Menambahkan metadata instance kustom selama pembuatan VM

Gunakan petunjuk ini untuk menambahkan metadata pada instance VM tertentu pada saat pembuatannya.

Konsol

  1. Di konsol Google Cloud, buka halaman Create an instance.

    Buka Create an instance

  2. Tentukan detail VM.

  3. Luaskan bagian Opsi lanjutan, dan lakukan hal berikut:

    1. Luaskan bagian Pengelolaan.
    2. Untuk menambahkan beberapa key-value pair untuk metadata kustom Anda, di bagian Metadata, klik Tambahkan item.

  4. Untuk membuat VM, klik Buat.

gcloud

Untuk menetapkan metadata kustom, gunakan perintah gcloud compute instances create dengan flag --metadata.

gcloud compute instances create VM_NAME \
--zone=ZONE \
--image-project=IMAGE_PROJECT \
IMAGE_FLAG \
--metadata=KEY=VALUE

Ganti kode berikut:

  • VM_NAME: nama VM Anda
  • ZONE: zona untuk membuat VM
  • IMAGE_PROJECT: project yang berisi image yang akan digunakan untuk VM

  • IMAGE_FLAG: tentukan salah satu dari hal berikut:

    • Gunakan flag --image IMAGE_NAME untuk menentukan versi image publik tertentu.

      Misalnya, --image debian-12-bookworm-v20241112.

    • Gunakan flag --image-family IMAGE_FAMILY_NAME untuk menentukan kelompok image.

      Tindakan ini akan membuat VM dari image OS terbaru yang tidak digunakan lagi dalam kelompok image. Misalnya, jika Anda menentukan --image-family debian-12, Compute Engine akan menggunakan OS image versi terbaru dalam kelompok image Debian 12.

  • KEY: nama kunci metadata Anda

  • VALUE: nilai yang disimpan untuk kunci ini

Contoh

Misalnya untuk menetapkan kunci baru env yang memiliki nilai test pada VM bernama example-instance, jalankan perintah berikut:

 gcloud compute instances create example-instance \
   --zone=us-central1-a --image-project=debian-cloud \
   --image-family=debian-12 \
   --metadata=env=test

REST

Gunakan metode instances.insert dan berikan metadata kustom sebagai bagian dari properti metadata dalam permintaan Anda:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances

{
  "machineType": "zones/MACHINE_TYPE_ZONE/machineTypes/MACHINE_TYPE",
  "name": "VM_NAME",
  "...": [
    {
    }
    ],
  "metadata": {
    "items": [
      {
        "key": "KEY",
        "value": "VALUE"
      }
    ]
  },
  ..
}

Ganti kode berikut:

  • PROJECT_ID: project ID Anda
  • ZONE: zone tempat VM akan dibuat
  • MACHINE_TYPE: jenis mesin, bawaan atau kustom, untuk VM yang baru
  • VM_NAME: nama VM baru
  • KEY: nama kunci metadata Anda
  • VALUE: nilai yang disimpan untuk kunci ini

Menambahkan atau memperbarui metadata instance kustom di VM yang ada

Gunakan petunjuk ini untuk memperbarui metadata pada instance VM tertentu yang sudah ada.

Konsol

  1. Di Konsol Google Cloud, buka halaman VM instances.

    Buka halaman Instance VM

  2. Klik instance yang metadatanya ingin Anda perbarui.
  3. Klik tombol Edit di bagian atas halaman.
  4. Di bagian Metadata kustom, klik Tambahkan item atau edit entri metadata yang sudah ada.
  5. Simpan perubahan Anda.

gcloud

Memperbarui metadata VM dengan gcloud CLI adalah tindakan tambahan. Tentukan hanya kunci metadata yang ingin ditambahkan atau diubah. Jika kunci yang Anda berikan sudah ada, nilai untuk kunci tersebut akan diperbarui dengan nilai baru.

Gunakan perintah instances add-metadata:

gcloud compute instances add-metadata VM_NAME \
    --metadata=KEY=VALUE,KEY=VALUE

Ganti kode berikut:

  • VM_NAME: nama VM Anda
  • KEY: nama kunci metadata Anda
  • VALUE: nilai yang disimpan untuk kunci ini

Contoh

Jika Anda ingin menambahkan entri foo=bar, gunakan:

gcloud compute instances add-metadata VM_NAME \
    --metadata=foo=bar

Jika Anda ingin mengubah entri foo=bar menjadi foo=bat, gunakan:

gcloud compute instances add-metadata VM_NAME \
    --metadata=foo=bat

REST

  1. Dapatkan sidik jari saat ini dan lihat pasangan nilai kunci yang sudah ada untuk VM. Untuk melakukannya, panggil metode instances().get.

    Sidik jari adalah string karakter acak yang dihasilkan oleh Compute Engine dan digunakan untuk melakukan penguncian optimis. Untuk memperbarui VM, Anda harus memberikan nilai sidik jari yang cocok. Sidik jari akan berubah setelah setiap permintaan, dan jika Anda memberikan sidik jari yang tidak cocok, permintaan Anda akan ditolak. Hal ini berfungsi sehingga hanya satu pembaruan yang dapat dilakukan pada satu waktu, sehingga mencegah konflik.

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME

    Ganti kode berikut:

    • PROJECT_ID: project ID Anda
    • ZONE: zona tempat VM berada
    • VM_NAME: nama VM Anda

    Outputnya mirip dengan hal berikut ini:

    {
  ...
  "name": "example-instance",
  "metadata": {
    "kind": "compute#metadata",
    "fingerprint": "zhma6O1w2l8="
    "items": [
      {
        "key": "foo",
        "value": "bar"
      }
    ]
    },
  ...
}

  2. Buat permintaan ke metode instances().setMetadata. Berikan daftar nilai metadata baru dan nilai fingerprint saat ini.

    Jika VM memiliki key-value pair yang sudah ada dan ingin dipertahankan, Anda harus menyertakannya dalam permintaan ini dengan key-value pair baru.

    Contoh

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata

{
"fingerprint": "zhma6O1w2l8=",
"items": [
  {
    "key": "foo",
    "value": "bar"
  },
  {
    "key": "baz",
    "value": "bat"
  }
]
}

    Ganti kode berikut:

    • PROJECT_ID: project ID Anda
    • ZONE: zona tempat VM berada
    • VM_NAME: nama VM Anda

Menghapus metadata kustom dari VM

Bagian ini memberikan informasi tentang cara menghapus entri metadata kustom untuk VM Compute Engine Anda dengan salah satu cara berikut:

Menghapus metadata project kustom

Anda dapat menghapus metadata project kustom menggunakan Konsol Google Cloud atau Google Cloud CLI.

Konsol

  1. Di Konsol Google Cloud, buka halaman Metadata.

    Buka halaman Metadata

  2. Klik Edit di bagian atas halaman.

  3. Buka entri metadata yang ingin Anda hapus, lalu klik tombol hapus di samping entri tersebut.

    Ulangi langkah ini untuk setiap entri metadata yang ingin Anda hapus.

  4. Untuk menyelesaikan penghapusan entri metadata project kustom, klik Simpan.

gcloud

Untuk menghapus metadata project kustom, gunakan perintah gcloud compute project-info remove-metadata.

  • Jika Anda ingin menghapus entri metadata kustom untuk kunci tertentu, tentukan kunci tersebut menggunakan flag --keys, dan kecualikan nilai kunci tersebut.
gcloud compute project-info remove-metadata \
    --keys=KEY1,KEY2,...
  • Jika Anda ingin menghapus semua metadata kustom untuk VM, tentukan flag --all.
gcloud compute project-info remove-metadata \
    --all

Ganti kode berikut:

  • KEY1, KEY2...: kunci metadata instance kustom yang ingin Anda hapus.

Menghapus metadata zona kustom

Anda dapat menghapus metadata zona kustom menggunakan Google Cloud CLI atau REST.

gcloud

Untuk menghapus metadata zona kustom, gunakan perintah gcloud compute project-zonal-metadata remove dan tentukan semua kunci metadata yang ingin Anda hapus menggunakan flag --keys.

gcloud compute project-zonal-metadata remove \
    --project=PROJECT_ID  \
    --zone=ZONE \
    --keys=KEY1,KEY2,...

Ganti kode berikut:

  • PROJECT_ID: project ID Anda
  • ZONE: zona tempat Anda ingin menghapus metadata zonal.
  • KEY1, KEY2...: kunci metadata zona kustom yang ingin Anda hapus.

Setelah Anda menjalankan perintah, jika salah satu kunci yang ditentukan memiliki nilai metadata project yang tersedia, VM di zona yang ditentukan akan mewarisi nilai metadata project tersebut. Jika entri metadata hanya ditetapkan di tingkat zona dan tidak ada nilai metadata project yang sesuai untuk kunci tersebut, VM di zona tersebut akan kehilangan informasi metadata tersebut.

Contoh:

Pertimbangkan contoh project my-project, yang memiliki metadata project kustom berikut:

  • Metadata project: "key-1":"value-a", "key-2":"value-b", dan "key-3":"value-c"
  • Metadata zona di zona us-central1-a: "key-1":"new-value-1", "key-2":"value-2", "key-3":"value-3", dan "key-4":"new-value-4"

Untuk menghapus semua metadata zonal di zona us-central1-a, jalankan perintah berikut.

gcloud compute project-zonal-metadata remove \
    --metadata=key-1,key-2,key-3,key-4 \
    --project=my-project \
    --zone=us-central1-a

Setelah Anda menjalankan perintah, VM di zona us-central1-a memiliki entri metadata project kustom berikut:

  • "key-1":"value-a"
  • "key-2":"value-b"
  • "key-3":"value-c"

REST

  1. Dapatkan sidik jari saat ini dan lihat pasangan nilai kunci yang ada untuk project di zona tersebut.

    Untuk melakukan penguncian optimis, Anda harus memberikan sidik jari. Sidik jari adalah string karakter acak yang dihasilkan oleh Compute Engine. Sidik jari berubah setiap kali Anda membuat permintaan untuk menambahkan, memperbarui, atau menghapus metadata zona, dan jika Anda memberikan sidik jari yang tidak cocok, Compute Engine akan menolak permintaan Anda.

    Jika Anda tidak memberikan sidik jari, pemeriksaan konsistensi akan dilakukan dan permintaan penghapusan Anda tidak akan berhasil. Hal ini berfungsi sehingga hanya satu permintaan yang dapat dilakukan pada satu waktu, sehingga mencegah konflik. Perilaku ini cocok dengan instances().setMetadata, yang selalu memerlukan sidik jari.

    Untuk mendapatkan sidik jari saat ini dari sebuah project, lakukan panggilan metode instanceSettings().get.

    GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings

    Ganti kode berikut:

    • PROJECT_ID: project ID Anda
    • ZONE: zona tempat Anda ingin menghapus metadata zonal.

    Berikut adalah contoh output untuk permintaan ini:

        {
      "fingerprint": "FikclA7UBC0=",
      "metadata": {
        ...
      }
    }

  2. Untuk menghapus metadata zona kustom, buat permintaan PATCH ke metode instanceSettings().patch dengan mengecualikan kunci metadata, yang metadata zonanya ingin Anda hapus, dari isi permintaan. Anda harus memberikan hal berikut dengan permintaan Anda:

    • Mask pembaruan. Gunakan parameter kueri update_mask. Mask update harus berisi semua kunci metadata kustom yang ada yang metadata zonanya ingin Anda hapus. Anda harus menambahkan string metadata.items. sebagai awalan untuk setiap kunci—misalnya, metadata.items.key1,metadata.items.key3.

    • Dalam isi permintaan, hanya berikan nilai sidik jari saat ini. Kecualikan semua kunci metadata kustom yang Anda tentukan dalam mask update. Jika Anda menyertakan kunci metadata apa pun dalam mask update dan isi permintaan, Compute Engine tidak akan menghapus metadata zonal untuk kunci tersebut. 

    PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings?update_mask=PREFIXED_METADATA_KEYS
{
  "fingerprint": "FINGER_PRINT",
  "metadata": {
    "items": {
    }
  }
}

    Ganti kode berikut:

    • PROJECT_ID: ID project.
    • ZONE: zona tempat Anda ingin menghapus metadata zonal.

    • PREFIXED_METADATA_KEYS: daftar semua kunci metadata kustom yang ada yang metadata zonanya ingin Anda hapus, dengan setiap kunci diawali dengan string metadata.items. . Untuk memastikan permintaan penghapusan Anda berhasil, kecualikan kunci metadata ini dari isi permintaan. Jika Anda menyertakan kunci metadata apa pun dalam mask update dan isi permintaan, Compute Engine tidak akan menghapus metadata zonal untuk kunci tersebut.

      Misalnya, kunci metadata saat ini dengan metadata zona adalah key-1, key-2, key-3, dan key-4, dan Anda ingin menghapus entri metadata zona untuk key-1 dan key-2, maka mask update Anda harus memiliki string berikut:

      metadata.items.key1,metadata.items.key2

    • FINGER_PRINT: nilai sidik jari saat ini.

Setelah Anda membuat permintaan, jika salah satu kunci yang ditentukan memiliki nilai metadata project yang tersedia, VM di zona yang ditentukan akan mewarisi nilai metadata project tersebut. Jika kunci metadata hanya ditetapkan di tingkat zona dan tidak ada nilai metadata project yang sesuai untuk kunci tersebut, VM di zona tersebut akan kehilangan informasi metadata tersebut.

Contoh:

Pertimbangkan contoh project my-project, yang memiliki metadata project kustom berikut:

  • Metadata project: "key-1":"value-a", "key-2":"value-b", dan "key-3":"value-c"
  • Metadata zona di zona us-central1-a: "key-1":"new-value-1", "key-2":"value-2", "key-3":"value-3", dan "key-4":"new-value-4"

Untuk menghapus metadata zona untuk key-1 dan key-2 di zona us-central1-a, buat permintaan PATCH berikut.

PATCH https://compute.googleapis.com/compute/beta/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-1,metadata.items.key-2
{
  "fingerprint": "FikclA7UBC0=",
  "metadata": {
  "items": {
    }
  }
}

Setelah permintaan ini diproses, VM di zona us-central1-a memiliki metadata kustom berikut. VM mewarisi nilai metadata project untuk key-1 dan key-2, tetapi mempertahankan metadata zona untuk key-3 dan key-4.

  • Metadata project: "key-1":"value-a" dan "key-2":"value-b"
  • Metadata zonal di zona us-central1-a: "key-3":"value-3" dan "key-4":"new-value-4"

Menghapus metadata instance kustom

Anda dapat menghapus metadata instance kustom menggunakan konsol Google Cloud, Google Cloud CLI, atau REST.

Konsol

  1. Di Konsol Google Cloud, buka halaman VM instances.

    Buka halaman VM instances

  2. Di kolom Name, klik nama VM yang metadatanya ingin Anda hapus.
  3. Klik Edit di bagian atas halaman.
  4. Di bagian Metadata, klik Delete item untuk setiap entri metadata yang ingin Anda hapus.
  5. Untuk mengonfirmasi perubahan dan menghapus metadata instance kustom, klik Save.

gcloud

Untuk menghapus metadata instance kustom, gunakan perintah gcloud compute instances remove-metadata.

  • Jika Anda ingin menghapus entri metadata kustom untuk kunci tertentu, tentukan kunci tersebut menggunakan flag --keys, dan kecualikan nilai kunci tersebut.
gcloud compute instances remove-metadata VM_NAME \
    --zone=ZONE  \
    --keys=KEY1,KEY2,...
  • Jika Anda ingin menghapus semua metadata kustom untuk VM, tentukan flag --all.
gcloud compute instances remove-metadata VM_NAME \
    --zone=ZONE  \
    --all

Ganti kode berikut:

  • PROJECT_ID: project ID Anda.
  • ZONE: zona VM Anda.
  • VM_NAME: nama VM Anda
  • KEY1, KEY2...: kunci metadata instance kustom yang ingin Anda hapus.

REST

  1. Dapatkan sidik jari saat ini dan lihat pasangan nilai kunci yang sudah ada untuk VM. Untuk melakukannya, panggil metode instances().get.

    Sidik jari adalah string karakter acak yang dihasilkan oleh Compute Engine dan digunakan untuk melakukan penguncian optimis. Untuk memperbarui VM, Anda harus memberikan nilai sidik jari yang cocok. Sidik jari akan berubah setelah setiap permintaan, dan jika Anda memberikan sidik jari yang tidak cocok, permintaan Anda akan ditolak. Hal ini berfungsi sehingga hanya satu pembaruan yang dapat dilakukan pada satu waktu, sehingga mencegah konflik.

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME

    Ganti kode berikut:

    • PROJECT_ID: project ID Anda.
    • ZONE: zona VM Anda.
    • VM_NAME: nama VM Anda

    Outputnya mirip dengan hal berikut ini:

    {
  ...
  "name": "example-instance",
  "metadata": {
    "kind": "compute#metadata",
    "fingerprint": "zhma6O1w2l8="
    "items": [
    {
      "key": "key-1",
      "value": "value-1"
    }
    {
      "key": "key-2",
      "value": "value-2"
    }
    ]
  },
  ...
}

  2. Buat permintaan ke metode instances().setMetadata. Anda harus menyertakan nilai sidik jari metadata saat ini agar permintaan Anda berhasil.

    • Untuk menghapus semua key-value pair metadata kustom dari VM, di properti items, kecualikan kunci metadata yang ingin Anda hapus nilai metadatanya.

      POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata

{
"fingerprint": "FINGER_PRINT"
"items": [
  {
    "key": "KEY1"
    "value": "VALUE1"
  }
  {
    "key": "KEY2"
    "value": "VALUE2"
  }
  ...
]
}

    • Untuk menghapus semua metadata instance kustom di VM, kecualikan properti items secara keseluruhan.

      POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata

{
"fingerprint": FINGER_PRINT
}

    Ganti kode berikut:

    • PROJECT_ID: project ID Anda.
    • ZONE: zona VM Anda.
    • VM_NAME: nama VM Anda
    • FINGER_PRINT: nilai sidik jari saat ini.
    • KEY1, KEY2...: kunci metadata instance kustom yang ingin Anda hapus.
    • VALUE1, VALUE2...: nilai kunci metadata instance kustom yang ingin Anda hapus.

Langkah berikutnya