Configuración avanzada de servicios y componentes

Esta sección describe la configuración técnica avanzada de los distintos servicios y componentes que conforman Anjana Data Platform. Está dirigida a administradores y equipos técnicos responsables del mantenimiento y la operación del entorno, una vez la plataforma ha sido instalada mediante Ansible o Kubernetes.

El objetivo de esta guía es proporcionar las directrices necesarias para ajustar el comportamiento de los microservicios y módulos de Anjana, abarcando aspectos como:

• Activación de perfiles y configuraciones específicas (spring.profiles.active).

• Gestión de secretos y credenciales en Vaults y Secret Managers cloud (AWS, Azure, GCP).

• Configuración de logs, rendimiento y balanceo de carga.

• Integración con sistemas externos (autenticación, notificaciones, licencias).

• Administración de los plugins TOT y parámetros de Horus.

Uso de perfiles

Cualquiera de los servicios de Anjana puede iniciarse utilizando diferentes perfiles. Esta práctica es especialmente útil cuando se necesita ejecutar una configuración específica en momentos determinados, como cambios en el perfilado de logs o ajustes en variables que impactan el rendimiento. En la siguiente sección, se explicará cómo habilitar diferentes perfiles en diversas tecnologías; por lo tanto, ahora nos enfocaremos en cómo utilizar esos perfiles.

Por defecto, Anjana Data se configura para ejecutar el perfil 'default', el cual incluye los valores predeterminados proporcionados por Anjana. Estos valores son generalmente suficientes, a menos que se requieran configuraciones específicas de conexiones. Esta configuración se puede observar en el descriptor de servicio de cualquiera de los artefactos, donde se incluye el argumento --spring.profiles.active=default.

Es posible modificar este perfil o combinarlo con otros, utilizando una coma para separarlos, como en --spring.profiles.active=default,perfil1,perfil2. Además, se pueden ejecutar perfiles que se complementen entre sí. Es importante tener en cuenta que el orden de los perfiles configurados influye en el resultado: el último perfil especificado "gana". En caso de que existan propiedades con valores diferentes en cada perfil, se aplicará el valor del último perfil que las configure.

Distribución de configuración

Anjana puede ser configurada de diferentes modos e incluso cada servicio puede ser configurado de una manera diferente por su arquitectura de microservicios, aunque por practicidad se recomienda utilizar el mismo mecanismo para todos ellos.

Se puede configurar mediante:

• Horus como repositorio centralizado de configuración que puede leer configuraciones de diferentes puntos como un repositorio Git, base de datos (tabla app_configuration del esquema de base de datos portuno), HashiCorp's Vault, AWS Secret Manager o del sistema de archivos en el que se aloja Horus. (Esta es la opción recomendada y por defecto).

• Otra forma de configuración es utilizar en cada servicio un repositorio de claves Vault (AWS Secret manager, GCP Secret Manager o Azure Key Vault).

• La última forma de configuración es con un YAML accesible directamente desde el servicio que se quiere configurar; esta forma habilita el uso de variables de entorno en la misma máquina.

Los métodos anteriormente descritos pueden ser usados en combinación, por ejemplo utilizar Vault para la configuración de credenciales, la tabla app_configuration para configuración de Anjana y un yaml para configurar el nivel de logs.

📝Nota:

• Si se usa Horus Vault tiene que ser mediante Horus.

⚠️Recomendación:

Teniendo en cuenta que la gran parte de configuración técnica corresponde a conexiones y credenciales se recomienda, por seguridad, priorizar el uso de repositorios Vault.

YAML directo

Para que un servicio pueda usar un YAML directamente se tiene que configurar el descriptor de servicio para que incluya el siguiente argumento:

--spring.config.additional-location=<path a directorio de fichero de propiedades>

Este argumento acepta ficheros concretos o directorios. Si se elige un fichero concreto, este sobrescribirá todos los valores por defecto, dejando sin valor toda configuración que no se incluya en este fichero; por ello se recomienda utilizar directorio, acabando en / la ruta elegida.

El nombre del fichero o ficheros tiene que seguir el siguiente formato: application-<profile>.yaml. El uso de perfiles se explica en el apartado anterior.

Horus como repositorio centralizado

Horus es el único que no puede usar otro Horus para proporcionar configuración, así que para este servicio hay que elegir una de las otras dos opciones, o ambas.

