Merge pull request #289463 from MicrosoftDocs/main

10/30 11:00 AM IST Publish

Author: Saisang

articles/api-management/import-and-publish.md

@@ -6,15 +6,15 @@ author: dlepow
 ms.service: azure-api-management
 ms.custom: mvc, devdivchpfy22, engagement-fy23
 ms.topic: tutorial
-ms.date: 06/15/2023
+ms.date: 10/29/2024
 ms.author: danlep
 
 ---
 # Tutorial: Import and publish your first API
 
 [!INCLUDE [api-management-availability-all-tiers](../../includes/api-management-availability-all-tiers.md)]
 
-This tutorial shows how to import an OpenAPI specification backend API in JSON format into Azure API Management. Microsoft provides the backend API used in this example, and hosts it on Azure at `https://conferenceapi.azurewebsites.net`.
+This tutorial shows how to import an OpenAPI specification backend API in JSON format into Azure API Management. For this example, you import the open source [Petstore API](https://petstore3.swagger.io/).
 
 Once you import the backend API into API Management, your API Management API becomes a façade for the backend API. You can customize the façade to your needs in API Management without touching the backend API. For more information, see [Transform and protect your API](transform-api.md).
 
@@ -26,7 +26,7 @@ In this tutorial, you learn how to:
 
 After import, you can manage the API in the Azure portal.
 
-:::image type="content" source="media/import-and-publish/created-api.png" alt-text="Screenshot of a new API in API Management in the portal.":::
+:::image type="content" source="media/import-and-publish/created-api.png" lightbox="media/import-and-publish/created-api.png" alt-text="Screenshot of a new API in API Management in the portal.":::
 
 ## Prerequisites
 
@@ -51,21 +51,18 @@ This section shows how to import and publish an OpenAPI specification backend AP
 
    |Setting|Value|Description|
    |-------|-----|-----------|
-   |**OpenAPI specification**|*https:\//conferenceapi.azurewebsites.net?format=json*|Specifies the backend service implementing the API and the operations that the API supports. <br/><br/>The backend service URL appears later as the **Web service URL** on the API's **Settings** page.<br/><br/>After import, you can add, edit, rename, or delete operations in the specification.  |
+   |**OpenAPI specification**|*https:\//petstore3.swagger.io/api/v3/openapi.json*|Specifies the backend service implementing the API and the operations that the API supports. <br/><br/>The backend service URL appears later as the **Web service URL** on the API's **Settings** page.<br/><br/>After import, you can add, edit, rename, or delete operations in the specification.  |
    | **Include query parameters in operation templates** | Selected (default) | Specifies whether to import required query parameters in the specification as template parameters in API Management.  |
    |**Display name**|After you enter the OpenAPI specification URL, API Management fills out this field based on the JSON.|The name displayed in the [developer portal](api-management-howto-developer-portal.md).|
    |**Name**|After you enter the OpenAPI specification URL, API Management fills out this field based on the JSON.|A unique name for the API.|
    |**Description**|After you enter the OpenAPI specification URL, API Management fills out this field based on the JSON.|An optional description of the API.|
    |**URL scheme**|**HTTPS**|Which protocols can access the API.|
-   |**API URL suffix**|*conference*|The suffix appended to the base URL for the API Management service. API Management distinguishes APIs by their suffix, so the suffix must be unique for every API for a given publisher.|
+   |**API URL suffix**|*petstore*|The suffix appended to the base URL for the API Management service. API Management distinguishes APIs by their suffix, so the suffix must be unique for every API for a given publisher.|
    |**Tags**| |Tags for organizing APIs for searching, grouping, or filtering.|
-   |**Products**|**Unlimited**|Association of one or more APIs. Each API Management instance comes with two sample products: **Starter** and **Unlimited**. You publish an API by associating the API with a product, **Unlimited** in this example.<br/><br/> You can include several APIs in a product and offer product [subscriptions](api-management-subscriptions.md) to developers through the developer portal. To add this API to another product, type or select the product name. Repeat this step to add the API to multiple products. You can also add APIs to products later from the **Settings** page.<br/><br/>  For more information about products, see [Create and publish a product](api-management-howto-add-products.md).|
+   |**Products**|**Unlimited**|Association of one or more APIs. In certain tiers, API Management instance comes with two sample products: **Starter** and **Unlimited**. You publish an API in the developer portal by associating the API with a product.<br/><br/> You can include several APIs in a product and offer product [subscriptions](api-management-subscriptions.md) to developers through the developer portal. To add this API to another product, type or select the product name. Repeat this step to add the API to multiple products. You can also add APIs to products later from the **Settings** page.<br/><br/>  For more information about products, see [Create and publish a product](api-management-howto-add-products.md).|
    |**Gateways**|**Managed**|API gateway(s) that expose the API. This field is available only in **Developer** and **Premium** tier services.<br/><br/>**Managed** indicates the gateway built into the API Management service and hosted by Microsoft in Azure. [Self-hosted gateways](self-hosted-gateway-overview.md) are available only in the Premium and Developer service tiers. You can deploy them on-premises or in other clouds.<br/><br/> If no gateways are selected, the API won't be available and your API requests won't succeed.|
    |**Version this API?**|Select or deselect|For more information, see [Publish multiple versions of your API](api-management-get-started-publish-versions.md).|
 
-   > [!NOTE]
-   > To publish the API to API consumers, you must associate it with a product.
-
 1. Select **Create** to create your API.
 
 If you have problems importing an API definition, see the [list of known issues and restrictions](api-management-api-import-restrictions.md).
@@ -74,8 +71,8 @@ If you have problems importing an API definition, see the [list of known issues
 
 You can call API operations directly from the Azure portal, which provides a convenient way to view and test the operations. In the portal's test console, by default, APIs are called by using a key from the built-in all-access subscription. You can also test API calls by using a subscription key scoped to a product.
 
-1. In the left navigation of your API Management instance, select **APIs** > **Demo Conference API**.
-1. Select the **Test** tab, and then select **GetSpeakers**. The page shows **Query parameters** and **Headers**, if any. 
+1. In the left navigation of your API Management instance, select **APIs** > **Swagger Petstore**.
+1. Select the **Test** tab, and then select **Finds Pets by status**. The page shows the *status* **Query parameter**. Select one of the available values, such as *pending*. You can also add query parameters and headers here. 
 
     In the **HTTP request** section, the **Ocp-Apim-Subscription-Key** header is filled in automatically for you, which you can see if you select the "eye" icon.
 1. Select **Send**.

articles/api-management/media/import-and-publish/created-api.png

@@ -20,7 +20,7 @@ This article shows you how to configure Azure Bastion to use Kerberos authentica
 * VMs migrated from on-premises to Azure aren't currently supported for Kerberos. 
 * Cross-realm authentication isn't currently supported for Kerberos.
 * The Domain controller must be an Azure Hosted VM within the same VNET that bastion is deployed.
-* Changes to DNS server aren't currently supported for Kerberos. After making any changes to DNS server, you'll need to delete and re-create the Bastion resource.
+* Changes to DNS servers do not propagate to Bastion. Bastion re-deployment is needed for DNS info to properly propagate. After making any changes to DNS server, you'll need to delete and re-create the Bastion resource.
 * If additional DC (domain controllers) are added, Bastion will only recognize the first DC.
 * If additional DCs are added for different domains, the added domains can't successfully authenticate with Kerberos.
 

articles/api-management/media/import-and-publish/open-api-specs.png

@@ -5,7 +5,7 @@ description: Learn how to troubleshoot issues with the Oracle connector in Azure
 author: jianleishen
 ms.subservice: data-movement
 ms.topic: troubleshooting
-ms.date: 07/02/2024
+ms.date: 10/23/2024
 ms.author: jianleishen
 ms.custom: has-adal-ref, synapse
 ---
@@ -35,17 +35,17 @@ This article provides suggestions to troubleshoot common problems with the Oracl
 
 - **Cause**: The secure algorithm is not added to your Oracle server. 
 
-- **Recommendation**: Update your Oracle server settings to add these secure algorithms:
+- **Recommendation**: Update your Oracle server settings to add these secure algorithms if they are not already included:
 
-    - The following algorithms are deemed as secure by OpenSSL, and will be sent along to the server for OAS (Oracle Advanced Security) encryption.
+    - For **SQLNET.ENCRYPTION_TYPES_SERVER**, need to add the following algorithms that are deemed as secure by OpenSSL and will be used for OAS (Oracle Advanced Security) encryption.
         - AES256 
         - AES192 
         - 3DES168 
         - AES128 
         - 3DES112 
         - DES
 
-    - The following algorithms are deemed as secure by OpenSSL, and will be sent along to the server for OAS (Oracle Advanced Security) data integrity. 
+    - For **SQLNET.CRYPTO_CHECKSUM_TYPES_SERVER**, need to add the following algorithms that are deemed as secure by OpenSSL and will be used for OAS (Oracle Advanced Security) data integrity.
         - SHA256 
         - SHA384 
         - SHA512

articles/api-management/media/import-and-publish/test-new-api.png

@@ -406,16 +406,16 @@ spec:
     command: ["sh", "-c"]
     args: ["apk add mosquitto-clients mqttui && sleep infinity"]
     volumeMounts:
-    - name: mq-sat
+    - name: broker-sat
       mountPath: /var/run/secrets/tokens
     - name: trust-bundle
       mountPath: /var/run/certs
   volumes:
-  - name: mq-sat
+  - name: broker-sat
     projected:
       sources:
       - serviceAccountToken:
-          path: mq-sat
+          path: broker-sat
           audience: aio-internal # Must match audience in BrokerAuthentication
           expirationSeconds: 86400
   - name: trust-bundle
@@ -450,7 +450,7 @@ mosquitto_sub --host aio-broker --port 18883 \
   -t "tutorial/#" \
   --debug --cafile /var/run/certs/ca.crt \
   -D CONNECT authentication-method 'K8S-SAT' \
-  -D CONNECT authentication-data $(cat /var/run/secrets/tokens/mq-sat)
+  -D CONNECT authentication-data $(cat /var/run/secrets/tokens/broker-sat)
 ```
 
 Leave the command running and open a new terminal window.
@@ -472,7 +472,7 @@ mosquitto_pub -h aio-broker -p 18883 \
   --repeat 5 --repeat-delay 1 -d \
   --debug --cafile /var/run/certs/ca.crt \
   -D CONNECT authentication-method 'K8S-SAT' \
-  -D CONNECT authentication-data $(cat /var/run/secrets/tokens/mq-sat)
+  -D CONNECT authentication-data $(cat /var/run/secrets/tokens/broker-sat)
 ```
 
 ## View the messages in the subscriber

articles/bastion/kerberos-authentication-portal.md

@@ -20,7 +20,7 @@ The connector for OPC UA publishes messages from OPC UA servers to the MQTT brok
 The payload of an OPC UA message is a JSON object that contains the telemetry data from the OPC UA server. The following example shows the payload of a message from the sample thermostat asset used in the quickstarts. Use the following command to subscribe to messages in the `azure-iot-operations/data` topic:
 
 ```console
-mosquitto_sub --host aio-broker --port 18883 --topic "azure-iot-operations/data/#" -v --debug --cafile /var/run/certs/ca.crt -D CONNECT authentication-method 'K8S-SAT' -D CONNECT authentication-data $(cat /var/run/secrets/tokens/mq-sat)
+mosquitto_sub --host aio-broker --port 18883 --topic "azure-iot-operations/data/#" -v --debug --cafile /var/run/certs/ca.crt -D CONNECT authentication-method 'K8S-SAT' -D CONNECT authentication-data $(cat /var/run/secrets/tokens/broker-sat)
 ```
 
 The output from the previous command looks like the following example:
@@ -43,7 +43,7 @@ Client $server-generated/05a22b94-c5a2-4666-9c62-837431ca6f7e received PUBLISH (
 The headers in the messages published by the connector for OPC UA are based on the [CloudEvents specification for OPC UA](https://github.com/cloudevents/spec/blob/main/cloudevents/extensions/opcua.md). The headers from an OPC UA message become user properties in a message published to the MQTT broker. The following example shows the user properties of a message from the sample thermostat asset used in the quickstarts. Use the following command to subscribe to messages in the `azure-iot-operations/data` topic:
 
 ```console
-mosquitto_sub --host aio-broker --port 18883 --topic "azure-iot-operations/data/#" -V mqttv5 -F %P --cafile /var/run/certs/ca.crt -D CONNECT authentication-method 'K8S-SAT' -D CONNECT authentication-data $(cat /var/run/secrets/tokens/mq-sat)
+mosquitto_sub --host aio-broker --port 18883 --topic "azure-iot-operations/data/#" -V mqttv5 -F %P --cafile /var/run/certs/ca.crt -D CONNECT authentication-method 'K8S-SAT' -D CONNECT authentication-data $(cat /var/run/secrets/tokens/broker-sat)
 ```
 
 The output from the previous command looks like the following example:

articles/data-factory/connector-troubleshoot-oracle.md

@@ -310,7 +310,7 @@ kubectl exec --stdin --tty mqtt-client -n azure-iot-operations -- sh
 Inside the pod's shell, run the following command to publish a message to the broker:
 
 ```bash
-mosquitto_pub --host aio-broker --port 18883 --message "hello" --topic "world" --debug --cafile /var/run/certs/ca.crt -D CONNECT authentication-method 'K8S-SAT' -D CONNECT authentication-data $(cat /var/run/secrets/tokens/mq-sat)
+mosquitto_pub --host aio-broker --port 18883 --message "hello" --topic "world" --debug --cafile /var/run/certs/ca.crt -D CONNECT authentication-method 'K8S-SAT' -D CONNECT authentication-data $(cat /var/run/secrets/tokens/broker-sat)
 ```
 
 The output should look similar to the following:
@@ -322,7 +322,7 @@ Client (null) sending PUBLISH (d0, q0, r0, m1, 'world', ... (5 bytes))
 Client (null) sending DISCONNECT
 ```
 
-The mosquitto client uses the service account token mounted at `/var/run/secrets/tokens/mq-sat` to authenticate with the broker. The token is valid for 24 hours. The client also uses the default root CA cert mounted at `/var/run/certs/ca.crt` to verify the broker's TLS certificate chain.
+The mosquitto client uses the service account token mounted at `/var/run/secrets/tokens/broker-sat` to authenticate with the broker. The token is valid for 24 hours. The client also uses the default root CA cert mounted at `/var/run/certs/ca.crt` to verify the broker's TLS certificate chain.
 
 ### Refresh service account tokens
 

articles/iot-operations/connect-to-cloud/tutorial-mqtt-bridge.md

@@ -30,19 +30,25 @@ For a list of the available settings, see the [Broker](/rest/api/iotoperationsmq
 
 To configure the scaling settings MQTT broker, you need to specify the `cardinality` fields in the specification of the *Broker* custom resource. For more information on setting the mode and cardinality settings using Azure CLI, see [az iot ops init](/cli/azure/iot/ops#az-iot-ops-init).
 
-The `cardinality` field is a nested field that has these subfields:
+### Automatic deployment cardinality
+
+To automatically determine the initial cardinality during deployment, omit the `cardinality` field in the *Broker* resource. The MQTT broker operator automatically deploys the appropriate number of pods based on the number of available nodes at the time of the deployment. This is useful for non-production scenarios where you don't need high-availability or scale.
+
+However, this is *not* auto-scaling. The operator doesn't automatically scale the number of pods based on the load. The operator only determines the initial number of pods to deploy based on the cluster hardware. As noted above, the cardinality can only be set at initial deployment time, and a new deployment is required if the cardinality settings need to be changed.
+
+### Configure cardinality directly
+
+To configure the cardinality settings directly, specify the `cardinality` field. The `cardinality` field is a nested field that has these subfields:
 
 - `frontend`: This subfield defines the settings for the frontend pods, such as:
-  - `replicas`: The number of frontend pods to deploy. This subfield is required if the `mode` field is set to `distributed`.
-  - `workers`: The number of workers to deploy per frontend, currently it must be set to `1`. This subfield is required if the `mode` field is set to `distributed`.
+  - `replicas`: The number of frontend pods to deploy. Increasing the number of frontend replicas provides high availability in case one of the frontend pods fails.
+  - `workers`: The number of logical frontend workers per replica. Increasing the number of workers per frontend replica improves CPU core utilization because each worker can use only one CPU core at most. For example, if your cluster has 3 nodes, each with 8 CPU cores, then set the number of replicas to match the number of nodes (3) and increase the number of workers up to 8 per replica as you need more frontend throughput. This way, each frontend replica can use all the CPU cores on the node without workers competing for CPU resources.
 - `backendChain`: This subfield defines the settings for the backend chains, such as:
-  - `redundancyFactor`: The number of data copies in each backend chain. This subfield is required if the `mode` field is set to `distributed`.
-  - `partitions`: The number of partitions to deploy. This subfield is required if the `mode` field is set to `distributed`.
-  - `workers`: The number of workers to deploy per backend, currently it must be set to `1`. This subfield is required if the `mode` field is set to `distributed`.
-
-If `cardinality` field is omitted, cardinality is determined by MQTT broker operator automatically deploys the appropriate number of pods based on the cluster hardware.
+  - `partitions`: The number of partitions to deploy. Increasing the number of partitions increases the number of messages that the broker can handle. Through a process called *sharding*, each partition is responsible for a portion of the messages, divided by topic ID and session ID. The frontend pods distribute message traffic across the partitions.
+  - `redundancyFactor`: The number of backend pods to deploy per partition. Increasing the redundancy factor increases the number of data copies to provide resiliency against node failures in the cluster.
+  - `workers`: The number of workers to deploy per backend replica. The workers take care of storing and delivering messages to clients together. Increasing the number of workers per backend replica increases the number of messages that the backend pod can handle. Each worker can consume up to 2 CPU cores at most, so be careful when increasing the number of workers per replica to not exceed the number of CPU cores in the cluster.
 
-To configure the scaling settings MQTT broker, you need to specify the `mode` and `cardinality` fields in the specification of the *Broker* custom resource. For more information on setting the mode and cardinality settings using Azure CLI, see [az iot ops init](/cli/azure/iot/ops#az-iot-ops-init).
+When you increase these values, the broker's capacity to handle more connections and messages improves, and it enhances high availability in case of pod or node failures. However, this also leads to higher resource consumption. So, when adjusting cardinality values, consider the memory profile settings and balance these factors to optimize the broker's resource usage.
 
 ## Configure memory profile