# 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. :::note[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](/docs/guides/self-managed/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](#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](#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 `.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. :::tip[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-input` does not start without it.** `l4-input` runs on a default install and exits at startup until `http-input-tls` holds a valid key pair, even if you never publish syslog. In that case a self-signed certificate is enough. - **`l4-input` reads it only at startup.** After the certificate is renewed, restart `l4-input` so it serves the new one: `kubectl rollout restart deployment/l4-input -n monad`. To create the Secret from files you already have: ```bash kubectl create secret tls http-input-tls \ --cert= \ --key= \ -n monad ``` To make a self-signed key pair, for example when you do not publish syslog: ```bash openssl req -x509 -newkey rsa:2048 -nodes -days 365 \ -keyout tls.key -out tls.crt \ -subj "/CN=l4.monad.example.com" \ -addext "subjectAltName=DNS:l4.monad.example.com,DNS:*.l4.monad.example.com" ``` ### 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](https://cert-manager.io/docs/configuration/acme/dns01/). ```yaml apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: name: letsencrypt-dns spec: acme: server: https://acme-v02.api.letsencrypt.org/directory email: privateKeySecretRef: name: letsencrypt-dns solvers: - dns01: route53: {} ``` The Gateway certificate, in your Gateway's namespace: ```yaml apiVersion: cert-manager.io/v1 kind: Certificate metadata: name: monad-example-com-crt namespace: spec: secretName: monad-example-com-crt issuerRef: name: letsencrypt-dns kind: ClusterIssuer dnsNames: - monad.example.com ``` The syslog certificate, in the Monad namespace: ```yaml apiVersion: cert-manager.io/v1 kind: Certificate metadata: name: http-input-tls namespace: monad spec: secretName: http-input-tls issuerRef: name: letsencrypt-dns kind: ClusterIssuer dnsNames: - l4.monad.example.com - "*.l4.monad.example.com" ``` 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](https://cert-manager.io/docs/configuration/acme/http01/). 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: ```bash kubectl get certificate -n monad http-input-tls kubectl get certificate -n monad-example-com-crt ``` ## 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](/docs/guides/self-managed/before-you-install#operators-and-controllers) for the other controllers Monad needs, and [Gateway API route versions](#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](#per-pipeline-ingest-host) | The Gateway, with every listener but `data`: ```yaml apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: namespace: spec: gatewayClassName: listeners: - name: web port: 80 protocol: HTTP allowedRoutes: namespaces: from: All - name: websecure port: 443 protocol: HTTPS allowedRoutes: namespaces: from: All tls: mode: Terminate certificateRefs: - name: monad-example-com-crt - name: otel-grpc port: 4317 protocol: HTTPS allowedRoutes: namespaces: from: All tls: mode: Terminate certificateRefs: - name: monad-example-com-crt - name: otel-https port: 4318 protocol: HTTPS allowedRoutes: namespaces: from: All tls: mode: Terminate certificateRefs: - name: monad-example-com-crt - name: tcp port: 6514 protocol: TCP allowedRoutes: namespaces: from: All ``` 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: ```yaml routing: enabled: true parentRefs: - namespace: name: sectionName: websecure routes: otel: parentRefs: - namespace: name: sectionName: otel-grpc - namespace: name: sectionName: otel-https tcp: parentRefs: - namespace: name: sectionName: tcp ``` - `routing.enabled` renders Gateway API routes. `routing.parentRefs` is where every route attaches unless the route sets its own `parentRefs`. - `routes.default` is the HTTPRoute each web component renders for its own paths, on every `hostnames` entry. It attaches to `routing.parentRefs`. - `routes.otel` is rendered by `http-input` only and sends everything on the OTLP listeners to its OTLP port. Give it the OTLP listeners as above. Without its own `parentRefs`, it attaches to `routing.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, set `http-input.routes.otel.enabled` to `false` instead. - `routes.tcp` is rendered by `l4-input` only. Give it the TCP listener as above, or set `l4-input.routes.tcp.enabled` to `false` if 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: ```bash kubectl get httproute,tcproute -n monad kubectl describe httproute -n monad kubectl get gateway -n \ -o jsonpath='{range .status.listeners[*]}{.name}{"\t"}{.attachedRoutes}{"\n"}{end}' ``` 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: ```yaml - name: syslog-tls port: 6514 protocol: TLS tls: mode: Passthrough allowedRoutes: namespaces: from: All ``` 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: ```yaml l4-input: routes: tcp: enabled: false tls: enabled: true type: tls hostnames: - "*.l4.monad.example.com" parentRefs: - namespace: name: sectionName: syslog-tls rules: - backendRefs: - kind: Service name: l4-input port: 3335 ``` ## Per-pipeline ingest host Monad can serve each pipeline its own ingest hostname, `.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 `.data.`. `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/` | `https://.data.monad.example.com` | | OTLP | `https://monad.example.com:4318` or `:4317`, with the header `Monad-Pipeline-Id: ` (the `monad-pipeline-id` metadata key for gRPC) | `https://.data.monad.example.com`, or `:443` for gRPC exporters that need a port | | Syslog | `.l4.monad.example.com:6514` | `.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](#per-pipeline-ingest-host-on-an-ingress). 1. **DNS.** Point a wildcard record at the load balancer in front of your Gateway: ``` *.data.monad.example.com -> ``` HTTP and OTLP (443) and syslog (6514) use this name, so it has to resolve to a load balancer that carries both. 2. **Certificates.** The name has to be on both certificates, because HTTP and OTLP terminate at the Gateway while syslog terminates in the `l4-input` pod: - **Gateway certificate.** The `data` listener presents it, and so do the OTLP listeners if you add `data-otel`, so add `*.data.monad.example.com` to it. - **`http-input-tls`.** Syslog clients validate this one, so add the same name. With cert-manager, that is one more entry in each `dnsNames` list. The issuer needs a DNS-01 solver for both, because both now carry a wildcard. For `http-input-tls`: ```yaml dnsNames: - l4.monad.example.com - "*.l4.monad.example.com" - "*.data.monad.example.com" ``` 3. **Gateway listener.** Add an HTTPS listener for the wildcard name to your Gateway: ```yaml - name: data hostname: "*.data.monad.example.com" port: 443 protocol: HTTPS allowedRoutes: namespaces: from: All tls: mode: Terminate certificateRefs: - name: monad-example-com-crt ``` The OTLP listeners and the `tcp` listener need no change. They carry no hostname, so they already accept connections for any name that resolves to them. 4. **Values.** Turn on `http-input`'s `data` route, which the chart ships from version 2.104.0, and point it at the `data` listener. It answers on `*.data.` plus your first `hostnames` entry, so here `*.data.monad.example.com`; set `hostnames` on 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. Add `data-otel` only if senders also need OTLP on 4317 and 4318 under this name. ```yaml http-input: routes: data: enabled: true parentRefs: - namespace: name: sectionName: data # Optional: only to also accept OTLP on 4317 and 4318 under this name. data-otel: enabled: true type: http pathType: PathPrefix hostnames: - "*.data.monad.example.com" parentRefs: - namespace: name: sectionName: otel-grpc - namespace: name: sectionName: otel-https rules: - matches: - path: value: / backendRefs: - kind: Service name: http-input port: 4317 ``` :::warning[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. ::: 5. **Verify.** The new route is named `http-input-data`, and `http-input-data-otel` if you added it; your Gateway should accept both. Then send a record to a pipeline that has an HTTP input: ```bash kubectl get httproute -n monad curl -i --request POST \ --url https://.data.monad.example.com \ --header 'authorization: ApiKey ' \ --data '{"hello":"world"}' ``` A 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: ```yaml ingress: className: annotations: cert-manager.io/cluster-issuer: tls: - secretName: monad-example-com-crt hosts: - monad.example.com api: ingress: enabled: true docs: ingress: enabled: true http-input: ingress: enabled: true mcp: ingress: enabled: true ui: ingress: enabled: true ``` - Each of the five components gets its own Ingress for its own paths. They all answer on the first `hostnames` entry only. - `ingress.tls` names 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 `hostnames` value 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 set `ingress.hosts`. - `l4-input` still needs the [`http-input-tls` Secret](#syslog-certificate) 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. ```yaml l4-input: service: type: LoadBalancer ports: - name: tls port: 6514 targetPort: tls appProtocol: tls ``` **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](#configure-your-gateway). Add this in place of the example's `routing` and `routes` keys: ```yaml routing: enabled: true routes: default: enabled: false otel: parentRefs: - namespace: name: sectionName: otel-grpc - namespace: name: sectionName: otel-https tcp: parentRefs: - namespace: name: sectionName: tcp ``` ### 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: ```yaml http-input: ingress: enabled: true hosts: - host: monad.example.com paths: - path: /api/v2/http/send pathType: Prefix - path: /services/collector pathType: Prefix - host: "*.data.monad.example.com" paths: - path: / pathType: Prefix tls: - secretName: monad-example-com-crt hosts: - monad.example.com - secretName: data-monad-example-com-crt hosts: - "*.data.monad.example.com" ``` 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](#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: ```bash helm template oci://registry-1.docker.io/monadinc/monad --version \ -n monad -f \ --api-versions gateway.networking.k8s.io/v1alpha2/TCPRoute ``` ### 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: ```bash helm get manifest -n monad | grep -B1 'kind: TCPRoute' ``` If it shows `v1alpha2`, move it to `v1` before installing CRDs that stop serving the alpha versions: 1. Install CRDs that serve both versions: the experimental channel, v1.6 or later. 2. Run `helm upgrade` for the release once, with chart version 2.96.1 or later and your usual values. The release now stores its TCPRoute at `v1`. 3. 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`.