Utilizzare implementazioni graduali delle funzionalità

Questa guida spiega come configurare ed eseguire un'implementazione graduale delle funzionalità utilizzando i flag di funzionalità di App Lifecycle Manager. Imparerai a definire gli attributi di targeting, configurare le allocazioni basate su percentuali ed eseguire un'implementazione progressiva in modo sicuro.

Utilizzeremo uno scenario in cui vuoi attivare un algoritmo enhanced-search solo per l'1% del tuo traffico, randomizzato in base all'attributo userID, mentre il restante 99% continua a utilizzare la ricerca standard.

Prerequisiti

Prima di iniziare, assicurati di aver completato una delle guide rapide standard per eseguire il provisioning dell'infrastruttura di base o delle risorse flag funzionalità autonomi:

Integra il flag nella tua applicazione

Per supportare le allocazioni basate su percentuali in base ai dati utente, l'applicazione deve collegare il valore dell'attributo (ad es. userID) al contesto di valutazione OpenFeature in fase di runtime prima di chiamare il metodo di valutazione.

Gli esempi seguenti mostrano come recuperare il client inizializzato e valutare il flag con il contesto di targeting allegato.

Vai

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

Configura il comportamento dei flag

Definisci il parametro dell'attributo randomizzato e associalo a una regola di allocazione basata su percentuale nella risorsa flag funzionalità.

  1. Crea l'attributo di targeting: definisci la risorsa dell'attributo userID a livello globale per registrarla per la valutazione del targeting.

    gcloud beta app-lifecycle-manager flags attributes create "user-id-attr" \
      --key="userID" \
      --attribute-value-type="STRING" \
      --location="global"
    
  2. Definisci la regola di allocazione del flag: crea la risorsa flag funzionalità per assegnare un peso dell'1% alla variante enabled randomizzata su 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"]
      }'
    

Crea un'implementazione della configurazione dei flag

Per distribuire in sicurezza la regola di allocazione graduale appena creata, segui le fasi di implementazione immutabile standard.

  1. Crea una revisione: acquisisci uno snapshot della configurazione di allocazione dell'1%.

    gcloud beta app-lifecycle-manager flags revisions create "enhanced-search-rev-1" \
       --location="global" \
       --flag="enhanced-search"
    
  2. Crea una release: pacchettizza la revisione per il deployment in base ai tipi di unità.

    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. Avvia l'implementazione: definisci la strategia di orchestrazione ed esegui il deployment della configurazione.

    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. Monitora l'implementazione: verifica che il deployment raggiunga lo stato SUCCEEDED.

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

Aggiorna il targeting dei flag

Una volta che l'implementazione dell'1% è considerata riuscita e stabile, espandi la percentuale di pubblico dell'implementazione aggiornando il peso di allocazione interno del flag (ad esempio, al 50%).

  1. Aggiorna la specifica del flag: modifica gli slot allocati in modo che il 50% sia attivato e il 50% disattivato.

    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. Esegui il deployment dell'espansione: segui il ciclo di vita per distribuire il peso aggiornato ai client connessi.

    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"
    

    Questa operazione può essere ripetuta continuamente fino a quando la funzionalità non raggiunge il 100% del deployment.

Dismetti un flag

Una volta completata l'implementazione di un flag funzionalità e quando questo funge da comportamento operativo standard, deve essere ritirato in sicurezza.

  1. Rimuovi dall'applicazione: rimuovi tutta la logica condizionale di valutazione dei flag dal codebase dell'applicazione ed esegui il deployment del payload aggiornato in produzione.
  2. Contrassegna per la pulizia: imposta lo stato del flag su CLEANUP per segnalare l'intenzione di eseguire il deprovisioning:

    gcloud beta app-lifecycle-manager flags update "enhanced-search" \
        --location="global" \
        --state=cleanup
    
  3. Esegui il deployment dell'implementazione finale: crea una release di flag che faccia riferimento al flag ed eseguine l'implementazione per scollegare il flag dalle tue unità:

    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"
    

    Al termine dell'implementazione, elimina la release del flag, le revisioni del flag e il flag dal piano di gestione.