This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

TLS in Kubernetes

1: Configure TLS in Kubernetes
2: Enable TLS in Vertica on Kubernetes

To enhance security, the VerticaDB operator supports Transport Layer Security (TLS) for the HTTPS service, Client-Server authentication, and internode communication. Vertica does not store TLS certificates in its catalog or on disk. Instead, it reads the certificates directly from Kubernetes or AWS secrets when needed, which reduces the risk of unauthorized access to stored certificates.

1 - Configure TLS in Kubernetes

To enhance security, the VerticaDB operator supports TLS authentication for both the HTTPS service and Client-Server authentication. This ensures that the Vertica server can verify identities of its clients before communication, helping protect against unauthorized access by enforcing certificate verification for both HTTPS service and Client-Server authentication. Vertica does not store TLS certificates in its catalog or on disk. Instead, it reads the certificates directly from Kubernetes or AWS secrets when needed. This enhances security by reducing the risk of unauthorized access to stored certificates. For more information about configuring TLS, see CREATE TLS CONFIGURATION.

Note

This topic covers the basic use case of enabling TLS on an existing database. For detailed scenarios, such as enabling TLS when creating, reviving, or upgrading a database, see Enable TLS in Vertica on Kubernetes.

Configure TLS

Prerequisites

Install VerticaDB operator 25.3.0-0 and higher.
Create a VerticaDB custom resource definition manifest.

Note

Setting up HTTPS and Client-Server TLS via VerticaDB operator using Kubernetes or AWS secrets is supported in Vertica version 25.3.0-0 or higher.
Setting up Internode TLS via VerticaDB operator using Kubernetes or AWS secrets is supported in Vertica version 26.1.0-0 or higher.
TLS cannot be disabled after it has been enabled.
Any TLS configuration is rejected when vertica.com/mount-nma-certs is set to true. You must first set it to false, which triggers a rolling update, before you can configure TLS.

Enable TLS

Use kubectl edit to edit the existing VerticaDB. Set httpsNMATLS.secret, httpsNMATLS.mode, clientServerTLS.secret, clientServerTLS.mode, interNodeTLS.secret, and interNodeTLS.mode.

The operator generates a TLS secret when:
- A TLS configuration is enabled by setting enabled to true.
- No secret is specified (httpsNMATLS.secret, clientServerTLS.secret, or interNodeTLS.secret). The generated secrets follow the naming patterns <vdb-name>-https-tls-<5-digits-random-string>, <vdb-name>-clientserver-tls-<5-digits-random-string>, or <vdb-name>-internode-tls-<5-digits-random-string>.
If a TLS configuration is not specified at all, the operator does not generate a secret for that configuration.

If httpsNMATLS.mode and clientServerTLS.mode are not specified, the default mode try_verify will be applied.

If interNodeTLS.mode is not specified, the default mode verify_ca will be applied.

If you want to use your own TLS certificates, you can optionally provide them using a Kubernetes secret of type kubernetes.io/tls or an AWS Secrets Manager secret.

Note
The automatically generated secret is not deleted when the VerticaDB resource is removed. This is required if you want to revive the database later. If you want the secret to be automatically deleted, then set the vertica.com/remove-tls-secret-on-vdb-delete annotation to true.
```
$ kubectl edit vdb cluster-name

apiVersion: vertica.com/v1
kind: VerticaDB
metadata:
  annotations:
    ...
    vertica.com/enable-tls-auth: "true"
    vertica.com/remove-tls-secret-on-vdb-delete: "false"
    ...
spec:
  ...
  clientServerTLS:
    mode:    TRY_VERIFY
    secret:  your-clientserver-tls-secret
    enabled: true
  httpsNMATLS:
    mode:    TRY_VERIFY
    secret:  your-https-tls-secret
    enabled: true
  interNodeTLS:
    mode:    VERIFY_CA
    secret:  your-internode-tls-secret
    enabled: true
```

Use kubectl describe to check the events generated by the operator while setting up TLS mode:


$ kubectl describe vdb cluster-name

...

Events:

  Type     Reason                                   Age                From                Message
  ----     ------                                   ----               ----                -------
  Normal  TLSConfigurationStarted     3m46s  verticadb-operator  Starting to configure TLS for httpsNMA
  Normal  TLSConfigurationSucceeded   3m44s  verticadb-operator  Successfully set HTTP tls config
  Normal  TLSConfigurationStarted     3m44s  verticadb-operator  Starting to configure TLS for clientServer
  Normal  TLSConfigurationSucceeded   3m42s  verticadb-operator  Successfully set Server tls config
  Normal  TLSConfigurationStarted     3m42s  verticadb-operator  Starting to configure TLS for interNode
  Normal  TLSConfigurationSucceeded   3m40s  verticadb-operator  Successfully set Internode tls config

Note

The following example assumes that no custom secret was provided and VerticaDB operator automatically generates Kubernetes secrets for Https NMATLS, Client Server TLS, and Internode TLS.

Use kubectl describe to check the secrets that are generated:


$ kubectl describe vdb cluster-name

...
Status:
  ...
  Tls Configs:
    Mode:          try_verify
    Name:          httpsNMA
    Secret:        vertica-db-https-tls-lhj82
    Mode:          try_verify
    Name:          clientServer
    Secret:        vertica-db-clientserver-tls-j86v9
    Mode:          verify_ca
    Name:          interNode
    Secret:        vertica-db-internode-tls-gbcx8

