Networking and TLS
Read this page before you install, whichever way traffic reaches your cluster. It covers what Monad publishes, the two TLS certificates it needs, how to attach the chart's routes to your Gateway, the optional per-pipeline ingest host, and what changes when you use an ingress controller instead of Gateway API. Monad recommends Gateway API: an Ingress carries only part of Monad's traffic.
Merge snippets into your values file
Each values snippet gives full paths from the top-level key. If your values file already has that key, add the snippet's settings under it: a second copy of a top-level key silently replaces the first. See Install.
What Monad publishes
| Traffic | Port | Served by (Service and port) | Where TLS ends |
|---|---|---|---|
| Console, API, API reference, docs, MCP server, HTTP ingest and Splunk HEC | 443 | ui, api, docs, mcp and http-input, port 80 | Your Gateway or ingress controller |
| OTLP over gRPC | 4317 | http-input, port 4317 | Your Gateway |
| OTLP over HTTP | 4318 | http-input, port 4317 | Your Gateway |
| Syslog and other TLS over TCP | 6514 | l4-input, port 3335 | The l4-input pod, with the http-input-tls certificate |
These ports are the ones Monad's sender documentation uses. Your Gateway's listeners set them.
Monad expects to be reached over HTTPS. The hostnames value lists the names it is served at: every route answers on each one, each becomes an https:// backend URL, and the first is the console's origin. Set it before you install and point each name at your Gateway or ingress controller in DNS.
| DNS name | Points at | Needed for |
|---|---|---|
Each hostnames entry, such as monad.example.com | The load balancer in front of your Gateway or ingress controller | Every install |
*.l4.monad.example.com | The load balancer that carries port 6514 | Syslog, unless you use only the per-pipeline ingest host |
*.data.monad.example.com | The load balancer in front of your Gateway, carrying 443 and 6514, plus 4317 and 4318 if you add data-otel | The optional per-pipeline ingest host |
TLS certificates
Monad needs two certificates: one your Gateway presents for web and OTLP traffic, and one the l4-input pod presents for syslog.
Gateway certificate
The Gateway terminates HTTPS with a Secret of type kubernetes.io/tls that covers every hostnames entry, plus *.data.monad.example.com if you set up the per-pipeline ingest host. Create it in your Gateway's namespace, not the Monad namespace: Gateway API rejects a certificate reference to another namespace unless a ReferenceGrant in that namespace allows it. On an ingress-controller install, the certificate lives in the Monad namespace instead; see Use an ingress controller instead.
Syslog certificate
Syslog and other TLS-over-TCP inputs are served by the l4-input workload, which terminates TLS itself, so the Gateway passes these connections through unopened. It presents the certificate in a Secret of type kubernetes.io/tls named http-input-tls in the Monad namespace. Despite the name, this is the syslog certificate: both the l4-input and http-input pods mount it, and l4-input serves it.
Syslog clients connect to <pipeline-id>.l4.monad.example.com:6514, and l4-input reads the pipeline ID from the first label of the name the client sends (SNI). The certificate should answer to l4.monad.example.com and *.l4.monad.example.com, plus *.data.monad.example.com if you set up the per-pipeline ingest host.
The syslog name is yours to choose
The wildcard you use for syslog does not have to sit under your Monad hostname. Any name that resolves to the load balancer and reaches l4-input works, as long as its first label is the pipeline ID and the certificate covers it.
Two behaviors to plan for:
l4-inputdoes not start without it.l4-inputruns on a default install and exits at startup untilhttp-input-tlsholds a valid key pair, even if you never publish syslog. In that case a self-signed certificate is enough.l4-inputreads it only at startup. After the certificate is renewed, restartl4-inputso it serves the new one:kubectl rollout restart deployment/l4-input -n monad.
To create the Secret from files you already have:
Code
To make a self-signed key pair, for example when you do not publish syslog:
Code
Certificates with cert-manager
cert-manager is optional. If you use it, create an issuer and one Certificate for each Secret above.
The http-input-tls certificate always includes a wildcard, and ACME cannot issue a wildcard through an HTTP-01 challenge, so its issuer needs a DNS-01 solver or has to be a CA you run. The issuer below uses Let's Encrypt with DNS-01. Its dns01 block is for Amazon Route 53 with credentials from cert-manager's own AWS identity; replace it with the block for your DNS provider from cert-manager's DNS01 documentation.
Code
The Gateway certificate, in your Gateway's namespace:
Code
The syslog certificate, in the Monad namespace:
Code
The Gateway certificate has no wildcard unless you add the per-pipeline ingest host, so it can also be issued over HTTP-01. Use an http01.gatewayHTTPRoute solver whose parentRefs name your Gateway and an HTTP listener on port 80, such as web in the example Gateway below. That solver needs cert-manager's Gateway API support turned on; see cert-manager's HTTP01 documentation. An http01.ingress solver works only where that ingress class serves the challenge, so do not copy one written for another cluster.
Check that both certificates are ready:
Code
Gateway API
You need a Gateway API implementation in the cluster, such as Traefik, Istio, Envoy Gateway or kgateway, and Gateway API CRDs that include TCPRoute for syslog: the standard channel from v1.6, or the experimental channel. See Operators and controllers for the other controllers Monad needs, and Gateway API route versions for how the chart picks a TCPRoute version.
Configure your Gateway
Each route the chart renders attaches to Gateway listeners by name, the route's sectionName. The listener names below are the ones the chart's example values files use; if yours differ, change the sectionName values to match.
| Listener | Port | Protocol | Routes that attach | Needed for |
|---|---|---|---|---|
websecure | 443 | HTTPS, terminated with the Gateway certificate | api-default, docs-default, http-input-default, mcp-default and ui-default | Every install |
otel-grpc | 4317 | HTTPS, terminated with the Gateway certificate | http-input-otel, and http-input-data-otel with the per-pipeline ingest host | OTLP over gRPC |
otel-https | 4318 | HTTPS, terminated with the Gateway certificate | http-input-otel, and http-input-data-otel with the per-pipeline ingest host | OTLP over HTTP |
tcp | 6514 | TCP, passed through to l4-input | l4-input-tcp (a TCPRoute) | Syslog |
web | 80 | HTTP | None of Monad's | Optional: HTTP-01 challenges or a redirect to HTTPS |
data | 443 | HTTPS for *.data.monad.example.com | http-input-data | Optional: the per-pipeline ingest host |
The Gateway, with every listener but data:
Code
The routes live in the Monad namespace, so each listener's allowedRoutes has to admit routes from it: from: All as here, or a Selector that matches the Monad namespace. Refer to your implementation's documentation for anything else its listeners need.
Attach the routes
Every example values file in the chart has this block. Replace the placeholders with your Gateway's name and namespace:
Code
routing.enabledrenders Gateway API routes.routing.parentRefsis where every route attaches unless the route sets its ownparentRefs.routes.defaultis the HTTPRoute each web component renders for its own paths, on everyhostnamesentry. It attaches torouting.parentRefs.routes.otelis rendered byhttp-inputonly and sends everything on the OTLP listeners to its OTLP port. Give it the OTLP listeners as above. Without its ownparentRefs, it attaches torouting.parentRefs, the console's listener, and claims/there, the same path as the console, so console requests can land on the OTLP port. If you do not take OTLP, sethttp-input.routes.otel.enabledtofalseinstead.routes.tcpis rendered byl4-inputonly. Give it the TCP listener as above, or setl4-input.routes.tcp.enabledtofalseif you do not publish syslog.
A component's own routes.default.rules replaces that component's paths, because lists replace rather than merge. Leave them alone unless you mean to change what a component serves.
Check the routes after installing. Each should be accepted by your Gateway, and each listener should count the routes attached to it:
Code
In kubectl describe, each parent should show the conditions Accepted and ResolvedRefs as True.
Syslog through a TLSRoute
If your implementation supports TLSRoute but not TCPRoute, or your CRDs are the standard channel v1.5, which has TLSRoute but not TCPRoute, route syslog with a TLSRoute instead. The Gateway then routes on SNI in Passthrough mode and still hands the connection to l4-input unopened. Every syslog client must send SNI, so a client that cannot, and names its pipeline with a client certificate instead, cannot use this route.
Replace the tcp listener with a TLS listener in Passthrough mode:
Code
Then turn off the TCPRoute and add a TLSRoute for the syslog names. Add *.data.monad.example.com to hostnames if you set up the per-pipeline ingest host:
Code
Per-pipeline ingest host
Monad can serve each pipeline its own ingest hostname, <pipeline-id>.data.monad.example.com, as Monad Cloud does. Senders post to the root of that host with no path, and the hostname identifies the pipeline, so a sender needs nothing beyond the URL and its API key. OTLP senders use the same name on 443, and syslog clients on 6514.
The host must have the form <pipeline-id>.data.<domain>. http-input takes the pipeline ID from the host only when its second label is data.
This is optional. Without it, senders name the pipeline another way:
| Sender | Without a per-pipeline host | With one |
|---|---|---|
| HTTP | https://monad.example.com/api/v2/http/send/<pipeline-id> | https://<pipeline-id>.data.monad.example.com |
| OTLP | https://monad.example.com:4318 or :4317, with the header Monad-Pipeline-Id: <pipeline-id> (the monad-pipeline-id metadata key for gRPC) | https://<pipeline-id>.data.monad.example.com, or :443 for gRPC exporters that need a port |
| Syslog | <pipeline-id>.l4.monad.example.com:6514 | <pipeline-id>.data.monad.example.com:6514 |
Setting it up on Gateway API takes a DNS record, a certificate change, a Gateway listener and one values change. For an ingress-controller install, see Per-pipeline ingest host on an Ingress.
-
DNS. Point a wildcard record at the load balancer in front of your Gateway:
CodeHTTP and OTLP (443) and syslog (6514) use this name, so it has to resolve to a load balancer that carries both.
-
Certificates. The name has to be on both certificates, because HTTP and OTLP terminate at the Gateway while syslog terminates in the
l4-inputpod:- Gateway certificate. The
datalistener presents it, and so do the OTLP listeners if you adddata-otel, so add*.data.monad.example.comto it. http-input-tls. Syslog clients validate this one, so add the same name.
With cert-manager, that is one more entry in each
dnsNameslist. The issuer needs a DNS-01 solver for both, because both now carry a wildcard. Forhttp-input-tls:Code - Gateway certificate. The
-
Gateway listener. Add an HTTPS listener for the wildcard name to your Gateway:
CodeThe OTLP listeners and the
tcplistener need no change. They carry no hostname, so they already accept connections for any name that resolves to them. -
Values. Turn on
http-input'sdataroute, which the chart ships from version 2.104.0, and point it at thedatalistener. It answers on*.data.plus your firsthostnamesentry, so here*.data.monad.example.com; sethostnameson the route to use another name. It sends OTLP over HTTP and gRPC to the Service's OTLP port, and every other path, including the bare root, to the ingest Service. Adddata-otelonly if senders also need OTLP on 4317 and 4318 under this name.Code
Set these under http-input, not at the top level
A route under the top-level routes key is inherited by every component, so each one would claim *.data.monad.example.com and ingest requests could land on the console or the API instead.
Don't set rules on data: it would replace the chart's rules entirely and drop OTLP on 443 or root-path ingest. data-otel is not in the chart, so it inherits nothing from routes.default: enabled, type, pathType, hostnames, parentRefs and rules all have to be set. Leaving out type: http renders no route at all and reports no error.
-
Verify. The new route is named
http-input-data, andhttp-input-data-otelif you added it; your Gateway should accept both. Then send a record to a pipeline that has an HTTP input:CodeA 200 response with
{"status":"success","count":1}means the DNS record, certificate, listener and route are all in place.
Use an ingress controller instead
If your cluster routes with Kubernetes Ingress resources rather than Gateway API, start from an example values file, remove its routing and routes keys, and add:
Code
- Each of the five components gets its own Ingress for its own paths. They all answer on the first
hostnamesentry only. ingress.tlsnames the certificate Secret, which lives in the Monad namespace on an Ingress install. Without cert-manager, remove the annotation and create that Secret yourself.- The
hostnamesvalue still sets the backend URLs and the console origin. The chart's defaults set each component's Ingress host and paths, so you do not need to setingress.hosts. l4-inputstill needs thehttp-input-tlsSecret to start.
Check the result with kubectl get ingress -n monad, which should list api, docs, http-input, mcp and ui.
What an Ingress cannot carry
An Ingress routes HTTP requests by host and path, and the chart's Ingresses send each path to its component's first Service port. That leaves out syslog and OTLP:
| Traffic | Why the chart's Ingresses miss it | How to publish it |
|---|---|---|
| Syslog and other TLS over TCP | l4-input takes raw TCP and terminates TLS itself; an Ingress carries only HTTP | A LoadBalancer Service for l4-input (below), your ingress controller's own TCP passthrough to Service l4-input port 3335, or a Gateway |
| OTLP over gRPC and HTTP | OTLP is on http-input's second Service port, otel (4317) | A Gateway (below), or a proxy you configure that terminates TLS and forwards to Service http-input port 4317 |
| MCP server | Not an Ingress limit: the MCP server's Ingress is off by default | mcp.ingress.enabled: true, as in the values above |
The otel port speaks plaintext HTTP/2 (h2c) for OTLP over gRPC and HTTP/1.1 or HTTP/2 for OTLP over HTTP. It does not terminate TLS, so do not expose it directly; for gRPC, your ingress controller needs its setting for HTTP/2 backends.
On an Ingress, the api answers OAuth discovery for MCP clients at /.well-known/oauth-authorization-server/api/v2/oauth. The Gateway route also rewrites the bare /.well-known/oauth-authorization-server path to the api; the chart's Ingresses do not, so an MCP client that requests the bare path gets a 404 there.
Syslog through a LoadBalancer Service. Make l4-input's Service a LoadBalancer on port 6514, and point *.l4.monad.example.com at the address your cloud assigns it. l4-input.service.annotations and l4-input.service.loadBalancerClass take your cloud's load balancer settings.
Code
OTLP and syslog through a Gateway. If the cluster also runs a Gateway API implementation, keep the Ingresses for web traffic and attach only the OTLP and syslog routes to a Gateway with the otel-grpc, otel-https and tcp listeners from Configure your Gateway. Add this in place of the example's routing and routes keys:
Code
Per-pipeline ingest host on an Ingress
An Ingress can carry the per-pipeline host for HTTP ingest. Replace the http-input block in the Ingress values above with:
Code
Setting hosts and tls here replaces the chart's defaults for http-input, so the first host entry restates its usual paths. The wildcard gets a Secret of its own, which with cert-manager needs a DNS-01 issuer. Point *.data.monad.example.com at your ingress controller. OTLP and syslog do not reach that address, so they keep the forms in the "Without a per-pipeline host" column of Per-pipeline ingest host.
Gateway API route versions
HTTPRoutes always render at gateway.networking.k8s.io/v1. TCPRoutes and TLSRoutes render at v1 whenever the cluster serves that version; otherwise at v1alpha2 (TCPRoute) or v1alpha3 (TLSRoute) when the cluster serves that instead.
| Gateway API CRDs | TCPRoute versions served | TLSRoute versions served |
|---|---|---|
| Standard channel v1.4 and earlier | None | None |
| Standard channel v1.5 | None | v1 |
| Standard channel v1.6 and later | v1 | v1 |
| Experimental channel v1.3 and earlier | v1alpha2 | v1alpha2 |
| Experimental channel v1.4 | v1alpha2 | v1alpha2, v1alpha3 |
| Experimental channel v1.5 | v1alpha2 | v1, v1alpha2, v1alpha3 |
| Experimental channel v1.6 and later | v1, v1alpha2 | v1, v1alpha2, v1alpha3 |
A TLSRoute needs CRDs that serve v1 or v1alpha3.
The chart reads the versions the cluster serves when Helm installs or upgrades the release. Rendered with helm template, it cannot see the cluster and renders v1. For a cluster that serves TCPRoute only at v1alpha2, tell it so:
Code
Upgrading Gateway API CRDs
Helm cannot upgrade a release whose stored manifest uses an API version the cluster no longer serves. A release stores its TCPRoute at v1alpha2 when it was last installed or upgraded on CRDs that served only that version, or by an older chart. The standard channel from v1.6 does not serve v1alpha2. To see what your release stored:
Code
If it shows v1alpha2, move it to v1 before installing CRDs that stop serving the alpha versions:
- Install CRDs that serve both versions: the experimental channel, v1.6 or later.
- Run
helm upgradefor the release once, with chart version 2.96.1 or later and your usual values. The release now stores its TCPRoute atv1. - Install the CRDs you want.
If an upgrade already fails with no matches for kind "TCPRoute" in version "gateway.networking.k8s.io/v1alpha2", set served: true on that version in the CRD (kubectl edit crd tcproutes.gateway.networking.k8s.io), upgrade the release, then set it back to false.