Enable TLS In EMQX

Objective

Customize TLS certificates using the extraVolumes and extraVolumeMounts fields.

Create a Secret Based On TLS Certificate

A secret is an object that contains a small amount of sensitive information, such as passwords, tokens, or keys. In this demonstration, we use secrets to store TLS certificate information, so we need to create one before creating the EMQX cluster.

For more information, please refer to the Secret documentation.

Save the following as a YAML file and deploy it using the kubectl apply command:

apiVersion: v1
kind: Secret
metadata:
  name: emqx-tls
type: kubernetes.io/tls
stringData:
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  tls.crt: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  tls.key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    -----END RSA PRIVATE KEY-----

TIP

In this example, the contents of the above three fields are omitted. Please fill them with your own certificate contents.

• ca.crt should contain the CA certificate.
• tls.crt should contain the server certificate.
• tls.key should contain the server's private key.

Configure EMQX Cluster

EMQX CRD apps.emqx.io/v2beta1 provides the following fields to configure additional volumes and mount points for the EMQX cluster:

• .spec.coreTemplate.extraVolumes
• .spec.coreTemplate.extraVolumeMounts
• .spec.replicantTemplate.extraVolumes
• .spec.replicantTemplate.extraVolumeMounts

In this demonstration, we will use these fields to provide TLS certificates to the EMQX cluster.

There are many types of Volumes. For information about Volumes, please refer to the Volumes documentation. Here we are using the secret volume type.

1. Save the following as a YAML file and deploy it using kubectl apply:

apiVersion: apps.emqx.io/v2beta1
kind: EMQX
metadata:
  name: emqx
spec:
  image: emqx/emqx:6.0.1
  config:
    # Configure the TLS listener certificates mounted from the `emqx-tls` volume:
    data: |
      listeners.ssl.default {
        bind = "0.0.0.0:8883"
        ssl_options {
          cacertfile = "/mounted/cert/ca.crt"
          certfile = "/mounted/cert/tls.crt"
          keyfile = "/mounted/cert/tls.key"
          gc_after_handshake = true
          handshake_timeout = 5s
        }
      }
      license {
        key = "..."
      }
  coreTemplate:
    spec:
      extraVolumes:
        - name: emqx-tls
          secret:
            secretName: emqx-tls
      extraVolumeMounts:
        - name: emqx-tls
          mountPath: /mounted/cert
  replicantTemplate:
    spec:
      extraVolumes:
        # Create a `secret` volume type named `emqx-tls`:
        - name: emqx-tls
          secret:
            secretName: emqx-tls
      extraVolumeMounts:
        - name: emqx-tls
          # Directory where the TLS certificate is mounted to EMQX nodes:
          mountPath: /mounted/cert
  dashboardServiceTemplate:
    spec:
      type: LoadBalancer
  listenersServiceTemplate:
    spec:
      type: LoadBalancer

2. Wait for the EMQX cluster to become ready.

Check the status of the EMQX cluster using kubectl get, and make sure that STATUS is Ready. This may take a while.

$ kubectl get emqx
NAME   STATUS   AGE
emqx   Ready    10m

Verify TLS Connection using MQTTX

MQTTX CLI is an open-source MQTT 5.0 command-line client tool, designed to help developers quickly get started with MQTT services and applications.

1. Obtain the external IP of the EMQX listeners service.

external_ip=$(kubectl get svc emqx-listeners -o json | jq '.status.loadBalancer.ingress[0].ip')

2. Subscribe to messages using MQTTX CLI.

Connect to the TLS listener port 8883, using the --insecure flag to skip certificate verification.

mqttx sub -h ${external_ip} -p 8883 -t "hello" -l mqtts --insecure
[10:00:25] › … Connecting...
[10:00:25] › ✔ Connected
[10:00:25] › … Subscribing to hello...
[10:00:25] › ✔ Subscribed to hello

3. In a separate terminal window, publish a message.

mqttx pub -h ${external_ip} -p 8883 -t "hello" -m "hello world" -l mqtts --insecure
[10:00:58] › … Connecting...
[10:00:58] › ✔ Connected
[10:00:58] › … Message Publishing...
[10:00:58] › ✔ Message published

4. Observe the subscriber client receiving the message.

This indicates that both the publisher and subscriber clients successfully communicate with the broker over a TLS connection.

[10:00:58] › payload: hello world