Mengelola setelan resource

Panduan ini menjelaskan cara mengelola setelan resource. Anda dapat menggunakan Setelan Resource guna mengonfigurasi setelan secara terpusat untuk project, folder, dan organisasi Google Cloud Anda. Setiap setelan resource memungkinkan Anda mengontrol aspek layanan yang didukung.

Sebelum memulai

Untuk mengetahui informasi selengkapnya tentang setelan resource dan cara kerjanya, lihat ringkasan Setelan Resource.

Mengaktifkan API

Resource Settings API dapat diaktifkan untuk masing-masing project.

Konsol Google Cloud

Untuk mengaktifkan Resource Settings API, lakukan hal berikut:

Buka APIs & services

  1. Pilih project yang akan Anda gunakan untuk mengakses API.
  2. Klik tombol Enable APIs and Service.
  3. Telusuri "Resource Settings".
  4. Di hasil penelusuran, klik "Resource Settings API".
  5. Jika "API diaktifkan" ditampilkan, berarti API sudah diaktifkan. Jika belum, klik tombol Enable.

gcloud

Untuk mengaktifkan Resource Settings API, gunakan perintah gcloud services enable:

gcloud services enable resourcesettings.googleapis.com

Izin yang diperlukan

Izin yang Anda perlukan bergantung pada tindakan yang harus dilakukan.

Untuk mendapatkan izin ini, minta administrator untuk memberikan peran yang disarankan pada level hierarki resource yang sesuai.

Lihat setelan resource

Untuk melihat setelan resource yang tersedia untuk digunakan pada resource, serta nilai setelan lokal yang efektif pada resource, Anda memerlukan peran Resource Settings Viewer (roles/resourcesettings.viewer), atau peran lain yang mencakup izin berikut:

  • resourcesettings.settings.get
  • resourcesettings.settings.list

Mengelola setelan resource

Untuk membuat, memperbarui, dan menghapus nilai setelan resource pada resource, Anda memerlukan peran Resource Settings Administrator (roles/resourcesettings.admin), atau peran lain yang mencakup izin berikut:

  • resourcesettings.settings.get
  • resourcesettings.settings.list
  • resourcesettings.settings.update

Mencantumkan setelan yang tersedia

Anda bisa mendapatkan daftar semua setelan fasilitas yang tersedia untuk fasilitas tertentu. Daftar ini menampilkan semua setelan resource yang dapat diterapkan ke resource tersebut. Setelan resource dalam status pratinjau hanya tersedia bagi setelan yang telah diberi izin eksplisit untuk menggunakannya.

gcloud

Untuk mendapatkan daftar semua setelan yang tersedia untuk digunakan pada resource, gunakan perintah gcloud resource-settings list berikut:

gcloud resource-settings list --RESOURCE_ID

Dengan RESOURCE_ID adalah ID folder, project, atau organisasi yang setelan resource-nya ingin Anda temukan. Contoh: --project=7890123456

API

Untuk mendapatkan daftar semua setelan yang tersedia untuk digunakan pada resource, gunakan salah satu metode settings.list berikut. Gunakan metode yang sesuai dengan jenis resource yang setelannya ingin Anda cantumkan:

curl -X GET -H "Content-Type: application/json" -H \
  "Authorization: Bearer $ACCESS_TOKEN" \
  https://resourcesettings.googleapis.com/v1/RESOURCE_ID/settings

Ganti kode berikut:

  • ACCESS_TOKEN: token akses OAuth 2.0.

  • RESOURCE_ID: ID folder, project, atau organisasi yang setelan resource-nya ingin Anda temukan. Contoh: projects/7890123456

Contoh respons

Respons terhadap permintaan daftar di folders/4567890123 terlihat mirip dengan berikut:

{
  "settings" : [
    {
      "name": "folders/4567890123/settings/net-preferredDnsServers",
      "metadata":  {
        "displayName": "Preferred DNS Servers",
        "description": "The DNS servers to be used by VMs associated with this resource.",
        "read_only": false,
        "data_type" : "STRING_SET",
        "default_value" : {
          "string_set_value" : {
            "values" : [ "8.8.8.8" ],
          }
        }
      }
    },
    {
      "name": "folders/4567890123/settings/text-defaultTextColor",
      "metadata":  {
        "displayName": "Default Text Color",
        "description": "The default text color for this resource.",
        "read_only": false,
        "data_type" : "STRING",
        "default_value" : {
          "string_value" : "black"
        }
      }
    },
    ...
  ]
}

Kolom name adalah nama pendek setelan resource, yang harus digunakan di permintaan API dan gcloud CLI yang terkait dengan setelan tersebut.

Mengubah nilai setelan lokal

Anda dapat mengubah nilai setelan lokal untuk setelan resource yang diberikan. Jika Anda menetapkan nilai setelan lokal, nilai ini akan menggantikan setelan nilai efektif yang diwariskan. Jika Anda membatalkan penetapan nilai setelan lokal, nilai setelan lokal apa pun yang diterapkan ke resource ancestry akan diwariskan, sehingga menjadi nilai yang efektif.

