使用 BrokerListener 保護 MQTT 代理程式通訊

重要事項

本頁包含使用 Kubernetes 部署清單管理 Azure IoT Operations 元件的說明，該清單已在預覽中。此功能以數項限制提供，不應用於生產工作負載。

請參閱 Microsoft Azure 預覽版增補使用規定，以了解適用於 Azure 功能 (搶鮮版 (Beta)、預覽版，或尚未正式發行的版本) 的法律條款。

BrokerListener 資源對應至網路端點，該端點會透過網路向用戶端公開代理程式。您可以為每個代理程式擁有一或多個 BrokerListener 資源，每個代理程式都有多個連接埠和不同的存取控制。

每個 BrokerListener 連接埠可以有自己的驗證和授權規則，這些規則會定義誰可以連線到該接聽程式連接埠，以及他們可以在代理程式上執行的動作。您可以使用 BrokerAuthentication 和 BrokerAuthorization 資源來指定每個接聽程式連接埠的存取控制原則。此彈性可讓您根據 MQTT 用戶端的需求和使用案例，微調 MQTT 用戶端的權限和角色。

提示

預設 MQTT 代理程式部署是叢集 IP 服務，需要用戶端連線到傳輸層安全性 (TLS) 通訊協定，並使用服務帳戶權杖進行驗證。從叢集外部連線的用戶端需要額外的設定才能連線。

代理程式接聽程式具有下列特性：

名稱：接聽程式的名稱。除非覆寫，否則此名稱也是 Kubernetes 服務名稱。
服務類型：您最多可以有三個接聽程式，每個服務類型一個接聽程式。預設接聽程式是服務類型 ClusterIp。
連接埠：每個接聽程式都支援多個連接埠。連接埠不能與不同的接聽程式發生衝突。
驗證和授權參考：每個連接埠都已設定 BrokerAuthentication 和 BrokerAuthorization。
TLS：每個連接埠會套用 [手動] 或 [自動] TLS 設定。
通訊協定：每個連接埠都可以啟用 [透過 WebSocket 的 MQTT]。

如需所有可用設定的清單，請參閱代理程式接聽程式 API 參考。

預設 BrokerListener

當您部署 Azure IoT 操作時，部署會建立名為 default 的BrokerListener 資源。此接聽程式用於 IoT 操作元件之間的加密內部通訊。預設接聽程式是預設代理程式的一部分。

它會在連接埠 18883 上公開 ClusterIp 服務。
它會要求用戶端使用 Kubernetes 服務帳戶驗證。
它有自動管理的 TLS 憑證。
它不會設定任何用戶端授權原則。

注意

若要避免中斷內部 IoT 操作通訊，請將預設接聽程式保持不變，並專用於內部使用。針對外部通訊，請建立新的接聽程式。如果您需要使用 ClusterIp 服務，請將更多連接埠新增至預設接聽程式，而不需要變更任何現有的設定。

若要檢視或編輯預設接聽程式，請遵循下列步驟。

在 Azure 入口網站中，移至您的 IoT 操作執行個體。
在 [元件] 底下，選取 [MQTT 代理程式]。
從代理程式接聽程式清單中，選取 [預設] 接聽程式。
檢閱接聽程式設定，但請避免修改任何現有的設定。請改為建立新的連接埠，並視需要進行設定。

使用 az iot ops broker listener show 命令來檢視本機 MQTT 訊息代理程式默認接聽程式。

az iot ops broker listener show --resource-group <ResourceGroupName> --instance <AioInstanceName> --broker default --name default

當您使用 Bicep 修改預設接聽程式時，請特別注意。請勿變更現有的設定。相反地，將更多連接埠新增至預設接聽程式。下列範例示範如何將新的連接埠新增至預設接聽程式：

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-11-01' existing = {
  parent: aioInstance
  name: 'default'
}

resource defaultListener 'Microsoft.IoTOperations/instances/brokers/listeners@2024-11-01' = {
  parent: defaultBroker
  name: 'default'
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    // Don't change the service name or service type
    serviceType: 'ClusterIp'
    serviceName: 'aio-broker'
    ports: [
      // Don't modify the default port 18883 settings
      {
        port: 18883
        authenticationRef: 'default'
        protocol: 'Mqtt'
        tls: {
          mode: 'Automatic'
          certManagerCertificateSpec: {
            issuerRef: {
              name: 'azure-iot-operations-aio-certificate-issuer'
              kind: 'ClusterIssuer'
              group: 'cert-manager.io'
            }
            privateKey: {
              algorithm: 'Ec256'
              rotationPolicy: 'Always'
            }
          }
        }
      }
      // Add more ports here, like the following example
      {
        port: 1884
        protocol: 'Mqtt'
      }
    ]
  }
}

