Configure HTTPS / TLS Termination

HTTPS is required for production Okareo Standalone deployments. OIDC providers require a secure redirect URI, and browsers will not send SSO cookies over plain HTTP. The Helm chart accepts any TLS certificate: corporate internal CA, cert-manager, or manually provisioned and any ingress routing topology you need.

This page covers:

• Provisioning a TLS certificate for your cluster.
• Configuring the Ingress with TLS.
• Updating application URLs to use HTTPS.
• Trusting a private CA when your organization uses one.

Prerequisites

• A working Okareo Standalone deployment per the Kubernetes deploy guide.
• An ingress controller installed in the cluster (for example, ingress-nginx).
• A TLS certificate and private key for your chosen hostname(s).
• A DNS name (or names) resolving to the ingress controller's external IP.

1) Provision a TLS certificate

Okareo needs a Kubernetes TLS secret containing the certificate and private key for your hostname(s). How you provision that secret depends on your environment:

Method	When to use
cert-manager with a ClusterIssuer (recommended)	Automates certificate issuance, renewal, and secret creation. Add a cert-manager.io/cluster-issuer annotation to the Ingress and cert-manager populates the TLS secret automatically. No manual secret step needed.
Corporate internal CA	Your organization issues certs from a private PKI. Create the secret from the issued cert and key (see below).
Manually provisioned certificate	You obtained a cert out-of-band from a commercial CA or internal process. Create the secret from the issued cert and key (see below).

For cert-manager setups, skip to Step 2 and add the ClusterIssuer annotation to your ingress values.

For manual certificate provisioning, create the secret directly:

kubectl -n "$NS" create secret tls okareo-tls \
  --cert=<PATH_TO_CERT_PEM> \
  --key=<PATH_TO_KEY_PEM>

2) Enable ingress with TLS

Add or merge the following into your Helm values file. Adjust hostnames, paths, and annotations to match your environment:

ingress:
  frontend:
    enabled: true
    className: nginx
    annotations:
      nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
      nginx.ingress.kubernetes.io/ssl-redirect: "true"
    hosts:
      - host: <OKAREO_HOST>
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: okareo-tls
        hosts:
          - <OKAREO_HOST>

  services:
    enabled: true
    className: nginx
    annotations:
      nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
      nginx.ingress.kubernetes.io/ssl-redirect: "true"
    hosts:
      - host: <OKAREO_API_HOST>
        paths:
          - path: /v0
            pathType: Prefix
          - path: /v1
            pathType: Prefix
    tls:
      - secretName: okareo-tls
        hosts:
          - <OKAREO_API_HOST>

Replace <OKAREO_HOST> and <OKAREO_API_HOST> with your DNS names. These may be the same hostname (path-based routing) or separate hostnames (host-based routing) depending on your network topology.

3) Update application URLs

Set the HTTPS URLs so the application knows its own addresses:

config:
  okareoAppDomain: "https://<OKAREO_HOST>"
  okareoApiGateway: "https://<OKAREO_API_HOST>"

Value	Purpose
okareoAppDomain	The browser-facing frontend URL. Used for CORS allowed origins and SSO redirect URIs.
okareoApiGateway	The URL the frontend uses to reach the API. May be the same host with a path prefix, or a separate host.

4) Apply

Run the Helm upgrade with your updated values:

helm upgrade --install <RELEASE_NAME> ./helm/okareo-standalone \
  -n "$NS" \
  -f okareo-values.yaml \
  --wait --timeout 20m

If using split releases, apply the updated values to both the services and frontend releases.

5) Verify

Confirm TLS is working without certificate warnings:

curl -sS -o /dev/null -w "%{http_code}\n" "https://<OKAREO_HOST>"
curl -sS -o /dev/null -w "%{http_code}\n" "https://<OKAREO_API_HOST>/v0/health"

Expected:

• Both commands succeed without --insecure.
• Frontend returns 200 or 307 (redirect to login).
• API health returns a success status code.

If curl reports a certificate error, verify that your DNS resolves to the ingress controller IP and that the TLS secret contains the correct certificate chain.

Private PKI: trusting your internal CA

Organizations that issue TLS certificates from a corporate CA need one extra step. The Okareo frontend pod makes server-side requests to the API through the ingress. If that TLS certificate is signed by a private CA, the frontend's Node.js runtime must be told to trust it.

Mount the CA bundle into the frontend pod and set NODE_EXTRA_CA_CERTS:

frontend:
  extraEnv:
    - name: NODE_EXTRA_CA_CERTS
      value: /etc/ssl/custom/ca-bundle.crt
  extraVolumeMounts:
    - name: ca-bundle
      mountPath: /etc/ssl/custom/ca-bundle.crt
      subPath: ca-bundle.crt
      readOnly: true
  extraVolumes:
    - name: ca-bundle
      configMap:
        name: <CA_CONFIGMAP_NAME>

Create the ConfigMap from your CA certificate file:

kubectl -n "$NS" create configmap <CA_CONFIGMAP_NAME> \
  --from-file=ca-bundle.crt=<PATH_TO_CA_PEM>

Skip this section if your certificate is from a publicly-trusted CA (DigiCert, Entrust, or another commercial CA).

Reference: Helm values

Value	Description
ingress.frontend.enabled	Create an Ingress resource for the frontend.
ingress.frontend.className	Ingress class (e.g. nginx).
ingress.frontend.annotations	Arbitrary annotations (SSL redirect, cert-manager issuer, etc.).
ingress.frontend.hosts	List of host/path rules for the frontend.
ingress.frontend.tls	TLS configuration referencing a secret and hostnames.
ingress.services.enabled	Create an Ingress resource for the API services.
ingress.services.className	Ingress class for services.
ingress.services.annotations	Annotations for the services ingress.
ingress.services.hosts	List of host/path rules for the API.
ingress.services.tls	TLS configuration for the services ingress.
config.okareoAppDomain	Browser-facing frontend URL (used for CORS and SSO redirects).
config.okareoApiGateway	URL the frontend uses to call the API.
frontend.extraVolumeMounts	Mount volumes into the frontend container (e.g. CA bundles).
frontend.extraVolumes	Define volumes for the frontend pod.

---

Next step: Single Sign-On (SSO)

Related: Deploy on Kubernetes | Model Configuration