docs(service-defaults): upstream overrides for peered services (#16122)

Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>

website/content/docs/connect/config-entries/service-defaults.mdx

@@ -421,6 +421,16 @@ represents a location outside the Consul cluster. They can be dialed directly wh
               description:
                 'The namespace of the upstream. This should not be set to the wildcard specifier `*`.',
             },
+            {
+              name: 'Peer',
+              type: 'string: ""',
+              description: 
+                `The name of the peer containing the upstream. Do not use a wildcard specifier ( \`*\`).<br><br>
+                    If the \`peer\` field is not set in any \`Overrides\` configuration, then Consul applies overrides to peered services with the same [\`name\`](/consul/docs/connect/config-entries/service-defaults#name). 
+                    This maintains backward compatibility with Consul 1.14.0. 
+                    If the \`peer\` field is specified in any override, then backward compatibility with Consul 1.14.0 is disabled. 
+                    As a result, each peered service must have a separate override configuration if desired.` ,
+            },
             {
               name: 'Protocol',
               type: 'string: ""',
@@ -433,6 +443,8 @@ represents a location outside the Consul cluster. They can be dialed directly wh
                     proxy upstream config will not fully enable some
                     [L7 features](/consul/docs/connect/l7-traffic).
                     It is supported here for backwards compatibility with Consul versions prior to 1.6.0.
+                    In addition, the \`protocol\` of a peered service cannot be overriden. Any value in 
+                    this field is ignored for peered services.
                   `,
             },
             {

website/content/docs/upgrading/upgrade-specific.mdx

@@ -87,6 +87,54 @@ In Consul v1.15 and higher:
 
    </CodeBlockConfig>
 
+#### `service-defaults` Overrides for Upstream Peered Services
+
+In Consul 1.14.x, `service-defaults` upstream [`overrides`](/consul/docs/connect/config-entries/service-defaults#overrides) apply to both local and peered services as long as the `name` field matches.
+Consul 1.15.0 is backward compatible with 1.14 if the [`peer`](/consul/docs/connect/config-entries/service-defaults#peer) is not set in any override.
+We recommend converting any upstream peer service overrides as a 1.15.x post-upgrade step.
+
+Before Consul v1.15:
+
+   <CodeBlockConfig>
+
+   ```hcl
+   Kind = "service-defaults"
+   Name = "<SERVICE_NAME>"
+   Protocol  = "http"
+   UpstreamConfig = {
+     Overrides = [
+       {
+          Name = foo      # Applies to local `foo` and any peered service `foo`
+       }
+     ]
+   }
+   ```
+
+   </CodeBlockConfig>
+
+In Consul v1.15 and higher:
+
+   <CodeBlockConfig>
+
+   ```hcl
+   Kind = "service-defaults"
+   Name = "<SERVICE_NAME>"
+   Protocol  = "http"
+   UpstreamConfig = {
+     Overrides = [
+       {
+          Name = foo  # Applies to local service `foo` 
+       },
+       {
+          Name = foo  # Applies to `foo` imported from peered cluster `bar`
+          Peer = bar
+       }
+     ]
+   }
+   ```
+
+   </CodeBlockConfig>
+
 ## Consul 1.14.x
 
 ### Service Mesh Compatibility