שימוש בסכימות

סכימה מתארת את המפרטים של תבנית Deployment Manager. אם קיימת סכימה לתבנית, Deployment Manager משתמש בסכימה כדי להגדיר את אופן האינטראקציה של המשתמשים עם התבנית המתאימה. סכימות מגדירות קבוצה של כללים שקובץ הגדרות צריך לעמוד בהם כדי להשתמש בתבנית מסוימת.

בנוסף להגדרת הכללים של תבנית, סכימות מאפשרות למשתמשים ליצור אינטראקציה עם התבניות שאתם כותבים, בלי שהם צריכים לבדוק וללמוד על כל שכבה של תבניות. המשתמשים יכולים פשוט לעיין בדרישות שמוגדרות בסכימה שלכם כדי להבין אילו מאפיינים אפשר להגדיר או נדרשים עבור התבנית הרלוונטית.

לדוגמה, אפשר ליצור סכימה שבה התבנית המתאימה חייבת תמיד להגדיר קבוצה ספציפית של מאפייני חובה, ולכל אחד מהמאפיינים האלה יש מפרט משלו. מאפיין אחד צריך להיות מחרוזת, מאפיין אחר צריך להיות מספר שלם שקטן מ-100 וכן הלאה. אם משתמש רוצה להחיל את התבנית שלכם בהגדרה שלו, הוא בודק את הסכימה ומגדיר את המאפיינים הנכונים בהגדרה שלו.

לפני שמתחילים

סכימה לדוגמה

סכימת הדוגמה נכתבה עבור מנוע התבניות Jinja. אם אתם משתמשים במנוע תבניות אחר, סיומות הקבצים יהיו שונות ותחביר התבנית יכול להיות שונה.

זהו קובץ סכימה פשוט בשם 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

הסכימה חלה על התבנית הזו, 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'] }}

אם משתמש רוצה להשתמש בתבנית הזו בהגדרה שלו, הוא יכול לעיין בסכימה כדי לראות שיש מאפיין חובה אחד שהוא צריך להגדיר (IPv4Range) ומאפיין אופציונלי אחד (description) שהוא יכול להשמיט או לכלול. משתמש יכול ליצור קובץ תצורה כמו זה שבהמשך, ולוודא שהוא כולל מאפיין בשם 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

המבנה של סכימה

בהמשך מופיע מסמך סכימה לדוגמה. ‫Deployment Manager ממליץ לכתוב סכימות בפורמט YAML, אבל אפשר גם לכתוב סכימות בפורמט JSON, והן יתקבלו על ידי Deployment Manager.

‫Deployment Manager מקבל סכימות שנכתבו בהתאם לטיוטה 4 של מפרטי סכימת 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

קובץ סכימה תקין הוא קובץ סכימת JSON עם שני שדות נוספים ברמה העליונה: info ו-imports. בהמשך מופיע תיאור קצר של כל שדה והתוכן התקין שלו.

מידע

המאפיין info מכיל מטא-מידע על הסכימה. המידע הזה כולל פרטים כמו שם, מספר גרסה, תיאור וכו'.

צריך לציין לפחות שם ותיאור במאפיין הזה.

ייבוא

השדה imports מכיל רשימה של קבצים תואמים שנדרשים לתבניות שמשתמשות בסכימה הזו. כשמעלים תבנית עם סכימה שיש בה רשימה של ייבוא, Deployment Manager בודק שכל הקבצים במאפיין imports הועלו יחד עם התבנית.

אם מציינים קובץ בשדה הייבוא הזה, אפשר להשמיט אותו מהשדה imports בהגדרה. בדוגמה שלמעלה, השדה imports מייבא את שם הקובץ vm-instance.jinja:

imports:
- path: vm-instance.jinja

בקובץ ההגדרות התואם, המשתמש יכול להשמיט את הייבוא של הקובץ vm-instance.jinja, כי הוא ייובא אוטומטית כש-Deployment Manager יבדוק את הסכימה של התבנית.

