docs: Update v2 K8s docs to use virtual port references

Now that service virtual port references are supported in xRoutes and config, - Call out both formats accepted for service port references - Update K8s examples to use virtual ports (most likely use case) backport of commit 1a732b0
hashicorp · Feb 26, 2024 · 50a6876 · 50a6876
1 parent 1cc9ffd
commit 50a6876
Show file tree

Hide file tree

Showing 4 changed files with 72 additions and 111 deletions.
diff --git a/website/content/docs/k8s/multiport/reference/grpcroute.mdx b/website/content/docs/k8s/multiport/reference/grpcroute.mdx
@@ -93,7 +93,7 @@ metadata:
   namespace: <namespace>
 spec:
   parentRefs:
-    port: <portNameRoutedFrom>
+    port: <portRoutedFrom>
     - ref:
       name: <nameRoutedFrom>
       type: 
@@ -104,7 +104,7 @@ spec:
     - backendRefs:
       - backendRef:
         datacenter: <datacenterRoutedTo>
-        port: "<portNameRoutedTo>"
+        port: "<portRoutedTo>"
         ref:
           name: <nameRoutedTo>
           type:
@@ -230,7 +230,9 @@ Specifies the services and other resources to attach the route to. You can only
 
 ### `spec.parentRefs.port`
 
-Specifies the name of the port that the configuration applies to.
+Specifies the port for the Consul service that the configuration applies to. This parameter can be either a virtual port number, such as a Kubernetes service port, or a non-numeric target port value representing a named workload port.
+
+If you are not targeting a virtual port, specify the workload port name directly.
 
 #### Values
 
@@ -312,7 +314,9 @@ Specifies the name of the Consul datacenter that registered the Service backend
 
 ### `spec.rules.backendRefs.backendRef.port`
 
-Specifies the name of the port for the Consul service that the configuration routes traffic to.
+Specifies the port for the Consul service that the configuration routes traffic to. This parameter can be either a virtual port number, such as a Kubernetes service port, or a non-numeric target port value representing a named workload port.
+
+If you are not targeting a virtual port, specify the workload port name directly.
 
 #### Values
 
@@ -701,8 +705,8 @@ spec:
           groupVersion: v2beta1
           kind: Service
         name: api
-      # The configuration targets the workload port, not the service port.
-      port: "api-workload"
+      # The virtual port number for the "api-workload" target port.
+      port: "80"
   rules:
     - backendRefs:
       - backendRef:
@@ -712,8 +716,8 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          # The configuration targets the workload port, not the service port.
-          port: "api-workload"
+          # The virtual port number for the "api-workload" target port.
+          port: "80"
         weight: 50
       - backendRef:
           ref: 
@@ -722,8 +726,8 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          # The configuration targets the workload port, not the service port.
-          port: "admin-workload"
+          # The virtual port number for the "admin-workload" target port.
+          port: "90"
         weight: 50
 ```
 
@@ -750,8 +754,8 @@ spec:
           groupVersion: v2beta1
           kind: Service
         name: api
-      # The configuration targets the workload port, not the service port.
-      port: "api-workload"
+      # The virtual port number for the "api-workload" target port.
+      port: "80"
   rules:
     - matches:
       - headers:
@@ -775,8 +779,8 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          # The configuration targets the workload port, not the service port.
-          port: "api-workload"
+          # The virtual port number for the "api-workload" target port.
+          port: "80"
     - matches:
       - headers:
           - type: "HEADER_MATCH_TYPE_EXACT"
@@ -799,6 +803,6 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api-admin
-          # The configuration targets the workload port, not the service port.
-          port: "admin-workload"
+          # The virtual port number for the "admin-workload" target port.
+          port: "90"
 ```
diff --git a/website/content/docs/k8s/multiport/reference/httproute.mdx b/website/content/docs/k8s/multiport/reference/httproute.mdx
@@ -97,7 +97,7 @@ metadata:
   namespace: <namespace>
 spec:
   parentRefs:
-    port: <portNameRoutedFrom>
+    port: <portRoutedFrom>
     - ref:
       name: <nameRoutedFrom>
       type: 
@@ -108,7 +108,7 @@ spec:
     - backendRefs:
       - backendRef:
         datacenter: <datacenterRoutedTo>
-        port: <portNameRoutedTo>
+        port: <portRoutedTo>
         ref:
           name: <nameRoutedTo>
           type:
@@ -238,7 +238,9 @@ Specifies the services and other resources to attach the route to. You can only
 
 ### `spec.parentRefs.port`
 
-Specifies the name of the port that the configuration applies to.
+Specifies the port for the Consul service that the configuration applies to. This parameter can be either a virtual port number, such as a Kubernetes service port, or a non-numeric target port value representing a named workload port.
+
+If you are not targeting a virtual port, specify the workload port name directly.
 
 #### Values
 
@@ -320,7 +322,9 @@ Specifies the name of the Consul datacenter that registered the Service backend
 
 ### `spec.rules.backendRefs.backendRef.port`
 
-Specifies the name of the port for the Consul service that the configuration routes traffic to.
+Specifies the name of the port for the Consul service that the configuration routes traffic to. This parameter can be either a virtual port number, such as a Kubernetes service port, or a non-numeric target port value representing a named workload port.
+
+If you are not targeting a virtual port, specify the workload port name directly.
 
 #### Values
 
@@ -754,8 +758,8 @@ spec:
           groupVersion: v2beta1
           kind: Service
         name: api
-      # The configuration targets the workload port, not the service port.
-      port: "api"
+      # The virtual port number for the "api-workload" target port.
+      port: "80"
   rules:
     - backendRefs:
       - backendRef:
@@ -765,8 +769,8 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          # The configuration targets the workload port, not the service port.
-          port: "api"
+          # The virtual port number for the "api-workload" target port.
+          port: "80"
         weight: 50
       - backendRef:
           ref: 
@@ -775,8 +779,8 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          # The configuration targets the workload port, not the service port.
-          port: "admin"
+          # The virtual port number for the "admin-workload" target port.
+          port: "90"
         weight: 50
 ```
 
@@ -803,8 +807,8 @@ spec:
           groupVersion: v2beta1
           kind: Service
         name: api
-      # The configuration targets the workload port, not the service port.
-      port: "api-workload"
+      # The virtual port number for the "api-workload" target port.
+      port: "80"
   rules:
     - matches:
       - headers:
@@ -828,8 +832,8 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          # The configuration targets the workload port, not the service port.
-          port: "api-workload"
+          # The virtual port number for the "api-workload" target port.
+          port: "80"
     - matches:
       - headers:
           - type: "HEADER_MATCH_TYPE_EXACT"
@@ -852,8 +856,8 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api-admin
-          # The configuration targets the workload port, not the service port.
-          port: "admin-workload"
+          # The virtual port number for the "admin-workload" target port.
+          port: "90"
 ```
 
 ### Route traffic by matching header and query parameter
@@ -877,8 +881,8 @@ spec:
           groupVersion: v2beta1
           kind: Service
         name: api
-      # The configuration targets the workload port, not the service port.
-      port: "api-workload"
+      # The virtual port number for the "api-workload" target port.
+      port: "80"
   rules:
     - matches:
       - headers:
@@ -897,8 +901,8 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          # The configuration targets the workload port, not the service port.
-          port: "api-workload"
+          # The virtual port number for the "api-workload" target port.
+          port: "80"
     - matches:
       - headers:
           - type: "HEADER_MATCH_TYPE_EXACT"