使用 Azure CLI 部署 Bicep 檔案：

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

若要檢視預設 BrokerListener 資源，請使用下列命令：

kubectl get brokerlistener default -n azure-iot-operations -o yaml

輸出看起來應該類似此範例，其中大部分的中繼資料都已移除，以求簡潔：

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerListener
metadata:
  name: default
  namespace: azure-iot-operations
  ownerReferences:
  - apiVersion: mqttbroker.iotoperations.azure.com/v1
    kind: Broker
    name: default
spec:
  serviceType: ClusterIp
  serviceName: aio-broker
  ports:
  - port: 18883
    authenticationRef: default
    protocol: Mqtt
    tls:
      mode: Automatic
      certManagerCertificateSpec:
        issuerRef:
          name: azure-iot-operations-aio-certificate-issuer
          kind: ClusterIssuer
          group: cert-manager.io
        privateKey:
          algorithm: Ec256
          rotationPolicy: Always

若要將沒有 TLS 和驗證的新連接埠 1883 新增至預設接聽程式，請使用 kubectl patch 命令：

kubectl patch brokerlistener default -n azure-iot-operations --type='json' -p='[{"op": "add", "path": "/spec/ports/-", "value": {"port": 1883, "protocol": "Mqtt"}}]'

請避免修改預設代理程式接聽程式

若要防止中斷內部 IoT 操作通訊，請將預設接聽程式保持不變，並專用於內部使用。針對外部通訊，請建立新的接聽程式。

由於預設代理程式接聽程式使用服務類型 ClusterIp，且每個服務類型只能有一個接聽程式，因此，如果您需要使用 ClusterIp 服務，請將更多連接埠新增至預設接聽程式，而不需要變更任何現有的設定。

建立新的代理程式接聽程式

若要建立新的接聽程式，請指定下列設定：

名稱：接聽程式的名稱。除非覆寫，否則此名稱也是 Kubernetes 服務名稱。
服務類型：Kubernetes 服務的類型。請參閱服務類型。
連接埠：要接聽的連接埠清單。請參閱連接埠。
服務名稱 (選擇性)：覆寫 Kubernetes 服務名稱。請參閱服務名稱。

範例：使用兩個連接埠建立新的接聽程式

此範例示範如何使用 LoadBalancer 服務類型建立新的接聽程式。 BrokerListener 資源會定義接受來自用戶端 MQTT 連線的兩個通訊埠。

第一個連接埠會在連接埠 1883 上接聽，而不需要 TLS 和驗證。此設定僅適用於測試。請勿在實際執行環境中使用此設定。
第二個通訊連接埠會在通訊連接埠 8883 上接聽，使用 TLS 且啟用驗證。只有具有 Kubernetes 服務帳戶權杖的已驗證用戶端才能連線。 TLS 會設定為 [自動模式]，使用 cert-manager 從預設簽發者管理伺服器憑證。此設定更接近實際執行設定。

在 Azure 入口網站中，移至您的 IoT 操作執行個體。
在 [元件] 底下，選取 [MQTT 代理程式]。

選取 [適用於 LoadBalancer 的 MQTT 代理程式接聽程式]>[建立]。

輸入下列設定：

設定	描述
名稱	BrokerListener 資源的名稱。
服務名稱	Kubernetes 服務的名稱。保留空白，以使用接聽程式名稱作為服務名稱。
服務類型	LoadBalancer 已選取。

在 [連接埠] 下，輸入第一個連接埠的下列設定：

設定描述

連接埠輸入 1883。

驗證選擇 [無]。

授權選擇 [無]。

通訊協定選擇 [MQTT]。

TLS 不要新增。
選取 [新增連接埠項目] 以新增第二個連接埠，然後輸入下列設定：

設定描述

連接埠輸入 8883。

驗證選擇 [預設值]。

授權選擇 [無]。

通訊協定選擇 [MQTT]。

TLS 選取 [新增]。
在 [TLS 設定] 窗格中，輸入下列設定：

設定描述

TLS 模式選擇 [自動]。

簽發者名稱輸入 azure-iot-operations-aio-certificate-issuer。

簽發者種類選擇 [ClusterIssuer]。

將其他設定保留為預設值，然後選取 [套用]。
選取 [建立接聽程式]。

設定	描述
連接埠	輸入 1883。
驗證	選擇 [無]。
授權	選擇 [無]。
通訊協定	選擇 [MQTT]。
TLS	不要新增。

設定	描述
連接埠	輸入 8883。
驗證	選擇 [預設值]。
授權	選擇 [無]。
通訊協定	選擇 [MQTT]。
TLS	選取 [新增]。