gcloud

Guna mengubah nilai setelan lokal untuk setelan resource di resource, gunakan perintah gcloud resource-settings set-value berikut:

gcloud resource-settings set-value --value-file=FILE_PATH

Ganti FILE_PATH dengan jalur ke file YAML atau JSON yang berisi setelan resource.

Contoh file JSON:

{
  "localValue" : {
    "stringSetValue": {
      "values": [
        "8.8.8.8",
        "8.8.4.4",
      ]
    }
  },
  "name": "RESOURCE_ID/settings/SETTING_NAME"
}

Ganti kode berikut:

  • RESOURCE_ID: ID folder, project, atau organisasi yang setelan resource lokalnya ingin Anda perbarui. Contoh: projects/7890123456

  • SETTING_NAME: nama pendek setelan resource yang ingin Anda update.

Untuk membatalkan penetapan nilai setelan lokal pada resource, gunakan perintah gcloud resource-settings unset-value:

gcloud resource-settings unset-value SETTING_NAME \
  --RESOURCE_ID

Ganti kode berikut:

  • SETTING_NAME: nama pendek setelan resource yang nilai lokalnya ingin Anda batalkan penetapannya.

  • RESOURCE_ID: ID folder, project, atau organisasi yang setelan resource-nya ingin Anda temukan. Contoh: projects/7890123456

API

Guna mengubah nilai setelan lokal untuk setelan resource di resource, gunakan metode settings.patch. Gunakan metode yang sesuai dengan jenis resource yang setelannya ingin Anda perbarui:

curl -X PATCH -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" -d \
  '{
    "localValue": {
      "stringSetValue": {
        "values": [ "8.8.8.8", "8.8.4.4" ]
      }
    }
  }
  ' https://resourcesettings.googleapis.com/v1/RESOURCE_ID/settings/net-preferredDnsServers

Ganti kode berikut:

  • ACCESS_TOKEN: token akses OAuth 2.0.

  • RESOURCE_ID: ID folder, project, atau organisasi yang setelan resource-nya ingin Anda temukan. Contoh: projects/7890123456

Jika Anda membuat permintaan ini tanpa nilai lokal yang disertakan dalam file JSON, Anda akan membatalkan penetapan nilai setelan lokal, dan resource akan mewarisi setelan nilai induk, atau menggunakan setelan default yang dikelola Google.

Setelah membuat permintaan yang berhasil, Anda akan mendapatkan respons yang menyertakan nilai lokal yang dibuat untuk setelan ini dan kolom etag yang harus Anda sertakan pada permintaan update berikutnya.

{
  "name": "folders/4567890123/settings/net-preferredDnsServers",
  "localValue": {
    "stringSetValue": {
      "values": [ "8.8.8.8", "8.8.4.4" ]
    }
  }
  "etag": "O2VWGxZU01VnAfRU4Mu97w==",
}

Melihat setelan nilai lokal atau efektif

Anda dapat melihat nilai lokal atau nilai efektif setelan resource pada resource tertentu.

gcloud

Untuk melihat nilai lokal setelan resource pada resource tertentu, gunakan perintah gcloud resource-settings describe, seperti berikut:

gcloud resource-settings describe SETTING_NAME \
  --RESOURCE_ID

Ganti kode berikut:

  • SETTING_NAME: nama pendek setelan resource tempat Anda ingin menemukan nilai lokal atau efektifnya.

  • RESOURCE_ID: ID folder, project, atau organisasi tempat Anda ingin menemukan setelan resource yang tersedia. Contoh: --project=7890123456

Jika menambahkan flag --effective, Anda akan mendapatkan nilai yang efektif karena dievaluasi untuk resource ini.

API

Untuk melihat nilai lokal atau nilai efektif setelan resource pada resource tertentu, gunakan metode settings.get. Gunakan metode yang sesuai dengan jenis resource yang setelannya ingin Anda cantumkan:

curl -X GET -H "Content-Type: application/json" -H \
  "Authorization: Bearer $ACCESS_TOKEN" \
  https://resourcesettings.googleapis.com/v1/RESOURCE_ID \
  /settings/SETTING_NAME?view=VIEW_PARAMETER

Ganti kode berikut:

  • ACCESS_TOKEN: token akses OAuth 2.0.

  • RESOURCE_ID: ID folder, project, atau organisasi yang setelan resource-nya ingin Anda temukan. Contoh: projects/7890123456

  • SETTING_NAME: nama pendek setelan resource yang nilainya ingin Anda tampilkan.

  • VIEW_PARAMETER: SETTING_VIEW_LOCAL_VALUE untuk menampilkan nilai setelan lokal, atau SETTING_VIEW_EFFECTIVE_VALUE untuk menampilkan nilai efektif di resource ini.

