Siamo alla ricerca di feedback sulle funzionalità dei flag di funzionalità e sull'esperienza utente. Registra il tuo interesse a fornire feedback e influenzare la progettazione del nostro prodotto compilando questo modulo.

Esegui il deployment dei flag funzionalità

Questa guida rapida mostra come creare, implementare e utilizzare i flag funzionalità con App Lifecycle Manager.

In questa guida rapida imparerai a installare e configurare un provider di flag ed eseguire il flagging delle funzionalità di base utilizzando i flag funzionalità di App Lifecycle Manager.

Prima di iniziare

Accedi al tuo Account Google.

Se non ne hai già uno, registrati per un nuovo account.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the App Lifecycle Manager, Artifact Registry, Infrastructure Manager, Developer Connect, Cloud Build, Cloud Storage, Cloud Run and SaaS Config APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Create a service account:

Ensure that you have the Create Service Accounts IAM role (roles/iam.serviceAccountCreator) and the Project IAM Admin role (roles/resourcemanager.projectIamAdmin). Learn how to grant roles.
In the Google Cloud console, go to the Create service account page.
Go to Create service account
Select your project.
In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

In the Service account description field, enter a description. For example, Service account for quickstart.
Click Create and continue.
Grant the Project > Owner role to the service account.

To grant the role, find the Select a role list, then select Project > Owner.

Note: The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
Click Continue.
Click Done to finish creating the service account.

Installa Google Cloud CLI.

Nota: se hai già installato gcloud CLI, assicurati di avere l'ultima versione eseguendo gcloud components update.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the App Lifecycle Manager, Artifact Registry, Infrastructure Manager, Developer Connect, Cloud Build, Cloud Storage, Cloud Run and SaaS Config APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Create a service account:

Ensure that you have the Create Service Accounts IAM role (roles/iam.serviceAccountCreator) and the Project IAM Admin role (roles/resourcemanager.projectIamAdmin). Learn how to grant roles.
In the Google Cloud console, go to the Create service account page.
Go to Create service account
Select your project.
In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

In the Service account description field, enter a description. For example, Service account for quickstart.
Click Create and continue.
Grant the Project > Owner role to the service account.

To grant the role, find the Select a role list, then select Project > Owner.

Note: The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
Click Continue.
Click Done to finish creating the service account.

Installa Google Cloud CLI.

Nota: se hai già installato gcloud CLI, assicurati di avere l'ultima versione eseguendo gcloud components update.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

Crea un'offerta SaaS. Per completare questa guida rapida, devi avere un'offerta SaaS. Per saperne di più su come creare un'offerta SaaS, vedi Crea un'offerta SaaS.

Concedi le autorizzazioni al account di servizio di App Lifecycle Manager

Quando abiliti l'API App Lifecycle Manager, App Lifecycle Manager crea un service account. Questo account di servizio si chiama service-PROJECT-NUMBER@gcp-sa-saasservicemgmt.iam.gserviceaccount.com, dove PROJECT-NUMBER è il numero del tuo progetto.

Concedi a questo account di servizio le autorizzazioni richieste eseguendo il seguente comando:

gcloud projects add-iam-policy-binding `PROJECT_ID` \
    --member="serviceAccount:service-<var>`PROJECT_NUMBER`</var>@gcp-sa-saasservicemgmt.iam.gserviceaccount.com" \
    --role="roles/saasservicemgmt.serviceAgent"

Sostituisci:

PROJECT_ID: un identificatore stringa che rappresenta l'ID progetto.
PROJECT_NUMBER: il numero del tuo progetto.

Individuare la documentazione di riferimento

Questo account di servizio agisce per tuo conto per varie attività, come il provisioning delle unità.

Crea un repository in Artifact Registry

Per utilizzare App Lifecycle Manager, devi avere un repository in Artifact Registry. Per creare questo repository, esegui il seguente comando nel terminale:

gcloud artifacts repositories create flags-quickstart \
    --repository-format=docker \
    --location=us-central1