Verify that the auto generated secrets exist in Kubernetes secrets manager in the same namespace where the VerticaDB was created.
```
$ kubectl get secrets
NAME                                                                                  TYPE                             DATA   AGE
vertica-db-clientserver-tls-j86v9                                                     kubernetes.io/tls                3      5m7s
vertica-db-https-tls-lhj82                                                            kubernetes.io/tls                3      5m18s
vertica-db-internode-tls-gbcx8                                                        kubernetes.io/tls                3      5m7s
```
The Client Server TLS.mode and Https NMATLS.mode are set to TRY_VERIFY by default. You can set following values:
- ENABLE: Enables TLS without validating client certificates.
- TRY_VERIFY: Establishes a TLS connection if the other host
  - presents a valid certificate.
  - does not present a certificate.
  - presents an invalid certificate. In this case, the connection will use plaintext.
- VERIFY_CA: Allows the connection if the other host presents a certificate signed by a trusted CA. If no certificate is provided, the connection falls back to plaintext.
Internode TLS.mode is set to VERIFY_CA by default and cannot be set to TRY_VERIFY or VERIFY_FULL.

You can set vertica.com/tls-cache-duration to a value of your choice. In the following example, we will set it to 1 hour in the VerticaDB CR:

apiVersion: vertica.com/v1
kind: VerticaDB
metadata:
  annotations:
    ...    
    vertica.com/tls-cache-duration: "3600"

You can connect to the database and verify the necessary TLS configurations, authentication settings, and secrets after TLS is enabled. The operator creates four built-in TLS client authentication configurations for future connections. You must not modify or delete these configurations.

$ vsql -h <hostname/ip> -U dbadmin

Welcome to vsql, the Vertica Analytic Database interactive terminal.

Type:  \h or \? for help with vsql commands
       \g or terminate with semicolon to execute query
       \q to quit
SSL connection (cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, protocol: TLSv1.2)

-- Verify TLS Configuration
vertdb=> SELECT * FROM tls_configurations;

     name     |  owner  |     certificate     |     ca_certificate     | cipher_suites | cipher_list |    mode
--------------+---------+---------------------+------------------------+---------------+-------------+------------
 https        | dbadmin | https_cert_0        | https_ca_cert_0        |               |             | TRY_VERIFY
 server       | dbadmin | server_cert_0       | server_ca_cert_0       |               |             | TRY_VERIFY
 data_channel | dbadmin | data_channel_cert_0 | data_channel_ca_cert_0 |               |             | VERIFY_CA
 LDAPLink     | dbadmin |                     |                        |               |             | DISABLE
 LDAPAuth     | dbadmin |                     |                        |               |             | DISABLE
(5 rows)

-- Verify TLS authentication created
vertdb=> SELECT auth_name, auth_host_type, auth_host_address, auth_method FROM client_auth WHERE auth_method = 'TLS';
            auth_name             | auth_host_type | auth_host_address | auth_method
----------------------------------+----------------+-------------------+-------------
 k8s_remote_ipv4_tls_builtin_auth | HOSTSSL        | 0.0.0.0/0         | TLS
 k8s_remote_ipv6_tls_builtin_auth | HOSTSSL        | ::/0              | TLS
 k8s_local_tls_builtin_auth       | LOCALSSL       |                   | TLS
(3 rows)

-- Verify that secret_name is same as set in httpsNMATLS.secret and cache duration is same as set in vertica.com/ tls-cache-duration annotation
vertdb=> SELECT name, secret_name, secret_manager_config from certificates where name in ('https_ca_cert_0','server_ca_cert_0', 'data_channel_ca_cert_0', 'https_cert_0', 'server_cert_0', 'data_channel_cert_0');
          name          |            secret_name            |                        secret_manager_config
------------------------+-----------------------------------+---------------------------------------------------------------------
 https_ca_cert_0        | vertica-db-https-tls-lhj82        | {"data-key":"ca.crt","namespace":"vertica","cache-duration":86400}
 server_ca_cert_0       | vertica-db-clientserver-tls-j86v9 | {"data-key":"ca.crt","namespace":"vertica","cache-duration":86400}
 data_channel_ca_cert_0 | vertica-db-internode-tls-gbcx8    | {"data-key":"ca.crt","namespace":"vertica","cache-duration":86400}
 https_cert_0           | vertica-db-https-tls-lhj82        | {"data-key":"tls.crt","namespace":"vertica","cache-duration":86400}
 server_cert_0          | vertica-db-clientserver-tls-j86v9 | {"data-key":"tls.crt","namespace":"vertica","cache-duration":86400}
 data_channel_cert_0    | vertica-db-internode-tls-gbcx8    | {"data-key":"tls.crt","namespace":"vertica","cache-duration":86400}
(6 rows)

Add multiple CA certificates to your TLS configuration

When a Certificate Authority provides multiple certificate files (such as root and intermediate certificates), you need to combine them into a single file and then create a Kubernetes secret as shown in the following example:


# combine them into a single file
$ cat cert1_ca.crt cert2_ca.crt cert3_ca.crt > combined_ca.crt
 
# use combined file to create kubernetes secret
$ kubectl create secret generic combined-ca-secret --from-file=ca.crt=combined_ca.crt

You can now use combined-ca-secret for setting up TLS with the VerticaDB operator.

Configure TLS version and cipher suites

TLS 1.2 supports the following cipher suites:

ECDHE-RSA-AES256-GCM-SHA384
ECDHE-RSA-CHACHA20-POLY1305
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-RSA-AES256-SHA
ECDHE-RSA-AES128-SHA

TLS 1.3 supports the following cipher suites:

TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256

Note

While Vertica offers multiple cipher suites, the Kubernetes deployment supports only those listed here as the Go HTTP client supports only this subset.

