diff --git a/website/content/docs/k8s/multiport/configure.mdx b/website/content/docs/k8s/multiport/configure.mdx index 8beaf8339d1c..81d87b738a10 100644 --- a/website/content/docs/k8s/multiport/configure.mdx +++ b/website/content/docs/k8s/multiport/configure.mdx @@ -18,7 +18,7 @@ This page describes the process for integrating a service that uses multiple por Registering multi-port services with Consul requires Kubernetes. Multi-port services are not supported on VM deployments. -The following software versions are required: +The following minimum versions are required: - Consul v1.17.0 - `consul-k8s` CLI v1.3.0+ or `hashicorp/consul` Helm chart release v1.3.0+ @@ -29,7 +29,7 @@ There are additional requirements for service mesh proxies in transparent proxy ## Enable the v2 catalog -To enable the v2 catalog and its support for multi-port services, set `global.experiments: ["resource-apis"]` and `ui.enabled: false`. The following example includes these parameters in a Helm chart with minimal required configurations for the Consul installation: +To enable the v2 catalog and its support for multi-port services, set `global.experiments: ["resource-apis"]` and `ui.enabled: false`. The following example includes these parameters in a Helm chart with additional configurations for the Consul installation: @@ -37,10 +37,12 @@ To enable the v2 catalog and its support for multi-port services, set `global.ex global: enabled: true name: consul - image: hashicorp/consul:1.17.0-rc1 + image: hashicorp/consul:1.17.0 datacenter: dc1 tls: enabled: true + acls: + manageSystemACLs: true experiments: ["resource-apis"] server: enabled: true @@ -59,22 +61,28 @@ Then install Consul to your Kubernetes cluster using either the `consul-k8s` CLI -For platforms other than Mac OSX amd64, refer to [Install a previous version](/consul/docs/k8s/installation/install-cli#install-a-previous-version) for instructions on how to install a specific version of the `consul-k8s` CLI prior to running `consul-k8s install`. +```shell-session +$ consul-k8s install -config-file=values.yaml +``` + +To download a compatible version of `consul-k8s` and add it to your `PATH`, run the following commands instead: ```shell-session -$ export VERSION=1.3.0-rc1 && \ +$ export VERSION=1.3.0 && \ curl --location "https://releases.hashicorp.com/consul-k8s/${VERSION}/consul-k8s_${VERSION}_darwin_amd64.zip" --output consul-k8s-cli.zip $ unzip -o consul-k8s-cli.zip -d ~/consul-k8s $ export PATH=$PATH:$HOME/consul-k8s $ consul-k8s install -config-file=values.yaml ``` +For platforms other than Mac OSX amd64, refer to [Install a previous version](/consul/docs/k8s/installation/install-cli#install-a-previous-version). This page contains instructions on how to install a specific version of the `consul-k8s` CLI on Linux prior to running `consul-k8s install`. + ```shell-session -$ helm install consul hashicorp/consul --create-namespace --namespace consul --version 1.3.0-rc1 --values values.yaml +$ helm install consul hashicorp/consul --create-namespace --namespace consul --version 1.3.0 --values values.yaml ``` @@ -289,23 +297,23 @@ $ kubectl apply -f api.yaml -f web.yaml ## Configure traffic permissions -Consul uses traffic permissions to validate communication between services based on L4 identity. In the beta release of the v2 catalog API, traffic permissions allow all services by default. In order to verify that services function correctly on each port, create CRDs that deny traffic to each port. +Consul uses traffic permissions to validate communication between services based on L4 identity. When ACLs are enabled for the service mesh, traffic permissions deny all services by default. In order to allow traffic between the static client and the multi-port service, create CRDs that allow traffic to each port. The following examples create Consul CRDs that allow traffic to only one port of the multi-port service. Each resource separately denies `web` permission when it is a source of traffic to one of the services. These traffic permissions work with either method for defining a multi-port service. When following the instructions on this page, apply these permissions individually when you validate the ports. - + - + ```yaml apiVersion: auth.consul.hashicorp.com/v2beta1 kind: TrafficPermissions metadata: - name: web-to-api-port-deny + name: web-to-api spec: destination: identityName: api - action: deny + action: allow permissions: - sources: - identityName: web @@ -315,17 +323,17 @@ spec: - + ```yaml apiVersion: auth.consul.hashicorp.com/v2beta1 kind: TrafficPermissions metadata: - name: web-to-admin-port-deny + name: web-to-admin spec: destination: identityName: api - action: deny + action: allow permissions: - sources: - identityName: web @@ -353,9 +361,9 @@ Set environment variables to remember the pod name for the web workload for use $ export WEB_POD=web-6dcbd684bc-gk8n5 ``` -### Validate both ports +### Apply traffic permissions -Use the `web` Pod's name to open a shell session and test the `api` service on port 80. +Use the `web` Pod's name to open a shell session and test the `api` service on both ports. When ACLs are enabled, these commands fail until you apply a traffic permissions resource. @@ -363,14 +371,12 @@ Use the `web` Pod's name to open a shell session and test the `api` service on p ```shell-session $ kubectl exec -it ${WEB_POD} -c web -- curl api:80 -hello world ``` Then test the `api` service on port 90. ```shell-session $ kubectl exec -it ${WEB_POD} -c web -- curl api:90 -hello world from 9090 admin ``` @@ -379,25 +385,21 @@ hello world from 9090 admin ```shell-session $ kubectl exec -it ${WEB_POD} -c web -- curl api:80 -hello world ``` Then test the `api-admin` service on port 90. ```shell-session -$ kubectl exec -it ${WEB_POD} -c web --namespace consul -- curl api-admin:90 -hello world from 9090 admin +$ kubectl exec -it ${WEB_POD} -c web -- curl api-admin:90 ``` -### Validate port 80 - -Apply the CRD to allow traffic to port 80 only: +Apply the CRD to allow traffic to port 80: ```shell-session -$ kubectl apply -f deny-90.yaml +$ kubectl apply -f allow-80.yaml ``` @@ -410,13 +412,6 @@ Then, open a shell session in the `web` container and test the `api` service on $ kubectl exec -it ${WEB_POD} -c web -- curl api:80 hello world ``` - -Test the `api` service on port 90. This command should fail, indicating that the traffic permission is in effect. - -```shell-session -$ kubectl exec -it ${WEB_POD} -c web -- curl api:90 -``` - @@ -428,27 +423,13 @@ $ kubectl exec -it ${WEB_POD} -c web -- curl api:80 hello world ``` -Test the `admin` service on port 90. This command should fail, indicating that the traffic permission is in effect. - -```shell-session -$ kubectl exec -it ${WEB_POD} -c web -- curl api-admin:90 -``` - -Before testing the other port, remove the `TrafficPermissions` CRD. - -```shell-session -$ kubectl delete -f deny-90.yaml -``` - -### Validate port 90 - -Apply the CRD to allow traffic to port 90 only: +Apply the CRD to allow traffic to port 90: ```shell-session -$ kubectl apply -f deny-80.yaml +$ kubectl apply -f allow-90.yaml ``` @@ -462,12 +443,6 @@ $ kubectl exec -it ${WEB_POD} -c web -- curl api:90 hello world from 9090 admin ``` -Test the `api` service on port 80. This command should fail, indicating that the traffic permission is in effect. - -```shell-session -$ kubectl exec -it ${WEB_POD} -c web -- curl api:80 -``` - @@ -479,11 +454,16 @@ $ kubectl exec -it ${WEB_POD} -c web -- curl api-admin:90 hello world from 9090 admin ``` -Test the `api` service on port 80. This command should fail, indicating that the traffic permission is in effect. - -```shell-session -$ kubectl exec -it ${WEB_POD} -c web -- curl api:80 -``` - + +## Next steps + +After applying traffic permissions and validating service-to-service communication within your service mesh, you can manage traffic between multi-port services, filter traffic between ports based on L7 header information, or match HTTP traffic with ports using query parameters. + +Refer to the following pages for more information: + +- [Split traffic between services](/consul/docs/k8s/multiport/traffic-split) +- [gRPC route example: route traffic by matching header](/consul/docs/k8s/multiport/reference/httproute#route-traffic-by-matching-header) +- [HTTP route example: route traffic by matching header](/consul/docs/k8s/multiport/reference/httproute#route-traffic-by-matching-header) +- [HTTP route example: route traffic by matching header and query parameter](/consul/docs/k8s/multiport/reference/httproute#route-traffic-by-matching-header-and-query-parameter) \ No newline at end of file diff --git a/website/content/docs/k8s/multiport/index.mdx b/website/content/docs/k8s/multiport/index.mdx index 2524e7f8cd5c..ec8dd6354e7b 100644 --- a/website/content/docs/k8s/multiport/index.mdx +++ b/website/content/docs/k8s/multiport/index.mdx @@ -18,14 +18,21 @@ This topic describes the process to register a service with multiple ports on Ku To use a multi-port service in Consul on Kubernetes deployments, complete the following steps: -1. Enable the v2 catalog. Add `global.experiments: ["resource-apis"]` and `ui.enabled: false` to a cluster's Helm chart before deploying Consul. +1. Enable the v2 catalog with ACLs enabled. Add `global.experiments: ["resource-apis"]`, `ui.enabled: false`, and `manageSystemACLs: true` to a cluster's Helm chart before deploying Consul. 1. Use the `"consul.hashicorp.com/mesh-inject": "true"` annotation so that Consul registers the service automatically when Kubernetes deploys containers. -1. Configure traffic permissions. In the beta release, services registered to the v2 catalog allow all traffic by default. You can use the `TrafficPermissions` CRD to deny traffic to individual services for testing purposes. -1. Validate multi-port functionality. Send test traffic to each port to confirm that traffic is authorized and routed correctly. +1. Configure traffic permissions. When ACLs are enabled, Consul denies all traffic by default. You can use the `TrafficPermissions` CRD to allow traffic to services. For an example configuration and instructions for each of the steps in this workflow, refer to [configure multi-port services](/consul/docs/k8s/multiport/configure). -[Link to/describe advanced routing configurations re: examples on configuration pages] +### Advanced proxy and route configuration workflow + +You can also configure Envoy proxies and sidecar behavior with the proxy configurations resource, and manage traffic between services at the L4 and L7 networking layers with the TCP, HTTP, and gRPC route resources. After you [configure multi-port services](/consul/docs/k8s/multiport/configure), complete the following steps: + +1. Define the resource's behavior in a custom resource definition (CRD). For specifications and example configurations, refer to the [configuration reference](#reference-documentation) for each resource. +1. Apply the resource to your cluster. +1. Output the resource path with the `consul resource read` command. + +For an example configuration and instructions for each of the steps in this workflow, refer to [split service traffic between ports](/consul/docs/k8s/multiport/traffic-split). ## Constraints and limitations @@ -48,12 +55,13 @@ The following resources are available to help you use multi-port services: ### Usage documentation - [Configure multi-port services](/consul/docs/k8s/multiport/configure) +- [Split traffic between multi-port services](/consul/docs/k8s/multiport/traffic-split) ### Reference documentation - [`consul resource` CLI command](/consul/docs/k8s/multiport/reference/resource-command) -- [GRPCRoute configuration reference](/consul/docs/k8s/multiport/reference/grpcroute) -- [HTTPRoute configuration reference](/consul/docs/k8s/multiport/reference/httproute) -- [ProxyConfiguration configuration reference](/consul/docs/k8s/multiport/reference/proxyconfiguration) -- [TCPRoute configuration reference](/consul/docs/k8s/multiport/reference/tcproute) -- [TrafficPermissions configuration reference](/consul/docs/k8s/multiport/reference/trafficpermissions) +- [`GRPCRoute` resource configuration reference](/consul/docs/k8s/multiport/reference/grpcroute) +- [`HTTPRoute` resource configuration reference](/consul/docs/k8s/multiport/reference/httproute) +- [`ProxyConfiguration` resource configuration reference](/consul/docs/k8s/multiport/reference/proxyconfiguration) +- [`TCPRoute` resource configuration reference](/consul/docs/k8s/multiport/reference/tcproute) +- [`TrafficPermissions` resource configuration reference](/consul/docs/k8s/multiport/reference/trafficpermissions) diff --git a/website/content/docs/k8s/multiport/reference/httproute.mdx b/website/content/docs/k8s/multiport/reference/httproute.mdx index b7bfc8f0f48c..31f722e32878 100644 --- a/website/content/docs/k8s/multiport/reference/httproute.mdx +++ b/website/content/docs/k8s/multiport/reference/httproute.mdx @@ -866,10 +866,10 @@ spec: The following examples routes HTTP traffic for the `api` service according to its header HTTP traffic for services registered to the Consul catalog that are available at the `api-workload` port are routed according to the following criteria: -- For traffic with a header that contains a `x-debug` value of exactly `1`, Consul modifies the response and request headers and routes to the `api` service at the `api-workload` port. -- For traffic with a header that contains a `x-debug` value of exactly `2`, Consul modifies the response and request headers and routes to the `api-admin` service at the `admin-workload` port. +- For traffic with a header that contains a `x-debug` value of exactly `1`, Consul routes to the `api` service at the `api-workload` port. +- For traffic with a header that contains a `x-debug` value of exactly `2`, Consul routes to the `api-admin` service at the `admin-workload` port. -This example also includes how to include filters that modify request or response headers. +This example also configures Consul to modify request and response headers when routing traffic. ```yaml apiVersion: mesh.consul.hashicorp.com/v2beta1 @@ -936,4 +936,68 @@ spec: name: api-admin # The configuration targets the workload port, not the service port. port: "admin-workload" +``` + +### Route traffic by matching header and query parameter + +The following examples routes HTTP traffic for the `api` service according to its header HTTP traffic for services registered to the Consul catalog that are available at the `api-workload` port are routed according to the following criteria: + +- For traffic with a header _and_ a query parameter that both contain `x-debug` values of exactly `1`, Consul routes to the `api` service at the `api-workload` port. +- For traffic with a header _and_ a query parameter that both contain `x-debug` values of exactly `2`, Consul routes to the `api-admin` service at the `admin-workload` port. + +```yaml +apiVersion: mesh.consul.hashicorp.com/v2beta1 +kind: HTTPRoute +metadata: + name: api-match-split + namespace: default +spec: + parentRefs: + - ref: + type: + group: catalog + groupVersion: v2beta1 + kind: Service + name: api + # The configuration targets the workload port, not the service port. + port: "api-workload" + rules: + - matches: + - headers: + - type: "HEADER_MATCH_TYPE_EXACT" + name: "x-debug" + value: "1" + queryParams: + - type: "QUERY_PARAM_MATCH_TYPE_EXACT" + name: "x-debug" + value: "1" + backendRefs: + - backendRef: + ref: + type: + group: catalog + groupVersion: v2beta1 + kind: Service + name: api + # The configuration targets the workload port, not the service port. + port: "api-workload" + - matches: + - headers: + - type: "HEADER_MATCH_TYPE_EXACT" + name: "x-debug" + value: "2" + queryParams: + - type: "QUERY_PARAM_MATCH_TYPE_EXACT" + name: "x-debug" + value: "2" + backendRefs: + - backendRef: + ref: + type: + group: catalog + groupVersion: v2beta1 + kind: Service + name: api-admin + # The configuration targets the workload port, not the service port. + port: "admin-workload" ``` \ No newline at end of file diff --git a/website/content/docs/k8s/multiport/reference/resource-command.mdx b/website/content/docs/k8s/multiport/reference/resource-command.mdx index 593a6ceba725..6f7470b16c86 100644 --- a/website/content/docs/k8s/multiport/reference/resource-command.mdx +++ b/website/content/docs/k8s/multiport/reference/resource-command.mdx @@ -35,7 +35,12 @@ You can issue the following subcommands with the `consul resource` command. ### `apply` `consul resource apply` writes or updates a resource at a given file path. -You must present a token with `operator:write` [ACL permissions](/consul/api-docs/api-structure#authentication) to use the `apply` command. + +The following table shows the required [ACLs permissions](/consul/api-docs/api-structure#authentication) to run the `apply` command: + +| ACL Required | +| ------------ | +| `operator:write` | #### Command Options @@ -53,7 +58,7 @@ $ consul resource apply -f=trafficpermissions.yaml `consul resource delete`removes a Consul resource at a given file path. -The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). +The following table shows the required [ACLs permissions](/consul/api-docs/api-structure#authentication) to run the `delete` command: | ACL Required | | ------------ | @@ -77,7 +82,7 @@ $ consul resource delete -f=trafficpermissions.yaml This command must be issued with a resource type. All resource definitions include a `type` configuration block that contains a `group`, `groupVersion`, and `kind`. By formatting the `type` on the command line as `group.groupVersion.kind`, you can return all resources with a matching `type` in the configuration. -The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). +The following table shows the required [ACLs permissions](/consul/api-docs/api-structure#authentication) to run the `list` command: | ACL Required | | ------------ | @@ -101,9 +106,9 @@ $ consul resource list catalog.v2beta1.Service card-processor -partition=billing ### `read` -`consul resource list` outputs names of resources according to the type of resource or where the resource is applied. +`consul resource read` outputs names of resources according to the type of resource or where the resource is applied. -The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). +The following table shows the required [ACLs permissions](/consul/api-docs/api-structure#authentication) to run the `read` command: | ACL Required | | ------------ | diff --git a/website/content/docs/k8s/multiport/traffic-split.mdx b/website/content/docs/k8s/multiport/traffic-split.mdx new file mode 100644 index 000000000000..03a72834d585 --- /dev/null +++ b/website/content/docs/k8s/multiport/traffic-split.mdx @@ -0,0 +1,92 @@ +--- +layout: docs +page_title: Split traffic between multi-port services +description: Learn how to +--- + +# Split traffic between multi-port services + + + +Multi-port services are part of a beta release. This documentation supports testing and development scenarios. Do not use multi-port services or the v2 catalog API in secure production environments. + + + +This page describes the process for splitting TCP, HTTP, and gRPC traffic between two ports of a multi-port service. It includes an example TCPRoute resource configuration to demonstrate Consul's multi-port features. + +## Prerequisites + +Splitting traffic between two ports of a multi-port service requires the [v2 catalog API](/consul/docs/architecture/catalog/v2). For guidance on enabling the v2 catalog, deploying multi-port services, and applying traffic permissions to them, refer to [configure multi-port services](/consul/docs/k8s/multiport/configure). + +## Split traffic using route resources + +You can split traffic according to the application traffic's network protocol using the following CRDs: + +- [`TCPRoute` resource](/consul/docs/k8s/multiport/reference/tcproute) +- [`HTTPRoute` resource](/consul/docs/k8s/multiport/reference/httproute) +- [`GRPCRoute` resource](/consul/docs/k8s/multiport/reference/tcproute) + +The process for implementing these resources in your Consul on Kubernetes deployment is the same: + +1. Define the resource's behavior in a custom resource definition (CRD). +1. Apply the resource to your cluster. +1. Output the resource path with the `consul resource read` command. + +Configurable fields between each resource vary. The usage instructions on this page configure a TCP route resource to use with the [end-to-end multi-port deployment example](/consul/docs/k8s/multiport/configure). + +## Define route resource + +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 +kind: TCPRoute +metadata: + name: api-split + namespace: default +spec: + parentRefs: + - ref: + type: + group: catalog + groupVersion: v2beta1 + kind: Service + name: api + port: "api-workload" + rules: + - backendRefs: + - backendRef: + ref: + type: + group: catalog + groupVersion: v2beta1 + kind: Service + name: api + port: "api-workload" + weight: 50 + - backendRef: + ref: + type: + group: catalog + groupVersion: v2beta1 + kind: Service + name: api + port: "admin-workload" + weight: 50 +``` + + + +## Apply the resource + +Use the `kubectl` command to apply the resource to your Consul cluster. + +```shell-session +$ kubectl apply -f api-split.yaml +``` + +## Read the resource path + +[Final TODO] \ No newline at end of file diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index e2d6255f4a24..0b15632842ac 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1538,6 +1538,10 @@ "title": "Configure multi-port services", "path": "k8s/multiport/configure" }, + { + "title": "Split traffic between multi-port services", + "path": "k8s/multiport/traffic-split" + }, { "title": "Reference", "routes": [