שימוש בתגי ישות לבקרת בו-זמניות אופטימית

‫Secret Manager תומך בשימוש בתגי ישות (ETags) לבקרת בו-זמניות אופטימית.

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

תגי ETag מאפשרים בקרת בו-זמניות אופטימית, כי הם מאפשרים לתהליכים לראות אם משאב שונה לפני שהם מבצעים פעולה במשאב הזה.

שימוש ב-ETags עם Secret Manager

בקשות השינוי הבאות של משאבים תומכות ב-ETags:

בבקשת secrets.patch, תג ה-ETag של הבקשה מוטמע בנתוני Secret. כל הבקשות האחרות מקבלות פרמטר אופציונלי etag.

אם מצוין ETag והוא תואם ל-ETag הנוכחי של המשאב, הבקשה תצליח. אחרת, היא תיכשל עם השגיאה FAILED_PRECONDITION וקוד הסטטוס HTTP 400. אם לא מצוין ETag, הבקשה תמשיך בלי לבדוק את ערך ה-ETag שמאוחסן כרגע.

תגי ETag של משאבים נוצרים בזמן יצירת המשאב (projects.secrets.create,‏ projects.secrets.addVersion) ומתעדכנים עבור כל אחת מבקשות השינוי שמופיעות ברשימה שלמעלה. בקשת שינוי מעדכנת רק את ה-ETag של המשאב שאליו היא מתייחסת. כלומר, עדכון של גרסת סוד לא משפיע על ה-ETag של הסוד, וכך גם עדכון של ה-ETag לא משפיע על גרסת הסוד.

גם אם עדכון לא משנה את מצב המשאב, הוא עדיין מעדכן את ה-ETag של המשאב.

דוגמה:

  • משתמש 1 מנסה להפעיל גרסה סודית בלי לדעת שהיא כבר הופעלה. המערכת מעבדת את זה, ולא משנה שום דבר חוץ מה-ETag של הגרסה.

  • משתמש 2, שמשתמש ב-ETag הישן, מנסה להשבית את הגרסה.

  • הפעולה נכשלת כי המערכת מזהה את תג ה-ETag החדש יותר, שמציין כוונה עדכנית יותר להשאיר את הגרסה מופעלת.

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

המשאב etag מוחזר בתשובה בכל פעם שמשאב (Secret או SecretVersion) נכלל.

מחיקת סוד באמצעות ETags

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

gcloud

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

  • ‫SECRET_ID: המזהה של הסוד.
  • ‫ETAG: תג הישות של הסוד. תג ה-ETag חייב לכלול את המירכאות שמקיפות אותו. לדוגמה, אם ערך ה-ETag היה "abc", הערך אחרי הסרת התווים המיוחדים יהיה "\"abc\"".

מריצים את הפקודה הבאה:

‫Linux,‏ macOS או Cloud Shell

gcloud secrets delete SECRET_ID \
    --etag "ETAG"

‏Windows (PowerShell)

gcloud secrets delete SECRET_ID `
    --etag "ETAG"

Windows‏ (cmd.exe)

gcloud secrets delete SECRET_ID ^
    --etag "ETAG"

REST

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

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫SECRET_ID: המזהה של הסוד.
  • ‫ETAG: תג הישות של הסוד. ה-ETag מצוין כחלק ממחרוזת השאילתה של כתובת ה-URL, והוא חייב להיות בקידוד URL. לדוגמה, אם ערך ה-ETag הוא "abc", הערך המקודד בכתובת ה-URL יהיה %22abc%22 כי התו של המירכאות מקודד כ-%22.

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

DELETE https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?etag=ETAG

גוף בקשת JSON: 

{}

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

curl

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?etag=ETAG"

PowerShell

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?etag=ETAG" | Select-Object -Expand Content

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

{}

עדכון סוד באמצעות תגי ETags

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

gcloud

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

  • ‫SECRET_ID: המזהה של הסוד.
  • ‫KEY: שם התווית.
  • ‫VALUE: ערך התווית התואם.
  • ‫ETAG: תג הישות של הסוד. תג ה-ETag חייב לכלול את המירכאות שמקיפות אותו. לדוגמה, אם ערך ה-ETag היה "abc", הערך אחרי הסרת התווים המיוחדים יהיה "\"abc\"".

מריצים את הפקודה הבאה:

‫Linux,‏ macOS או Cloud Shell

gcloud secrets update SECRET_ID \
    --update-labels "KEY=VALUE" \
    --etag "ETAG"

‏Windows (PowerShell)

gcloud secrets update SECRET_ID `
    --update-labels "KEY=VALUE" `
    --etag "ETAG"

Windows‏ (cmd.exe)

gcloud secrets update SECRET_ID ^
    --update-labels "KEY=VALUE" ^
    --etag "ETAG"

התשובה מחזירה את הסוד.

REST

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

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫SECRET_ID: המזהה של הסוד.
  • ‫ETAG: תג הישות של הסוד. התג ETag מצוין כשדה ב-Secret וחייב לכלול את המרכאות שמסביב. לדוגמה, אם ערך ה-ETag היה "abc", הערך אחרי הוספת התו '\' יהיה {"etag":"\"abc\""}.
  • ‫KEY: שם התווית.
  • ‫VALUE: ערך התווית התואם.

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

PATCH https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=labels

גוף בקשת JSON: 

{"etag":"ETAG", "labels":{"KEY": "VALUE"}}

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

curl

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=labels"

PowerShell

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=labels" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-04T04:06:00.660420Z",
  "labels": {
    "KEY": "VALUE"
  },
  "etag": "\"162145a4f894d5\""
}

עדכון גרסה של סוד באמצעות תגי ETags

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

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

gcloud

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

  • ‫VERSION_ID: המזהה של גרסת הסוד.
  • ‫SECRET_ID: המזהה של הסוד.
  • ‫ETAG: תג הישות. תג ה-ETag חייב לכלול את המירכאות שמקיפות אותו. לדוגמה, אם ערך ה-ETag היה "abc", הערך אחרי הסרת התווים המיוחדים יהיה "\"abc\"".

מריצים את הפקודה הבאה:

‫Linux,‏ macOS או Cloud Shell

gcloud secrets versions disable VERSION_ID \
  --secret SECRET_ID \
  --etag "ETAG"

‏Windows (PowerShell)

gcloud secrets versions disable VERSION_ID `
  --secret SECRET_ID `
  --etag "ETAG"

Windows‏ (cmd.exe)

gcloud secrets versions disable VERSION_ID ^
  --secret SECRET_ID ^
  --etag "ETAG"

התשובה מחזירה את הסוד.

REST

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

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫SECRET_ID: המזהה של הסוד.
  • ‫VERSION_ID: המזהה של גרסת הסוד.
  • ‫ETAG: תג הישות של גרסת הסוד. התג ETag מוגדר כשדה ב-SecretVersion וחייב לכלול את המרכאות שמסביב. לדוגמה, אם ערך ה-ETag היה "abc", הערך אחרי הוספת התו '\' יהיה {"etag":"\"abc\""}.

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

POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:disable"

גוף בקשת JSON: 

{"etag":"ETAG"}

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

curl

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:disable""

PowerShell

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:disable"" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions/VERSION_ID",
  "createTime": "2024-09-04T06:41:57.859674Z",
  "state": "DISABLED",
  "etag": "\"1621457b3c1459\""
}

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