Memperbarui properti instance

Anda dapat menggunakan satu permintaan dari Google Cloud CLI atau Compute Engine API untuk memperbarui beberapa properti instance dan secara opsional memulai ulang instance, jika diperlukan. Metode pembaruan menangani logika untuk memvalidasi properti instance yang diperbarui dan memastikan bahwa resource yang diperlukan tersedia agar pembaruan berhasil dilakukan. Jika permintaan menyertakan properti yang tidak valid atau jika resource yang diminta tidak tersedia, permintaan akan menampilkan error dan tidak membuat perubahan pada instance Anda. Tindakan ini melindungi instance dari pembaruan parsial dan melindungi instance agar tidak dihentikan dan tidak dapat mengakses resource untuk memulai kembali.

Sebelum memulai

  • Siapkan autentikasi, jika Anda belum melakukannya. Autentikasi adalah proses verifikasi identitas Anda untuk akses ke layanan dan API Google Cloud. Untuk menjalankan kode atau contoh dari lingkungan pengembangan lokal, Anda dapat melakukan autentikasi ke Compute Engine sebagai berikut.

    Pilih tab untuk melihat bagaimana Anda berencana menggunakan contoh di halaman ini:

    Konsol

    Saat menggunakan Konsol Google Cloud untuk mengakses API dan layanan Google Cloud, Anda tidak perlu menyiapkan autentikasi.

    gcloud

    1. Instal Google Cloud CLI, lalu initialize dengan menjalankan perintah berikut: 

      gcloud init
    2. Menetapkan region dan zona default.

    REST

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

      Instal Google Cloud CLI, lalu initialize dengan menjalankan perintah berikut: 

      gcloud init

Pembatasan

  • Permintaan pembaruan instance melalui gcloud CLI atau Compute Engine API tidak mendukung semantik PATCH. Resource instance dalam permintaan pembaruan harus menyertakan semua properti instance. Properti yang tidak ada dalam konfigurasi instance pada permintaan pembaruan Anda dianggap sudah dihapus dari instance.
  • Anda hanya dapat memperbarui daftar properti tertentu.
  • Mengubah instance ke dan dari tenancy tunggal tidak didukung.
  • Anda dapat mengubah instance dari satu pemesanan ke pemesanan lainnya, tetapi Anda tidak dapat melampirkan atau melepaskan instance ke pemesanan menggunakan proses pembaruan.
  • Jika instance memiliki SSD lokal yang terpasang, Anda tidak dapat memperbarui properti yang mengharuskan instance untuk dimulai ulang. Anda harus menghapus, lalu membuat ulang instance. Pastikan Anda memigrasikan data penting dari SSD lokal ke persistent disk atau ke VM lain sebelum menghapus VM.
  • Jika instance menggunakan resource yang hanya tersedia di Compute Engine API beta, Anda harus menggunakan versi metode instances.update yang benar untuk memperbarui properti tersebut. Misalnya, jika Anda membuat instance menggunakan Compute Engine API beta dan mengonfigurasi instance dengan resource yang hanya dikenali API beta, Anda juga harus menggunakan metode instances.update versi beta untuk memperbarui resource tersebut. Versi v1 metode instances.update tidak mengenali resource beta yang digunakan instance Anda, sehingga akan menghapus resource beta tersebut dari konfigurasi instance selama proses pembaruan. Hal ini juga berlaku untuk resource di API alfa.

Izin

Anda harus memiliki izin compute.instances.update untuk memperbarui instance. Izin ini disertakan dalam beberapa peran Identity and Access Management (IAM) yang ada. Anda juga harus memiliki izin untuk menggunakan resource yang ingin Anda ubah pada instance. Misalnya, untuk menambahkan disk ke instance, Anda harus memiliki izin berikut:

  • Izin compute.instances.update pada instance yang ingin Anda perbarui.
  • Izin compute.disks.use untuk disk yang ada atau compute.disks.create pada project tempat Anda ingin membuat disk baru.

Praktik terbaik

Untuk memastikan antarmuka pembaruan instance berfungsi paling efektif untuk Anda, gunakan praktik terbaik berikut:

  • Jika memungkinkan, gunakan versi Compute Engine API yang sama secara konsisten untuk membuat, menetapkan, dan memperbarui instance. Ini memastikan Anda dapat memperbarui dan mengubah resource instance jika resource tersebut hanya tersedia dalam satu versi API.
  • Meskipun Anda dapat menggunakan metode instances.update untuk memperbarui instance dalam grup instance terkelola (MIG), untuk sebagian besar situasi, sebaiknya ubah template instance grup dan luncurkan pembaruan ke MIG.

Properti yang dapat diperbarui

