Label instance

Halaman ini menjelaskan terkait label. Panduan ini menjelaskan cara membuat instance dengan label; cara menambahkan, mengupdate, dan menghapus label; dan cara menggunakan label dalam penelusuran.

Label adalah cara mudah untuk mengelompokkan instance yang berhubungan atau berkaitan satu sama lain. Misalnya, Anda dapat memberi label pada instance berdasarkan apakah digunakan untuk pengujian atau produksi, atau Anda dapat menambahkan kode penagihan Anda sendiri ke instance. Anda dapat menggunakan label tersebut untuk mencari instance atau melacak biaya instance.

Anda selalu menambahkan label sebagai key-value pair:

{
 "userLabels": {
    "track": "production",
    "location": "western-division"
    "billing-code": "34802",...
 }

Mengubah label tidak akan memengaruhi performa instance Cloud SQL.

Untuk informasi selengkapnya, lihat Apa yang dimaksud dengan label? dan Persyaratan untuk label.

Pembatasan

  • Anda dapat menetapkan hingga 64 label untuk setiap instance.

  • Kunci dan nilai label harus sesuai dengan batasan berikut:

    • Panjang kunci dan nilai masing-masing tidak boleh lebih dari 63 karakter.
    • Kunci dan nilai hanya boleh berisi huruf kecil, karakter numerik, garis bawah, dan tanda pisah. Karakter internasional diperbolehkan.
    • Kunci label harus diawali dengan huruf kecil.
    • Kunci label tidak boleh kosong.

Membuat instance dengan label

Saat membuat instance baru menggunakan gcloud CLI atau API, Anda dapat menerapkan label ke instance.

gcloud

Saat membuat instance, sertakan flag `--labels`, diikuti dengan daftar key-value pair label yang dipisahkan koma. Anda harus menggunakan versi beta perintah pembuatan (create command) untuk menyertakan label.

Contoh:

gcloud beta sql instances create ... --labels track=production,billing-code=34802

Terraform

Gunakan resource Terraform saat membuat instance dengan label: 

resource "google_sql_database_instance" "postgres_instance_labels" {
  name             = "postgres-instance-labels"
  region           = "us-central1"
  database_version = "POSTGRES_14"
  settings {
    tier = "db-custom-2-7680"
    user_labels = {
      track        = "production"
      billing-code = 34802
    }
  }
  # set `deletion_protection` to true, will ensure that one cannot accidentally delete this instance by
  # use of Terraform whereas `deletion_protection_enabled` flag protects this instance at the GCP level.
  deletion_protection = false
}

Menerapkan perubahan

Untuk menerapkan konfigurasi Terraform di project Google Cloud, selesaikan langkah-langkah di bagian berikut.

Menyiapkan Cloud Shell

  1. Luncurkan Cloud Shell.

  2. Tetapkan project Google Cloud default tempat Anda ingin menerapkan konfigurasi Terraform.

    Anda hanya perlu menjalankan perintah ini sekali per project, dan dapat dijalankan di direktori mana pun.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Variabel lingkungan akan diganti jika Anda menetapkan nilai eksplisit dalam file konfigurasi Terraform.

Menyiapkan direktori

Setiap file konfigurasi Terraform harus memiliki direktorinya sendiri (juga disebut modul root).

  1. Di Cloud Shell, buat direktori dan file baru di dalam direktori tersebut. Nama file harus memiliki ekstensi .tf—misalnya main.tf. Dalam tutorial ini, file ini disebut sebagai main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Jika mengikuti tutorial, Anda dapat menyalin kode contoh di setiap bagian atau langkah.

    Salin kode contoh ke dalam main.tf yang baru dibuat.

    Atau, salin kode dari GitHub. Tindakan ini direkomendasikan jika cuplikan Terraform adalah bagian dari solusi menyeluruh.

  3. Tinjau dan ubah contoh parameter untuk diterapkan pada lingkungan Anda.
  4. Simpan perubahan Anda.
  5. Lakukan inisialisasi Terraform. Anda hanya perlu melakukan ini sekali per direktori. 
    terraform init

    Secara opsional, untuk menggunakan versi penyedia Google terbaru, sertakan opsi -upgrade: 

    terraform init -upgrade

Menerapkan perubahan

  1. Tinjau konfigurasi dan pastikan resource yang akan dibuat atau diupdate oleh Terraform sesuai yang Anda inginkan: 
    terraform plan

    Koreksi konfigurasi jika diperlukan.

  2. Terapkan konfigurasi Terraform dengan menjalankan perintah berikut dan memasukkan yes pada prompt: 
    terraform apply

    Tunggu hingga Terraform menampilkan pesan "Apply complete!".

  3. Buka project Google Cloud Anda untuk melihat hasilnya. Di Konsol Google Cloud, buka resource Anda di UI untuk memastikan bahwa Terraform telah membuat atau mengupdatenya.

Menghapus perubahan

Untuk menghapus perubahan Anda, lakukan langkah-langkah berikut:

  1. Untuk menonaktifkan perlindungan penghapusan, di file konfigurasi Terraform Anda, tetapkan argumen deletion_protection ke false. 
    deletion_protection =  "false"
  2. Terapkan konfigurasi Terraform terbaru dengan menjalankan perintah berikut dan memasukkan yes pada perintah: 
    terraform apply

  1. Hapus resource yang sebelumnya diterapkan dengan konfigurasi Terraform Anda dengan menjalankan perintah berikut dan memasukkan yes pada prompt:

    terraform destroy

curl

Di API, selama permintaan `POST` untuk menambahkan instance baru, tambahkan properti `userLabels` dalam isi permintaan untuk menerapkan label ke instance baru. Misalnya, isi permintaan Anda untuk membuat instance memiliki label berikut:

          "settings": {"tier":"db-custom-2-7680",
                       "userLabels": {"track": "production",
                                      "location": "western-division",
                                      "billing-code": "34802"},

Menambahkan atau mengupdate label pada instance yang ada

konsol

  1. Buka halaman Instance Cloud SQL di konsol Google Cloud.

    Buka halaman Instance Cloud SQL

  2. Pilih kotak centang di samping resource yang ingin diberi label.

  3. Klik Tampilkan Panel Info di sudut kanan atas untuk meluaskan kolom label.

  4. Update atau tambahkan label baru sesuai keinginan.

  5. Simpan perubahan Anda.

gcloud

Gunakan subperintah patch (versi beta) untuk mengupdate atau menambahkan label pada instance yang ada:

gcloud beta sql instances patch [INSTANCE_NAME] --update-labels [KEY1]=[VALUE1]...

Contoh:

gcloud beta sql instances patch my-instance --update-labels track=production,billing-code=34802

Jika Anda memberikan kunci label yang sudah ada, alat ini akan mengupdate kunci yang ada dengan nilai label baru. Jika Anda memberikan kunci baru, alat tersebut akan menambahkan kunci baru ke daftar label. Hanya label yang Anda tentukan yang akan terpengaruh; label yang sudah ada yang tidak disertakan dalam perintah tetap tidak berubah.

istirahat v1

Untuk menambahkan atau mengupdate label, gunakan metode PATCH:

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • project-id: ID project
  • instance-id: ID instance
  • label-name-1: Nama label
  • value-1: Nilai label-name-1
  • label-name-2: Nama label
  • value-2: Nilai label-name-2

Metode HTTP dan URL: 

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

Meminta isi JSON: 

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name-1" : "value-1",
            "label-name-2" : "value-2"
         }
    }
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan menerima respons JSON yang mirip seperti berikut:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Jika Anda memberikan kunci label yang sudah ada, alat ini akan mengupdate kunci yang ada dengan nilai label baru. Jika Anda memberikan kunci baru, alat tersebut akan menambahkan kunci baru ke daftar label. Hanya label yang Anda tentukan yang akan terpengaruh; label yang sudah ada yang tidak disertakan dalam permintaan tetap tidak berubah.

