Merge pull request #113987 from ShawnJackson/how-to-deploy-self-hosted-gateway-kubernetes

Ja-Dunn · web-flow · commit 70f34c5554e0 · 2020-05-05T16:26:46.000-07:00
edit pass: how-to-deploy-self-hosted-gateway-kubernetes
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
@@ -1,6 +1,6 @@
 ---
-title: Deploy self-hosted gateway to Kubernetes | Microsoft Docs
-description: Learn how to deploy self-hosted gateway component of Azure API Management to Kubernetes
+title: Deploy a self-hosted gateway to Kubernetes | Microsoft Docs
+description: Learn how to deploy a self-hosted gateway component of Azure API Management to Kubernetes
 services: api-management
 author: vladvino
 manager: gwallace
@@ -10,104 +10,108 @@ ms.topic: article
 ms.author: apimpm
 ms.date: 04/23/2020
 ---
-# Deploy self-hosted gateway to Kubernetes
+# Deploy a self-hosted gateway to Kubernetes
 
-This article describes the steps for deploying self-hosted gateway component of Azure API Management to a Kubernetes cluster.
+This article describes the steps for deploying the self-hosted gateway component of Azure API Management to a Kubernetes cluster.
 
 ## Prerequisites
 
-- Complete the following quickstart: [Create an Azure API Management instance](get-started-create-service-instance.md)
+- Complete the following quickstart: [Create an Azure API Management instance](get-started-create-service-instance.md).
 - Create a Kubernetes cluster.
