Label instances

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

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

תמיד מוסיפים תוויות כצמדי מפתח/ערך:

{
 "userLabels": {
    "track": "production",
    "location": "western-division"
    "billing-code": "34802",...
 }

שינוי תוויות לא משפיע על הביצועים של מכונות Cloud SQL.

מידע נוסף זמין במאמרים מהן תוויות? ודרישות לגבי תוויות.

הגבלות

  • אפשר להקצות עד 50 תוויות בהגדרת משתמש לכל מכונה. למרות שמשאביGoogle Cloud תומכים בעד 64 תוויות בסך הכול, Cloud SQL שומר עד 14 תוויות למערכת פנימית ולמטא-נתונים של חיוב בתמונות מצב של גיבוי בסיסי.
  • אם למכונה קיימת כבר יש יותר מ-50 תוויות שהוגדרו על ידי המשתמש, לא תוכלו להוסיף תוויות חדשות, וגיבויים אוטומטיים או לפי דרישה עלולים להיכשל אם מספר התוויות של המשתמש והמערכת ביחד עולה על 64. כדי למנוע כשלים בגיבוי, צריך להקטין את מספר התוויות שמוגדרות על ידי המשתמש ל-50 או פחות לכל מכונה.

  • המפתחות והערכים של התוויות צריכים לעמוד במגבלות הבאות:

    • המפתחות והערכים לא יכולים להיות ארוכים מ-63 תווים כל אחד.
    • המפתחות והערכים יכולים להכיל רק אותיות קטנות, ספרות, קווים תחתונים ומקפים. אפשר להשתמש בתווים בינלאומיים.
    • המפתחות של התוויות צריכים להתחיל באות קטנה.
    • המפתחות של התוויות לא יכולים להיות ריקים.

יצירת מכונות עם תוויות

כשיוצרים מכונה חדשה באמצעות ה-CLI של gcloud או ה-API, אפשר להוסיף תוויות למכונה.

gcloud

כשיוצרים את המכונה, מוסיפים את הדגל ‎ `--labels` ‎ ואחריו רשימה מופרדת בפסיקים של צמדי מפתח/ערך של תוויות. כדי לכלול תוויות, צריך להשתמש בגרסת הבטא של הפקודה create.

לדוגמה:

gcloud beta sql instances create ... --labels track=production,billing-code=34802

Terraform

כשיוצרים מכונה עם תווית, משתמשים במשאב של Terraform: 

resource "google_sql_database_instance" "default" {
  name             = "sqlserver-instance-labels"
  region           = "us-central1"
  database_version = "SQLSERVER_2019_STANDARD"
  root_password    = "INSERT-PASSWORD-HERE"
  settings {
    tier = "db-custom-2-7680"
    user_labels = {
      track        = "production"
      billing-code = 34802
    }
  }
}

החלה של השינויים

כך מחילים את ההגדרות של Terraform בפרויקט ב- Google Cloud :

הכנת Cloud Shell

  1. מפעילים את Cloud Shell.

  2. מגדירים את פרויקט ברירת המחדל ב- Google Cloud שבו רוצים להחיל את ההגדרות של Terraform.

    תצטרכו להריץ את הפקודה הזו רק פעם אחת לכל פרויקט, ותוכלו לעשות זאת בכל ספרייה.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

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

הכנת הספרייה

לכל קובץ תצורה של Terraform צריכה להיות ספרייה משלו (שנקראת גם מודול ברמה הבסיסית).

  1. יוצרים ספרייה חדשה ב-Cloud Shell ובה יוצרים קובץ חדש. שם הקובץ חייב לכלול את הסיומת .tf, למשל main.tf. במדריך הזה, הקובץ נקרא main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. אם אתם עוקבים אחרי המדריך, תוכלו להעתיק את הקוד לדוגמה בכל קטע או שלב.

    מעתיקים את הקוד לדוגמה בקובץ main.tf החדש שיצרתם.

    לחלופין, אפשר גם להעתיק את הקוד מ-GitHub. כדאי לעשות את זה כשקטע הקוד של Terraform הוא חלק מפתרון מקצה לקצה.

  3. בודקים את הפרמטרים לדוגמה ומשנים אותם בהתאם לסביבה שלכם.
  4. שומרים את השינויים.
  5. מפעילים את Terraform. צריך לעשות זאת רק פעם אחת לכל ספרייה. 
    terraform init

    אופציונלי: תוכלו לכלול את האפשרות -upgrade, כדי להשתמש בגרסה העדכנית ביותר של הספק של Google: 

    terraform init -upgrade

החלה של השינויים

  1. בודקים את ההגדרות ומוודאים שהמשאבים שמערכת Terraform תיצור או תעדכן תואמים לציפיות שלכם: 
    terraform plan

    מתקנים את ההגדרות לפי הצורך.

  2. מריצים את הפקודה הבאה ומזינים yes בהודעה שמופיעה, כדי להחיל את הגדרות Terraform: 
    terraform apply

    ממתינים עד שב-Terraform תוצג ההודעה "Apply complete!‎".

  3. פותחים את הפרויקט ב- Google Cloud כדי להציג את התוצאות. במסוף Google Cloud , נכנסים למשאבים בממשק המשתמש כדי לוודא שהם נוצרו או עודכנו ב-Terraform.

למחוק את השינויים

כדי למחוק את השינויים:

  1. כדי להשבית את ההגנה מפני מחיקה, בקובץ התצורה של Terraform מגדירים את הארגומנט deletion_protection לערך false. 
    deletion_protection =  "false"
  2. מריצים את הפקודה הבאה ומזינים yes בהודעה שמופיעה, כדי להחיל את הגדרות Terraform המעודכנות: 
    terraform apply

  1. כדי להסיר משאבים שהוחלו בעבר על הגדרות Terraform, מריצים את הפקודה הבאה ומזינים yes בהודעה שמופיעה:

    terraform destroy

curl

ב-API, במהלך בקשת ה-`POST` להוספת מכונה חדשה, מוסיפים את המאפיין `userLabels` לגוף הבקשה כדי להחיל תוויות על המכונה החדשה. לדוגמה, גוף הבקשה ליצירת מכונה כולל את התוויות הבאות:

          "settings": {"tier":"db-custom-2-7680",
                       "userLabels": {"track": "production",
                                      "location": "western-division",
                                      "billing-code": "34802"},

הוספה או עדכון של תוויות במכונה קיימת

console

  1. נכנסים לדף Cloud SQL Instances במסוף Google Cloud .

    כניסה לדף Cloud SQL Instances

  2. מסמנים את התיבות לצד המשאבים שרוצים להוסיף להם תוויות.

  3. לוחצים על Show Info Panel בפינה הימנית העליונה כדי להרחיב את עמודת התוויות.

  4. מעדכנים או מוסיפים תוויות חדשות לפי הצורך.

  5. שומרים את השינויים.

gcloud

כדי לעדכן או להוסיף תוויות למכונה קיימת, משתמשים בפקודת המשנה patch (גרסת בטא):

gcloud beta sql instances patch [INSTANCE_NAME] --update-labels [KEY1]=[VALUE1]...

לדוגמה:

gcloud beta sql instances patch my-instance --update-labels track=production,billing-code=34802

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

rest v1

כדי להוסיף או לעדכן תוויות, משתמשים ב-method‏ PATCH:

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫project-id: מזהה הפרויקט
  • ‫instance-id: מזהה המכונה
  • ‫label-name-1: שם התווית
  • ‫value-1: הערך של label-name-1
  • ‫label-name-2: שם התווית
  • ‫value-2: הערך של label-name-2

ה-method של ה-HTTP וכתובת ה-URL: 

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

תוכן בקשת JSON: 

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name-1" : "value-1",
            "label-name-2" : "value-2"
         }
    }
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

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