rest v1beta4

Untuk menambahkan atau mengupdate label, gunakan metode PATCH:

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • project-id: ID project
  • instance-id: ID instance
  • label-name-1: Nama label
  • value-1: Nilai label-name-1
  • label-name-2: Nama label
  • value-2: Nilai label-name-2

Metode HTTP dan URL: 

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

Meminta isi JSON: 

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name-1" : "value-1",
            "label-name-2" : "value-2"
         }
    }
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan menerima respons JSON yang mirip seperti berikut:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Jika Anda memberikan kunci label yang sudah ada, alat ini akan mengupdate kunci yang ada dengan nilai label baru. Jika Anda memberikan kunci baru, alat tersebut akan menambahkan kunci baru ke daftar label. Hanya label yang Anda tentukan yang akan terpengaruh; label yang sudah ada yang tidak disertakan dalam permintaan tetap tidak berubah.

Menghapus label

konsol

  1. Buka halaman Instance Cloud SQL di konsol Google Cloud.

    Buka halaman Instance Cloud SQL

  2. Pilih kotak centang di samping resource yang ingin Anda hapus labelnya.

  3. Klik Tampilkan panel info untuk meluaskan kolom label.

  4. Klik X di samping semua label yang ingin Anda hapus.

  5. Simpan perubahan Anda.