Questo repository conterrà un progetto (file Terraform pacchettizzati) che descrive come eseguire il provisioning delle unità.

Crea un progetto di applicazione per il flagging delle funzionalità

Crea uno script Python che legge un flag funzionalità e lo utilizza per creare ed eseguire il push di un'immagine Docker:

Crea una directory denominata alm_docker per il contesto di creazione di Docker.

Nella directory alm_docker, crea il file flags.py con questo snippet:

import google.auth.transport.grpc
import google.auth.transport.requests
import grpc
import logging
import time
import os
import sys
from flask import Flask, jsonify

from openfeature import api
from openfeature.provider import ProviderEvent, ProviderStatus
from openfeature.contrib.provider.flagd import FlagdProvider
from openfeature.contrib.provider.flagd.config import ResolverType

# --- Flask App Setup ---
app = Flask(__name__)

# --- Logging Setup ---
logging.basicConfig(stream=sys.stdout) # Log to stdout for Cloud Run
log = logging.getLogger(__name__)
log.setLevel(logging.INFO) # Use INFO or DEBUG as needed

# --- OpenFeature/Flagd Setup ---
FLAG_KEY = "quickstart-flag"
DEFAULT_FLAG_VALUE = False

# Check for necessary environment variable
provider_id = os.environ.get("FLAGD_SOURCE_PROVIDER_ID")
if not provider_id:
  log.critical("FATAL: FLAGD_SOURCE_PROVIDER_ID environment variable not set.")
  sys.exit("FLAGD_SOURCE_PROVIDER_ID not set") # Exit if critical config is missing

log.info(f"Initializing OpenFeature provider for ID: {provider_id}")

def add_x_goog_request_params_header(config_name):
  return lambda context, callback: callback([("x-goog-request-params", f'name={config_name}')], None)

try:
  # Configure gRPC credentials for Google Cloud service
  configservice_credentials = grpc.composite_channel_credentials(
      grpc.ssl_channel_credentials(),
      grpc.metadata_call_credentials(
          google.auth.transport.grpc.AuthMetadataPlugin(
              google.auth.default()[0], # Get just the credentials from the tuple
              google.auth.transport.requests.Request()
          )
      ),
      grpc.metadata_call_credentials(
          add_x_goog_request_params_header(provider_id)
      )
  )

  # Set up the Flagd provider to connect to SaaS Config service
  # Using IN_PROCESS resolver type as recommended for direct gRPC connection
  provider = FlagdProvider(
      resolver_type=ResolverType.IN_PROCESS,
      host="saasconfig.googleapis.com",
      port=443,
      sync_metadata_disabled=True, # Important when using IN_PROCESS with direct service
      provider_id=provider_id,
      channel_credentials=configservice_credentials
  )
  api.set_provider(provider)
  client = api.get_client()

  initial_flag_value = client.get_boolean_value(FLAG_KEY, DEFAULT_FLAG_VALUE)
  log.info(f"***** STARTUP FLAG CHECK ***** Flag '{FLAG_KEY}' evaluated to: {initial_flag_value}")

except Exception as e:
  log.critical(f"FATAL: Failed to initialize OpenFeature provider: {e}", exc_info=True)
  # Depending on the desired behavior, you might exit or let Flask start
  # but log the critical failure. Exiting might be safer in production.
  sys.exit(f"Provider initialization failed: {e}")

# --- Flask Routes ---
@app.route('/')
def home():
  """Endpoint to check the feature flag's value."""
  log.info(f"Request received for flag: {FLAG_KEY}")
  try:
      # Get the flag value. Use the client initialized earlier.
      # The default value (DEFAULT_FLAG_VALUE) is returned if the flag isn't found
      # or if the provider isn't ready/errors occur during evaluation.
      flag_value = client.get_boolean_value(FLAG_KEY, DEFAULT_FLAG_VALUE)
      log.info(f"Evaluated flag '{FLAG_KEY}': {flag_value}")
      return jsonify({
          "flag_key": FLAG_KEY,
          "value": flag_value,
      })
  except Exception as e:
      log.error(f"Error evaluating flag '{FLAG_KEY}': {e}", exc_info=True)
      # Return an error response but keep the server running
      return jsonify({
          "error": f"Failed to evaluate flag {FLAG_KEY}",
          "details": str(e),
      }), 500

