להטמיע תרחישים נפוצים לדוגמה

במסמך הזה מוסבר איך להטמיע תרחישי שימוש נפוצים באמצעות Cloud Quotas API. ה-API הזה מאפשר לכם לשנות מכסות באופן פרוגרמטי ולבצע שינויים אוטומטיים במכסות ב Google Cloud פרויקטים, בתיקיות או בארגון.

מידע נוסף זמין בסקירה הכללית ובהפניה של Cloud Quotas API.

מגבלות

אלו המגבלות שחלות על מכסות ב-Cloud:

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

  • אפשר לבקש הקטנה של מכסות ברמת הפרויקט, הארגון והתיקייה.

מעקב אחר השימוש ושליחת בקשה להגדלת המכסה כשהשימוש עובר את רף ה-80%

בדוגמה הזו נעשה מעקב אחרי השימוש במכסה באמצעות Cloud Monitoring, ואז נשלחת בקשה להגדלת המכסה כשהשימוש בה עולה על 80%.

  1. מתקשרים למשאב QuotaInfo של השירות כדי לקבוע את quotaValue הנוכחי. השירות בדוגמה הזו הוא compute.googleapis.com:

    GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos

    מחליפים את PROJECT_NUMBER במספר הפרויקט.

  2. כדי למצוא את מספר ליבות ה-CPU לכל פרויקט ואת המיקומים הרלוונטיים, צריך לעיין בתגובה QuotaInfo של מזהה המכסה CPUS-per-project-region. הערך של quotaValue הוא 20.

    "quotaInfos": [
  ...
  {
      "name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/CPUS-per-project-region",
      "quotaId": "CPUS-per-project-region",
      "metric": "compute.googleapis.com/cpus",
      "containerType": "PROJECT",
      "dimensions": [
          "region"
      ],
      "dimensionsInfo": [
          {
              "dimensions": [],
              "details": {
                  "quotaValue": 20,
                  "resetValue": 20
              },
              "applicableLocations": [
                  "us-central1",
                  "us-central2",
                  "us-west1",
                  "us-east1"
              ]
          }
      ]
  },
  ...
]

  3. שולחים קריאה ל-Cloud Monitoring API כדי לראות את השימוש במכסה. בדוגמה הבאה, האזור us-central1 צוין. מדדי המכסות הנתמכים מפורטים בקטע serviceruntime.

    {
"name": "projects/PROJECT_NUMBER"
  "filter": "metric.type=\"serviceruntime.googleapis.com/quota/allocation/usage\" AND
  metric.labels.quota_metric=\"compute.googleapis.com/cpus\" AND resource.type=\"consumer_quota\" AND
  resource.label.location=\"us-central1\" ",
  "interval": {
  "startTime": "2023-11-10T18:18:18.0000Z",
  "endTime": "2023-11-17T18:18:18.0000Z"
  },
  "aggregation": {
  "alignmentPeriod": "604800s", // 7 days
  "perSeriesAligner": "ALIGN_MAX",
  "crossSeriesReducer": "REDUCE_MAX"
  }
}

  4. כדי לקבוע את השימוש, צריך לטפל בתגובה מ-Cloud Monitoring API. כדי לקבוע את השימוש, משווים את הערך מ-Cloud Monitoring לערך quotaValue מהשלבים הקודמים.

    בדוגמה הבאה של תגובה, ערך השימוש ב-Cloud Monitoring הוא 19 באזור us-central1. הערך של quotaValue בכל האזורים הוא 20. השימוש גדול מ-80% מהמכסה, ואפשר ליזום עדכון של העדפת המכסה.

    time_series {
metric {
labels {
key: "quota_metric"
value: "compute.googleapis.com/cpus"
}
  type: "serviceruntime.googleapis.com/quota/allocation/usage"
}
resource {
  type: "consumer_quota"
  labels {
    key: "project_id"
    value: "PROJECT_ID"
  }
  labels {
    key: "location"
    value: "us-central1"
  }
}
metric_kind: GAUGE
value_type: INT64
points {
  interval {
    start_time {
      seconds: "2023-11-10T18:18:18.0000Z"
    }
    end_time {
      seconds: "2023-11-17T18:18:18.0000Z"
    }
  }
  value {
    int64_value: 19
  }
}
}

  5. כדי להימנע מהעדפות מכסה כפולות, צריך להתקשר אל ListQuotaPreferences קודם כדי לבדוק אם יש בקשות בהמתנה. הדגל reconciling=true קורא לבקשות בהמתנה.

    GET projects/PROJECT_NUMBER/locations/global/quotaPreferences?filter=service=%22compute.googleapis.com%22%20AND%20quotaId=%22CPUS-per-project-region%22%20AND%20reconciling=true

    מחליפים את PROJECT_NUMBER במספר הפרויקט.

  6. מתקשרים אל UpdateQuotaPreference כדי להגדיל את ערך המכסה לאזור us-central1. בדוגמה הבאה, צוין ערך מועדף חדש של 100.

    השדה allow_missing מוגדר ל-true. התג הזה אומר למערכת ליצור משאב QuotaPreference אם לא קיים משאב עם השם שצוין.

    PATCH projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1?allowMissing=true {
"service": "compute.googleapis.com",
"quotaId": "CPUS-per-project-region",
"quotaConfig": { "preferredValue": 100 },
"dimensions": { "region": "us-central1" },
"justification": "JUSTIFICATION",
"contactEmail": "EMAIL"
}

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫PROJECT_NUMBER: המזהה הייחודי של הפרויקט.
    • ‫JUSTIFICATION: מחרוזת אופציונלית שמסבירה את הבקשה.
    • ‫EMAIL: כתובת אימייל שאפשר להשתמש בה ככתובת ליצירת קשר, למקרה ש- Google Cloud יצטרך מידע נוסף לפני שיוכל לאשר הקצאת נפח אחסון נוסף.

  7. מתקשרים אל GetQuotaPreference כדי לבדוק את הסטטוס של שינוי העדפת המכסה:

    GET projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1

    מחליפים את PROJECT_NUMBER במספר הפרויקט.

    בזמן ש- Google Cloud בודק את ערך המכסה המבוקש, סטטוס המכסה שלכם מוגדר כ-true.

    לפעמים Google Cloud מאשרת חלק מבקשת ההגדלה במקום לאשר את ההגדלה המלאה. אם הבקשה אושרה באופן חלקי, העדפת המכסה כוללת את השדה stateDetail. בשדה stateDetail מתואר המצב של אישור חלקי. בשדה grantedValue מוצגת ההתאמה שבוצעה כדי למלא חלקית את הבקשה שלך.

    כדי לראות אם הערך שאושר הוא הערך הסופי, בודקים את השדה reconciling. אם הבקשה שלך עדיין בבדיקה, הערך של השדה reconciling הוא true. אם השדה reconciling מוגדר ל-false או מושמט, הערך שמאושר הוא הערך הסופי.

    בדוגמה הבאה, ערך המכסה המבוקש הוא 100, והשדה reconciling מציין שהבקשה נמצאת בבדיקה.

    "name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1",
