Menggunakan tombol fitur Mandiri

Pelajari cara menggunakan tombol fitur App Lifecycle Manager sebagai layanan mandiri untuk mengelola ketersediaan fitur di aplikasi Anda, meskipun aplikasi tersebut tidak di-deploy atau dikelola oleh App Lifecycle Manager.

Pengantar

Panduan memulai ini menunjukkan cara menggunakan kemampuan peluncuran terkontrol dan tombol fitur yang andal dari App Lifecycle Manager tanpa perlu menggunakan App Lifecycle Manager untuk penyediaan infrastruktur (seperti men-deploy VM atau layanan Cloud Run menggunakan cetak biru Terraform). Pendekatan ini ideal jika Anda mengelola infrastruktur aplikasi secara independen, tetapi ingin menggunakan App Lifecycle Manager untuk pengelolaan tombol fitur yang aman.

Dalam pendekatan mandiri ini, Anda akan:

  1. Membuat model sistem Anda dengan resource App Lifecycle Manager yang ringan: Buat Units App Lifecycle Manager untuk mewakili komponen infrastruktur yang ada (misalnya, deployment microservice tertentu, lingkungan tenant, instance biner tunggal). Unit ini hanya bertindak sebagai target untuk konfigurasi tombol dan tidak melibatkan deployment infrastruktur menggunakan cetak biru App Lifecycle Manager.
  2. Menentukan dan Mendistribusikan Tombol: Gunakan App Lifecycle Manager API atau Google Cloud konsol untuk membuat tombol fitur. Kelola siklus prosesnya menggunakan Rollouts App Lifecycle Manager untuk memastikan propagasi perubahan konfigurasi yang aman dan bertahap ke Units yang dimodelkan. Hal ini memberikan konsistensi dan keamanan operasional meskipun hanya mengelola tombol.
  3. Berintegrasi dengan Aplikasi Anda: Gunakan OpenFeature SDK dengan penyedia flagd dalam kode aplikasi Anda (berjalan di mana saja – lokal, on-premise, cloud yang dikelola sendiri). Konfigurasikan untuk terhubung ke layanan tombol App Lifecycle Manager (saasconfig.googleapis.com), autentikasi, dan mengidentifikasi dirinya sendiri menggunakan nama resource Unit yang sesuai untuk mengambil nilai tombol yang benar.

Pendekatan ini memungkinkan Anda mendapatkan manfaat dari distribusi tombol yang aman dan terkelola tanpa mengubah pipeline deployment atau alat pengelolaan infrastruktur yang ada.

Tombol fitur App Lifecycle Manager berada dalam Pratinjau Pribadi. Akses memerlukan daftar yang diizinkan. Untuk meminta akses bagi organisasi atau project Anda, isi formulir ini.

Panduan memulai ini menggunakan aplikasi Python dasar yang berjalan secara lokal untuk mendemonstrasikan akses ke tombol, yang mensimulasikan cara aplikasi yang ada akan terintegrasi.

Tujuan

  • Menyiapkan project baru atau menggunakan project yang sudah ada. Google Cloud
  • Mengaktifkan API yang diperlukan (App Lifecycle Manager dan SaaS Config).
  • Memberikan izin Identity and Access Management yang diperlukan untuk pembuatan resource dan pembacaan tombol.
  • Membuat resource App Lifecycle Manager minimal (Penawaran SaaS, Jenis Unit, Unit) untuk memodelkan komponen aplikasi tanpa men-deploy infrastruktur.
  • Menentukan resource tombol fitur yang terkait dengan Jenis Unit.
  • Membuat mekanisme peluncuran tombol (Jenis Peluncuran) yang menentukan strategi distribusi.
  • Mendistribusikan konfigurasi tombol awal menggunakan Peluncuran App Lifecycle Manager.
  • Menjalankan aplikasi Python contoh secara lokal yang terhubung ke layanan tombol App Lifecycle Manager dan mengevaluasi tombol untuk Unit yang dimodelkan.
  • Memperbarui nilai tombol, membuat rilis tombol baru, dan mendistribusikan perubahan.
  • Memastikan aplikasi mengambil nilai tombol yang diperbarui.

