Menggunakan Skema

Skema menjelaskan spesifikasi template Deployment Manager. Jika skema ada untuk template, Deployment Manager akan menggunakan skema tersebut untuk menerapkan cara pengguna dapat berinteraksi dengan template yang sesuai. Skema menentukan serangkaian aturan yang harus dipenuhi file konfigurasi jika ingin menggunakan template tertentu.

Selain menentukan aturan template, skema juga memungkinkan pengguna berinteraksi dengan template yang Anda tulis, tanpa perlu meninjau dan mempelajari setiap lapisan template. Pengguna cukup meninjau persyaratan yang ditentukan dalam skema Anda untuk mempelajari properti apa yang dapat ditetapkan atau diperlukan untuk template masing-masing.

Misalnya, Anda dapat membuat skema yang template terkaitnya harus selalu menentukan kumpulan properti wajib tertentu, dan setiap properti ini memiliki spesifikasinya sendiri. Satu properti harus berupa string, properti lainnya harus berupa bilangan bulat yang kurang dari 100, dan seterusnya. Jika pengguna ingin menerapkan template Anda dalam konfigurasi mereka, pengguna akan meninjau skema dan menetapkan properti yang benar dalam konfigurasi mereka.

Sebelum memulai

Contoh skema

Contoh skema ditulis untuk mesin templating Jinja. Jika Anda menggunakan mesin templating yang berbeda, ekstensi file Anda akan berbeda dan sintaksis template dapat berbeda.

Berikut adalah contoh file skema bernama vm-instance-with-network.jinja.schema:

info:
  title: VM Template
  author: Jane
  description: Creates a new network and instance
  version: 1.0

imports:
- path: vm-instance.jinja # Must be a relative path

required:
- IPv4Range

properties:
  IPv4Range:
    type: string
    description: Range of the network

  description:
    type: string
    default: "My super great network"
    description: Description of network

Skema ini berlaku untuk template ini, vm-instance-with-network.jinja:

resources:
- name: vm-1
  type: vm-instance.jinja

- name: a-new-network
  type: compute.v1.network
  properties:
    IPv4Range: {{ properties['IPv4Range'] }}
    description: {{ properties['description'] }}

Jika pengguna ingin menggunakan template ini dalam konfigurasi mereka, mereka dapat meninjau skema untuk mempelajari bahwa ada satu properti wajib yang harus mereka tentukan (IPv4Range) dan satu properti opsional (description) yang dapat mereka hapus atau sertakan. Pengguna kemudian dapat membuat file konfigurasi seperti ini, dengan memastikan untuk memberikan properti bernama IPv4Range:

imports:
- path: vm-instance-with-network.jinja

resources:
- name: vm-1
  type: vm-instance-with-network.jinja
  properties:
    IPv4Range: 10.0.0.1/16

Struktur skema

Di bawah ini adalah contoh dokumen skema. Deployment Manager merekomendasikan agar skema ditulis dalam format YAML, tetapi Anda juga dapat menulis skema dalam JSON dan skema tersebut akan diterima oleh Deployment Manager.

Deployment Manager menerima skema yang ditulis sesuai dengan draf 4 spesifikasi skema JSON.

<mongodb.py.schema>
info:
  title: MongoDB Template
  author: Jane
  description: Creates a MongoDB cluster
  version: 1.0

imports:
  - path: helper.py
    name: mongodb_helper.py

required:
  - name

properties:
  name:
    type: string
    description: Name of your Mongo Cluster

  size:
    type: integer
    default: 2
    description: Number of Mongo Slaves

  zone:
    type: string
    default: us-central1-a
    description: Zone to run
    metadata: gce-zone

File skema yang valid adalah file skema JSON dengan penambahan dua kolom tingkat atas, info dan imports. Berikut adalah deskripsi singkat setiap kolom dan kontennya yang valid.

info

Properti info berisi informasi meta tentang skema. Informasi ini mencakup informasi seperti judul, nomor versi, deskripsi, dan sebagainya.

Minimal, berikan judul dan deskripsi dalam properti ini.

imports

Kolom imports berisi daftar file terkait yang diperlukan untuk template yang menggunakan skema ini. Saat Anda mengupload template dengan skema yang memiliki daftar impor, Deployment Manager akan memeriksa apakah semua file dalam properti imports diupload bersama dengan template.

