שימוש בהשקות הדרגתיות של תכונות

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

נשתמש בתרחיש שבו רוצים להפעיל אלגוריתם enhanced-search רק ל-1% מהתנועה, באופן אקראי לפי המאפיין userID, בזמן ש-99% הנותרים ממשיכים להשתמש בחיפוש רגיל.

דרישות מוקדמות

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

שילוב הדגל באפליקציה

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

בדוגמאות הבאות מוסבר איך לאחזר את הלקוח שאותחל ולהעריך את הדגל עם הקשר של הטירגוט שמצורף.

```go import ( "context" "fmt" "log"

"github.com/open-feature/go-sdk/pkg/openfeature"

)

‫‎// Example userID - in a real application, this would come from the request context. var userID = "example-user-123"

‫// 1. קבלת לקוח client := openfeature.NewClient("simple-api")

‫// 2. יצירת הקשר של ההערכה עם נתוני המשתמש evalCtx := openfeature.NewEvaluationContext( userID, map[string]interface{}{ "userID": userID, // Ensure userID is passed dynamically }, )

‫// 3. Evaluate flag (defaults to false if unreachable) isEnhanced, err := client.BooleanValue(context.Background(), "enhanced-search", false, evalCtx) if err != nil { log.Printf("Flag evaluation failed: %v", err) }

‫// 4. ‪Execute business logic if isEnhanced { log.Printf("Enhanced search algorithm for user %s", userID) } else { log.Printf("Standard search algorithm for user %s", userID) } </devsite-tab> <devsite-tab title="Java">java // 1. Get client var client = OpenFeatureAPI.getInstance().getClient("simple-api");

‫// 2. יצירת הקשר של ההערכה עם נתוני משתמש var context = new dev.openfeature.sdk.MutableContext(); context.add("userID", userID);

‫// 3. הערכת דגל boolean isEnhanced = client.getBooleanValue("enhanced-search", false, context);

‫// 4. הפעלת לוגיקה עסקית if (isEnhanced) { System.out.println("Executing enhanced search algorithm..."); } else { System.out.println("Executing standard search algorithm..."); } </devsite-tab> <devsite-tab title="Python">python import openfeature from openfeature.evaluation_context import EvaluationContext

1. הורדת אפליקציית הלקוח

client = openfeature.api.get_client()

2. יצירת הקשר להערכה עם נתוני משתמשים

eval_ctx = EvaluationContext( targeting_key=str(user_id), attributes={ "userID": user_id,
} )

3. הערכת דגל

is_enhanced = client.get_boolean_value( "enhanced-search", False, eval_ctx )

4. הפעלת לוגיקה עסקית

if is_enhanced: print(f"Executing enhanced search for user {user_id}") else: print(f"Executing standard search for user {user_id}") ```

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

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

  1. יוצרים את מאפיין הטירגוט: מגדירים את משאב המאפיין userID באופן גלובלי כדי לרשום אותו להערכת טירגוט.

    gcloud beta app-lifecycle-manager flags attributes create "user-id-attr" \
  --key="userID" \
  --attribute-value-type="STRING" \
  --location="global"

  2. הגדרת כלל להקצאת feature flag: יוצרים את משאב feature flag כדי להקצות משקל של 1% לווריאציה enabled שעוברת אקראיות ב-userID.

    gcloud beta app-lifecycle-manager flags create "enhanced-search" \
  --key="enhanced-search" \
  --flag-value-type=BOOL \
  --location="global" \
  --unit-kind="demo-test-unitKind" \
  --variants='[ { "id": "Enabled", "booleanValue": true }, { "id": "Disabled", "booleanValue": false } ]' \
  --evaluation-spec='{
    "allocations": [{
      "id": "percentage-rollout",
      "randomizedOn": "userID",
      "slots": [
        {"variant": "enabled", "weight": 1},
        {"variant": "disabled", "weight": 99}
      ]
    }],
    "defaultTarget": "percentage-rollout",
    "attributes": ["projects/PROJECT_ID/locations/global/flagAttributes/user-id-attr"]
  }' \

