Set up networking and ingress for Lumi Enterprise on OpenShift

info

This information applies to Imply Lumi Enterprise deployments on OpenShift.
Lumi Enterprise on OpenShift is an early access feature.

The Lumi Helm chart deploys the Imply Lumi Enterprise services, including the Kong API gateway that receives incoming traffic. For external traffic to reach the gateway, you need to set up the following networking outside the Lumi Helm chart:

• Hostnames
• TLS certificate
• Ingress controller
• Load balancer
• DNS records

If you configure any of these systems incorrectly, Lumi might be unreachable.

This topic explains how network traffic reaches Lumi Enterprise on OpenShift and how to configure each of the networking systems.

In this topic, placeholder values are shown in uppercase—for example, INGRESS_CLASS. Replace them with values for your own environment.

How traffic reaches Lumi

Lumi Enterprise uses Kong as an API gateway to route incoming traffic to its internal services.

The following diagram shows how traffic flows from the load balancer to Kong. Blue boxes represent components you manage, and yellow boxes represent components Lumi manages.

The following components route your traffic to Kong:

• Load balancer provides the address that clients connect to.
• Ingress controller reads Ingress rules and routes traffic to the correct service.
• Ingress maps a hostname to a service inside the cluster.
• Kong service receives the traffic and routes it to internal services in Lumi.

OpenShift includes a default ingress controller, managed by the Ingress Operator. To receive traffic from outside the cluster, an ingress controller needs an external address. One way to provide that address is by using a LoadBalancer service. For more information, see Ingress Operator in OpenShift Container Platform in the OpenShift documentation.

info

Splunk S2S traffic doesn't go through Kong. For more information, see Splunk S2S over TCP.

Ports Kong exposes

By default, the Kong proxy runs as a Kubernetes ClusterIP Service, reachable only from inside the cluster. You can change the service type with gateway.service.type.

Depending on whether you set gateway.tls.secretName in your Helm values, service port 443 forwards to the following container ports:

• No gateway.tls.secretName (default): Service port 443 forwards to container port 8000, Kong's plaintext listener. The chart's Ingress routes here, after the ingress controller has ended TLS.
• With gateway.tls.secretName: Service port 443 forwards to container port 8443. Kong ends TLS with your certificate.

For more information about Kubernetes networking concepts, see Services, Load Balancing, and Networking in the Kubernetes documentation.

Ingress, DNS, and TLS values

The following table shows the values you configure in values.yaml to control ingress, DNS, and TLS for Lumi:

Value	Default	Effect
ingress.host	""	Sets the hostnames the Ingress serves. Lumi derives all three hosts from this value.
ingress.className	kong	Ingress class for the Ingress resources that the Lumi gateway manages. When empty, the gateway uses kong. Set a different value only if this cluster already runs its own Kong.
gateway.ingress.enabled	false	When true, the Lumi Helm chart creates the Ingress that routes traffic to Kong. The chart creates no Ingress by default.
gateway.ingress.className	""	Ingress class for that Ingress. See Ingress controller for more information.
gateway.ingress.hosts	[]	Hosts for the Ingress. If left blank, Lumi uses the three hosts it derives from ingress.host.
gateway.service.type	ClusterIP	Service type for the Kong proxy. One of ClusterIP, LoadBalancer, or NodePort.
gateway.tls.secretName	""	Name of a kubernetes.io/tls secret in the Lumi namespace. When set, Kong terminates TLS on service port 443 with this certificate.

Note the difference between the following similar-looking settings:

• ingress.className controls routing inside the cluster, after traffic already reaches Kong.
• gateway.ingress.className controls routing external traffic to Kong. It's the single entry point for traffic to Kong.

Hostnames

Pick a hostname for Lumi, for example lumi.example.com, and set it as ingress.host. Lumi serves traffic on the following hostnames:

• ingress.host
• *.ingress.host
• *.spl.ingress.host

If you leave gateway.ingress.hosts empty, Lumi builds the hostnames from ingress.host. If you supply your own gateway.ingress.hosts list, Lumi doesn't derive the hostnames, so make sure your list includes the same three hostnames.

You create DNS records for these hostnames after you set up your load balancer. See DNS records.

Certificates and TLS

The Lumi chart doesn't create a certificate. Create one certificate that lists all three Lumi hostnames as Subject Alternative Names (SANs), and store it in a Kubernetes secret. How you issue the certificate is your choice. If the certificate doesn't list a hostname, clients reject connections to it.

info

On certificates, a wildcard covers only one level of subdomain. For example, *.ingress.host covers api.ingress.host but not api.spl.ingress.host, so the certificate must list *.spl.ingress.host separately.

If TLS ends at the ingress controller, point your ingress controller at the secret by setting the defaultCertificate value of your IngressController to the name of the secret.

The secret must meet the following conditions:

• Be of type kubernetes.io/tls.
• Reside in the openshift-ingress namespace because the controller reads it from there.
• The name of the secret must match the defaultCertificate value of the IngressController. In the example in Ingress controller, the value is lumi-wildcard-tls, so the secret is named lumi-wildcard-tls.

Ingress controller

An Ingress is a set of routing rules. It has no effect until an ingress controller claims it and routes traffic according to its rules. The value for gateway.ingress.className specifies which ingress controller claims the Lumi Ingress. If you leave it empty, the chart creates the Ingress rule without a class.

