TLS Setup

Overview

Server-side TLS is the baseline transport security for any KubeMQ connection that leaves a trusted network — it encrypts the wire and lets the client confirm it's really talking to your KubeMQ server, not an impersonator. Reach for it whenever traffic crosses a public network or a boundary you don't fully control; skip it and channel names, payloads, and client IDs travel in plaintext with no protection against a spoofed endpoint.

It works by pairing the client with the CA certificate that signed the server's TLS certificate: KubeMQ::TLSConfig.new(enabled: true, ca_file: ...) loads that CA file, and the client performs a standard TLS handshake, validating the server's certificate chain before any request is sent. The client presents no certificate of its own — only the server proves its identity.

Gotchas: this is one-way trust — it stops eavesdropping and server impersonation, but the server still can't verify who the client is (that's what mTLS adds). ca_file must point to the issuing CA (or full chain), not the server's leaf certificate, or the handshake fails outright and raises KubeMQ::Error. The insecure_skip_verify escape hatch disables certificate validation entirely — it's fine for a local self-signed cert in development, but leaving it on in production defeats the point of TLS.

Prerequisites

• KubeMQ server running with TLS enabled
• Ruby SDK installed (gem install kubemq)
• CA certificate file

Code

require 'kubemq'

address = ENV.fetch('KUBEMQ_ADDRESS', 'localhost:50000')
ca_file = ENV.fetch('KUBEMQ_CA_FILE', '/path/to/ca.pem')

begin
  tls = KubeMQ::TLSConfig.new(
    enabled: true,
    ca_file: ca_file
  )
  client = KubeMQ::PubSubClient.new(
    address: address,
    client_id: 'tls-example',
    tls: tls
  )
  puts "Connected with TLS to #{address}"

  info = client.ping
  puts "Ping OK: host=#{info.host}, version=#{info.version}"
rescue KubeMQ::Error => e
  puts "KubeMQ error: #{e.message}"
ensure
  client&.close
  puts 'Connection closed'
end

How It Works

• TLSConfig with ca_file enables server certificate verification.
• The client verifies the server's certificate against the provided CA.
• For self-signed certificates in development, set insecure_skip_verify: true.
• Review timeouts, channel names, and client IDs before running against shared environments.

Related

• Ruby SDK Reference
• mTLS Setup
• Token Authentication