Horus acepta varios tipos de repositorios para proporcionar como ya se ha comentado, pero además acepta configurar varios a la vez. Para ello se deberá establecer un orden mediante la propiedad spring.cloud.config.server.<repositorio>.order y poner un orden numérico a cada uno.

Cada servicio que vaya a hacer uso de Horus tiene que tener el siguiente argumento configurado en su descriptor de servicio: --spring.config.import=optional:configserver:http://<host de Horus>:9999/config

A continuación se detalla cómo configurar cada repositorio.

Repositorio Filesystem

Solo es necesario ajustar la carpeta donde se encuentran los ficheros de configuración de los microservicios de Anjana, es el perfil nativo de Horus.

spring:
  profiles:
    active: native
  cloud:
    config:
      server:
        native:
         search-locations:
         - file:/opt/data/config
         - file:/opt/data/config/{application}
         - file:/opt/data/config/{application}/{profile}

Repositorio Git

Se puede indicar que rama se va a usar en default-label, el resto de propiedades son genéricas de conexión a un repositorio Git

spring:
  cloud:
    config:
      server:
        git:
          uri: <usuario>@<servidor>/<repositorio>.git
          default-label: <rama>
          skipSslValidation: true
          timeout: 10
          clone-on-start: true
          force-pull: true
          searchPaths: '{application}'
          ignoreLocalSshSettings: true
          privateKey: |
            -----BEGIN RSA PRIVATE KEY-----
                       .......
            -----END RSA PRIVATE KEY-----

Repositorio Vault

Se permite la utilización de repositorios Vault mediante la herramienta de HashiCorp's Vault

spring:
  profiles:
    active: vault
  cloud:
    config:
      server:
         vault:
            token: ******
            kv-version: 2
            host: <host de vault>
            port: 8200
            authentication: TOKEN

Para la configuración completa de HashiCorp Vault como backend de Horus (obtención de credenciales, significado de cada propiedad y particularidades del entorno) consulta la página Vaults.

Base de datos

Anjana tiene una comunicación nativa con la tabla app_configuration del esquema Portuno de la base de datos. Esta tabla está compuesta de las columnas:

• Key para la propiedad a configurar

• Value para el valor a configurar

• Label para usar como descripción de la propiedad

• Application para definir para qué servicio se configura la propiedad (valor NULL identifica la propiedad para todos los servicios)

• Profile para definir el perfil asociado a la propiedad (ver qué es un perfil)

AWS Secret Manager

Se permite usar el secret manager de AWS para el almacenamiento de credenciales y otra configuración.

spring:
  # 1. BOOTSTRAP: Horus carga SU propia configuración.
  config:
    import: "optional:aws-secretsmanager:{HORUS_SM_PREFIX}/application_default/}" # EX: /secret/dev
  cloud:
    # 2. Conexión con Secret Manager
    aws:
      region:
        static: {HORUS_SM_REGION}
      secretsmanager:
        enabled: true

    # 3. Configuración de prefijos para las aplicaciones que usan horus como centro de configuración
    config:
      server:
        aws-secretsmanager:
          order: 20
          prefix: {HORUS_SM_PREFIX} # EX: /secret/dev
          profile-separator: {APP_PREFIX} # EX: _

Vault Encriptado

La configuración de un Vault de forma directa está solo disponible para los Tot Plugins dado que podrían no estar en la red del core de Anjana y no poder disponer de Vault a través de Horus. Por defecto viene deshabilitada esta opción, para poder habilitar cualquiera de los Vault Cloud se deberá editar el descriptor de servicio añadiendo la propiedad que habilita el Vault que se define a continuación. Para saber como configurar esta propiedad se puede seguir el formato que se explica en el apartado anterior "Uso de perfiles".

La configuración completa de cada proveedor (credenciales necesarias, YAML y particularidades) está centralizada en la página Vaults, para evitar mantenerla duplicada en dos sitios.

Secrets Manager AWS

Permite guardar los parámetros sensibles de la configuración del plugin en el Secret Manager de AWS y recuperarlos mediante llamada a la API. Configuración detallada (credenciales IAM o rol de EC2, YAML necesario y convención de nombres de secreto) en la sección "Configuración de AWS Secret Manager" de Vaults.

Azure Key Vault

Permite guardar las propiedades sensibles de la configuración del plugin en Azure Key Vault y recuperarlas mediante llamada a la API. Configuración detallada (registro de aplicación en Azure AD, YAML necesario y restricciones de nombres de secreto) en la sección "Configuración de Azure Key Vault" de Vaults.

GCP Secret Management

Permite guardar la configuración sensible del plugin en GCP Secret Manager y recuperarla mediante llamada a la API. Configuración detallada (proyecto GCP, credenciales de cuenta de servicio y YAML necesario) en la sección "Configuración de GCP Secret Manager" de Vaults.

Otras formas de securizar credenciales

Variables de entorno

Se pueden usar variables de entorno para ocultar información sensible en los yamls de configuración por ejemplo.

Se crea la carpeta con el nombre del servicio /etc/systemd/system/xxxxx.service.d y dentro un archivo del tipo env.conf (root con permisos 600) de esta forma solo el microservicio tiene acceso a ese archivo env.conf.

[Service]
Environment=<KEY>=<VALUE>
Environment=<KEY2>=<VALUE2>

En el yaml de configuración del microservicio se puede poner entre llaves y con un simbolo dolar previo ${KEY}

spring:
  datasource:
    username: anjana
    password: ${BBDD_PASSWORD}
...

Configuraciones genéricas de utilidades y performance

Todos los microservicios de Anjana tienen por defecto un tamaño de de cabeceras HTTP de 2KB, este valor puede ser modificado cambiando esta propiedad en el fichero de propiedades.

server:
  max-http-header-size: 20000

Es posible activar las estadísticas de Hibernate para visualizar la información que ofrece con la siguiente configuración.

Es importante destacar que la generación de las estadísticas puede afectar al rendimiento por lo que debe estar activa solo de forma puntual.

jpa:
  properties:
    hibernate:
      generate_statistics: true

Colector de basura: Todos los servicios que estén utilizando el jdk17 tendrán que tener el colector de basura G1 para manejar de forma más eficiente la memoria:

-XX:+UseG1GC -XX:+UseStringDeduplication

Configuración de logs

Los microservicios están configurados por defecto para que den su salida a consola estándar para que los log puedan ser gestionados por la utilidad de logs del sistema, normalmente en entornos de máquina virtual se usará syslog, rsyslog y jornalctl para consumirmos o configurar su tratamiento.

Todos ellos pueden ser configurados mediante el fichero yaml de cada uno siguiendo las prácticas estándar de Spring Boot.

Ejemplo de usos comunes:

logging:
  pattern:
  console: "%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){faint} [HERMES] %clr(${LOG_LEVEL_PATTERN:%5p}) %clr(${PID:- }){magenta} %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{39}){cyan} %clr(:){faint} %m%n${LOG_EXCEPTION_CONVERSION_WORD:%wEx}"
  level:
    root: INFO
    com.anjana: DEBUG

Balanceo de carga

El balanceo de carga y la alta disponibilidad de Horus (variable HORUS_REPLICAS, registro de varias URLs de Eureka y de Config Server) están documentados en la página Horus, sección "Alta disponibilidad de Horus", para evitar mantener el mismo contenido duplicado en dos sitios.

Autenticación

Todo se configura en Zeus. En el Yaml de ejemplo disponible en Nexus se puede ver en detalle la configuración, pudiendo copiar, editar y pegar lo que se necesite, incluidas descripciones de los campos.

Además las integraciones de autenticación se detallan en los documentos específicos en Integraciones/Autentificación:

• SSO OKTA/AUTH0 (Deprecado)

• SSO AWS (Deprecado)

• SSO GCP (Deprecado)

• SSO Azure (Deprecado)

• Login LDAP/WAD

• SSO OICD

• SSO SAML 2.0

Notificaciones vía email

Anjana Data Platform permite enviar notificaciones automáticas por correo electrónico (por ejemplo, avisos de validación, cambios de estado, adherencias, etc.).
Para habilitarlas es necesario configurar la conexión SMTP en el servicio Hermes, que es el componente encargado de gestionar el envío de notificaciones.

La configuración se realiza mediante el fichero de parámetros de Hermes (YAML). En Nexus existe un YAML de ejemplo con comentarios que puede tomarse como base para copiar y adaptar a cada organización.

Información necesaria (qué debes solicitar a tu organización)

Antes de configurar Hermes, solicita al equipo responsable del correo corporativo o del proveedor SMTP los siguientes datos:

1. Servidor SMTP (host)
   Dirección del servidor SMTP corporativo o del proveedor (por ejemplo, smtp.empresa.com).

