Gateway module

The gateway is the entry point for all external REST requests to Vertex.

Partner transport TLS

A dedicated partner Gateway can terminate TLS before applying its HTTP routing and rate limits. Configure one optional GatewayModuleConfig.TransportEndpoint per instance. Route the partner’s hostname through cluster ingress with TLS passthrough, not HTTPS termination or re-encryption. The downstream module continues to receive HTTP on its interconnect port.

GatewayModuleConfig:
  Url: ''
  EnableModuleDiscovery: false
  EnableSwagger: false
  EnableGraphQL: false
  EnableUserSessions: false
  TransportEndpoint:
    Port: 8443
    CertificateBase64: '${TennetMessageClientCertificateBase64}'
    CertificatePassword: '${TennetMessageClientCertificatePassword}'

An empty Url leaves the dedicated Gateway without a plaintext HTTP listener. The shared user-facing Gateway can retain its existing Url and omit TransportEndpoint. The PFX must contain a private key, permit server authentication, and cover the public hostname. Certificates and pins are loaded at startup; restart the Gateway after changing them.

TransportEndpoint.ClientCertificateSha256Pins is an optional array of SHA-256 fingerprints of complete client certificates:

• Omitted or empty: server-only TLS; no client certificate is requested.
• Non-empty: a client certificate is required and must match a pin and pass normal certificate-chain, validity and revocation checks. Pins do not bypass CA trust.
• Each entry is 64 hexadecimal characters; colon separators and spaces are accepted. Windows’ usual SHA-1 thumbprint is not accepted.
• Include both current and next fingerprints during rotation. Full public leaf certificates are unnecessary for pinning; private issuing CAs must still be trusted by the Gateway pod.
• Malformed pins or an invalid PFX abort startup rather than falling back to unauthenticated TLS.

Obtain a fingerprint with openssl x509 -in client.pem -noout -fingerprint -sha256. The pod needs access to the certificate issuer’s CRL/OCSP endpoints when mTLS is enabled.

Use one Gateway deployment per partner to enforce backend isolation with Kubernetes NetworkPolicy. NetworkPolicy identifies pods and destination ports, not HTTP routes or the source listener.

Optional Gateway capabilities

Each capability defaults to true for existing user-facing deployments. Disable them explicitly on a partner Gateway; TLS configuration is independent of these switches.

Selecting an instance’s configuration section

By default, the Gateway binds GatewayModuleConfig. Set the deployment environment variable ConfigSections__GatewayModuleConfig=TennetGatewayModuleConfig to bind another section instead. Colon-delimited nested paths are also supported. ModuleId remains the instance identity and does not determine the selected section.

The legacy configuration loader binds only the selected section, after normal Config Server, vault, environment-variable and placeholder processing. It does not overlay that section onto GatewayModuleConfig; shared routes, user-session settings and credentials are not inherited. An explicitly selected missing or blank section fails startup instead of falling back. Class-level defaults still apply to properties omitted from the selected section.

Both sections can live beside each other in config.yaml, with their environment overrides in config-acc.yaml. Maintainers can organize files later using the existing Config Server layers. Disabling module discovery alone does not remove explicitly configured routes.

Request tracing and caller attribution

Trace context

Send a W3C traceparent header to link the handling of a request in Vertex to a trace in your own tooling. B3 and Jaeger trace headers are also accepted; when several are present, traceparent takes precedence. A missing or malformed trace header never causes a request to be rejected; Vertex then starts a new trace for that request.

Caller headers

Identify your application and job with the following optional headers. They allow traffic and issues to be traced back to a specific caller and run, without requiring any tracing tooling on your side.

• Use stable application and job names, and generate a new run identifier for every execution.
• These headers are diagnostic labels only: they do not authenticate the caller, grant permissions, or change rate limits.
• Never put credentials, tokens, personal data, or request content in these headers.

Header value rules

• Allowed characters are ASCII letters, digits, spaces, ., _, and -; other characters are removed.
• Values are trimmed and truncated to 128 characters.
• Empty values, repeated headers, comma-separated lists, and values longer than 1,024 characters are ignored.
• An invalid caller header never causes the request itself to be rejected.