기능 플래그 배포

이 빠른 시작에서는 App Lifecycle Manager로 기능 플래그를 만들고, 출시하고, 사용하는 방법을 보여줍니다.

이 빠른 시작에서는 플래그 프로바이더를 설치하고 구성하는 방법과 앱 수명 주기 관리자 기능 플래그를 사용하여 기본 기능 플래그를 실행하는 방법을 알아봅니다.

시작하기 전에

  1. Google 계정에 로그인합니다.

    아직 계정이 없으면 새 계정을 등록하세요.

  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. Google Cloud CLI를 설치합니다.

  7. 외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

  8. gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다. 

    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. Google Cloud CLI를 설치합니다.

  14. 외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

  15. gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다. 

    gcloud init
  16. SaaS 제품을 만듭니다. 이 빠른 시작을 완료하려면 SaaS 제품이 필요합니다. SaaS 제품을 만드는 방법에 대한 자세한 내용은 SaaS 제품 만들기를 참고하세요.

App Lifecycle Manager 서비스 계정에 권한 부여

App Lifecycle Manager API를 사용 설정하면 App Lifecycle Manager에서 서비스 계정을 만듭니다. 이 서비스 계정은 service-PROJECT-NUMBER@gcp-sa-saasservicemgmt.iam.gserviceaccount.com이며 여기서 PROJECT-NUMBER는 프로젝트 번호입니다.

다음 명령어를 실행하여 이 서비스 계정에 필요한 권한을 부여합니다.

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"

다음과 같이 바꿉니다.

  • PROJECT_ID: 프로젝트 ID를 나타내는 문자열 식별자입니다.
  • PROJECT_NUMBER: 프로젝트 번호입니다.

참고 문서 찾기

이 서비스 계정은 단위 프로비저닝과 같은 다양한 작업을 대신 수행합니다.

Artifact Registry에서 저장소 만들기

App Lifecycle Manager를 사용하려면 Artifact Registry에 저장소가 있어야 합니다. 이 저장소를 만들려면 터미널에서 다음 명령어를 실행합니다.

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

이 저장소에는 단위를 프로비저닝하는 방법을 설명하는 청사진 (패키지된 Terraform 파일)이 포함됩니다.

기능 플래그 지정 애플리케이션 청사진 만들기

기능 플래그를 읽고 이를 사용하여 Docker 이미지를 빌드하고 푸시하는 Python 스크립트를 만듭니다.

  1. Docker 빌드 컨텍스트용으로 alm_docker라는 디렉터리를 만듭니다.

  2. alm_docker 디렉터리에서 다음 스니펫으로 flags.py 파일을 만듭니다.

    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)

    이 Python 스크립트는 App Lifecycle Manager 단위에서 Docker 이미지로 실행되는 애플리케이션 내에서 기능 플래그에 액세스하는 방법을 보여줍니다. 표준 OpenFeature 원칙을 사용하여 App Lifecycle Manager 기능 플래그 구성 서비스 (saasconfig.googleapis.com)와 통합됩니다.

  3. alm_docker 디렉터리에 다음 스니펫이 포함된 requirements.txt이라는 텍스트 파일을 만듭니다.

    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. alm_docker 디렉터리에 다음을 사용하여 Dockerfile를 추가합니다.

    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. 로컬 환경에서 다음 명령어를 실행하여 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}"

    다음과 같이 바꿉니다.

    • PROJECT_ID: 프로젝트 ID를 나타내는 문자열 식별자입니다.

  6. Docker 환경에서 alm_terraform 디렉터리를 만듭니다.

  7. alm_terraform에서 다음 파일을 만듭니다.

    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. alm_terraform 디렉터리에서 다음 명령어를 실행하여 Terraform 청사진 파일을 패키징합니다.

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

애플리케이션 블루프린트를 사용하여 단위를 만듭니다.

기능 플래그를 활용하는 애플리케이션 청사진을 만든 후 앱 수명 주기 관리자 단위 종류 (flags-unit-kind)를 만든 다음 이 종류의 단위 (flags-quickstart-unit)를 만들어야 합니다.

단위 및 단위 종류에 대한 자세한 내용은 배포의 모델 및 패키지 단위를 참고하세요.

