Share via

Compatibilidad con la configuración de aplicaciones

  • Artículo

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 del servicio de configuración de App de Azure. 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

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 App de Azure 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>5.12.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>

Nota:

Si usa Spring Boot 2.x, asegúrese de establecer la spring-cloud-azure-dependencies versión 4.18.0en . Para obtener más información sobre la versión que se usa para esta lista de materiales, consulte La versión de Spring Cloud que se debe usar en Azure.

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 bootstrap.properties contiene la siguiente línea:

spring.cloud.azure.appconfiguration.stores[0].connection-string=${CONFIG_STORE_CONNECTION_STRING}

CONFIG_STORE_CONNECTION_STRINGes una variable de entorno con el cadena de conexión al almacén de configuración de App de Azure. Puede acceder al cadena de conexión mediante el comando siguiente:

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

De forma predeterminada, si no se establecen configuraciones, las configuraciones que comienzan por /application/ se cargan con una etiqueta predeterminada de a menos que se establezca un perfil de (No Label) Spring, en cuyo caso la etiqueta predeterminada es el perfil de Spring. Dado que el almacén está vacío, no se cargan configuraciones, pero todavía se genera el origen de la propiedad de configuración de App de Azure.

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.

Carga de la 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 varios almacenes, la carga de todos los almacenes da como resultado la configuración de almacenes de mayor prioridad que se carga. El último gana. Este proceso se muestra en el ejemplo siguiente:

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

En el ejemplo, si los almacenes primero y segundo tienen la misma configuración, la configuración del segundo almacén tiene la prioridad más alta y la última gana.

Nota:

Puede usar App de Azure opciones de configuración como cualquier otra configuración de Spring. Para obtener 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 App de Azure Configuración.

Selección de configuraciones

Las configuraciones se cargan mediante su clave y etiqueta. De forma predeterminada, se cargan las configuraciones que comienzan por la clave /application/ . La etiqueta predeterminada es ${spring.profiles.active}. Si ${spring.profiles.active} no se establece, se cargan las configuraciones con la null etiqueta. La null etiqueta aparece como (No Label) en Azure Portal.

Puede configurar las configuraciones que se cargan seleccionando diferentes filtros de clave y etiqueta, como se muestra en el ejemplo siguiente:

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 null las etiquetas, que aparecen como (No Label) en Azure Portal.
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 necesita empezar con null, el filtro de etiqueta debe estar rodeado de comillas simples, como se muestra en el ejemplo siguiente:

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

Nota:

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

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, todas las configuraciones con la null etiqueta se cargan, seguidas de todas las configuraciones que coinciden con los perfiles de Spring. Los perfiles de Spring tienen prioridad sobre las null 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.

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.

Además de deshabilitar las tiendas, puede configurar las tiendas para que se deshabilite si no se cargan. Para esta configuración, use spring.cloud.azure.appconfiguration.stores[0].fail-fast. Cuando fail-fast está deshabilitado estableciendo en false, se RuntimeException deshabilita el almacén de aplicaciones sin configuraciones de que se cargue. Si un almacén de configuración está deshabilitado al iniciarse, no se comprueba si hay cambios tras la actualización. Además, no hay ningún intento de cargar valores desde él si se actualizan las configuraciones.

Si se produce RuntimeException un error durante una comprobación de actualización o al intentar volver a cargar las configuraciones, el intento de actualización finaliza y se reintenta después refresh-interval de que se haya superado.

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.

Cadena de conexión

La autenticación a través de cadena de conexión es la forma más sencilla de configurar. 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 spring.cloud.azure.appconfiguration.stores[0].connection-string propiedad en el cadena de conexión. Se recomienda encarecidamente establecer el 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 el cadena de conexión al control de código fuente.

Configuración de Azure de Spring Cloud

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. DefaultAzureCredential Usa los métodos siguientes para autenticarse:

  • Credenciales de entorno
  • Credencial de identidad administrada
  • Credencial de la CLI para desarrolladores de Azure
  • Credencial de IntelliJ
  • Credencial de la CLI de Azure
  • Credencial de Azure PowerShell

