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 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
- Una suscripción a Azure: cree una cuenta gratuita.
- Kit de desarrollo de Java (JDK) versión 8 o posterior.
- Apache Maven
- CLI de Azure
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-config
de 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.19.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 versión de spring-cloud-azure-dependencies
en 4.19.0
.
Para obtener más información sobre la versión que se usa para esta lista de materiales, consulte Qué versión de Spring Cloud Azure debo usar.
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_STRING
es 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>
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 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.
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
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 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. 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.
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 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.
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.
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 enfalse
. 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 laenabled-for
propiedad . En este caso,feature-u
tiene un filtro de características denominadoRandom
, que no requiere ninguna configuración, por lo que solo se requiere la propiedad name.feature-v
especifica un filtro de características denominadoTimeWindowFilter
. Este filtro de características se puede 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 comotrue
. Elevaluate
campo se usa para detener la evaluación de los filtros de características y da como resultado que el filtro de características devuelvafalse
siempre .
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 false en , devuelve isEnabled 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 DisabledFeaturesHandler
de , 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 , FeatureManagementSnapshot
que 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
. FeatureFilterEvaluationContext
tiene 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":
- A los usuarios individuales, Jeff y Alicia se les concede acceso a la versión Beta.
- Otro usuario, Mark, pide participar y está incluido.
- El veinte por ciento de un grupo conocido como "Ring1" se incluye en la versión Beta.
- El número de usuarios "Ring1" incluidos en la versión beta aumenta hasta el 100 %.
- El cinco por ciento de la base de usuarios se incluye en la versión beta.
- 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 @Bean
elementos 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
, h
y 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
Automatizados
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 AppConfigurationRefresh
mé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 refresh
refresh-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 | null |
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
, h
y 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ó enfalse
.
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 ConfigurationClientCustomizer
SecretClientCustomizer
, 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 ConfigurationClientBuilder
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 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();
}
}