Edits and updates related to self-hosted gateway GA

Author: vladvino

articles/api-management/api-management-howto-cache-external.md

@@ -9,24 +9,23 @@ editor: ''
 
 ms.assetid: 740f6a27-8323-474d-ade2-828ae0c75e7a
 ms.service: api-management
-ms.workload: mobile
-ms.tgt_pltfrm: na
 ms.topic: conceptual
-ms.date: 05/15/2019
+ms.date: 04/26/2020
 ms.author: apimpm
 
 ---
 
-# Use an external Azure Cache for Redis in Azure API Management
+# Use an external Redis-compatible cache in Azure API Management
 
-In addition to utilizing the built-in cache, Azure API Management also allows for caching responses in an external Azure Cache for Redis.
+In addition to utilizing the built-in cache, Azure API Management allows for caching responses in an external Redis-compatible cache, e.g. Azure Cache for Redis.
 
-Using an external cache allows to overcome a few limitations of the built-in cache. It is especially beneficial if you would like to:
+Using an external cache allows to overcome a few limitations of the built-in cache:
 
 * Avoid having your cache periodically cleared during API Management updates
 * Have more control over your cache configuration
 * Cache more data than your API Management tier allows to
 * Use caching with the Consumption tier of API Management
+* Enable caching in the [API Management self-hosted gateways](self-hosted-gateway-overview.md)
 
 For more detailed information about caching, see [API Management caching policies](api-management-caching-policies.md) and  [Custom caching in Azure API Management](api-management-sample-cache-by-key.md).
 
@@ -50,14 +49,18 @@ This section explains how to create an Azure Cache for Redis in Azure. If you al
 
 [!INCLUDE [redis-cache-create](../../includes/redis-cache-create.md)]
 
