BrokerListener를 사용하여 보안 MQTT 브로커 통신

2025-06-20

중요합니다

이 페이지에는 미리 보기 상태인 Kubernetes 배포 매니페스트를 사용하여 Azure IoT Operations 구성 요소를 관리하기 위한 지침이 포함되어 있습니다. 이 기능은 몇 가지 제한 사항을 제공하며 프로덕션 워크로드에 사용하면 안 됩니다.

베타, 미리 보기 또는 아직 일반 공급으로 릴리스되지 않은 Azure 기능에 적용되는 법적 용어는 Microsoft Azure 미리 보기에 대한 추가 사용 약관 을 참조하세요.

BrokerListener 리소스는 네트워크를 통해 클라이언트에게 브로커를 노출하는 네트워크 엔드포인트에 해당합니다. 각 브로커에는 하나 이상의 BrokerListener 리소스가 있을 수 있으며, 각각 여러 포트와 다른 액세스 제어가 가능합니다.

각 BrokerListener 포트에는 해당 수신기 포트에 연결할 수 있는 사용자와 브로커에서 수행할 수 있는 작업을 정의하는 고유한 인증 및 권한 부여 규칙이 있을 수 있습니다. BrokerAuthentication 및 BrokerAuthorization 리소스를 사용하여 각 수신기 포트에 대한 액세스 제어 정책을 지정할 수 있습니다. 이러한 유연성 덕분에 요구 사항과 사용 사례에 따라 MQTT 클라이언트의 권한과 역할을 미세 조정할 수 있습니다.

팁

기본 MQTT 브로커 배포는 클라이언트가 TLS(전송 계층 보안) 프로토콜을 사용하여 연결하고 서비스 계정 토큰으로 인증해야 하는 클러스터 IP 서비스입니다. 클러스터 외부에서 연결하는 클라이언트는 연결하기 전에 추가 구성이 필요합니다 .

브로커 수신기는 다음과 같은 특성을 갖습니다.

이름: 수신기의 이름입니다. 재정의 하지 않는 한 이 이름은 Kubernetes 서비스 이름이기도 합니다.
서비스 유형: 서비스 유형당 하나씩 최대 3개의 수신기를 가질 수 있습니다. 기본 수신기는 서비스 유형ClusterIp입니다.
포트: 각 수신기는 여러 포트를 지원합니다. 포트 는 다른 수신기를 통해 충돌할 수 없습니다.
인증 및 권한 부여 참조: BrokerAuthentication 및 BrokerAuthorization 은 포트별로 구성됩니다.
TLS: 수동 또는 자동 TLS 구성은 포트별로 적용됩니다.
프로토콜: 포트당 WebSockets를 통해 MQTT 를 사용하도록 설정할 수 있습니다.

사용 가능한 모든 설정 목록은 Broker 수신기 API 참조를 참조하세요.

기본 BrokerListener

Azure IoT Operations를 배포하면 배포에서 기본값이라는 BrokerListener 리소스를 만듭니다. 이 수신기는 IoT 운영 구성 요소 간의 암호화된 내부 통신에 사용됩니다. 기본 수신기는 기본 브로커의 일부입니다.

18883 포트에 ClusterIp 서비스를 노출합니다.
클라이언트가 Kubernetes 서비스 계정 인증을 사용해야 합니다.
자동으로 관리되는 TLS 인증서가 있습니다.
클라이언트 권한 부여 정책을 구성하지 않습니다.

주의

IoT 운영 내부 통신을 중단하지 않으려면 기본 수신기를 변경하지 않고 내부용으로만 사용합니다. 외부 통신의 경우 새 수신기를 만듭니다. ClusterIp 서비스를 사용해야 하는 경우 기존 설정을 변경하지 않고 기본 수신기에 포트를 더 추가합니다.

기본 수신기를 보거나 편집하려면 다음 단계를 따릅니다.

Azure Portal에서 IoT Operations 인스턴스로 이동합니다.
구성 요소 아래에서 MQTT Broker를 선택합니다.
broker 수신기 목록에서 기본 수신기를 선택합니다.
수신기 설정을 검토하지만 기존 설정은 수정하지 마세요. 대신 새로운 포트를 만들고 필요에 따라 구성합니다.

az iot ops broker listener show 명령을 사용하여 로컬 MQTT broker 기본 수신기를 봅니다.

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 운영 내부 통신이 중단되는 것을 방지하려면 기본 수신기를 변경하지 않고 내부용으로만 사용합니다. 외부 통신의 경우 새 수신기를 만듭니다.

