Skip to content

Commit e81656f

Browse files
PatAltimorePatAltimore
committed
BrokerListener changes
1 parent 06b61f3 commit e81656f

File tree

3 files changed

+144
-142
lines changed

3 files changed

+144
-142
lines changed

‎articles/iot-operations/manage-mqtt-broker/howto-configure-brokerlistener.md

Lines changed: 39 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,15 @@ To customize the network access and security use the **BrokerListener** resource
2020

2121
Each listener can have its own authentication and authorization rules that define who can connect to the listener and what actions they can perform on the broker. You can use *BrokerAuthentication* and *BrokerAuthorization* resources to specify the access control policies for each listener. This flexibility allows you to fine-tune the permissions and roles of your MQTT clients, based on their needs and use cases.
2222

23+
Listeners have the following characteristics:
24+
25+
- You can have up to three listeners. One listener per service type of `loadBalancer`, `clusterIp`, or `nodePort`. The default *BrokerListener* named *listener* is service type `clusterIp`.
26+
- Each listener supports multiple ports
27+
- AuthN and authZ references are per port
28+
- TLS configuration is per port
29+
- Service names must be unique
30+
- Ports cannot conflict over different listeners
31+
2332
The *BrokerListener* resource has these fields:
2433

2534
| Field Name | Required | Description |
@@ -50,7 +59,7 @@ The *BrokerListener* resource has these fields:
5059
| ports.tls.manual | No | Manual TLS server certificate management through a defined secret. For more information, see [Configure TLS with manual certificate management](howto-configure-tls-manual.md).|
5160
| ports.tls.manual.secretName | Yes | Kubernetes secret containing an X.509 client certificate. This is a reference to the secret through an identifying name, not the secret itself. |
5261
| ports.tls.manual.secretNamespace | No | Certificate K8S namespace. Omit to use current namespace. |
53-
| serviceName | No | The name of Kubernetes service created for this listener. Kubernetes creates DNS records for this `serviceName` that clients should use to connect to MQTT broker. This subfield is optional and defaults to `aio-mq-dmqtt-frontend`. Important: If you have multiple listeners with the same `serviceType` and `serviceName`, the listeners share the same Kubernetes service. For more information, see [Service name and service type](#service-name-and-service-type). |
62+
| serviceName | No | The name of Kubernetes service created for this listener. Kubernetes creates DNS records for this `serviceName` that clients should use to connect to MQTT broker. This subfield is optional and defaults to `aio-mq-dmqtt-frontend`. |
5463
| serviceType | No | The type of the Kubernetes service created for this listener. This subfield is optional and defaults to `clusterIp`. Must be either `loadBalancer`, `clusterIp`, or `nodePort`. |
5564

5665
## Default BrokerListener
@@ -74,28 +83,28 @@ metadata:
7483
spec:
7584
brokerRef: broker
7685
ports:
77-
- authenticationRef: authn
78-
port: 8883
79-
protocol: Mqtt
80-
tls:
81-
automatic:
82-
issuerRef:
83-
apiGroup: cert-manager.io
84-
kind: Issuer
85-
name: mq-dmqtt-frontend
86-
mode: Automatic
87-
serviceName: aio-mq-dmqtt-frontend
88-
serviceType: ClusterIp
86+
- authenticationRef: authn
87+
port: 8883
88+
protocol: Mqtt
89+
tls:
90+
automatic:
91+
issuerRef:
92+
apiGroup: cert-manager.io
93+
kind: Issuer
94+
name: mq-dmqtt-frontend
95+
mode: Automatic
96+
serviceName: aio-mq-dmqtt-frontend
97+
serviceType: ClusterIp
8998
```
9099
91100
To learn more about the default BrokerAuthentication resource linked to this listener, see [Default BrokerAuthentication resource](howto-configure-authentication.md#default-brokerauthentication-resource).
92101
93102
## Create new BrokerListeners
94103
95-
This example shows how to create two new *BrokerListener* resources for a *Broker* resource named *my-broker*. Each *BrokerListener* resource defines a port and a TLS setting for a listener that accepts MQTT connections from clients.
104+
This example shows how to create a new *BrokerListener* resource for a *Broker* resource named *my-broker*. The *BrokerListener* resource defines a two ports that accept MQTT connections from clients.
96105
97-
- The first *BrokerListener* resource, named *my-test-listener*, defines a listener on port 1883 with no TLS and authentication off. Clients can connect to the broker without encryption or authentication.
98-
- The second *BrokerListener* resource, named *my-secure-listener*, defines a listener on port 8883 with TLS and authentication enabled. Only authenticated clients can connect to the broker with TLS encryption. The `tls` field is set to `automatic`, which means that the listener uses cert-manager to get and renew its server certificate.
106+
- The first port listens on port 1883 with no TLS and authentication off. Clients can connect to the broker without encryption or authentication.
107+
- The second port listens on port 8883 with TLS and authentication enabled. Only authenticated clients can connect to the broker with TLS encryption. TLS is set to `automatic`, which means that the listener uses cert-manager to get and renew its server certificate.
99108

100109
To create these *BrokerListener* resources, apply this YAML manifest to your Kubernetes cluster:
101110

@@ -106,48 +115,23 @@ metadata:
106115
name: my-test-listener
107116
namespace: azure-iot-operations
108117
spec:
109-
authenticationEnabled: false
110-
authorizationEnabled: false
111-
brokerRef: broker
112-
port: 1883
113-
---
114-
apiVersion: mq.iotoperations.azure.com/v1beta1
115-
kind: BrokerListener
116-
metadata:
117-
name: my-secure-listener
118-
namespace: azure-iot-operations
119-
spec:
120-
authenticationEnabled: true
121-
authorizationEnabled: false
122118
brokerRef: broker
123-
port: 8883
124-
tls:
125-
automatic:
126-
issuerRef:
127-
name: e2e-cert-issuer
128-
kind: Issuer
129-
group: cert-manager.io
119+
serviceType: loadBalancer
120+
serviceName: my-new-listener
121+
ports:
122+
port: 1883
123+
protocol: Mqtt
124+
port: 18883
125+
authenticationRef: authn
126+
protocol: Mqtt
127+
tls:
128+
automatic:
129+
issuerRef:
130+
name: e2e-cert-issuer
131+
kind: Issuer
132+
group: cert-manager.io
130133
```
131134

132-
## Service name and service type
133-
134-
If you have multiple BrokerListener resources with the same `serviceType` and `serviceName`, the resources share the same Kubernetes service. This means that the service exposes all the ports of all the listeners. For example, if you have two listeners with the same `serviceType` and `serviceName`, one on port 1883 and the other on port 8883, the service exposes both ports. Clients can connect to the broker on either port.
135-
136-
There are two important rules to follow when sharing service name:
137-
138-
1. Listeners with the same `serviceType` must share the same `serviceName`.
139-
140-
1. Listeners with different `serviceType` must have different `serviceName`.
141-
142-
Notably, the service for the default listener on port 8883 is `clusterIp` and named `aio-mq-dmqtt-frontend`. The following table summarizes what happens when you create a new listener on a different port:
143-
144-
| New listener `serviceType` | New listener `serviceName` | Result |
145-
| --- | --- | --- |
146-
| `clusterIp` | `aio-mq-dmqtt-frontend` | The new listener creates successfully, and the service exposes both ports. |
147-
| `clusterIp` | `my-service` | The new listener fails to create because the service type conflicts with the default listener. |
148-
| `loadBalancer` or `nodePort` | `aio-mq-dmqtt-frontend` | The new listener fails to create because the service name conflicts with the default listener. |
149-
| `loadBalancer` or `nodePort` | `my-service` | The new listener creates successfully, and a new service is created. |
150-
151135
## Related content
152136

153137
- [Configure MQTT broker authorization](howto-configure-authorization.md)

‎articles/iot-operations/manage-mqtt-broker/howto-configure-tls-auto.md

Lines changed: 79 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ ms.subservice: azure-mqtt-broker
77
ms.topic: how-to
88
ms.custom:
99
- ignite-2023
10-
ms.date: 07/01/2024
10+
ms.date: 07/27/2024
1111

1212
#CustomerIntent: As an operator, I want to configure MQTT broker to use TLS so that I have secure communication between the MQTT broker and client.
1313
---
@@ -24,8 +24,11 @@ With automatic certificate management, you use cert-manager to manage the TLS se
2424

2525
1. Use `kubectl` to check for the pods matching the cert-manager app labels.
2626

27-
```console
28-
$ kubectl get pods --namespace azure-iot-operations -l 'app in (cert-manager,cainjector,webhook)'
27+
```bash
28+
kubectl get pods --namespace azure-iot-operations -l 'app in (cert-manager,cainjector,webhook)'
29+
```
30+
31+
```Output
2932
NAME READY STATUS RESTARTS AGE
3033
aio-cert-manager-64f9548744-5fwdd 1/1 Running 4 (145m ago) 4d20h
3134
aio-cert-manager-cainjector-6c7c546578-p6vgv 1/1 Running 4 (145m ago) 4d20h
@@ -99,7 +102,7 @@ If you don't have a CA certificate, cert-manager can generate a root CA certific
99102
kubectl apply -f ca.yaml
100103
```
101104
102-
Cert-manager creates a CA certificate using its defaults. The properties of this certificate can be changed by modifying the Certificate spec. See [cert-manager documentation](https://cert-manager.io/docs/reference/api-docs/#cert-manager.io/v1.CertificateSpec) for a list of valid options.
105+
Cert-manager creates a CA certificate using its defaults. The properties of this certificate can be changed by modifying the Certificate specification. See [cert-manager documentation](https://cert-manager.io/docs/reference/api-docs/#cert-manager.io/v1.CertificateSpec) for a list of valid options.
103106
104107
### Distribute the root certificate
105108
@@ -179,9 +182,7 @@ metadata:
179182
namespace: azure-iot-operations
180183
spec:
181184
brokerRef: broker
182-
authenticationEnabled: false # If set to true, a BrokerAuthentication resource must be configured
183-
authorizationEnabled: false
184-
serviceType: loadBalancer # Optional; defaults to 'clusterIP'
185+
serviceType: loadBalancer
185186
serviceName: my-new-tls-listener # Avoid conflicts with default service name 'aio-mq-dmqtt-frontend'
186187
port: 8884 # Avoid conflicts with default port 8883
187188
tls:
@@ -268,74 +269,80 @@ To help you get started, Azure IoT Operations is deployed with a default "quicks
268269
269270
* The public portion of the root CA certificate is stored in a ConfigMap called `aio-ca-trust-bundle-test-only`. You can retrieve the CA certificate from the ConfigMap and inspect it with kubectl and openssl.
270271
271-
```console
272-
$ kubectl get configmap aio-ca-trust-bundle-test-only -n azure-iot-operations -o json | jq -r '.data["ca.crt"]' | openssl x509 -text -noout
273-
Certificate:
274-
Data:
275-
Version: 3 (0x2)
276-
Serial Number:
277-
74:d8:b6:fe:63:5a:7d:24:bd:c2:c0:25:c2:d2:c7:94:66:af:36:89
278-
Signature Algorithm: ecdsa-with-SHA256
279-
Issuer: CN = Azure IoT Operations Quickstart Root CA - Not for Production
280-
Validity
281-
Not Before: Nov 2 00:34:31 2023 GMT
282-
Not After : Dec 2 00:34:31 2023 GMT
283-
Subject: CN = Azure IoT Operations Quickstart Root CA - Not for Production
284-
Subject Public Key Info:
285-
Public Key Algorithm: id-ecPublicKey
286-
Public-Key: (256 bit)
287-
pub:
288-
04:51:43:93:2c:dd:6b:7e:10:18:a2:0f:ca:2e:7b:
289-
bb:ba:5c:78:81:7b:06:99:b5:a8:11:4f:bb:aa:0d:
290-
e0:06:4f:55:be:f9:5f:9e:fa:14:75:bb:c9:01:61:
291-
0f:20:95:cd:9b:69:7c:70:98:f8:fa:a0:4c:90:da:
292-
5b:1a:d7:e7:6b
293-
ASN1 OID: prime256v1
294-
NIST CURVE: P-256
295-
X509v3 extensions:
296-
X509v3 Basic Constraints: critical
297-
CA:TRUE
298-
X509v3 Key Usage:
299-
Certificate Sign
300-
X509v3 Subject Key Identifier:
301-
B6:DD:8A:42:77:05:38:7A:51:B4:8D:8E:3F:2A:D1:79:32:E9:43:B9
302-
Signature Algorithm: ecdsa-with-SHA256
303-
30:44:02:20:21:cd:61:d7:21:86:fd:f8:c3:6d:33:36:53:e3:
304-
a6:06:3c:a6:80:14:13:55:16:f1:19:a8:85:4b:e9:5d:61:eb:
305-
02:20:3e:85:8a:16:d1:0f:0b:0d:5e:cd:2d:bc:39:4b:5e:57:
306-
38:0b:ae:12:98:a9:8f:12:ea:95:45:71:bd:7c:de:9d
307-
```
272+
```bash
273+
kubectl get configmap aio-ca-trust-bundle-test-only -n azure-iot-operations -o json | jq -r '.data["ca.crt"]' | openssl x509 -text -noout
274+
```
275+
276+
```Output
277+
Certificate:
278+
Data:
279+
Version: 3 (0x2)
280+
Serial Number:
281+
74:d8:b6:fe:63:5a:7d:24:bd:c2:c0:25:c2:d2:c7:94:66:af:36:89
282+
Signature Algorithm: ecdsa-with-SHA256
283+
Issuer: CN = Azure IoT Operations Quickstart Root CA - Not for Production
284+
Validity
285+
Not Before: Nov 2 00:34:31 2023 GMT
286+
Not After : Dec 2 00:34:31 2023 GMT
287+
Subject: CN = Azure IoT Operations Quickstart Root CA - Not for Production
288+
Subject Public Key Info:
289+
Public Key Algorithm: id-ecPublicKey
290+
Public-Key: (256 bit)
291+
pub:
292+
04:51:43:93:2c:dd:6b:7e:10:18:a2:0f:ca:2e:7b:
293+
bb:ba:5c:78:81:7b:06:99:b5:a8:11:4f:bb:aa:0d:
294+
e0:06:4f:55:be:f9:5f:9e:fa:14:75:bb:c9:01:61:
295+
0f:20:95:cd:9b:69:7c:70:98:f8:fa:a0:4c:90:da:
296+
5b:1a:d7:e7:6b
297+
ASN1 OID: prime256v1
298+
NIST CURVE: P-256
299+
X509v3 extensions:
300+
X509v3 Basic Constraints: critical
301+
CA:TRUE
302+
X509v3 Key Usage:
303+
Certificate Sign
304+
X509v3 Subject Key Identifier:
305+
B6:DD:8A:42:77:05:38:7A:51:B4:8D:8E:3F:2A:D1:79:32:E9:43:B9
306+
Signature Algorithm: ecdsa-with-SHA256
307+
30:44:02:20:21:cd:61:d7:21:86:fd:f8:c3:6d:33:36:53:e3:
308+
a6:06:3c:a6:80:14:13:55:16:f1:19:a8:85:4b:e9:5d:61:eb:
309+
02:20:3e:85:8a:16:d1:0f:0b:0d:5e:cd:2d:bc:39:4b:5e:57:
310+
38:0b:ae:12:98:a9:8f:12:ea:95:45:71:bd:7c:de:9d
311+
```
308312
309313
* By default, there's already a CA issuer configured in the `azure-iot-operations` namespace called `aio-ca-issuer`. It's used as the common CA issuer for all TLS server certificates for IoT Operations. MQTT broker uses an issuer created from the same CA certificate to issue TLS server certificates for the default TLS listener on port 8883. You can inspect the issuer with the following command:
310314
311-
```console
312-
$ kubectl get issuer aio-ca-issuer -n azure-iot-operations -o yaml
313-
apiVersion: cert-manager.io/v1
314-
kind: Issuer
315-
metadata:
316-
annotations:
317-
meta.helm.sh/release-name: azure-iot-operations
318-
meta.helm.sh/release-namespace: azure-iot-operations
319-
creationTimestamp: "2023-11-01T23:10:24Z"
320-
generation: 1
321-
labels:
322-
app.kubernetes.io/managed-by: Helm
323-
name: aio-ca-issuer
324-
namespace: azure-iot-operations
325-
resourceVersion: "2036"
326-
uid: c55974c0-e0c3-4d35-8c07-d5a0d3f79162
327-
spec:
328-
ca:
329-
secretName: aio-ca-key-pair-test-only
330-
status:
331-
conditions:
332-
- lastTransitionTime: "2023-11-01T23:10:59Z"
333-
message: Signing CA verified
334-
observedGeneration: 1
335-
reason: KeyPairVerified
336-
status: "True"
337-
type: Ready
338-
```
315+
```bash
316+
kubectl get issuer aio-ca-issuer -n azure-iot-operations -o yaml
317+
```
318+
319+
```Output
320+
apiVersion: cert-manager.io/v1
321+
kind: Issuer
322+
metadata:
323+
annotations:
324+
meta.helm.sh/release-name: azure-iot-operations
325+
meta.helm.sh/release-namespace: azure-iot-operations
326+
creationTimestamp: "2023-11-01T23:10:24Z"
327+
generation: 1
328+
labels:
329+
app.kubernetes.io/managed-by: Helm
330+
name: aio-ca-issuer
331+
namespace: azure-iot-operations
332+
resourceVersion: "2036"
333+
uid: c55974c0-e0c3-4d35-8c07-d5a0d3f79162
334+
spec:
335+
ca:
336+
secretName: aio-ca-key-pair-test-only
337+
status:
338+
conditions:
339+
- lastTransitionTime: "2023-11-01T23:10:59Z"
340+
message: Signing CA verified
341+
observedGeneration: 1
342+
reason: KeyPairVerified
343+
status: "True"
344+
type: Ready
345+
```
339346
340347
For production, you must configure a CA issuer with a certificate from a trusted CA, as described in the previous sections.
341348

0 commit comments

Comments
 (0)