Compatibilidad con la configuración de aplicaciones

En este artículo se describe la biblioteca de configuración de Spring Cloud App de Azure. Esta biblioteca carga las configuraciones y las marcas de características desde el servicio Azure App Configuration. La biblioteca genera PropertySource abstracciones para que coincidan con las abstracciones ya generadas por el entorno de Spring, como variables de entorno, configuraciones de línea de comandos, archivos de configuración local, etc.

Spring es un marco de trabajo de aplicaciones de código abierto desarrollado por VMware que ofrece un método modular simplificado para crear aplicaciones Java. Spring Cloud Azure es un proyecto de código abierto que proporciona una integración perfecta de Spring con los servicios de Azure.

Requisitos previos

• Una suscripción de Azure: cree una gratuitamente.
• Java Development Kit (JDK) versión 8 o posterior.
• Apache Maven
• Azure CLI

Configuración del almacén de App Configuration

Use el comando siguiente para crear el almacén de configuración de App de Azure:

az appconfig create \
    --resource-group <your-resource-group> \
    --name <name-of-your-new-store> \
    --sku Standard

Este comando crea un almacén de configuración nuevo y vacío. Puede cargar las configuraciones mediante el siguiente comando de importación:

az appconfig kv import \
    --name <name-of-your-new-store> \
    --source file \
    --path <location-of-your-properties-file> \
    --format properties \
    --prefix /application/

Confirme las configuraciones antes de cargarlas. Puede cargar archivos YAML cambiando el formato a YAML. El campo de prefijo es importante porque es el prefijo predeterminado cargado por la biblioteca cliente.

Uso de la biblioteca

Para usar la característica en una aplicación, puede compilarla como una aplicación de Spring Boot. La manera más cómoda de agregar la dependencia es con el iniciador com.azure.spring:spring-cloud-azure-starter-appconfiguration-configde Spring Boot. En el ejemplo siguiente pom.xml archivo se usa Azure App Configuration:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>{spring-boot-version}</version>
    <relativePath />
</parent>

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.azure.spring</groupId>
      <artifactId>spring-cloud-azure-dependencies</artifactId>
      <version>6.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.azure.spring</groupId>
        <artifactId>spring-cloud-azure-starter-appconfiguration-config</artifactId>
    </dependency>
</dependencies>
<build>
    <plugins>
           <plugin>
               <groupId>org.springframework.boot</groupId>
               <artifactId>spring-boot-maven-plugin</artifactId>
           </plugin>
    </plugins>
</build>

En el ejemplo siguiente se muestra una aplicación básica de Spring Boot mediante App Configuration:

@SpringBootApplication
@RestController
public class Application {