기본 broker 수신기는 서비스 유형을 ClusterIp사용하고 서비스 유형당 하나의 수신기만 가질 수 있으므로 서비스를 사용해야 하는 경우 기존 설정을 변경하지 않고 기본 수신기에 포트를 ClusterIp 더 추가합니다.

새 브로커 수신기 만들기

새로운 수신기를 만들려면 다음 설정을 지정합니다.

이름: 수신기의 이름입니다. 재정의 하지 않는 한 이 이름은 Kubernetes 서비스 이름이기도 합니다.
서비스 유형: Kubernetes 서비스의 유형입니다. 서비스 형식을 참조하세요.
포트: 수신 대기할 포트 목록입니다. 포트를 참조하세요.
서비스 이름 (선택 사항): Kubernetes 서비스 이름을 재정의합니다. 서비스 이름을 참조하세요.

예: 두 개의 포트를 사용하여 새 수신기 만들기

이 예에서는 LoadBalancer 서비스 형식으로 새 수신기를 만드는 방법을 보여 줍니다. BrokerListener 리소스는 클라이언트로부터 MQTT 연결을 허용하는 두 개의 포트를 정의합니다.

첫 번째 포트는 TLS 및 인증 없이 포트 1883에서 수신 대기합니다. 이 설정은 테스트에만 적합합니다. 프로덕션 환경에서는 이 구성을 사용하지 마세요.
두 번째 포트는 TLS 및 인증을 사용하도록 설정한 상태로 포트 8883에서 수신 대기합니다. Kubernetes 서비스 계정 토큰을 사용하는 인증된 클라이언트만 연결할 수 있습니다. TLS는 cert-manager를 사용하여 기본 발급자에서 서버 인증서를 관리하는 자동 모드로 설정됩니다. 이 설정은 프로덕션 구성에 더 가깝습니다.

Azure Portal에서 IoT Operations 인스턴스로 이동합니다.
구성 요소 아래에서 MQTT Broker를 선택합니다.

LoadBalancer용 MQTT broker 수신기를 선택하고 >를 클릭합니다.

다음 설정을 입력합니다.

설정	설명
이름	BrokerListener 리소스의 이름.
서비스 이름	Kubernetes 서비스의 이름. 수신기 이름을 서비스 이름으로 사용하려면 비워 둡니다.
서비스 유형	LoadBalancer가 이미 선택되어 있습니다.

포트에서 첫 번째 포트에 대해 다음 설정을 입력합니다.

설정	설명
포트	1883을 입력합니다.
인증	없음을 선택합니다.
승인	없음을 선택합니다.
프로토콜	MQTT를 선택합니다.
TLS	추가하지 마세요.

포트 추가 항목을 선택하여 두 번째 포트를 추가하고 다음 설정을 입력합니다.

설정	설명
포트	8883을 입력합니다.
인증	기본값을 선택합니다.
승인	없음을 선택합니다.
프로토콜	MQTT를 선택합니다.
TLS	추가를 선택합니다.

TLS 구성 창에서 다음 설정을 입력합니다.

설정	설명
TLS 모드	자동을 선택합니다.
발급자 이름	`azure-iot-operations-aio-certificate-issuer`를 입력합니다.
발급자 종류	ClusterIssuer를 선택합니다.

다른 설정을 기본값으로 두고 적용을 선택합니다.

수신기 만들기를 선택합니다.

az iot ops broker listener apply 명령을 사용하여 새 MQTT broker 수신기를 만듭니다.

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: Broker를 외부에 노출합니다. 서비스에는 클라이언트가 브로커에 연결하는 데 사용할 수 있는 외부 IP 주소가 할당됩니다. 이 서비스 형식은 프로덕션 배포에 가장 일반적입니다.

서비스 형식당 수신기는 하나만 있음

서비스 형식당 수신기는 하나만 허용됩니다. 동일한 서비스 형식에 대한 연결성이 더 필요한 경우 해당 서비스 형식의 기존 수신기에 포트를 더 추가합니다.

서비스 이름

서비스 이름은 브로커와 연결된 Kubernetes Service의 이름입니다. 지정하지 않으면 브로커 수신기 이름이 서비스 이름으로 사용됩니다. 서비스 이름은 네임스페이스 내에서 고유해야 합니다.

팁