נתיבי הייבוא צריכים להיות יחסיים למיקום של קובץ הסכימה. כך תוכלו לאחסן תבניות, סכימות והגדרות באותה ספרייה, ולוודא שהקבצים יכללו ייבוא תקין אם הספרייה תשותף או תועבר.

נדרש

השדה required מכיל רשימה של רכיבים מהשדה properties שנדרשים בתבנית שמשתמשת בסכימה. כל האלמנטים שלא מצוינים בשדה required הזה נחשבים אופציונליים.

נכסים

השדה properties מכיל את כללי סכימת ה-JSON של המסמך הזה. משתמשים בתבנית יכולים להגדיר את הרכיבים שמתוארים בשדה properties. אפשר להשתמש בכל האימותים של סכימת JSON שנתמכים במאפיינים האלה, כמו:

  • ‫type (מחרוזת, ערך בוליאני, מספר שלם, מספר וכו')
  • default
  • minimum / exclusiveMinimum / maximum / exclusiveMaximum
  • minLength / maxLength
  • pattern
  • not X / allOf X, Y / anyOf X, Y / oneOf X, Y

מומלץ לכלול לפחות type וdescription של השדה, כדי שהמשתמשים ידעו מהו ערך קביל למאפיין. במאפיינים אופציונליים, מומלץ לכלול גם ערך default.

רשימה של מילות מפתח לאימות מופיעה במסמכי התיעוד בנושא אימות סכימת JSON.

הגדרת מטא-נתונים שרירותיים

כברירת מחדל, Deployment Manager מתעלם מכל השדות שלא תואמים לסכימת JSON תקפה. אם אתם צריכים להרחיב את הסכימות כדי להוסיף שדות או מאפיינים מיוחדים, אתם יכולים ליצור באופן שרירותי כל מאפיין שתרצו ולהוסיף אותו לסכימה, כל עוד השדה או המאפיין לא חופפים למילות מפתח של אימות סכימת JSON.

לדוגמה, אפשר להוסיף שדה מטא-נתונים שמבצע הערה לאחד מהנכסים:

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

או שיוצרים משתנה מיוחד שאפשר להשתמש בו באפליקציות אחרות מחוץ ל-Deployment Manager:

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

יצירת סכימה

סכימה היא מסמך נפרד שנקרא על שם התבנית שהוא מתאר. שמות הסכימות צריכים להיות זהים לשמות התבניות התואמות, עם הסיומת .schema:

TEMPLATE_NAME.EXTENSION.schema

לדוגמה, אם שם התבנית הוא vm-instance.py, שם קובץ הסכימה המתאים צריך להיות vm-instance.py.schema. כל תבנית יכולה לכלול רק סכימה אחת.

סכימות יכולות להכיל שדה אחד או יותר מהשדות שמתוארים בקטע מבנה של סכימה. אפשר גם לכתוב סכימות ב-JSON. דוגמאות לסכימות JSON מופיעות במסמכי העזרה בנושא סכימת JSON.

שימוש בסכימה

gcloud


כשיוצרים פריסה באמצעות Google Cloud CLI, ‏ Deployment Manager מעלה באופן אוטומטי את כל התבניות הרלוונטיות להגדרה. באופן דומה, אם יש קובצי סכימה, שמזוהים לפי הפורמט .schema שנוסף, Deployment Manager יעלה את הסכימה ויאמת את הפריסה מול הסכימה, לפני שינסה ליצור משאבים.

כדי להשתמש בסכימה, פשוט כוללים אותה באותה ספרייה מקומית שבה נמצאים התבניות וההגדרות, ויוצרים את הפריסה כרגיל. ה-CLI של gcloud מזהה את קובץ הסכימה ומעביר אותו ל-Deployment Manager.

API


פועלים לפי ההוראות ליצירת פריסה ב-API, וכוללים את קובץ הסכימה בתוך גוף הבקשה, כמו שכוללים תבנית.

המאמרים הבאים