Example 1: Configure TLS 1.2

The following example configures TLS1.2 and enables all cipher suites supported by Vertica.

apiVersion: vertica.com/v1
kind: VerticaDB
metadata:
  name: vdb-tls
  annotations:
    ...
    vertica.com/enable-tls-auth: "true"
     
spec:
  ...  
  dbTlsConfig:    
    tlsVersion: 2
    cipherSuites:""

Example 2: Configure TLS 1.3 with single cipher suite

The following example configures TLS 1.3 and enables a single cipher suite (TLS_AES_256_GCM_SHA384):

apiVersion: vertica.com/v1
kind: VerticaDB
metadata:
  name: vdb-tls
  annotations:
    ...
    vertica.com/enable-tls-auth: "true"
     
spec:
  ...  
  dbTlsConfig:    
    tlsVersion: 3
    cipherSuites:"TLS_AES_256_GCM_SHA384"

Example 3: Configure TLS 1.2 with multiple cipher suites

The following example configures TLS 1.2 and enables multiple cipher suites (ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-CHACHA20-POLY1305, and ECDHE-RSA-AES128-GCM-SHA256):

apiVersion: vertica.com/v1
kind: VerticaDB
metadata:
  name: vdb-tls
  annotations:
    ...
    vertica.com/enable-tls-auth: "true"
     
spec:
  ...  
  dbTlsConfig:    
    tlsVersion: 2
    cipherSuites:"ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256"

You can run the following command to verify the TLS version and status of the cipher suites:

$ kubectl describe vdb
Name:         vdb-tls
...
Spec:
  ...
  Db Tls Config:
    Cipher Suites:  ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256
    Tls Version:    2
Status:
  ...
  Db Tls Config:
    Cipher Suites:    ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256
    Tls Version:      2
  Events:
  Type    Reason                Age    From                Message
  ----    ------                ----   ----                -------  
  Normal   DBTLSUpdateStarted          18s                verticadb-operator  Started to update tls version to 2
  Normal   DBTLSUpdateSucceeded        9s                 verticadb-operator  Successfully updated tls version to 2
  Normal   DBTLSUpdateStarted          9s                 verticadb-operator  Started to update tls cipher suites to ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256
  Normal   DBTLSUpdateSucceeded        1s                 verticadb-operator  Successfully updated tls cipher suites to ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256

You can also connect to the database and execute SELECT LIST_ENABLED_CIPHERS(); to verify the changes have been applied:

$ vsql
Welcome to vsql, the Vertica Analytic Database interactive terminal.
 
Type:  \h or \? for help with vsql commands
       \g or terminate with semicolon to execute query
       \q to quit
 
SSL connection (cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, protocol: TLSv1.2)
 
vertdb=> SELECT LIST_ENABLED_CIPHERS();
                                LIST_ENABLED_CIPHERS
-------------------------------------------------------------------------------------
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-RSA-CHACHA20-POLY1305
ECDHE-RSA-AES128-GCM-SHA256
(1 row)

Certificate Rotation

Some deployments require periodic rotation of certificates for security and compliance. During this process, the goal is to avoid restarting or shutting down database nodes. Instead, only the HTTPS service and NMA are restarted, allowing certificate updates with minimal disruption to database operations.

Note

You must rotate certificates before they expire.
It is recommended to create a restore point before rotating certificates, so the database can be recovered in case the rotation fails. For more information, see VerticaRestorePointsQuery custom resource definition.
The interval between two certificate rotations must be longer than the TLS cache duration (vertica.com/tls-cache-duration in the VerticaDB spec). If it is shorter, the rotation may fail especially if the currently used secret is updated.
You must make a note of the secret used for create_db as you can use it for revive_db.
If you use the same secret for both HTTPS and Client Server TLS, you must rotate them at the same time to avoid issues when the old secret is updated or removed.
Certificate rotation is not supported for sandboxes.
You cannot rotate certificates when the operator is performing other tasks such as a database upgrade.
If TLS certificate rotation fails for any reason, the system rolls back to the last TLS certificate applied before the rotation began.

Rotate TLS certificates

Use kubectl edit to locate and change the secret you want to rotate (Client Server TLS.secret or Https NMATLS.secret). The following example shows how to rotate Https NMATLS.secret from vertica-db-https-tls-s42r2 to custom-cert.


$ kubectl edit vdb cluster-name

apiVersion: vertica.com/v1
kind: VerticaDB
metadata:
  annotations:
    ...
    vertica.com/enable-tls-auth: "true"
...


  httpsNMATLS:
    mode:             TRY_VERIFY
    secret:           vertica-db-https-tls-s42r2

Change the value of Https NMATLS.secret to custom-cert and save.

$ kubectl edit vdb cluster-name

apiVersion: vertica.com/v1
kind: VerticaDB
metadata:
  annotations:
    ...
    vertica.com/enable-tls-auth: "true"
...


  httpsNMATLS:
    mode:             TRY_VERIFY
    secret:           custom-cert

Use kubectl describe to check the events generated by the operator while rotating TLS certificates:


$ kubectl describe vdb cluster-name

...  
Events:
  Type    Reason                       Age   From                Message
  ----    ------                       ----  ----                -------

  Normal  HTTPSTLSUpdateStarted        15m   verticadb-operator  Starting tls cert rotation for HTTP with secret name custom-cert and mode TRY_VERIFY
  Normal  HTTPSTLSUpdateSucceeded      14m   verticadb-operator  Successfully rotated HTTP tls cert with secret name custom-cert and mode TRY_VERIFY
  Normal  NMATLSCertRotationStarted    14m   verticadb-operator  Start rotating nma cert from vertica-db-https-tls-s42r2 to custom-cert
  Normal  NMATLSCertRotationSucceeded  14m   verticadb-operator  Successfully rotated nma cert from vertica-db-https-tls-s42r2 to custom-cert