if __name__ == '__main__':
  port = int(os.environ.get('PORT', 8080))
  log.info(f"Starting Flask server on port {port}")
  app.run(host='0.0.0.0', port=port)

Questo script Python mostra come accedere ai flag funzionalità all'interno dell'applicazione in esecuzione come immagine Docker su un'unità App Lifecycle Manager. Utilizza i principi standard di OpenFeature per l'integrazione con il servizio di configurazione dei flag funzionalità di App Lifecycle Manager (saasconfig.googleapis.com).

Crea un file di testo denominato requirements.txt nella directory alm_docker che contiene questo snippet:

google-auth
grpcio>=1.49.1,<2.0.0dev
openfeature-sdk==0.8.0
openfeature-provider-flagd==0.2.2
requests 
typing_extensions
Flask>=2.0

Aggiungi il Dockerfile nella directory alm_docker con:

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .

RUN pip install --no-cache-dir -r requirements.txt
COPY flags.py .
CMD ["python", "flags.py"]

Esegui questo comando nell'ambiente locale per creare ed eseguire il push dell'immagine Docker:

export DOCKER_REGISTRY="us-central1-docker.pkg.dev/PROJECT_ID/flags-quickstart"
export FULL_IMAGE_PATH="${DOCKER_REGISTRY}/flags-quickstart:latest"
docker build -t "${FULL_IMAGE_PATH}" .
docker push "${FULL_IMAGE_PATH}"

Sostituisci:

PROJECT_ID: un identificatore stringa che rappresenta l'ID progetto.

Nell'ambiente Docker, crea una directory alm_terraform.

In alm_terraform, crea questi file:

main.tf

locals {
  config_path = "projects/${var.system_unit_project}/locations/${var.system_unit_location}/featureFlagsConfigs/${var.system_unit_name}"
  docker_image_path = "${var.system_unit_location}-docker.pkg.dev/${var.system_unit_project}/${var.docker_repo_name}/${var.docker_tag}"
}

provider "google" {
  project = var.system_unit_project
  region  = var.system_unit_location
}

resource "google_cloud_run_service" "flags_quickstart_service" {
  name     = var.cloud_run_service_name
  location = var.system_unit_location
  project  = var.system_unit_project

  template {
    spec {
      containers {
        image = local.docker_image_path 

        env {
          name  = "FLAGD_SOURCE_PROVIDER_ID"
          value = local.config_path
        }
      }
      service_account_name = var.actuation_sa
    }
  }
}

variables.tf

variable "actuation_sa" {
  description = "Actuation SA"
  type        = string
}

variable "system_unit_project" {
  description = "Project id - variable set by App Lifecycle Manager"
  type        = string
}

variable "system_unit_location" {
  description = "Location - variable set by App Lifecycle Manager"
  type        = string
}

variable "system_unit_name" {
  description = "Unit name- variable set by App Lifecycle Manager"
  type = string
}

variable "docker_repo_name" {
  description = "The name of the Artifact Registry repository where the Docker image is stored."
  type        = string
  default     = "flags-quickstart"
}

variable "docker_tag" {
  description = "The tag of the Docker image to deploy."
  type        = string
  default     = "flags-quickstart:latest"
}

variable "cloud_run_service_name" {
  description = "Name for the Cloud Run service to be created."
  type        = string
  default     = "saas-flags-quickstart-svc"
}

Nella directory alm_terraform, esegui questo comando per pacchettizzare i file del progetto Terraform:
```
zip terraform-files.zip main.tf variables.tf
```