Sebelum memulai

  1. Login ke Akun Google Anda.

    Jika Anda belum memilikinya, Daftar untuk membuat akun baru.

  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 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. Instal Google Cloud CLI.

  6. Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

  7. Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut: 

    gcloud init

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

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

  10. Enable the App Lifecycle Manager 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

  11. Instal Google Cloud CLI.

  12. Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

  13. Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut: 

    gcloud init
  14. Instal Python: Pastikan Anda telah menginstal Python 3.7+ di mesin tempat Anda akan menjalankan aplikasi contoh. Anda juga memerlukan pip untuk menginstal dependensi. 
    python --version
     
    pip --version
  15. Mengautentikasi gcloud untuk Kredensial Default Aplikasi (ADC): Skrip Python lokal menggunakan ADC untuk mengautentikasi ke Google Cloud layanan. Login menggunakan akun pengguna Anda: 
    gcloud auth application-default login
  16. Memberikan Izin Identitas Aplikasi: Aplikasi Anda memerlukan izin untuk membaca konfigurasi tombol dari layanan SaaS Config. Berikan peran `roles/saasconfig.viewer` ke identitas yang akan digunakan aplikasi. Untuk panduan memulai ini menggunakan ADC secara lokal dengan akun pengguna Anda, berikan peran ke alamat email Anda: 
        gcloud projects add-iam-policy-binding PROJECT_ID \
        --member="user:YOUR_EMAIL_ADDRESS" \
        --role="roles/saasconfig.viewer"
     Ganti PROJECT_ID dengan Google Cloud project ID Anda dan YOUR_EMAIL_ADDRESS dengan email yang terkait dengan login CLI Anda.

Membuat resource App Lifecycle Manager minimal

Meskipun kita tidak men-deploy infrastruktur dengan App Lifecycle Manager, kita memerlukan beberapa resource untuk mengatur, menargetkan, dan mendistribusikan tombol kita dengan aman. Resource ini mewakili komponen aplikasi yang ada dalam App Lifecycle Manager.

  1. Menentukan variabel: Tetapkan variabel lingkungan untuk nama dan lokasi resource.

    export PROJECT_ID="your-project-id"
export SAAS_OFFERING_ID="standalone-flags-saas"
export UNIT_KIND_ID="standalone-app-kind"
export UNIT_ID="my-app-instance-01"
export LOCATION_1="us-central1" # Example region where your app instance conceptually resides
# Add more locations if your app components span multiple regions
# export LOCATION_2="europe-west1"

  2. Membuat penawaran SaaS: Tindakan ini berfungsi sebagai container tingkat atas untuk konfigurasi layanan Anda, termasuk tombol.

    gcloud beta app-lifecycle-manager saas create ${SAAS_OFFERING_ID} \
    --project=${PROJECT_ID} \
    --location=global \
    --locations=name=${LOCATION_1} # Add --locations=name=${LOCATION_2} if using more regions

 gcloud beta app-lifecycle-manager saas create ${SAAS_OFFERING_ID} \
    --project=${PROJECT_ID} \
    --location=${LOCATION_1} \
    --locations=name=${LOCATION_1}

  3. Membuat jenis unit: Tindakan ini menentukan jenis komponen yang Anda modelkan. Yang terpenting, kami tidak menyediakan cetak biru karena kami tidak mengelola infrastruktur.

    gcloud beta app-lifecycle-manager unit-kinds create ${UNIT_KIND_ID} \
  --project=${PROJECT_ID} \
  --location=global \
  --saas=${SAAS_OFFERING_ID}

gcloud beta app-lifecycle-manager unit-kinds create ${UNIT_KIND_ID} \
  --project=${PROJECT_ID} \
  --location=${LOCATION_1} \
  --saas=${SAAS_OFFERING_ID}

  4. Membuat unit: Tindakan ini mewakili instance tertentu dari aplikasi Anda.

    gcloud beta app-lifecycle-manager units create ${UNIT_ID} \
  --project=${PROJECT_ID} \
  --unit-kind=${UNIT_KIND_ID} \
  --location=${LOCATION_1}

Menentukan dan meluncurkan tombol fitur