gcloud

Menggunakan gcloud CLI, jalankan subperintah patch (versi beta) dengan flag --remove-labels:

gcloud beta sql instances patch [INSTANCE_NAME] --remove-labels [LABEL1],[LABEL2]

Jika Anda memberikan nama label yang tidak ada, error tidak akan muncul.

istirahat v1

Hapus label menggunakan API dengan menyetel nilainya ke null:

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • project-id: ID project
  • instance-id: ID instance
  • label-name: Nama label

Metode HTTP dan URL: 

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

Meminta isi JSON: 

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name" : null,
         }
    }
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan menerima respons JSON yang mirip seperti berikut:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

rest v1beta4

Hapus label menggunakan API dengan menyetel nilainya ke null:

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • project-id: ID project
  • instance-id: ID instance
  • label-name: Nama label

Metode HTTP dan URL: 

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

Meminta isi JSON: 

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name" : null,
         }
    }
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Memfilter penelusuran instance menggunakan label

Anda dapat memfilter hasil daftar instance menurut label menggunakan gcloud CLI atau API.

gcloud

Di gcloud, buat permintaan list dan gunakan flag --filter. Untuk memfilter label, gunakan sintaksis labels.[KEY]:[VALUE] Misalnya, jika ingin memfilter label billing-code dengan nilai 34802, Anda dapat menjalankan perintah berikut:

gcloud beta sql instances list --filter='labels.billing-code:34802'

Jika Anda ingin memfilter keberadaan label tanpa memperhatikan nilainya, jalankan perintah berikut:

gcloud beta sql instances list --filter='labels:billing-code'

Untuk dokumentasi lengkap tentang sintaksis filter di gcloud CLI, lihat dokumentasi gcloud topic filters.

curl

Di API, buat permintaan daftar dengan parameter kueri filter yang dienkode ke URL:

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.[KEY1_NAME]:[KEY1_VALUE]%20userLabels.[KEY2_NAME]:[KEY2_VALUE]

Contoh:

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.track:production%20userLabels.billing-code:34802

Saat dua nilai label disertakan dengan spasi (dienkode) di antara keduanya, keduanya harus bernilai benar agar instance ditampilkan (operasi AND). Anda juga dapat menyediakan operator AND, OR, dan NOT secara eksplisit. Misalnya:

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.track:production%20OR%20userLabels.billing-code:34802

Langkah selanjutnya