관리 오버헤드를 방지하려면 서비스 이름을 비워두는 것이 좋습니다. 수신기 이름은 고유하며, 이를 사용하여 서비스를 식별할 수 있습니다. 수신기의 이름을 서비스 이름으로 지정할 수 없는 경우에만 서비스 이름을 재정의로 사용합니다.

항구

각 수신기는 여러 개의 포트를 가질 수 있으며, 각 포트는 인증, 권한 부여, 프로토콜 및 TLS에 대한 고유한 설정을 가질 수 있습니다.

포트에 대한 자체 인증 또는 권한 부여 설정을 사용하려면 수신기와 함께 사용하기 전에 해당 리소스를 만들어야 합니다. 자세한 내용은 MQTT Broker 인증 구성 및 MQTT Broker 권한 부여 구성을 참조하세요.

TLS를 사용하려면 자동 인증서 관리를 사용하여 TLS 구성 또는 수동 인증서 관리 섹션을 사용하여 TLS 구성 을 참조하세요.

수신기 전체에서 동일한 포트 사용

여러 수신기에서 동일한 포트 번호를 사용하는 것은 지원되지 않습니다. 각 포트 번호는 IoT Operations MQTT 브로커 내에서 고유해야 합니다.

예를 들어, 포트 1883을 사용하는 수신기가 있는 경우 포트 1883으로 다른 수신기를 만들 수 없습니다. 마찬가지로 기본 수신기는 포트 18883을 사용하므로 포트 18883으로 다른 수신기를 만들 수 없습니다.

WebSocket 지원

IoT Operations MQTT 브로커는 WebSockets를 통한 MQTT를 지원합니다. WebSocket을 사용하도록 설정하려면 포트에 대한 프로토콜을 WebSockets로 설정합니다.

자동 인증서 관리를 사용하여 TLS 구성

자동 인증서 관리를 통해 TLS를 사용하도록 설정하려면 수신기 포트에서 TLS 설정을 지정합니다.

cert-manager 설치 확인

자동 인증서 관리를 사용하면 cert-manager를 사용하여 TLS 서버 인증서를 관리합니다. 기본적으로 cert-manager는 이미 cert-manager 네임스페이스에 IoT Operations와 함께 설치됩니다. 계속 진행하기 전에 설치를 확인합니다.

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 는 기본적으로 여러 발급자 유형을 지원합니다. 또한 고유하게 지원되는 발급자를 넘어 기능을 확장하기 위한 외부issuer 형식도 지원합니다. 모든 형식의 인증서 관리자 발급자와 함께 MQTT 브로커를 사용할 수 있습니다.

중요합니다

초기 배포 과정에서 IoT Operations는 TLS 서버 인증서에 대한 기본 발급자와 함께 설치됩니다. 개발 및 테스트에 이 발급자를 사용할 수 있습니다. 자세한 내용은 Azure IoT Operations를 사용하는 기본 루트 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 인증서를 생성할 수 있습니다. 인증서 관리자를 사용하여 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 설명서를 참조하세요.

루트 인증서 배포

이전 예제에서는 test-ca라는 Kubernetes 비밀에 CA 인증서를 저장합니다. 다음 명령을 사용하여 비밀에서 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 Issuer:

