TLS certificate configuration

DataQI supports multiple approaches to TLS certificate management to accommodate the variety of environments in which it is installed. This guide helps you choose the right approach and configure it correctly.

Choosing a mode

Set routing.tls.mode in your values.yaml to one of the following values:

Mode	When to use
certManager	You have cert-manager installed on your cluster and a ClusterIssuer configured (ACME/Let’s Encrypt, Step CA, Vault, internal CA).
preProvisioned	You already have a TLS certificate — a wildcard cert, a Windows CA export, or a Cloudflare origin certificate — and will create the Kubernetes Secret manually.
external	TLS is terminated upstream before traffic reaches the cluster (Cloudflare proxy, a WAF, or a cloud load balancer). The chart renders no TLS resources.
none	Plain HTTP only. Use for local development or air-gapped internal clusters where TLS is not required.

Is TLS terminated before it reaches the cluster?
└─ Yes → external

Do you have cert-manager installed with a ClusterIssuer?
└─ Yes → certManager

Do you have a certificate file you can provide manually?
└─ Yes → preProvisioned

Local development only?
└─ Yes → none

---

Mode: certManager

The chart creates a cert-manager Certificate resource and a ReferenceGrant that allows the shared Gateway to read the resulting TLS secret.

Prerequisites:

• cert-manager External link; internet access required installed on the cluster.
• A ClusterIssuer configured for your chosen CA.

Configuration

routing:
  type: gateway
  tls:
    mode: certManager
    secretName: dataqi-tls        # Name of the Secret cert-manager will create
    certManager:
      clusterIssuerName: "my-cluster-issuer"
      extraDnsNames: []           # Optional extra SANs beyond the standard subdomains

The chart automatically includes all enabled DataQI subdomains (SPA, API, Keycloak, and optionally localDevSpa and MCP Sandbox) in the certificate’s SAN list.

ClusterIssuer examples

Let’s Encrypt (public clusters)

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: platform@yourdomain.com
    privateKeySecretRef:
      name: letsencrypt-prod-key
    solvers:
      - http01:
          gatewayHTTPRoute:
            parentRefs:
              - name: dataqi-gateway
                namespace: nginx-gateway

Step CA (on-premises)

If you are running smallstep/step-ca External link; internet access required as your internal CA, configure an ACME provisioner and create a ClusterIssuer pointing at it:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: step-ca
spec:
  acme:
    server: https://step-ca.yourdomain.internal/acme/acme/directory
    email: platform@yourdomain.com
    privateKeySecretRef:
      name: step-ca-key
    caBundle: "<base64-encoded-step-ca-root-cert>"
    solvers:
      - http01:
          gatewayHTTPRoute:
            parentRefs:
              - name: dataqi-gateway
                namespace: nginx-gateway

Vault PKI / CFSSL (internal CA)

Use the cert-manager Vault issuer External link; internet access required or the CFSSL issuer External link; internet access required as appropriate for your PKI.

---

Mode: preProvisioned

You supply the TLS secret directly. The chart creates a ReferenceGrant that allows the shared Gateway to read it — no Certificate resource is created.

Use this when you have:

• A wildcard certificate from any CA.
• A certificate exported from a Windows / Active Directory CA.
• A Cloudflare origin certificate.

Step 1: obtain your certificate files

You need two PEM-format files:

• fullchain.pem — the certificate and any intermediate certificates, concatenated.
• privkey.pem — the private key.

From a Windows / Active Directory CA (PFX export)

Active Directory Certificate Services typically exports PFX bundles. Convert them to PEM using openssl:

# Extract the private key
openssl pkcs12 -in cert.pfx -nocerts -nodes -out privkey.pem

# Extract the certificate chain
openssl pkcs12 -in cert.pfx -clcerts -nokeys -out fullchain.pem

You will be prompted for the PFX export password.

From Cloudflare origin certificate

Download the Origin Certificate and Private Key from the Cloudflare dashboard (SSL/TLS → Origin Server). Save them as fullchain.pem and privkey.pem respectively.

From any other CA

Ensure you have PEM-format files. If your CA provides DER-format certificates (.cer or .der), convert them first:

openssl x509 -inform DER -in cert.cer -out fullchain.pem

Step 2: create the Kubernetes secret

kubectl create secret tls dataqi-tls \
  --cert=fullchain.pem \
  --key=privkey.pem \
  -n <namespace>

Replace dataqi-tls with whatever name you intend to use for routing.tls.secretName.

Step 3: configure the chart

routing:
  type: gateway
  tls:
    mode: preProvisioned
    secretName: dataqi-tls    # Must match the secret name you created above

Note

The TLS secret must live in the same namespace as the DataQI release. The chart’s ReferenceGrant grants the Gateway access to secrets in that namespace only.

---

Mode: external

TLS is terminated by an upstream component before traffic reaches the Gateway — for example a Cloudflare proxy, a WAF, an Application Load Balancer, or a network appliance.

The chart renders no TLS resources (Certificate or ReferenceGrant). Your Gateway listener should be configured for plain HTTP internally.

routing:
  type: gateway
  tls:
    mode: external

---

Mode: none

Plain HTTP only. The chart renders no TLS resources. Use for local development or internal clusters where TLS is not needed.

routing:
  type: gateway
  tls:
    mode: none

Caution

Do not use mode: none in a production environment. All credentials and session tokens will be transmitted in plain text.