Support custom/pre-provisioned TLS certificates via existingSecret reference

[viniciusdc]

Problem

Currently, the operator always creates cert-manager Certificate resources that obtain certificates through a configured ClusterIssuer. While users can work around this by using a CA-based ClusterIssuer with a pre-provisioned CA certificate, there's no way to directly reference an existing TLS secret for a NebariApp.

This limitation affects environments that:

• Use pre-provisioned certificates from external sources
• Cannot run cert-manager at all
• Need to use certificates provisioned outside the cluster
• Have certificates managed by external tooling/processes
• Require certificate rotation to happen outside Kubernetes

Proposed Solution

Add an optional field to RoutingTLSConfig that allows referencing an existing Kubernetes TLS secret instead of creating a cert-manager Certificate:

apiVersion: reconcilers.nebari.dev/v1
kind: NebariApp
metadata:
  name: myapp
spec:
  hostname: myapp.example.com
  service:
    name: myapp-service
    port: 8080
  routing:
    tls:
      enabled: true
      existingSecret: my-custom-tls-cert  # New optional field

Implementation Considerations

1. Behavior when existingSecret is set:

   • Skip cert-manager Certificate creation
   • Still create the per-app Gateway HTTPS listener
   • Reference the specified secret in the Gateway listener's certificateRefs
   • Validate that the secret exists and is of type kubernetes.io/tls

2. Secret namespace:

   • The secret must be in the Gateway namespace (envoy-gateway-system)
   • Document requirement for users to create/maintain the secret in correct namespace
   • Consider adding validation to check secret existence

3. Mutual exclusivity:

   • existingSecret and ClusterIssuer-based certificate creation are mutually exclusive
   • When existingSecret is set, ignore TLS_CLUSTER_ISSUER_NAME

4. Status conditions:

   • Adjust TLSReady condition logic to check secret existence instead of Certificate readiness
   • Consider adding events/warnings if secret is missing or invalid

Benefits

• Simplifies deployment in environments without ACME access
• Supports certificate management workflows external to the cluster
• Maintains backward compatibility (existing behavior when omitted)
• Still leverages Gateway API for routing (only certificate source changes)

Related Discussion

This enhancement was discussed in the context of air-gapped and restricted environments where DNS configuration and ACME providers are not accessible.

[oren-openteams]

Verified end-to-end by PR #114 on an EKS 1.34 cluster. Operator pinned past v0.1.0-alpha.20 (image quay.io/nebari/nebari-operator:feat-dark_and_light_icons — a build off the same tree as main HEAD past that tag).

Test procedure

Isolated synthetic test, no interference with any live NebariApp. Full sequence:

1. Pre-flight — confirmed the CRD's routing.tls.secretName field is present with the expected description on the deployed operator.
2. Provisioned cert + secret — generated a self-signed cert for a never-used hostname (tls-test.<zone>) with openssl, created a kubernetes.io/tls secret from it in the Gateway's namespace (envoy-gateway-system).
3. Deployed a stub backend — tiny nginx Deployment + Service in a fresh test namespace.
4. Labelled the namespace with nebari.dev/managed=true (needed for the operator's namespace-opt-in guardrail — sensible security default).
5. Created the test NebariApp with spec.routing.tls.enabled=true + spec.routing.tls.secretName=<our-secret>.
6. Verified operator behavior (see below).
7. Deleted the NebariApp and confirmed the operator cleanly removed the Gateway listener it had added.
8. Cleanup — secret, namespace, deployment, service, local files.

Operator behavior — all four AC checks pass

Positive assertion 1: TLSReady condition set with the correct reason

$ kubectl -n tls-secret-test get nebariapp tls-test-app \
    -o jsonpath='{range .status.conditions[*]}{.type}={.status} (reason={.reason}){"\n"}{end}'

Ready=True (reason=ReconcileSuccess)
TLSReady=True (reason=UserProvidedSecretReady)
RoutingReady=True (reason=HTTPRouteReady)
AuthReady=False (reason=AuthDisabled)

reason=UserProvidedSecretReady is the code path introduced by this PR — the operator recognized the user-provided secret and used it instead of asking cert-manager for a Certificate.

Positive assertion 2: operator log confirms the intended code path

INFO  Using user-provided TLS secret     {"secret":"tls-test-secret",
                                          "namespace":"envoy-gateway-system",
                                          "hostname":"tls-test.<zone>"}
INFO  Applied Gateway listener           {"listener":"tls-tls-test-app-tls-secret-test",
                                          "gateway":"nebari-gateway"}
INFO  TLS reconciled successfully        {"listenerName":"tls-tls-test-app-tls-secret-test"}

Positive assertion 3: Gateway carries a new HTTPS listener with our secret in certificateRefs

Direct read of nebari-gateway after reconciliation showed a per-app listener named tls-tls-test-app-tls-secret-test, hostname matching our test app's hostname, tls.mode=Terminate, tls.certificateRefs=[{name: tls-test-secret}].

Negative assertion (anti-behavior): NO cert-manager Certificate was created

$ kubectl get certificate -A -o jsonpath='...' | grep -E 'tls-test'
✓ PASS: no Certificate object references tls-test

This is arguably the most important assertion — proves the operator took the secretName code path rather than falling back to the cert-manager path (which is what would produce the browser-untrusted selfsigned-issuer chain in intercepted-egress environments).

Delete-side symmetry: removing the NebariApp removes the listener

After kubectl delete nebariapp tls-test-app, a fresh read of nebari-gateway showed the tls-tls-test-app-tls-secret-test listener was gone. So the create/delete cycle is symmetric — no orphan listeners on delete.

Observations worth recording

Transient conflict on first apply, resolved on retry

First reconcile hit TLSReady=False (GatewayListenerFailed) with the classic Kubernetes optimistic-concurrency conflict message (the object has been modified; please apply your changes to the latest version and try again). This is expected on a shared Gateway that multiple NebariApp controllers are contending on. A single re-nudge cleared it. Not a bug for this PR — but PR #142 (watch owned resources + user-provided secrets for prompt reconciliation) will presumably make the retry path more responsive.

Namespace opt-in guardrail

First apply also returned Ready=False (NamespaceNotOptedIn, msg=namespace ... is not opted-in to Nebari management (missing label: nebari.dev/managed=true)). This is a sensible security default and clearly documented in the condition message — nice touch. Just something to know when writing docs or examples for this feature.

Production shape confirmation

Independent of this synthetic test, this feature is already in productive use on a separate cluster: three NebariApps (nebi-pack, nebari-landing, data-science-pack) on that deployment all reference a single pre-provisioned wildcard TLS secret via this exact routing.tls.secretName field, gitops-managed. So PR #114's shape has held up in real multi-app usage, not just isolated tests.

Closing the verification side. Reopen if behavior regresses.