docs(apim-shgw): SHGW is deprecated and provide Azure Advisor query for Azure Resource Graph

tomkerkhove · tomkerkhove · commit c2c695633f70 · 2022-09-26T08:03:17.000+02:00
Signed-off-by: Tom Kerkhove &lt;kerkhove.tom@gmail.com&gt;
diff --git a/articles/api-management/api-management-gateways-overview.md b/articles/api-management/api-management-gateways-overview.md
@@ -44,6 +44,7 @@ API Management offers both managed and self-hosted gateways:
 
     * Each self-hosted gateway is associated with a **Gateway** resource in a cloud-based API Management instance from which it receives configuration updates and communicates status. 
 
+[!INCLUDE [preview](./includes/preview/preview-callout-self-hosted-gateway-deprecation.md.md)]
 
 ## Feature comparison: Managed versus self-hosted gateways
 
@@ -53,7 +54,6 @@ The following table compares features available in the managed gateway versus th
 > * Some features of managed and self-hosted gateways are supported only in certain [service tiers](api-management-features.md) or with certain [deployment environments](self-hosted-gateway-overview.md#packaging) for self-hosted gateways.
 > * See also self-hosted gateway [limitations](self-hosted-gateway-overview.md#limitations).
 
-
 ### Infrastructure
 
 | Feature support  | Managed (Dedicated)  | Managed (Consumption) | Self-hosted  |
diff --git a/articles/api-management/how-to-deploy-self-hosted-gateway-azure-kubernetes-service.md b/articles/api-management/how-to-deploy-self-hosted-gateway-azure-kubernetes-service.md
@@ -13,6 +13,8 @@ ms.author: danlep
 
 This article provides the steps for deploying self-hosted gateway component of Azure API Management to [Azure Kubernetes Service](https://azure.microsoft.com/services/kubernetes-service/). For deploying self-hosted gateway to a Kubernetes cluster, see the how-to article for deployment by using a [deployment YAML file](how-to-deploy-self-hosted-gateway-kubernetes.md) or [with Helm](how-to-deploy-self-hosted-gateway-kubernetes-helm.md).
 
+[!INCLUDE [preview](./includes/preview/preview-callout-self-hosted-gateway-deprecation.md.md)]
+
 > [!NOTE]
 > You can also deploy self-hosted gateway to an [Azure Arc-enabled Kubernetes cluster](how-to-deploy-self-hosted-gateway-azure-arc.md) as a [cluster extension](../azure-arc/kubernetes/extensions.md).
 
diff --git a/articles/api-management/how-to-deploy-self-hosted-gateway-docker.md b/articles/api-management/how-to-deploy-self-hosted-gateway-docker.md
@@ -13,6 +13,8 @@ ms.author: danlep
 
 This article provides the steps for deploying self-hosted gateway component of Azure API Management to a Docker environment.
 
+[!INCLUDE [preview](./includes/preview/preview-callout-self-hosted-gateway-deprecation.md.md)]
+
 > [!NOTE]
 > Hosting self-hosted gateway in Docker is best suited for evaluation and development use cases. Kubernetes is recommended for production use. Learn how to [deploy with Helm](how-to-deploy-self-hosted-gateway-kubernetes-helm.md) or using [deployment YAML file](how-to-deploy-self-hosted-gateway-kubernetes.md) to learn how to deploy self-hosted gateway to Kubernetes.
 
diff --git a/articles/api-management/how-to-deploy-self-hosted-gateway-kubernetes-helm.md b/articles/api-management/how-to-deploy-self-hosted-gateway-kubernetes-helm.md
@@ -15,6 +15,8 @@ ms.author: tomkerkhove
 
 This article provides the steps for deploying self-hosted gateway component of Azure API Management to a Kubernetes cluster by using Helm.
 
+[!INCLUDE [preview](./includes/preview/preview-callout-self-hosted-gateway-deprecation.md.md)]
+
 > [!NOTE]
 > You can also deploy self-hosted gateway to an [Azure Arc-enabled Kubernetes cluster](how-to-deploy-self-hosted-gateway-azure-arc.md) as a [cluster extension](../azure-arc/kubernetes/extensions.md).
 
diff --git a/articles/api-management/how-to-deploy-self-hosted-gateway-kubernetes.md b/articles/api-management/how-to-deploy-self-hosted-gateway-kubernetes.md
@@ -13,6 +13,8 @@ ms.date: 05/25/2021
 
 This article describes the steps for deploying the self-hosted gateway component of Azure API Management to a Kubernetes cluster.
 
+[!INCLUDE [preview](./includes/preview/preview-callout-self-hosted-gateway-deprecation.md.md)]
+
 > [!NOTE]
 > You can also deploy self-hosted gateway to an [Azure Arc-enabled Kubernetes cluster](how-to-deploy-self-hosted-gateway-azure-arc.md) as a [cluster extension](../azure-arc/kubernetes/extensions.md).
 
diff --git a/articles/api-management/how-to-self-hosted-gateway-on-kubernetes-in-production.md b/articles/api-management/how-to-self-hosted-gateway-on-kubernetes-in-production.md
@@ -16,6 +16,8 @@ In order to run the self-hosted gateway in production, there are various aspects
 
 This article provides guidance on how to run [self-hosted gateway](./self-hosted-gateway-overview.md) on Kubernetes for production workloads to ensure that it will run smoothly and reliably.
 
+[!INCLUDE [preview](./includes/preview/preview-callout-self-hosted-gateway-deprecation.md.md)]
+
 ## Access token
 Without a valid access token, a self-hosted gateway can't access and download configuration data from the endpoint of the associated API Management service. The access token can be valid for a maximum of 30 days. It must be regenerated, and the cluster configured with a fresh token, either manually or via automation before it expires.
 
diff --git a/articles/api-management/import-container-app-with-oas.md b/articles/api-management/import-container-app-with-oas.md
@@ -1,5 +1,5 @@
 ---
-title: Import Azure Container App to Azure API Management  | Microsoft Docs
+title: Import Azure Container App to Azure API Management | Microsoft Docs
 description: This article shows you how to use Azure API Management to import a web API hosted in Azure Container Apps.
 services: api-management
 documentationcenter: ''
diff --git a/articles/api-management/includes/preview/preview-callout-self-hosted-gateway-deprecation.md b/articles/api-management/includes/preview/preview-callout-self-hosted-gateway-deprecation.md
@@ -0,0 +1,10 @@
+---
+ms.service: api-management
+ms.topic: include
+author: tomkerkhove
+ms.author: tomkerkhove
+ms.date: 09/26/2022
+---
+
+> [!IMPORTANT]
+> Support for Azure API Management self-hosted gateway version 0 and version 1 container images is ending on 1 October 2023, along with its corresponding Configuration API v1. Use our [migration guide](./../../self-hosted-gateway-migration-guide.md) to use self-hosted gateway v2.0.0 or higher with Configuration API v2. [Learn more in our deprecation documentation](./../../breaking-changes/self-hosted-gateway-v0-v1-retirement-oct-2023.md)
diff --git a/articles/api-management/self-hosted-gateway-migration-guide.md b/articles/api-management/self-hosted-gateway-migration-guide.md
@@ -15,6 +15,9 @@ ms.author: tomkerkhove
 
 This article explains how to migrate existing self-hosted gateway deployments to self-hosted gateway v2.
 
+> [!IMPORTANT]
+> Support for Azure API Management self-hosted gateway version 0 and version 1 container images is ending on 1 October 2023, along with its corresponding Configuration API v1. [Learn more in our deprecation documentation](./../../breaking-changes/self-hosted-gateway-v0-v1-retirement-oct-2023.md)
+
 ## What's new?
 
 As we strive to make it easier for customers to deploy our self-hosted gateway, we've **introduced a new configuration API** that removes the dependency on Azure Storage, unless you're using [API inspector](api-management-howto-api-inspector.md) or quotas.
@@ -112,6 +115,45 @@ In order to make the migration easier, we have introduced new Azure Advisor reco
 
 We highly recommend customers to use ["All Recommendations" overview in Azure Advisor](https://portal.azure.com/#view/Microsoft_Azure_Expert/AdvisorMenuBlade/~/All) to determine if a migration is required. Use the filtering options to see if one of the above recommendations is present.
 
+### Use Azure Resource Graph to identify Azure API Management instances
+
+This Azure Resource Graph query provides you with a list of impacted Azure API Management instances:
+
+```kusto
+AdvisorResources
+| where type == 'microsoft.advisor/recommendations'
+| where properties.impactedField == 'Microsoft.ApiManagement/service' and properties.category == 'OperationalExcellence'
+| extend
+    recommendationTitle = properties.shortDescription.solution
+| where recommendationTitle == 'Use self-hosted gateway v2' or recommendationTitle == 'Use Configuration API v2 for self-hosted gateways'
+| extend
+    instanceName = properties.impactedValue,
+    recommendationImpact = properties.impact,
+    recommendationMetadata = properties.extendedProperties,
+    lastUpdated = properties.lastUpdated
+| project tenantId, subscriptionId, resourceGroup, instanceName, recommendationTitle, recommendationImpact, recommendationMetadata, lastUpdated
+```
+
+# [Azure CLI](#tab/azure-cli)
+
+```azurecli-interactive
+az graph query -q "AdvisorResources | where type == 'microsoft.advisor/recommendations' | where properties.impactedField == 'Microsoft.ApiManagement/service' and properties.category == 'OperationalExcellence' | extend recommendationTitle = properties.shortDescription.solution | where recommendationTitle == 'Use self-hosted gateway v2' or recommendationTitle == 'Use Configuration API v2 for self-hosted gateways' | extend instanceName = properties.impactedValue, recommendationImpact = properties.impact, recommendationMetadata = properties.extendedProperties, lastUpdated = properties.lastUpdated | project tenantId, subscriptionId, resourceGroup, instanceName, recommendationTitle, recommendationImpact, lastUpdated"
+```
+
+# [Azure PowerShell](#tab/azure-powershell)
+
+```azurepowershell-interactive
+Search-AzGraph -Query "AdvisorResources | where type == 'microsoft.advisor/recommendations' | where properties.impactedField == 'Microsoft.ApiManagement/service' and properties.category == 'OperationalExcellence' | extend recommendationTitle = properties.shortDescription.solution | where recommendationTitle == 'Use self-hosted gateway v2' or recommendationTitle == 'Use Configuration API v2 for self-hosted gateways' | extend instanceName = properties.impactedValue, recommendationImpact = properties.impact, recommendationMetadata = properties.extendedProperties, lastUpdated = properties.lastUpdated | project tenantId, subscriptionId, resourceGroup, instanceName, recommendationTitle, recommendationImpact, lastUpdated"
+```
+
+# [Portal](#tab/azure-portal)
+
+:::image type="icon" source="./../articles/governance/resource-graph/media/resource-graph-small.png"::: Try this query in Azure Resource Graph Explorer:
+
+- Azure portal: <a href="https://portal.azure.com/?feature.customportal=false#blade/HubsExtension/ArgQueryBlade/query/AdvisorResources%0A%7C%20where%20type%20%3D%3D%20%27microsoft.advisor%2Frecommendations%27%0A%7C%20where%20properties.impactedField%20%3D%3D%20%27Microsoft.ApiManagement%2Fservice%27%20and%20properties.category%20%3D%3D%20%27OperationalExcellence%27%0A%7C%20extend%0A%20%20%20%20recommendationTitle%20%3D%20properties.shortDescription.solution%0A%7C%20where%20recommendationTitle%20%3D%3D%20%27Use%20self-hosted%20gateway%20v2%27%20or%20recommendationTitle%20%3D%3D%20%27Use%20Configuration%20API%20v2%20for%20self-hosted%20gateways%27%0A%7C%20extend%0A%20%20%20%20instanceName%20%3D%20properties.impactedValue%2C%0A%20%20%20%20recommendationImpact%20%3D%20properties.impact%2C%0A%20%20%20%20recommendationMetadata%20%3D%20properties.extendedProperties%2C%0A%20%20%20%20lastUpdated%20%3D%20properties.lastUpdated%0A%7C%20project%20tenantId%2C%20subscriptionId%2C%20resourceGroup%2C%20instanceName%2C%20recommendationTitle%2C%20recommendationImpact%2C%20recommendationMetadata%2C%20lastUpdated" target="_blank">portal.azure.com</a>
+- Azure Government portal: <a href="https://portal.azure.us/?feature.customportal=false#blade/HubsExtension/ArgQueryBlade/query/AdvisorResources%0A%7C%20where%20type%20%3D%3D%20%27microsoft.advisor%2Frecommendations%27%0A%7C%20where%20properties.impactedField%20%3D%3D%20%27Microsoft.ApiManagement%2Fservice%27%20and%20properties.category%20%3D%3D%20%27OperationalExcellence%27%0A%7C%20extend%0A%20%20%20%20recommendationTitle%20%3D%20properties.shortDescription.solution%0A%7C%20where%20recommendationTitle%20%3D%3D%20%27Use%20self-hosted%20gateway%20v2%27%20or%20recommendationTitle%20%3D%3D%20%27Use%20Configuration%20API%20v2%20for%20self-hosted%20gateways%27%0A%7C%20extend%0A%20%20%20%20instanceName%20%3D%20properties.impactedValue%2C%0A%20%20%20%20recommendationImpact%20%3D%20properties.impact%2C%0A%20%20%20%20recommendationMetadata%20%3D%20properties.extendedProperties%2C%0A%20%20%20%20lastUpdated%20%3D%20properties.lastUpdated%0A%7C%20project%20tenantId%2C%20subscriptionId%2C%20resourceGroup%2C%20instanceName%2C%20recommendationTitle%2C%20recommendationImpact%2C%20recommendationMetadata%2C%20lastUpdated" target="_blank">portal.azure.us</a>
+- Azure China 21Vianet portal: <a href="https://portal.azure.cn/?feature.customportal=false#blade/HubsExtension/ArgQueryBlade/query/AdvisorResources%0A%7C%20where%20type%20%3D%3D%20%27microsoft.advisor%2Frecommendations%27%0A%7C%20where%20properties.impactedField%20%3D%3D%20%27Microsoft.ApiManagement%2Fservice%27%20and%20properties.category%20%3D%3D%20%27OperationalExcellence%27%0A%7C%20extend%0A%20%20%20%20recommendationTitle%20%3D%20properties.shortDescription.solution%0A%7C%20where%20recommendationTitle%20%3D%3D%20%27Use%20self-hosted%20gateway%20v2%27%20or%20recommendationTitle%20%3D%3D%20%27Use%20Configuration%20API%20v2%20for%20self-hosted%20gateways%27%0A%7C%20extend%0A%20%20%20%20instanceName%20%3D%20properties.impactedValue%2C%0A%20%20%20%20recommendationImpact%20%3D%20properties.impact%2C%0A%20%20%20%20recommendationMetadata%20%3D%20properties.extendedProperties%2C%0A%20%20%20%20lastUpdated%20%3D%20properties.lastUpdated%0A%7C%20project%20tenantId%2C%20subscriptionId%2C%20resourceGroup%2C%20instanceName%2C%20recommendationTitle%2C%20recommendationImpact%2C%20recommendationMetadata%2C%20lastUpdated" target="_blank">portal.azure.cn</a>
+
 ## Known limitations
 
 Here's a list of known limitations for the self-hosted gateway v2:
diff --git a/articles/api-management/self-hosted-gateway-overview.md b/articles/api-management/self-hosted-gateway-overview.md
@@ -39,7 +39,6 @@ Deploying self-hosted gateways into the same environments where the backend API
 
 :::image type="content" source="media/self-hosted-gateway-overview/with-gateways.png" alt-text="API traffic flow with self-hosted gateways":::
 
-
 ## Packaging
 
 The self-hosted gateway is available as a Linux-based Docker [container image](https://aka.ms/apim/shgw/registry-portal) from the Microsoft Artifact Registry. It can be deployed to Docker, Kubernetes, or any other container orchestration solution running on a server cluster on premises, cloud infrastructure, or for evaluation and development purposes, on a personal computer. You can also deploy the self-hosted gateway as a cluster extension to an [Azure Arc-enabled Kubernetes cluster](./how-to-deploy-self-hosted-gateway-azure-arc.md).
@@ -88,6 +87,8 @@ Self-hosted gateways require outbound TCP/IP connectivity to Azure on port 443.
 -   Sending metrics to Azure Monitor, if configured to do so
 -   Sending events to Application Insights, if set to do so
 
+[!INCLUDE [preview](./includes/preview/preview-callout-self-hosted-gateway-deprecation.md.md)]
+
 ### FQDN dependencies
 
 To operate properly, each self-hosted gateway needs outbound connectivity on port 443 to the following endpoints associated with its cloud-based API Management instance:
