שימוש בדגלי תכונות של App Lifecycle Manager עם Java

במדריך הזה מוסבר איך לשלב את אפליקציות Java עם ה-feature flags של App Lifecycle Manager. תלמדו איך להשתמש ב-OpenFeature SDK עם הספק flagd כדי להעריך דגלים שמנוהלים על ידי App Lifecycle Manager, וכך לשלוט באופן דינמי בזמינות ובהתנהגות של תכונות בשירותי Java שלכם.

במדריך הזה אנחנו יוצאים מנקודת הנחה שכבר הגדרתם את המשאבים הנדרשים של App Lifecycle Manager (כמו הצעות לאפליקציות, סוגי יחידות, יחידות, דגלים והשקות) על ידי השלמת אחד מהמדריכים למתחילים הבאים:

דרישות מוקדמות

לפני שמתחילים, חשוב לוודא שהתנאים הבאים מתקיימים:

  1. Java מותקן: JDK 17 ואילך.
  2. השלמתם את המדריך למתחילים בנושא Feature flags ב-App Lifecycle Manager:
    • השלמתם בהצלחה את ההגדרה של יחידת היעד באמצעות המדריך למתחילים בנושא דגלים של תכונות משולבות או עצמאיות.
    • אמורים להיות לכם משתני סביבה או ערכים מהמדריך למתחילים, כמו PROJECT_ID,‏ LOCATION_1 (האזור של היחידה), UNIT_ID ו-FLAG_KEY.

  3. אימות של gcloud ל-Application Default Credentials ‏ (ADC): אפליקציית Java משתמשת ב-ADC כדי לאמת את שירותי Google Cloud . מוודאים שביצעתם אימות בסביבה שלכם:

    gcloud auth application-default login

  4. הרשאות IAM: הזהות שמריצה את אפליקציית Java צריכה את התפקיד roles/saasconfig.viewer בניהול הזהויות והרשאות הגישה (IAM) בפרויקט Google Cloud כדי לקרוא הגדרות של דגלים:

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
    --member="user:YOUR_EMAIL_ADDRESS" \
    --role="roles/saasconfig.viewer"

    מחליפים את YOUR_PROJECT_ID ואת YOUR_EMAIL_ADDRESS בהתאם.

הסבר על משתני סביבה מרכזיים

אפליקציית Java מסתמכת על משתני סביבה כדי להתחבר להגדרת הדגל הנכונה.

  • ‫FLAGD_SOURCE_PROVIDER_ID: מציין איזו הגדרה של feature flag צריך לאחזר משירות App Lifecycle Manager. הוא צריך להיות שם המשאב המלא של FeatureFlagConfig שמשויך ליחידה שלכם.
    • פורמט: projects/PROJECT_ID/locations/LOCATION/featureFlagsConfigs/UNIT_ID
    • לדוגמה: projects/my-gcp-project/locations/us-central1/featureFlagsConfigs/my-app-instance-01

הגדרת פרויקט Java

כדי להריץ את האפליקציה, צריך להפעיל את הפרויקט ולהגדיר את יחסי התלות הנדרשים.

  1. יוצרים ספריית פרויקט:

    mkdir java-featureflag-app
cd java-featureflag-app

  2. הוספת יחסי תלות: מגדירים את מערכת ה-build ‏ (Maven או Gradle) כך שתכלול את הספריות הבאות. כדי להבטיח תאימות, צריך להשתמש בגרסאות חדשות יותר מ-OpenFeature 1.14.1, ‏flagd 0.11.5 ו-gRPC 1.71.0.

    • dev.openfeature:javasdk:1.14.1+
    • dev.openfeature.contrib.providers:flagd:0.11.5+
    • io.grpc:grpc-netty-shaded:1.71.0+
    • io.grpc:grpc-auth:1.71.0+
    • com.google.auth:google-auth-library-oauth2-http

  3. יוצרים את קוד האתחול: מוסיפים קובץ בשם FeatureManagement.java עם התוכן הבא. המחלקות האלה מגדירות מיירטי gRPC כדי לצרף כותרות של ADC וניתוב אזורי, ומבצעות אתחול של FlagdProvider באמצעות רזולוציה בתוך התהליך.

    import com.google.auth.oauth2.GoogleCredentials;
import dev.openfeature.contrib.providers.flagd.Config;
import dev.openfeature.contrib.providers.flagd.FlagdOptions;
import dev.openfeature.contrib.providers.flagd.FlagdProvider;
import dev.openfeature.sdk.OpenFeatureAPI;
import io.grpc.*;
import io.grpc.auth.MoreCallCredentials;
import java.util.ArrayList;
import java.util.List;