Saat menentukan file di kolom impor ini, Anda dapat menghapusnya dari kolom imports di konfigurasi. Dalam contoh di atas, kolom imports mengimpor nama file vm-instance.jinja:

imports:
- path: vm-instance.jinja

Dalam file konfigurasi yang sesuai, pengguna dapat menghapus impor file vm-instance.jinja, karena file tersebut akan diimpor secara otomatis saat Deployment Manager memeriksa skema untuk template.

Jalur impor harus relatif terhadap lokasi file skema. Hal ini memungkinkan Anda menyimpan template, skema, dan konfigurasi di direktori yang sama, serta memastikan bahwa file akan memiliki impor yang valid jika direktori dibagikan atau dipindahkan.

wajib

Kolom required berisi daftar elemen dari kolom properti yang diperlukan dalam template yang menggunakan skema. Elemen apa pun yang tidak ditentukan dalam kolom required ini dianggap opsional.

properties

Kolom properties berisi aturan skema JSON untuk dokumen ini. Elemen yang dijelaskan di kolom properties dapat ditetapkan oleh pengguna template. Anda dapat menggunakan semua validasi skema JSON yang didukung untuk properti ini, seperti:

  • type (string, boolean, integer, number, ...)
  • default
  • minimum / exclusiveMinimum / maximum / exclusiveMaximum
  • minLength / maxLength
  • pattern
  • not X / allOf X, Y / anyOf X, Y / oneOf X, Y

Minimal, sebaiknya sertakan type dan description kolom agar pengguna mengetahui nilai yang dapat diterima untuk properti tersebut. Untuk properti opsional, sebaiknya sertakan nilai default.

Baca dokumentasi Validasi Skema JSON untuk mengetahui daftar kata kunci validasi.

Menetapkan metadata arbitrer

Secara default, Deployment Manager mengabaikan kolom apa pun yang bukan skema JSON yang valid. Jika perlu memperluas skema agar memiliki kolom atau properti khusus, Anda dapat membuat properti apa pun yang diinginkan secara arbitrer dan menambahkannya ke skema selama kolom atau properti tersebut tidak tumpang-tindih dengan kata kunci validasi skema JSON.

Misalnya, Anda dapat menambahkan kolom metadata yang menganotasi salah satu properti Anda:

properties:
  zone:
    type: string
    default: us-central1-a
    description: Zone to run
    metadata: a-special-property

Atau, Anda membuat variabel khusus yang mungkin digunakan di aplikasi lain di luar Deployment Manager:

properties:
  size:
    type: integer
    default: 2
    description: Number of Mongo Slaves
    variable-x: ultra-secret-sauce

Membuat skema

Skema adalah dokumen terpisah yang diberi nama sesuai dengan template yang dijelaskannya. Skema harus diberi nama yang sama dengan template yang sesuai, dengan .schema ditambahkan di akhir:

TEMPLATE_NAME.EXTENSION.schema

Misalnya, untuk template bernama vm-instance.py, file skema yang sesuai harus diberi nama vm-instance.py.schema. Hanya satu skema yang dapat ada untuk setiap template.

Skema dapat berisi satu atau beberapa kolom yang dijelaskan di bagian Struktur skema. Atau, Anda juga dapat menulis skema dalam JSON. Untuk contoh skema JSON, lihat dokumentasi skema JSON.

Menggunakan skema

gcloud


Saat Anda membuat deployment menggunakan Google Cloud CLI, Deployment Manager akan otomatis mengupload semua template yang relevan untuk konfigurasi tersebut. Demikian pula, jika ada file skema, yang diidentifikasi dengan format .schema yang ditambahkan, Deployment Manager akan mengupload skema dan memvalidasi deployment terhadap skema tersebut, sebelum mencoba membuat resource apa pun.

Untuk menggunakan skema, cukup sertakan skema tersebut di direktori lokal yang sama dengan template dan konfigurasi Anda, lalu buat deployment seperti biasa. gcloud CLI akan mendeteksi dan meneruskan file skema ke Deployment Manager.

API


Ikuti petunjuk untuk membuat deployment di API dan sertakan file skema secara inline dengan isi permintaan Anda seolah-olah Anda menyertakan template.

Langkah berikutnya