Skip to content

Commit

Permalink
Index + usage updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@boruszak
boruszak committed Nov 1, 2023
1 parent 28e487b commit 376eeb0
Show file tree
Hide file tree
Showing 6 changed files with 230 additions and 77 deletions.
100 changes: 40 additions & 60 deletions website/content/docs/k8s/multiport/configure.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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+
Expand All @@ -29,18 +29,20 @@ 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:

<CodeBlockConfig name="values.yaml">

```yaml
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
Expand All @@ -59,22 +61,28 @@ Then install Consul to your Kubernetes cluster using either the `consul-k8s` CLI

<Tab heading="consul-k8s CLI" group="consul-k8s">

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`.

</Tab>

<Tab heading="Helm" group="helm">

```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
```

</Tab>
Expand Down Expand Up @@ -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.

<CodeTabs tabs={[ "Deny port 80", "Deny port 90" ]}>
<CodeTabs tabs={[ "Allow port 80", "Allow port 90" ]}>

<CodeBlockConfig filename="deny-80.yaml">
<CodeBlockConfig filename="allow-80.yaml">

```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
Expand All @@ -315,17 +323,17 @@ spec:
</CodeBlockConfig>
<CodeBlockConfig filename="deny-90.yaml">
<CodeBlockConfig filename="allow-90.yaml">
```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
Expand Down Expand Up @@ -353,24 +361,22 @@ 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.

<Tabs>

<Tab heading="Method 1" group="method1">

```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
```

</Tab>
Expand All @@ -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
```

</Tab>
</Tabs>

### 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
```

<Tabs>
Expand All @@ -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
```

</Tab>

<Tab heading="Method 2" group="method2">
Expand All @@ -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
```

</Tab>
</Tabs>

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
```

<Tabs>
Expand All @@ -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
```

</Tab>

<Tab heading="Method 2" group="method2">
Expand All @@ -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
```

</Tab>
</Tabs>

## 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)
26 changes: 17 additions & 9 deletions website/content/docs/k8s/multiport/index.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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)
70 changes: 67 additions & 3 deletions website/content/docs/k8s/multiport/reference/httproute.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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"
```
Loading

0 comments on commit 376eeb0

Please sign in to comment.