public class FeatureManagement {
    public static void initialize() throws Exception {
        // Read the full Unit resource name
        String flagConfigId = System.getenv("FLAGD_SOURCE_PROVIDER_ID");
        if (flagConfigId == null || flagConfigId.isEmpty()) {
            throw new IllegalStateException("FLAGD_SOURCE_PROVIDER_ID environment variable is not set.");
        }

        // Configure gRPC Security and Routing
        GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
        CallCredentials callCredentials = MoreCallCredentials.from(credentials);

        List<ClientInterceptor> interceptors = new ArrayList<>();

        // Interceptor to inject the Unit name into headers for regional routing
        interceptors.add(new ClientInterceptor() {
            @Override
            public <ReqT, RespT> ClientCall<ReqT, RespT> interceptCall(MethodDescriptor<ReqT, RespT> method, CallOptions callOptions, Channel next) {
                return new ForwardingClientCall.SimpleForwardingClientCall<ReqT, RespT>(next.newCall(method, callOptions)) {
                    @Override
                    public void start(Listener<RespT> responseListener, Metadata headers) {
                        headers.put(Metadata.Key.of("x-goog-request-params", Metadata.ASCII_STRING_MARSHALLER), "name=" + flagConfigId);
                        super.start(responseListener, headers);
                    }
                };
            }
        });

        // Interceptor to attach ADC to the gRPC calls
        interceptors.add(new ClientInterceptor() {
            @Override
            public <ReqT, RespT> ClientCall<ReqT, RespT> interceptCall(MethodDescriptor<ReqT, RespT> method, CallOptions callOptions, Channel next) {
                return next.newCall(method, callOptions.withCallCredentials(callCredentials));
            }
        });

        // Initialize the flagd provider with In-Process resolution
        FlagdProvider provider = new FlagdProvider(
            FlagdOptions.builder()
                .resolverType(Config.Resolver.IN_PROCESS)
                .host("saasconfig.googleapis.com").port(443)
                .tls(true)
                .providerId(flagConfigId)
                .clientInterceptors(interceptors)
                .syncMetadataDisabled(true)
                .deadline(10000)
                .build()
        );

        // Set the global provider
        OpenFeatureAPI.getInstance().setProviderAndWait(provider);
    }
}

  4. יוצרים את הלוגיקה של האפליקציה: מוסיפים קובץ בשם Main.java עם התוכן הבא כדי להריץ את הערכת ההגדרה.

    import dev.openfeature.sdk.OpenFeatureAPI;
import dev.openfeature.sdk.MutableContext;

public class Main {
    public static void main(String[] args) throws Exception {

    // 1. Get Client
    var client = OpenFeatureAPI.getInstance().getClient("simple-api");

    // 2. Create Evaluation Context 
    var context = new dev.openfeature.sdk.MutableContext();

    // 3. Evaluate Flag
    // Default to false if evaluation fails or service is unreachable
    boolean isEnhanced = client.getBooleanValue("enhanced-search", false, context);

    // 4. Execute business logic based on result
    if (isEnhanced) {
        System.out.println("Executing enhanced search algorithm...");
    } else {
        System.out.println("Standard search algorithm...");
    }

    }
}

הפעלת אפליקציית Java

אתם יכולים להריץ את האפליקציה באופן מקומי באמצעות ההגדרות העצמאיות, או לפרוס אותה כקונטיינר.

הרצה באופן עצמאי (מקומית)

  1. הגדרה של משתני סביבה:

    export PROJECT_ID="your-gcp-project-id"
export LOCATION_1="us-central1"
export UNIT_ID="my-app-instance-01"
export FLAGD_SOURCE_PROVIDER_ID="projects/${PROJECT_ID}/locations/${LOCATION_1}/featureFlagsConfigs/${UNIT_ID}"

  2. מריצים את האפליקציה: מריצים את הפרויקט באמצעות פקודת כלי ה-build המועדפת (למשל, mvn compile exec:java או ./gradlew run).

הפעלה משולבת (בקונטיינרים)

  1. יוצרים קובץ Dockerfile: מגדירים את ה-build של הקונטיינר שכולל את הקובץ הבינארי של Java.

    FROM maven:3.9-eclipse-temurin-17 AS builder
WORKDIR /app
COPY pom.xml .
COPY src ./src
RUN mvn clean package

FROM eclipse-temurin:17-jre
WORKDIR /app
COPY --from=builder /app/target/java-featureflag-app.jar app.jar
ENTRYPOINT ["java", "-jar", "app.jar"]

  2. יוצרים את קובץ האימג' ושולחים אותו:

    export PROJECT_ID="your-gcp-project-id"
docker build -t gcr.io/${PROJECT_ID}/my-java-app:latest .
docker push gcr.io/${PROJECT_ID}/my-java-app:latest

  3. פריסת השירות: מעדכנים את תוכנית היחידה כך שתפנה אל gcr.io/${PROJECT_ID}/my-java-app:latest ופורסים את הגרסה החדשה באמצעות השקה של App Lifecycle Manager.

אימות השינויים בדגלים

אחרי שהאפליקציה פועלת, צריך לוודא שהיא מעריכה את ה-flags בצורה נכונה.

  1. בודקים את הערך הראשוני: מוודאים שערך ההערכה שמתאים למצב ההגדרה הראשוני מתועד בפלט של המסוף.
  2. עדכון הדגל ב-App Lifecycle Manager: משנים את מטען הדגל או את כללי הטירגוט באמצעות Google Cloud console או gcloud.
  3. מאמתים את הערך המעודכן: מריצים מחדש את ההפעלה המקומית או בודקים את יומני הקונטיינר כדי לאשר את המצב החדש שהוערך.

המאמרים הבאים