2. Puerto (port)
   Puerto de envío SMTP habilitado. Los más habituales son:

   • 587 (TLS STARTTLS)

   • 465 (SMTPS / TLS implícito)

   • 25 (sin cifrado o relay interno, no recomendado salvo entornos controlados)

3. Cuenta emisora (from)
   Dirección de correo desde la que se enviarán las notificaciones
   (por ejemplo, anjanadata@empresa.com).
   Esta cuenta debe estar autorizada para enviar emails desde el dominio.

4. Credenciales de autenticación (username / password)
   Usuario y contraseña del buzón o de la cuenta técnica SMTP.

5. Requisitos de seguridad

   • Si el servidor requiere autenticación SMTP (auth = true).

   • Si exige TLS/STARTTLS (starttls.enable = true).

   • Si hay restricciones por IP, proxy o firewall que deban abrirse para Hermes.

Verificación previa del servicio SMTP desde línea de comandos

Antes de configurar Hermes o ante cualquier duda durante la resolución de incidencias, se recomienda verificar de forma independiente que el servidor SMTP y las credenciales funcionan correctamente. Esto permite aislar problemas de conectividad o autenticación de posibles errores funcionales de la plataforma.

Ejemplo de prueba SMTP desde terminal (SMTPS – puerto 465)

swaks \
  --server smtp.empresa.com \
  --port 465 \
  --tls-on-connect \
  --auth LOGIN --auth-user 'usuario'--auth-password 'password' \
  --from 'anjanadata_platform@empresa.com' --to 'destinatario@empresa.com' \
  --header "Subject: Test SMTPS 465" \
  --body "Prueba de envío SMTP desde línea de comandos"

Si el correo se recibe correctamente, se confirma que:

• el servidor SMTP es accesible desde el entorno,

• las credenciales son válidas,

• y no existen bloqueos de red o firewall.

Configuración SMTP en Hermes según el puerto utilizado

La configuración de Hermes varía en función del puerto SMTP y del tipo de cifrado soportado por el servidor. Es importante no combinar SSL y STARTTLS simultáneamente, ya que son mecanismos excluyentes.

Puerto 587 – SMTP con STARTTLS (recomendado en la mayoría de entornos)

Dentro del YAML de configuración de Hermes, habilita el bloque mail y completa los valores proporcionados por tu organización.

######################
### SMTP connection properties
######################
  mail:
    # the host of the SMTP server
    host: smtp.example.com
    # the port to establish a connection with the SMTP server
    port: 587
    # the email address of the account you want to use as the sender of the emails
    from: anjanadata@anjanadata.com
    # the credentials for the SMTP server
    username: <userName>
    password: <password>
    properties:
      mail:
        smtp:
        # to enable SMTP authentication. When set to true, it indicates that the SMTP server requires authentication before sending email
          auth: true
        # to enable the use of TLS when connecting to the SMTP server. When set to true, it ensures that the connection is secured using TLS encryption
          starttls:
            enable: true
            required: true
          ssl:
            enable: false

Uso típico: servidores corporativos modernos, relays autenticados, proveedores cloud.

Puerto 465 – SMTPS (TLS implícito)

######################
### SMTP connection properties
######################
  mail:
    # the host of the SMTP server
    host: smtp.example.com
    # the port to establish a connection with the SMTP server
    port: 465
    # the email address of the account you want to use as the sender of the emails
    from: anjanadata@anjanadata.com
    # the credentials for the SMTP server
    username: <userName>
    password: <password>
    properties:
      mail:
        smtp:
        # to enable SMTP authentication. When set to true, it indicates that the SMTP server requires authentication before sending email
          auth: true
          ssl:
            enable: true
        # to enable the use of TLS when connecting to the SMTP server. When set to true, it ensures that the connection is secured using TLS encryption
          starttls:
            enable: true
            required: true

Uso típico: servidores que exigen conexión cifrada desde el inicio.

Puerto 25 – SMTP sin cifrado (no recomendado)

Solo debe utilizarse en entornos internos y controlados.

######################
### SMTP connection properties
######################
  mail:
    # the host of the SMTP server
    host: smtp.interno.local
    # the port to establish a connection with the SMTP server
    port: 25
    # the email address of the account you want to use as the sender of the emails
    from: anjanadata@anjanadata.com
    properties:
      mail:
        smtp:
          auth: false
        # to enable the use of TLS when connecting to the SMTP server. When set to true, it ensures that the connection is secured using TLS encryption
          starttls:
            enable: false