"service": "compute.googleapis.com",
"quotaId": "CPUS-per-project-region",
"quotaConfig": {
  "preferredValue": 100,
  "grantedValue": 50,
  "traceId": "123acd-345df23",
  "requestOrigin": "ORIGIN_UNSPECIFIED"
},
"dimensions": { "region": "us-central1" },
"reconciling": true,
"createTime": "2023-01-15T01:30:15.01Z",
"updateTime": "2023-01-16T02:35:16.01Z"

    אחרי שהעדפת המכסה תעובד, השדה reconciling יוגדר לערך false. הערך של grantedValue זהה לערך של preferredValue. המכסה המועדפת אושרה במלואה.

    כש- Google Cloud דוחה או מאשר חלקית בקשת לקוח, ערך המכסה שאושר עדיין יכול להיות נמוך מהערך המועדף.

הקטנת מכסה

בדוגמה הבאה, מספר ה-TPU יורד ל-10 בכל אזור.

  1. כדי לקבל את מזהה המכסה ואת ערך המכסה הנוכחי, מבצעים קריאה ל-ListQuotaInfos:

    GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos

    מחליפים את PROJECT_NUMBER במספר הפרויקט.

  2. בודקים את שדות התגובה כדי למצוא רשומה של QuotaInfo עבור V2-TPUS-per-project-region.

    "quotaInfos": [
  ...
  {
      "name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-region",
      "quotaId": "V2-TPUS-per-project-region",
      "metric": "compute.googleapis.com/Tpus",
      "containerType": "PROJECT",
      "dimensions": [
          "region"
      ],
      "dimensionsInfo": [
          {
              "dimensions": [],
              "details": {
                  "quotaValue": 20,
                  "resetValue": 20
              },
              "applicableLocations": [
                  "us-central1",
                  "us-central2",
                  "us-west1",
                  "us-east1"
              ]
          }
      ]
  },
  ...
]

    בתגובה הזו, מזהה הקצאה הוא V2-TPUS-per-project-region, והערך הנוכחי של quotaValue הוא 20.

  3. צמצום מכסת ה-TPU בכל אזור ל-10 עם CreateQuotaPreferenceRequest. מגדירים את הערך preferredValue ל-10.

    POST projects/PROJECT_NUMBER/locations/global/quotaPreferences?quotaPreferenceId=compute_googleapis_com-Tpu-all-regions {
  "quotaConfig": {
      "preferredValue": 10
  },
  "dimensions": [],
  "service": "compute.googleapis.com",
  "quotaId": "V2-TPUS-per-project-region",
  "justification": "JUSTIFICATION",
  "contactEmail": "EMAIL"
}

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫PROJECT_NUMBER: המזהה הייחודי של הפרויקט.
    • ‫JUSTIFICATION: מחרוזת אופציונלית שמסבירה את הבקשה.
    • ‫EMAIL: כתובת אימייל שאפשר להשתמש בה ככתובת ליצירת קשר, למקרה ש- Google Cloud יצטרך מידע נוסף לפני שיוכל לאשר הקצאת נפח אחסון נוסף.

  4. מאשרים את ערך המכסה החדש באמצעות קריאה ל-GetQuotaInfo שבה מזהה המכסה מוגדר כ-V2-TPUS-per-project-region.

    GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-region

    מחליפים את PROJECT_NUMBER במספר הפרויקט.

    זוהי דוגמה לתשובה, הערך value הוא 10 והוא רלוונטי בכל האזורים.

    "name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-region",