Debe asignar una identidad como una identidad asignada por el sistema para leer 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 buscar coincidencias, puede usar ConfigurationClientCustomizer para modificar almacenes que usan un método diferente.

Replicación geográfica

La biblioteca admite la característica de replicación geográfica de App de Azure Configuración. 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.

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

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

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]

Uso de la réplica del almacén de configuración

Después de crear una réplica, puede usarla en la aplicación. Al igual que el almacén de origen, puede conectarse a la réplica mediante el identificador de Microsoft Entra o un cadena de conexión.

Para usar microsoft Entra ID para conectarse a la réplica, debe enumerar las endpoints instancias del almacén de configuración, como se muestra en el ejemplo siguiente:

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

Puede enumerar tantos puntos de conexión como tenga réplicas. La biblioteca intenta conectarse a los puntos de conexión en el orden en que se muestran. Si la biblioteca no puede conectarse a una réplica, intenta la siguiente de la lista. Una vez transcurrido un período de tiempo, la biblioteca intenta volver a conectarse a los puntos de conexión preferidos.

Valores clave

App de Azure Configuration admite varios tipos de valores clave, algunos de los cuales tienen características especiales integradas. App de Azure Configuration tiene compatibilidad integrada con el tipo de contenido JSON, los marcadores de posición 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 configuración de App de Azure 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.

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

App de Azure Configuración y sus bibliotecas admiten la referencia a 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 se almacenan de forma segura en Key Vault, pero se puede acceder al mismo modo que cualquier otra configuración después de cargarse.

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, tienen un tipo de contenido único y el cliente se conecta a Key Vault para recuperar sus valores automáticamente.

Nota:

Key Vault solo permite recuperar secretos de uno en uno, por lo que cada referencia de Key Vault almacenada en App Configuration da como resultado una extracción en 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 Creación>de 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.

Resolución de secretos que no son de Key Vault

La biblioteca de App Configuration proporciona un método para resolver localmente los secretos que no tienen un almacén de claves asociado a ellos. Esta resolución se realiza a través de .KeyVaultSecretProvider KeyVaultSecretProvider Se llama cuando no se proporciona una TokenCredential referencia de Key Vault. Se proporciona el URI de la referencia de Key Vault y el valor devuelto se convierte en el valor del secreto.

Advertencia

El uso de invalida KeyVaultSecretProvider el uso automático de la identidad administrada asignada por el sistema. Para usar ambos, debe usar KeyVaultCredentialProvider y devolver null los URI que necesitan resolver.

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 marcas de características 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 marcas 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.

Puede habilitar las marcas de características mediante filtros de clave/etiqueta. De forma predeterminada, se asigna una null etiqueta, como (No Label), . 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ística

Las marcas de características se componen de dos partes: 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/desactivado, o bien pueden tener una lista de filtros de características. Las marcas de características evalúan los filtros de características hasta que una 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 App de Azure Configuración junto con application.yml o bootstrap.yml 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-t: false
  feature-u:
    enabled-for:
    - name: Random
  feature-v:
    enabled-for:
    - name: TimeWindowFilter
      parameters:
        Start: "Wed, 01 May 2019 13:59:59 GMT"
        End: "Mon, 01 July 2019 00:00:00 GMT"
  feature-w:
    evaluate: false
    enabled-for:
    - 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 marca de característica.
  • feature-u se usa con filtros de características. 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. Este filtro de características se puede pasar parámetros para usarlos como configuración. En este ejemplo, , TimeWindowFilterpasa las horas de inicio y finalización durante las que la característica está activa.
  • feature-w se usa para , AlwaysOnFilterque 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 proporciona una manera asincrónica de comprobar el estado de la marca.

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:

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

Si no ha configurado la administración de características o 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 Necesario 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 falseen , devuelve isEnabledfalse 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 DisabledFeaturesHandlerde , 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 no se agregan automáticamente, pero puede configurarlos en .@Configuration