Anda hanya dapat mengubah kumpulan properti instance tertentu melalui metode pembaruan. Pembaruan pada beberapa properti mengharuskan instance dimulai ulang. Untuk mencegah mulai ulang yang tidak disengaja pada instance, permintaan Anda harus menentukan tindakan yang dapat diambil pada instance Anda. Permintaan Anda dapat menentukan salah satu tindakan berikut:

  • NO_EFFECT: Permintaan pembaruan memeriksa apakah permintaan tersebut valid dan apakah resource tersedia, tetapi tidak menjalankan pembaruan. Gunakan metode ini untuk menguji perintah tanpa memulai pembaruan yang sebenarnya.
  • REFRESH: Permintaan pembaruan hanya berjalan jika properti instance yang diubah tidak mengharuskan instance untuk dimulai ulang. Permintaan akan menampilkan error INFEASIBLE jika permintaan tersebut valid, tetapi perlu dimulai ulang.
  • RESTART: Jika pembaruan mengharuskan instance dimulai ulang, sistem akan memulai ulang instance.

Properti yang memerlukan RESTART untuk pembaruan:

  • reservationAffinity
  • disks - Boot disk
    • disks.deviceName - Semua disk
  • displayDevice
  • enableNestedVirtualization
  • guestAccelerators
  • machineType
  • minCpuPlatform
  • networkPerformanceConfig
  • resourcePolicies
  • scheduling
  • serviceAccounts
  • shieldedInstanceConfig
  • threadsPerCore
  • visibleCoreCount

Properti yang hanya memerlukan REFRESH untuk pembaruan:

  • canIpForward
  • deletionProtection
  • description
  • disks - Properti non-boot disk, kecuali deviceName
  • labels
  • metadata
  • nodeAffinities
  • tags

Memperbarui properti instance

Perbarui instance Anda menggunakan langkah-langkah berikut:

  1. Ekspor properti konfigurasi instance yang ada.
  2. Ubah properti konfigurasi instance.
  3. Jalankan permintaan pengujian dengan menetapkan NO_EFFECT sebagai tindakan yang paling mengganggu. Responsnya menunjukkan kolom yang tidak valid dalam konfigurasi instance dan menunjukkan tindakan yang diperlukan untuk menerapkan perubahan.
  4. Jika konfigurasi dapat diterima, minta pembaruan instance dan tentukan tindakan paling mengganggu yang dapat diterima untuk pembaruan instance Anda.

Sistem akan memulai proses pembaruan hanya jika permintaan Anda memenuhi persyaratan berikut:

  • Properti fingerprint instance dalam permintaan Anda harus cocok dengan fingerprint instance yang sedang Anda perbarui. Hal ini mencegah permintaan pembaruan yang simultan pada instance yang sama agar tidak saling menimpa.
  • Properti dalam permintaan pembaruan Anda harus valid.
  • Resource yang Anda minta harus tersedia.
  • Jika properti dalam permintaan Anda mengharuskan instance dimulai ulang, permintaan Anda harus menentukan RESTART sebagai tindakan yang diizinkan.

Jika persyaratan terpenuhi, sistem akan memulai proses pembaruan instance. Jika tidak, sistem tidak akan membuat perubahan pada instance yang ada atau konfigurasinya.

Anda dapat memulai pembaruan menggunakan gcloud CLI atau Compute Engine API.

gcloud

  1. Gunakan perintah instances export untuk mengekspor properti instance yang ada:

    gcloud compute instances export INSTANCE_NAME \
    --project PROJECT_ID \
    --zone ZONE \
    --destination=FILE_PATH

    Ganti kode berikut:

    • INSTANCE_NAME: nama untuk instance yang ingin Anda ekspor.
    • PROJECT_ID: project ID untuk permintaan ini.
    • ZONE: zona untuk instance ini.
    • FILE_PATH: jalur output tempat Anda ingin menyimpan file konfigurasi instance di workstation lokal Anda.

  2. Gunakan editor teks untuk mengubah satu atau beberapa properti dalam file konfigurasi instance yang diekspor. Untuk mempelajari properti yang dapat Anda perbarui, lihat daftar properti yang dapat diperbarui. Misalnya, untuk mengubah jenis mesin instance, ubah properti machineType:

    ⋮