Sekarang, buat tombol fitur yang sebenarnya dan gunakan mekanisme peluncuran App Lifecycle Manager untuk membuat konfigurasinya tersedia bagi unit yang Anda buat.

  1. Menentukan variabel tombol:

    export FLAG_ID="standalone-flag-01"
export FLAG_KEY="enable-beta-feature"

  2. Membuat resource, revisi, dan rilis tombol:

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

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

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

  3. Membuat jenis peluncuran: Tentukan strategi untuk mendistribusikan perubahan tombol.

    export ROLLOUT_KIND_ID="standalone-flags-rollout-kind"

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

  4. Membuat peluncuran: Mulai proses distribusi.

    export ROLLOUT_ID_1="${FLAG_ID}-rollout1"

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

  5. Memantau peluncuran: Pastikan deployment berhasil sebelum melanjutkan.

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

Mengonfigurasi infrastruktur mandiri

Dalam penyiapan mandiri, Anda mengelola hosting aplikasi sendiri (misalnya, Cloud Run atau GKE) dan menggunakan App Lifecycle Manager murni untuk sinkronisasi konfigurasi. Kode aplikasi tetap standar di seluruh deployment; kode ini hanya memerlukan variabel lingkungan FLAGD_SOURCE_PROVIDER_ID untuk ada saat runtime agar dapat terhubung ke Layanan Konfigurasi SaaS.

Anda dapat memetakan definisi unit App Lifecycle Manager ke dalam definisi deployment Terraform standar dengan meneruskan jalur yang dibuat sebagai variabel lingkungan.

  1. Menentukan infrastruktur Anda: Petakan jalur dalam template deployment Anda (misalnya, standalone.tf).

    variable "project_id" { type = string }
variable "region"     { type = string }
variable "unit_id"    { type = string }

resource "google_cloud_run_v2_service" "standalone_app" {
  name     = "my-standalone-service"
  location = var.region

  template {
    containers {
      image = "us-central1-docker.pkg.dev/my-project/my-repo/my-image:latest"

      env {
        name  = "FLAGD_SOURCE_PROVIDER_ID"
        value = "projects/${var.project_id}/locations/${var.region}/featureFlagsConfigs/${var.unit_id}"
      }
    }
  }
}

  2. Menentukan nilai variabel Anda: Berikan parameter unit konfigurasi dalam file variabel terkait (misalnya, terraform.tfvars).

    project_id = "PROJECT_ID"
region     = "LOCATION_1"
unit_id    = "UNIT_ID"

Mengintegrasikan dan menjalankan aplikasi contoh

Jalankan aplikasi Python contoh secara lokal untuk terhubung ke layanan tombol App Lifecycle Manager menggunakan konfigurasi unit yang dimodelkan.

  1. Membuat direktori dan file project:

    mkdir saas_flags_standalone_app
cd saas_flags_standalone_app

    Buat 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

    Instal dependensi:

    pip install -r requirements.txt

  2. Membuat app.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.contrib.provider.flagd import FlagdProvider
from openfeature.contrib.provider.flagd.config import ResolverType

app = Flask(__name__)

logging.basicConfig(stream=sys.stdout, level=logging.INFO,
                    format='%(asctime)s - %(levelname)s - %(message)s')
log = logging.getLogger(__name__)

FLAG_KEY = os.environ.get("FLAG_KEY", "enable-beta-feature")
DEFAULT_FLAG_VALUE = False 

# CRITICAL: Read the Unit resource name from environment variable.
# This identifies the application instance to the flag service.
provider_id = os.environ.get("FLAGD_SOURCE_PROVIDER_ID")
if not provider_id:
    log.critical("FATAL: FLAGD_SOURCE_PROVIDER_ID not set.")
    sys.exit("FLAGD_SOURCE_PROVIDER_ID not set")

log.info(f"Initializing OpenFeature provider for Unit: {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:
    credentials, detected_project_id = google.auth.default(
        scopes=["https://www.googleapis.com/auth/cloud-platform"] 
    )
    auth_req = google.auth.transport.requests.Request() 

    configservice_credentials = grpc.composite_channel_credentials(
        grpc.ssl_channel_credentials(), 
        grpc.metadata_call_credentials( 
            google.auth.transport.grpc.AuthMetadataPlugin(credentials, auth_req)
        ),
        grpc.metadata_call_credentials(
            add_x_goog_request_params_header(provider_id)
        )
    )

    provider = FlagdProvider(
        resolver_type=ResolverType.IN_PROCESS,    
        host="saasconfig.googleapis.com",         
        port=443,                                 
        sync_metadata_disabled=True,              
        provider_id=provider_id,                  
        channel_credentials=configservice_credentials 
    )

    api.set_provider(provider)
    client = api.get_client()

    time.sleep(5)

    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)
    sys.exit(f"Provider initialization failed: {e}")

