Usar flags de recursos do App Lifecycle Manager com Java

Este guia explica como integrar seus aplicativos Java com flags de recursos do App Lifecycle Manager. Você vai aprender a usar o SDK OpenFeature com o provedor flagd para avaliar flags gerenciadas pelo App Lifecycle Manager, permitindo controlar dinamicamente a disponibilidade de recursos e o comportamento nos seus serviços Java.

Este guia pressupõe que você já configurou os recursos necessários do App Lifecycle Manager (como ofertas de SaaS, tipos de unidades, unidades, flags e lançamentos) ao concluir um dos seguintes quickstarts:

Pré-requisitos

Antes de começar, verifique se você tem o seguinte:

  1. Java instalado:JDK 17 ou mais recente.
  2. Conclua um guia de início rápido de flags de recursos do App Lifecycle Manager:
    • Conclua com sucesso o guia de início rápido das flags de recurso integradas ou autônomas para provisionar sua unidade de destino.
    • Você precisa ter variáveis de ambiente ou valores desse início rápido, como PROJECT_ID, LOCATION_1 (a região da sua unidade), UNIT_ID e FLAG_KEY.

  3. gcloud autenticado para Application Default Credentials (ADC): o aplicativo Java usa o ADC para autenticar com os serviços do Google Cloud . Verifique se você fez a autenticação no seu ambiente:

    gcloud auth application-default login

  4. Permissões do IAM:a identidade que executa seu aplicativo Java precisa da função roles/saasconfig.viewer do Identity and Access Management no projeto Google Cloud para ler as configurações de flag:

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

    Substitua YOUR_PROJECT_ID e YOUR_EMAIL_ADDRESS de acordo com a situação.

Entender as principais variáveis de ambiente

Seu aplicativo Java depende de variáveis de ambiente para se conectar à configuração de flag correta.

  • FLAGD_SOURCE_PROVIDER_ID: especifica qual configuração de flag de recurso buscar no serviço do App Lifecycle Manager. Ele precisa ser o nome completo do recurso do FeatureFlagConfig associado à sua unidade.
    • Formato: projects/PROJECT_ID/locations/LOCATION/featureFlagsConfigs/UNIT_ID
    • Exemplo: projects/my-gcp-project/locations/us-central1/featureFlagsConfigs/my-app-instance-01

Configurar o projeto Java

Antes de executar o aplicativo, é preciso inicializar o projeto e configurar as dependências necessárias.

  1. Crie um diretório de projeto:

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

  2. Adicionar dependências:configure seu sistema de build (Maven ou Gradle) para incluir as seguintes bibliotecas. Para garantir a compatibilidade, use versões mais recentes que OpenFeature 1.14.1, flagd 0.11.5 e 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. Crie o código de inicialização:adicione um arquivo chamado FeatureManagement.java com o seguinte conteúdo. Essa classe configura interceptadores gRPC para anexar cabeçalhos de roteamento regional e ADC e inicializa o FlagdProvider usando a resolução no processo.

    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. Crie a lógica do aplicativo:adicione um arquivo chamado Main.java com o conteúdo a seguir para executar a avaliação de flag.

    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...");
    }

    }
}

Executar o aplicativo Java

É possível executar o aplicativo localmente usando sua configuração independente ou implantado como um contêiner.

Executar independente (localmente)

  1. Defina variáveis de ambiente:

    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. Execute o aplicativo:execute o projeto usando o comando da ferramenta de build de sua preferência (por exemplo, mvn compile exec:java ou ./gradlew run).

Executar integrado (em contêiner)

  1. Crie um Dockerfile:defina um build de contêiner que empacote o binário 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. Crie e envie a imagem:

    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. Implante o serviço:atualize o blueprint da unidade para referenciar gcr.io/${PROJECT_ID}/my-java-app:latest e implante a nova versão usando um lançamento do App Lifecycle Manager.

Verificar mudanças de flag

Depois que o aplicativo estiver em execução, confirme se ele avalia as flags corretamente.

  1. Observe o valor inicial:verifique se a saída do console registra o valor avaliado correspondente ao estado inicial da configuração.
  2. Atualize a flag no App Lifecycle Manager:modifique o payload da flag ou as regras de segmentação usando o console Google Cloud ou gcloud.
  3. Verifique o valor atualizado:execute novamente a execução local ou observe os registros do contêiner para confirmar o novo estado avaliado.

A seguir