TLS_PASSTHROUGH document

aws · Jun 10, 2024 · c34d9d4 · c34d9d4
1 parent d3fa856
commit c34d9d4
Show file tree

Hide file tree

Showing 18 changed files with 1,414 additions and 79 deletions.
diff --git a/.github/workflows/publish-doc.yaml b/.github/workflows/publish-doc.yaml
@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - main
+      - 'release-v*.*.*'
 jobs:
   publish-docs:
     runs-on: ubuntu-latest
@@ -24,10 +25,12 @@ 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
+            mike deploy dev latest --update-aliases --push
+          elif [[ ${{ github.ref }} == refs/heads/release-v* ]]; then
+            branch_name=${{ github.ref }}  # refs/heads/release-vx.x.x
+            version=${branch_name##refs/heads/release-}  # Extract version part
+            mike deploy $version --push
+          fi
diff --git a/.gitignore b/.gitignore
@@ -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

diff --git a/docs/api-types/target-group-policy.md b/docs/api-types/target-group-policy.md
@@ -3,13 +3,13 @@
 ## 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 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:
@@ -23,15 +23,14 @@ 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 a 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 a 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

diff --git a/docs/api-types/tls-route.md b/docs/api-types/tls-route.md
@@ -0,0 +1,63 @@
+# 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.
+
+### TLSRoute Key Features & Limitations
+
+**Features**:
+
+- **Routing Traffic**: Enables routing end-to-end TLS encrypted traffic from your client workload to server workload.
+
+
+**Limitations**:
+
+- **Listener Protocol**: The `TLSRoute` sectionName must refer to an TLS protocol listener with mode: Passthrough in the parent `Gateway`.
+- **Service Export**: The `TLSRoute` does not support integration with `ServiceExport`.
+- `TLSRoute` don't have any rule matching field.
+- `TLSRoute` only support to have one rule.
+- The `hostnames` field with exactly one host name is required in the `TLSRoute`. This domain name is used as a vpc lattice's Service Name Indication (SNI) match.
+
+
+## Example Configuration
+
+Here is a sample configuration that demonstrates how to set up a `TLSRoute` for a HelloWorld gRPC 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 e2e tls encrypted traffic to a k8s service named `nginx-tls` on port 443.
+
+---
+
+This `TLSRoute` documentation provides a detailed introduction, feature set, and a basic example of how to configure
+and use the resource within AWS Gateway API Controller project. For in-depth details and specifications, you can refer to the
+official [Gateway API documentation](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.TLSRoute).
diff --git a/docs/guides/tls-passthrough.md b/docs/guides/tls-passthrough.md
@@ -0,0 +1,257 @@
+# 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 already included in the helm chart and deployment.yaml, If you are using these 2 methods to install the controller no extra steps are needed.
+If you want to install the 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/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
+
+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)
+* ALPN, offering h2
+* ALPN, offering http/1.1
+* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH
+* successfully set certificate verify locations:
+*  CAfile: /etc/pki/tls/certs/ca-bundle.crt
+*  CApath: none
+* 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):
+* SSL connection using TLSv1.2 / ECDHE-RSA-AES256-GCM-SHA384
+* ALPN, server accepted to use h2
+* Server certificate:
+*  subject: C=US; ST=wa; L=seattle; O=aws; OU=lattice; CN=liwen.ssl-test.com; [email protected]
+*  start date: Mar  5 21:26:24 2024 GMT
+# use customer defined name
+curl -k -v https://nginx-test.my-test.com --resolve nginx-test.my-test.com:443:169.254.171.32
+* Added nginx-test.my-test.com:443:169.254.171.32 to DNS cache
+* Hostname nginx-test.my-test.com was found in DNS cache
+*   Trying 169.254.171.0:443...
+* Connected to nginx-test.my-test.com (169.254.171.0) port 443 (#0)
+* ALPN, offering h2
+* ALPN, offering http/1.1
+* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH
+* successfully set certificate verify locations:
+*  CAfile: /etc/pki/tls/certs/ca-bundle.crt
+*  CApath: none
+* 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):
+* SSL connection using TLSv1.2 / ECDHE-RSA-AES256-GCM-SHA384
+* ALPN, server accepted to use h2
+* Server certificate:
+*  subject: C=US; ST=wa; L=seattle; O=aws; OU=lattice; CN=liwen.ssl-test.com; [email protected]
+
+....
+<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 ServieExport 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 bluegreen 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
+```
diff --git a/docs/images/tlsroute-multi-cluster.png b/docs/images/tlsroute-multi-cluster.png