Merge pull request #282006 from PatAltimore/patricka-default-listener-release-aio-july-updates

MQTT broker Brokerlistener changes

Author: Stacyrch140

articles/iot-operations/create-edge-apps/howto-deploy-dapr.md

@@ -131,7 +131,7 @@ To configure authorization policies to MQTT broker, first you create a [BrokerAu
 1. Save the following yaml, which contains a BrokerAuthorization definition, to a file named `aio-dapr-authz.yaml`:
 
     ```yml
-    apiVersion: mq.iotoperations.azure.com/v1beta1
+    apiVersion: mqttbroker.iotoperations.azure.com/v1beta1
     kind: BrokerAuthorization
     metadata:
       name: my-dapr-authz-policies

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

@@ -7,7 +7,7 @@ ms.subservice: azure-mqtt-broker
 ms.topic: how-to
 ms.custom:
   - ignite-2023
-ms.date: 07/26/2024
+ms.date: 08/02/2024
 
 #CustomerIntent: As an operator, I want to configure authentication so that I have secure MQTT broker communications.
 ---
@@ -29,27 +29,26 @@ kubectl get brokerauthentication authn -n azure-iot-operations -o yaml
 The output shows the default BrokerAuthentication resource, with metadata removed for brevity:
 
 ```yaml
-apiVersion: mq.iotoperations.azure.com/v1beta1
+apiVersion: mqttbroker.iotoperations.azure.com/v1beta1
 kind: BrokerAuthentication
 metadata:
   name: authn
   namespace: azure-iot-operations
 spec:
-  listenerRef:
-    - listener
   authenticationMethods:
-    - sat:
-        audiences: ["aio-mq"]
+  - method: ServiceAccountToken
+    serviceAccountToken:
+      audiences:
+      - aio-mq
 ```
 
 To change the configuration, modify the `authenticationMethods` setting in this BrokerAuthentication resource or create new brand new BrokerAuthentication resource with a different name. Then, deploy it using `kubectl apply`.
 
 ## Relationship between BrokerListener and BrokerAuthentication
 
-BrokerListener and BrokerAuthentication are separate resources, but they're linked together using `listenerRef`. The following rules apply:
+The following rules apply to the relationship between BrokerListener and BrokerAuthentication:
 
-* A BrokerListener can be linked to only one BrokerAuthentication
-* A BrokerAuthentication can be linked to multiple BrokerListeners
+* Each BrokerListener can have multiple ports. Each port can be linked to a BrokerAuthentication resource. 
 * Each BrokerAuthentication can support multiple authentication methods at once
 
 ## Authentication flow
@@ -71,18 +70,21 @@ The authentication flow ends when:
 With multiple authentication methods, MQTT broker has a fallback mechanism. For example:
 
 ```yaml
-apiVersion: mq.iotoperations.azure.com/v1beta1
+apiVersion: mqttbroker.iotoperations.azure.com/v1beta1
 kind: BrokerAuthentication
 metadata: 
   name: authn
   namespace: azure-iot-operations
 spec:
-  listenerRef:
-    - listener
   authenticationMethods:
-    - custom:
+    - method: Custom
+      custom:
+        # ...
+    - method: ServiceAccountToken
+      serviceAccountToken:
         # ...
-    - sat:
+    - method: x509Credentials
+      x509Credentials:
         # ...
 ```
 
@@ -98,12 +100,7 @@ If the custom authentication server is unavailable and all subsequent methods de
 
 ## Disable authentication
 
-For testing, disable authentication by changing it in the [BrokerListener resource](howto-configure-brokerlistener.md).
-
-```yaml
-spec:
-  authenticationEnabled: false
-```
+For testing, you can disable authentication by omitting `authenticationRef` in the `ports` setting of a BrokerListener resource.
 
 ## Configure authentication method
 
@@ -155,14 +152,15 @@ BinaryData
 X509 attributes can be specified in the *BrokerAuthentication* resource. For example, every client that has a certificate issued by the root CA `CN = Contoso Root CA Cert, OU = Engineering, C = US` or an intermediate CA `CN = Contoso Intermediate CA` receives the attributes listed.
 
 ```yaml
-apiVersion: mq.iotoperations.azure.com/v1beta1
+apiVersion: mqttbroker.iotoperations.azure.com/v1beta1
 kind: BrokerAuthentication
 metadata: 
   name: authn
   namespace: azure-iot-operations
 spec:
   authenticationMethods:
-    - x509Credentials:
+    - method: x509Credentials
+      x509Credentials:
         authorizationAttributes:
           root:
             subject = "CN = Contoso Root CA Cert, OU = Engineering, C = US"
@@ -192,7 +190,8 @@ Finally, once the trusted client root CA certificate and the certificate-to-attr
 ```yaml
 spec:
   authenticationMethods:
-    - x509:
+    - method: x509Credentials
+      x509Credentials:
         trustedClientCaCert: client-ca
         attributes:
           secretName: x509-attributes
@@ -264,13 +263,16 @@ Clients authentication via SAT can optionally have their SATs annotated with att
 
 ### Enable Service Account Token (SAT) authentication
 
-Modify the `authenticationMethods` setting in a BrokerAuthentication resource to specify `sat` as a valid authentication method. The `audiences` specifies the list of valid audiences for tokens. Choose unique values that identify the MQTT broker service. You must specify at least one audience, and all SATs must match one of the specified audiences.
+Modify the `authenticationMethods` setting in a BrokerAuthentication resource to specify `ServiceAccountToken` as a valid authentication method. The `audiences` specifies the list of valid audiences for tokens. Choose unique values that identify the MQTT broker service. You must specify at least one audience, and all SATs must match one of the specified audiences.
 
 ```yaml
 spec:
   authenticationMethods:
-    - sat:
-        audiences: ["aio-mq", "my-audience"]
+    - method: ServiceAccountToken
+      serviceAccountToken:
+        audiences:
+        - aio-mq
+        -  my-audience
 ```
 
 Apply your changes with `kubectl apply`. It might take a few minutes for the changes to take effect.

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

@@ -29,7 +29,6 @@ The specification of a *BrokerAuthorization* resource has the following fields:
 
 | Field Name | Required | Description |
 | --- | --- | --- |
-| listenerRef | Yes | The names of the BrokerListener resources that this authorization policy applies. This field is required and must match an existing *BrokerListener* resource in the same namespace. |
 | authorizationPolicies | Yes | This field defines the settings for the authorization policies, such as *enableCache* and *rules*.|
 | enableCache | No | Whether to enable caching for the authorization policies.  If set to `true`, the broker caches the authorization results for each client and topic combination to improve performance and reduce latency. If set to `false`, the broker evaluates the authorization policies for each client and topic request, to ensure consistency and accuracy. This field is optional and defaults to `false`. |
 | rules | No | A list of rules that specify the principals and resources for the authorization policies. Each rule has these subfields: *principals* and *brokerResources*. |
@@ -44,14 +43,12 @@ The specification of a *BrokerAuthorization* resource has the following fields:
 The following example shows how to create a *BrokerAuthorization* resource that defines the authorization policies for a listener named *my-listener*.
 
 ```yaml
-apiVersion: mq.iotoperations.azure.com/v1beta1
+apiVersion: mqttbroker.iotoperations.azure.com/v1beta1
 kind: BrokerAuthorization
 metadata:
   name: "my-authz-policies"
   namespace: azure-iot-operations
 spec:
-  listenerRef:
-    - "my-listener" # change to match your listener name as needed
   authorizationPolicies:
     enableCache: true
     rules:
@@ -92,7 +89,7 @@ Clients that use [X.509 certificates for authentication](./howto-configure-authe
 
 ### Using attributes
 
-To create rules based on properties from a client's certificate, its root CA, or intermediate CA, define the X.509 attributes in in the *BrokerAuthorization* resource. For more information, see [Certificate attributes](howto-configure-authentication.md#certificate-attributes).
+To create rules based on properties from a client's certificate, its root CA, or intermediate CA, define the X.509 attributes in the *BrokerAuthorization* resource. For more information, see [Certificate attributes](howto-configure-authentication.md#certificate-attributes).
 
 ### With client certificate subject common name as username
 
@@ -113,14 +110,12 @@ Attribute annotations must begin with `aio-mq-broker-auth/` to distinguish them
 As the application has an authorization attribute called `authz-sat`, there's no need to provide a `clientId` or `username`. The corresponding *BrokerAuthorization* resource uses this attribute as a principal, for example:
 
 ```yaml
-apiVersion: mq.iotoperations.azure.com/v1beta1
+apiVersion: mqttbroker.iotoperations.azure.com/v1beta1
 kind: BrokerAuthorization
 metadata:
   name: "my-authz-policies"
   namespace: azure-iot-operations
 spec:
-  listenerRef:
-    - "az-mqtt-non-tls-listener"
   authorizationPolicies:
     enableCache: false
     rules:
@@ -161,7 +156,7 @@ kubectl edit brokerauthorization my-authz-policies
 To disable authorization, set `authorizationEnabled: false` in the BrokerListener resource. When the policy is set to allow all clients, all [authenticated clients](./howto-configure-authentication.md) can access all operations.
 
 ```yaml
-apiVersion: mq.iotoperations.azure.com/v1beta1
+apiVersion: mqttbroker.iotoperations.azure.com/v1beta1
 kind: BrokerListener
 metadata:
   name: "my-listener"

articles/iot-operations/manage-mqtt-broker/howto-configure-availability-scale.md

@@ -108,7 +108,7 @@ kubectl delete broker broker -n azure-iot-operations
 Then, create a YAML file with desired settings. For example, the following YAML file configures the broker with name `broker` in namespace `azure-iot-operations` with `medium` memory profile and `distributed` mode with two frontend replicas and two backend chains with two partitions and two workers each. Also, the [encryption of internal traffic option](#configure-encryption-of-internal-traffic) is disabled.
 
 ```yaml
-apiVersion: mq.iotoperations.azure.com/v1beta1
+apiVersion: mqttbroker.iotoperations.azure.com/v1beta1
 kind: Broker
 metadata:
   name: broker
@@ -178,7 +178,7 @@ The following table lists the properties of the broker advanced settings that in
 Here's an example of a *Broker* with advanced settings:
 
 ```yml
-apiVersion: mq.iotoperations.azure.com/v1beta1
+apiVersion: mqttbroker.iotoperations.azure.com/v1beta1
 kind: Broker
 metadata:
   name: broker
@@ -243,7 +243,7 @@ You can configure diagnostics using the *Broker* custom resource definition (CRD
 Here's an example of a *Broker* custom resource with metrics and tracing enabled and self-check disabled:
 
 ```yaml
-apiVersion: mq.iotoperations.azure.com/v1beta1
+apiVersion: mqttbroker.iotoperations.azure.com/v1beta1
 kind: Broker
 metadata:
   name: broker