Menggunakan Skema

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

Selain menentukan aturan template, skema juga memungkinkan pengguna untuk 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 disetel atau diperlukan untuk template masing-masing.

Misalnya, Anda dapat membuat skema di mana template terkait harus selalu menentukan serangkaian properti tertentu yang diperlukan, dan masing-masing properti ini memiliki spesifikasinya sendiri. Satu properti harus berupa string, properti lainnya harus berupa bilangan bulat yang kurang dari 100, dan seterusnya. Jika ingin menerapkan template Anda dalam konfigurasi, ia akan meninjau skema dan menetapkan properti yang benar dalam konfigurasinya.

Sebelum memulai

Contoh skema

Skema contoh ditulis untuk mesin template Jinja. Jika Anda menggunakan mesin template yang berbeda, ekstensi file Anda akan berbeda dan sintaksis template dapat berbeda pula.

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 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 ingin menggunakan template ini dalam konfigurasi, 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. Selanjutnya, pengguna dapat membuat file konfigurasi seperti itu, dan pastikan 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

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 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 konten yang valid.

info

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

Minimal, berikan judul dan deskripsi di properti ini.

impor

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 diupload bersama dengan template tersebut.

Saat menentukan file dalam kolom impor ini, Anda dapat menghilangkannya 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 terkait, pengguna dapat menghilangkan proses impor file vm-instance.jinja, karena file tersebut akan diimpor secara otomatis saat Deployment Manager memeriksa skema untuk template tersebut.

Jalur impor harus relatif terhadap lokasi file skema. Hal ini memungkinkan Anda menyimpan template, skema, dan konfigurasi di direktori yang sama, dan memastikan bahwa file akan memiliki impor yang valid jika direktori tersebut 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, integer, number, ...)
  • 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 berapa 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.

Menyetel 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 bebas membuat properti apa pun yang diinginkan dan menambahkannya ke skema Anda selama kolom atau properti tersebut tidak tumpang-tindih dengan kata kunci validasi skema JSON mana pun.

Misalnya, Anda dapat menambahkan kolom metadata yang memberi anotasi pada salah satu properti:

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 berdasarkan template yang dideskripsikan. Skema harus diberi nama dengan nama yang sama seperti template yang sesuai, dengan .schema yang ditambahkan ke bagian akhir:

TEMPLATE_NAME.EXTENSION.schema

Misalnya, untuk template bernama vm-instance.py, file skema yang terkait harus bernama vm-instance.py.schema. Hanya boleh ada satu skema untuk setiap template.

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

Gunakan skema

gcloud


Saat Anda membuat deployment menggunakan Google Cloud CLI, Deployment Manager otomatis mengupload semua template yang relevan untuk konfigurasi untuk 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 sebuah skema, cukup sertakan skema tersebut 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 dalam API dan sertakan file skema yang sesuai dengan isi permintaan seolah-olah Anda menyertakan template.

Langkah selanjutnya