Proper TLS termination option

[mazmar]

Proposed change

Leave TLS termination to the components designed to handle TLS, and let the client/server behave as if TLS is not required.

Why should the server configuration even include tls_available, and why should the NATS client care about this option?

TLS handshakes should be performed properly at the proxy layer. TLS should then be completely out of scope for the internal components.

When TLS termination is implemented correctly, the backend server does not need to know anything about it.

Currently, if tls: {} and allow_non_tls are set, the server responds to non-TLS requests with tls_available and forces the client to use TLS anyway. This eventually results in a bad request error because no TLS certificate is provided.

In my setup, I have a Kubernetes cluster where external connections are properly handled through a TLS-terminated port 4221 with valid certificates. That port routes traffic to the internal service nats.nats.svc.cluster.local.

However, I also have multiple local clients connecting directly to nats.nats.svc.cluster.local. I do not want to enable TLS for those connections—it adds unnecessary overhead. I also don’t want to manage an internal CA just to issue cluster.local certificates, distribute that CA, or configure local clients to ignore certificate validation.

This separation is standard in other messaging systems such as AMQP implementations, where TLS handling is independent from the messaging solution itself.

Use case

Scenario
A company runs a Kubernetes-based microservices platform that relies on NATS as the internal messaging backbone. The cluster hosts dozens of internal services that communicate through NATS for event streaming, service coordination, and background job processing.

The platform exposes a public endpoint for external clients (partners, SaaS integrations, and remote services) that must connect securely over the internet.

Architecture
The system is designed with TLS termination at the cluster edge, typically handled by a reverse proxy or ingress component such as NGINX, HAProxy, or Traefik.

The architecture looks like this:

External Clients
       │
       │ TLS (valid public certificate)
       ▼
Ingress / Proxy (TLS termination, port 4221)
       │
       │ Plain TCP
       ▼
NATS Service (nats.nats.svc.cluster.local:4222)
       │
       ├── Internal microservices
       ├── Workers
       └── Local tooling / scripts

External Access
External systems connect securely:

tls://nats.example.com:4221

The proxy:
1. Performs the TLS handshake
2. Validates certificates
3. Terminates TLS
4. Forwards plain TCP traffic to the internal NATS service.

This ensures secure communication over the public internet without exposing the internal cluster.

Internal Access
Inside the Kubernetes cluster, services connect directly to:

nats://nats.nats.svc.cluster.local:4222

These connections remain non-TLS because:
• Traffic never leaves the cluster network.
• Kubernetes networking is already isolated.
• Performance is better without unnecessary encryption overhead.
• No internal PKI or certificate distribution is required.

Internal clients include:
• microservices
• background workers
• scheduled jobs
• local debugging tools

Problem Encountered
When TLS is configured on the NATS server with:

tls: {}
allow_non_tls: true

the server advertises tls_available to clients.

This causes clients to attempt upgrading to TLS even when connecting internally without TLS. Since no TLS certificates are configured for internal connections, the handshake fails and results in bad request errors.

Desired Behavior
In this architecture, TLS should be handled entirely by the proxy layer, and the NATS server should behave as if TLS does not exist.

The desired behavior:
• External connections → TLS handled by proxy
• Internal connections → plain NATS
• NATS server unaware of TLS
• Clients not forced into TLS negotiation

Benefits

1. Simpler Infrastructure
   No internal certificate authority, certificate distribution, or trust configuration is required.

2. Better Performance
   Internal services avoid unnecessary TLS overhead.

3. Clear Separation of Responsibilities
   • Edge proxy → security and TLS
   • Messaging system → message transport

4. Standard Architecture
   This approach mirrors how many RabbitMQ or other AMQP deployments handle TLS: encryption is often terminated at the network edge rather than enforced inside the messaging layer.

Summary
This use case demonstrates a common Kubernetes deployment pattern:
• TLS at the edge
• plain communication internally

In such architectures, messaging systems like NATS should ideally remain TLS-agnostic internally, allowing secure external access without complicating internal service communication.

Contribution

No response

[wallyqs]

tls_available should not force the client to use TLS, (that is the role of tls_required or tls handshake first options), maybe there was a client implementation which accidentally tried to upgrade to TLS after seeing tls_available? Could you share which runtime you are using to connect?

[wallyqs]

The setup you described should work already with those two options, so I think might be an issue with the local client that tried to connect.

[mazmar]

unfortunately I am not in control of the client application, however I've provided the application with url: nats://nats.nats.svc.cluster.local:4222 and all I can see is TLS handshake failure