    @RequestMapping("/")
    public String home() {
        return "Hello World!";
    }

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

En este ejemplo, el archivo application.properties contiene la siguiente línea:

spring.config.import=azureAppConfiguration
spring.cloud.azure.appconfiguration.stores[0].endpoint=${CONFIG_STORE_ENDPOINT}

CONFIG_STORE_ENDPOINT es una variable de entorno con la dirección URL del punto de conexión al Almacén de Azure App Configuration.

Nota:

Microsoft recomienda usar el flujo de autenticación más seguro disponible. El flujo de autenticación descrito en este procedimiento, como para bases de datos, memorias caché, mensajería o servicios de inteligencia artificial, requiere un grado de confianza muy alto en la aplicación y conlleva riesgos que no están presentes en otros flujos. Use este flujo solo cuando las opciones más seguras, como las identidades administradas para conexiones sin contraseña o sin claves, no sean viables. En el caso de las operaciones de máquina local, prefiera identidades de usuario para conexiones sin contraseña o sin claves.

De forma predeterminada, si no se establecen configuraciones, las configuraciones que comienzan por /application/ se cargan con una etiqueta predeterminada de (No Label). Sin embargo, si se establece un perfil de Spring, la etiqueta predeterminada es su perfil de Spring.

Se crea un origen de propiedad denominado /application/https://<name-of-your-store>.azconfig.io/ que contiene las propiedades de ese almacén. La etiqueta usada en la solicitud se anexa al final del nombre. Si no se establece ninguna etiqueta, el carácter \0 está presente como un espacio vacío.

Cargando configuración

La biblioteca admite la carga de uno o varios almacenes de App Configuration. En la situación en la que se duplica una clave en varias tiendas, la última gana.

spring.cloud.azure.appconfiguration.stores[0].endpoint=[first-store-endpoint]
spring.cloud.azure.appconfiguration.stores[1].endpoint=[second-store-endpoint]

En este ejemplo, si ambos almacenes tienen la misma clave de configuración, la configuración del segundo almacén tiene la prioridad más alta.

Nota:

Puede usar las configuraciones de Azure App Configuration como cualquier otra configuración de Spring. Para más información, consulte Características principales en la documentación de Spring Boot o Inicio rápido: Creación de una aplicación de Java Spring con Azure App Configuration.

Selección de configuraciones

La biblioteca carga las configuraciones mediante su clave y etiqueta. De forma predeterminada, se cargan las configuraciones que comienzan por la clave /application/ . La etiqueta predeterminada es \0, que aparece como (No Label) en Azure Portal. Si se establece un perfil de Spring y no se proporciona ninguna etiqueta, la etiqueta predeterminada es spring Profile, que es ${spring.profiles.active}.

Puede configurar qué configuraciones se cargan seleccionando diferentes filtros de clave y etiqueta:

spring.cloud.azure.appconfiguration.stores[0].selects[0].key-filter=[my-key]
spring.cloud.azure.appconfiguration.stores[0].selects[0].label-filter=[my-label]

La key-filter propiedad admite los siguientes filtros:

Filtro de clave	Efecto
*	Coincide con cualquier clave.
abc	Coincide con una clave denominada abc.
abc*	Coincide con los nombres de clave que empiezan por abc.
abc,xyz	Coincide con los nombres clave abc o xyz. Limitado a cinco valores separados por comas.

La label-filter propiedad admite los siguientes filtros:

Etiqueta	Descripción
*	Coincide con cualquier etiqueta, incluido \0.
\0	Coincide con las etiquetas null, que aparecen como (No Label) en el portal de Azure.
1.0.0	Coincide exactamente con la etiqueta 1.0.0.
1.0.*	Coincide con las etiquetas que empiezan por 1.0.*.
,1.0.0	Coincide con las etiquetas null y 1.0.0. Limitado a cinco valores separados por comas.

Si usa YAML con filtros de etiqueta y quiere cargar configuraciones sin etiqueta y más configuraciones con otras etiquetas, debe incluir un vacío ,. Por ejemplo, ,dev coincide con \0 y dev. En este caso, rodea el filtro de etiqueta con comillas simples. Este valor permite cargar primero la configuración sin etiqueta, seguida de configuraciones con etiquetas específicas, en el mismo filtro:

spring:
  cloud:
    azure:
      appconfiguration:
        stores:
        - selects:
          - label-filter: ',1.0.0'

Nota:

No se puede combinar * con , en filtros. En ese caso, debe utilizar un valor de selección adicional.

Cuando se usa * en el filtro de etiqueta y se cargan varias configuraciones con la misma clave, se cargan en orden alfabético y se usa la etiqueta en orden alfabético.

Perfiles de Spring

De forma predeterminada, spring.profiles.active se establece como valor predeterminado label-filter para todas las configuraciones seleccionadas. Puede invalidar esta funcionalidad mediante label-filter. Puede usar los perfiles de Spring en label-filter mediante ${spring.profiles.active}, como se muestra en el ejemplo siguiente:

spring.cloud.azure.appconfiguration.stores[0].selects[0].label-filter=,${spring.profiles.active}
spring.cloud.azure.appconfiguration.stores[0].selects[1].label-filter=${spring.profiles.active}_local

En el primer label-filter, la biblioteca carga primero todas las configuraciones con la \0 etiqueta, seguidas de todas las configuraciones que coinciden con los perfiles de Spring. Los perfiles de Spring tienen prioridad sobre las \0 configuraciones, ya que están al final.

En el segundo label-filter, la cadena _local se anexa al final de Los perfiles de Spring, aunque solo al último perfil de Spring si hay más de uno.

Almacenes deshabilitados

Con la configuración spring.cloud.azure.appconfiguration.enabled, puede deshabilitar la carga de todos los almacenes de configuración. Con la spring.cloud.azure.appconfiguration.stores[0].enabled configuración, puede deshabilitar un almacén individual.

Nota:

Si usa métricas de salud, verá los almacenes enumerados, pero con el valor NOT LOADED. Cuando compruebas los orígenes de propiedades cargados, aún los ves enumerados, pero no contienen valores. Este comportamiento se debe a que se establece la spring.config.import propiedad . Si azureAppConfiguration no se establece para spring.config.import, no se muestran valores.

Autenticación

La biblioteca admite todas las formas de identidad admitidas por la biblioteca de identidades de Azure. Puede realizar la autenticación a través de la configuración de cadena de conexión e identidad administrada.

Nota:

Microsoft recomienda usar el flujo de autenticación más seguro disponible. El flujo de autenticación descrito en este procedimiento, como para bases de datos, memorias caché, mensajería o servicios de inteligencia artificial, requiere un grado de confianza muy alto en la aplicación y conlleva riesgos que no están presentes en otros flujos. Use este flujo solo cuando las opciones más seguras, como las identidades administradas para conexiones sin contraseña o sin claves, no sean viables. En el caso de las operaciones de máquina local, prefiera identidades de usuario para conexiones sin contraseña o sin claves.

Cadena de conexión (no recomendada)

La autenticación a través de la cadena de conexión es el formulario más sencillo de configurar, aunque no se recomienda. Puede acceder a los cadena de conexión de una tienda mediante el comando siguiente:

az appconfig credential list --name <name-of-your-store>

A continuación, puede establecer la propiedad spring.cloud.azure.appconfiguration.stores[0].connection-string a la cadena de conexión. Al usar este enfoque, se recomienda encarecidamente establecer la cadena de conexión en el archivo de configuración local en un valor de marcador de posición que se asigne a una variable de entorno. Este enfoque le permite evitar agregar la cadena de conexión al control de código fuente.

Configuración de Spring Cloud Azure

Puede usar la configuración de Azure de Spring Cloud para configurar la biblioteca. Puede usar las siguientes propiedades para configurar la biblioteca:

spring.cloud.azure.appconfiguration.stores[0].endpoint= <URI-of-your-configuration-store>

Cuando solo se establece el punto de conexión, la biblioteca cliente usa DefaultAzureCredential para autenticarse.

Debe asignar la identidad que se usa para leer las configuraciones. Puede crear esta asignación mediante el comando siguiente:

az role assignment create \
    --role "App Configuration Data Reader" \
    --assignee <your-client-ID> \
    --scope /subscriptions/<your-subscription>/resourceGroups/<your-stores-resource-group>/providers/Microsoft.AppConfiguration/configurationStores/<name-of-your-configuration-store>

Nota:

Solo puede definir un método de autenticación por punto de conexión: cadena de conexión, identidad asignada por el usuario o credenciales de token. Si necesita mezclar y hacer coincidir, puede usar ConfigurationClientCustomizer para modificar para ConfigurationClientBuilder usar diferentes métodos.

Nota:

Microsoft recomienda usar el flujo de autenticación más seguro disponible. El flujo de autenticación descrito en este procedimiento, como para bases de datos, memorias caché, mensajería o servicios de inteligencia artificial, requiere un grado de confianza muy alto en la aplicación y conlleva riesgos que no están presentes en otros flujos. Use este flujo solo cuando las opciones más seguras, como las identidades administradas para conexiones sin contraseña o sin claves, no sean viables. En el caso de las operaciones de máquina local, prefiera identidades de usuario para conexiones sin contraseña o sin claves.

Replicación geográfica

La biblioteca admite la característica de replicación geográfica de Azure App Configuration. Esta característica le permite replicar los datos en otras ubicaciones. Esta característica es útil para la alta disponibilidad y la recuperación ante desastres.

Cada réplica que cree tiene un punto de conexión dedicado. Si la aplicación reside en varias geolocalizaciones, puede actualizar cada implementación de la aplicación en una ubicación para conectarse a la réplica más cercana a esa ubicación, lo que ayuda a minimizar la latencia de red entre la aplicación y App Configuration. Dado que cada réplica tiene su cuota de solicitudes independiente, esta configuración también ayuda a la escalabilidad de la aplicación mientras crece a un servicio distribuido de varias regiones.

De forma predeterminada, la biblioteca detecta automáticamente todas las réplicas que existen para un almacén de configuración. Cuando se realiza una solicitud al almacén proporcionado y se produce un error, la biblioteca reintenta automáticamente la solicitud en las réplicas disponibles.

La conmutación por error puede producirse si la biblioteca observa alguna de las condiciones siguientes:

• Recibe respuestas con código de estado de servicio no disponible (HTTP 500 o superior) de un endpoint.
• Experimenta problemas de conectividad de red.
• Las solicitudes se limitan (código de estado HTTP 429).

Una vez que la tienda proporcionada vuelva a estar en línea, la biblioteca reintenta automáticamente la solicitud en el almacén proporcionado.

Si desea controlar el comportamiento de conmutación por error, puede proporcionar manualmente una lista de almacenes que se usarán para la conmutación por error.

spring.cloud.azure.appconfiguration.stores[0].endpoints[0]=[your primary store endpoint]
spring.cloud.azure.appconfiguration.stores[0].endpoints[1]=[your replica store endpoint]

o

spring.cloud.azure.appconfiguration.stores[0].connection-strings[0]=[your primary store connection string]
spring.cloud.azure.appconfiguration.stores[0].connection-strings[1]=[your replica store connection string]

Si se produce un error en todos los puntos de conexión de réplica proporcionados, la biblioteca intenta conectarse a réplicas detectadas automáticamente del almacén principal.

Puede deshabilitar la replicación con la configuración spring.cloud.azure.appconfiguration.stores[0].replica-discovery-enabled=false.

Creación de un almacén de configuración con replicación geográfica

Para crear una réplica del almacén de configuración, puede usar la CLI de Azure o Azure Portal. En el ejemplo siguiente se usa la CLI de Azure para crear una réplica en la región Este de EE. UU. 2:

az appconfig replica create --location --name --store-name [--resource-group]

Valores clave

Azure App Configuration admite varios tipos de valores de clave, algunos de los cuales tienen características especiales incorporadas. Azure App Configuration tiene compatibilidad integrada con el tipo de contenido JSON, los marcadores de posición de Spring y las referencias de Key Vault.

Marcadores de posición

La biblioteca admite configuraciones con marcadores de posición de entorno de ${}estilo. Al hacer referencia a una clave de Azure App Configuration con un marcador de posición, quite los prefijos de la referencia. Por ejemplo, /application/config.message se hace referencia a como ${config.message}.

Nota:

El prefijo que se quita coincide con el valor spring.cloud.azure.appconfiguration.stores[0].selects[0].key-filter. El prefijo que se recorta se puede cambiar estableciendo un valor para spring.cloud.azure.appconfiguration.stores[0].trim-key-prefix[0].

JSON

Las configuraciones que tienen un tipo application/json de contenido se procesan como objetos JSON. Esta característica permite asignar una configuración a un objeto complejo dentro de .@ConfigurationProperties Por ejemplo, considere la clave /application/config.colors JSON con el siguiente valor:

{
 "Red": {
  "value": [255, 0, 0]
 },
 "Blue": {
  "value": [0, 255, 0]
 },
 "Green": {
  "value": [0, 0, 255]
 }
}

Esta clave se asigna al código siguiente:

@ConfigurationProperties(prefix = "config")
public class MyConfigurations {

