Funktions-Flags bereitstellen

In dieser Kurzanleitung erfahren Sie, wie Sie mit App Lifecycle Manager Funktions-Flags erstellen, einführen und verwenden.

In dieser Kurzanleitung lernen Sie, wie Sie einen Flag-Anbieter installieren und konfigurieren und grundlegende Funktions-Flags mit App Lifecycle Manager-Funktions-Flags ausführen.

Hinweis

  1. Melden Sie sich bei Ihrem Google-Konto an.

    Wenn Sie noch kein Konto haben, melden Sie sich hier für ein neues Konto an.

  2. 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

  3. Verify that billing is enabled for your Google Cloud project.

  4. 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

  5. Create a service account:

    1. 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.

    2. In the Google Cloud console, go to the Create service account page.

      Go to Create service account
    3. Select your project.

    4. 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.

    5. Click Create and continue.

    6. Grant the Project > Owner role to the service account.

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

    7. Click Continue.

    8. Click Done to finish creating the service account.

  6. Installieren Sie die Google Cloud CLI.

  7. Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

  8. Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren: 

    gcloud init

  9. 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

  10. Verify that billing is enabled for your Google Cloud project.

  11. 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

  12. Create a service account:

    1. 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.

    2. In the Google Cloud console, go to the Create service account page.

      Go to Create service account
    3. Select your project.

    4. 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.

    5. Click Create and continue.

    6. Grant the Project > Owner role to the service account.

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

    7. Click Continue.

    8. Click Done to finish creating the service account.

  13. Installieren Sie die Google Cloud CLI.

  14. Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

  15. Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren: 

    gcloud init
  16. SaaS-Angebot erstellen Sie benötigen ein SaaS-Angebot, um diese Kurzanleitung abzuschließen. Weitere Informationen zum Erstellen eines SaaS-Angebots finden Sie unter SaaS-Angebot erstellen.

Berechtigungen für das App Lifecycle Manager-Dienstkonto gewähren

Wenn Sie die App Lifecycle Manager API aktivieren, erstellt App Lifecycle Manager ein Dienstkonto. Dieses Dienstkonto heißt service-PROJECT-NUMBER@gcp-sa-saasservicemgmt.iam.gserviceaccount.com, wobei PROJECT-NUMBER Ihre Projektnummer ist.

Gewähren Sie diesem Dienstkonto die erforderlichen Berechtigungen, indem Sie den folgenden Befehl ausführen:

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"

Ersetzen Sie:

  • PROJECT_ID: Eine String-ID, die Ihre Projekt-ID darstellt.
  • PROJECT_NUMBER: Ihre Projektnummer.

Referenzdokumentation suchen

Dieses Dienstkonto führt in Ihrem Namen verschiedene Aufgaben aus, z. B. die Bereitstellung von Einheiten.

Repository in Artifact Registry erstellen

Wenn Sie App Lifecycle Manager verwenden möchten, benötigen Sie ein Repository in Artifact Registry. Führen Sie den folgenden Befehl in Ihrem Terminal aus, um dieses Repository zu erstellen:

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

Dieses Repository enthält einen Blueprint (verpackte Terraform-Dateien), der beschreibt, wie Sie Ihre Einheiten bereitstellen.

Blueprint für eine Anwendung mit Funktions-Flags erstellen

Erstellen Sie ein Python-Skript, das ein Funktions-Flag liest, und verwenden Sie es, um ein Docker-Image zu erstellen und zu übertragen:

  1. Erstellen Sie ein Verzeichnis mit dem Namen alm_docker für den Docker-Build-Kontext.

  2. Erstellen Sie im Verzeichnis alm_docker die Datei flags.py mit diesem 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)

    Dieses Python-Skript zeigt, wie Sie auf Funktions-Flags in Ihrer Anwendung zugreifen, die als Docker-Image auf einer App Lifecycle Manager-Einheit ausgeführt wird. Es verwendet standardmäßige OpenFeature-Prinzipien zur Integration in den App Lifecycle Manager-Konfigurationsdienst für Funktions-Flags (saasconfig.googleapis.com).

  3. Erstellen Sie im Verzeichnis alm_docker eine Textdatei mit dem Namen requirements.txt, die dieses Snippet enthält:

    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

  4. Fügen Sie dem Dockerfile im Verzeichnis alm_docker Folgendes hinzu:

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

  5. Führen Sie diesen Befehl in Ihrer lokalen Umgebung aus, um das Docker-Image zu erstellen und zu übertragen:

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

    Ersetzen Sie:

    • PROJECT_ID: Eine String-ID, die Ihre Projekt-ID darstellt.

  6. Erstellen Sie in Ihrer Docker-Umgebung ein Verzeichnis alm_terraform.

  7. Erstellen Sie in alm_terraform die folgenden Dateien:

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

  8. Führen Sie im Verzeichnis alm_terraform diesen Befehl aus, um die Terraform-Blueprint-Dateien zu verpacken:

    zip terraform-files.zip main.tf variables.tf

Anwendungs-Blueprint zum Erstellen einer Einheit verwenden

Nachdem Sie einen Anwendungs-Blueprint erstellt haben, der Funktions-Flags verwendet, müssen Sie eine App Lifecycle Manager-Einheit (flags-unit-kind) und dann eine Einheit dieser Art (flags-quickstart-unit) erstellen.

