Transport Layer Security (TLS)¶

Percona Operator for MongoDB uses Transport Layer Security (TLS) cryptographic protocol for the following types of communication:

External - to enable client applications communicate with the cluster
Internal - for communication between Percona Server for MongoDB instances in the cluster. The internal certificate is also used as an authorization method.

These certificates are stored in Secrets. Default Secret names are <cluster-name>-ssl and <cluster-name>-ssl-internal. These Secrets are referenced in the secrets.ssl and secrets.sslInternal Custom Resource options.

You control TLS usage with the tls.mode option in the Custom Resource. This setting defines how Percona Server for MongoDB cluster handles TLS for both internal and external connections. You can choose from the following modes:

allowTLS: The cluster accepts both TLS and non-TLS incoming connections, but does not use TLS for internal communication.
preferTLS (default): The cluster uses TLS for internal communication and accepts both TLS and non-TLS external connections.
requireTLS: The cluster enforces TLS encryption for all connections and accepts only TLS connections.
disabled: The cluster completely disables TLS for all connections.

Example configuration:

...
spec:
  ...
  tls:
    mode: preferTLS

TLS Certificates¶

You can configure TLS security in several ways:

Approach	Best for	Renewal
Operator-generated certificates (default)	Quick start, development	Manual
cert-manager with Operator-managed issuers	Automated TLS without external PKI	Automatic (cert-manager)
cert-manager with your existing `Issuer` or `ClusterIssuer`	Production clusters that use the organization’s PKI (Smallstep, ACME, etc.)	Automatic (cert-manager)
Manual Secrets	Full control, air-gapped or custom PKI workflows	Manual

By default, the Operator generates long-term certificates automatically during the cluster creation if there are no certificate secrets available and no cert-manager is installed. When generating certificates, the Operator creates two Secrets objects named <cluster-name>-ssl and <cluster-name>-ssl-internal. These Secrets are referenced in the secrets.ssl and secrets.sslInternal options in the Custom Resource.

Operator-generated certificates are not renewed automatically. You must renew them manually if you need new certificates.

To allow certificates automatically generated by the Operator, the tls.allowInvalidCertificates Custom Resource option is set to true by default. You can set it to false when using other certificate generation methods, such as cert-manager with a trusted CA.
The Operator can use an installed cert-manager to automatically generate and renew short-term TLS certificates. By default it creates namespace-scoped issuers in the database namespace. Starting with Operator 1.23.0, you can also point it at an existing cluster-wide ClusterIssuer so MongoDB certificates are signed by your organization’s CA.
You can generate TLS certificates manually and pass them to the Operator as Kubernetes Secrets.

For testing purposes, you can use pre-generated certificates available in the deploy/ssl-secrets.yaml file. But we strongly recommend to not use them on any production system!

Certificate management policy¶

Starting with Operator version 1.23.0, you can control what happens when TLS Secrets are missing via the spec.tls.certManagementPolicy option in the Custom Resource:

auto (default) — If Secrets are not found, the Operator creates new certificates automatically (self-signed or via cert-manager). New certificates can replace a lost user-managed Secret with a new CA, which triggers a rolling restart of all database Pods, and can disconnect clients that trust the original CA.
userProvidedOnly — The Operator skips auto-creation or replacement of unavailable TLS certificates, so that you control the certificate lifecycle management (manually, via External Secrets, GitOps, or your own cert-manager workflow). If a Secret is missing, Pods keep running with existing certificates where possible, and the Operator sets the TLSSecretsReady=False condition until you restore the Secret.

Your setup	Recommended policy
Operator self-signed or Operator-driven cert-manager	`auto`
Manual, External Secrets, or GitOps-managed TLS Secrets in production	`userProvidedOnly`

Example:

spec:
  tls:
    mode: preferTLS
    certManagementPolicy: userProvidedOnly
  secrets:
    ssl: my-cluster-name-ssl
    sslInternal: my-cluster-name-ssl-internal

See Configure the TLS certificate management policy for setup steps, monitoring, recovery, and policy switching.

TLS configuration¶

The following sections provide guidelines how to:

To use TLS for external traffic, you need to additionally configure your client application. See this blog post for detailed instruction with examples. Also, you can check the official MongoDB documentation .

For clients outside of your Kubernetes-based environment, you must also expose your cluster.

Last update: August 3, 2026
Created: August 3, 2026