k8s L7 traffic management

website/content/docs/k8s/connect/cluster-peering/usage/k8s-l7-traffic.mdx

@@ -0,0 +1,85 @@
+---
+layout: docs
+page_title: Manage L7 Traffic With Cluster Peering on Kubernetes
+description: >-
+  Combine service resolver configurations with splitter and router configurations to manage L7 traffic in Consul on Kubernetes deployments with cluster peering connections. Learn how to define dynamic traffic rules to target peers for redirects in k8s. 
+---
+
+# Manage L7 traffic with cluster peering on Kubernetes
+
+This usage topic describes how to configure the [`service-resolver` configuration entry](/docs/connect/config-entries/) to set up and manage L7 traffic between services that have an existing cluster peering connection in Consul on Kubernetes deployments.
+
+## Service resolvers for redirects and failover
+
+When you use cluster peering to connect datacenters through their admin partitions, you can use [dynamic traffic management](/consul/docs/connect/l7-traffic) to configure your service mesh so that services automatically forward traffic to services hosted on peer clusters.
+
+However, the `service-splitter` and `service-router` configuration entry kinds do not natively support directly targeting a service instance hosted on a peer. Before you can split or route traffic to a service on a peer, you must define the service hosted on the peer as an upstream service by configuring a failover in the `service-resolver` configuration entry. Then, you can set up a redirect in a second service resolver to interact with the peer service by name.
+
+For more information about formatting, updating, and managing configuration entries in Consul, refer to [How to use configuration entries](/consul/docs/agent/config-entries).
+
+## Configure dynamic traffic between peers
+
+To configure L7 traffic management behavior in deployments with cluster peering connections, complete the following steps in order:
+
+1. Define the peer cluster as a failover target in the service resolver configuration. Then apply the configuration.
+
+  The following example updates the [`service-resolver` configuration entry](/docs/connect/config-entries/) in `cluster-01` so that Consul redirects traffic intended for the `frontend` service to a backup instance in peer `cluster-02` when it detects multiple connection failures.
+
+  <CodeBlockConfig title="failover-resolver.yaml">
+
+  ```yaml
+  apiVersion: consul.hashicorp.com/v1alpha1
+  kind: ServiceResolver
+  metadata:
+    name: frontend
+  spec:
+    connectTimeout: 15s
+    failover:
+      '*':
+        targets:
+          - peer: 'cluster-02'
+            service: 'frontend'
+            namespace: 'default'
+  ```
+
+  </CodeBlockConfig>
+
+1. Define the desired behavior in `service-splitter` or `service-router` configuration entry. Then apply the configuration.
+
+  The following example splits traffic evenly between `frontend` and `frontend-peer` services by defining the desired behavior locally:
+
+  <CodeBlockConfig title="splitter.yaml">
+
+  ```yaml
+  apiVersion: consul.hashicorp.com/v1alpha1
+  kind: ServiceSplitter
+  metadata:
+    name: frontend
+  spec:
+    splits:
+      - weight: 50
+        ## defaults to service with same name as configuration entry ("frontend")
+      - weight: 50
+        service: frontend-peer
+  ```
+
+  </CodeBlockCOnfig>
+
+1. Create a second `service-resolver` configuration entry on the local cluster that resolves the name of the peer service you used when splitting or routing the traffic. Then apply the configuration.
+
+  The following example uses the name `frontend-peer` to define a redirect targeting the `frontend` service on the peer `cluster-02`:
+
+  <CodeBlockConfig title="peer-resolver.yaml">
+
+  ```yaml
+  apiVersion: consul.hashicorp.com/v1alpha1
+  kind: ServiceResolver
+  metadata:
+    name: frontend-peer
+  spec:
+    redirect:
+      peer: 'cluster-02'
+      service: 'frontend'
+  ```
+
+</CodeBlockConfig>