"quotaId": "V2-TPUS-per-project-region",
"metric": "compute.googleapis.com/v2_tpus",
"containerType": "PROJECT",
"dimensions": [
  "region"
],
"dimensionsInfo": [
  {
      "dimensions": [],
      "details": {
          "value": 10,
      },
      "applicableLocations": [
          "us-central1",
          "us-central2",
          "us-west1",
          "us-east1"
      ]
  }
]

העתקת העדפות מכסה לפרויקט אחר

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

  1. שיחה עם ListQuotaPreferences בפרויקט המקור ללא מסנן:

    GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences

    ‫PROJECT_NUMBER1 הוא מספר הפרויקט של פרויקט המקור. התשובה מכילה את כל העדפות המכסה של פרויקט המקור.

  2. לכל העדפת מכסה בתשובה, קוראים ל-UpdateQuotaPreference ומגדירים את השדות הבאים:

    • ‫name – שדה השם המעודכן נלקח מהתגובה, ומספר פרויקט המקור (PROJECT_NUMBER1) מוחלף במספר פרויקט היעד (PROJECT_NUMBER2).

    • ‫service, quotaId, preferredValue, dimensions – אפשר לקחת את השדות האלה ישירות מהתגובה כמו שהם.

    for (QuotaPreference srcPreference : listResponse.getQuotaPreferences()) {
  QuotaPreference.Builder targetPreference = QuotaPreference.newBuilder()
      .setName(srcPreference.getName().replace("PROJECT_NUMBER1", "PROJECT_NUMBER2"))
      .setService(srcPreference.getService())
      .setQuotaId(srcPreference.getQuotaId())
      .setJustification(srcPreference.getJustification())
      .setContactEmail(srcPreference.getContactEmail())
      .setQuotaConfig(
          QuotaConfig.newBuilder().setPreferredValue(srcPreference.getQuotaConfig().getPreferredValue()))
      .putAllDimensions(srcPreference.getDimensionsMap());
  UpdateQuotaPreferenceRequest updateRequest = UpdateQuotaPreferenceRequest.newBuilder()
      .setQuotaPreference(targetPreference)
      .setAllowMissing(true)
      .build();
  cloudQuotas.updateQuotaPreference(updateRequest);
}

  3. מתקשרים אל ListQuotaPreferences כדי לאמת את הסטטוס של העדפות המכסה בפרויקט היעד:

    GET projects/PROJECT_NUMBER2/locations/global/quotaPreferences

    מחליפים את PROJECT_NUMBER2 במספר הפרויקט של פרויקט היעד.