Contoh respons

Respons terhadap permintaan get di folders/4567890123 terlihat mirip dengan berikut:

{
  "name": "folders/4567890123/settings/net-preferredDnsServers",
  "value": {
    "stringSetValue": {
      "values": [ "8.8.8.8", "8.8.4.4" ]
    }
  }
  "etag": "O2VWGxZU01VnAfRU4Mu97w=="
}

Pewarisan

Setelan resource yang berlaku pada resource tertentu dievaluasi berdasarkan pewarisan. Anda dapat mengganti nilai yang diwarisi pada resource dengan menetapkan nilai lokal, yang juga memengaruhi nilai setelan yang diwarisi oleh turunan resource tersebut. Untuk mengetahui informasi selengkapnya tentang pewarisan setelan resource, lihat Nilai setelan yang efektif.

Mengambil nilai yang efektif

Anda dapat mengambil nilai setelan yang efektif pada resource tertentu menggunakan API atau gcloud CLI. Untuk petunjuk mendetail, lihat Melihat setelan nilai lokal atau efektif. Pertimbangkan contoh berikut, dengan nilai yang ditetapkan untuk setelan resource Preferred DNS Servers di organisasi, folder dalam organisasi itu, dan subfolder dalam folder tersebut:

Nilai efektif pada setiap sumber daya ini dievaluasi sebagai berikut:

  • organizations/111 tidak memiliki nilai lokal, dan tidak memiliki resource induk untuk diwarisi, sehingga akan menggunakan default 8.8.8.8 yang dikelola Google.

    • Jika Anda menggunakan metode describe untuk mendapatkan nilai yang efektif pada resource, dan metode tersebut menggunakan default yang dikelola Google, informasi tersebut akan disertakan dalam respons. Contoh:
    {
  "name": "organizations/111/settings/net-preferredDnsServers",
  "effectiveValue": {
    "stringSetValue": {
      "values": [ "8.8.8.8" ] # Google-managed default
    }
  }
}

  • folders/222 memiliki setelan nilai lokal 8.8.4.4, sehingga tidak mewarisi dari resource induknya.

    • Jika Anda menggunakan metode describe untuk mendapatkan nilai yang efektif pada resource, dan merupakan nilai yang ditetapkan secara lokal, informasi tersebut akan disertakan dalam respons. Contoh:
    {
  "name": "folders/222/settings/net-preferredDnsServers",
  "effectiveValue": {
    "stringSetValue": {
      "values": [ "8.8.4.4" ] # set on folders/222
    }
  }
}

  • folders/333 tidak memiliki nilai lokal, tetapi resource induknya memilikinya. Class ini mewarisi nilai setelan lokal dari folders/222, sehingga bernilai 8.8.4.4.

    • Jika Anda menggunakan metode describe untuk mendapatkan nilai yang efektif pada resource, dan metode tersebut mewarisi nilai tersebut dari resource induk, informasi tersebut akan disertakan dalam respons. Contoh:
    {
  "name": "folders/333/settings/net-preferredDnsServers",
  "effectiveValue": {
    "stringSetValue": {
      "values": [ "8.8.4.4" ] # inherited from folders/222
    }
  }
}

Ganti nilai yang diwarisi

Jika Anda mengubah nilai setelan lokal folders/333 untuk setelan Server DNS Pilihan, nilai yang efektif akan berubah. Misalnya, Anda menggunakan metode patch untuk memperbarui nilai setelan lokal folders/333 menjadi 192.168.1.1. Untuk petunjuk mendetail, lihat Mengubah nilai setelan lokal.

Jika menggunakan metode describe pada resource folders/333 yang telah diperbarui, Anda akan melihat bahwa nilai yang efektif sekarang adalah 192.168.1.1:

{
  "name": "folders/333/settings/net-preferredDnsServers",
  "effectiveValue": {
    "stringSetValue": {
      "values": [ "192.168.1.1" ] # set on folders/333
    }
  }
}

Kembalikan ke nilai pewaris

Untuk mengembalikan perilaku ini sehingga resource mewarisi nilai lokal dari induk, gunakan metode patch API tanpa nilai lokal yang ditetapkan dalam kueri, atau dengan menggunakan perintah unset-value gcloud CLI. Untuk petunjuk mendetail, lihat Mengubah nilai setelan lokal.

Misalnya, jika Anda membatalkan penetapan nilai lokal di folders/333, nilai tersebut akan mewarisi nilai efektif dari resource induk terdekatnya, folders/222 sekali lagi. Jika Anda menggunakan metode describe pada resource folders/333 yang telah diperbarui, Anda akan melihat bahwa nilai yang efektif sekarang adalah 8.8.4.4:

{
  "name": "folders/333/settings/net-preferredDnsServers",
  "effectiveValue": {
    "stringSetValue": {
      "values": [ "8.8.4.4" ] # inherited from folders/222
    }
  }
}