設定	描述
TLS 模式	選擇 [自動]。
簽發者名稱	輸入 `azure-iot-operations-aio-certificate-issuer`。
簽發者種類	選擇 [ClusterIssuer]。

使用 az iot ops broker listener apply 命令來建立新的 MQTT 訊息代理程式接聽程式。

az iot ops broker listener apply --resource-group <ResourceGroupName> --instance <AioInstanceName> --broker default --name <ListenerName> --config-file <ConfigFilePathAndFileName>

參數 --config-file 是 JSON 組態檔的路徑和檔名，其中包含資源屬性。

在此範例中，假設名為 loadbalancer-listener.json 的組態檔，其中包含儲存在使用者主目錄中的下列內容：

{
    "serviceType": "LoadBalancer",
    "ports": [
        {
            "port": 1883,
            "protocol": "Mqtt"
        },
        {
            "authenticationRef": "default",
            "port": 8883,
            "protocol": "Mqtt",
            "tls": {
                "mode": "Automatic",
                "certManagerCertificateSpec": {
                    "issuerRef": {
                        "name": "azure-iot-operations-aio-certificate-issuer",
                        "kind": "ClusterIssuer",
                        "group": "cert-manager.io"
                    }
                }
            }
        }
    ]
}

建立名為 aio-broker-loadbalancer 的新接聽程式的範例命令如下所示：

az iot ops broker listener apply --resource-group myResourceGroupName --instance myAioInstanceName --broker default --name aio-broker-loadbalancer --config-file ~/loadbalancer-listener.json

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param listenerName string = '<LISTENER_NAME>'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-11-01' existing = {
  parent: aioInstance
  name: 'default'
}

resource loadBalancerListener 'Microsoft.IoTOperations/instances/brokers/listeners@2024-11-01' = {
  parent: defaultBroker
  name: listenerName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }

  properties: {
    serviceType: 'LoadBalancer'
    ports: [
      {
        port: 1883
        protocol: 'Mqtt'
      }
      {
        authenticationRef: 'default'
        port: 8883
        protocol: 'Mqtt'
        tls: {
          mode: 'Automatic'
          certManagerCertificateSpec: {
            issuerRef: {
              name: 'azure-iot-operations-aio-certificate-issuer'
              kind: 'ClusterIssuer'
              group: 'cert-manager.io'
            }
          }
        }
      }
    ]
  }
}

使用 Azure CLI 部署 Bicep 檔案：

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerListener
metadata:
  name: <LISTENER_NAME>
  namespace: azure-iot-operations
spec:
  brokerRef: default
  serviceType: LoadBalancer
  ports:
  - port: 1883
    protocol: Mqtt
  - port: 8883
    authenticationRef: default
    protocol: Mqtt
    tls:
      mode: Automatic
      certManagerCertificateSpec:
        issuerRef:
            name: azure-iot-operations-aio-certificate-issuer
            kind: ClusterIssuer
            group: cert-manager.io

服務類型

每個 BrokerListener 資源都會對應至 Kubernetes 服務。服務類型會決定代理程式如何向網路公開。支援的服務類型如下：

ClusterIp：在叢集內部 IP 上公開代理程式。用戶端可以從叢集內連線到代理程式。此預設服務類型適用於預設接聽程式。
NodePort：在靜態連接埠上公開每個節點 IP 上的代理程式。用戶端可以從叢集外部連線到代理程式。此服務類型適用於開發和測試。
LoadBalancer：在外部公開代理程式。服務會指派外部 IP 位址，用戶端可用來連線到代理程式。此服務類型是實際執行部署最常見的類型。

每個服務類型只有一個接聽程式

每個服務類型只允許一個接聽程式。如果您需要相同服務類型的更多連線能力，請將更多連接埠新增至該服務類型的現有接聽程式。

服務名稱

服務名稱是與代理程式相關聯的 Kubernetes 服務名稱。如果未指定，代理程式接聽程式名稱會作為服務名稱使用。服務名稱在命名空間內必須是唯一的。

提示

若要避免管理額外負荷，建議您保留服務名稱空白。接聽程式名稱是唯一的，您可以使用它來識別服務。只有在您無法在接聽程式之後為服務命名時，才使用服務名稱作為覆寫。

連接埠

每個接聽程式可以有多個連接埠，且每個連接埠都可以有自己的驗證、授權、通訊協定和 TLS 設定。

若要針對連接埠使用您自己的驗證或授權設定，您必須先建立對應的資源，才能與接聽程式搭配使用。如需詳細資訊，請參閱設定 MQTT 代理程式驗證和設定 MQTT 代理程式授權。

若要使用 TLS，請參閱使用自動憑證管理設定 TLS 或使用手動憑證管理設定 TLS 小節。

