HTTPS Termination (#140)

* HTTPS Termination

This commit adds support for HTTPS listeners with a TLS mode of Terminate.
Multiple HTTPS listeners are supported provided their hostnames do not conflict.
Additionally, a gateway can have an HTTP and HTTPS listener with the same
hostname.

Limitations:
- HTTPS listeners must listen on port 443
- Supports a single reference to a Kubernetes Secret of type kubernetes.io/tls
- Secret must be in the same namespace as the Gateway
- Secret must be created before the HTTPRoutes are created
- Secret rotation is not supported
- SNI enforcement is not implemented

Author: kate-osborn

README.md

@@ -93,11 +93,6 @@ You can deploy NGINX Kubernetes Gateway on an existing Kubernetes 1.16+ cluster.
    NAME                             READY   STATUS    RESTARTS   AGE
    nginx-gateway-5d4f4c7db7-xk2kq   2/2     Running   0          112s
    ```
-1. Create the Gateway resource:
-
-   ```
-   kubectl apply -f deploy/manifests/gateway.yaml
-   ```
 
 ## Expose NGINX Kubernetes Gateway
 

deploy/manifests/nginx-gateway.yaml

@@ -13,6 +13,7 @@ rules:
   - ""
   resources:
   - services
+  - secrets
   verbs:
   - list
   - watch
@@ -80,7 +81,7 @@ spec:
       initContainers:
       - image: busybox:1.34 # FIXME(pleshakov): use gateway container to init the Config with proper main config
         name: nginx-config-initializer
-        command: [ 'sh', '-c', 'echo "load_module /usr/lib/nginx/modules/ngx_http_js_module.so; events {}  pid /etc/nginx/nginx.pid; http { include /etc/nginx/conf.d/*.conf; js_import /usr/lib/nginx/modules/njs/httpmatches.js; server { default_type text/html; return 404; } }" > /etc/nginx/nginx.conf && mkdir /etc/nginx/conf.d && chown 1001:0 /etc/nginx/conf.d' ]
+        command: [ 'sh', '-c', 'echo "load_module /usr/lib/nginx/modules/ngx_http_js_module.so; events {}  pid /etc/nginx/nginx.pid; http { include /etc/nginx/conf.d/*.conf; js_import /usr/lib/nginx/modules/njs/httpmatches.js; }" > /etc/nginx/nginx.conf && mkdir /etc/nginx/conf.d /etc/nginx/secrets && chown 1001:0 /etc/nginx/conf.d /etc/nginx/secrets' ]
         volumeMounts:
         - name: nginx-config
           mountPath: /etc/nginx
@@ -105,6 +106,8 @@ spec:
         ports:
         - name: http
           containerPort: 80
+        - name: https
+          containerPort: 443
         volumeMounts:
         - name: nginx-config
           mountPath: /etc/nginx

deploy/manifests/service/loadbalancer.yaml

@@ -11,5 +11,9 @@ spec:
     targetPort: 80
     protocol: TCP
     name: http
+  - port: 443
+    targetPort: 443
+    protocol: TCP
+    name: https
   selector:
     app: nginx-gateway

examples/advanced-routing/README.md

@@ -46,6 +46,12 @@ The cafe application consists of four services: `coffee-v1-svc`, `coffee-v2-svc`
 
 ## 3. Configure Routing
 
+1. Create the `Gateway`:
+   
+   ```
+   kubectl apply -f gateway.yaml
+   ```
+   
 1. Create the `HTTPRoute` resources:
 
    ```

examples/advanced-routing/cafe-routes.yaml

@@ -5,7 +5,6 @@ metadata:
 spec:
   parentRefs:
   - name: gateway
-    namespace: nginx-gateway
     sectionName: http
   hostnames:
   - "cafe.example.com"
@@ -41,7 +40,6 @@ metadata:
 spec:
   parentRefs:
   - name: gateway
-    namespace: nginx-gateway
     sectionName: http
   hostnames:
   - "cafe.example.com"

deploy/manifests/gateway.yaml renamed to examples/advanced-routing/gateway.yaml

@@ -2,7 +2,6 @@ apiVersion: gateway.networking.k8s.io/v1alpha2
 kind: Gateway
 metadata:
   name: gateway
-  namespace: nginx-gateway
   labels:
     domain: k8s-gateway.nginx.org
 spec:

examples/cafe-example/README.md

@@ -39,6 +39,12 @@ In this example we deploy NGINX Kubernetes Gateway, a simple web application, an
 
 ## 3. Configure Routing
 
+1. Create the `Gateway`:
+
+   ```
+   kubectl apply -f gateway.yaml
+   ```
+
 1. Create the `HTTPRoute` resources:
 
    ```

examples/cafe-example/cafe-routes.yaml

@@ -5,7 +5,6 @@ metadata:
 spec:
   parentRefs:
   - name: gateway
-    namespace: nginx-gateway
     sectionName: http
   hostnames:
   - "cafe.example.com"
@@ -21,7 +20,6 @@ metadata:
 spec:
   parentRefs:
   - name: gateway
-    namespace: nginx-gateway
     sectionName: http
   hostnames:
   - "cafe.example.com"
@@ -41,7 +39,6 @@ metadata:
 spec:
   parentRefs:
   - name: gateway
-    namespace: nginx-gateway
     sectionName: http
   hostnames:
   - "cafe.example.com"

examples/cafe-example/gateway.yaml

@@ -0,0 +1,12 @@
+apiVersion: gateway.networking.k8s.io/v1alpha2
+kind: Gateway
+metadata:
+  name: gateway
+  labels:
+    domain: k8s-gateway.nginx.org
+spec:
+  gatewayClassName: nginx
+  listeners:
+  - name: http
+    port: 80
+    protocol: HTTP

examples/https-termination/README.md

@@ -0,0 +1,90 @@
+# HTTPS Termination Example
+
+In this example we expand on the simple [cafe-example](../cafe-example) by adding HTTPS termination to our routes.
+
+## Running the Example
+
+## 1. Deploy NGINX Kubernetes Gateway
+
+1. Follow the [installation instructions](https://github.com/nginxinc/nginx-kubernetes-gateway/blob/main/README.md#run-nginx-gateway) to deploy NGINX Gateway.
+
+1. Save the public IP address of NGINX Kubernetes Gateway into a shell variable:
+   
+   ```
+   GW_IP=XXX.YYY.ZZZ.III
+   ```
+
+1. Save the HTTPS port of NGINX Kubernetes Gateway:
+   
+   ```
+   GW_HTTPS_PORT=port
+   ```
+
+## 2. Deploy the Cafe Application  
+
+1. Create the coffee and the tea deployments and services:
+   
+   ```
+   kubectl apply -f cafe.yaml
+   ```
+
+1. Check that the Pods are running in the `default` namespace:
+
+   ```
+   kubectl -n default get pods
+   NAME                      READY   STATUS    RESTARTS   AGE
+   coffee-6f4b79b975-2sb28   1/1     Running   0          12s
+   tea-6fb46d899f-fm7zr      1/1     Running   0          12s
+   ```
+
+## 3. Configure HTTPS Termination and Routing
+
+1. Create a secret with a TLS certificate and key:
+   ```
+   kubectl apply -f cafe-secret.yaml
+   ```
+
+   The TLS certificate and key in this secret are used to terminate the TLS connections for the cafe application.
+   **Important**: This certificate and key are for demo purposes only. 
+   
+1. Create the `Gateway` resource:
+   ```
+   kubectl apply -f gateway.yaml
+   ```
+
+   This [gateway](./gateway.yaml) configures an `https` listener is to terminate TLS connections using the `cafe-secret` we created in the step 1. 
+
+1. Create the `HTTPRoute` resources:
+   ```
+   kubectl apply -f cafe-routes.yaml
+   ```
+
+   To configure HTTPS termination for our cafe application, we will bind the `https` listener to our `HTTPRoutes` in [cafe-routes.yaml](./cafe-routes.yaml) using the [`parentRef`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io%2fv1alpha2.ParentReference) field:
+
+   ```yaml
+   parentRefs:
+   - name: gateway
+     namespace: default
+     sectionName: https
+   ```
+
+## 4. Test the Application
+
+To access the application, we will use `curl` to send requests to the `coffee` and `tea` services.
+Since our certificate is self-signed, we'll use curl's `--insecure` option to turn off certificate verification.
+
+To get coffee:
+
+```
+curl --resolve cafe.example.com:$GW_HTTPS_PORT:$GW_IP https://cafe.example.com:$GW_HTTPS_PORT/coffee --insecure
+Server address: 10.12.0.18:80
+Server name: coffee-7586895968-r26zn
+```
+
+To get tea:
+
+```
+curl --resolve cafe.example.com:$GW_HTTPS_PORT:$GW_IP https://cafe.example.com:$GW_HTTPS_PORT/tea --insecure
+Server address: 10.12.0.19:80
+Server name: tea-7cd44fcb4d-xfw2x
+```