    private Map<String, Color> colors;

}

Referencias de Key Vault

Azure App Configuration y sus bibliotecas soportan hacer referencia a los secretos almacenados en Key Vault. En App Configuration, puede crear claves con valores que se asignan a secretos almacenados en un almacén de claves. Los secretos permanecen seguros en Key Vault, pero puede acceder a ellos de la misma manera que cualquier otra configuración al cargar la aplicación.

La aplicación usa el proveedor de cliente para recuperar las referencias de Key Vault, igual que para cualquier otra clave almacenada en App Configuration. Dado que el cliente reconoce las claves como referencias de Key Vault, estas tienen un tipo de contenido único y el cliente se conecta a Key Vault para recuperar sus valores para usted.

Nota:

Key Vault solo permite recuperar secretos uno por uno, por lo que cada referencia de Key Vault almacenada en App Configuration resulta en una solicitud a Key Vault.

Creación de referencias de Key Vault

Para crear una referencia de Key Vault en Azure Portal, vaya al Explorador de configuración>Crear>referencia de Key Vault. A continuación, puede seleccionar un secreto al que hacer referencia desde cualquiera de los almacenes de claves a los que tiene acceso. También puede crear referencias arbitrarias de Key Vault desde la pestaña Entrada . En Azure Portal, escriba un URI válido.

También puede crear una referencia de Key Vault a través de la CLI de Azure mediante el comando siguiente:

az appconfig kv set-keyvault \
    --name <name-of-your-store> \
    --key <key-name> \
    --secret-identifier <URI-to-your-secret>

Puede crear cualquier identificador secreto a través de la CLI de Azure. Los identificadores secretos solo requieren el formato {vault}/{collection}/{name}/{version?} en el que la sección de versión es opcional.

Usar referencias de almacén de claves

Puede usar la configuración de Azure de Spring Cloud para configurar la biblioteca. Puede usar la misma credencial que se usa para conectarse a App Configuration para conectarse a Azure Key Vault.

También puede crear de SecretClientCustomizer la misma manera que crearía para ConfigurationClientCustomizer proporcionar su propio método de autenticación.

Resolución de secretos que no son de Key Vault

La biblioteca de App Configuration proporciona un método para invalidar la resolución de referencias del almacén de claves. Por ejemplo, puede usarlo para resolver localmente secretos en un entorno de desarrollo. Esta resolución se realiza a través de KeyVaultSecretProvider. Si KeyVaultSecretProviderse proporciona, se llama a en todas las referencias del almacén de claves. Si getSecret devuelve un valor distinto de null, se usa como valor secreto. De lo contrario, la referencia de Key Vault se resuelve normalmente.

public class MySecretProvider implements KeyVaultSecretProvider {

