Move to dedicated page

Signed-off-by: Tom Kerkhove <[email protected]>

Author: tomkerkhove

articles/api-management/how-to-self-hosted-gateway-on-kubernetes-in-production.md

@@ -28,7 +28,7 @@ The Azure portal provides commands to create self-hosted gateway resources in th
 Consider [creating and deploying](https://www.kubernetesbyexample.com/) a self-hosted gateway into a separate namespace in production.
 
 ## Number of replicas
-The minimum number of replicas suitable for production is two.
+The minimum number of replicas suitable for production is three, preferably combined with [high-available scheduling of the instances](#high-availability).
 
 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.
 
@@ -48,40 +48,16 @@ It's impossible to reliably predict and recommend the amount of per-container CP
 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. This tag always references the most recent version of the self-hosted gateway container image.
 
-We provide a variety of container images for self-hosted gateways to meet your needs:
-- `2.0.0` - The most specific tag for a container image.
-  - *Use this image if you always want to run the same container image.*
-- `v2` - The latest stable version of the v2 container image. (Moving tag) 
-  - *Use this image if you always want to run our v2 container image with every new feature and patch.*
-- `v2-preview` - The latest preview version of the container image. (Moving tag)
-  - *Use this image if you always want to run our latest preview container image, but not recommended for production.*
-- `latest` - The latest stable version of the container image. (Moving tag)
-  - *Use this image to evaluate the self-hosted gateway, but not recommended for production.*
+Consider using a specific version tag in production to avoid unintentional upgrade to a newer version.
 
-You can find a full list of available tags [here](https://mcr.microsoft.com/v2/azure-api-management/gateway/tags/list).
+You can [download a full list of available tags](https://mcr.microsoft.com/v2/azure-api-management/gateway/tags/list).
 
-### Use of tags in our official deployment options
-
-Our deployment options in the Azure portal use the `v2` tag which allows customers to use the most recent version of the self-hosted gateway v2 container image with all feature updates and patches.
-
-> [!NOTE]
-> We provide the command and YAML snippets as reference, feel free to use a more specific tag if you wish to.
-
-When installing with our Helm chart, image tagging is optimized for you. The Helm chart's application version pins the gateway to a given version and does not rely on `latest`.
-
-Learn more on how to [install an API Management self-hosted gateway on Kubernetes with Helm](how-to-deploy-self-hosted-gateway-kubernetes-helm.md).
-
-### Risk of using moving tags
-
-Moving tags are tags that are potentially updated when a new version of the container image is released. This allows container users to receive updates to the container image without having to update their deployments.
-
-This means that you can potentially run different versions in parallel without noticing it, for example when you perform scaling actions once `v2` tag was updated.
-
-Example - `v2` tag was released with `2.0.0` container image, but when `2.1.0` will be released, the `v2` tag will be linked to the `2.1.0` image.
-
-> [!IMPORTANT]
-> Consider using a specific version tag in production to avoid unintentional upgrade to a newer version.
+> [!TIP]
+> When installing with Helm, image tagging is optimized for you. The Helm chart's application version pins the gateway to a given version and does not rely on `latest`.
+> 
+> Learn more on how to [install an API Management self-hosted gateway on Kubernetes with Helm](how-to-deploy-self-hosted-gateway-kubernetes-helm.md).
 
 ## DNS policy
 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.

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

@@ -49,6 +49,41 @@ The following functionality found in the managed gateways is **not available** i
 - Client certificate renegotiation. This means that for [client certificate authentication](api-management-howto-mutual-certificates-for-clients.md) to work, API consumers must present their certificates as part of the initial TLS handshake. To ensure this behavior, enable the Negotiate Client Certificate setting when configuring a self-hosted gateway custom hostname.
 - Built-in cache. Learn about using an [external Redis-compatible cache](api-management-howto-cache-external.md) in self-hosted gateways.
 
+### Container images
+
+We provide a variety of container images for self-hosted gateways to meet your needs:
+
+| Tag convention | Recommendation | Example  | Rolling tag  | Recommended for production |
+| ------------- | -------- | ------- | ------- | ------- |
+| `{major}.{minor}.{patch}` | Use this tag to always to run the same version of the gateway |`2.0.0` | ❌ |  ✔️ |
+| `v{major}` | Use this tag to always run a major version of the gateway with every new feature and patch. |`v2` | ✔️ |  ❌ |
+| `v{major}-preview` | Use this tag if you always want to run our latest preview container image. | `v2-preview` | ✔️ |  ❌ |
+| `latest` | Use this tag if you want to evaluate the self-hosted gateway. | `latest` | ✔️ |  ❌ |
+
+You can find a full list of available tags [here](https://mcr.microsoft.com/v2/azure-api-management/gateway/tags/list).
+
+#### Use of tags in our official deployment options
+
+Our deployment options in the Azure portal use the `v2` tag which allows customers to use the most recent version of the self-hosted gateway v2 container image with all feature updates and patches.
+
+> [!NOTE]
+> We provide the command and YAML snippets as reference, feel free to use a more specific tag if you wish to.
+
+When installing with our Helm chart, image tagging is optimized for you. The Helm chart's application version pins the gateway to a given version and does not rely on `latest`.
+
+Learn more on how to [install an API Management self-hosted gateway on Kubernetes with Helm](how-to-deploy-self-hosted-gateway-kubernetes-helm.md).
+
+#### Risk of using rolling tags
+
+Rolling tags are tags that are potentially updated when a new version of the container image is released. This allows container users to receive updates to the container image without having to update their deployments.
+
+This means that you can potentially run different versions in parallel without noticing it, for example when you perform scaling actions once `v2` tag was updated.
+
+Example - `v2` tag was released with `2.0.0` container image, but when `2.1.0` will be released, the `v2` tag will be linked to the `2.1.0` image.
+
+> [!IMPORTANT]
+> Consider using a specific version tag in production to avoid unintentional upgrade to a newer version.
+
 ## Connectivity to Azure
 
 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. A self-hosted gateway uses connectivity to Azure for: