Skip to content

Latest commit

 

History

History
237 lines (181 loc) · 8.53 KB

configure-emqx-tls.md

File metadata and controls

237 lines (181 loc) · 8.53 KB

Enable TLS In EMQX

Task Target

Customize TLS certificates via the extraVolumes and extraVolumeMounts fields.

Create Secret Based On TLS Certificate

Secret is an object that contains a small amount of sensitive information such as passwords, tokens, or keys. For its documentation, please refer to: Secret. In this article, we use Secret to save TLS certificate information, so we need to create Secret based on TLS certificate before creating EMQX cluster.

  • Save the following as a YAML file and deploy it with 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-----

    ca.crt indicates the content of the CA certificate, tls.crt indicates the content of the server certificate, and tls.key indicates the content of the server private key. In this example, the contents of the above three fields are omitted, please fill them with the contents of your own certificate.

Configure EMQX Cluster

The following is the relevant configuration of EMQX Custom Resource. You can choose the corresponding APIVersion according to the version of EMQX you want to deploy. For the specific compatibility relationship, please refer to EMQX Operator Compatibility:

:::: tabs type:card ::: tab apps.emqx.io/v2beta1

apps.emqx.io/v2beta1 EMQX supports .spec.coreTemplate.extraVolumes and .spec.coreTemplate.extraVolumeMounts and .spec.replicantTemplate.extraVolumes and .spec.replicantTemplate.extraVolumeMounts fields to EMQX The cluster configures additional volumes and mount points. In this article, we can use these two fields to configure TLS certificates for the EMQX cluster.

There are many types of Volumes. For the description of Volumes, please refer to the document: Volumes. In this article we are using the secret type.

  • Save the following as a YAML file and deploy it with the kubectl apply command

    apiVersion: apps.emqx.io/v2beta1
kind: EMQX
metadata:
  name: emqx
spec:
  image: emqx:5
  config:
    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
        }
      }
  coreTemplate:
    spec:
      extraVolumes:
        - name: emqx-tls
          secret:
            secretName: emqx-tls
      extraVolumeMounts:
        - name: emqx-tls
          mountPath: /mounted/cert
  replicantTemplate:
    spec:
      extraVolumes:
        - name: emqx-tls
          secret:
            secretName: emqx-tls
      extraVolumeMounts:
        - name: emqx-tls
          mountPath: /mounted/cert
  dashboardServiceTemplate:
    spec:
      type: LoadBalancer
  listenersServiceTemplate:
    spec:
      type: LoadBalancer

    The .spec.coreTemplate.extraVolumes field configures the volume type as: secret, and the name as: emqx-tls.

    The .spec.coreTemplate.extraVolumeMounts field configures the directory where the TLS certificate is mounted to EMQX: /mounted/cert.

    The .spec.config.data field configures the TLS listener certificate path. For more TLS listener configurations, please refer to the document: Configuration Manual.

  • Wait for EMQX cluster to be ready, you can check the status of EMQX cluster through the kubectl get command, please make sure that STATUS is Running, this may take some time

    $ kubectl get emqx

NAME   IMAGE      STATUS    AGE
emqx   emqx:5.1   Running   10m

  • Obtain the External IP of EMQX cluster and access EMQX console

    EMQX Operator will create two EMQX Service resources, one is emqx-dashboard and the other is emqx-listeners, corresponding to EMQX console and EMQX listening port respectively.

    $ kubectl get svc emqx-dashboard -o json | jq '.status.loadBalancer.ingress[0].ip'

192.168.1.200

    Access http://192.168.1.200:18083 through a browser, and use the default username and password admin/public to login EMQX console.

::: ::: tab apps.emqx.io/v1beta4

apps.emqx.io/v1beta4 EmqxEnterprise supports configuring volumes and mount points for EMQX clusters through .spec.template.spec.volumes and .spec.template.spec.emqxContainer.volumeMounts fields. In this article, we can use these two fields to configure TLS certificates for the EMQX cluster.

There are many types of Volumes. For the description of Volumes, please refer to the document: Volumes. In this article we are using the secret type.

  • Save the following as a YAML file and deploy it with the kubectl apply command

    apiVersion: apps.emqx.io/v1beta4
kind: EmqxEnterprise
metadata:
  name: emqx-ee
spec:
  template:
    spec:
      emqxContainer:
        image:
          repository: emqx/emqx-ee
          version: 4.4.14
        emqxConfig:
          listener.ssl.external.cacertfile: /mounted/cert/ca.crt
          listener.ssl.external.certfile: /mounted/cert/tls.crt
          listener.ssl.external.keyfile: /mounted/cert/tls.key
          listener.ssl.external: "0.0.0.0:8883"
          listener.ssl.external.gc_after_handshake: "true"
          listener.ssl.external.hibernate_after: 5s
        volumeMounts:
          - name: emqx-tls
            mountPath: /mounted/cert
      volumes:
        - name: emqx-tls
          secret:
            secretName: emqx-tls
serviceTemplate:
  spec:
    type: LoadBalancer

    The .spec.template.spec.volumes field configures the volume type as: secret, and the name as: emqx-tls.

    The .spec.template.spec.emqxContainer.volumeMounts field configures the directory where the TLS certificate is mounted to EMQX: /mounted/cert.

    The .spec.template.spec.emqxContainer.emqxConfig field configures the TLS listener certificate path. For more TLS listener configurations, please refer to the document: tlsexternal.

  • Wait for EMQX cluster to be ready, you can check the status of EMQX cluster through the kubectl get command, please make sure that STATUS is Running, this may take some time

    $ kubectl get emqxenterprises
NAME      STATUS   AGE
emqx-ee   Running  8m33s

  • Obtain the External IP of EMQX cluster and access EMQX console

    $ kubectl get svc emqx-ee -o json | jq '.status.loadBalancer.ingress[0].ip'

192.168.1.200

    Access http://192.168.1.200:18083 through a browser, and use the default username and password admin/public to login EMQX console.

::: ::::

Verify TLS Connection Using MQTT X CLI

MQTT X CLI is an open source MQTT 5.0 command line client tool, designed to help developers to more Quickly develop and debug MQTT services and applications.

  • Obtain the External IP of EMQX cluster

    :::: tabs type:card ::: tab apps.emqx.io/v2beta1

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

    ::: ::: tab apps.emqx.io/v1beta4

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

    ::: ::::

  • Subscribe to messages using MQTT X CLI

    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

  • Create a new terminal window and publish a message using the MQTT X CLI

    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

  • View messages received in the subscribed terminal window

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