Expose Geocore Services

Contour and its Envoy proxy expose the Geocore API and Centui over HTTP(S). Envoy translates Centui’s gRPC-Web calls into gRPC requests for the API. MQTT and NTP are not routed through Contour: keep their NodePort configuration in the k0s guide. For all exposure choices, see Service Exposure.

1. Install Contour and Envoy

Contour is required for the documented Geocore access path. The geocore-ingress-contour chart only creates Geocore routes; it does not install Contour or Envoy. Keep the Geocore API and Centui services as their default ClusterIP services.

Create Harbor image-pull credentials

Contour and Envoy images are hosted in Centiloc Harbor. Create the contour namespace, then create a Docker registry secret in that namespace:

kubectl create namespace contour

kubectl create secret docker-registry harbor-regcred \
  --namespace contour \
  --docker-server=harbor.centiloc.com \
  --docker-username=<username> \
  --docker-password=<password> \
  --docker-email=<email>

The secret is namespace-scoped: it must be created before installing Contour, and it is distinct from the credentials used by Helm to download charts.

LoadBalancer

Use this option when the Kubernetes platform, or MetalLB, provides a LoadBalancer address:

helm install contour oci://harbor.centiloc.com/bitnamicharts/contour \
  --namespace contour \
  --version 21.1.4 \
  --set contour.certgen.certificateLifetime=2190 \
  --set 'global.imagePullSecrets[0]=harbor-regcred'

NodePort

Use this option for a plain HTTP single-node installation. Envoy is exposed on NodePort 30180:

helm install contour oci://harbor.centiloc.com/bitnamicharts/contour \
  --namespace contour \
  --version 21.1.4 \
  --set contour.certgen.certificateLifetime=2190 \
  --set 'global.imagePullSecrets[0]=harbor-regcred' \
  --set envoy.service.type="NodePort" \
  --set envoy.service.nodePorts.http="30180"

Alternative gRPC-Web proxy

An alternative proxy such as grpcwebproxy may be used instead of Contour and geocore-ingress-contour. Its installation and configuration are not covered here.

2. Choose plain HTTP or TLS

Envoy can publish the API and Centui in plain HTTP or with TLS termination. The choice must match the core.geo.tlsEnabled and core.centui.tlsEnabled values configured in the k0s guide.

Ingress transport	`core.geo.tlsEnabled` and `core.centui.tlsEnabled`	Routing chart `tlsEnabled`
Plain HTTP	`false`	`false`
TLS	`true`	`true`

Continue with the following TLS sections only when using HTTPS. For plain HTTP, skip directly to Create Geocore routes.

3. Configure TLS

The following steps describe one self-managed TLS option for a single-node cluster. If your infrastructure already provides certificates and an Ingress Controller, use its existing certificate-management workflow instead.

Install cert-manager

Install cert-manager to manage certificates in the cluster:

helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set installCRDs=true

Create a Geocore PKI

Create a geocore-pki.yaml file. This example creates a self-signed root CA and an intermediate issuer for Geocore certificates:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: selfsigned-issuer
  namespace: cert-manager
spec:
  selfSigned: {}

---

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: root-ca
  namespace: cert-manager
spec:
  isCA: true
  dnsNames:
    - X.X.X.X
  subject:
    organizations:
      - YourOrganization
    countries:
      - FR
  commonName: Root CA Issuer
  secretName: root-ca-secret
  duration: 864000h
  renewBefore: 700000h
  privateKey:
    algorithm: ECDSA
    size: 256
  issuerRef:
    name: selfsigned-issuer
    kind: ClusterIssuer
    group: cert-manager.io

---

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: root-ca-issuer
  namespace: cert-manager
spec:
  ca:
    secretName: root-ca-secret

---

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: geocore-cert
  namespace: cert-manager
spec:
  isCA: true
  subject:
    organizations:
      - Your Organization Name
    countries:
      - Your Country Name
  commonName: Geocore Intermediate Issuer
  secretName: geocore-cert-secret
  duration: 438000h
  renewBefore: 420000h
  privateKey:
    algorithm: ECDSA
    size: 256
  issuerRef:
    name: root-ca-issuer
    kind: ClusterIssuer
    group: cert-manager.io

---

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: geocore-issuer
  namespace: cert-manager
spec:
  ca:
    secretName: geocore-cert-secret

k0s IP address

Replace X.X.X.X with the IP address of the k0s single-node cluster before applying the manifest.

Apply the PKI:

kubectl apply -f geocore-pki.yaml

Trust the certificate authority

When using self-signed certificates, add the generated CA certificate to the trust store of every client that accesses the API or Centui.

4. Provide a LoadBalancer address

On a single-node cluster, MetalLB can assign an external IP address to a LoadBalancer service. Skip this section if your Kubernetes platform already provides load balancers.

Install MetalLB:

helm repo add metallb https://metallb.github.io/metallb
helm repo update
helm install my-metallb metallb/metallb \
  --namespace metallb \
  --create-namespace \
  --version 0.13.11

Create a metallb-ipaddresspool.yaml file and replace X.X.X.X with the address assigned to the k0s host:

apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
  name: geocore-pool
  namespace: metallb
spec:
  addresses:
    - X.X.X.X/32

Apply the address pool:

kubectl apply -f metallb-ipaddresspool.yaml

5. Create Geocore routes

After Contour is ready, create an ingress-values.yaml file. Select the tab matching the Envoy exposure method chosen in the Geocore chart.

Plain HTTP

certmanager:
  enabled: false

tlsEnabled: false

api:
  domain: api.local.centiloc.com

centui:
  domain: centui.local.centiloc.com

TLS

certmanager:
  enabled: true
  issuer:
    name: geocore-issuer

tlsEnabled: true

api:
  domain: api.local.centiloc.com

centui:
  domain: centui.local.centiloc.com

Install the routing chart:

helm install geocore-ingress-contour \
  oci://harbor.centiloc.com/centiloc/geocore-ingress-contour \
  --namespace geocore \
  -f ingress-values.yaml

Host name consistency

The api.domain and centui.domain values must match the corresponding host names in the Geocore chart configuration. With an Envoy NodePort, add the Envoy port to core.centui.apiURL, for example api.k0s.example.test:30180; do not add that port to api.domain.

6. Publish DNS records

Point the public DNS records to the external address of Envoy:

<ingress-controller-IP> api.local.centiloc.com
<ingress-controller-IP> centui.local.centiloc.com

For a local proof of concept, the same entries can be added to the client machine’s hosts file. In production, create the equivalent DNS records in your DNS zone.

7. Verify access

Once the records resolve to Envoy, open Centui at its configured URL and verify that API requests succeed. If either service is unavailable, first confirm that Envoy exposes its external address, then check the Geocore routing chart and the FQDN values.