machineType: https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/MACHINE_TYPE
⋮

    Ganti kode berikut:

    • PROJECT_ID: project ID untuk permintaan ini.
    • ZONE: zona untuk instance ini.
    • MACHINE_TYPE: jenis mesin instance. Misalnya, n1-standard-2.

  3. Gunakan perintah instances update-from-file untuk menjalankan pembaruan pengujian instance target. Tentukan flag --most-disruptive-allowed-action=NO_EFFECT. Responsnya mengidentifikasi properti yang salah dikonfigurasi dan menunjukkan apakah tindakan RESTART atau REFRESH diperlukan untuk menerapkan pembaruan.

    gcloud compute instances update-from-file INSTANCE_NAME \
    --project PROJECT_ID \
    --zone ZONE \
    --source=FILE_PATH \
    --most-disruptive-allowed-action NO_EFFECT

    Ganti kode berikut:

    • INSTANCE_NAME: nama untuk instance yang ingin Anda ekspor.
    • PROJECT_ID: project ID untuk permintaan ini.
    • ZONE: zona untuk instance ini.
    • FILE_PATH: jalur ke file konfigurasi instance yang diubah di workstation lokal Anda.

  4. Gunakan perintah instances update-from-file untuk memperbarui instance target. Jika Anda memperbarui properti yang mengharuskan instance dimulai ulang, sertakan flag --most-disruptive-allowed-action=RESTART. Jika properti tidak memerlukan mulai ulang, tentukan flag --most-disruptive-allowed-action=REFRESH. Untuk mempelajari properti mana yang memerlukan mulai ulang, lihat daftar properti yang dapat diperbarui.

    gcloud compute instances update-from-file INSTANCE_NAME \
    --project PROJECT_ID \
    --zone ZONE \
    --source=FILE_PATH \
    --most-disruptive-allowed-action ALLOWED_ACTION

    Ganti kode berikut:

    • INSTANCE_NAME: nama untuk instance yang ingin Anda ekspor.
    • PROJECT_ID: project ID untuk permintaan ini.
    • ZONE: zona untuk instance ini.
    • FILE_PATH: jalur ke file konfigurasi instance yang diubah di workstation lokal Anda.
    • ALLOWED_ACTION: menentukan seberapa mengganggu pembaruan. Tentukan RESTART agar instance dapat dimulai ulang sepenuhnya. Tentukan REFRESH untuk memperbarui instance, hanya jika properti yang diubah tidak mengharuskan instance untuk dimulai ulang.

Jika permintaan pembaruan valid dan resource yang diperlukan tersedia, proses pembaruan instance akan dimulai. Anda dapat memantau status operasi ini dengan melihat log audit. Jika pembaruan perlu dimulai ulang dan perintah Anda mengizinkan RESTART, instance akan dimulai ulang untuk menerapkan perubahan.

REST

  1. Gunakan metode instances.get di Compute Engine API untuk mengekspor properti instance yang ada:

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

    Ganti kode berikut:

    • PROJECT_ID: project ID untuk permintaan ini.
    • ZONE: zona untuk instance ini.
    • INSTANCE_NAME: nama untuk instance yang ingin Anda ekspor.

    Permintaan ini menampilkan definisi resource instance.

  2. Dalam respons, ubah properti resource instance. Untuk mempelajari properti yang dapat diperbarui, lihat daftar properti yang dapat diperbarui. Misalnya, untuk mengubah jenis mesin instance, ubah properti machineType. Anda dapat mengubah beberapa properti.

    {
  ⋮
  "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/MACHINE_TYPE",
  ⋮
}

    Ganti kode berikut:

    • PROJECT_ID: project ID untuk permintaan ini.
    • ZONE: zona untuk instance ini.
    • MACHINE_TYPE: jenis mesin instance. Misalnya, n1-standard-2.

  3. Gunakan metode instances.update di Compute Engine API dan tentukan most_disruptive_allowed_action=NO_EFFECT untuk menjalankan pembaruan pengujian instance target. Responsnya mengidentifikasi properti yang salah dikonfigurasi dan menunjukkan apakah tindakan RESTART atau REFRESH diperlukan untuk menerapkan update.

    PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME?most_disruptive_allowed_action=NO_EFFECT

{
  ⋮
  "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/n1-standard-2",
  ⋮
}

    Ganti kode berikut:

    • PROJECT_ID: project ID untuk permintaan ini.
    • ZONE: zona untuk instance ini.
    • INSTANCE_NAME: nama untuk instance yang ingin Anda ekspor.

  4. Gunakan metode instances.update di Compute Engine API untuk memperbarui instance target. Jika Anda memperbarui properti yang mengharuskan instance dimulai ulang, sertakan parameter kueri ?most_disruptive_allowed_action=RESTART untuk menunjukkan bahwa instance dapat dimulai ulang selama pembaruan. Jika properti tidak memerlukan mulai ulang, tentukan parameter kueri ?most_disruptive_allowed_action=REFRESH. Untuk mempelajari properti mana yang memerlukan mulai ulang, lihat daftar properti yang dapat diperbarui. Sertakan isi lengkap untuk resource instance yang Anda ubah. Pada contoh berikut, isi mengubah jenis mesin menjadi n1-standard-2:

    PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME?most_disruptive_allowed_action=ALLOWED_ACTION

{
  ⋮
  "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/n1-standard-2",
  ⋮
}

    Ganti kode berikut:

    • PROJECT_ID: project ID untuk permintaan ini.
    • ZONE: zona untuk instance ini.
    • INSTANCE_NAME: nama untuk instance yang ingin Anda ekspor.
    • ALLOWED_ACTION: menentukan seberapa mengganggu pembaruan. Tentukan RESTART agar instance dapat dimulai ulang sepenuhnya. Tentukan REFRESH untuk memperbarui instance, hanya jika properti yang diubah tidak mengharuskan instance dimulai ulang.

Jika permintaan pembaruan valid dan resource yang diperlukan tersedia, proses pembaruan instance akan dimulai. Anda dapat memantau status operasi ini dengan melihat log audit. Jika pembaruan perlu dimulai ulang dan perintah Anda mengizinkan RESTART, instance akan dimulai ulang untuk menerapkan perubahan.

Langkah selanjutnya