יצירת השקה של הגדרת דגל

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

  1. יצירת גרסה: צילום תמונת מצב של הקצאת 1%.

    gcloud beta app-lifecycle-manager flags revisions create "enhanced-search-rev-1" \
   --location="global" \
   --flag="enhanced-search"

  2. יצירת גרסת הפצה: אורזים את התיקון לפריסה בהתאם לסוגי היחידות.

    gcloud beta app-lifecycle-manager flags releases create "release-of-enhanced-search" \
   --location="global" \
   --unit-kind="demo-test-unitkind" \
   --flag-revisions="enhanced-search-rev-1"

  3. התחלת ההשקה: מגדירים את אסטרטגיית התיאום ופורסים את ההגדרה.

    gcloud beta app-lifecycle-manager rollout-kinds create "rollout-kind-of-enhanced-search" \
   --unit-kind="demo-test-unikind" \
   --rollout-orchestration-strategy="Google.Cloud.Simple.AllAtOnce" \
   --location="global"

gcloud beta app-lifecycle-manager rollouts create "rollout-of-enhanced-search" \
   --flag-release="release-of-enhanced-search" \
   --rollout-kind="rollout-kind-of-enhanced-search" \
   --location="global"

  4. מעקב אחרי ההשקה: מוודאים שהפריסה מגיעה למצב SUCCEEDED.

    gcloud beta app-lifecycle-manager rollouts describe "rollout-of-enhanced-search" \
   --location="global"

עדכון של טירגוט לפי דגל

אחרי שנקבע שההשקה ל-1% מהמשתמשים הייתה מוצלחת ויציבה, אפשר להגדיל את אחוז המשתמשים בהשקה על ידי עדכון משקל ההקצאה הפנימי של הדגל (למשל, ל-50%).

  1. מעדכנים את הגדרות הדגל: משנים את משבצות ההקצאה ל-50% מופעלות ו-50% מושבתות.

    gcloud beta app-lifecycle-manager flags update "enhanced-search" \
  --evaluation-spec='{
    "allocations": [{
      "id": "percentage-rollout",
      "randomizedOn": "userID",
      "slots": [
        {"variant": "enabled", "weight": 50},
        {"variant": "disabled", "weight": 50}
      ]
    }],
    "defaultTarget": "percentage-rollout",
    "attributes": ["projects/PROJECT_ID/locations/global/flagAttributes/user-id-attr"]
  }'

  2. פריסת ההרחבה: פועלים לפי מחזור החיים כדי להפיץ את המשקל המעודכן ללקוחות המקושרים.

    gcloud beta app-lifecycle-manager flags revisions create "enhanced-search-rev-2" \
   --location="global" \
   --flag="enhanced-search"

gcloud beta app-lifecycle-manager flags releases create "enhanced-search-50pct" \
   --location="global" \
   --unit-kind="demo-test-unitkind" \
   --flag-revisions="enhanced-search-rev-2"

gcloud beta app-lifecycle-manager rollouts create "rollout-of-enhanced-search-50pct" \
   --flag-release="enhanced-search-50pct" \
   --rollout-kind="rollout-kind-of-enhanced-search" \
   --location="global"

    אפשר לחזור על הפעולה הזו שוב ושוב עד שהתכונה תופעל ב-100% מהמכשירים.

הוצאה משימוש של דגל

curl --request POST
"https://saasservicemgmt.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/flagReleases?flagReleaseId=obsolete-enhanced-search"
--header "Authorization: Bearer $(gcloud auth application-default print-access-token)"
--header "Content-Type: application/json"
--header "Accept: application/json"
--data "{ "unitKind": "projects/PROJECT_ID/locations/global/unitKinds/UNIT_KIND_ID", "obsoleteFlags": ["projects/PROJECT_ID/locations/global/flags/enhanced-search"] }"

אחרי ש-feature flag מופעל באופן מלא ומשמש כהתנהגות תפעולית רגילה, צריך להוציא אותו משימוש בצורה בטוחה.

  1. הסרה מהאפליקציה: מסירים את כל הלוגיקה המותנית של הערכת הסימון מבסיס הקוד של האפליקציה ומפרסים את מטען הנתונים המעודכן בסביבת הייצור.
  2. סימון לניקוי: מגדירים את מצב הדגל לערך CLEANUP כדי לציין במפורש את הכוונה לבטל את ההקצאה.
  3. פריסת ההשקה הסופית: מבצעים השקה סופית כדי להפוך את הגדרת ה-Backend ללא זמינה באופן מפורש. לאחר מכן אפשר למחוק בצורה מאובטחת את הדגל ואת מטא-נתוני הגרסה ממישור הניהול.