跨接聽程式使用相同的連接埠

不支援跨不同接聽程式使用相同的連接埠號碼。每個連接埠號碼在 IoT 操作 MQTT 代理程式內都必須是唯一的。

例如，如果您有使用連接埠 1883 的接聽程式，則無法使用連接埠 1883 建立另一個接聽程式。同樣地，預設接聽程式會使用連接埠 18883，因此您無法使用連接埠 18883 建立另一個接聽程式。

WebSocket 支援

IoT 操作 MQTT 代理程式支援透過 WebSocket 的 MQTT。若要開啟 WebSockets，請將連接埠的通訊協定設定為 WebSockets。

使用自動憑證管理設定 TLS

若要啟用具有自動憑證管理的 TLS，請在接聽程式連接埠上指定 TLS 設定。

確認 cert-manager 安裝

透過自動憑證管理，您可以使用 cert-manager 來管理 TLS 伺服器憑證。根據預設，cert-manager 會與 cert-manager 命名空間中的 IoT 操作一起安裝。在繼續之前，請先確認安裝。

使用 kubectl 檢查是否有符合 cert-manager 應用程式標籤的 Pod。

kubectl get pods --namespace cert-manager -l 'app in (cert-manager,cainjector,webhook)'

NAME                                           READY   STATUS    RESTARTS       AGE
aio-cert-manager-64f9548744-5fwdd              1/1     Running   4 (145m ago)   4d20h
aio-cert-manager-cainjector-6c7c546578-p6vgv   1/1     Running   4 (145m ago)   4d20h
aio-cert-manager-webhook-7f676965dd-8xs28      1/1     Running   4 (145m ago)   4d20h

如果您看到顯示為就緒且正在執行的 Pod，則已安裝 cert-manager 並可供使用。

提示

若要進一步確認安裝，請檢查 cert-manager 文件以確認安裝。請記得使用 cert-manager 命名空間。

建立 TLS 伺服器憑證的簽發者

Cert-manager 簽發者資源會定義如何自動發行憑證。 Cert-manager 原生支援數種簽發者類型。它也支援外部issuer類型，以擴充原生支援簽發者以外的功能。您可以使用 MQTT 代理程式搭配任何類型的憑證管理員簽發者。

重要事項

在初始部署期間，IoT 操作會隨 TLS 伺服器憑證的預設簽發者一起安裝。您可以使用此簽發者進行開發和測試。如需詳細資訊，請參閱使用 Azure IoT 操作的預設根憑證授權單位 (CA) 和簽發者。只有在您想要使用不同的簽發者時，才需要下列步驟。

建立簽發者的方法會根據您的案例而有所不同。下列各節列出可協助您開始使用的範例。

開發或測試
實際執行

CA 簽發者適用於開發和測試。它必須使用儲存在 Kubernetes 秘密中的憑證和私鑰進行設定。

將根憑證設定為 Kubernetes 祕密

如果您有現有的 CA 憑證，請使用 CA 憑證和 CA 私密金鑰 PEM 檔案建立 Kubernetes 祕密。執行下列命令，將 CA 憑證匯入為 Kubernetes 祕密，並略過下一節。

kubectl create secret tls test-ca --cert tls.crt --key tls.key -n azure-iot-operations

如果您沒有 CA 憑證，cert-manager 可以為您產生 CA 憑證。使用 cert-manager 產生 CA 憑證被稱為使用自我簽署憑證啟動一個 CA 簽發者。

從建立 ca.yaml 開始：

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: selfsigned-ca-issuer
  namespace: azure-iot-operations
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: selfsigned-ca-cert
  namespace: azure-iot-operations
spec:
  isCA: true
  commonName: test-ca
  secretName: test-ca
  issuerRef:
    # Must match Issuer name above
    name: selfsigned-ca-issuer
    # Must match Issuer kind above
    kind: Issuer
    group: cert-manager.io
  # Override default private key config to use an EC key
  privateKey:
    rotationPolicy: Always
    algorithm: ECDSA
    size: 256

使用下列命令建立自我簽署 CA 憑證：
```
kubectl apply -f ca.yaml
```

Cert-manager 會使用其預設值來建立 CA 憑證。您可以修改憑證規格來變更此憑證的屬性。如需有效選項的清單，請參閱 cert-manager 文件。

散發根憑證

上述範例會將 CA 憑證儲存在名為 test-ca 的 Kubernetes 祕密中。您可以從祕密擷取 PEM 格式的憑證，並使用下列命令將其儲存在檔案 ca.crt 中：

kubectl get secret test-ca -n azure-iot-operations -o json | jq -r '.data["tls.crt"]' | base64 -d > ca.crt

此憑證必須由所有用戶端分散及信任。例如，使用 Mosquitto 用戶端的 --cafile 旗標。

根據 CA 憑證建立簽發者

cert-manager 需要根據先前步驟產生或匯入的 CA 憑證來建立一個簽發者。將下列檔案建立為 issuer-ca.yaml：

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: my-issuer
  namespace: azure-iot-operations
spec:
  ca:
    # Must match secretName of generated or imported CA cert
    secretName: test-ca

使用下列命令建立簽發者：

kubectl apply -f issuer-ca.yaml

先前的命令會建立簽發者來發行 TLS 伺服器憑證。記下簽發者的名稱和種類。在該範例中，名稱為 my-issuer，且種類為 Issuer。這些值稍後會在 BrokerListener 資源中設定。

如需生產環境，請檢查 cert-manager 文件，以查看哪一個簽發者最適合您。例如，使用 Vault 簽發者：

在您選擇的環境中部署 HashiCorp Vault，例如 Kubernetes。據以初始化和解除密封保存庫。
匯入 CA 憑證來建立和設定 PKI 祕密引擎。

使用角色和原則設定保存庫以簽發伺服器憑證。

下列角色是範例。請注意，ExtKeyUsageServerAuth 會讓伺服器憑證正常運作：

vault write pki/roles/my-issuer \
  allow_any_name=true \
  client_flag=false \
  ext_key_usage=ExtKeyUsageServerAuth \
  no_store=true \
  max_ttl=240h

角色的範例原則：

path "pki/sign/my-issuer" {
  capabilities = ["create", "update"]
}

使用選擇的方法設定 cert-manager 與保存庫之間的驗證，例如 SAT。
設定 cert-manager Vault 簽發者。

啟用連接埠的 TLS 自動憑證管理

以下範例是可在連接埠 8884 上使用自動憑證管理來啟用 TLS 的 BrokerListener 資源。

在 Azure 入口網站中，移至您的 IoT 操作執行個體。
在 [元件] 底下，選取 [MQTT 代理程式]。
選取或建立接聽程式。每個服務類型只能建立一個接聽程式。如果您已經有相同服務類型的接聽程式，您可以將更多連接埠新增至現有的接聽程式。

您可以選取現有連接埠上的 TLS 或新增連接埠，將 TLS 設定新增至接聽程式。

輸入下列設定：

設定	描述
名稱	BrokerListener 資源的名稱。輸入 `aio-broker-loadbalancer-tls`。
連接埠	BrokerListener 接聽 MQTT 連線的連接埠號碼。輸入 8884。
驗證	驗證資源參考。
授權	授權資源參考。
TLS	選取 [新增] 按鈕。
簽發者名稱	cert-manager 簽發者的名稱。必要。
簽發者種類	cert-manager 簽發者的種類。必要。
簽發者群組	cert-manager 簽發者的群組。必要。
私密金鑰演算法	私密金鑰的演算法。
私密金鑰輪替原則	輪替私密金鑰的原則。
DNS 名稱	憑證的 DNS 主體替代名稱。
IP 位址	憑證主體替代名稱的 IP 位址。
祕密名稱	包含 X.509 用戶端憑證的 Kubernetes 祕密。
持續時間	TLS 伺服器憑證的總存留期預設為 90 天。
在之前更新	何時開始更新憑證。

選取 [套用] 以儲存 TLS 設定。

使用 az iot ops broker listener port add 命令，將 TCP 連接埠組態新增或變更為 MQTT 訊息代理程式接聽程式服務。如果接聽程式存在，命令會更新現有的接聽程式。如果接聽程式不存在，命令會建立新的接聽程式。

az iot ops broker listener port add --resource-group <ResourceGroupName> --instance <AioInstanceName> --broker default --listener <ListenerName> --port <ListenerServicePort> --authn-ref default --tls-issuer-ref name=<IssuerName> kind=<IssuerKind> group=<IssuerGroup>

下列範例會將新的 TLS 連接埠 8884 新增至名為 aio-broker-loadbalancer的接聽程式：

az iot ops broker listener port add --resource-group myResourceGroupName --instance myAioInstanceName --broker default --listener aio-broker-loadbalancer --port 8884 --authn-ref default --tls-issuer-ref name=my-issuer kind=Issuer group=cert-manager.io

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param listenerName string = 'aio-broker-loadbalancer-tls'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-11-01' existing = {
  parent: aioInstance
  name: 'default'
}

resource loadBalancerListener 'Microsoft.IoTOperations/instances/brokers/listeners@2024-11-01' = {
  parent: defaultBroker
  name: listenerName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }

  properties: {
    serviceType: 'LoadBalancer'
    ports: [
      {
        authenticationRef: 'default'
        port: 8884
        tls: {
          mode: 'Automatic'
          certManagerCertificateSpec: {
            issuerRef: {
              name: 'my-issuer'
              kind: 'Issuer'
            }
          }
        }
      }
    ]
  }
}

