Saltar a contenido

Zeebe Gateway

Gateway stateless que sirve como punto de entrada unico al cluster Zeebe. Expone APIs gRPC y REST hibridas, rutea requests a la particion correcta, y aplica backpressure hacia los clientes cuando el cluster esta saturado.

Contexto

El gateway desacopla a los clientes del conocimiento interno del cluster. Los clientes no necesitan saber cuantos brokers hay, que particion hostea que proceso, ni quien es leader de cada particion. El gateway abstrae todo eso detras de una API unificada.

Entry point: gRPC + REST hibrido

El gateway expone dos protocolos simultaneamente:

  • gRPC (ver concepts/grpc-api): protocolo primario, usado por los SDKs oficiales (Java, Go, Node.js, Python). Definido en archivos .proto con servicios como Gateway y metodos como CreateProcessInstance, ActivateJobs, PublishMessage
  • REST: API REST en /v2/ que mapea a las mismas operaciones gRPC. Pensada para integraciones ligeras y clientes que no soportan gRPC

Ambas APIs son funcionalmente equivalentes. El gateway traduce las requests REST a llamadas internas gRPC.

Ruteo de requests

El gateway debe dirigir cada request a la particion correcta del cluster:

  • CreateProcessInstance: se usa round-robin entre particiones para distribuir carga uniformemente
  • PublishMessage: se rutea a la particion determinada por la correlation key del mensaje (hash de la key → particion). Esto garantiza que el mensaje llega a la particion que tiene la instancia esperandolo
  • CompleteJob / FailJob: se rutea a la particion que creo el job (codificada en el job key)
  • DeployResource: se envia a todas las particiones (broadcast) — cada particion necesita una copia del proceso

El gateway mantiene una vista actualizada de la topologia del cluster: que brokers estan vivos y quien es leader de cada particion.

Backpressure

Cuando el cluster esta saturado, el gateway aplica concepts/backpressure hacia los clientes:

  • Los brokers reportan su capacidad de procesamiento al gateway
  • Si una particion esta sobrecargada, el gateway rechaza requests nuevas con errores transitorios (gRPC RESOURCE_EXHAUSTED)
  • Los clientes con SDKs oficiales implementan retry con backoff exponencial
  • Este mecanismo evita que una avalancha de requests colapse al broker

Escalabilidad horizontal

El gateway es completamente stateless:

  • No persiste datos — toda la informacion de topologia viene de los brokers
  • Se pueden desplegar multiples instancias detras de un load balancer
  • Escalar gateways no requiere coordinacion ni re-particionamiento
  • En modo embedded, el gateway corre dentro del proceso del broker (simplifica despliegues pequenos)

Interceptors de autenticacion

El gateway soporta autenticacion via interceptors (ver concepts/authentication-flow):

  • OIDC (OpenID Connect): valida tokens JWT contra un Identity Provider externo. El gateway verifica la firma, expiracion y claims del token
  • Basic Auth: autenticacion basica para entornos de desarrollo
  • Los interceptors se configuran como middleware en la cadena gRPC
  • La autorizacion fina (que usuario puede hacer que operacion) se delega a entities/identity

Relaciones

Abierto / gaps

  • Mecanismo exacto de health checking entre gateway y brokers
  • Configuracion de rate limiting a nivel de gateway
  • Comportamiento del gateway cuando todos los leaders de una particion estan caidos