You can connect to the database to verify that the TLS configurations are updated with the rotated certificate. Each time a TLS certificate is rotated, a new key, certificate, and CA certificate are generated with an incremented index. For example, if the initial HTTPS TLS configuration uses https_cert_0 and https_ca_cert_0, the next rotation will use https_cert_1 and https_ca_cert_1. This index-based naming makes it easier to track certificate versions.


$ vsql -h <hostname/ip> -U dbadmin

Welcome to vsql, the Vertica Analytic Database interactive terminal.

Type:  \h or \? for help with vsql commands
       \g or terminate with semicolon to execute query
      \q to quit
SSL connection (cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, protocol: TLSv1.2)

-- tls_configurations updated to use https_cert_1 instead of https_cert_0
vertdb=> SELECT * FROM tls_configurations;
     name     |  owner  |  certificate  |  ca_certificate  | cipher_suites | cipher_list |    mode
--------------+---------+---------------+------------------+---------------+-------------+------------
 server       | dbadmin | server_cert_0 | server_ca_cert_0 |               |             | TRY_VERIFY
 https        | dbadmin | https_cert_1  | https_ca_cert_1  |               |             | TRY_VERIFY
 LDAPLink     | dbadmin |               |                  |               |             | DISABLE
 LDAPAuth     | dbadmin |               |                  |               |             | DISABLE
 data_channel | dbadmin |               |                  |               |             | DISABLE
(5 rows)

-- check the secrets used to generate above certificates
vertdb=> SELECT name,secret_name FROM certificates where name ilike 'https_cert%';
     name     |        secret_name
--------------+----------------------------
 https_cert_0 | vertica-db-https-tls-s42r2
 https_cert_1 | vertica-db-https-tls-xmmd2
(2 rows)

Note

The VerticaDB operator automatically rotates the secret used by the NMA container. For the updated secret to take effect, the NMA container is restarted. You can verify that the NMA secret has been rotated using the following steps:

$ kubectl exec -it <vertica-db-pod-name> -c nma -- env | grep NMA_SECRET
NMA_SECRET_NAME=vertica-db-https-tls-xmmd2
NMA_SECRET_NAMESPACE=<vertica-namespace>

Automatically rotate TLS certificates

You can configure the VerticaDB to automatically rotate both httpsNMATLS and clientServerTLS certificates. Provide a list of Secrets and set the rotation interval as shown in the following example:

apiVersion: vertica.com/v1
kind: VerticaDB
metadata:
  name: vdb-tls
  annotations:
    ...
    vertica.com/enable-tls-auth: "true"
     
spec:
  ...
  clientServerTLS:
    autoRotate:
      interval: 43200 # rotates every 30 days (30 days * 24 hrs * 60 mins = 43200 mins )
      restartAtEnd: true
      secrets:
      - clientServerSecret1
      - clientServerSecret2
      - clientServerSecret3
    mode: TRY_VERIFY
  ...
  httpsNMATLS:
    autoRotate:
      secrets:
        - httpsSecret1
        - httpsSecret2
        - httpsSecret3
      interval: 180 # rotates every 3 hours
      restartAtEnd: true
      mode: TRY_VERIFY

After automatic certificate rotation is enabled, you can check the VerticaDB status to see the currently used secrets and their last update time:

$ kubectl describe vdb
Name:         vdb-tls
...
Status:
  ...
  Tls Configs:
    Auto Rotate Secrets:
      httpsSecret1
      httpsSecret2
      httpsSecret3
    Last Update:  2025-09-23T19:10:52Z # last updated date and time of httpsNMA secret
    Mode:         try_verify
    Name:         httpsNMA
    Secret:       httpsSecret3 # current in-use httpsNMA secret
    Auto Rotate Secrets:
      clientServerSecret1
      clientServerSecret1
      clientServerSecret1
    Last Update:   2025-09-23T19:15:53Z # last updated date and time of clientServer secret
    Mode:          try_verify
    Name:          clientServer
    Secret:        clientServerSecret1 # current in-use clientServer secret

Note

If a new certificate fails, the system automatically rolls back to the last known good Secret. It also logs a warning in the event log, skips the faulty Secret, and continues with the next one.
If you modify the Secret list and the current Secret still appears in the updated autoRotate.secrets[] list, rotation continues with the next Secret in the new list. If the current Secret is no longer in the list, rotation restarts from the first Secret.

You can verify that the TLS configuration of VerticaDB has been updated by following the steps in the Rotate TLS certificates section in this topic.

Certificate rotation using AWS secret versioning

You can store certificates in a single AWS Secrets Manager secret and use versioning to manage updates. This makes it easy to rotate certificates by changing the version ID.

To allow VerticaDB to read the secret from AWS Secrets Manager, see Secrets management.

Following are steps to use and rotate version enabled AWS secret:

Verify the configuration of your version enabled AWS secret:


$ aws secretsmanager describe-secret --secret-id my_vertica_secret
 {
     "ARN": "arn:aws:secretsmanager:us-east-1:821715312548:secret:my_vertica_secret-fn1msI",
     "Name": "my_vertica_secret",
     "Description": "secret with version id",
     "LastChangedDate": "2025-06-13T11:08:15.533000-04:00",
     "LastAccessedDate": "2025-06-12T20:00:00-04:00",
     "VersionIdsToStages": {
         "46c90cb1-58e9-4053-bac0-5798a9f03daf": [
             "AWSPREVIOUS"
         ],
         "bd8e7d37-12b9-4433-b292-4ea33ab9e8e4": [
             "AWSCURRENT"
         ]
      },
  "CreatedDate": "2025-06-13T11:01:41.729000-04:00"
 }

Let's assume you used AWSPREVIOUS version of the secret in your initial VerticaDB CR:


apiVersion: vertica.com/v1
kind: VerticaDB
metadata:
  annotations:
    ...
    vertica.com/enable-tls-auth: "true"
...

  Https NMATLS:
    Mode:             TRY_VERIFY
    Secret:           awssm://arn:aws:secretsmanager:us-east-1:821715312548:secret:my_vertica_secret-fn1msI@46c90cb1-58e9-4053-bac0-5798a9f03daf

To rotate the certificate, edit the VerticaDB and change the versionId to use the AWSCURRENT version as follows:


$ kubectl edit vdb cluster-name
apiVersion: vertica.com/v1
kind: VerticaDB
metadata:
  annotations:
    ...
    vertica.com/enable-tls-auth: "true"
...

  Https NMATLS:
    Mode:             TRY_VERIFY
    Secret:           awssm://  arn:aws:secretsmanager:us-east-1:821715312548:secret:my_vertica_secret-fn1msI@bd8e7d37-12b9-4433-b292-4ea33ab9e8e4

You can verify that the TLS configuration of VerticaDB has been updated by following the steps in the Rotate TLS certificates section in this topic.

2 - Enable TLS in Vertica on Kubernetes

To protect database communications and enforce certificate verification, the VerticaDB operator supports Transport Layer Security (TLS) for the following:

HTTPS/NMA service: Secures the REST interface used by vclusterops and the Node Management Agent (NMA).
Client-Server authentication: Secures connections between external client applications (vsql, JDBC, ODBC, ADO.NET) and Vertica server nodes.
Internode traffic: Encrypts and validates communications between database cluster nodes.

The Vertica database server does not store private keys or certificates in its catalog or on local disk. Instead, it dynamically reads TLS credentials from Kubernetes secrets or AWS Secrets Manager.

TLS configuration modes and parameters

The following table describes the TLS configuration parameters and their supported modes:

Parameter	Description	Supported modes	Default mode
`httpsNMATLS`	TLS for the HTTPS service and Node Management Agent (NMA).	`DISABLE`, `ENABLE`, `TRY_VERIFY`, `VERIFY_CA`, `VERIFY_FULL`	`TRY_VERIFY`
`clientServerTLS`	TLS for SQL client connections (vsql, drivers).	`DISABLE`, `ENABLE`, `TRY_VERIFY`, `VERIFY_CA`, `VERIFY_FULL`	`TRY_VERIFY`
`interNodeTLS`	TLS for internal cluster communication (version 26.1.0-0 and higher).	`DISABLE`, `ENABLE`, `VERIFY_CA`	`VERIFY_CA`

Note

Automatic secret generation: If you enable TLS and omit the secret field, the VerticaDB operator automatically generates self-signed TLS certificates in Kubernetes secrets named <vdb-name>-https-tls-<hash>, <vdb-name>-clientserver-tls-<hash>, and <vdb-name>-internode-tls-<hash>.
Custom certificates: If you supply your own certificates, they must be stored in a Kubernetes secret of type kubernetes.io/tls that contains the keys tls.key, tls.crt, and ca.crt. You can also store custom certificates in an AWS Secrets Manager secret.
Irreversibility: After TLS is enabled on a database, it cannot be disabled.

You can enable TLS when you:

Create the database
Revive the database
Update a database that was created or revived without TLS
Upgrade the operator or database server

Enable TLS when creating the database

When you initialize a new database (initPolicy: Create), you can configure TLS parameters directly in the initial VerticaDB custom resource (CR) manifest. The operator provisions the cluster with TLS configured and enabled from the start.

(Optional) If you are using custom certificates instead of operator-generated certificates, you can create your own in AWS Secrets Manager or create the Kubernetes secrets in the same namespace where the VerticaDB CR is deployed:

# Create custom secret for HTTPS/NMA
$ kubectl create secret generic custom-https-tls \
  --from-file=tls.key=/path/to/https.key \
  --from-file=tls.crt=/path/to/https.crt \
  --from-file=ca.crt=/path/to/ca.crt

# Create custom secret for Client-Server TLS
$ kubectl create secret generic custom-client-tls \
  --from-file=tls.key=/path/to/client.key \
  --from-file=tls.crt=/path/to/client.crt \
  --from-file=ca.crt=/path/to/ca.crt

# Create custom secret for Internode TLS
$ kubectl create secret generic custom-internode-tls \
  --from-file=tls.key=/path/to/internode.key \
  --from-file=tls.crt=/path/to/internode.crt \
  --from-file=ca.crt=/path/to/ca.crt

Define the initial VerticaDB CR manifest. Include the TLS annotations and specifications in metadata.annotations and spec:

apiVersion: vertica.com/v1
kind: VerticaDB
metadata:
  name: vertica-db
  annotations:
    vertica.com/tls-cache-duration: "86400"
    vertica.com/remove-tls-secret-on-vdb-delete: "false"
