FAQ - Enable TLS for service, fabric and heartbeat traffic on an existing cluster

FAQ - Enable TLS for service, fabric and heartbeat traffic on an existing cluster.


How can I enable TLS for service, fabric and heartbeat traffic on my cluster with minimal downtime.


TLS can be enabled on the Aerospike cluster via rolling restarts. This procedure will require two rounds of rolling restarts on the cluster. To avoid affecting service, fabric and heartbeat traffic, we need to expose both TLS ports and non-TLS (or clear) ports initially before disabling the non-TLS ports…


  1. Make configurational changes on first node for TLS (service/heartbeat/fabric). Make sure to specify both tls-port and port (non-TLS or clear port) configuration in the respective network configuration stanzas.

TLS related configuration, parameter definitions and examples can be found on the TLS Configuration documentation as well as on the Enabling and Validating TLS knowledge base article.

service {
    port 3000
    tls-port 4333

heartbeat {
    port 3002
    tls-port 3012

  fabric {
    port 3001
    tls-port 3011
  1. Restart the Aerospike service on first node with the updaetd configuration.
  2. Verify the node joined the cluster successfully and there are no warnings in the Aerospike server logs.
  3. Repeat for all nodes in the cluster.

At this stage:

  • If TLS is enabled for service (or client traffic), client applications will continue to communicate with the cluster via clear ports (non-TLS).
  • If TLS is enabled for fabric or heartbeat, the Aerospike cluster will prefer TLS over non-TLS. So it can identify the endpoints between two nodes and decide whether to use TLS or non-TLS for the communication. If two nodes see that they can use TLS between them, they will use the TLS endpoints.
  1. Switch-over the client applications to use the TLS port (if enabled for service). Aerospike client applications need to be configured with correct certificates, tls name, tls protcols, cipher suite, etc. Refer to the Aerospike C Client config API reference documentation.

For heartbeat and fabric, the Aerospike server nodes will automatically start using TLS endpoints at this point.

  1. Once all the applications have switched over to use the TLS endpoint, verify there are no errors or warnings on both the Aerospike server and client logs.

  2. Another rolling restart across the cluster can be performed to remove the clear ports (non-TLS ports) from the respective network configuration stanzas, to move the cluster into having full TLS communication exclusively.




June 5 2019