Merge pull request #189459 from jaesoni/disabled-listener-change

Disabled listener change

Author: Court72

articles/application-gateway/application-gateway-key-vault-common-errors.md

@@ -12,6 +12,8 @@ ms.author: jaysoni
 
 # Common key vault errors in Azure Application Gateway
 
+Application Gateway enables customers to securely store TLS certificates in Azure Key Vault. When using a Key Vault resource, it is important that the gateway always has access to the linked key vault. If your Application Gateway is unable to fetch the certificate, the associated HTTPS listeners will be placed in a disabled state. [Learn more](../application-gateway/disabled-listeners.md).
+
 This article helps you understand the details of key vault error codes you might encounter, including what is causing these errors. This article also contains steps to resolve such misconfigurations.
 
 > [!TIP]

articles/application-gateway/configuration-listeners.md

@@ -51,6 +51,9 @@ Choose HTTP or HTTPS:
 
 To configure TLS termination, a TLS/SSL certificate must be added to the listener. This allows the Application Gateway to decrypt incoming traffic and encrypt response traffic to the client. The certificate provided to the Application Gateway must be in Personal Information Exchange (PFX) format, which contains both the private and public keys.
 
+> [!NOTE]
+> When using a TLS certificate from Key Vault for a listener, you must ensure your Application Gateway always has access to that linked key vault resource and the certificate object within it. This enables seamless operations of TLS termination feature and maintains the overall health of your gateway resource. If an application gateway resource detects a misconfigured key vault, it automatically puts the associated HTTPS listener(s) in a disabled state. [Learn more](../application-gateway/disabled-listeners.md).
+
 ## Supported certificates
 
 See [Overview of TLS termination and end to end TLS with Application Gateway](ssl-overview.md#certificates-supported-for-tls-termination)

articles/application-gateway/disabled-listeners.md

@@ -0,0 +1,54 @@
+---
+title: Identifying and fixing a disabled listener
+titleSuffix: Azure Application Gateway
+description: The article explains the details of a disabled listener and ways to resolve the problem.
+author: jaesoni
+ms.service: application-gateway
+ms.topic: troubleshooting
+ms.date: 02/22/2022
+ms.author: jaysoni
+
+---
+
+# Identifying and fixing a disabled listener on your gateway
+
+The SSL/TLS certificates for Azure Application Gateway’s listeners can be referenced from a customer’s Key Vault resource. Your application gateway must always have access to such linked key vault resource and its certificate object to ensure smooth operations of the TLS termination feature and the overall health of the gateway resource.
+
+It is important to consider any impact on your Application Gateway resource when making changes or revoking access to your Key Vault resource. In case your application gateway is unable to access the associated key vault or locate its certificate object, it will automatically put that listener in a disabled state. The action is triggered only in the case of configuration errors. Transient connectivity problems do not have any impact on the listeners.
+
+A disabled listener doesn’t affect the traffic for other operational listeners on your Application Gateway. For example, the HTTP listeners or HTTPS listeners for which PFX certificate file is directly uploaded on Application Gateway resource will never go in a disabled state.
+
+[![An illustration showing affected listeners.](../application-gateway/media/disabled-listeners/affected-listener.png)](../application-gateway/media/disabled-listeners/affected-listener.png#lightbox)
+
+## Periodic check and its impact on listeners
+
+Understanding the behavior of the Application Gateway’s periodic check and its potential impact on the state of a key vault-based listener could help you to preempt such occurrences or resolve them much faster.
+
+### How does the periodic check work?
+1. Application Gateway instances periodically poll the key vault resource to obtain a new certificate version.
+1. During this activity, if the instances instead detect a broken access to the key vault resource or a missing certificate object, the listener(s) associated with that key vault will go in a disabled state. The instances are updated with this disabled status of the listener(s) within 60 secs to provide a consistent data plane behavior.
+1. After the issue is resolved by the customer, the same four-hour periodic poll verifies the access to key vault certificate object and automatically re-enables listeners on all instances of that gateway.
+
+## Ways to identify a disabled listener
+
+1. The clients will observe the error "ERR_SSL_UNRECOGNIZED_NAME_ALERT" if any request is made to a disabled listener of your Application Gateway.
+
+[ ![Screenshot of client error will look.](../application-gateway/media/disabled-listeners/client-error.png) ](../application-gateway/media/disabled-listeners/client-error.png#lightbox)
+
+2. You can verify if the error is a result of a disabled listener on your gateway by checking your [Application Gateway’s Resource Health page](../application-gateway/resource-health-overview.md). You will see an event as shown below.
+
+![A screenshot of user-driven resource health.](../application-gateway/media/disabled-listeners/resource-health-event.png)
+
+## Resolving Key Vault configuration errors
+You can narrow down to the exact cause and find steps to resolve the problem by visiting the Azure Advisor recommendation in your account.
+1. Sign-in to your Azure portal
+1. Select Advisor
+1. Select Operational Excellence category from the left menu.
+1. You will find a recommendation titled **Resolve Azure Key Vault issue for your Application Gateway**, if your gateway is experiencing this issue. Ensure the correct Subscription is selcted from the drop-down options above.
+1. Select it to view the error details and the associated key vault resource along with the [troubleshooting guide](../application-gateway/application-gateway-key-vault-common-errors.md) to fix your exact issue.
+
+> [!NOTE]
+> The disabled listener(s) are automatically enabled if Application Gateway resource detects the underlying problem is resolved. This check occurs every four-hour interval. You can expedite it by performing any minor change to Application Gateway (for HTTP Setting, Resource Tags, etc.) that will force a check against the Key Vault.
+
+## Next steps
+[Troubleshooting key vault errors in Azure Application Gateway](../application-gateway/application-gateway-key-vault-common-errors.md)

articles/application-gateway/key-vault-certs.md

@@ -158,9 +158,26 @@ Under **Choose a certificate** select the certificate named in the previous step
 
 ## Investigating and resolving Key Vault errors
 
-Azure Application Gateway doesn't just poll for the renewed certificate version on Key Vault at every four-hour interval. It also logs any error and is integrated with Azure Advisor to surface any misconfiguration as a recommendation. The recommendation contains details about the problem and the associated Key Vault resource. You can use this information along with the [troubleshooting guide](../application-gateway/application-gateway-key-vault-common-errors.md) to quickly resolve such a configuration error. 
-
-We strongly recommend that you [configure Advisor alerts](../advisor/advisor-alerts-portal.md) to stay updated when a problem is detected. To set an alert for this specific case, use **Resolve Azure Key Vault issue for your Application Gateway** as the recommendation type. 
+> [!NOTE]
+> It is important to consider any impact on your Application Gateway resource when making changes or revoking access to your Key Vault resource. In case your application gateway is unable to access the associated key vault or locate the certificate object in it, it will automatically put that listener in a disabled state. 
+>
+> You can identify this user-driven event by viewing the Resource Health for your Application Gateway. [Learn more](../application-gateway/disabled-listeners.md).
+ 
+Azure Application Gateway doesn't just poll for the renewed certificate version on Key Vault at every four-hour interval. It also logs any error and is integrated with Azure Advisor to surface any misconfiguration with a recommendation for its fix.
+ 
+1. Sign-in to your Azure portal
+1. Select Advisor
+1. Select Operational Excellence category from the left menu.
+1. You will find a recommendation titled **Resolve Azure Key Vault issue for your Application Gateway**, if your gateway is experiencing this issue. Ensure the correct Subscription is selected from the drop-down options above.
+1. Select it to view the error details, the associated key vault resource and the  [troubleshooting guide](../application-gateway/application-gateway-key-vault-common-errors.md) to fix your exact issue.
+
+By identifying such an event through Azure Advisor or Resource Health, you can quickly resolve any configuration problems with your Key Vault. We strongly recommend you take advantage of [Azure Advisor](../advisor/advisor-alerts-portal.md) and [Resource Health](../service-health/resource-health-alert-monitor-guide.md) alerts to stay informed when a problem is detected.
+ 
+For Advisor alert, use "Resolve Azure Key Vault issue for your Application Gateway" in the recommendation type as shown below.</br>
+![Diagram that shows steps for Advisor alert.](media/key-vault-certs/advisor-alert.png)
+ 
+You can configure the Resource health alert as illustrated below.</br>
+![Diagram that shows steps for Resource health alert.](media/key-vault-certs/resource-health-alert.png)
 
 ## Next steps
 

articles/application-gateway/media/disabled-listeners/affected-listener.png

@@ -284,6 +284,8 @@
         href: application-gateway-backend-health-troubleshooting.md
       - name: Key Vault errors
         href: application-gateway-key-vault-common-errors.md
+      - name: Disabled listeners
+        href: disabled-listeners.md
   - name: Proxy buffer configuration
     href: proxy-buffers.md
   - name: Custom error pages