spec:
  initPolicy: Create
  dbName: vertdb
  licenseSecret: vertica-license
  passwordSecret: su-passwd
  communal:
    path: "s3://vertica-communal-storage/vertdb"
    endpoint: "https://s3.amazonaws.com"
    credentialSecret: s3-creds
    region: us-east-1
  subclusters:
    - name: primary
      size: 3
      serviceType: ClusterIP
  shardCount: 6
  httpsNMATLS:
    enabled: true
    mode: TRY_VERIFY
    secret: custom-https-tls       # Omit to allow the operator to auto-generate
  clientServerTLS:
    enabled: true
    mode: TRY_VERIFY
    secret: custom-client-tls      # Omit to allow the operator to auto-generate
  interNodeTLS:
    enabled: true
    mode: VERIFY_CA
    secret: custom-internode-tls   # Omit to allow the operator to auto-generate
  dbTlsConfig:
    tlsVersion: 2                  # 2 for TLS 1.2, 3 for TLS 1.3
    cipherSuites: ""

Apply the manifest:

$ kubectl apply -f verticadb-initial.yaml

Monitor the operator reconciliation events:

$ kubectl describe vdb vertica-db

Expected events include:

Normal  TLSConfigurationStarted    3m  verticadb-operator  Starting to configure TLS for httpsNMA
Normal  TLSConfigurationSucceeded  3m  verticadb-operator  Successfully set HTTP tls config
Normal  TLSConfigurationStarted    3m  verticadb-operator  Starting to configure TLS for clientServer
Normal  TLSConfigurationSucceeded  2m  verticadb-operator  Successfully set Server tls config
Normal  TLSConfigurationStarted    2m  verticadb-operator  Starting to configure TLS for interNode
Normal  TLSConfigurationSucceeded  2m  verticadb-operator  Successfully set Internode tls config

Verify the generated Kubernetes secrets (if auto-generated):
```
$ kubectl get secrets -l app.kubernetes.io/name=vertica
```

Verify the TLS authentication records created in the database:

=> SELECT auth_name, auth_host_type, auth_method, is_fallthrough_enabled FROM client_auth WHERE auth_name LIKE '%k8s%';
                   auth_name                   | auth_host_type | auth_method | is_fallthrough_enabled
----------------------------------------------+----------------+-------------+------------------------
 k8s_remote_ipv4_tls_builtin_auth             | HOSTSSL        | TLS         | False
 k8s_remote_ipv6_tls_builtin_auth             | HOSTSSL        | TLS         | False
 k8s_local_tls_builtin_auth                   | LOCALSSL       | TLS         | False
 k8s_remote_ipv4_reject_non_tls_builtin_auth  | HOSTNOSSL      | REJECT      | False
 k8s_remote_ipv6_reject_non_tls_builtin_auth  | HOSTNOSSL      | REJECT      | False
(5 rows)

Note

From version 26.2.0-2 and higher, the is_fallthrough_enabled flag is set to False by default. If you need to set it to true, use the vertica.com/enable-fallthrough: "true" annotation.

Enable TLS when reviving the database

When you revive an existing database (initPolicy: Revive) from data files on communal storage, the database catalog already contains references to the TLS configuration established when the database was running.

Important

The catalog stored in communal storage expects the specific certificate authorities and TLS certificates previously used. You must provide the original TLS private key (tls.key), certificate (tls.crt), and CA certificate (ca.crt) as Kubernetes secrets or AWS Secrets Manager's secrets before you apply the revive CR. If the secrets or keys do not match, the database revive or node synchronization fails.

Ensure the original TLS secrets exist in the cluster, based on how the original database stored its certificates:
- If the original VerticaDB CR used auto-generated secrets and vertica.com/remove-tls-secret-on-vdb-delete: "false" (the default), the auto-generated secrets are preserved and can be referenced directly when reviving in the same Kubernetes namespace. If you are reviving to a different namespace, copy the secrets to the new namespace.
- If the original cluster used custom certificates in Kubernetes secrets, reference the secrets if reviving in the same namespace, or recreate the original TLS secrets from backup files if reviving on a new cluster or namespace:
```
# Recreate the original HTTPS TLS secret
$ kubectl create secret generic vertica-db-https-tls-original \
  --from-file=tls.key=./backup/https.key \
  --from-file=tls.crt=./backup/https.crt \
  --from-file=ca.crt=./backup/ca.crt

# Recreate the original Client-Server TLS secret
$ kubectl create secret generic vertica-db-clientserver-tls-original \
  --from-file=tls.key=./backup/clientserver.key \
  --from-file=tls.crt=./backup/clientserver.crt \
  --from-file=ca.crt=./backup/ca.crt

# Recreate the original Internode TLS secret
$ kubectl create secret generic vertica-db-internode-tls-original \
  --from-file=tls.key=./backup/internode.key \
  --from-file=tls.crt=./backup/internode.crt \
  --from-file=ca.crt=./backup/ca.crt
```
- If the original secrets were stored in AWS Secrets Manager, no extra steps are required; reuse them directly.

Define the revive VerticaDB CR manifest with initPolicy: Revive, and reference the communal storage path and the original secrets:

apiVersion: vertica.com/v1
kind: VerticaDB
metadata:
  name: vertica-db
  annotations:
    vertica.com/tls-cache-duration: "86400"
    vertica.com/remove-tls-secret-on-vdb-delete: "false"
    vertica.com/ignore-cluster-lease: "true"