Weitere Informationen zu Einheiten und Einheitenarten finden Sie unter Einheiten eines Roll-outs modellieren und verpacken .

So erstellen Sie mit dem Anwendungs-Blueprint eine Einheit über die gcloud CLI:

  1. Wenn Sie Ihre Terraform-Konfiguration als OCI-Image (Blueprint) verpacken möchten, erstellen Sie im Terraform-Verzeichnis eine Datei mit dem Namen Dockerfile:

    # syntax=docker/dockerfile:1-labs
FROM scratch
COPY --exclude=Dockerfile --exclude=.git --exclude=.gitignore . /

  2. Dockerfile erstellen und in Ihr Artifact Registry-Repository übertragen:

    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 .

    Ersetzen Sie:

    • PROJECT_ID: Eine String-ID, die Ihre Projekt-ID darstellt.

  3. Erstellen Sie die Ressourcen flags-unit-kind und 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

    Ersetzen Sie:

    • PROJECT_ID: Eine String-ID, die Ihre Projekt-ID darstellt.

  4. Erstellen Sie die Einheit 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

    Ersetzen Sie:

    • PROJECT_ID: Eine String-ID, die Ihre Projekt-ID darstellt.

Funktions-Flag erstellen und bereitstellen

Bevor ein App Lifecycle Manager-Funktions-Flag von Ihrer bereitgestellten Einheit verwendet werden kann, müssen Sie die Funktions-Flag-Ressource erstellen und einen Roll-out starten, um die Konfiguration an die Einheit zu übertragen.

Führen Sie die Befehle aus, um das Funktions-Flag quickstart-flag zu erstellen und bereitzustellen:

  1. Definieren Sie in Ihrer Umgebung die folgenden Variablen:

    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"

  2. Erstellen Sie die Funktions-Flag-Ressource:

    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}

  3. Erstellen Sie eine Überarbeitung:

    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

  4. Erstellen Sie ein 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

  5. Erstellen Sie eine Roll-out-Art:

    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

  6. Erstellen Sie den Roll-out:

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

Sie können den Roll-out-Status mit dem folgenden Befehl überwachen:

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

Flag-Wert im laufenden Dienst ansehen

Nachdem Ihre App Lifecycle Manager-Einheit den Cloud Run-Dienst erfolgreich bereitgestellt hat, können Sie prüfen, ob Ihre Anwendung ausgeführt wird und das Funktions-Flag korrekt auswertet:

  1. Rufen Sie in der Google Cloud Console Cloud Run auf:

    Zu Cloud Run

  2. Suchen Sie in der Region us-central1 nach dem Dienst saas-flags-quickstart-svc. Ein Häkchen neben saas-flags-quickstart-svc zeigt an, dass der Dienst erfolgreich ausgeführt wird.

  3. Klicken Sie auf saas-flags-quickstart-svc, um die Details aufzurufen.

    Zu saas-flags-quickstart-svc.

  4. Wählen Sie den Tab Logs aus.

    1. Suchen Sie in den Logeinträgen nach einer Meldung wie der folgenden:

      INFO:__main__:***** STARTUP FLAG CHECK ***** Flag 'quickstart-flag' evaluated to: false

      Dies bestätigt, dass die Anwendung gestartet, eine Verbindung zum SaaS-Konfigurationsdienst hergestellt und das Flag quickstart-flag ausgewertet hat.

  5. Klicken Sie auf den Tab Networking, um auf den öffentlichen Endpunkt zuzugreifen.

    1. Suchen Sie im Abschnitt Endpoints nach der öffentlichen URL.
    2. Klicken Sie auf die URL, um sie in Ihrem Browser zu öffnen, oder verwenden Sie ein Tool wie curl, um über das Terminal darauf zuzugreifen (curl YOUR_SERVICE_URL, z. B.).

    3. Jedes Mal, wenn Sie auf die URL zugreifen, wertet der Dienst das Funktions-Flag aus und gibt den aktuellen Wert im JSON-Format zurück. Beispiel:

      {
  "flag_key": "quickstart-flag",
  "value": false
}

Sie haben erfolgreich einen Google Cloud Dienst bereitgestellt, der ein von App Lifecycle Manager verwaltetes Funktions-Flag liest. Sie können den Wert des Flags ändern und einen neuen Roll-out erstellen, um zu sehen, wie Ihre Anwendung die Änderung übernimmt.

Bereinigen

Mit den folgenden Schritten vermeiden Sie, dass Ihrem Google Cloud -Konto die auf dieser Seite verwendeten Ressourcen in Rechnung gestellt werden:

Optional: Projekt löschen

Wenn Sie die Lösung in einem neuen Google Cloud Projekt bereitgestellt haben und das Projekt nicht mehr benötigen, löschen Sie es so:

  1. Wechseln Sie in der Google Cloud Console zur Seite Ressourcen verwalten.

    Zu „Ressourcen verwalten“

  2. Wählen Sie in der Projektliste das Projekt aus, das Sie löschen möchten, und klicken Sie auf Löschen.
  3. Geben Sie an der Eingabeaufforderung die Projekt-ID ein und klicken Sie auf Herunterfahren.

Nächste Schritte