Schrittweise Einführung von Funktionen

In diesem Leitfaden wird beschrieben, wie Sie einen schrittweisen Funktions-Roll-out mit Funktions-Flags von App Lifecycle Manager konfigurieren und ausführen. Sie erfahren, wie Sie Targeting-Attribute definieren, prozentuale Zuweisungen konfigurieren und einen progressiven Roll-out sicher durchführen.

In diesem Szenario möchten Sie einen enhanced-search-Algorithmus für nur 1 % Ihres Traffics aktivieren, der nach dem Attribut userID randomisiert wird, während die restlichen 99 % weiterhin die Standardsuche verwenden.

Vorbereitung

Bevor Sie beginnen, müssen Sie eine der Standard-Kurzanleitungen abgeschlossen haben, um Ihre Referenzinfrastruktur oder eigenständige Funktions-Flag-Ressourcen bereitzustellen:

Flag in Ihre Anwendung einbinden

Damit prozentuale Zuweisungen basierend auf Nutzerdaten unterstützt werden, muss Ihre Anwendung den Attributwert (z.B. userID) zur Laufzeit an den OpenFeature-Evaluierungskontext anhängen, bevor die Evaluierungsmethode aufgerufen wird.

In den folgenden Beispielen wird gezeigt, wie Sie den initialisierten Client abrufen und das Flag mit angehängtem Targeting-Kontext auswerten.

Go

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}")

Flag-Verhalten konfigurieren

Definieren Sie den Parameter für das randomisierte Attribut und verknüpfen Sie ihn mit einer prozentualen Zuweisungsregel für die Funktions-Flag-Ressource.

  1. Targeting-Attribut erstellen: Definieren Sie die Attributressource userID global, um sie für die Targeting-Bewertung zu registrieren.

    gcloud beta app-lifecycle-manager flags attributes create "user-id-attr" \
      --key="userID" \
      --attribute-value-type="STRING" \
      --location="global"
    
  2. Regel für die Flag-Zuweisung definieren: Erstellen Sie die Funktions-Flag-Ressource, um der Variante enabled, die zufällig auf userID basiert, eine Gewichtung von 1 % zuzuweisen.

    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"]
      }'
    

Roll-out einer Flag-Konfiguration erstellen

Um die neu erstellte Regel für die schrittweise Zuweisung sicher zu verteilen, durchlaufen Sie die standardmäßigen unveränderlichen Rollout-Phasen.

  1. Version erstellen: Erstellen Sie einen Snapshot der Konfiguration mit der 1-%-Zuweisung.

    gcloud beta app-lifecycle-manager flags revisions create "enhanced-search-rev-1" \
       --location="global" \
       --flag="enhanced-search"
    
  2. Release erstellen: Verpacken Sie die Version für die Bereitstellung in Ihren Einheitentypen.

    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. Roll-out starten: Definieren Sie Ihre Orchestrierungsstrategie und stellen Sie die Konfiguration bereit.

    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. Roll-out überwachen: Prüfen Sie, ob die Bereitstellung den Status SUCCEEDED erreicht.

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

Flag-Targeting aktualisieren

Wenn die Einführung bei 1 % der Nutzer erfolgreich und stabil ist, erhöhen Sie den Prozentsatz der Nutzer, indem Sie die interne Zuweisungsgewichtung des Flags aktualisieren (z.B. auf 50 %).

  1. Flag-Spezifikation aktualisieren: Ändern Sie die zugewiesenen Slots in 50 % aktiviert und 50 % deaktiviert.

    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. Erweiterung bereitstellen: Folgen Sie dem Lebenszyklus, um die aktualisierte Gewichtung an verbundene Clients zu verteilen.

    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"
    

    Dieser Vorgang kann kontinuierlich wiederholt werden, bis die Funktion zu 100 % bereitgestellt ist.

Flag außer Betrieb nehmen

Nachdem ein Funktions-Flag vollständig eingeführt wurde und als Standardverhalten dient, muss es sicher außer Betrieb genommen werden.

  1. Aus Anwendung entfernen: Entfernen Sie die gesamte bedingte Logik für die Flag-Auswertung aus der Codebasis Ihrer Anwendung und stellen Sie die aktualisierte Nutzlast in der Produktion bereit.
  2. Zum Bereinigen markieren: Setzen Sie den Flag-Status auf CLEANUP, um die Absicht zu signalisieren, die Bereitstellung aufzuheben:

    gcloud beta app-lifecycle-manager flags update "enhanced-search" \
        --location="global" \
        --state=cleanup
    
  3. Endgültigen Roll-out bereitstellen: Erstellen Sie einen Flag-Release, der auf das Flag verweist, und führen Sie dafür einen Roll-out aus, um das Flag von Ihren Einheiten zu trennen:

    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"
    

    Löschen Sie nach Abschluss des Roll-outs den Flag-Release, die Flag-Versionen und das Flag aus der Verwaltungsebene.