spec:
  initPolicy: Revive
  dbName: vertdb                   # Must match the name of the database being revived
  licenseSecret: vertica-license
  passwordSecret: su-passwd
  communal:
    path: "s3://vertica-communal-storage/vertdb"  # Existing non-empty communal path
    endpoint: "https://s3.amazonaws.com"
    credentialSecret: s3-creds
    region: us-east-1
  subclusters:
    - name: primary
      size: 3
  httpsNMATLS:
    enabled: true
    mode: TRY_VERIFY
    secret: vertica-db-https-tls-original
  clientServerTLS:
    enabled: true
    mode: TRY_VERIFY
    secret: vertica-db-clientserver-tls-original
  interNodeTLS:
    enabled: true
    mode: VERIFY_CA
    secret: vertica-db-internode-tls-original

Apply the manifest:

$ kubectl apply -f verticadb-revive.yaml

Monitor the operator reconciliation events:

$ kubectl describe vdb vertica-db

Expected events include:

Normal  TLSConfigurationStarted    3m  verticadb-operator  Starting to configure TLS for httpsNMA
Normal  TLSConfigurationSucceeded  3m  verticadb-operator  Successfully set HTTP tls config
Normal  TLSConfigurationStarted    3m  verticadb-operator  Starting to configure TLS for clientServer
Normal  TLSConfigurationSucceeded  2m  verticadb-operator  Successfully set Server tls config
Normal  TLSConfigurationStarted    2m  verticadb-operator  Starting to configure TLS for interNode
Normal  TLSConfigurationSucceeded  2m  verticadb-operator  Successfully set Internode tls config

Verify the generated Kubernetes secrets (if auto-generated):
```
$ kubectl get secrets -l app.kubernetes.io/name=vertica
```
Ensure the revive operation completes and the database pod status transitions to Ready.

Enable TLS after the database is created or revived

If a database was initialized or revived without TLS enabled (or TLS was disabled), you can enable TLS in place by updating the existing VerticaDB custom resource. The operator configures TLS and updates the NMA and HTTPS services without requiring a full cluster restart.

Edit the deployed custom resource:

$ kubectl edit vdb vertica-db

Modify or add the TLS annotations and specification blocks, then save and exit the editor:

apiVersion: vertica.com/v1
kind: VerticaDB
metadata:
  name: vertica-db
...
spec:
  # ... existing database spec ...

  # Add TLS configurations (provide custom secrets or omit secret for auto-generation)
  clientServerTLS:
    enabled: true
    mode: TRY_VERIFY
    secret: custom-client-tls
  httpsNMATLS:
    enabled: true
    mode: TRY_VERIFY
    secret: custom-https-tls
  interNodeTLS:
    enabled: true
    mode: VERIFY_CA
    secret: custom-internode-tls

Check the operator progress:

$ kubectl describe vdb vertica-db

You will observe events confirming TLS configuration across components:

Normal  TLSConfigurationStarted    3m  verticadb-operator  Starting to configure TLS for httpsNMA
Normal  TLSConfigurationSucceeded  3m  verticadb-operator  Successfully set HTTP tls config
Normal  TLSConfigurationStarted    3m  verticadb-operator  Starting to configure TLS for clientServer
Normal  TLSConfigurationSucceeded  2m  verticadb-operator  Successfully set Server tls config
Normal  TLSConfigurationStarted    2m  verticadb-operator  Starting to configure TLS for interNode
Normal  TLSConfigurationSucceeded  2m  verticadb-operator  Successfully set Internode tls config

Upgrade scenarios and considerations for TLS

When you upgrade your environment, special considerations apply depending on whether you are upgrading the VerticaDB operator or the database server.

VerticaDB operator upgrade

Upgrading from operator v2.2.0 or earlier

In VerticaDB operator version 2.2.0, the selector labels for StatefulSets were modified. Kubernetes selector labels are immutable, so the operator reconciler automatically deletes existing StatefulSets and recreates them with updated labels, which triggers a rolling restart of all database pods.

Important

If you are upgrading from operator version v2.2.0 or earlier, you must wait for the rolling restart of all database pods to finish before you configure or modify TLS settings. Attempting to configure TLS during an active rolling restart might cause reconciliation conflicts.

After the rolling restart is complete, you can configure TLS as described in Enable TLS after the database is created or revived.

Upgrading from operator versions prior to v25.3.0 (pre-operator TLS support)

Operator-managed TLS (through CR parameters and Kubernetes secrets) was introduced in version 25.3.0-0. If you are upgrading from an operator version earlier than v25.3.0, consider the following scenarios:

Scenario 1: TLS was previously enabled manually in Vertica

If TLS was configured manually inside the database (for example, through ALTER TLS CONFIGURATION or custom SQL commands), existing TLS configurations remain active and untouched after the operator upgrade.

To manage TLS through the VerticaDB operator going forward, export your existing database certificate, private key, and CA certificate into Kubernetes secrets, and then edit the VerticaDB CR to reference them:

# 1. Create a Kubernetes secret with existing certificates
$ kubectl create secret generic existing-db-tls \
  --from-file=tls.key=/path/to/existing.key \
  --from-file=tls.crt=/path/to/existing.crt \
  --from-file=ca.crt=/path/to/existing_ca.crt

# 2. Update the existing VerticaDB CR
...
spec:
  clientServerTLS:
    enabled: true
    mode: TRY_VERIFY
    secret: existing-db-tls
  httpsNMATLS:
    enabled: true
    mode: TRY_VERIFY
    secret: existing-db-tls

Scenario 2: TLS was not enabled

If TLS was not previously enabled, upgrade the operator to the latest version and configure TLS as described in Enable TLS after the database is created or revived.

Automated TLS spec migration in operator v25.4.0 and higher

Beginning in operator version 25.4.0, the operator automatically backfills and sets the explicit enabled boolean flags in spec.httpsNMATLS.enabled and spec.clientServerTLS.enabled during reconciliation.