@@ -916,6 +920,6 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api-admin
-          # The configuration targets the workload port, not the service port.
-          port: "admin-workload"
+          # The virtual port number for the "admin-workload" target port.
+          port: "90"
 ```
diff --git a/website/content/docs/k8s/multiport/reference/tcproute.mdx b/website/content/docs/k8s/multiport/reference/tcproute.mdx
@@ -60,7 +60,7 @@ metadata:
   namespace: <namespace>
 spec:
   parentRefs:
-    port: <portNameRoutedFrom>
+    port: <portRoutedFrom>
     - ref:
       name: <nameRoutedFrom>
       type: 
@@ -71,7 +71,7 @@ spec:
     - backendRefs:
       - backendRef:
         datacenter: <datacenterRoutedTo>
-        port: <portNameRoutedTo>
+        port: <portRoutedTo>
         ref:
           name: <nameRoutedTo>
           type:
@@ -147,7 +147,7 @@ When using this CRD, the `spec` field closely resembles the `TCPRoute` GAMMA res
 
 ### `spec.parentRefs`
 
-Specifies the services and other resources to attach the route to. You can only define one `parentsRefs` configuration for each route. To attach the route to multiple resources, specify additional [`spec.parentRefs.ref`](#spec-parentrefs-ref) configurations in the `parentsRefs` block. You can only specify the name of one port for the route. Any resources that send traffic through the route use the same port.
+Specifies the services and other resources to attach the route to. You can only define one `parentsRefs` configuration for each route. To attach the route to multiple resources, specify additional [`spec.parentRefs.ref`](#spec-parentrefs-ref) configurations in the `parentsRefs` block. You can only specify one port for the route. Any resources that send traffic through the route use the same port.
 
 #### Values
 
@@ -157,7 +157,9 @@ Specifies the services and other resources to attach the route to. You can only
 
 ### `spec.parentRefs.port`
 
-Specifies the name of the port that the configuration applies to.
+Specifies the port for the Consul service that the configuration applies to. This parameter can be either a virtual port number, such as a Kubernetes service port, or a non-numeric target port value representing a named workload port.
+
+If you are not targeting a virtual port, specify the workload port name directly.
 
 #### Values
 
@@ -239,7 +241,9 @@ Specifies the name of the Consul datacenter that registered the Service backend
 
 ### `spec.rules.backendRefs.backendRef.port`
 
-Specifies the name of the port for the Consul service that the configuration routes traffic to.
+Specifies the port for the Consul service that the configuration routes traffic to. This parameter can be either a virtual port number, such as a Kubernetes service port, or a non-numeric target port value representing a named workload port.
+
+If you are not targeting a virtual port, specify the workload port name directly.
 
 #### Values
 
@@ -298,7 +302,7 @@ The following examples demonstrate common TCPRoute CRD configuration patterns fo
 
 ### Split TCP traffic between two ports
 
-The following example splits traffic for the `api` service. TCP traffic for services registered to the Consul catalog that are available at the `api` port is split so that 50% of the traffic routes to the service at the `api` port and 50% routes to the service at the `admin` port.
+The following example splits traffic for the `api` service. TCP traffic for services registered to the Consul catalog that are available at the `api-workload` port is split so that 50% of the traffic routes to the service at the `api-workload` port and 50% routes to the service at the `admin-workload` port.
 
 ```yaml
 apiVersion: mesh.consul.hashicorp.com/v2beta1
@@ -314,8 +318,8 @@ spec:
           groupVersion: v2beta1
           kind: Service
         name: api
-      # The configuration targets the workload port, not the service port.
-      port: "api"
+      # The virtual port number for the "api-workload" target port.
+      port: "80"
   rules:
     - backendRefs:
       - backendRef:
@@ -325,8 +329,8 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          # The configuration targets the workload port, not the service port.
-          port: "api"
+          # The virtual port number for the "api-workload" target port.
+          port: "80"
         weight: 50
       - backendRef:
           ref: 
@@ -335,7 +339,7 @@ spec:
               groupVersion: v2beta1
               kind: Service
             name: api
-          # The configuration targets the workload port, not the service port.
-          port: "admin"
+          # The virtual port number for the "admin-workload" target port.
+          port: "90"
         weight: 50
 ```