Utilizza il progetto dell'applicazione per creare un'unità

Dopo aver creato un progetto di applicazione che utilizza i flag funzionalità, devi creare un tipo di unità App Lifecycle Manager (flags-unit-kind), quindi creare un'unità di questo tipo (flags-quickstart-unit).

Per saperne di più sulle unità e sui tipi di unità, vedi Modellare e pacchettizzare le unità di un deployment.

Per utilizzare il progetto dell'applicazione per creare un'unità, segui questi passaggi di gcloud CLI:

Per pacchettizzare la configurazione Terraform come immagine OCI (progetto), crea un file denominato Dockerfile nella directory Terraform:
```
# syntax=docker/dockerfile:1-labs
FROM scratch
COPY --exclude=Dockerfile --exclude=.git --exclude=.gitignore . /
```

Crea ed esegui il push di Dockerfile nel repository Artifact Registry:

IMAGE_NAME="us-central1-docker.pkg.dev/PROJECT_ID/flags-quickstart/flags-quickstart-blueprint:latest"
ENGINE_TYPE=inframanager
ENGINE_VERSION=1.5.7

docker buildx build -t $IMAGE_NAME \
  --push \
  --annotation "com.easysaas.engine.type=$ENGINE_TYPE" \
  --annotation "com.easysaas.engine.version=$ENGINE_VERSION" \
  --provenance=false .

Sostituisci:

PROJECT_ID: un identificatore stringa che rappresenta l'ID progetto.

Crea le risorse flags-unit-kind e flags-release:

# Create unit kind
gcloud beta app-lifecycle-manager unit-kinds create flags-unit-kind \
  --project=PROJECT_ID \
  --location=global \
  --saas=flags-quickstart-saas-offering

# Create release referencing the Blueprint image
gcloud beta app-lifecycle-manager releases create flags-release \
  --project=PROJECT_ID \
  --location=global \
  --unit-kind=flags-unit-kind \
  --blueprint-package=$IMAGE_NAME

Sostituisci:

PROJECT_ID: un identificatore stringa che rappresenta l'ID progetto.

Crea l'unità flags-quickstart-unit:

gcloud beta app-lifecycle-manager units create flags-quickstart-unit \
  --project=PROJECT_ID \
  --location=us-central1 \
  --unit-kind=flags-unit-kind \
  --management-mode=user

Sostituisci:

PROJECT_ID: un identificatore stringa che rappresenta l'ID progetto.

Crea ed esegui il provisioning di un flag funzionalità

Prima che un flag funzionalità di App Lifecycle Manager possa essere utilizzato dall'unità di cui hai eseguito il provisioning, devi creare la risorsa del flag funzionalità e avviare un'implementazione per propagare la configurazione all'unità.

Esegui i comandi per creare ed eseguire il provisioning del flag funzionalità quickstart-flag:

Nel tuo ambiente, definisci queste variabili:

export FLAG_ID="quickstart-flag"
export FLAG_KEY="quickstart-flag"
export SAAS_OFFERING_ID="flags-quickstart-saas-offering"
export UNIT_KIND_ID="flags-unit-kind"
export UNIT_ID="flags-quickstart-unit"
export ROLLOUT_KIND_ID="flags-quickstart-rollout-kind"
export ROLLOUT_ID="flags-quickstart-rollout"

Crea la risorsa del flag funzionalità:

gcloud beta app-lifecycle-manager flags create ${FLAG_ID} \
  --project=${PROJECT_ID} \
  --key=${FLAG_KEY} \
  --flag-value-type=BOOL \
  --location=global \
  --unit-kind=${UNIT_KIND_ID}

Crea una revisione:

export FLAG_REVISION_ID="${FLAG_ID}-rev1"
gcloud beta app-lifecycle-manager flags revisions create ${FLAG_REVISION_ID} \
  --project=${PROJECT_ID} \
  --flag=${FLAG_ID} \
  --location=global

Crea una release:

