From 50a6876596a1a339edcd6a657a598027c0f04454 Mon Sep 17 00:00:00 2001 From: Michael Zalimeni Date: Fri, 23 Feb 2024 10:16:21 -0500 Subject: [PATCH] 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 1a732b0e6ad4a5a301fcb2869e77fa85c0b02f8b --- .../k8s/multiport/reference/grpcroute.mdx | 36 +++++----- .../k8s/multiport/reference/httproute.mdx | 48 +++++++------ .../docs/k8s/multiport/reference/tcproute.mdx | 28 ++++---- .../docs/k8s/multiport/traffic-split.mdx | 71 +++---------------- 4 files changed, 72 insertions(+), 111 deletions(-) diff --git a/website/content/docs/k8s/multiport/reference/grpcroute.mdx b/website/content/docs/k8s/multiport/reference/grpcroute.mdx index 2373ff96a67d..aa46137e9910 100644 --- a/website/content/docs/k8s/multiport/reference/grpcroute.mdx +++ b/website/content/docs/k8s/multiport/reference/grpcroute.mdx @@ -93,7 +93,7 @@ metadata: namespace: spec: parentRefs: - port: + port: - ref: name: type: @@ -104,7 +104,7 @@ spec: - backendRefs: - backendRef: datacenter: - port: "" + port: "" ref: name: 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" ``` \ No newline at end of file diff --git a/website/content/docs/k8s/multiport/reference/httproute.mdx b/website/content/docs/k8s/multiport/reference/httproute.mdx index 377e5f3a7235..9e211011b615 100644 --- a/website/content/docs/k8s/multiport/reference/httproute.mdx +++ b/website/content/docs/k8s/multiport/reference/httproute.mdx @@ -97,7 +97,7 @@ metadata: namespace: spec: parentRefs: - port: + port: - ref: name: type: @@ -108,7 +108,7 @@ spec: - backendRefs: - backendRef: datacenter: - port: + port: ref: name: 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" ``` \ No newline at end of file diff --git a/website/content/docs/k8s/multiport/reference/tcproute.mdx b/website/content/docs/k8s/multiport/reference/tcproute.mdx index 9dd8a4ca1bed..625b5af7e4c9 100644 --- a/website/content/docs/k8s/multiport/reference/tcproute.mdx +++ b/website/content/docs/k8s/multiport/reference/tcproute.mdx @@ -60,7 +60,7 @@ metadata: namespace: spec: parentRefs: - port: + port: - ref: name: type: @@ -71,7 +71,7 @@ spec: - backendRefs: - backendRef: datacenter: - port: + port: ref: name: 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 ``` \ No newline at end of file diff --git a/website/content/docs/k8s/multiport/traffic-split.mdx b/website/content/docs/k8s/multiport/traffic-split.mdx index 23a714f12466..c87aba534086 100644 --- a/website/content/docs/k8s/multiport/traffic-split.mdx +++ b/website/content/docs/k8s/multiport/traffic-split.mdx @@ -34,13 +34,7 @@ Complete the following steps to implement a split in TCP traffic between two ser ## Define route resource -The following example splits traffic for the services in the `api` Pod. - - - - - -TCP traffic for services registered to the Consul catalog that are available at the `admin` 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. @@ -52,84 +46,39 @@ metadata: spec: parentRefs: - ref: - type: + type: group: catalog groupVersion: v2beta1 kind: Service name: api - port: "admin" + # The virtual port number for the "api-workload" target port. + port: "80" rules: - backendRefs: - backendRef: - ref: - type: - group: catalog - groupVersion: v2beta1 - kind: Service - name: api - port: "api" - weight: 50 - - backendRef: - ref: + ref: type: group: catalog groupVersion: v2beta1 kind: Service name: api - port: "admin" + # The virtual port number for the "api-workload" target port. + port: "80" weight: 50 -``` - - - - - - -TCP traffic for services registered to the Consul catalog that are available at the `api-admin` 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 `api-admin` port. - - - -```yaml -apiVersion: mesh.consul.hashicorp.com/v2beta1 -kind: TCPRoute -metadata: - name: api-split -spec: - parentRefs: - - ref: - type: - group: catalog - groupVersion: v2beta1 - kind: Service - name: api-admin - port: "admin" - rules: - - backendRefs: - backendRef: - ref: + ref: type: group: catalog groupVersion: v2beta1 kind: Service name: api - port: "api" - weight: 50 - - backendRef: - ref: - type: - group: catalog - groupVersion: v2beta1 - kind: Service - name: api-admin - port: "admin" + # The virtual port number for the "admin-workload" target port. + port: "90" weight: 50 ``` - - - ## Apply the resource Use the `kubectl` command to apply the resource to your Consul cluster.