使用 Azure CLI 部署 Bicep 檔案：

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

修改 BrokerListener 資源中的 tls 設定，以指定前端的 TLS 連接埠和 Issuer。

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerListener
metadata:
  name: aio-broker-loadbalancer-tls # Avoid conflicts with default service name 'aio-broker'
  namespace: azure-iot-operations
spec:
  brokerRef: default
  serviceType: loadBalancer
  ports:
  - port: 8884 # Avoid conflicts with default port 18883
    tls:
      mode: Automatic
      certManagerCertificateSpec:
        issuerRef:
          name: my-issuer
          kind: Issuer

設定 BrokerListener 資源之後，MQTT 代理程式會自動建立已啟用指定連接埠和 TLS 的新服務。

選擇性：設定伺服器憑證參數

唯一必要的參數是 Issuer 名稱和 Issuer 種類。系統會自動選擇所產生 TLS 伺服器憑證的所有其他屬性。不過，MQTT 代理程式允許遵循與 cert-manager 憑證相同的語法來自訂特定屬性。例如，您可以指定私密金鑰演算法和輪替原則。這些設定位於 tls.certManagerCertificateSpec 下方或 Azure 入口網站中的 [TLS 設定] 窗格上。

如需這些設定的完整清單，請參閱代理程式接聽程式 CertManagerCertificateSpec API 參考。

驗證部署

使用 kubectl 檢查與 BrokerListener 資源相關聯的服務是否正在執行。從上述範例中，服務名稱為 aio-broker-loadbalancer-tls，而命名空間為 azure-iot-operations。下列命令會檢查服務狀態：

$ kubectl get service my-new-tls-listener -n azure-iot-operations
NAME                           TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
aio-broker-loadbalancer-tls    LoadBalancer   10.X.X.X        172.X.X.X     8884:32457/TCP   33s

使用 TLS 連線到代理程式

設定伺服器憑證之後，就會啟用 TLS。若要使用 Mosquitto 進行測試：

mosquitto_pub -h $HOST -p 8884 -V mqttv5 -i "test" -t "test" -m "test" --cafile ca.crt

--cafile 引數會在 Mosquitto 用戶端上啟用 TLS，並指定用戶端應信任特定檔案所簽發的所有伺服器憑證。您必須指定包含已設定 TLS 伺服器憑證簽發者的檔案。

將 $HOST 取代為適當的主機：

如果您要從同一叢集內連線，請替換為給定的服務名稱 (範例中為 my-new-tls-listener) 或服務 CLUSTER-IP。
如果您要從叢集外部連線，請使用服務 EXTERNAL-IP。

請記得視需要指定驗證方法。

預設根 CA 和簽發者

為了協助您開始使用，IoT 操作會使用 TLS 伺服器憑證的預設「快速入門」CA 憑證和簽發者來部署。您可以使用此簽發者進行開發和測試。如需詳細資訊，請參閱 TLS 伺服器憑證的預設根 CA 和簽發者。

針對生產環境，您必須使用來自受信任 CA 的憑證來設定 CA 簽發者，如前幾節所述。

使用手動憑證管理設定 TLS

若要手動設定 MQTT 代理程式以使用特定的 TLS 憑證，請在 BrokerListener 資源中指定它，並參考 Kubernetes 祕密，並使用 kubectl 加以部署。本文說明使用自我簽署憑證設定 TLS 以進行測試的範例。

使用步驟 CLI 建立憑證授權單位

步驟是憑證管理員，可在建立及管理您自己的私人 CA 時快速啟動並執行。

安裝步驟 CLI 並建立根 CA 憑證和金鑰。

step certificate create --profile root-ca "Example Root CA" root_ca.crt root_ca.key

建立根 CA 簽署的中繼 CA 憑證和金鑰。

step certificate create --profile intermediate-ca "Example Intermediate CA" intermediate_ca.crt intermediate_ca.key \
--ca root_ca.crt --ca-key root_ca.key

建立伺服器憑證

使用步驟 CLI 從中繼 CA 憑證和金鑰建立伺服器憑證。

step certificate create mqtts-endpoint mqtts-endpoint.crt mqtts-endpoint.key \
--profile leaf \
--not-after 8760h \
--san mqtts-endpoint \
--san localhost \
--ca intermediate_ca.crt --ca-key intermediate_ca.key \
--no-password --insecure