    @Override
    public String getSecret(String uri) {
        ...
    }

}

Administración de características

La administración de características proporciona una manera de que las aplicaciones de Spring Boot accedan dinámicamente al contenido. La administración de características tiene varias funciones, como las siguientes:

• Marcas de características que pueden habilitar o deshabilitar contenido
• Filtros de características para el destino cuando se muestra el contenido
• Filtros de características personalizados
• Puertas de características para habilitar de forma dinámica los puntos de conexión

Puede habilitar las banderas de funciones a través de la siguiente configuración:

spring.cloud.azure.appconfiguration.stores[0].feature-flags.enabled= true

Las marcas de características habilitadas se cargan en el sistema de configuración de Spring con el prefijo feature-management. También puede registrar marcas de características en el archivo de configuración local. Para obtener más información, consulte la sección Declaración de bandera de características.

La manera más fácil de usar la administración de características es usar las spring-cloud-azure-feature-management bibliotecas y spring-cloud-azure-feature-management-web . La diferencia entre las dos bibliotecas es que spring-cloud-azure-feature-management-web toma una dependencia de las spring-web bibliotecas y spring-webmvc para agregar más características, como puertas de características.

De forma predeterminada, todas las marcas de características con una \0 etiqueta, que se ven como (No Label), se cargan. Puede configurar las marcas de características que se cargan estableciendo un filtro de etiqueta, como se muestra en el ejemplo siguiente:

spring.cloud.azure.appconfiguration.stores[0].feature-flags.selects[0].key-filter=A*
spring.cloud.azure.appconfiguration.stores[0].feature-flags.selects[0].label-filter= dev

Conceptos básicos de administración de características

Marcas de características

Las marcas de características se componen de varias partes, incluido un nombre y una lista de filtros de características que se usan para activar la característica. Las marcas de características pueden tener un estado booleano de activado o desactivado, o bien pueden tener una lista de filtros de características. Las banderas de características evalúan los filtros de características hasta que uno devuelve true. Si ningún filtro de características devuelve true, la marca de característica devuelve false.

Filtros de características

Los filtros de características definen un escenario para cuando se debe habilitar una característica. Los filtros de características se evalúan de forma sincrónica.

La biblioteca de administración de características incluye cuatro filtros predefinidos: AlwaysOnFilter, PercentageFilter, TimeWindowFilter y TargetingFilter.

Puede crear filtros de características personalizados. Por ejemplo, puede usar un filtro de características para proporcionar una experiencia personalizada para los clientes que usan un explorador de Microsoft Edge. Puede personalizar las características de este filtro de características, por ejemplo, para mostrar un encabezado específico para la audiencia del explorador Microsoft Edge.

Declaración de la marca de características

La biblioteca de administración de características admite Azure App Configuration junto con application.yml o application.properties como orígenes para las marcas de características. Este es un ejemplo del formato usado para configurar marcas de características en un archivo application.yml :

feature-management:
  feature_flags:
  - id: feature-t
    enabled: false
  - id: feature-u
    conditions:
      client_filters:
      - name: Random
  - id: feature-v
    conditions:
      client_filters:
      - name: TimeWindowFilter
        parameters:
          Start: "Wed, 01 May 2019 13:59:59 GMT"
          End: "Mon, 01 July 2019 00:00:00 GMT"

