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

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

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

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

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

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

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

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

המשך

import (
    "context"
    "fmt"
    "log"

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

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

// 1. Get client
client := openfeature.NewClient("simple-api")

// 2. Create Evaluation Context with user data
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)
}

Java

// 1. Get client
var client = OpenFeatureAPI.getInstance().getClient("simple-api");

// 2. Create Evaluation Context with user data
var context = new dev.openfeature.sdk.MutableContext();
context.add("userID", userID);

// 3. Evaluate flag
boolean isEnhanced = client.getBooleanValue("enhanced-search", false, context);

// 4. Execute business logic
if (isEnhanced) {
    System.out.println("Executing enhanced search algorithm...");
} else {
    System.out.println("Executing standard search algorithm...");
}

Python

import openfeature
from openfeature.evaluation_context import EvaluationContext

# 1. Get client
client = openfeature.api.get_client()

# 2. Create Evaluation Context with user data
eval_ctx = EvaluationContext(
    targeting_key=str(user_id),
    attributes={
        "userID": user_id,
    }
)

# 3. Evaluate flag
is_enhanced = client.get_boolean_value(
    "enhanced-search",
    False,
    eval_ctx
)

# 4. Execute business logic
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 כדי להקצות משקל של 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": "disabled", "booleanValue": false }, { "id": "enabled", "booleanValue": true } ]' \
      --evaluation-spec='{
        "allocations": [{
          "id": "percentage-rollout",
          "randomizedOn": "userID",
          "slots": [
            {"variant": "disabled", "weight": 99},
            {"variant": "enabled", "weight": 1}
          ]
        }],
        "defaultAllocation": "percentage-rollout",
        "attributes": ["projects/PROJECT_ID/locations/global/flagAttributes/user-id-attr"]
      }'
    

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

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

  1. יצירת גרסה: יוצרים קובץ snapshot של הגדרת ההקצאה של 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" \
       --revisions="enhanced-search-rev-1"
    
  3. התחלת ההשקה: מגדירים את אסטרטגיית התזמור ופורסים את ההגדרות.

    gcloud beta app-lifecycle-manager rollout-kinds create "rollout-kind-of-enhanced-search" \
       --unit-kind="demo-test-unitkind" \
       --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" \
      --location="global" \
      --evaluation-spec='{
        "allocations": [{
          "id": "percentage-rollout",
          "randomizedOn": "userID",
          "slots": [
            {"variant": "disabled", "weight": 50},
            {"variant": "enabled", "weight": 50}
          ]
        }],
        "defaultAllocation": "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" \
       --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%.

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

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

  1. הסרה מהאפליקציה: מסירים את כל הלוגיקה המותנית של הערכת הדגלים מבסיס הקוד של האפליקציה, ופורסים את המטען הייעודי (payload) המעודכן בסביבת הייצור.
  2. סימון לניקוי: מגדירים את מצב הדגל לערך CLEANUP כדי לסמן שרוצים לבטל את ההקצאה שלו:

    gcloud beta app-lifecycle-manager flags update "enhanced-search" \
        --location="global" \
        --state=cleanup
    
  3. השקה סופית: יוצרים גרסת השקה של הדגל שמפנה לדגל, ומשיקים אותה כדי לנתק את הדגל מהיחידות:

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

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