在這裡，mqtts-endpoint 和 localhost 分別是 Kubernetes 和本機用戶端中 MQTT 代理程式前端的主體別名 (SAN)。若要透過網際網路連線，請新增具有--san 的。 --no-password --insecure 旗標用於測試，以略過密碼提示，並停用私密金鑰的密碼保護，因為它儲存在 Kubernetes 秘密中。針對生產環境，請使用密碼，並將私密金鑰儲存在安全的位置，例如 Azure Key Vault。

憑證金鑰演算法需求

支援 EC 和 RSA 金鑰，但鏈結中的所有憑證都必須使用相同的金鑰演算法。如果您匯入自己的 CA 憑證，請確定伺服器證書使用與 CA 相同的密鑰演算法。

將伺服器憑證鏈結匯入為 Kubernetes 祕密

建立完整的伺服器憑證鏈結，其中憑證的順序很重要。伺服器憑證是檔案中的第一個憑證，而中繼則是第二個。
```
cat  mqtts-endpoint.crt intermediate_ca.crt  > server_chain.crt
```

使用 kubectl 建立具有伺服器憑證鏈結和伺服器金鑰的 Kubernetes 祕密。

kubectl create secret tls server-cert-secret -n azure-iot-operations \
--cert server_chain.crt \
--key mqtts-endpoint.key

啟用連接埠的 TLS 手動憑證管理

下列範例顯示 BrokerListener 資源，可透過手動憑證管理在連接埠 8884 上啟用 TLS。

在 Azure 入口網站中，移至您的 IoT 操作執行個體。
在 [元件] 底下，選取 [MQTT 代理程式]。
選取或建立接聽程式。每個服務類型只能建立一個接聽程式。如果您已經有相同服務類型的接聽程式，您可以將更多連接埠新增至現有的接聽程式。若要遵循範例，請將接聽程式服務名稱指定為 mqtts-endpoint。

您可以選取現有連接埠上的 TLS 或新增連接埠，將 TLS 設定新增至接聽程式。

輸入下列設定：

設定	描述
連接埠	BrokerListener 接聽 MQTT 連線的連接埠號碼。必要。
驗證	驗證資源參考。
授權	授權資源參考。
TLS	選取 [新增] 按鈕。
祕密名稱	包含 X.509 用戶端憑證的 Kubernetes 祕密。

選取 [套用] 以儲存 TLS 設定。

az iot ops broker listener port add --resource-group <ResourceGroupName> --instance <AioInstanceName> --broker default --listener <ListenerName> --port <ListenerServicePort> --authn-ref default --tls-man-secret-ref <SecretReferenceName>

下列範例會將連接埠 8885 變更為名為 aio-broker-loadbalancer 之接聽程式的手動 TLS。它會使用包含 X.509 用戶端憑證的秘密名稱 server-cert-secret 。

az iot ops broker listener port add --resource-group myResourceGroupName --instance myAioInstanceName --broker default --listener aio-broker-loadbalancer --port 8885 --authn-ref default --tls-man-secret-ref server-cert-secret

修改 BrokerListener 資源中的 tls 設定，以指定參考 Kubernetes 祕密的手動 TLS 設定。請注意用於 TLS 伺服器憑證的祕密名稱 (先前範例中的 server-cert-secret)。

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param listenerServiceName string = 'mqtts-endpoint'
param listenerName string = '<LISTENER_NAME>' // Match the SAN in the server certificate

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-11-01' existing = {
  parent: aioInstance
  name: 'default'
}

resource loadBalancerListener 'Microsoft.IoTOperations/instances/brokers/listeners@2024-11-01' = {
  parent: defaultBroker
  name: listenerName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }

  properties: {
    serviceName: listenerServiceName
    serviceType: 'LoadBalancer'
    ports: [
      {
        authenticationRef: 'default'
        port: 8885 // Avoid port conflict with default listener at 18883
        tls: {
          mode: 'Manual'
          manual: {
            secretRef: 'server-cert-secret'
          }
        }
      }
    ]
  }
}

使用 Azure CLI 部署 Bicep 檔案：

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerListener
metadata:
  name: loadbalancer-tls
  namespace: azure-iot-operations
spec:
  brokerRef: default
  serviceType: loadBalancer # Optional, defaults to clusterIP
  serviceName: mqtts-endpoint # Match the SAN in the server certificate
  ports:
  - port: 8885 # Avoid port conflict with default listener at 18883
    tls:
      mode: Manual
      manual:
        secretRef: server-cert-secret

建立 BrokerListener 資源之後，操作員會自動建立 Kubernetes 服務並部署接聽程式。您可以執行 kubectl get svc 來檢查服務的狀態。

使用 TLS 連線到代理程式

若要測試與 Mosquitto 用戶端的 TLS 連線，請發佈訊息，並在參數中傳遞根 CA 憑證 --cafile。

mosquitto_pub -d -h localhost -p 8885 -i "my-client" -t "test-topic" -m "Hello" --cafile root_ca.crt

請記得在啟用 MQTT 代理程式驗證時指定使用者名稱和密碼等項目。

Client my-client sending CONNECT
Client my-client received CONNACK (0)
Client my-client sending PUBLISH (d0, q0, r0, m1, 'test-topic', ... (5 bytes))
Client my-client sending DISCONNECT

提示

若要使用 localhost，必須可在主機電腦上使用連接埠。例如 kubectl port-forward svc/mqtts-endpoint 8885:8885 -n azure-iot-operations。透過 K3d 之類的某些 Kubernetes 散發套件，您可以使用 k3d cluster edit $CLUSTER_NAME --port-add 8885:8885@loadbalancer 來新增轉送連接埠。

若要連線到訊息代理程式，您必須將信任根發佈至所有用戶端，也稱為信任套件組合。在此情況下，信任的根目錄是步驟 CLI 所建立的自我簽署根 CA。用戶端需要散發信任根目錄，才能驗證伺服器憑證鏈結。如果您的 MQTT 用戶端是 Kubernetes 叢集上的工作負載，您也需要使用根 CA 建立 ConfigMap，並將其掛接在您的 Pod 中。

針對伺服器憑證使用外部 IP

若要透過網際網路與 TLS 連線，MQTT 代理程式的伺服器憑證必須具有其外部主機名或 IP 位址作為 SAN。在實際執行環境中，此資訊通常是 DNS 名稱或已知的 IP 位址。在開發/測試期間，您可能不知道在部署之前指派哪些主機名或外部 IP。若要解決此問題，請先部署不含伺服器憑證的接聽程式、使用外部 IP 建立伺服器憑證和祕密，然後將祕密匯入接聽程式。

如果您嘗試部署範例 TLS 接聽程式 manual-tls-listener，但參考的 Kubernetes 祕密 server-cert-secret 不存在，則會建立相關聯的服務，但 Pod 不會啟動。因為操作員需要保留接聽程式的外部 IP，因此會建立服務。

kubectl get svc mqtts-endpoint -n azure-iot-operations

NAME                   TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)             AGE
mqtts-endpoint         LoadBalancer   10.X.X.X        172.X.X.X     8885:30674/TCP      1m15s

匯入伺服器憑證時，預期會發生此行為。健康情況管理員會記錄並指出 MQTT 代理程式正在等候伺服器憑證。

kubectl logs -l app=health-manager -n azure-iot-operations

...
<6>2023-11-06T21:36:13.634Z [INFO] [1] - Server certificate server-cert-secret not found. Awaiting creation of secret.

附註

一般而言，在分散式系統中，Pod 記錄並不具決定性，而且應該謹慎使用。這類資訊呈現的正確方式是透過 Kubernetes 事件和自訂資源狀態，也就是待辦項目。請將上一個步驟視為暫時的因應措施。

即使前端 Pod 未啟動，但外部 IP 已可供使用。

kubectl get svc mqtts-endpoint -n azure-iot-operations

NAME                   TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)             AGE
mqtts-endpoint         LoadBalancer   10.X.X.X        172.X.X.X     8885:30674/TCP      1m15s

從這裡，請遵循與先前顯示相同的步驟，在 --san 中建立具有此外部 IP 的伺服器憑證，並以相同的方式建立 Kubernetes 祕密。建立祕密之後，它會自動匯入至接聽程式。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-06-21

共用方式為

使用 BrokerListener 保護 MQTT 代理程式通訊

預設 BrokerListener

請避免修改預設代理程式接聽程式

建立新的代理程式接聽程式

範例：使用兩個連接埠建立新的接聽程式

服務類型

每個服務類型只有一個接聽程式

服務名稱

連接埠

跨接聽程式使用相同的連接埠

WebSocket 支援

使用自動憑證管理設定 TLS

確認 cert-manager 安裝

建立 TLS 伺服器憑證的簽發者

將根憑證設定為 Kubernetes 祕密

散發根憑證

根據 CA 憑證建立簽發者

啟用連接埠的 TLS 自動憑證管理

選擇性：設定伺服器憑證參數

驗證部署

使用 TLS 連線到代理程式

預設根 CA 和簽發者

使用手動憑證管理設定 TLS

使用步驟 CLI 建立憑證授權單位

建立伺服器憑證

憑證金鑰演算法需求

將伺服器憑證鏈結匯入為 Kubernetes 祕密

啟用連接埠的 TLS 手動憑證管理

使用 TLS 連線到代理程式

針對伺服器憑證使用外部 IP

相關內容

意見反應

其他資源