export FLAG_RELEASE_ID="${FLAG_ID}-rel1"
gcloud beta app-lifecycle-manager flags releases create ${FLAG_RELEASE_ID} \
  --project=${PROJECT_ID} \
  --flag-revisions=${FLAG_REVISION_ID} \
  --unit-kind=${UNIT_KIND_ID} \
  --location=global

Crea un tipo di implementazione:

gcloud beta app-lifecycle-manager rollout-kinds create ${ROLLOUT_KIND_ID} \
  --project=${PROJECT_ID} \
  --unit-kind=${UNIT_KIND_ID} \
  --rollout-orchestration-strategy=Google.Cloud.Simple.AllAtOnce \
  --location=global

Crea l'implementazione:

gcloud beta app-lifecycle-manager rollouts create ${ROLLOUT_ID} \
  --project=${PROJECT_ID} \
  --flag-release=${FLAG_RELEASE_ID} \
  --rollout-kind=${ROLLOUT_KIND_ID} \
  --location=global

Puoi monitorare lo stato dell'implementazione con:

gcloud beta app-lifecycle-manager rollouts describe ${ROLLOUT_ID} --project=${PROJECT_ID} --location=global

Visualizza il valore del flag nel servizio in esecuzione

Dopo che l'unità App Lifecycle Manager ha eseguito correttamente il provisioning del servizio Cloud Run, puoi verificare che l'applicazione sia in esecuzione e che valuti correttamente il flag funzionalità:

Nella Google Cloud console, vai a Cloud Run:

Vai a Cloud Run
Trova il servizio denominato saas-flags-quickstart-svc nella regione us-central1. Un segno di spunta accanto a saas-flags-quickstart-svc indica che è in esecuzione correttamente.
Fai clic su saas-flags-quickstart-svc per visualizzarne i dettagli.

Vai a saas-flags-quickstart-svc.
Seleziona la scheda Log.
1. Nelle voci di log, cerca un messaggio simile al seguente:
```
INFO:__main__:***** STARTUP FLAG CHECK ***** Flag 'quickstart-flag' evaluated to: false
```
  Questo conferma che l'applicazione è stata avviata, si è connessa al servizio di configurazione SaaS e ha valutato quickstart-flag.
Per accedere all'endpoint pubblico, fai clic sulla scheda Networking.
1. Trova l'URL pubblico elencato nella sezione Endpoint.
2. Fai clic sull'URL per aprirlo nel browser o utilizza uno strumento come curl per accedervi dal terminale (curl YOUR_SERVICE_URL, ad esempio).
3. Ogni volta che accedi all'URL, il servizio valuta il flag funzionalità e restituisce il suo valore attuale in formato JSON. Ad esempio:
```
{
  "flag_key": "quickstart-flag",
  "value": false
}
```

Hai eseguito correttamente il deployment di un Google Cloud servizio che legge un flag funzionalità gestito da App Lifecycle Manager. Puoi provare a modificare il valore del flag e a creare una nuova implementazione per vedere l'applicazione rilevare la modifica.

Libera spazio

Per evitare che al tuo Google Cloud account vengano addebitati costi relativi alle risorse utilizzate in questa pagina, segui questi passaggi.

(Facoltativo) Elimina il progetto

Se hai eseguito il deployment della soluzione in un nuovo Google Cloud progetto e non ti serve più il progetto, eliminalo completando i seguenti passaggi:

Nella Google Cloud console, vai alla pagina Gestisci risorse.
Vai a Gestisci risorse
Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
Quando ti viene richiesto, digita l'ID progetto, quindi fai clic su Chiudi.

Passaggi successivi

Prova la guida rapida autonoma Esegui il deployment dei flag funzionalità per utilizzare i flag indipendentemente dai deployment gestiti da App Lifecycle Manager.
Esplora le guide all'integrazione specifiche per lingua (Python, Java, Go).
Consulta la panoramica di App Lifecycle Manager per saperne di più su App Lifecycle Manager.