  - id: feature-w
    evaluate: false
    conditions:
      client_filters:
      - name: AlwaysOnFilter

Este ejemplo tiene las marcas de características siguientes:

• El valor de feature-t está establecido en false. Esta configuración siempre devuelve el valor de la bandera de función.
• feature-u se usa con filtros de funciones. Estos filtros se definen en la enabled-for propiedad . En este caso, feature-u tiene un filtro de características denominado Random, que no requiere ninguna configuración, por lo que solo se requiere la propiedad name.
• feature-v especifica un filtro de características denominado TimeWindowFilter. A este filtro de características se le pueden pasar parámetros para usarlos como configuración. En este ejemplo, TimeWindowFilter pasa las horas de inicio y finalización durante las que la característica está activa.
• feature-w se usa para AlwaysOnFilter, que siempre se evalúa como true. El evaluate campo se usa para detener la evaluación de los filtros de características y da como resultado que el filtro de características devuelva falsesiempre .

Evaluación de marcas de características

La spring-cloud-azure-feature-management biblioteca proporciona FeatureManager para determinar si una marca de característica está habilitada. FeatureManager ofrece una forma asincrónica de comprobar el estado de la bandera.

spring-cloud-azure-feature-management-web, junto con proporcionar FeatureManager, contiene FeatureManagerSnapshot, que almacena en caché el estado de las marcas de características evaluadas previamente en @RequestScope para garantizar que todas las solicitudes devuelvan el mismo valor. Además, la biblioteca web proporciona @FeatureGate, que puede bloquear o redirigir solicitudes web a distintos puntos de conexión.

Comprobación de la marca de características

FeatureManager es un @Bean objeto que se puede insertar @Autowired o insertar en @Component objetos de tipo. FeatureManager tiene un método isEnabled que, cuando se pasa el nombre de una marca de característica, devuelve su estado.

@Autowired
FeatureManager featureManager;

...

if (featureManager.isEnabled("feature-t")) {
    // Do Something
}

Nota:

FeatureManager también tiene una versión asincrónica de isEnabled denominada isEnabledAsync.

Sin la configuración de administración de características o cuando la marca de característica no existe, isEnabled siempre devuelve false. Si una marca de característica existente está configurada con un filtro de características desconocido, se produce una FilterNotFoundException excepción. Puede cambiar este comportamiento para devolver false configurando fail-fast en false. En la tabla siguiente se describe fail-fast:

Nombre	Descripción	Obligatorio	Valor predeterminado
spring.cloud.azure.feature.management.fail-fast	Si se produce una excepción, se produce una RuntimeException excepción. Si esta propiedad se establece en false, entonces isEnabled devuelve false en su lugar.	No	true

La única diferencia entre FeatureManagerSnapshot y FeatureManager es el almacenamiento en caché de los resultados en .@RequestScope

Puerta de características

Con la biblioteca web de administración de características, puede requerir que una característica determinada esté habilitada para ejecutar un punto de conexión. Puede configurar este requisito mediante la @FeatureGate anotación , como se muestra en el ejemplo siguiente:

@GetMapping("/featureT")
@FeatureGate(feature = "feature-t")
@ResponseBody
public String featureT() {
    ...
}

Solo puede acceder al featureT punto de conexión si está habilitado "feature-t".

Control de acciones deshabilitado

Cuando se bloquea un punto de conexión porque la característica que especifica está deshabilitada, DisabledFeaturesHandler se invoca. De forma predeterminada, se devuelve un HTTP 404. Puede invalidar este comportamiento mediante la implementación de DisabledFeaturesHandler, como se muestra en el ejemplo siguiente:

@Component
public class MyDisabledFeaturesHandler implements DisabledFeaturesHandler {

    @Override
    public HttpServletResponse handleDisabledFeatures(HttpServletRequest request, HttpServletResponse response) {
        ...
        return response;
    }

}

Enrutamiento

Algunas rutas pueden exponer funcionalidades de aplicación que están controladas por características. Si una característica está deshabilitada, puede redirigir estas rutas a otro punto de conexión, como se muestra en el ejemplo siguiente:

@GetMapping("/featureT")
@FeatureGate(feature = "feature-t" fallback= "/oldEndpoint")
@ResponseBody
public String featureT() {
    ...
}

@GetMapping("/oldEndpoint")
@ResponseBody
public String oldEndpoint() {
    ...
}

Filtros de características integrados

Hay algunos filtros de características que vienen con el spring-cloud-azure-feature-management paquete. Estos filtros de características se agregan automáticamente.

AlwaysOnFilter

Este filtro siempre devuelve true. Para obtener un ejemplo de uso, consulte la sección declaración de marca de características.

Filtro de Porcentaje

Cada vez que se comprueba, la evaluación de PercentageFilter puede devolver un resultado diferente. Puede eludir esta incoherencia mediante , FeatureManagementSnapshotque almacena en caché el resultado de la marca de característica por solicitud.

feature-management:
  feature_flags:
  - name: feature-v
    conditions:
      client_filters:
      - name: PercentageFilter
        parameters:
          Value: 50

TimeWindowFilter

Este filtro proporciona la capacidad de habilitar una característica basada en un período de tiempo. Si especifica solo End, la característica se considera activa hasta ese momento. Si especifica solo Start, la característica se considera activada en todos los puntos después de ese momento. Si especifica ambos, la característica se considera válida entre las dos veces.

feature-management:
  feature_flags:
  - name: feature-v
    conditions:
      client_filters:
      - name: TimeWindowFilter
        parameters:
          Start: "Wed, 01 May 2019 13:59:59 GMT"
          End: "Mon, 01 July 2019 00:00:00 GMT"

Este filtro también admite filtros de período de tiempo periódicos. Admite periodicidades diarias y semanales, junto con una hora de expiración.

feature-management:
  feature_flags:
  - name: feature-v
    conditions:
      client_filters:
      - name: TimeWindowFilter
        parameters:
          Start: "Mon, 01 July 2019 00:00:00 GMT"
          End: "Mon, 01 July 2019 12:00:00 GMT"
          Recurrence:
            Pattern:
              Type: Weekly
              Interval: 1
              FirstDayOfWeek: Sunday
              DaysOfWeek:
              - Monday
              - Wednesday

Este patrón de periodicidad se produce cada semana el lunes y el miércoles de 00:00:00 GMT a 12:00:00 GMT y no expira.

feature-management:
  feature_flags:
  - name: feature-v
    conditions:
      client_filters:
      - name: TimeWindowFilter
        parameters:
          Start: "Mon, 01 July 2019 00:00:00 GMT"
          End: "Mon, 01 July 2019 12:00:00 GMT"
          Recurrence:
            Pattern:
              Type: Daily
              Interval: 2
            Range:
              Type: EndDate
              EndDate: "Fri, 15 Aug 2025 07:00:00 GMT"

Este patrón de periodicidad se produce cada otro día de 00:00:00 GMT a 12:00:00 GMT hasta la fecha de finalización.

TargetingFilter

Este filtro proporciona la capacidad de habilitar una característica para una audiencia de destino. Para obtener una explicación detallada de la segmentación, consulte la sección de selección de destino . Los parámetros de filtro incluyen un objeto de audiencia que describe usuarios, grupos y un porcentaje predeterminado de la base de usuarios que debe tener acceso a la característica. Para cada objeto de grupo que aparece en la audiencia de destino, se requiere un porcentaje que define el porcentaje de los miembros de ese grupo que tienen acceso a la característica. Un usuario tiene habilitada la característica en los casos siguientes:

• El usuario se especifica directamente en la sección de usuarios.
• El usuario se encuentra en el porcentaje incluido de cualquiera de los lanzamientos de grupo.
• El usuario entra en el porcentaje de lanzamiento predeterminado.

feature-management:
  feature_flags:
  - name: target
    conditions:
      client_filters:
      - name: targetingFilter
        parameters:
          users:
          - Jeff
          - Alicia
          groups:
          - name: Ring0
            rollout-percentage: 100
          - name: Ring1
            rolloutPercentage: 100
          default-rollout-percentage: 50

Filtros de características personalizados

La creación de un filtro de características personalizado proporciona una manera de habilitar las características en función de los criterios que defina. Para crear un filtro de características personalizado, debe implementar la FeatureFilter interfaz . FeatureFilter tiene un único método evaluate. Cuando una característica especifica que se puede habilitar con un filtro de características, se llama al evaluate método . Si evaluate devuelve true, significa que la característica debe estar habilitada. Si devuelve false, continúa evaluando los filtros de características hasta que uno devuelve true. Si todos los filtros devuelven false, la característica está desactivada.

Los filtros de características se definen como Spring Beans, por lo que se especifican como @Component o se definen en un @Configuration.

@Component("Random")
public class Random implements FeatureFilter {