this is my server info provided on port 4222:

INFO {"server_id":"NATHQFESGPKZ7BA6EXET3CE5W6AYACOR53YFALA7FYDI5OQMAA6Y562M","server_name":"next-dev1-nats-0","version":"2.12.4","proto":1,"git_commit":"34894c1","go":"go1.25.6","host":"0.0.0.0","port":4222,"headers":true,"auth_required":true,"tls_available":true,"max_payload":1048576,"jetstream":true,"client_id":43,"client_ip":"10.244.0.233","nonce":"iaL2eafQkf6ZC6I","api_lvl":2,"xkey":"XCV5TINTSSJCYWVQNCAP7S2E4LJWIOFQJEPH32L6JCAPY2BJMDVSGRJ2"}

this is what i see in log:

nats [8] 2026/03/09 14:49:13.868135 [DBG] 10.244.0.233:36432 - cid:38 - Starting TLS client connection handshake
nats [8] 2026/03/09 14:49:13.869447 [ERR] 10.244.0.233:36432 - cid:38 - TLS handshake error: tls: no certificates configured
nats [8] 2026/03/09 14:49:13.869463 [DBG] 10.244.0.233:36432 - cid:38 - Client connection closed: TLS Handshake Failure

nats config

{
  "allow_non_tls": true,
  "http_port": 8222,
  "lame_duck_duration": "30s",
  "lame_duck_grace_period": "10s",
  "pid_file": "/var/run/nats/nats.pid",
  "port": 4222,
  "server_name": $SERVER_NAME,
  "tls": {
  }
}

[wallyqs]

Thanks the client should not have been trying to upgrade to TLS, but for some reason it is trying to... any more info about the client application will help (like go client version and go version using).

[mazmar]

I believe the app in question is using nats.net as the app itself is written in .net, I will try to get hold of the developer this week for some answers.

AFAIK they do not set any explicit TLS settings as if i remove the tls: {} from the settings, the client connects plaintext with the same url no problem

[wallyqs]

thanks, this is likely an oversight in the nats.net client

[mazmar]

meanwhile I've gathered more evidence from the client log:

17:21:33 | WARNING  | Platform     | 127.0.0.1:42334 | OUT exception | NatsClient::connect | TLS authentication failed
NATS.Client.Core.NatsException:
   at NATS.Client.Core.Internal.SslStreamConnection.AuthenticateAsClientAsync(NatsUri uri, TimeSpan timeout)
   at NATS.Client.Core.NatsConnection.SetupReaderWriterAsync(Boolean reconnect)
   at NATS.Client.Core.NatsConnection.SetupReaderWriterAsync(Boolean reconnect)
   at NATS.Client.Core.NatsConnection.InitialConnectAsync() | Args=servicesReference=NatsClient; operation=connect; paramsJson={"url":"nats:\/\/nats.nats.svc.cluster.local:4222","creds":"-----BEGIN NATS USER JWT-----xxx------END NATS USER JWT------\r\n\r\n-----BEGIN USER NKEY SEED-----xxx------END USER NKEY SEED
------\r\n","clientName":"xxx"} 

[wallyqs]

thanks, the client version is what would the most helpful. Whether it is using nats.net v1 or nats.net v2 and the tagged version they are using.

[wallyqs]

that being said maybe we do need an option better than tls {} + allow_non_tls = true, tls_terminated = true maybe...

[mazmar]

I’ve reached out to the developer, and he provided me with this nuget: “NATS.Net” Version=“2.7.1”.

However, I still don’t comprehend why “tls_available”: true is set, even though it’s not available because it fails when certificates are missing.

I can understand if the reverse proxy handles the TLS, and then NATS doesn’t need to worry about TLS knowledge.

[wallyqs]

“tls_available”: true is meant to signal the client that they can connect to TLS instead, but agree we could have a more user friendly option for this type of setup. Have you tried using the TLS handshake first option in the client by the way? That way you would force the client to establish TLS against the LB instead.

[mazmar]

TLS first option works just fine in this config when communication is from outside of the cluster. It is terminated by haproxy and everything works. I am talking about clients that are in cluster. These bypass haproxy and goes directly to nats:4222

tls_available is in my opinion misleading, as in fact it is not available. There are no certificates on nats to be available.

[wallyqs]

I think in the client you may have to do something like

var opts = new NatsOpts
{
    Url = "nats://nats.nats.svc.cluster.local:4222",
    TlsOpts = new NatsTlsOpts
    {
        Mode = TlsMode.Disable,
    },
};

await using var nats = new NatsConnection(opts);