רשימת בקשות מכסה בהמתנה

כדי לרשום את כל הבקשות להעדפות מכסה שממתינות לאישור בפרויקט, קוראים לפונקציה ListQuotaPreferences עם המסנן reconciling=true.

GET projects/PROJECT_NUMBER/locations/global/quotaPreferences?reconciling=true

מחליפים את PROJECT_NUMBER במספר הפרויקט.

בתגובה לבקשה הזו מוחזרת העדפת המכסה האחרונה בהמתנה. מכיוון ש-Cloud Quotas API הוא ממשק API הצהרתי, המערכת מנסה לממש את העדפת המכסה האחרונה.

דוגמה לתגובה:

  "quotaPreferences": [
    {
      "name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1",
      "service": "compute.googleapis.com",
      "quotaId": "CPUS-per-project-region",
      "quotaConfig": {
        "preferredValue": 100,
        "grantedValue": 30,
        "traceId": "123acd-345df23",
        "requestOrigin": "ORIGIN_UNSPECIFIED"
      },
      "dimensions": {
        "region": "us-central1"
      },
      "reconciling": true,
      "createTime": "2023-01-15T01:30:15.01Z",
      "updateTime": "2023-01-16T02:35:16.01Z"
    },
    {
      "name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-cross-regions",
      "service": "compute.googleapis.com",
      "quotaId": "CPUS-per-project-region",
      "quotaConfig": {
        "preferredValue": 10,
        "grantedValue": 5,
        "traceId": "456asd-678df43",
        "requestOrigin": "ORIGIN_UNSPECIFIED"
      },
      "reconciling": true,
      "createTime": "2023-01-15T01:35:15.01Z",
      "updateTime": "2023-01-15T01:35:15.01Z"
    }
  ]

בקשה להגדלת מכסות לקבוצה

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

לכל שורה בקובץ ה-CSV, קוראים את התוכן לשדות serviceName, quotaId, preferredValue ו-dimensionMap.

CreateQuotaPreferenceRequest request =
  CreateQuotaPreferenceRequest.newBuilder()
     .setParent("projects/PROJECT_NUMBER/locations/global")
     .setQuotaPreferenceId(buildYourOwnQuotaPreferenceId(serviceName, quotaId, dimensionMap))
     .setQuotaPreference(
        QuotaPreference.newBuilder()
            .setService(serviceName)
            .setQuotaId(quotaId)
            .setJustification(justification)
            .setContactEmail(contactEmail)
            .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(preferredValue))
            .putAllDimensions(dimensionMap))
  .build();
cloudQuotas.createQuotaPreference(request);

מחליפים את PROJECT_NUMBER במספר הפרויקט.

מכיוון שפרויקט היעד חדש, אפשר לבצע קריאה ל-method‏ CreateQuotaPreference בזמן הקריאה וההקצאה של השדות. אפשרות נוספת היא להתקשר לשיטה UpdateQuotaPreference עם allow_missing שמוגדר כ-true.

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

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

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

קבלת מידע על מכסות של מאפיין ספציפי בשירות

משפחת GPU היא מאפיין ספציפי לשירות. בדוגמה הבאה של בקשה נעשה שימוש במזהה המכסה GPUS-PER-GPU-FAMILY-per-project-region כדי לקבל את המשאב QuotaInfo.

GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/GPUS-PER-GPU-FAMILY-per-project-region

מחליפים את PROJECT_NUMBER במספר הפרויקט.

זוהי דוגמה לתשובה. לכל מפתח ייחודי מסוג gpu_family, הערכים quotaValue ו-applicableLocations שונים:

"name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/GpusPerProjectPerRegion",
"quotatName": "CPUS-per-project-region",
"metric": "compute.googleapis.com/gpus_per_gpu_family",
"isPrecise": true,
"quotaDisplayName": "GPUs per GPU family",
"metricDisplayName": "GPUs",
"dimensions": [
    "region",
    "gpu_family"
],
"dimensionsInfo": [
    {
        "dimensions": {
            "region": "us-central1",
            "gpu_family": "NVIDIA_H200"
        },
        "details": {
            "quotaValue": 30,
            "resetValue": 30,
        },
        "applicableLocations": [
            "us-central1"
        ]
    },
    {
        "dimensions": {
            "region": "us-central1"
            }
        "details": {
            "quotaValue": 100,
            "resetValue": 100,
        },
        "applicableLocations": [
            "us-central1"
        ]
    },
    {
        "dimensions": {
            "gpu_familly": "NVIDIA_H100"
            }
        "details": {
            "quotaValue": 10,
        },
        "applicableLocations": [
            "us-central2",
            "us-west1",
            "us-east1"
        ]
    }
      {
        "dimensions": [],
        "details": {
            "quotaValue": 50,
            "resetValue": 50,
        },
        "applicableLocations": [
            "us-central1",
            "us-central2",
            "us-west1",
            "us-east1"
        ]
    }
]

יצירת העדפת מכסה למאפיין ספציפי לשירות

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

בדוגמה הבאה של CreateQuotaPreference מצוינת משפחת GPU‏ NVIDIA_H100 ואזור us-central1.

POST projects/PROJECT_NUMBER/locations/global/quotaPreferences?quotaPreferenceId=compute_googleapis_com-gpus-us-central1-NVIDIA_H100 {
    "service": "compute.googleapis.com",
    "quotaId": "GPUS-PER-GPU-FAMILY-per-project-region",
    "quotaConfig": {
        "preferredValue": 100
    },
    "dimensions": {"region": "us-central1", "gpu_family": "NVIDIA_H100"},
    "justification": "JUSTIFICATION",
    "contactEmail": ""EMAIL"
}

מחליפים את מה שכתוב בשדות הבאים:

  • ‫PROJECT_NUMBER: המזהה הייחודי של הפרויקט.
  • ‫JUSTIFICATION: מחרוזת אופציונלית שמסבירה את הבקשה.
  • ‫EMAIL: כתובת אימייל שאפשר להשתמש בה ככתובת ליצירת קשר, למקרה ש- Google Cloud יצטרך מידע נוסף לפני שיוכל לאשר הקצאת נפח אחסון נוסף.

עדכון העדפה של מכסה למאפיין ספציפי לשירות

בדוגמת הקוד הבאה מתקבל הערך הנוכחי של המאפיין {"region" : "us-central1"; gpu_family:"NVIDIA_H100"}, ואז הערך המועדף מוגדר כערך כפול. היא כתובה ב-Java, אבל אפשר להשתמש בכל שפת תכנות.

// Get the current quota value for the target dimensions
Map<String, String> targetDimensions = Maps.createHashMap("region", "us-central1", "gpu_family", "NVIDIA_H100");
long currentQuotaValue = 0;
QuotaInfo quotaInfo = cloudQuotas.GetQuotaInfo(
    "projects/PROJECT_NUMBER/locations/global/services/" + serviceName + "quotaInfos/" + quotaId;
for (dimensionsInfo : quotaInfo.getDimensionsInfoList()) {
    If (targetDimensions.entrySet().containsAll(dimensionsInfo.getDimensionsMap().entrySet()) {
       currentQuotaValue = dimensionsInfo.getDetails().getValue();
       break;
    })
}

// Set the preferred quota value to double the current value for the target dimensions
QuotaPreference.Builder targetPreference = QuotaPreference.newBuilder()
        .setName(buildYourOwnQuotaPreferenceId(serviceName, quotaId, targetDimensions))
        .setService(serviceName)
        .setQuotaId(quotaId)
        .setJustification(justification)
        .setContactEmail(contactEmail)
        .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(currentQuotaValue * 2))
        .putAllDimensions(targetDimensions));
UpdateQuotaPreferenceRequest updateRequest = UpdateQuotaPreferenceRequest.newBuilder()
        .setQuotaPreference(targetPreference)
        .setAllowMissing(true)
        .build();
 cloudQuotas.updateQuotaPreference(updateRequest);

מחליפים את PROJECT_NUMBER במזהה הייחודי של הפרויקט.

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