Merge pull request #190441 from tomkerkhove/image-tagging

docs: Provide overview of tagging strategy for API Management's self-hosted gateway

Author: LJSpiller

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: