Despliegue self-managed con Kubernetes

Lamassu IoT puede desplegarse en infraestructura propia mediante Kubernetes, tanto en clústeres gestionados internamente como en entornos self-managed.

La referencia principal para este despliegue es el repositorio lamassu-helm, que incluye:

el chart principal de Lamassu
un chart auxiliar de SoftHSM
el script de despliegue automatizado scripts/lamassu-fast-lane.sh

Quickstart

Si lo que necesitas es levantar un entorno funcional lo antes posible, la vía más rápida es usar Fastlane desde el repositorio lamassu-helm:

git clone https://github.com/lamassuiot/lamassu-helm.git
cd lamassu-helm
./scripts/lamassu-fast-lane.sh -n -ns lamassu-dev -d dev.lamassu.io -l ./charts/lamassu

Ese flujo:

crea o reutiliza el namespace indicado
instala PostgreSQL, Keycloak y RabbitMQ
despliega el chart de Lamassu
deja la UI expuesta en https://<dominio>

Si buscas un despliegue productivo o más controlado, sigue con la instalación manual mediante Helm que se describe más abajo.

Qué se despliega

El chart principal charts/lamassu, actualmente en la serie 3.7.x, despliega estos componentes:

ui
ca
va
kms
device-manager
dms-manager
alerts
recursos de Gateway API y políticas de Envoy Gateway
job de migraciones de base de datos

Requisitos previos

Clúster Kubernetes 1.19+
kubectl configurado con acceso al clúster
Helm 3.2.0+
cert-manager 1.14+ para la gestión de certificados cuando se usa tls.type=certManager
Envoy Gateway 1.3.0+, ya que el chart publica servicios mediante Gateway API y no mediante Ingress
Acceso a un registro de contenedores o imágenes previamente importadas si se trabaja en modo offline
Almacenamiento persistente disponible para PostgreSQL, RabbitMQ, VA y KMS

Opciones de despliegue

Hay dos formas de desplegar Lamassu on-prem:

1. Despliegue manual con Helm

Es la opción recomendada para entornos productivos o controlados, donde PostgreSQL, RabbitMQ, Keycloak, certificados y direccionamiento del Gateway ya están definidos por el equipo de plataforma.

2. Despliegue automatizado con Fastlane

Es la opción más útil para pruebas, demos, CI o bootstrap rápido de un entorno. Fastlane levanta PostgreSQL, Keycloak, RabbitMQ y Lamassu en un único flujo. Su comportamiento está documentado en la página siguiente.

Arquitectura

Lamassu IoT se despliega como un conjunto de microservicios Kubernetes independientes. El chart principal crea Deployment, StatefulSet, Service, ConfigMap, HTTPRoute, Gateway, certificados y recursos auxiliares según los valores definidos.

Dependencias externas requeridas por el chart principal:

PostgreSQL
RabbitMQ
proveedor OIDC, típicamente Keycloak

El chart no instala estas dependencias por sí solo. Para un despliegue manual hay que provisionarlas antes. Si se busca un entorno funcional rápido para laboratorio o validación, el script Fastlane sí instala PostgreSQL, RabbitMQ y Keycloak además del chart de Lamassu.

Instalación manual con Helm

Agregar el repositorio Helm:

helm repo add lamassu https://lamassuiot.github.io/lamassu-helm
helm repo update

O instalar desde una copia local del repositorio:

helm install lamassu ./charts/lamassu -n lamassu --create-namespace -f values.yaml

Valores mínimos que deben definirse

Los valores por defecto del chart son deliberadamente incompletos para dependencias externas. Como mínimo, un despliegue manual debe definir:

postgres.hostname, postgres.username, postgres.password
amqp.hostname, amqp.username, amqp.password
auth.oidc.frontend.authority
auth.oidc.apiGateway.jwks
services.authz.jwkUrl y un principal de bootstrap que coincida con un administrador real
services.ca.domains
gateway.addresses o una estrategia equivalente de publicación según el clúster
tls.* según se use certManager o certificado externo

Ejemplo base:

postgres:
  hostname: postgresql
  port: 5432
  username: lamassu
  password: change-me

amqp:
  hostname: rabbitmq
  port: 5672
  username: lamassu
  password: change-me
  tls: false

tls:
  type: certManager
  certManagerOptions:
    issuer: downstream-ca-selfsigned-issuer
    certSpec:
      commonName: pki.example.internal
      hostnames:
        - pki.example.internal
      addresses:
        - 10.0.0.20

gateway:
  addresses:
    - 10.0.0.20
  ports:
    http: 80
    https: 443
  extraRouting:
    - path: /auth
      name: auth
      target:
        host: auth-keycloak
        port: 8080

auth:
  oidc:
    frontend:
      clientId: frontend
      authority: https://pki.example.internal/auth/realms/lamassu
    apiGateway:
      jwks:
        - name: oidc-authn
          uri: http://auth-keycloak.lamassu/auth/realms/lamassu/protocol/openid-connect/certs
  authorization:
    rolesClaim: realm_access.roles
    roles:
      admin: pki-admin

services:
  ca:
    domains:
      - pki.example.internal
  authz:
    jwkUrl: http://auth-keycloak.lamassu/auth/realms/lamassu/protocol/openid-connect/certs
    bootstrap:
      - principal_id: "oidc:pki-admin"
        principal_name: "PKI Admin"
        principal_type: "oidc"
        policy_ids:
          - "lamassu.a6811b60-5f89-4ce7-badb-78ea234794d3"
        auth_config:
          claims:
            - claim: realm_access.roles
              operator: contains
              value: pki-admin

Provisiona el primer administrador

No hay un superusuario implícito. Antes de instalar, crea el rol pki-admin en el proveedor OIDC y asígnalo al grupo que administrará Lamassu. El principal del ejemplo concede la política SUPER ADMIN a cualquier token que contenga ese rol.

El Job pre-install y pre-upgrade prepara las bases de datos, ejecuta las migraciones de authz, precarga las políticas y aplica services.authz.bootstrap antes de que arranquen los Deployments. El bootstrap es idempotente: conserva los principales existentes y añade únicamente los grants que falten.

Valida el acceso antes de exponer la plataforma

Si ningún token coincide con un principal activo, nadie podrá administrar la PKI. Prueba una identidad autorizada y otra denegada, y conserva un procedimiento de recuperación.

Consulta Control de acceso para diseñar principales y políticas.

Áreas de configuración más relevantes

TLS: tls.type, tls.certManagerOptions.* y tls.externalOptions.secretName controlan el certificado downstream del Gateway.
Gateway: gateway.addresses, gateway.ports.* y gateway.extraRouting publican la UI y las APIs mediante Envoy Gateway.
Persistencia: postgres.* define la conexión a PostgreSQL.
Mensajería: amqp.* configura la conexión a RabbitMQ.
Identidad y autorización: auth.oidc.*, services.authz.jwkUrl y services.authz.bootstrap configuran login, validación JWT y permisos iniciales.
Autoridades: services.ca.domains establece los dominios autorizados para CA y certificados.
Claves: services.kms.cryptoEngines.* configura los motores criptográficos y su almacenamiento.
Alertas: services.alerts.smtp_server.* prepara el envío de correo.

Verificación del despliegue

El chart incluye una prueba Helm en charts/lamassu/templates/tests/test-connections.yml. Tras instalarlo, puede validarse con:

helm test lamassu -n lamassu

La prueba comprueba al menos:

salud de ca
salud de dms-manager
salud de device-manager
salud de va
respuesta HTML esperada del servicio ui

Repositorio Helm

El repositorio lamassu-helm está organizado en tres bloques principales:

charts/lamassu: chart principal de Lamassu
charts/softhsm: chart opcional para laboratorios o escenarios de integración con PKCS#11 emulado
scripts/lamassu-fast-lane.sh: automatización para levantar dependencias y desplegar Lamassu con intervención mínima

SoftHSM como complemento opcional

El chart charts/softhsm no forma parte del despliegue estándar, pero resulta útil en entornos de laboratorio cuando se necesita simular un HSM compatible con PKCS#11. No sustituye al backend KMS principal; sirve como soporte para pruebas o integraciones concretas.

Versionado y migraciones

La versión actual del chart en el repositorio es 3.8.0. Para upgrades entre versiones, consulta las guías de charts/lamassu/CHANGELOG/ y revisa especialmente las migraciones de base de datos y el bootstrap de authz.

Kubernetes self-managed