Validación funcional del envío de notificaciones

Una vez verificada la conectividad SMTP desde línea de comandos y desplegada o actualizada la configuración en Hermes, es necesario validar el envío de notificaciones desde Anjana Data Platform.

Pasos de validación

1. Reiniciar el microservicio de Hermes
   Para que la nueva configuración SMTP sea efectiva, reinicia el microservicio de Hermes tras cualquier cambio en su YAML de configuración.

2. Generar una notificación desde la plataforma
   Ejecuta una acción que dispare el envío de correo, por ejemplo:

   • enviar un objeto a validar,

   • aprobar o rechazar una validación,

   • solicitar o aprobar una adherencia a un DSA.

3. Verificar el resultado
   Comprueba que:

   • el correo se recibe correctamente en el buzón del usuario destinatario,

   • el remitente coincide con el valor configurado en from,

   • el mensaje no es bloqueado por políticas anti-spam corporativas.

Resolución de incidencias

Si el correo no se recibe, revisa los siguientes puntos en este orden:

1. Conectividad SMTP

   • Confirma que Hermes puede alcanzar el host y port configurados.

   • Valida reglas de firewall, proxy o listas blancas de IP.

2. Credenciales y configuración

   • Verifica usuario, contraseña y puerto.

   • Revisa que la configuración TLS/STARTTLS o SSL sea coherente con el puerto utilizado.

3. Políticas del relay SMTP

   • Comprueba si el servidor exige:

     • autorización explícita del remitente (from),

     • dominio validado,

     • IP del servicio Hermes incluida en whitelist.

4. Logs de Hermes

   • Analiza los logs para identificar errores previos o posteriores al intento de envío.

   • Ten en cuenta que ciertos errores (por ejemplo, HTTP 400) pueden producirse antes de que se intente enviar el correo, y no estar relacionados directamente con SMTP.

Claves de encriptación para licenciamiento Drittesta-Veltesta

El NIST recomienda usar claves de como mínimo 2048 bits, que son las que proporciona Anjana. Aún así, si el cliente lo desea, podrá generar un nuevo par de claves RSA para incrementar la seguridad de la encriptación hasta 4096 bits creando las claves de forma manual; de este modo el cliente será el creador y validador de la seguridad y unicidad de las claves. Una vez generadas, la pública la deberá proporcionar a Anjana para configurar su instalación. La privada se establecerá en el proyecto de Drittesta con la nueva propiedad del yaml anjana.privateKey teniendo en cuenta que:

• Representa la clave privada del cliente para la comunicación entre los servicios de licencia.

• Será una propiedad obligatoria.

• Podrá ser generada por el cliente de la siguiente manera:

  • Con el endpoint habilitado en Drittesta para ello (clave de 2048 bits):

Donde {{host}} es la dirección de la máquina y {{port}} el puerto de Drittesta. La respuesta es un json con el siguiente formato:

O bien,

En una consola UNIX ejecutar las instrucciones:

• ssh-keygen -m PKCS8 -t rsa -b 4096

• openssl rsa -in nombreClave -pubout

La primera genera las claves en un directorio local. Descripción de los parámetros:

• -m indica el tipo de algoritmo que es obligatorio que sea PKCS8

• -t indica el tipo de clave que es RSA obligatoriamente.

• -b indica el tamaño de la clave. El cliente puede configurar el tamaño que desee. Los tamaños más comunes son 1024, 2048, 3072 o 4096 bits, siendo 4096 el tamaño máximo.

La segunda instrucción devuelve la clave pública en el formato correcto para usarse en Anjana. El parámetro "nombreClave" será el nombre de la clave que hemos dado en el paso anterior.

Tot plugins

En cada plugin existe configuración para poder registrarse en múltiples Tots y usarlo como proxy para registrarse en eureka.

totplugin.server.urls: Lista de urls de los Tot en los que el plugin se registraría.

Cada plugin puede registrar varias conexiones bajo la misma instancia. En el Yaml de ejemplo disponible en Nexus se puede ver en detalle la configuración, pudiendo copiar, editar y pegar lo que se necesite, incluidas descripciones de los campos.

Además de la configuración común, cada plugin tiene un documento para desplegar y configurar (con ejemplos de configuración).