    @Override
    public boolean evaluate(FeatureFilterEvaluationContext context) {
        double chance = Double.valueOf((String) context.getParameters().get("chance"));
        return Math.random() > chance / 100;
    }

}

Filtros de características con parámetros

Algunos filtros de características requieren parámetros para determinar si se debe activar una característica. Por ejemplo, un filtro de características del explorador podría activar una característica para un determinado conjunto de exploradores. Es posible que desee habilitar una característica para los exploradores Microsoft Edge y Chrome, pero no Firefox. Para configurar esta situación, puede diseñar un filtro de características para esperar parámetros. Estos parámetros se especificarían en la configuración de características y en el código, y serían accesibles a través del FeatureFilterEvaluationContext parámetro de evaluate. FeatureFilterEvaluationContext tiene una propiedad parameters, que es un Map<String, Object>.

Destinatarios

La segmentación es una estrategia de administración de funcionalidades que habilita a los desarrolladores implementar el lanzamiento progresivo de nuevas funcionalidades en la base de usuarios. La estrategia se basa en el concepto de dirigirse a un conjunto de usuarios conocidos como audiencia de destino. Un público se compone de usuarios, grupos y un porcentaje designado de toda la base de usuarios. Los grupos que se incluyen en la audiencia se pueden dividir más en porcentajes de sus miembros totales.

En los pasos siguientes se muestra un ejemplo de una implementación progresiva para una nueva característica "Beta":

1. A los usuarios individuales, Jeff y Alicia se les concede acceso a la versión Beta.
2. Otro usuario, Mark, pide participar y está incluido.
3. El veinte por ciento de un grupo conocido como "Ring1" está incluido en la Beta.
4. El número de usuarios "Ring1" incluidos en la versión beta aumenta hasta el 100 %.
5. El cinco por ciento de la base de usuarios se incluye en la versión beta.
6. El porcentaje de lanzamiento se aumenta hasta el 100 % y la característica se implementa por completo.

Esta estrategia para implementar una característica se integra en la biblioteca mediante el filtro de características incluido TargetingFilter .

Selección de destino en una aplicación

Una aplicación web de ejemplo que usa el filtro de características de destino está disponible en el proyecto de ejemplo.

Para empezar a usar TargetingFilter en una aplicación, debe agregarlo como un @Bean filtro de características similar a cualquier otro filtro de características. TargetingFilter se basa en otro @Bean que se va a agregar a la aplicación TargetingContextAccessor. Permite TargetingContextAccessor definir el objeto actual TargetingContext que se va a usar para definir el identificador de usuario y los grupos actuales, como se muestra en el ejemplo siguiente:

public class MyTargetingContextAccessor implements TargetingContextAccessor {

    @Override
    public void configureTargetingContext(TargetingContext context) {
        context.setUserId("Jeff");
        ArrayList<String> groups = new ArrayList<String>();
        groups.add("Ring0");
        context.setGroups(groups);
    }

}

Opciones de evaluación de destino

Las opciones están disponibles para personalizar cómo se realiza la evaluación de destino en todas las características.TargetingFilter Puede establecer un parámetro opcional, TargetingEvaluationOptions, durante la TargetingFilter creación.