-> [!TIP]
-> [Single-node clusters](https://kubernetes.io/docs/setup/#learning-environment) work well for development and evaluation purposes. Use [Kubernetes Certified](https://kubernetes.io/partners/#conformance) multi-node clusters on-premises or in the cloud for production workloads.
+   > [!TIP]
+   > [Single-node clusters](https://kubernetes.io/docs/setup/#learning-environment) work well for development and evaluation purposes. Use [Kubernetes Certified](https://kubernetes.io/partners/#conformance) multi-node clusters on-premises or in the cloud for production workloads.
 - [Provision a self-hosted gateway resource in your API Management instance](api-management-howto-provision-self-hosted-gateway.md).
 
 ## Deploy to Kubernetes
 
-1. Select **Gateways** from under **Deployment and infrastructure**.
-2. Select the self-hosted gateway resource you intend to deploy.
+1. Select **Gateways** under **Deployment and infrastructure**.
+2. Select the self-hosted gateway resource that you want to deploy.
 3. Select **Deployment**.
-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.
-5. Select **Kubernetes** tab under **Deployment scripts**.
-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/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
-NAME             READY   UP-TO-DATE   AVAILABLE   AGE
-<gateway-name>   1/1     1            1           18s
-```
-11. Execute command shown bellow to check if the service was successfully created. Note that your service IPs and ports will be different.
-```console
-kubectl get services
-NAME             TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                      AGE
-<gateway-name>   LoadBalancer   10.99.236.168   <pending>     80:31620/TCP,443:30456/TCP   9m1s
-```
+4. An access token in the **Token** text box was autogenerated for you, based on the default **Expiry** and **Secret key** values. If needed, choose values in either or both controls to generate a new token.
+5. Select the **Kubernetes** tab under **Deployment scripts**.
+6. Select the **<gateway-name>.yml** file link and download the YAML file.
+7. Select the **copy** icon at the lower-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 that contains the access token generated in step 4. The second command applies the configuration file downloaded in step 6 to the Kubernetes cluster and expects the file to be in the current directory.
+9. Run 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 pods from the [container image](https://aka.ms/apim/sputnik/dhub) downloaded from the Microsoft Container Registry.
+10. Run the following command to check if the deployment succeeded. Note that it might take a little time for all the objects to be created and for the pods to initialize.
+    ```console
+    kubectl get deployments
+    NAME             READY   UP-TO-DATE   AVAILABLE   AGE
+    <gateway-name>   1/1     1            1           18s
+    ```
+11. Run the following command to check if the service was successfully created. Note that your service IPs and ports will be different.
+    ```console
+    kubectl get services
+    NAME             TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                      AGE
+    <gateway-name>   LoadBalancer   10.99.236.168   <pending>     80:31620/TCP,443:30456/TCP   9m1s
+    ```
 12. Go back to the Azure portal and select **Overview**.
-13. **Status** showing a green checkmark icon followed by the node count matching the number of replicas specified in the YAML file confirms that deployed self-hosted gateway pods are successfully communicating with the API Management service and have a regular "heartbeat".
+13. Confirm that **Status** shows a green check mark, followed by a node count that matches the number of replicas specified in the YAML file. This status means the deployed self-hosted gateway pods are successfully communicating with the API Management service and have a regular "heartbeat."
 
-![gateway status](media/how-to-deploy-self-hosted-gateway-kubernetes/status.png)
+    ![Gateway status](media/how-to-deploy-self-hosted-gateway-kubernetes/status.png)
 
 > [!TIP]
-> Execute <code>kubectl logs deployment/<gateway-name></code> command to view logs from a randomly selected pod if there are more than one.
-> Execute <code>kubectl logs -h</code> for a complete set of command options, e.g. how to view logs for a specific pod or container.
+> Run the <code>kubectl logs deployment/<gateway-name></code> command to view logs from a randomly selected pod if there's more than one.
+> Run <code>kubectl logs -h</code> for a complete set of command options, such as how to view logs for a specific pod or container.
 
 ## Production deployment considerations
 
 ### Access token
-Without a valid access token self-hosted gateway is unable to access and download configuration from configuration data endpoint of the associated API Management service. 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. When automating token refresh use this management API [operation](https://docs.microsoft.com/rest/api/apimanagement/2019-12-01/gateway/generatetoken) to generated a new token. Follow this [link](https://kubernetes.io/docs/concepts/configuration/secret) for information on managing Kubernetes secrets.
+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. 
+
+When you're automating token refresh, use [this management API operation](https://docs.microsoft.com/rest/api/apimanagement/2019-12-01/gateway/generatetoken) to generate a new token. For information on managing Kubernetes secrets, see the [Kubernetes website](https://kubernetes.io/docs/concepts/configuration/secret).
 
 ### Namespace
-Kubernetes [namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) help with dividing a single cluster among multiple teams, projects, or applications. Namespaces provide a scope for resources and names and can be associated with a resource quota and access control policies.
-Commands provided in the Azure portal create self-hosted gateway resources in the **default** namespace which is automatically created, exists in every cluster, and can't be deleted.
-Consider [creating and deploying](https://kubernetesbyexample.com/ns/) self-hosted gateway into a separate namespace in production.
+Kubernetes [namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) help with dividing a single cluster among multiple teams, projects, or applications. Namespaces provide a scope for resources and names. They can be associated with a resource quota and access control policies.
+
+The Azure portal provides commands to create self-hosted gateway resources in the **default** namespace. This namespace is automatically created, exists in every cluster, and can't be deleted.
+Consider [creating and deploying](https://kubernetesbyexample.com/ns/) a self-hosted gateway into a separate namespace in production.
 
 ### Number of replicas
-Minimal number of replicas suitable in production is two.
+The minimum number of replicas suitable for production is two.
 
-By default, self-hosted gateway is deployed with a **RollingUpdate** deployment [strategy](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy). Review the default values and consider explicitly setting [**maxUnavailable**](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#max-unavailable) and [**maxSurge**](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#max-surge) fields, especially when using a high replica count.
+By default, a self-hosted gateway is deployed with a **RollingUpdate** deployment [strategy](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy). Review the default values and consider explicitly setting the [maxUnavailable](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#max-unavailable) and [maxSurge](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#max-surge) fields, especially when you're using a high replica count.
 
 ### Container resources
 By default, the YAML file provided in the Azure portal doesn't specify container resource requests.
 
-It's impossible to reliably predict and recommend the amount of per-container CPU and memory resources and the number of replicas required for supporting a specific workload due to many factors at play, e.g.:
+It's impossible to reliably predict and recommend the amount of per-container CPU and memory resources and the number of replicas required for supporting a specific workload. Many factors are at play, such as:
 
-- Specific hardware the cluster is running on
-- Presence and type of virtualization
-- Number and rate of concurrent client connections
-- Request rate
-- Kind and number of configured policies
-- Payload size and if payloads are buffered or streamed
-- Backend service latency
+- Specific hardware that the cluster is running on.
+- Presence and type of virtualization.
+- Number and rate of concurrent client connections.
+- Request rate.
+- Kind and number of configured policies.
+- Payload size and whether payloads are buffered or streamed.
+- Backend service latency.
 
-We recommend setting resource request to 2 cores and 2 GiB as a starting point, performing a load test and scaling up/out or down/in based the results.
+We recommend setting resource requests to two cores and 2 GiB as a starting point. Perform a load test and scale up/out or down/in based on the results.
 
 ### Container image tag
-The YAML file provided in the Azure portal uses the **latest** tag which always references the most recent version of the self-hosted gateway container image.
+The YAML file provided in the Azure portal uses the **latest** tag. This tag always references the most recent version of the self-hosted gateway container image.
 
 Consider using a specific version tag in production to avoid unintentional upgrade to a newer version.
 
-Follow this [link](https://mcr.microsoft.com/v2/azure-api-management/gateway/tags/list) to see the full list of available tags.
+You can [download a full list of available tags](https://mcr.microsoft.com/v2/azure-api-management/gateway/tags/list).
 
 ### DNS policy
-DNS name resolution plays a critical role in self-hosted gateway's ability to connect to dependencies in Azure and dispatch API calls to backend services.
+DNS name resolution plays a critical role in a self-hosted gateway's ability to connect to dependencies in Azure and dispatch API calls to backend services.
 
-The YAML file provided in the Azure portal applies the default [**ClusterFirst**](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-s-dns-policy) policy which causes name resolution requests not resolved by the cluster DNS to be forwarded to the upstream DNS server inherited from the node.
+The YAML file provided in the Azure portal applies the default [ClusterFirst](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-s-dns-policy) policy. This policy causes name resolution requests not resolved by the cluster DNS to be forwarded to the upstream DNS server that's inherited from the node.
 
-Follow this [link](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service) to learn about name resolution in Kubernetes and consider customizing [DNS policy](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-s-dns-policy) or D[NS configuration](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-s-dns-config) as appropriate for your setup.
+To learn about name resolution in Kubernetes, see the [Kubernetes website](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service). Consider customizing [DNS policy](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-s-dns-policy) or [DNS configuration](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-s-dns-config) as appropriate for your setup.
 
 ### Configuration backup
-Follow this [link](self-hosted-gateway-overview.md#connectivity-to-azure) to learn about self-hosted gateway behavior in the presence of a temporary Azure connectivity outage.
-Configure local storage volume for the self-hosted gateway container, so it can persist a backup copy of the latest downloaded configuration and, if connectivity is down, use it upon restart. The volume mount path must be  <code>/apim/config</code>. See an example [here](https://github.com/Azure/api-management-self-hosted-gateway/blob/master/examples/self-hosted-gateway-with-configuration-backup.yaml).
-To learn about storage in Kubernetes follow this [link](https://kubernetes.io/docs/concepts/storage/volumes/).
+To learn about self-hosted gateway behavior in the presence of a temporary Azure connectivity outage, see [Self-hosted gateway overview](self-hosted-gateway-overview.md#connectivity-to-azure).
+
+Configure a local storage volume for the self-hosted gateway container, so it can persist a backup copy of the latest downloaded configuration. If connectivity is down, the storage volume can use the backup copy upon restart. The volume mount path must be <code>/apim/config</code>. See an example on [GitHub](https://github.com/Azure/api-management-self-hosted-gateway/blob/master/examples/self-hosted-gateway-with-configuration-backup.yaml).
+To learn about storage in Kubernetes, see the [Kubernetes website](https://kubernetes.io/docs/concepts/storage/volumes/).
 
 ### Local logs and metrics
-Self-hosted gateway sends telemetry to [Azure Monitor](api-management-howto-use-azure-monitor.md) and [Azure Application Insights](api-management-howto-app-insights.md) per configuration settings in the associated API Management service.
+The self-hosted gateway sends telemetry to [Azure Monitor](api-management-howto-use-azure-monitor.md) and [Azure Application Insights](api-management-howto-app-insights.md) according to configuration settings in the associated API Management service.
 When [connectivity to Azure](self-hosted-gateway-overview.md#connectivity-to-azure) is temporarily lost, the flow of telemetry to Azure is interrupted and the data is lost for the duration of the outage.
-Consider [setting up local monitoring](how-to-configure-local-metrics-logs.md) to ensure ability to observe the API traffic and prevent telemetry loss during Azure connectivity outages.
+Consider [setting up local monitoring](how-to-configure-local-metrics-logs.md) to ensure the ability to observe API traffic and prevent telemetry loss during Azure connectivity outages.
 
 ## Next steps
 
-* To learn more about the self-hosted gateway, see [Azure API Management self-hosted gateway overview](self-hosted-gateway-overview.md)
+* To learn more about the self-hosted gateway, see [Self-hosted gateway overview](self-hosted-gateway-overview.md).