@app.route('/')
def home():
    log.info(f"Request received for endpoint '/', evaluating flag: {FLAG_KEY}")
    try:
        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,
            "provider_id": provider_id 
        })
    except Exception as e:
        log.error(f"Error evaluating flag '{FLAG_KEY}': {e}", exc_info=True)
        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 web server on host 0.0.0.0 port {port}")
    app.run(host='0.0.0.0', port=port)

  3. Menjalankan aplikasi:

    export FLAGD_SOURCE_PROVIDER_ID="projects/${PROJECT_ID}/locations/${LOCATION_1}/featureFlagsConfigs/${UNIT_ID}"
python app.py

  4. Memverifikasi nilai tombol awal: Jalankan pemeriksaan terhadap endpoint lokal di terminal sekunder.

    curl http://localhost:8080

Memperbarui tombol dan mendistribusikan perubahan

Ubah status runtime definisi tombol dan distribusikan update ke target yang terhubung.

  1. Memperbarui resource tombol:

    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}

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

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

  2. Membuat peluncuran baru untuk update:

    export ROLLOUT_ID_2="${FLAG_ID}-rollout2"

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

  3. Memantau peluncuran baru:

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

  4. Memverifikasi perubahan dalam aplikasi yang berjalan:

    curl http://localhost:8080

Pembersihan

Agar akunAnda tidak dikenai biaya untuk resource yang digunakan pada halaman ini, ikuti langkah-langkah berikut. Google Cloud

  1. Tekan Ctrl+C di terminal tempat app.py berjalan untuk menghentikan aplikasi Python lokal.
  2. Tetapkan status tombol.
  3. Buat peluncuran baru untuk menghapus tombol yang tidak digunakan lagi.

  4. Setelah peluncuran selesai dan tombol yang tidak digunakan lagi telah dihapus, hapus resource App Lifecycle Manager:

    gcloud beta app-lifecycle-manager rollouts delete ${ROLLOUT_ID_1} --project=${PROJECT_ID} --location=global --quiet 
gcloud beta app-lifecycle-manager rollouts delete ${ROLLOUT_ID_2} --project=${PROJECT_ID} --location=global --quiet 
gcloud beta app-lifecycle-manager rollout-kinds delete ${ROLLOUT_KIND_ID} --project=${PROJECT_ID} --location=global --quiet 
gcloud beta app-lifecycle-manager flags releases delete ${FLAG_RELEASE_ID_1} --project=${PROJECT_ID} --location=global --quiet 
gcloud beta app-lifecycle-manager flags releases delete ${FLAG_RELEASE_ID_2} --project=${PROJECT_ID} --location=global --quiet 
gcloud beta app-lifecycle-manager flags delete ${FLAG_ID} --project=${PROJECT_ID} --location=global --quiet 
gcloud beta app-lifecycle-manager units delete ${UNIT_ID} --project=${PROJECT_ID} --location=${LOCATION_1} --quiet 
gcloud beta app-lifecycle-manager unit-kinds delete ${UNIT_KIND_ID} --project=${PROJECT_ID} --location=global --quiet 
gcloud beta app-lifecycle-manager unit-kinds delete ${UNIT_KIND_ID} --project=${PROJECT_ID} --location=${LOCATION_1} --quiet 
gcloud beta app-lifecycle-manager saas delete ${SAAS_OFFERING_ID} --project=${PROJECT_ID} --location=global --quiet 
gcloud beta app-lifecycle-manager saas delete ${SAAS_OFFERING_ID} --project=${PROJECT_ID} --location=${LOCATION_1} --quiet

  5. Hapus direktori lokal:

    cd ..
rm -rf saas_flags_standalone_app

Langkah berikutnya