    @Bean
    public TargetingFilter targetingFilter(MyTargetingContextAccessor contextAccessor) {
        return new TargetingFilter(contextAccessor, new TargetingEvaluationOptions().setIgnoreCase(true));
    }

Actualización de configuración

La habilitación de la actualización de configuración para las configuraciones le permite extraer sus valores más recientes del almacén o almacenes de App Configuration sin tener que reiniciar la aplicación.

Para habilitar la actualización, debe habilitar la supervisión junto con desencadenadores de supervisión. Un desencadenador de supervisión es una clave con una etiqueta opcional que el sistema supervisa los cambios de valor para desencadenar actualizaciones. El valor del desencadenador de supervisión puede ser cualquier valor, siempre que cambie cuando se necesite una actualización.

Nota:

Cualquier operación que cambie la ETag de un desencadenador de supervisión provoca una actualización, como un cambio de tipo de contenido.

spring:
  cloud:
    azure:
      appconfiguration:
        stores:
        - monitoring:
          enabled: true
          triggers:
          - key: [my-watched-key]
            label: [my-watched-label]

Para desencadenar una actualización de configuración, cambie el valor de una clave en el almacén de configuración. A continuación, actualice una de las claves de monitoreo a un nuevo valor. Este cambio desencadena la creación de un registro. Por ejemplo, cambiar el valor de /application/config.message desencadena el siguiente mensaje de registro:

INFO 17496 --- [TaskScheduler-1] o.s.c.e.event.RefreshEventListener       : Refresh keys changed: [config.message]

Después de que la aplicación genere el registro, actualiza todos los @Beanelementos del ámbito de actualización.

Nota:

De forma predeterminada, @ConfigurationProperties los frijoles anotados se incluyen en este ámbito.

Actualización basada en extracción

Las bibliotecas spring de App Configuration admiten la capacidad de comprobar periódicamente un intervalo de actualización para los cambios realizados en los desencadenadores de supervisión. De forma predeterminada, el intervalo de actualización se establece en 30 segundos. Una vez que se supera el intervalo de actualización, cuando se realiza un intento de actualización, todos los desencadenadores se comprueban en el almacén determinado para ver los cambios. Cualquier cambio en la clave hace que se desencadene una actualización. Dado que las bibliotecas se integran con el sistema spring refresh, cualquier actualización vuelve a cargar todas las configuraciones de todos los almacenes. Puede establecer el intervalo de actualización en cualquier intervalo superior a 1 segundo. Las unidades admitidas para el intervalo de actualización son s, m, hy d durante segundos, minutos, horas y días, respectivamente. En el ejemplo siguiente se establece el intervalo de actualización en 5 minutos:

spring.cloud.azure.appconfiguration.stores[0].monitoring.refresh-interval= 5m

Automatizado

Cuando se usa la spring-cloud-azure-appconfiguration-config-web biblioteca, la aplicación comprueba automáticamente si hay una actualización cada vez que se produce una solicitud de servlet, específicamente ServletRequestHandledEvent. La forma más común de enviar este evento es mediante solicitudes a los puntos de conexión en un @RestController.

Manual de instrucciones

En las aplicaciones que usan solo spring-cloud-azure-appconfiguration-config, como las aplicaciones de consola, puede desencadenar manualmente una actualización llamando al AppConfigurationRefreshmétodo de refreshConfiguration . AppConfigurationRefresh es un @Bean que puedes inyectar en cualquier @Component.

Además, dado que la biblioteca usa el sistema de configuración de Spring, el desencadenamiento de una actualización provoca una actualización de todas las configuraciones, no solo una recarga de las de su almacén de Azure App Configuration.

Actualización basada en push (no recomendada)

Nota:

Este método ya no se recomienda, pero todavía se admite.

Puede configurar la biblioteca para recibir notificaciones push desde el spring-cloud-azure-appconfiguration-config-web almacén de Azure App Configuration para actualizar los valores de configuración. Puede configurar esta configuración a través de un webhook de Azure Event Grid, que puede configurar para enviar notificaciones de cambios a las claves especificadas. Al agregar la biblioteca Spring Actuator como una dependencia, puede exponer los endpoints de actualización de App Configuration. Hay dos puntos de conexión diferentes: appconfiguration-refresh y appconfiguration-refresh-bus. Estos endpoints funcionan de forma similar a sus homólogos refresh y refresh-bus, donde los endpoints de configuración de la aplicación permiten que el intervalo de actualización expire en lugar de forzar una actualización al momento de recibir. Todavía puede usar refresh y refresh-bus, pero no puede conectarlos directamente a Azure Event Grid mediante un Web Hook porque requieren una respuesta durante el proceso de configuración.

La appconfiguration-refresh propiedad termina el intervalo de actualización, por lo que no se espera el intervalo de actualización restante antes de la siguiente verificación de actualización. La appconfiguration-refresh-bus propiedad envía una notificación a un servicio de mensajería conectado, como Azure Service Bus, para notificar a todas las instancias de una aplicación que se actualicen. En ambos casos, no expira completamente en el intervalo de actualización, pero está desactivado por una pequeña cantidad de vibración. Esta fluctuación garantiza que cada instancia de su aplicación no intente refrescar al mismo tiempo.

management.endpoints.web.exposure.include= appconfiguration-refresh, appconfiguration-refresh-bus

Además de exponer los puntos de conexión de actualización, la biblioteca requiere un parámetro de consulta para la seguridad. No existe ningún nombre o valor de token de forma predeterminada, pero debe establecer uno para usar los puntos de conexión, como se muestra en el ejemplo siguiente:

spring.cloud.azure.appconfiguration.stores[0].monitoring.push-notification.primary-token.name=[primary-token-name]
spring.cloud.azure.appconfiguration.stores[0].monitoring.push-notification.primary-token.secret=[primary-token-secret]
spring.cloud.azure.appconfiguration.stores[0].monitoring.push-notification.secondary-token.name=[secondary-token-name]
spring.cloud.azure.appconfiguration.stores[0].monitoring.push-notification.secondary-token.secret=[secondary-token-secret]

Configuración de webhooks

Para configurar un webhook, abra el almacén de Azure App Configuration y abra Eventos en el menú de navegación. A continuación, seleccione Suscripción de eventos. Establezca el nombre del evento y seleccione el tipo de punto de conexión que va a ser Web Hook. Al seleccionar Web Hook, aparecerá una opción Punto de conexión . Seleccione Seleccionar un punto de conexión. El punto de conexión debe tener un aspecto similar al del ejemplo siguiente: https://www.myaplication.com/actuator/appconfiguration-refresh?myTokenName=mySecret.

Confirmar la Selección envía una notificación de configuración al URI dado y espera una respuesta. Si no se devuelve ninguna respuesta, se produce un error en el programa de instalación. La configuración de la biblioteca azure-spring-cloud-appconfiguration-web para los endpoints devuelve la respuesta correcta si el almacén de configuración de aplicaciones de Azure está configurado para la aplicación. Esta confirmación se puede enviar de otras maneras. Para obtener más información sobre la entrega de webhook, consulte Entrega de eventos de webhook.

Nota:

Esta validación solo se produce tras la creación o modificación del punto de conexión.

Se recomienda encarecidamente configurar filtros porque, de lo contrario, se desencadena una actualización después de cada creación y modificación de claves.

Actualización forzada del cliente

Puede configurar la biblioteca para forzar una actualización de todas las configuraciones en un intervalo de actualización. En la tabla siguiente se describe la refresh-interval propiedad :

Nombre	Descripción	Obligatorio	Valor predeterminado
spring.cloud.azure.appconfiguration.refresh-interval	Cantidad de tiempo estándar entre actualizaciones. Es una Duration.	No	nulo

La actualización con spring.cloud.azure.appconfiguration.refresh-interval no comprueba ninguna clave de inspección configurada. Esta propiedad se usa para garantizar que los secretos de Key Vault se mantengan actualizados, ya que Azure App Configuration no puede detectar cuándo se actualizan.

Dado que Azure Key Vault almacena el par de claves pública y privada de un certificado como secreto, la aplicación puede recuperar cualquier certificado como referencia de Key Vault en App Configuration. Dado que los certificados deben rotarse periódicamente, las aplicaciones cliente deben actualizarse con tanta frecuencia, lo que se puede hacer mediante el intervalo de actualización del cliente.

Actualización de marcas de características

Si las marcas de características y la supervisión están habilitadas, de forma predeterminada, el intervalo de actualización de las marcas de características se establece en 30 segundos. Cuando finaliza el intervalo de actualización, el sistema comprueba todas las marcas de características del almacén determinado para ver los cambios. Cualquier cambio en la clave hace que se desencadene una actualización. Dado que las bibliotecas se integran con el sistema spring refresh, cualquier actualización vuelve a cargar todas las configuraciones de todos los almacenes. Puede establecer el intervalo de actualización en cualquier intervalo superior a 1 segundo. Las unidades admitidas para el intervalo de actualización son s, m, hy d durante segundos, minutos, horas y días, respectivamente. En el ejemplo siguiente se establece el intervalo de actualización en 5 minutos:

spring.cloud.azure.appconfiguration.stores[0].monitoring.feature-flag-refresh-interval= 5m

Indicador de salud

La biblioteca cliente incluye un indicador de estado que comprueba si la conexión con uno o varios almacenes de configuración de aplicaciones de Azure es saludable. Si está habilitado para cada almacén, proporciona uno de los siguientes valores de estado:

• UP: la última conexión se realizó correctamente.
• DOWN: la última conexión produjo un código de error distinto de 200. Este estado podría deberse a problemas que van desde la expiración de credenciales hasta un problema de servicio. La biblioteca cliente vuelve a intentar conectarse automáticamente a la tienda en el siguiente intervalo de refresco.
• NOT LOADED: el almacén de configuración aparece en el archivo de configuración local, pero el almacén de configuración no se cargó desde el archivo al inicio. El almacén de configuración está deshabilitado en el archivo de configuración o la configuración o las configuraciones no se pudieron cargar al iniciarse mientras la fail-fast configuración del almacén se estableció en false.

Puede habilitar el indicador de salud estableciendo management.health.azure-app-configuration.enabled=true.

Personalización del cliente

La biblioteca de App Configuration usa el SDK de Azure para Java para conectarse a Azure App Configuration y Azure Key Vault. Se proporcionan dos interfaces, ConfigurationClientCustomizer y SecretClientCustomizer, para modificar los clientes. Cada interfaz tiene un método customize que toma su respectivo generador junto con el valor String del URI para el cual se está configurando el cliente, como se muestra en las siguientes definiciones de interfaz.

public interface ConfigurationClientCustomizer {
    public void customize(ConfigurationClientBuilder builder, String endpoint);
}

public interface SecretClientCustomizer {
    public void customize(SecretClientBuilder builder, String endpoint);
}

Estas interfaces permiten personalizar el cliente HTTP y sus configuraciones. En el ejemplo siguiente se reemplaza el valor predeterminado HttpClient por otro que usa un proxy para todo el tráfico dirigido a App Configuration y Key Vault.

Nota:

Los ConfigurationClientBuilder y SecretClientBuilder ya están configurados para su uso cuando se pasan a customize. Los cambios realizados en los clientes, incluidas las credenciales y la directiva de reintento, invalidan los valores predeterminados ya implementados.

También puede realizar esta configuración mediante la configuración de Spring Cloud Azure.

public class CustomClient implements ConfigurationClientCustomizer, SecretClientCustomizer {

    @Override
    public void customize(ConfigurationClientBuilder builder, String endpoint) {
        builder.httpClient(buildHttpClient());
    }

    @Override
    public void customize(SecretClientBuilder builder, String endpoint) {
        builder.httpClient(buildHttpClient());
    }

    private HttpClient buildHttpClient() {
        String hostname = System.getProperty("https.proxyHosts");
        String portString = System.getProperty("https.proxyPort");
        int port = Integer.valueOf(portString);

        ProxyOptions proxyOptions = new ProxyOptions(ProxyOptions.Type.HTTP,
                new InetSocketAddress(hostname, port));
        return new NettyAsyncHttpClientBuilder()
                .proxy(proxyOptions)
                .build();
    }

}