Service Exposure

An OnPremise Geocore installation has four external entry points. Decide how each one is exposed before installing the chart: the choice determines the Helm values, DNS records, certificates, and firewall rules.

Service exposure at a glance

Service	Used by	Protocol	Supported exposure
MQTT	Boards and external MQTT clients, including Transtream consumers	TCP or TLS	NodePort only
NTP	Boards	UDP port 123	NodePort only
API	Native API clients	gRPC	Direct NodePort, or Contour/Envoy
API	Centui	gRPC-Web	Contour/Envoy only
Centui	Web browsers	HTTP	Contour/Envoy only

Ingress scope

MQTT and NTP must remain directly reachable through NodePorts; they are not routed through an Ingress Controller. API and Centui traffic goes through Contour’s Envoy proxy.

MQTT and NTP

Boards must reach MQTT directly, and the Geocore NTP service must be directly reachable on UDP port 123. Configure both services as NodePorts. On a single-node cluster, MQTT and NTP use the k0s host address; redirect host UDP port 123 to the NTP NodePort when required by the cluster network.

Use the single-node k0s guide for the MQTT, NTP, and host redirect configuration. The same direct MQTT endpoint can also be used by external MQTT clients.

API and Centui through Envoy

Centui is a browser application that connects to the API using gRPC-Web, while the Geocore API serves gRPC. The Envoy proxy managed by Contour converts the browser requests to gRPC before sending them to the internal API service.

Browser ──Centui host──> Envoy (Contour) ──> Centui (ClusterIP)
       └─API host─────> Envoy (gRPC-Web → gRPC) ──> API (ClusterIP)

This makes Contour and geocore-ingress-contour the standard Geocore access path. Keep the Geocore API and Centui services as ClusterIP; do not point Centui directly at the API NodePort.

Centui needs two public addresses:

core.centui.apiURL: the Envoy address used by Centui to reach the API. Add the Envoy NodePort when the Envoy service uses NodePort.
core.centui.centuiURL: the host name used by browsers to reach Centui.

Both host names must resolve to Envoy: its LoadBalancer address for a standard installation, or the Kubernetes node for an Envoy NodePort installation.

Chart naming

In the current Geocore chart, these values are under core:. Some older chart documentation refers to this dependency as front:; that key is not used by the current chart.

Available access patterns

Pattern	Geocore services	TLS setting	Public address
Contour Envoy NodePort	Default `ClusterIP` services	`core.geo.tlsEnabled: false` and `core.centui.tlsEnabled: false`	HTTP host names and the Envoy NodePort
Contour Envoy LoadBalancer	Default `ClusterIP` services	`core.geo.tlsEnabled: false` and `core.centui.tlsEnabled: false`	HTTP host names managed by Envoy
Contour Envoy with TLS	Default `ClusterIP` services	`core.geo.tlsEnabled: true` and `core.centui.tlsEnabled: true`	HTTPS host names; TLS terminates at Envoy

For NodePort access, configure the NodePort on the Contour Envoy service, not on core.service. Set core.centui.apiURL to the API host name and Envoy NodePort, as shown in the k0s guide.

Install geocore-ingress-contour to create the API and Centui routes. The Ingress guide provides the Contour setup and both the plain HTTP and TLS configurations.

Alternative gRPC-Web proxy

You may use another gRPC-Web proxy, such as grpcwebproxy, instead of the Contour and geocore-ingress-contour path. Its deployment, routing, CORS settings, and lifecycle are outside the scope of this documentation.

Address consistency

Use stable DNS names whenever possible. For a local proof of concept, add the API and Centui names to the client machine’s hosts file. The configured names must resolve consistently from every board, browser, and external client that needs them.