chore(policies): move all non targetRef policies in a subsection (kum…

…ahq#1592)

Also does correct cross-linking. Do not change url so that permalinks
still work.

Signed-off-by: Charly Molter <[email protected]>

app/_data/docs_nav_kuma_dev.yml

@@ -254,28 +254,10 @@ items:
     items:
       - text: Introduction
         url: /policies/introduction/
-      - text: General notes about Kuma policies
-        url: /policies/general-notes-about-kuma-policies/
       - text: Applying Policies
         url: /policies/applying-policies/
-      - text: How Kuma chooses the right policy to apply
-        url: /policies/how-kuma-chooses-the-right-policy-to-apply/
-        items:
-          - text: General rules
-            url: "/policies/how-kuma-chooses-the-right-policy-to-apply/#general-rules"
-          - text: Combine Policies to Avoid Overriding
-            url: "/policies/how-kuma-chooses-the-right-policy-to-apply/#combine-policies-to-avoid-overriding"
-          - text: Dataplane Policy
-            url: "/policies/how-kuma-chooses-the-right-policy-to-apply/#dataplane-policy"
-          - text: Connection policies
-            url: "/policies/how-kuma-chooses-the-right-policy-to-apply/#connection-policies"
-          - text: Outbound Connection Policy
-            url: "/policies/how-kuma-chooses-the-right-policy-to-apply/#outbound-connection-policy"
-          - text: Inbound Connection Policy
-            url: "/policies/how-kuma-chooses-the-right-policy-to-apply/#inbound-connection-policy"
       - text: Understanding TargetRef policies
         url: "/policies/targetref"
-
       - text: Protocol support in Kuma
         url: /policies/protocol-support-in-kuma/
         items:
@@ -296,128 +278,20 @@ items:
             url: "/policies/mutual-tls/#permissive-mtls"
           - text: Certificate Rotation
             url: "/policies/mutual-tls/#certificate-rotation"
-      - text: Traffic Permissions
-        url: /policies/traffic-permissions/
-        items:
-          - text: Usage
-            url: "/policies/traffic-permissions/#usage"
-          - text: Access to External Services
-            url: "/policies/traffic-permissions/#access-to-external-services"
-      - text: Traffic Route
-        url: /policies/traffic-route/
-        items:
-          - text: Usage
-            url: "/policies/traffic-route/#usage"
-      - text: Traffic Metrics
-        url: /policies/traffic-metrics/
-        items:
-          - text: Expose metrics from data plane proxies
-            url: "/policies/traffic-metrics/#expose-metrics-from-data-plane-proxies"
-          - text: Expose metrics from applications
-            url: "/policies/traffic-metrics/#expose-metrics-from-applications"
-          - text: Override Prometheus settings per data plane proxy
-            url: "/policies/traffic-metrics/#override-prometheus-settings-per-data-plane-proxy"
-          - text: Filter Envoy metrics
-            url: "/policies/traffic-metrics/#filter-envoy-metrics"
-          - text: Secure data plane proxy metrics
-            url: "/policies/traffic-metrics/#secure-data-plane-proxy-metrics"
-      - text: Traffic Trace
-        url: /policies/traffic-trace/
-        items:
-          - text: Add a tracing backend to the mesh
-            url: "/policies/traffic-trace/#add-a-tracing-backend-to-the-mesh"
-          - text: Add TrafficTrace resource
-            url: "/policies/traffic-trace/#add-traffictrace-resource"
-      - text: Traffic Log
-        url: /policies/traffic-log/
-        items:
-          - text: Add a logging backend
-            url: "/policies/traffic-log/#add-a-logging-backend"
-          - text: Add a TrafficLog resource
-            url: "/policies/traffic-log/#add-a-trafficlog-resource"
-          - text: Logging external services
-            url: "/policies/traffic-log/#logging-external-services"
-          - text: Builtin Gateway support
-            url: "/policies/traffic-log/#builtin-gateway-support"
-          - text: Access Log Format
-            url: "/policies/traffic-log/#access-log-format"
-      - text: Locality-aware Load Balancing
-        url: /policies/locality-aware/
-        items:
-          - text: Enabling locality-aware load balancing
-            url: "/policies/locality-aware/#enabling-locality-aware-load-balancing"
-      - text: Fault Injection
-        url: /policies/fault-injection/
-        items:
-          - text: Usage
-            url: "/policies/fault-injection/#usage"
-          - text: Matching
-            url: "/policies/fault-injection/#matching"
-      - text: Health Check
-        url: /policies/health-check/
-        items:
-          - text: Usage
-            url: "/policies/health-check/#usage"
-          - text: Matching
-            url: "/policies/health-check/#matching"
-      - text: Circuit Breaker
-        url: /policies/circuit-breaker/
-        items:
-          - text: Usage
-            url: "/policies/circuit-breaker/#usage"
-          - text: Matching
-            url: "/policies/circuit-breaker/#matching"
-          - text: Builtin Gateway support
-            url: "/policies/circuit-breaker/#builtin-gateway-support"
-          - text: Non-mesh traffic
-            url: "/policies/circuit-breaker/#non-mesh-traffic"
       - text: External Service
         url: /policies/external-services/
         items:
           - text: Usage
             url: "/policies/external-services/#usage"
           - text: Builtin Gateway support
             url: "/policies/external-services/#builtin-gateway-support"
-      - text: Retry
-        url: /policies/retry/
-        items:
-          - text: Usage
-            url: "/policies/retry/#usage"
-          - text: Matching
-            url: "/policies/retry/#matching"
-          - text: Builtin Gateway support
-            url: "/policies/retry/#builtin-gateway-support"
-      - text: Timeout
-        url: /policies/timeout/
-        items:
-          - text: Usage
-            url: "/policies/timeout/#usage"
-          - text: Configuration
-            url: "/policies/timeout/#configuration"
-          - text: Default general-purpose Timeout policy
-            url: "/policies/timeout/#default-general-purpose-timeout-policy"
-          - text: Matching
-            url: "/policies/timeout/#matching"
-          - text: Builtin Gateway support
-            url: "/policies/timeout/#builtin-gateway-support"
-          - text: Inbound timeouts
-            url: "/policies/timeout/#inbound-timeouts"
-          - text: Non-mesh traffic
-            url: "/policies/timeout/#non-mesh-traffic"
-      - text: Rate Limit
-        url: /policies/rate-limit/
-        items:
-          - text: Usage
-            url: "/policies/rate-limit/#usage"
-          - text: Matching destinations
-            url: "/policies/rate-limit/#matching-destinations"
-          - text: Builtin Gateway support
-            url: "/policies/rate-limit/#builtin-gateway-support"
-      - text: Virtual Outbound
-        url: /policies/virtual-outbound/
+      - text: Service Health Probes
+        url: /policies/service-health-probes/
         items:
-          - text: Examples
-            url: "/policies/virtual-outbound/#examples"
+          - text: Kubernetes
+            url: "/policies/service-health-probes/#kubernetes"
+          - text: Universal probes
+            url: "/policies/service-health-probes/#universal-probes"
       - text: MeshGateway
         url: /policies/meshgateway/
         items:
@@ -436,13 +310,6 @@ items:
             url: "/policies/meshgatewayroute/#reference"
       - text: MeshGatewayInstance
         url: /policies/meshgatewayinstance/
-      - text: Service Health Probes
-        url: /policies/service-health-probes/
-        items:
-          - text: Kubernetes
-            url: "/policies/service-health-probes/#kubernetes"
-          - text: Universal probes
-            url: "/policies/service-health-probes/#universal-probes"
       - text: MeshAccessLog
         url: /policies/meshaccesslog/
         items:
@@ -575,6 +442,39 @@ items:
             url: "/policies/meshloadbalancingstrategy/#configuration"
           - text: Examples
             url: "/policies/meshloadbalancingstrategy/#examples"
+      - title: Previous Policies
+        group: true
+        items:
+          - text: General notes about Kuma policies
+            url: /policies/general-notes-about-kuma-policies/
+          - text: How Kuma chooses the right policy to apply
+            url: /policies/how-kuma-chooses-the-right-policy-to-apply/
+          - text: Traffic Permissions
+            url: /policies/traffic-permissions/
+          - text: Traffic Route
+            url: /policies/traffic-route/
+          - text: Traffic Metrics
+            url: /policies/traffic-metrics/
+          - text: Traffic Trace
+            url: /policies/traffic-trace/
+          - text: Traffic Log
+            url: /policies/traffic-log/
+          - text: Locality-aware Load Balancing
+            url: /policies/locality-aware/
+          - text: Fault Injection
+            url: /policies/fault-injection/
+          - text: Health Check
+            url: /policies/health-check/
+          - text: Circuit Breaker
+            url: /policies/circuit-breaker/
+          - text: Retry
+            url: /policies/retry/
+          - text: Timeout
+            url: /policies/timeout/
+          - text: Rate Limit
+            url: /policies/rate-limit/
+          - text: Virtual Outbound
+            url: /policies/virtual-outbound/
   - title: Reference
     group: true
     items:

app/_src/policies/circuit-breaker.md

@@ -1,6 +1,11 @@
 ---
 title: Circuit Breaker
 ---
+{% if_version gte:2.6.x %}
+{% warning %}
+New to Kuma? You don't need this policy, check [`MeshCircuitBreaker`](/docs/{{ page.version }}/policies/meshcircuitbreaker) instead.
+{% endwarning %}
+{% endif_version %}
 
 {% tip %}
 Circuit Breaker is an outbound policy. Dataplanes whose configuration is modified are in the `sources` matcher.

app/_src/policies/fault-injection.md

@@ -1,6 +1,11 @@
 ---
 title: Fault Injection
 ---
+{% if_version gte:2.6.x %}
+{% warning %}
+New to Kuma? You need this policy, check [`MeshFaultInjection`](/docs/{{ page.version }}/policies/meshfaultinjection) instead.
+{% endwarning %}
+{% endif_version %}
 
 {% tip %}
 Fault Injection is an inbound policy. Dataplanes whose configuration is modified are in the `destinations` matcher.

app/_src/policies/general-notes-about-kuma-policies.md

@@ -1,11 +1,17 @@
 ---
 title: General notes about Kuma policies
 ---
-
+{% if_version gte:2.6.x %}
+{% warning %}
+New to Kuma? You don't need this, check [`TargetRef` policies](/docs/{{ page.version }}/policies/introduction) instead.
+{% endwarning %}
+{% endif_version %}
+{% if_version lte:2.5.x %}
 {% tip %}
 This only applies to source/destination policies.
 If you are unfamiliar with these, checkout [introduction to policies](/docs/{{ page.version }}/policies/introduction).
 {% endtip %}
+{% endif_version %}
 
 Policies applied to data plane proxies all follow the same basic structure:
 

app/_src/policies/health-check.md

@@ -1,6 +1,11 @@
 ---
 title: Health Check
 ---
+{% if_version gte:2.6.x %}
+{% warning %}
+New to Kuma? You don't need this policy, check [`MeshHealthCheck`](/docs/{{ page.version }}/policies/meshhealthcheck) instead.
+{% endwarning %}
+{% endif_version %}
 
 {% tip %}
 Health Check is an outbound policy. Dataplanes whose configuration is modified are in the `sources` matcher.

app/_src/policies/how-kuma-chooses-the-right-policy-to-apply.md

@@ -2,10 +2,17 @@
 title: How Kuma chooses the right policy to apply
 ---
 
+{% if_version gte:2.6.x %}
+{% warning %}
+New to Kuma? You don't need this, check [`TargetRef` policies](/docs/{{ page.version }}/policies/introduction) instead.
+{% endwarning %}
+{% endif_version %}
+{% if_version lte:2.5.x %}
 {% tip %}
 This only applies to source/destination policies. 
 If you are unfamiliar with these, checkout [introduction to policies](/docs/{{ page.version }}/policies/introduction).
 {% endtip %}
+{% endif_version %}
 
 At any single moment, there might be multiple policies (of the same type) that match a connection between `sources` and `destinations` `Dataplane`s.
 

app/_src/policies/introduction.md

@@ -23,6 +23,13 @@ The following table shows the equivalence between source/destination and `target
 | [ProxyTemplate](/docs/{{ page.version }}/policies/proxy-template)           | [MeshProxyPatch](/docs/{{ page.version }}/policies/meshproxypatch)                                                                                                                   |
 
 {% warning %}
+{% if_version lte:2.5.x %}
 `targetRef` policies are still beta and it is therefore not supported to mix source/destination and targetRef policies
 together.
+{% endif_version %}
+{% if_version gte:2.6.x %}
+If you are new to Kuma you should only need to use `targetRef` policies.
+If you already use source/destination policies you can keep using them. Future versions of Kuma will provide a migration path.
+You can mix targetRef and source/destination policies as long as they are of different types. For example: You can use `MeshTrafficPermission` with `FaultInjection` but you can't use `MeshTrafficPermission` with `TrafficPermission`.
+{% endif_version %}
 {% endwarning %}

app/_src/policies/locality-aware.md

@@ -4,7 +4,7 @@ title: Locality-aware Load Balancing
 
 {% if_version gte:2.5.x %}
 {% warning %}
-This mode of doing locality aware load balancing is being replaced by [MeshLoadBalancingStrategy](/docs/{{ page.version }}/policies/meshloadbalancingstrategy) which is more powerful and flexible.
+New to Kuma? You don't need this, Check the [`MeshLoadBalancingStrategy` policy](/docs/{{ page.version }}/policies/meshloadbalancingstrategy) instead.
 {% endwarning %}
 {% endif_version %}
 

app/_src/policies/meshgatewayroute.md

@@ -1,6 +1,11 @@
 ---
 title: MeshGatewayRoute
 ---
+{% if_version gte:2.6.x %}
+{% warning %}
+New to Kuma? Don't use this, check the [`MeshHTTPRoute` policy](/docs/{{ page.version }}/policies/meshhttproute) or [`MeshTCPRoute` policy](/docs/{{ page.version }}/policies/meshtcproute) instead.
+{% endwarning %}
+{% endif_version %}
 
 `MeshGatewayRoute` is a policy used to configure [{{site.mesh_product_name}}'s builtin gateway](/docs/{{ page.version }}/explore/gateway#builtin).
 It is used in combination with [`MeshGateway`](/docs/{{ page.version }}/policies/meshgateway).

app/_src/policies/meshloadbalancingstrategy.md

@@ -6,9 +6,8 @@ title: MeshLoadBalancingStrategy
 This policy uses new policy matching algorithm.
 {% endwarning %}
 
-This policy enables {{site.mesh_product_name}} to configure the load balancing strategy 
-for traffic between services in the mesh. Also, [localityAwareLoadBalancing](/docs/{{ page.version }}/policies/locality-aware) 
-flag is going to be replaced by the current policy and will be deprecated in the future releases.  
+This policy enables {{site.mesh_product_name}} to configure the load balancing strategy for traffic between services in the mesh.
+When using this policy, the [localityAwareLoadBalancing](/docs/{{ page.version }}/policies/locality-aware) flag is ignored.
 
 ## TargetRef support matrix
 

app/_src/policies/rate-limit.md

@@ -1,6 +1,11 @@
 ---
 title: Rate Limit
 ---
+{% if_version gte:2.6.x %}
+{% warning %}
+New to Kuma? Don't use this policy, check [`MeshRateLimit`](/docs/{{ page.version }}/policies/meshratelimit) instead.
+{% endwarning %}
+{% endif_version %}
 
 {% tip %}
 Rate Limit is an inbound policy. Dataplanes whose configuration is modified are in the `destinations` matcher.

app/_src/policies/retry.md

@@ -1,6 +1,11 @@
 ---
 title: Retry
 ---
+{% if_version gte:2.6.x %}
+{% warning %}
+New to Kuma? Don't use this policy, check [`MeshRetry`](/docs/{{ page.version }}/policies/meshretry) instead.
+{% endwarning %}
+{% endif_version %}
 
 {% tip %}
 Retry is an outbound policy. Dataplanes whose configuration is modified are in the `sources` matcher.

app/_src/policies/timeout.md

@@ -1,6 +1,11 @@
 ---
 title: Timeout
 ---
+{% if_version gte:2.6.x %}
+{% warning %}
+New to Kuma? Don't use this policy, check [`MeshTimeout`](/docs/{{ page.version }}/policies/meshtimeout) instead.
+{% endwarning %}
+{% endif_version %}
 
 {% tip %}
 Timeout is an outbound policy. Dataplanes whose configuration is modified are in the `sources` matcher.

app/_src/policies/traffic-log.md

@@ -1,6 +1,11 @@
 ---
 title: Traffic Log
 ---
+{% if_version gte:2.6.x %}
+{% warning %}
+New to Kuma? Don't use this, check the [`MeshAccessLog` policy](/docs/{{ page.version }}/policies/meshaccesslog) instead.
+{% endwarning %}
+{% endif_version %}
 
 With the Traffic Log policy you can easily set up access logs on every data plane in a mesh. 
 

app/_src/policies/traffic-metrics.md

@@ -1,6 +1,11 @@
 ---
 title: Traffic Metrics
 ---
+{% if_version gte:2.6.x %}
+{% warning %}
+New to Kuma? Don't use this, check the [`MeshMetric` policy](/docs/{{ page.version }}/policies/meshmetric) instead.
+{% endwarning %}
+{% endif_version %}
 
 {{site.mesh_product_name}} facilitates consistent traffic metrics across all data plane proxies in your mesh.