Skip to content

Commit

Permalink
TLS_PASSTHROUGH document (#650)
Browse files Browse the repository at this point in the history
* TLS_PASSTHROUGH documentation
  • Loading branch information
zijun726911 authored Jun 14, 2024
1 parent d3fa856 commit f60df58
Show file tree
Hide file tree
Showing 19 changed files with 1,384 additions and 80 deletions.
18 changes: 12 additions & 6 deletions .github/workflows/publish-doc.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ on:
push:
branches:
- main
- 'release-v*.*.*'
jobs:
publish-docs:
runs-on: ubuntu-latest
Expand All @@ -24,10 +25,15 @@ jobs:
run: |
python -m pip install --upgrade pip
pip install mkdocs-material mike
- name: Build
- name: Deploy to Mike
run: |
mike deploy 1.0.5 latest --update-aliases --push
mike set-default latest --allow-empty --push
if [[ ${{ github.ref }} == refs/heads/main ]]; then
# Deploy to the mike doc version `dev` and update the `latest` alias for the main branch new git commits
mike deploy dev latest --update-aliases --push
mike set-default latest
elif [[ ${{ github.ref }} == refs/heads/release-v* ]]; then
# Deploy to the mike doc version `vx.x.x` for the new git branches `release-vx.x.x`
branch_name=${{ github.ref }}
version=${branch_name##refs/heads/release-}
mike deploy $version --push
fi
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ go.work*

# gomock generated prog.go
pkg/aws/services/gomock_reflect_*

mocks/controller-runtime/client/gomock_reflect_*
pkg/**/prog.*

# Image build tarballed bundles
Expand Down
20 changes: 12 additions & 8 deletions docs/api-types/target-group-policy.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,35 +3,39 @@
## Introduction

By default, AWS Gateway API Controller assumes plaintext HTTP/1 traffic for backend Kubernetes resources.
TargetGroupPolicy is a CRD that can be attached to a Service, which allows the users to define protocol and
TargetGroupPolicy is a CRD that can be attached to Service or ServiceExport, which allows the users to define protocol, protocol version and
health check configurations of those backend resources.

When attaching a policy to a resource, the following restrictions apply:

- A policy can be only attached to `Service` resources.
- The attached resource can only be `backendRef` of `HTTPRoute` and `GRPCRoute`.
- A policy can be attached to `Service` that being `backendRef` of `HTTPRoute`, `GRPCRoute` and `TLSRoute`.
- A policy can be attached to `ServiceExport`.
- The attached resource should exist in the same namespace as the policy resource.

The policy will not take effect if:

- The resource does not exist
- The resource is not referenced by any route
- The resource is referenced by a route of unsupported type
- The ProtocolVersion is non-empty if the TargetGroupPolicy protocol is TCP

Please check the TargetGroupPolicy API Reference for more details. [TargetGroupPolicy API Reference](../api-reference.md#application-networking.k8s.aws/v1alpha1.TargetGroupPolicy)


These restrictions are not forced; for example, users may create a policy that targets a service that is not created yet.
However, the policy will not take effect unless the target is valid.



### Limitations and Considerations

- Attaching TargetGroupPolicy to a resource that is already referenced by a route will result in a replacement
- Attaching TargetGroupPolicy to an existing Service that is already referenced by a route will result in a replacement
of VPC Lattice TargetGroup resource, except for health check updates.
- Attaching TargetGroupPolicy to an existing ServiceExport will result in a replacement of VPC Lattice TargetGroup resource, except for health check updates.
- Removing TargetGroupPolicy of a resource will roll back protocol configuration to default setting. (HTTP1/HTTP plaintext)

## Example Configuration

This will enable TLS traffic between the gateway and Kubernetes service, with customized health check configuration.

Note that the TLS traffic is always terminated at the gateway, so it will be re-encrypted in this case. The gateway does not perform any certificate validations to the certificate on targets.
This will enable HTTPS traffic between the gateway and Kubernetes service, with customized health check configuration.

```
apiVersion: application-networking.k8s.aws/v1alpha1
Expand Down
58 changes: 58 additions & 0 deletions docs/api-types/tls-route.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# TLSRoute API Reference

## Introduction

With integration of the Gateway API, AWS Gateway API Controller supports `TLSRoute`.
This allows you to define and manage end-to-end TLS encrypted traffic routing to your Kubernetes clusters.

### Considerations

- `TLSRoute` sectionName must refer to a `TLS` protocol listener with `mode: Passthrough` in the parentRefs `Gateway`.
- `TLSRoute` only supports to have one rule.
- `TLSRoute` does not support any rule matching condition.
- The `hostnames` field with exactly one host name is required.


## Example Configuration

Here is a sample configuration that demonstrates how to set up a `TLSRoute` resource to route end-to-end TLS encrypted traffic to a nginx service:

```yaml
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata:
name: nginx-tls-route
spec:
hostnames:
- nginx-test.my-test.com
parentRefs:
- name: my-hotel-tls-passthrough
sectionName: tls
rules:
- backendRefs:
- name: nginx-tls
kind: Service
port: 443
```
In this example:
- The `TLSRoute` is named ` nginx-tls-route` and is associated with a parent gateway named `my-hotel-tls-passthrough` that has
a listener section named `tls`:
```
- name: tls
protocol: TLS
port: 443
tls:
mode: Passthrough
```
- The `TLSRoute` is configured to route traffic to a k8s service named `nginx-tls` on port 443.
- The `hostnames` field is set to `nginx-test.my-test.com`. The customer must use this hostname to send traffic to the nginx service.


For the detailed tls passthrough traffic connectivity setup, please refer the user guide [here](../guides/tls-passthrough.md).

For the detailed Gateway API `TLSRoute` resource specifications, you can refer to the
Kubernetes official [documentation](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.TLSRoute).

For the VPC Lattice tls passthrough Listener configuration details, you can refer to the VPC Lattice [documentation](https://docs.aws.amazon.com/vpc-lattice/latest/ug/tls-listeners.html).
1 change: 1 addition & 0 deletions docs/contributing/developer.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,7 @@ And install additional CRDs for the controller:

```bash
kubectl apply -f config/crds/bases/externaldns.k8s.io_dnsendpoints.yaml
kubectl apply -f config/crds/bases/gateway.networking.k8s.io_tlsroutes.yaml
kubectl apply -f config/crds/bases/application-networking.k8s.aws_serviceexports.yaml
kubectl apply -f config/crds/bases/application-networking.k8s.aws_serviceimports.yaml
kubectl apply -f config/crds/bases/application-networking.k8s.aws_targetgrouppolicies.yaml
Expand Down
222 changes: 222 additions & 0 deletions docs/guides/tls-passthrough.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,222 @@
# TLS Passthrough Support

[Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/guides/tls/) lays out the general guidelines on how to configure TLS passthrough. Here are examples on how to use them against AWS Gateway Api controller and VPC Lattice.

## Install Gateway API TLSRoute CRD

The TLSRoute CRD is already included in the helm chart and deployment.yaml, if you are using these 2 methods to install the controller no extra steps needed.
If you want to install the TLSRoute CRD manually by yourself:
```
# Install CRD
kubectl apply -f config/crds/bases/gateway.networking.k8s.io_tlsroutes.yaml
# Verfiy TLSRoute CRD
kubectl get crd tlsroutes.gateway.networking.k8s.io
NAME CREATED AT
tlsroutes.gateway.networking.k8s.io 2024-03-07T23:16:22Z
```

## Setup TLS Passthrough Connectivity in a single cluster

### 1. Configure TLS Passthrough Listener on Gateway

```
kubectl apply -f files/examples/my-gateway-tls-passthrough.yaml
```

```
# tls listener config snips:
apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
name: my-hotel-tls-passthrough
spec:
gatewayClassName: amazon-vpc-lattice
listeners:
...
- name: tls
protocol: TLS
port: 443
tls:
mode: Passthrough
...
```

### 2. Configure TLSRoute

```
# Suppose in the below example, we use the "parking" service as the client pod to test the TLS passthrough traffic.
kubectl apply -f files/examples/parking.yaml
# Configure nginx backend service (This nginx image includes a self-signed certificate)
kubectl apply -f files/example/nginx-server-tls-passthrough.yaml
# configure nginx tls route
kubectl apply -f files/examples/tlsroute-nginx.yaml
```

### 3. Verify the controller has reconciled nginx-tls route

Make sure the TLSRoute has the `application-networking.k8s.aws/lattice-assigned-domain-name` annotation and status `Accepted: True`
```
kubectl get tlsroute nginx-tls -o yaml
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata:
annotations:
application-networking.k8s.aws/lattice-assigned-domain-name: nginx-tls-default-0af995120af2711bc.7d67968.vpc-lattice-svcs.us-west-2.on.aws
...
name: nginx-tls
namespace: default
...
status:
parents:
- conditions:
- lastTransitionTime: .....
message: ""
observedGeneration: 1
reason: Accepted
status: "True"
type: Accepted
- lastTransitionTime: .....
message: ""
observedGeneration: 1
reason: ResolvedRefs
status: "True"
type: ResolvedRefs
controllerName: application-networking.k8s.aws/gateway-api-controller
```

### 4. Verify TLS Passthrough Traffic

```
kubectl get deployment nginx-tls
NAME READY UP-TO-DATE AVAILABLE AGE
nginx-tls 2/2 2 2 1d
# Use the specified TLSRoute hostname to send traffic to the beackend nginx service
kubectl exec deployments/parking -- curl -kv https://nginx-test.my-test.com --resolve nginx-test.my-test.com:443:169.254.171.0
* Trying 169.254.171.0:443...
* Connected to nginx-test.my-test.com (169.254.171.0) port 443 (#0)
....
* TLSv1.2 (OUT), TLS header, Certificate Status (22):
* TLSv1.2 (OUT), TLS handshake, Client hello (1):
* TLSv1.2 (IN), TLS handshake, Server hello (2):
* TLSv1.2 (IN), TLS handshake, Certificate (11):
* TLSv1.2 (IN), TLS handshake, Server key exchange (12):
* TLSv1.2 (IN), TLS handshake, Server finished (14):
* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
* TLSv1.2 (OUT), TLS change cipher, Change cipher spec (1):
* TLSv1.2 (OUT), TLS handshake, Finished (20):
* TLSv1.2 (IN), TLS change cipher, Change cipher spec (1):
* TLSv1.2 (IN), TLS handshake, Finished (20): <---------- TLS Handshake from client pod to the backend `nginx-tls` pod successfully, no tls termination in the middle
* SSL connection using TLSv1.2 / ECDHE-RSA-AES256-GCM-SHA384
* ALPN, server accepted to use h2
....
<body>
<h1>Welcome to nginx!</h1>
<p>If you see this page, the nginx web server is successfully installed and
working. Further configuration is required.</p>
....
```

## Setup TLS Passthrough Connectivity spanning multiple clusters


![tlsoute multi cluster](../images/tlsroute-multi-cluster.png)

### 1. In this example we still use the "parking" Kubernetes service as the client pod to test the cross cluster TLS passthrough traffic.
```
kubectl apply -f files/examples/parking.yaml
```

### 2. In cluster-1, create `tls-rate1` Kubernetes Service:
```
kubectl apply -f files/examples/tls-rate1.yaml
```

### 3. Configure ServiceExport with TargetGroupPolicy `protocol:TCP` in cluster-2

```
# Create tls-rate2 Kubernetes Service in cluster-2
kubectl apply -f files/examples/tls-rate2.yaml
# Create serviceexport in cluster-2
kubectl apply -f files/examples/tls-rate2-export.yaml
# Create targetgroup policy to configure TCP protocol for tls-rate2 in cluster-2
kubectl apply -f files/examples/tls-rate2-targetgrouppolicy.yaml
```

```
# Snips of serviceexport config
apiVersion: application-networking.k8s.aws/v1alpha1
kind: ServiceExport
metadata:
name: tls-rate-2
annotations:
application-networking.k8s.aws/federation: "amazon-vpc-lattice"
# Snips of targetgroup policy config
apiVersion: application-networking.k8s.aws/v1alpha1
kind: TargetGroupPolicy
metadata:
name: tls-rate2
spec:
targetRef:
group: "application-networking.k8s.aws"
kind: ServiceExport
name: tls-rate2
protocol: TCP
```

### 4. Configure ServiceImport in cluster1

```
kubectl apply -f files/examples/tls-rate2-import.yaml
```

### 5. Configure TLSRoute for blue/green deployment

```
kubectl apply -f files/examples/rate-tlsroute-bluegreen.yaml
# snips of TLSRoute span multiple Kubernetes Clusters
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata:
name: tls-rate
spec:
hostnames:
- tls-rate.my-test.com
parentRefs:
- name: my-hotel-tls
sectionName: tls
rules:
- backendRefs:
- name: tls-rate1 <---------- to Kubernetes Cluster-1
kind: Service
port: 443
weight: 10
- name: tls-rate2 <---------- to Kubernetes Cluster-2
kind: ServiceImport
port: 443
weight: 90
```
### 6. Verify cross-cluster TLS passthrough traffic

Expected to receive the weighted traffic route to tls-rate1 service(10%) and tls-rate2 service(90%), if you curl the `tls-rate.my-test.com` from the client pod multiple times:
```
kubectl exec deploy/parking -- sh -c 'for ((i=1; i<=30; i++)); do curl -k https://tls-rate.my-test.com --resolve tls-rate.my-test.com:443:169.254.171.0 2>/dev/null; done'
Requsting to TLS Pod(tls-rate2-7f8b9cc97b-fgqk6): tls-rate2 handler pod <----> k8s service in cluster-2
Requsting to TLS Pod(tls-rate2-7f8b9cc97b-fgqk6): tls-rate2 handler pod
Requsting to TLS Pod(tls-rate2-7f8b9cc97b-fgqk6): tls-rate2 handler pod
Requsting to TLS Pod(tls-rate2-7f8b9cc97b-fgqk6): tls-rate2 handler pod
Requsting to TLS Pod(tls-rate1-98cc7fd87a-642zw): tls-rate1 handler pod <----> k8s service in cluster-1
Requsting to TLS Pod(tls-rate2-7f8b9cc97b-fgqk6): tls-rate2 handler pod
Requsting to TLS Pod(tls-rate2-7f8b9cc97b-fgqk6): tls-rate2 handler pod
Requsting to TLS Pod(tls-rate2-7f8b9cc97b-fgqk6): tls-rate2 handler pod
Requsting to TLS Pod(tls-rate1-98cc7fd87a-642zw): tls-rate1 handler pod
```
Binary file added docs/images/tlsroute-multi-cluster.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
15 changes: 15 additions & 0 deletions files/examples/my-gateway-tls-passthrough.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
name: my-hotel-tls-passthrough
spec:
gatewayClassName: amazon-vpc-lattice
listeners:
- name: http
protocol: HTTP
port: 80
- name: tls
protocol: TLS
port: 443
tls:
mode: Passthrough
Loading

0 comments on commit f60df58

Please sign in to comment.