1. Base de conocimiento
2. Despliegue

Documentación del chart de Helm de Seatmap

Resumen

El chart de Helm de Seatmap despliega un stack completo de la aplicación Seatmap.pro que incluye los servicios Editor, Booking y converter, junto con las dependencias requeridas como PostgreSQL y Redis.

• Versión del chart: 1.2.1
• Versión de la aplicación: 1.40.0

Requisitos previos

• Kubernetes 1.19+
• Helm 3.2.0+
• Soporte de aprovisionador de PV en la infraestructura subyacente
• Soporte de LoadBalancer (para ingress)

Dependencias

El chart incluye las siguientes dependencias de Bitnami:

• PostgreSQL (versión 12.x.x)
• Redis (versión 17.x.x)

Instalación

Instalación desde el monorepo

El chart de Helm se encuentra en deployment/helm/seatmap/ en el monorepo. Antes de desplegar, asegúrate de que las dependencias de bitnami estén resueltas:

helm repo add bitnami https://charts.bitnami.com/bitnami
helm dependency update deployment/helm/seatmap

helm upgrade --install seatmap deployment/helm/seatmap \
  --create-namespace \
  --namespace seatmap \
  --set global.s3.bucket=${S3_BUCKET} \
  --set global.s3.region=${S3_REGION} \
  --set global.s3.endpoint=${S3_ENDPOINT} \
  --set global.mail.host=${MAIL_HOST} \
  --set global.mail.fromAddress=${MAIL_FROM} \
  --set global.mail.port=${MAIL_PORT} \
  --set global.mail.strategy=${MAIL_STRATEGY} \
  --set-string secrets.s3.accessKey=${S3_ACCESS_KEY} \
  --set-string secrets.s3.secretKey=${S3_SECRET_KEY} \
  --set-string secrets.mail.username=${MAIL_USERNAME} \
  --set-string secrets.mail.password=${MAIL_PASSWORD} \
  --set-string secrets.google.apiKey=${GOOGLE_API_KEY} \
  --set imageCredentials.registry=${REGISTRY} \
  --set-string imageCredentials.username=${REGISTRY_USERNAME} \
  --set-string imageCredentials.password=${REGISTRY_PASSWORD}

Pruebas locales

Ejecuta la prueba del stack local completo con kind:

./deployment/helm/test-local.sh

Configuración

Parámetros globales

Configuración de hosts

global:
  hosts:
    editor: editor.test-5.seatmap.dev
    booking: booking.test-5.seatmap.dev

Registro de imágenes

imageCredentials:
  registry: registry.gitlab.com
  username: seatmap
  password: <password>

Configuraciones de recursos

global:
  resources:
    default:
      requests:
        cpu: '500m'
        memory: '2Gi'
      limits:
        cpu: '1000m'
        memory: '3Gi'
    frontend:
      requests:
        cpu: '100m'
        memory: '128Mi'
      limits:
        cpu: '200m'
        memory: '256Mi'

Configuración de ingress

El chart proporciona configuraciones de ingress para los servicios Editor y Booking con nombres de host independientes.

Ajustes globales de ingress

global:
  ingress:
    className: public
    proxyBodySize: '50m'
    annotations:
      cert-manager.io/cluster-issuer: 'letsencrypt-prod'
  hosts:
    editor: editor.test-5.seatmap.dev
    booking: booking.test-5.seatmap.dev

Ingress de Editor

El ingress del servicio Editor está configurado para gestionar tanto el tráfico web como el de la API en su dominio dedicado.

editor:
  ingress:
    enabled: true
    annotations: {} # Additional service-specific annotations
    apiPaths:
      - /api
      - /swagger-ui
      - /preview
      - /media
      - /ws
      - /webjars
      - /v3

Características:

• Host: editor.{domain} (p. ej., editor.test-5.seatmap.dev)
• TLS habilitado con certificado basado en el nombre de host
• La ruta web predeterminada (/) se enruta al puerto web
• Las rutas de API se enrutan al puerto de la API
• Soporte de WebSocket habilitado
• Tamaño máximo del cuerpo configurable

Ingress de Booking

El ingress del servicio Booking está configurado en su propio dominio dedicado.

booking:
  ingress:
    enabled: true
    annotations: {} # Additional service-specific annotations
    apiPaths:
      - /api
      - /swagger-ui
      - /custom
      - /scalar
      - /scalar.html
      - /scalar-v1.html
      - /scalar-v2-booking.html
      - /scalar-v2-management.html
      - /webjars
      - /v3
      - /csrf
      - /oauth2
      - /login
      - /.well-known

Características:

• Host: booking.{domain} (p. ej., booking.test-5.seatmap.dev)
• TLS habilitado con certificado basado en el nombre de host
• La ruta web predeterminada (/) se enruta al puerto web
• Las rutas de API se enrutan al puerto de la API
• Soporte de WebSocket habilitado
• Configuración de tamaño del cuerpo del proxy compartida con Editor

Características comunes de ingress

Ambos ingress incluyen:

• Anotaciones de NGINX para los límites de tamaño del cuerpo
• Soporte de WebSocket
• Configuración de TLS
• Tipos de ruta Implementation-specific para las rutas raíz
• Tipos de ruta Prefix para los endpoints de la API

Configuraciones de componentes

PostgreSQL

• Autenticación gestionada mediante postgresql-secret
• Base de datos y nombre de usuario predeterminados: seatmap
• Incluye la inicialización de la extensión uuid-ossp

postgresql:
  enabled: true
  auth:
    existingSecret: 'postgresql-secret'
    username: seatmap
    database: seatmap

Redis

• Arquitectura standalone
• Autenticación habilitada mediante redis-secret
• Configuración de memoria:
  • Memoria máxima: 512MB
  • Política: allkeys-lru

redis:
  enabled: true
  architecture: standalone
  auth:
    enabled: true
    existingSecret: 'redis-secret'
  master:
    persistence:
      enabled: true
      size: 8Gi

Registro de contenedores

Todas las imágenes de los servicios se alojan en el GitLab Container Registry:

Las etiquetas de imagen siguen el versionado semántico (p. ej., 1.60.0 para releases, 1.61.0-dev.55-a9130b33 para builds de dev/stage).

Componentes de servicio

Servicio Editor

editor:
  image:
    repository: registry.gitlab.com/seatmap.pro/seatmap/editor-service
    tag: '1.60.0'
  frontend:
    image:
      repository: registry.gitlab.com/seatmap.pro/seatmap/editor-client
      tag: '1.60.0'

Configuraciones clave:

• Ajustes del pool de conexiones HikariCP
• Ajustes de expiración de tokens
• Soporte de integración SSO
• Rutas de API para ingress

Servicio Booking

booking:
  image:
    repository: registry.gitlab.com/seatmap.pro/seatmap/booking-service
    tag: '1.60.0'
  frontend:
    image:
      repository: registry.gitlab.com/seatmap.pro/seatmap/booking-client
      tag: '1.60.0'

Características:

• Configuración de JPA/Hibernate
• Ajustes del pool de conexiones
• Soporte de OAuth2
• Endpoints de Actuator

Servicio Converter

converter:
  image:
    repository: registry.gitlab.com/seatmap.pro/seatmap/converter-service
    tag: '1.60.0'

converter:
  config:
    async:
      enabled: true
      cpuClaimDelayMs: 5000
    rateLimit:
      jobsMax: 5000
  gpu:
    enabled: false

Comportamiento:

• Las conversiones se encolan en el Redis de la release mientras converter.config.async.enabled es true (valor por defecto). Ponlo en false para renderizar dentro de la solicitud sin Redis.
• converter.gpu.enabled añade una variante de pod con GPU que reclama primero los trabajos encolados; los pods por CPU toman lo que no reclame.
• El chart genera un secreto compartido en <release>-converter y lo conecta con editor-service. Un despliegue que ejecuta el conversor en una release separada define el mismo secrets.converter.apiKey en ambos lados antes de actualizar cualquiera de ellas.

Limitaciones:

• Longitud máxima del contenido: 32MB
• Dimensiones máximas de imagen: 15000x15000 píxeles
• Integración con almacenamiento S3

Configuración de servicios externos

Almacenamiento S3

global:
  s3:
    bucket: 'seatmap-storage'
    region: 'us-east-1'
    endpoint: 'https://s3.amazonaws.com'

Servidor de correo

global:
  mail:
    host: 'smtp.example.com'
    port: 587
    strategy: 'SMTP_TLS'
    fromAddress: 'seatmap@example.com'

El correo de restablecimiento de contraseña permanece desactivado hasta que se configuran host y fromAddress. strategy admite SMTPS para TLS implícito, normalmente en el puerto 465, SMTP_TLS para STARTTLS, normalmente en el puerto 587, o SMTP, que envía sin cifrar cuando el servidor no ofrece STARTTLS y solo es adecuado en una red de confianza; el chart rechaza cualquier otro valor. Si se deja vacío, el editor usa SMTPS en el puerto 465 y SMTP_TLS en cualquier otro puerto. Deje secrets.mail.username y secrets.mail.password vacíos cuando el servidor de correo acepte correo sin iniciar sesión.

Consideraciones de seguridad

Claves de firma JWT

El servicio de editor firma sus tokens con un par de claves RSA guardado en el Secret {release}-rsa. Un hook de preinstalación y preactualización lo crea y nunca sobrescribe uno existente, de modo que el par de claves sobrevive a cada actualización y los tokens emitidos siguen verificándose.

El hook copia el material de claves existente al Secret de forma literal durante la actualización: no se invalida ningún token ni se cierra la sesión de ningún usuario. Si los datos de clave existentes están vacíos, el hook se niega a migrar y hace fallar la actualización, en lugar de generar en silencio un par de claves nuevo e invalidar todas las sesiones activas.

Solo se genera un par de claves nuevo en una instalación desde cero, donde no hay nada que trasladar.

Una vez que la actualización termine correctamente, puedes eliminar el ConfigMap antiguo. Ya no lo lee nada.

kubectl delete configmap {release}-rsa -n {namespace}

Gestión de secretos

Se deben proporcionar los siguientes secretos:

• Credenciales de PostgreSQL
• Contraseña de Redis
• Credenciales de acceso a S3
• Credenciales del servidor de correo, si el servidor exige iniciar sesión
• Clave de la API de Google
• Secreto compartido del conversor (generado por el chart, o secrets.converter.apiKey para una release separada)

Seguridad de red

• Terminación TLS a través de ingress
• Integración con cert-manager para la gestión automatizada de certificados
• Puertos de API y web separados para los servicios

Escalado

Autoescalado horizontal de pods

El HPA es configurable para todos los servicios con ajustes predeterminados:

global:
  hpa:
    enabled: false
    targetCPUUtilizationPercentage: 80
    targetMemoryUtilizationPercentage: 80

Configuraciones de HPA específicas por servicio:

• Editor: 2-6 réplicas
• Booking: 2-6 réplicas
• Converter: 1-4 réplicas

Monitorización y métricas

• Endpoints de Actuator habilitados para los servicios Spring Boot
• Métricas de Redis deshabilitadas por defecto
• Endpoints de métricas personalizados configurados para los servicios editor y booking

Resolución de problemas

Problemas comunes

1. Errores al extraer la imagen

   • Verifica las credenciales del registro
   • Comprueba que las etiquetas de imagen existan

2. Problemas de conexión con la base de datos

   • Verifica que el secreto de PostgreSQL exista
   • Comprueba los ajustes del pool de conexiones

3. Problemas de almacenamiento

   • Valida las credenciales de S3 y la accesibilidad del bucket
   • Comprueba las cuotas y límites de almacenamiento

Depuración

1. Accede a los logs mediante:

   kubectl logs -f deployment/seatmap-<component>
   

2. Comprueba el estado de los servicios:

   kubectl get pods -l app.kubernetes.io/instance=seatmap
   

Referencia de variables de configuración

Variables globales

Variables de instancia

Variables de PostgreSQL

Variables de Redis

Variables del servicio Editor

Variables del servicio Booking

Variables del servicio Converter

Variables de servicios externos

Soporte y mantenimiento

• Actualizaciones periódicas mediante etiquetas de versión
• Cambios de configuración mediante Helm upgrade
• Gestión del almacenamiento persistente para PostgreSQL y Redis