Network, DNS, and ports

Design client entry points and dependency connectivity before installation. Koldan exposes HTTP and gRPC separately; publish only the interfaces clients require and keep management and dependency endpoints private.

Define the network zones

Document which networks contain:

• HTTP clients and browser users.
• gRPC clients.
• Ingress controllers, OpenShift routers, or external load balancers.
• Koldan workloads and cluster monitoring.
• PostgreSQL, Temporal, object storage, the identity provider, and optional providers.

For each flow, record the source, destination hostname, protocol, port, TLS termination point, certificate owner, firewall owner, and verification method. Use the rendered Helm manifest to identify all Services created by the selected values.

Client entry points

The HTTP and gRPC hostnames can be separate. Certificates must contain every client-visible hostname in their Subject Alternative Name extension.

Publish the address clients use

Set these application properties to the address, port, and TLS state visible to clients:

• koldan.api-http.advertisement.address, .port, and .ssl
• koldan.api-grpc.advertisement.address, .port, and .ssl

When web.ingress.enabled is true, the chart derives the HTTP advertisement from the first configured Ingress host and its TLS setting. Set the values explicitly in config for Routes, external load balancers, and any deployment where the derived address is not the client-visible address. Always set the gRPC advertisement when clients connect through an external endpoint.

Advertised names must resolve from every client network and must match the serving certificate. Do not advertise a pod IP, ClusterIP, or internal service name to external clients.

Dependency and management traffic

Allow Koldan pods to resolve and connect to the actual configured endpoints. Common defaults are listed below; external service configuration takes precedence.

Health and Prometheus endpoints use workload management ports and must remain private. The HTTP and gRPC management ports are 5193 and 5195; worker-pool management ports are configurable through workerPools.<pool>.managementPort. Allow access only from cluster health checks and approved monitoring collectors. See Operational endpoints for the complete operator-facing list.

Ingress, Route, and load-balancer requirements

HTTP

Configure one public path for the HTTP endpoint:

• Kubernetes Ingress: web.ingress.*
• OpenShift Route: web.route.*, with web.ingress.enabled: false
• Direct service exposure: web.service.*

Size request-body limits and connection, read, and send timeouts for the largest supported upload and longest expected request. Preserve the original host and forwarding information required by the identity redirect flow. Reject plaintext external traffic or redirect it to HTTPS according to platform policy.

gRPC

The network path must carry HTTP/2 gRPC traffic for the full expected session duration. Confirm all proxies and load balancers support:

• HTTP/2 and gRPC end to end.
• The selected TLS termination mode.
• Idle, request, and graceful-drain timeouts longer than normal sessions.
• Connection draining during rollout or scale-down.

For OpenShift, configure grpc.route.*. For Kubernetes, configure grpc.service.* and the platform's supported gRPC-capable load balancer or ingress resource. The chart does not create a Kubernetes Ingress resource for gRPC.

TLS design

Choose and document one termination model for each external endpoint:

• Edge termination: the router or load balancer serves the public certificate and connects to the backend using the configured backend protocol.
• Re-encryption: the router terminates client TLS and establishes a second trusted TLS connection to the backend.
• Passthrough: the Koldan backend serves the client-facing certificate directly.

The Route or load-balancer configuration, grpc.certificate.*, and the application TLS properties must agree. A mismatch commonly appears as TLS handshake failures, HTTP/2 downgrade, or readiness that succeeds internally while external gRPC calls fail.

For outbound connections to services issued by a private CA, enable customCA and install the issuing chain. Keep hostname verification enabled. See TLS and custom CAs.

NetworkPolicy baseline

For namespaces using default-deny policies, allow only the required flows:

• Ingress-controller, router, or load-balancer traffic to the HTTP and gRPC Services.
• Cluster health checks and monitoring collectors to management ports.
• DNS from Koldan pods to the cluster DNS service.
• Koldan egress to PostgreSQL, Temporal, object storage, OIDC endpoints, enabled search and coordination services, container registries where runtime pulls require it, and configured optional providers.
• Traffic among the rendered Koldan Services and workloads required by the selected release.

Do not expose management ports, database ports, Temporal administration, object-storage consoles, or search and coordination services to public networks. If an administrative interface is required, place it behind the organization's authenticated administrative access path.

DNS and certificate checklist

• Create stable records for the HTTP and gRPC endpoints before identity-provider redirects and certificates are finalized.
• Use private DNS for internal dependencies and public or split-horizon DNS only where clients require it.
• Confirm forward resolution from Koldan pods and from every intended client network.
• Ensure certificate SANs match the names clients and Koldan actually use; aliases not present in the certificate will fail hostname verification.
• Serve the complete chain, including intermediate certificates.
• Monitor certificate expiry and rehearse rotation without changing the advertised endpoint.

Verify before production traffic

Inspect the deployed resources:

kubectl get services,ingresses,endpointslices -n koldan
kubectl get networkpolicies -n koldan

On OpenShift, also inspect Routes:

oc get routes -n koldan

From each client network, verify DNS and TLS for both public endpoints. For example:

openssl s_client -connect api.example.com:443 -servername api.example.com
openssl s_client -connect grpc.example.com:443 -servername grpc.example.com -alpn h2

Use an approved diagnostic pod in the Koldan namespace to verify DNS, TCP connectivity, TLS hostname validation, and authentication to every external dependency. Finish with supported HTTP and gRPC client smoke tests; a successful TCP or TLS handshake alone does not prove application readiness.

Diagnose common failures

Continue with Install with Helm after all required network flows have an owner and a verification method.