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 yang dapat ditetapkan atau diperlukan untuk template masing-masing.

Misalnya, Anda dapat membuat skema dengan template yang sesuai harus selalu menentukan kumpulan properti yang diperlukan, 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 konfigurasinya, pengguna akan meninjau skema dan menetapkan properti yang benar dalam konfigurasinya.

Sebelum memulai

Contoh skema

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

Ini adalah file skema sederhana 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 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 ingin menggunakan template ini dalam konfigurasinya, pengguna dapat meninjau skema untuk mengetahui bahwa ada satu properti wajib yang harus ditentukan (IPv4Range) dan satu properti opsional (description) yang dapat dihilangkan atau disertakan. Kemudian, pengguna dapat membuat file konfigurasi seperti ini, dengan memastikan untuk menyediakan 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

Berikut 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 dari 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 tentang setiap kolom dan kontennya yang valid.

info

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

Minimal, berikan judul dan deskripsi di properti ini.

imports

Kolom imports berisi daftar file yang sesuai 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 di properti imports telah diupload bersama dengan template.

Saat menentukan file di kolom impor ini, Anda dapat menghapusnya dari kolom imports dalam konfigurasi. Pada 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. Setiap elemen 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, bilangan bulat, angka, ...)
  • default
  • minimum / exclusiveMinimum / maximum / exclusiveMaximum
  • minLength / maxLength
  • pattern
  • not X / allOf X, Y / anyOf X, Y / oneOf X, Y

Setidaknya, sebaiknya sertakan type dan description kolom agar pengguna tahu nilai yang dapat diterima untuk properti. Untuk properti opsional, sebaiknya sertakan juga nilai default.

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

Menetapkan metadata arbitrer

Secara default, Deployment Manager mengabaikan kolom yang bukan skema JSON yang valid. Jika perlu memperluas skema untuk memiliki kolom atau properti khusus, Anda dapat membuat properti apa pun yang diinginkan secara sewenang-wenang dan menambahkannya ke skema selama kolom atau properti 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 dapat 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 dengan nama yang sama dengan template yang sesuai, dengan .schema ditambahkan di bagian 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 bagi Anda. Demikian pula, jika ada file skema, yang diidentifikasi oleh format .schema yang ditambahkan, Deployment Manager akan mengupload skema dan memvalidasi deployment terhadap skema, sebelum mencoba membuat resource apa pun.

Untuk menggunakan skema, cukup sertakan dalam direktori lokal yang sama dengan template dan konfigurasi Anda, lalu buat deployment seperti biasa. gcloud CLI 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 seperti jika Anda menyertakan template.

Langkah selanjutnya