#Configure TLS

This guide covers the TLS-related configuration of Alauda Hyperflux for its outbound connections: the LLM service, the reranker, MCP servers and PostgreSQL.

The most common need — trusting an LLM or MCP endpoint that uses an internal or self-signed certificate — is solved with Extra CA ConfigMaps, available directly in the installation form. For test environments, certificate verification for LLM calls can also be skipped entirely (see the last section).

#Trust an internal / self-signed CA (Extra CA ConfigMaps)

If your LLM, reranker or MCP endpoint presents a certificate signed by an internal CA, requests fail with CERTIFICATE_VERIFY_FAILED. Add the CA certificate to the trust bundle:

1. Create a ConfigMap holding the CA certificate (PEM) in the namespace where Alauda Hyperflux is installed (cpaas-system). CA certificates are public, so a ConfigMap — not a Secret — is appropriate. One ConfigMap can hold multiple *.pem keys:

   kubectl create configmap my-org-internal-ca -n cpaas-system \
     --from-file=ca.pem=/path/to/internal-ca.pem

2. In Administrator / Marketplace / Cluster Plugins, install or update the Alauda Hyperflux plugin and add the ConfigMap name under Extra CA ConfigMaps. The service restarts automatically.

Each listed ConfigMap is mounted read-only at /opt/extra-ca/<configmap-name>/. At startup the certificates are merged with the default CA bundle and the merged bundle is applied process-wide, so it covers LLM, reranker and MCP connections.

NOTE: PostgreSQL is the exception — it does not use this bundle. TLS to an external PostgreSQL is configured separately via the pgSSLMode / pgSSLRootCert values of the plugin configuration.

Updating the content of an already-registered ConfigMap (e.g. rotating the CA) requires a manual restart:

kubectl -n cpaas-system rollout restart deploy/smart-doc

#Verify

# The mounted CA and the merged bundle
kubectl -n cpaas-system exec deploy/smart-doc -c serve -- ls /opt/extra-ca/my-org-internal-ca/
kubectl -n cpaas-system exec deploy/smart-doc -c serve -- grep -c 'BEGIN CERTIFICATE' /tmp/smart-doc-ca.pem

# The startup log line
kubectl -n cpaas-system logs -l app=smart-doc -c serve | grep extra_ca

Expected log line:

extra_ca: merged 1/1 CA file(s) into /tmp/smart-doc-ca.pem

Then ask a question in the chat panel — requests to the endpoint that previously failed with CERTIFICATE_VERIFY_FAILED should now succeed.

#Skip TLS certificate verification (not recommended)

For test or development environments where importing the CA is not practical, TLS certificate verification for LLM calls can be switched off entirely with llmSkipSslVerify.

WARNING: This exposes the LLM connection to man-in-the-middle attacks, and it overrides both the TLS profile and any extra CA trust — which is why it is deliberately not offered in the installation form. The production-safe path for internal certificates is Extra CA ConfigMaps above. The setting affects LLM calls only; reranker, MCP and PostgreSQL connections are not touched.

Apply it by patching the plugin configuration (ModuleInfo) directly:

# Find the ModuleInfo of the Hyperflux plugin (cluster-scoped, name like global-<hash>)
MI=$(kubectl get moduleinfo -o jsonpath='{.items[?(@.spec.module=="alauda-hyperflux")].metadata.name}')

kubectl patch moduleinfo "$MI" --type=merge -p \
  '{"spec":{"config":{"smartdoc":{"llmSkipSslVerify":true}}}}'

The platform reconciles the change and rolls the pods automatically. When enabled, every startup logs a warning:

LLM_SKIP_SSL_VERIFY=true — LLM TLS certificate verification is DISABLED (verify=False)

To revert, patch the value back to false.

For external MCP servers there is an equivalent per-server tls_verify: false field — see Configure External MCP Servers, with the same caveat.