If you are upgrading from an operator version earlier than 25.4.0 where the enabled fields are nil in the CR spec, the operator checks the vertica.com/enable-tls-auth annotation and automatically updates the CR spec to match:

If vertica.com/enable-tls-auth: "true" is set, the operator sets spec.httpsNMATLS.enabled: true and spec.clientServerTLS.enabled: true.
If vertica.com/enable-tls-auth: "false" (or not set), the operator sets both fields to false.

Vertica database server upgrade

When you upgrade the database server image (for example, updating spec.image in the VerticaDB CR), consider the following:

Configuration retention

All database configurations, catalog objects, and TLS settings configured in previous versions are preserved as is.

Automatic TLS fallthrough migration (upgrading from v26.2.0-1 or earlier to v26.2.0-2 or higher)

Database server version 26.2.0-2 introduced stricter built-in client authentication rules (HOSTNOSSL rejections) along with the vertica.com/enable-fallthrough annotation.

Note

If you have TLS configured through the VerticaDB operator for database server version 26.2.0-1 or earlier, the operator automatically sets the following:

...
metadata:
  annotations:
    vertica.com/enable-fallthrough: "true"

This ensures that existing client applications that rely on fallback or password authentication continue to connect without disruption.

Post-upgrade verification

After you complete the database upgrade, verify that the client authentication rules remain the same as they were before the upgrade:

=> SELECT auth_name, auth_host_type, auth_method, is_fallthrough_enabled
   FROM client_auth
   WHERE auth_name LIKE '%k8s%';
             auth_name             | auth_host_type | auth_method | is_fallthrough_enabled
----------------------------------+----------------+-------------+------------------------
 k8s_remote_ipv4_tls_builtin_auth | HOSTSSL        | TLS         | True
 k8s_remote_ipv6_tls_builtin_auth | HOSTSSL        | TLS         | True
 k8s_local_tls_builtin_auth       | LOCALSSL       | TLS         | True
(3 rows)

If you want to enforce strict TLS authentication (disallowing fallthrough to password authentication), edit the CR and set vertica.com/enable-fallthrough: "false".

Verify and validate

After TLS is configured using any of the use cases, verify the TLS status inside the database.

Connect to the database using SSL/TLS through vsql. The initial banner displays the negotiated SSL/TLS cipher and protocol:

$ vsql -h <VERTICA_SERVICE_IP_OR_HOST> -U dbadmin -w <PASSWORD>

Example output:

Welcome to vsql, the Vertica Analytic Database interactive terminal.

SSL connection (cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, protocol: TLSv1.2)

Verify the database TLS configurations by querying the tls_configurations system table:

=> SELECT name, owner, certificate, ca_certificate, cipher_suites, mode
   FROM tls_configurations;
     name     |  owner  |     certificate     |     ca_certificate     | cipher_suites |    mode
--------------+---------+---------------------+------------------------+---------------+------------
 https        | dbadmin | https_cert_0        | https_ca_cert_0        |               | TRY_VERIFY
 server       | dbadmin | server_cert_0       | server_ca_cert_0       |               | TRY_VERIFY
 data_channel | dbadmin | data_channel_cert_0 | data_channel_ca_cert_0 |               | VERIFY_CA
 LDAPLink     | dbadmin |                     |                        |               | DISABLE
 LDAPAuth     | dbadmin |                     |                        |               | DISABLE
(5 rows)

Verify the built-in client authentication rules. The operator automatically configures these TLS client authentication records:

=> SELECT auth_name, auth_host_type, auth_method, is_fallthrough_enabled FROM client_auth WHERE auth_name LIKE '%k8s%';
                   auth_name                   | auth_host_type | auth_method | is_fallthrough_enabled
----------------------------------------------+----------------+-------------+------------------------
 k8s_remote_ipv4_tls_builtin_auth             | HOSTSSL        | TLS         | False
 k8s_remote_ipv6_tls_builtin_auth             | HOSTSSL        | TLS         | False
 k8s_local_tls_builtin_auth                   | LOCALSSL       | TLS         | False
 k8s_remote_ipv4_reject_non_tls_builtin_auth  | HOSTNOSSL      | REJECT      | False
 k8s_remote_ipv6_reject_non_tls_builtin_auth  | HOSTNOSSL      | REJECT      | False
(5 rows)

Verify the active secret mapping and cache duration to confirm that the database references the expected Kubernetes secret and cache configuration:

=> SELECT name, secret_name, secret_manager_config
   FROM certificates;

Example output:

          name           |            secret_name            |                        secret_manager_config
------------------------+-----------------------------------+---------------------------------------------------------------------
 https_ca_cert_0        | vertica-db-https-tls-lhj82        | {"data-key":"ca.crt","namespace":"vertica","cache-duration":86400}
 server_ca_cert_0       | vertica-db-clientserver-tls-j86v9 | {"data-key":"ca.crt","namespace":"vertica","cache-duration":86400}
 data_channel_ca_cert_0 | vertica-db-internode-tls-gbcx8    | {"data-key":"ca.crt","namespace":"vertica","cache-duration":86400}
 https_cert_0           | vertica-db-https-tls-lhj82        | {"data-key":"tls.crt","namespace":"vertica","cache-duration":86400}
 server_cert_0          | vertica-db-clientserver-tls-j86v9 | {"data-key":"tls.crt","namespace":"vertica","cache-duration":86400}
 data_channel_cert_0    | vertica-db-internode-tls-gbcx8    | {"data-key":"tls.crt","namespace":"vertica","cache-duration":86400}
(6 rows)