Improve VS retry documentation

networking/v1alpha3/virtual_service.proto

@@ -445,6 +445,15 @@ message HTTPRoute {
   google.protobuf.Duration timeout = 6;
 
   // Retry policy for HTTP requests.
+  //
+  // Note: the default cluster-wide retry policy, if not specified, is:
+  //
+  // ```yaml
+  // attempts: 2
+  // retryOn: "connect-failure,refused-stream,unavailable,cancelled,503"
+  // ```
+  //
+  // This can be customized in [`Mesh Config` `defaultHttpRetryPolicy`](https://istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/#MeshConfig).
   HTTPRetry retries = 7;
 
   // Fault injection policy to apply on HTTP traffic at the client side.
@@ -1271,7 +1280,6 @@ message StringMatch {
 //       perTryTimeout: 2s
 //       retryOn: gateway-error,connect-failure,refused-stream
 // ```
-//
 message HTTPRetry {
   // Number of retries to be allowed for a given request. The interval
   // between retries will be determined automatically (25ms+). When request
@@ -1289,9 +1297,15 @@ message HTTPRetry {
 
   // Specifies the conditions under which retry takes place.
   // One or more policies can be specified using a ‘,’ delimited list.
-  // If `retry_on` specifies a valid HTTP status, it will be added to retriable_status_codes retry policy.
   // See the [retry policies](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#x-envoy-retry-on)
   // and [gRPC retry policies](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#x-envoy-retry-grpc-on) for more details.
+  //
+  // In addition to the policies specified above, a list of HTTP status codes can be passed, such as `retryOn: "503,reset"`.
+  // Note these status codes refer to the actual responses received from the destination.
+  // For example, if a connection is reset, Istio will translate this to 503 for it's response.
+  // However, the destination did not return a 503 error, so this would not match `"503"` (it would, however, match `"reset"`).
+  //
+  // If not specified, this defaults to `connect-failure,refused-stream,unavailable,cancelled,503`.
   string retry_on = 3;
 
   // Flag to specify whether the retries should retry to other localities.