Kubernetes와 같은 선택한 환경에서 HashiCorp Vault를 배포합니다. 자격 증명 모음을 초기화하고 봉인을 해제합니다.
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"]
}
```
SAT와 같은 선택 방법을 사용하여 cert-manager와 Vault 간에 인증을 설정합니다.
cert-manager Vault 발급자를 구성합니다.

포트에 대한 TLS 자동 인증서 관리 사용

다음 예는 자동 인증서 관리를 통해 포트 8884에서 TLS를 사용하도록 설정하는 BrokerListener 리소스입니다.

Azure Portal에서 IoT Operations 인스턴스로 이동합니다.
구성 요소 아래에서 MQTT Broker를 선택합니다.
수신기를 선택하거나 만듭니다. 서비스 형식당 수신기를 하나만 만들 수 있습니다. 동일한 서비스 형식의 수신기가 이미 있는 경우 기존 수신기에 더 많은 포트를 추가할 수 있습니다.

기존 포트에서 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 broker 수신기 서비스에 추가하거나 변경합니다. 수신기가 있는 경우 명령은 기존 수신기를 업데이트합니다. 수신기가 없는 경우 명령은 새 수신기를 만듭니다.

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>

다음 예제에서는 명명 aio-broker-loadbalancer된 수신기에 새 TLS 포트 8884를 추가합니다.

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 인증서와 동일한 구문에 따라 특정 속성을 사용자 지정할 수 있도록 허용합니다. 예를 들어, 프라이빗 키 알고리즘과 회전 정책을 지정할 수 있습니다. 이러한 설정은 Azure Portal의 tls.certManagerCertificateSpec 창 아래에 있거나 있습니다.

이러한 설정의 전체 목록은 Broker 수신기 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 Operations는 기본 "빠른 시작" CA 인증서와 TLS 서버 인증서 발급자와 함께 배포됩니다. 개발 및 테스트에 이 발급자를 사용할 수 있습니다. 자세한 내용은 TLS 서버 인증서에 대한 기본 루트 CA 및 발급자를 참조하세요.

프로덕션의 경우 이전 섹션에서 설명한 대로 신뢰할 수 있는 CA의 인증서를 사용하여 CA 발급자를 구성해야 합니다.

수동 인증서 관리를 사용하여 TLS 구성

MQTT 브로커가 특정 TLS 인증서를 사용하도록 수동으로 구성하려면 Kubernetes 비밀에 대한 참조와 함께 BrokerListener 리소스에 해당 인증서를 지정하고 kubectl을 사용하여 배포합니다. 이 문서에서는 테스트를 위해 자체 서명된 인증서로 TLS를 구성하는 예를 보여 줍니다.

Step 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

서버 인증서 만들기

Step 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 수동 인증서 관리 사용

다음 예에서는 수동 인증서 관리를 통해 포트 8884에서 TLS를 사용하도록 설정하는 BrokerListener 리소스를 보여 줍니다.

Azure Portal에서 IoT Operations 인스턴스로 이동합니다.
구성 요소 아래에서 MQTT Broker를 선택합니다.
수신기를 선택하거나 만듭니다. 서비스 형식당 수신기를 하나만 만들 수 있습니다. 동일한 서비스 형식의 수신기가 이미 있는 경우 기존 수신기에 더 많은 포트를 추가할 수 있습니다. 예를 따르려면 수신기 서비스 이름을 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>

다음 예제에서는 명명된 aio-broker-loadbalancer수신기에 대한 포트 8885를 수동 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 Service를 만들고 수신기를 배포합니다. kubectl get svc를 실행하여 서비스의 상태를 확인할 수 있습니다.

TLS를 사용하여 브로커에 연결

Mosquitto 클라이언트를 사용하여 TLS 연결을 테스트하려면 메시지를 게시하고 매개 변수 --cafile에 루트 CA 인증서를 전달합니다.

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와 함께 전달된 포트를 추가할 수 있습니다.

브로커에 연결하려면 모든 클라이언트에 신뢰할 수 있는 루트(신뢰 번들)를 배포해야 합니다. 이 경우 신뢰할 수 있는 루트는 Step 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

이러한 동작은 서버 인증서를 가져오는 동안 예상됩니다. Health Manager 로그에는 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 비밀을 만듭니다. 비밀이 만들어지면 자동으로 수신기로 가져옵니다.

다음을 통해 공유

BrokerListener를 사용하여 보안 MQTT 브로커 통신

기본 BrokerListener

기본 브로커 수신기 수정 방지

새 브로커 수신기 만들기

예: 두 개의 포트를 사용하여 새 수신기 만들기

서비스 유형

서비스 형식당 수신기는 하나만 있음

서비스 이름

항구

수신기 전체에서 동일한 포트 사용

WebSocket 지원

자동 인증서 관리를 사용하여 TLS 구성

cert-manager 설치 확인

TLS 서버 인증서에 대한 발급자 만들기

루트 인증서를 Kubernetes 비밀로 설정

루트 인증서 배포

CA 인증서를 기반으로 발급자 만들기

포트에 대한 TLS 자동 인증서 관리 사용

선택 사항: 서버 인증서 매개 변수 구성

배포 확인

TLS를 사용하여 브로커에 연결

기본 루트 CA 및 발급자

수동 인증서 관리를 사용하여 TLS 구성

Step CLI를 사용하여 인증 기관 만들기

서버 인증서 만들기

인증서 키 알고리즘 요구 사항

Kubernetes 비밀로 서버 인증서 체인 가져오기

포트에 대한 TLS 수동 인증서 관리 사용

TLS를 사용하여 브로커에 연결

서버 인증서에 외부 IP 사용

관련 콘텐츠

피드백

추가 리소스