+## <a name="create-cache"> </a> Deploy Redis cache to Kubernetes
+
+For caching, self-hosted gateways rely exclusively on external caches. For caching to be effective self-hosted gateways and the cache they rely on must be located close to each other to minimize lookup and store latencies. Deploying a Redis cache into the same Kubernetes cluster or in a separate cluster nearby are the best options. Follow this [link](https://github.com/kubernetes/examples/tree/master/guestbook) to learn how to deploy Redis cache to a Kubernetes cluster.
+
 ## <a name="add-external-cache"> </a>Add an external cache
 
 Follow the steps below to add an external Azure Cache for Redis in Azure API Management.
 
 ![Bring your own cache to APIM](media/api-management-howto-cache-external/add-external-cache.png)
 
 > [!NOTE]
-> The **Use from** setting specifies which API Management regional deployment will communicate with the configured cache in case of a multi-regional configuration of API Management. The caches specified as **Default** will be overridden by caches with a regional value.
+> The **Use from** setting specifies an Azure region or a self-hosted gateway location that will use the configured cache. The caches configured as **Default** will be overridden by caches with a specific matching region or location value.
 >
 > For example, if API Management is hosted in the East US, Southeast Asia and West Europe regions and there are two caches configured, one for **Default** and one for **Southeast Asia**, API Management in **Southeast Asia** will use its own cache, while the other two regions will use the **Default** cache entry.
 
@@ -80,6 +83,16 @@ Follow the steps below to add an external Azure Cache for Redis in Azure API Man
 6. Provide your Azure Cache for Redis connection string in the **Connection string** field.
 7. Click **Save**.
 
+### Add a Redis cache to a self-hosted gateway
+
+1. Browse to your API Management instance in the Azure portal.
+2. Select the **External cache** tab from the menu on the left.
+3. Click the **+ Add** button.
+4. Select **Custom** in the **Cache instance** dropdown field.
+5. Specify the desired self-hosted gateway location or **Default** in the **Use from** dropdown field.
+6. Provide your Redis cache connection string in the **Connection string** field.
+7. Click **Save**.
+
 ## Use the external cache
 
 Once the external cache is configured in Azure API Management, it can be used through caching policies. See [Add caching to improve performance in Azure API Management](api-management-howto-cache.md) for detailed steps.

articles/api-management/api-management-howto-deploy-self-hosted-gateway-to-docker.md

@@ -8,10 +8,8 @@ manager: gwallace
 editor: ''
 
 ms.service: api-management
-ms.workload: mobile
-ms.tgt_pltfrm: na
 ms.topic: article
-ms.date: 03/31/2020
+ms.date: 04/26/2020
 ms.author: apimpm
 
 ---
@@ -20,6 +18,9 @@ ms.author: apimpm
 
 This article provides the steps for deploying self-hosted Azure API Management gateway into a Docker environment.
 
+> [!NOTE]
+> Hosting self-hosted gateway in Docker is best suited for evaluation and development use cases. Kubernetes is recommended for production use. See [this](api-management-howto-deploy-self-hosted-gateway-to-k8s.md) document to learn how to deploy self-hosted gateway to Kubernetes.
+
 ## Prerequisites
 
 - Complete the following quickstart: [Create an Azure API Management instance](get-started-create-service-instance.md)
@@ -31,25 +32,25 @@ This article provides the steps for deploying self-hosted Azure API Management g
 
 ## Deploy the self-hosted gateway to Docker
 
-1. Select **Gateways** from under **Settings**.
+1. Select **Gateways** from under **Deployment and infrastructure**.
 2. Select the gateway resource you intend to deploy.
 3. Select **Deployment**.
-4. Note that a new token in the **Token** text box was autogenerated for you using the default **Expiry** and **Secret Key** values. Adjust either or both if desired and select **Generate** to create a new token.
+4. Note that an access token in the **Token** text box was autogenerated for you using the default **Expiry** and **Secret key** values. If needed, pick desired values in either or both controls to generate a new token.
 4. Make sure **Docker** is selected under **Deployment scripts**.
 5. Select **env.conf** file link next to the **Environment** to download the file.
-6. Select **copy** icon located at the right end of the **Run** text box to save the Docker command to clipboard.
-7. Paste the command to the terminal (or command) window. Adjust the port mappings and container name as needed. Note that the command expects the downloaded environment file to be present in the current directory.
+6. Select **copy** icon located at the right end of the **Run** text box to copy the Docker command to clipboard.
+7. Paste the command to the terminal (or command) window. Adjust the port mappings and container name as needed. Note that the command assumes that downloaded environment file is present in the current directory.
 ```
     docker run -d -p 80:8080 -p 443:8081 --name <gateway-name> --env-file env.conf mcr.microsoft.com/azure-api-management/gateway:<tag>
 ```
-8. Execute the command. The command instructs your Docker environment to run the container, using self-hosted gateway's image downloaded from the Microsoft Container Registry, and to map the container's HTTP (8080) and HTTPS (8081) ports to ports 80 and 443 on the host.
-9. Run the below command to check the gateway pod is running:
+8. Execute the command. The command instructs your Docker environment to run the container using [container image](https://aka.ms/apim/sputnik/dhub) downloaded from the Microsoft Container Registry, and to map the container's HTTP (8080) and HTTPS (8081) ports to ports 80 and 443 on the host.
+9. Run the below command to check if the gateway container is running:
 ```console
 docker ps
 CONTAINER ID        IMAGE                                                 COMMAND                  CREATED             STATUS              PORTS                                         NAMES
-895ef0ecf13b        mcr.microsoft.com/azure-api-management/gateway:beta   "/bin/sh -c 'dotnet …"   5 seconds ago       Up 3 seconds        0.0.0.0:80->8080/tcp, 0.0.0.0:443->8081/tcp   my-gateway
+895ef0ecf13b        mcr.microsoft.com/azure-api-management/gateway:latest   "/bin/sh -c 'dotnet …"   5 seconds ago       Up 3 seconds        0.0.0.0:80->8080/tcp, 0.0.0.0:443->8081/tcp   my-gateway
 ```
-10. Go back to Azure portal and confirm that gateway node you just deployed is reporting healthy status.
+10. Go back to Azure portal, click on **Overview** and confirm that self-hosted gateway container you just deployed is reporting a healthy status.
 
 ![gateway status](media/api-management-howto-deploy-self-hosted-gateway-to-docker/status.png)
 

articles/api-management/api-management-howto-deploy-self-hosted-gateway-to-k8s.md

@@ -32,7 +32,7 @@ This article describes the steps for deploying self-hosted gateway to a Kubernet
 6. Click on the **<gateway-name>.yml** file link and download the YAML file.
 7. Select **copy** icon located at the bottom right corner of the **Deploy** text box to save the `kubectl` commands to the clipboard.
 8. Paste commands to the terminal (or command) window. The first command creates a Kubernetes secret containing access token generated in step 4. Second command applies the configuration file downloaded in step 6 to the Kubernetes cluster and expects the the file to be present in the current directory.
-9. Execute the commands to create the necessary Kubernetes objects in the [default namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) and start self-hosted gateway pod(s) from [container image](https://aka.ms/apim/sputnik/repo) downloaded from the Microsoft Container Registry.
+9. Execute the commands to create the necessary Kubernetes objects in the [default namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) and start self-hosted gateway pod(s) from [container image](https://aka.ms/apim/sputnik/dhub) downloaded from the Microsoft Container Registry.
 10. Execute command shown bellow to check if the deployment succeeded . Note that it might take a little time for all the objects to be created and for pod(s) to initialize.
 ```console
 kubectl get deployments

articles/api-management/self-hosted-gateway-overview.md

@@ -1,23 +1,21 @@
 ---
 title: Azure API Management self-hosted gateway overview | Microsoft Docs
-description: Learn how Azure API Management self-hosted gateway helps organizations manage APIs in the hybrid and multicloud environments.
+description: Learn how Azure API Management self-hosted gateway helps organizations manage APIs in hybrid and multicloud environments.
 services: api-management
 documentationcenter: ''
 author: vlvinogr
 manager: gwallace
 editor: ''
 
 ms.service: api-management
-ms.workload: mobile
-ms.tgt_pltfrm: na
 ms.topic: article
-ms.date: 04/24/2020
+ms.date: 04/26/2020
 ms.author: apimpm
 ---
 
-# Self-hosted API Management gateway overview
+# API Management self-hosted gateway overview
 
-This article explains how self-hosted gateway feature enables hybrid and multi-cloud API management, presents its high-level architecture, and highlights its fundamental capabilities.
+This article explains how self-hosted gateway feature enables hybrid and multi-cloud API management, presents its high-level architecture, and highlights its capabilities.
 
 ## Hybrid and multi-cloud API management
 
@@ -35,20 +33,26 @@ By default, all these components are deployed in Azure, causing all API traffic
 
 ![API traffic flow without self-hosted gateways](media/self-hosted-gateway-overview/without-gateways.png)
 
-Deploying self-hosted gateways into the same environments as backend API implementations and adding them to the API Management service allows API traffic to flow directly to the backend APIs, which improves latency, optimizes data transfer costs, and enables compliance while retaining the benefits of having a single point of management and discovery of all APIs within the organization regardless of where their implementations are hosted.
+Deploying self-hosted gateways into the same environments where the backend API implementations are hosted allows API traffic to flow directly to the backend APIs, which improves latency, optimizes data transfer costs, and enables compliance while retaining the benefits of having a single point of management, observanility, and discovery of all APIs within the organization regardless of where their implementations are hosted.
 
 ![API traffic flow with self-hosted gateways](media/self-hosted-gateway-overview/with-gateways.png)
 
 ## Packaging and features
 
-The self-hosted gateway is a containerized, functionally-equivalent version of the managed gateway deployed to Azure as part of every API Management service. The self-hosted gateway is available as a Linux-based Docker container from the Microsoft Container Registry. It can be deployed to Docker, Kubernetes, or any other container orchestration solution running on a desktop, server cluster, or cloud infrastructure.
+The self-hosted gateway is a containerized, functionally-equivalent version of the managed gateway deployed to Azure as part of every API Management service. The self-hosted gateway is available as a Linux-based Docker [container](https://aka.ms/apim/sputnik/dhub) from the Microsoft Container 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.
 
-> [!IMPORTANT]
-> Some functionality available in the managed gateway is not yet available in preview. Most notably: Log to Event Hub policy, Service Fabric integration, downstream HTTP/2. There is no plan to make a built-in cache available in the self-hosted gateway.
+The following functionality found in the managed gateways is **not available** in the self-hosted gateways:
+
+- Upstream (backend side) TLS version and cipher management
+- Validation of server and client certificates using CA root certificates uploaded to API Management service. To add support for custom CA, add a layer to the self-hosted gateway container image that installs the CA's root certificate.
+- Integration with the [Service Fabric](../service-fabric/service-fabric-api-management-overview.md)
+- TLS session resumption
+- Client certificate renegotiation. Therefore, when using client certificate authentication, clients must be required to present their certificates as part of the TLS handshake. To accomplish that, enable the negotiate client certificate setting when configuring a self-hosted gateway custom hostname.
+- Built-in cache. See this [document](api-management-howto-cache-external.md) to learn about using external cache in self-hosted gateways.
 
 ## Connectivity to Azure
 
-The self-hosted gateway requires outbound TCP/IP connectivity to Azure on port 443. Each self-hosted gateway has to be associated with a single API Management service and is configured via its management plane. Self-hosted gateway uses connectivity to Azure for:
+Self-hosted gateways require outbound TCP/IP connectivity to Azure on port 443. Each self-hosted gateway must be associated with a single API Management service and is configured via its management plane. Self-hosted gateway uses connectivity to Azure for:
 
 -   Reporting its status by sending heartbeat messages every minute
 -   Regularly checking for (every 10 seconds) and applying configuration updates whenever they are available
@@ -57,17 +61,17 @@ The self-hosted gateway requires outbound TCP/IP connectivity to Azure on port 4
 
 When connectivity to Azure is lost, self-hosted gateway will be unable to receive configuration updates, report its status, or upload telemetry.
 
-The self-hosted gateway is designed to "fail static" and can survive the temporary loss of connectivity to Azure. It can be deployed with or without local configuration backup turned on. In the former case, self-hosted gateways will regularly save a backup copy of configuration on a persistent volume attached to the container or pod.
+The self-hosted gateway is designed to "fail static" and can survive temporary loss of connectivity to Azure. It can be deployed with or without local configuration backup. In the former case, self-hosted gateways will regularly save a backup copy of the latest downloaded configuration on a persistent volume attached to its container or pod.
 
 When configuration backup is turned off and connectivity to Azure is interrupted:
 
--   Self-hosted gateways that are running will continue to function using an in-memory copy of the configuration
+-   Running self-hosted gateways will continue to function using an in-memory copy of the configuration
 -   Stopped self-hosted gateways will not be able to start
 
 When configuration backup is turned on and connectivity to Azure is interrupted:
 
--   Self-hosted gateways that are running will continue to function using an in-memory copy of the configuration
--   Stopped self-hosted gateways will start using a backup copy of the configuration
+-   Running self-hosted gateways will continue to function using an in-memory copy of the configuration
+-   Stopped self-hosted gateways will be able to start using a backup copy of the configuration
 
 When connectivity is restored, each self-hosted gateway affected by the outage will automatically reconnect with its associated API Management service and download all configuration updates that occurred while the gateway was "offline".