Two of Lumi hostnames are wildcard hostnames. Not every ingress controller accepts wildcard hostnames. On OpenShift, the default ingress controller accepts them only if its wildcard policy is set to WildcardsAllowed.

If your cluster already runs an ingress controller that accepts wildcard hostnames, set the value of gateway.ingress.className to its class. Otherwise, create an ingress controller that accepts wildcard hostnames.

The following example shows an ingress controller that accepts wildcard hostnames and serves only the Lumi namespace:

apiVersion: operator.openshift.io/v1
kind: IngressController
metadata:
  name: lumi-external
  namespace: openshift-ingress-operator
spec:
  domain: lumi.example.com               # matches ingress.host
  routeAdmission:
    wildcardPolicy: WildcardsAllowed
  defaultCertificate:
    name: lumi-wildcard-tls              # TLS secret covering the three hosts below
  namespaceSelector:
    matchLabels:
      kubernetes.io/metadata.name: lumi  # your Lumi namespace
  endpointPublishingStrategy:
    type: LoadBalancerService

When you create an IngressController, OpenShift automatically creates an ingress class named openshift-NAME, where NAME is the name of the controller. For example, an IngressController named lumi-external gets the class openshift-lumi-external.

Set gateway.ingress.className to that class, so that the controller claims the Lumi Ingress. Then set the route.openshift.io/termination annotation based on where you want TLS to end, at the ingress controller or at Kong.

The following examples show both options:

TLS ends at the ingress controller (default)

Use edge if you don't set gateway.tls.secretName. The ingress controller decrypts the traffic with its certificate and sends plain HTTP to Kong.

gateway:
  ingress:
    enabled: true
    className: openshift-lumi-external
    annotations:
      route.openshift.io/termination: edge

TLS ends at Kong

Use passthrough if you set gateway.tls.secretName. The ingress controller forwards the encrypted traffic unchanged, and Kong decrypts it with your certificate.

gateway:
  ingress:
    enabled: true
    className: openshift-lumi-external
    annotations:
      route.openshift.io/termination: passthrough

Load balancer

You can use any load balancer that can route HTTPS to the OpenShift router or directly to a Kubernetes LoadBalancer service.

If you route through the OpenShift router, expose Lumi through an IngressController. See Ingress controller.

Alternatively, you can have the chart expose the gateway as a LoadBalancer service instead of creating an Ingress. This requires a load balancer implementation, such as MetalLB on bare metal.

When you expose the gateway as a LoadBalancer service, you must set gateway.tls.secretName. Without an ingress controller in front of Kong, Kong ends TLS itself, so it needs your certificate. If gateway.tls.secretName isn't set, the chart fails to render.

To expose the gateway as a LoadBalancer service, add the following configuration to your values.yaml:

ingress:
  host: lumi.HOSTNAME

gateway:
  service:
    type: LoadBalancer
    annotations: {}   # load balancer-specific annotations
  tls:
    secretName: TLS_SECRET_NAME

In this configuration, ingress.host sets the hostname Lumi serves traffic on. Replace HOSTNAME with the hostname you chose in Hostnames. If your load balancer needs specific settings, add them under annotations. Replace TLS_SECRET_NAME with the name of the kubernetes.io/tls secret that contains your certificate.

Start with the following settings for the gateway load balancer unless otherwise directed:

• Listeners: Open port 443 for TLS gateway traffic.
• Idle timeout: Set to 600 seconds to support long-running queries.
• Health checks: Use TCP checks against the gateway target.

If you use Splunk forwarders, the event collector needs a separate load balancer for S2S traffic on port 9997. See Splunk S2S over TCP.

For more information, see the following OpenShift documentation:

• Routes
• Configuring ingress cluster traffic
• Configuring certificates
• Load balancing with MetalLB

DNS records

After you set up your load balancer, create DNS records that point the Lumi hostnames to the address of the load balancer. If you route through an IngressController, use the address of the load balancer for that ingress controller. If you expose the gateway as a LoadBalancer service, use the address of that service.

A wildcard record for *.ingress.host also covers *.spl.ingress.host, so you need two records: one for ingress.host and one for *.ingress.host.

Splunk S2S over TCP

If you send data to Lumi from Splunk® forwarders, you need to expose a separate endpoint for them. Splunk-to-Splunk (S2S) is the protocol Splunk forwarders use to send data. S2S uses plain TCP, so its traffic bypasses Kong and goes directly to the event collector. Therefore, it needs its own service and load balancer.

Add the following configuration to your values.yaml:

eventCollector:
  s2s:
    service:
      type: LoadBalancer
    tls:
      secretName: lumi-s2s-tls

Setting type: LoadBalancer gives the service an external address. On bare-metal OpenShift, this requires a load balancer implementation in your cluster. If your load balancer needs specific settings, add them as annotations on the service. The service exposes TCP port 9997 used for connections from Splunk forwarders.

Choose a hostname for S2S traffic, such as splunk-tcp.lumi.example.com, and create a DNS record that points it to the load balancer address. Configure your forwarders to send data to this hostname on port 9997.

The tls.secretName value names a kubernetes.io/tls secret that you create. This certificate covers only the S2S hostname and is separate from the ingress certificate. If you don't set tls.secretName, the listener accepts plain TCP.

Next step

After you set up networking and ingress, continue to Size and prepare nodes.