애플리케이션 블루프린트를 사용하여 단위를 만들려면 다음 gcloud CLI 단계를 따르세요.

  1. Terraform 구성을 OCI 이미지 (청사진)로 패키징하려면 Terraform 디렉터리에 Dockerfile라는 파일을 만듭니다.

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

  2. Dockerfile를 빌드하고 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 .

    다음과 같이 바꿉니다.

    • PROJECT_ID: 프로젝트 ID를 나타내는 문자열 식별자입니다.

  3. flags-unit-kind 및 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

    다음과 같이 바꿉니다.

    • PROJECT_ID: 프로젝트 ID를 나타내는 문자열 식별자입니다.

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

    다음과 같이 바꿉니다.

    • PROJECT_ID: 프로젝트 ID를 나타내는 문자열 식별자입니다.

기능 플래그 만들기 및 프로비저닝

프로비저닝된 단위에서 App Lifecycle Manager 기능 플래그를 사용하려면 먼저 기능 플래그 리소스를 만들고 출시를 시작하여 구성을 단위에 전파해야 합니다.

명령어를 실행하여 quickstart-flag 기능 플래그를 만들고 프로비저닝합니다.

  1. 환경에서 다음 변수를 정의합니다.

    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. 기능 플래그 리소스를 만듭니다.

    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. 버전 만들기:

    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. 출시 버전 만들기

    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. 출시 종류를 만듭니다.

    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. 출시를 만듭니다.

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

다음 명령어를 사용하여 출시 상태를 모니터링할 수 있습니다.

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

실행 중인 서비스에서 플래그 값 보기

App Lifecycle Manager 단위가 Cloud Run 서비스를 성공적으로 프로비저닝한 후 애플리케이션이 실행 중이고 기능 플래그를 올바르게 평가하는지 확인할 수 있습니다.

  1. Google Cloud 콘솔에서 Cloud Run으로 이동합니다.

    Cloud Run으로 이동

  2. us-central1 리전에서 saas-flags-quickstart-svc라는 서비스를 찾습니다. saas-flags-quickstart-svc 옆의 체크표시는 성공적으로 실행되고 있음을 나타냅니다.

  3. saas-flags-quickstart-svc 아이콘을 클릭하여 세부정보를 확인합니다.

    saas-flags-quickstart-svc로 이동

  4. 로그 탭을 선택합니다.

    1. 로그 항목에서 다음과 비슷한 메시지를 찾습니다.

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

      이렇게 하면 애플리케이션이 시작되고 SaaS 구성 서비스에 연결되고 quickstart-flag가 평가되었음을 확인할 수 있습니다.

  5. 공개 엔드포인트에 액세스하려면 네트워킹 탭을 클릭합니다.

    1. 엔드포인트 섹션에 나열된 공개 URL을 찾습니다.
    2. URL을 클릭하여 브라우저에서 열거나 curl와 같은 도구를 사용하여 터미널 (예: curl YOUR_SERVICE_URL)에서 액세스합니다.

    3. URL에 액세스할 때마다 서비스는 기능 플래그를 평가하고 현재 값을 JSON 형식으로 반환합니다. 예를 들면 다음과 같습니다.

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

App Lifecycle Manager 관리 기능 플래그를 읽는 Google Cloud 서비스를 배포했습니다. 플래그 값을 변경하고 새 출시를 만들어 애플리케이션이 변경사항을 선택하는지 실험할 수 있습니다.

삭제

이 페이지에서 사용한 리소스 비용이 Google Cloud 계정에 청구되지 않도록 하려면 다음 단계를 수행합니다.

선택사항: 프로젝트 삭제

새 Google Cloud 프로젝트에 솔루션을 배포했고 프로젝트가 더 이상 없으면 다음 단계에 따라 이를 삭제합니다.

  1. Google Cloud 콘솔에서 리소스 관리 페이지로 이동합니다.

    리소스 관리로 이동

  2. 프로젝트 목록에서 삭제할 프로젝트를 선택하고 삭제를 클릭합니다.
  3. 프롬프트에서 프로젝트 ID를 입력한 후 종료를 클릭합니다.

다음 단계