rest v1beta4

כדי להוסיף או לעדכן תוויות, משתמשים ב-method‏ PATCH:

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫project-id: מזהה הפרויקט
  • ‫instance-id: מזהה המכונה
  • ‫label-name-1: שם התווית
  • ‫value-1: הערך של label-name-1
  • ‫label-name-2: שם התווית
  • ‫value-2: הערך של label-name-2

ה-method של ה-HTTP וכתובת ה-URL: 

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

תוכן בקשת JSON: 

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name-1" : "value-1",
            "label-name-2" : "value-2"
         }
    }
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

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

הסרת תווית

console

  1. נכנסים לדף Cloud SQL Instances במסוף Google Cloud .

    כניסה לדף Cloud SQL Instances

  2. מסמנים את התיבות לצד המשאבים שרוצים להסיר מהם את התוויות.

  3. לוחצים על Show info panel כדי להרחיב את עמודת התוויות.

  4. לוחצים על X לצד כל התוויות שרוצים להסיר.

  5. שומרים את השינויים.

gcloud

באמצעות ה-CLI של gcloud, מריצים את פקודת המשנה patch (גרסת בטא) עם הדגל --remove-labels:

gcloud beta sql instances patch [INSTANCE_NAME] --remove-labels [LABEL1],[LABEL2]

אם תציינו שם של תווית שלא קיימת, לא תוחזר שגיאה.

rest v1

כדי להסיר תווית באמצעות ה-API, מגדירים את הערך שלה ל-null:

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫project-id: מזהה הפרויקט
  • ‫instance-id: מזהה המכונה
  • ‫label-name: שם התווית

ה-method של ה-HTTP וכתובת ה-URL: 

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

תוכן בקשת JSON: 

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name" : null,
         }
    }
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

rest v1beta4

כדי להסיר תווית באמצעות ה-API, מגדירים את הערך שלה ל-null:

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫project-id: מזהה הפרויקט
  • ‫instance-id: מזהה המכונה
  • ‫label-name: שם התווית

ה-method של ה-HTTP וכתובת ה-URL: 

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

תוכן בקשת JSON: 

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name" : null,
         }
    }
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

סינון חיפושים של מכונות באמצעות תוויות

אפשר לסנן את תוצאות רשימת המכונות לפי תוויות באמצעות ה-CLI של gcloud או ה-API.

gcloud

ב-gcloud, שולחים בקשת list ומשתמשים בדגל --filter. כדי לסנן לפי תוויות, משתמשים בתחביר labels.[KEY]:[VALUE]. לדוגמה, כדי לסנן לפי תווית billing-code עם הערך 34802, אפשר להריץ את הפקודה הבאה:

gcloud beta sql instances list --filter='labels.billing-code:34802'

אם רוצים לסנן לפי קיום של תווית, בלי קשר לערך שלה:

gcloud beta sql instances list --filter='labels:billing-code'

במסמכי התיעוד של gcloud topic filters מפורט מידע מלא על תחביר המסננים ב-CLI של gcloud.

curl

ב-API, שולחים בקשת רשימה עם פרמטר שאילתה filter מקודד בכתובת URL:

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.[KEY1_NAME]:[KEY1_VALUE]%20userLabels.[KEY2_NAME]:[KEY2_VALUE]

לדוגמה:

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.track:production%20userLabels.billing-code:34802

כששני ערכי תוויות נכללים עם רווח (מקודד) ביניהם, שניהם צריכים להיות נכונים כדי שיוחזר מופע (פעולת AND). אפשר גם לציין במפורש את האופרטורים AND,‏ OR ו-NOT. לדוגמה:

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.track:production%20OR%20userLabels.billing-code:34802

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