AlwaysOnFilter

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

PercentageFilter

Cada vez que un usuario realiza una solicitud, 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ísticas por usuario. Esta funcionalidad garantiza que un usuario tenga una experiencia coherente, incluso si tiene que volver a enviar la solicitud.

feature-management:
  feature-v:
    enabled-for:
    - 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 en todos los puntos después de ese tiempo. Si especifica ambos, la característica se considera válida entre las dos veces.

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

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: 
  target:
    enabled-for:
    - 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 definen como @Component o se definen en .@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 puede 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. FeatureFilterEvaluationContexttiene una propiedad parameters, que es .HashMap<String, Object>

Selección de destino

El destino es una estrategia de administración de características que habilita a los desarrolladores implementar progresivamente nuevas características en su 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 que opte por participar y se incluya.
  3. El veinte por ciento de un grupo conocido como "Ring1" se incluye en la versión 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 getContextAsync(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 un determinado 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 se comprueba si hay 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 inspección a un nuevo valor. Este cambio desencadena la creación de un registro. Por ejemplo, al cambiar el valor de desencadena el siguiente mensaje de /application/config.message 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 ha superado el intervalo 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 de .@RestController

Manual

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 objeto que se puede insertar 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 configuración de App de Azure.

Actualización basada en inserción

Puede configurar la spring-cloud-azure-appconfiguration-config-web biblioteca para recibir notificaciones push del almacén de configuración de App de Azure 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 puntos de conexión de actualización de App Configuration. Hay dos puntos de conexión diferentes: appconfiguration-refresh y appconfiguration-refresh-bus. Estos puntos de conexión funcionan de forma similar a sus homólogos refresh y refresh-bus, donde los puntos de conexión de configuración de la aplicación expiran el intervalo de actualización en lugar de forzar una actualización al recibir. Todavía puede usar y refreshrefresh-bus, pero no puede conectarlos directamente a Azure Event Grid con un Web Hook porque requieren una respuesta en la configuración.

La appconfiguration-refresh propiedad expira el intervalo de actualización, por lo que no se espera el intervalo de actualización restante antes de la siguiente comprobació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. Este vibración garantiza que cada instancia de la aplicación no intente actualizar 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, se ha agregado un parámetro de consulta necesario para la seguridad. No se establece ningún nombre o valor de token de forma predeterminada, pero se requiere 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 configuración de App de Azure 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 Select an endpoint (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.

Confirme que Selection envía una notificación de configuración al URI especificado y espera una respuesta. Si no se devuelve ninguna respuesta, se produce un error en el programa de instalación. La azure-spring-cloud-appconfiguration-web configuración de biblioteca para los puntos de conexión devuelve la respuesta correcta si el almacén de configuración de App 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 Necesario Valor predeterminado
spring.cloud.azure.appconfiguration.refresh-interval Cantidad de tiempo estándar entre actualizaciones. Es .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 asegurarse de que los secretos de Key Vault se mantienen actualizados porque App de Azure Configuración no puede saber 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. Una vez transcurrido el intervalo de actualización, todas las marcas de características 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.feature-flag-refresh-interval= 5m

Indicador de mantenimiento

La biblioteca cliente incluye un indicador de estado que comprueba si la conexión con el almacén o almacenes de configuración de App de Azure es correcto. 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 reintenta automáticamente para conectarse al almacén en el siguiente intervalo de actualización.
  • 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 mantenimiento 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 App de Azure Configuration y Azure Key Vault. Se proporcionan dos interfaces y ConfigurationClientCustomizerSecretClientCustomizer, para modificar los clientes. Cada interfaz tiene un customize método que toma su respectivo generador junto con el valor del URI para el String que se configura el cliente, como se muestra en las siguientes definiciones de interfaz:

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

public interface SecretClientCustomizer {
    public void setup(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:

y ConfigurationClientBuilderSecretClientBuilder 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 las que ya están en vigor.

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

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();
    }

}