Add tutorial doc for VirtualServer configuration with Custom Listener Ports

docs/content/configuration/global-configuration/globalconfiguration-resource.md

@@ -58,7 +58,8 @@ protocol: TCP
 | ---| ---| ---| --- |
 |``name`` | The name of the listener. Must be a valid DNS label as defined in RFC 1035. For example, ``hello`` and ``listener-123`` are valid. The name must be unique among all listeners. The name ``tls-passthrough`` is reserved for the built-in TLS Passthrough listener and cannot be used. | ``string`` | Yes |
 |``port`` | The port of the listener. The port must fall into the range ``1..65535`` with the following exceptions: ``80``, ``443``, the [status port](/nginx-ingress-controller/logging-and-monitoring/status-page), the [Prometheus metrics port](/nginx-ingress-controller/logging-and-monitoring/prometheus). Among all listeners, only a single combination of a port-protocol is allowed. | ``int`` | Yes |
-|``protocol`` | The protocol of the listener. Supported values: ``TCP`` and ``UDP``. | ``string`` | Yes |
+|``protocol`` | The protocol of the listener. Supported values: ``TCP``, ``UDP`` and ``HTTP``. | ``string`` | Yes |
+|``ssl`` | Configures the listener with SSL. This is currently only supported for ``HTTP`` listeners. Default value is ``false`` | ``bool`` | No |
 {{% /table %}}
 
 ## Using GlobalConfiguration

docs/content/configuration/virtualserver-and-virtualserverroute-resources.md

@@ -25,6 +25,9 @@ metadata:
   name: cafe
 spec:
   host: cafe.example.com
+  listener:
+    http: http-8083
+    https: https-8443
   tls:
     secret: cafe-secret
   gunzip: on
@@ -54,6 +57,7 @@ spec:
 |Field | Description | Type | Required |
 | ---| ---| ---| --- |
 |``host`` | The host (domain name) of the server. Must be a valid subdomain as defined in RFC 1123, such as ``my-app`` or ``hello.example.com``. When using a wildcard domain like ``*.example.com`` the domain must be contained in double quotes.  The ``host`` value needs to be unique among all Ingress and VirtualServer resources. See also [Handling Host and Listener Collisions](/nginx-ingress-controller/configuration/handling-host-and-listener-collisions). | ``string`` | Yes |
+|``listener`` | Sets a custom HTTP and/or HTTPS listener. Must reference the name of a listener defined in a GlobalConfiguration resource | [listener](#virtualserverlistener) | No |
 |``tls`` | The TLS termination configuration. | [tls](#virtualservertls) | No |
 |``gunzip`` | Enables or disables [decompression](https://docs.nginx.com/nginx/admin-guide/web-server/compression/) of gzipped responses for clients. Allowed values “on”/“off”, “true”/“false” or “yes”/“no”. If the ``gunzip`` value is not set, it defaults to ``off``.   | ``boolean`` | No |
 |``externalDNS`` | The externalDNS configuration for a VirtualServer. | [externalDNS](#virtualserverexternaldns) | No |
@@ -125,6 +129,22 @@ cert-manager:
 |``usages`` |  This field allows you to configure spec.usages field for the Certificate to be generated. Pass a string with comma-separated values i.e. ``key agreement,digital signature, server auth``. An exhaustive list of supported key usages can be found in the [the cert-manager api documentation](https://cert-manager.io/docs/reference/api-docs/#cert-manager.io/v1.KeyUsage). | ``string`` | No |
 {{% /table %}}
 
+### VirtualServer.Listener
+The listener field defines a custom HTTP and/or HTTPS listener.
+The respective listeners used must reference the name of a listener defined using a [GlobalConfiguration](/nginx-ingress-controller/configuration/global-configuration/globalconfiguration-resource/) resource.
+For example:
+```yaml
+http: http-8083
+https: https-8443
+```
+
+{{% table %}}
+|Field | Description | Type | Required |
+| ---| ---| ---| --- |
+|``http`` |  The name of am HTTP listener defined in a [GlobalConfiguration](/nginx-ingress-controller/configuration/global-configuration/globalconfiguration-resource/) resource. | ``string`` | No |
+|``https`` |  The name of an HTTPS listener defined in a [GlobalConfiguration](/nginx-ingress-controller/configuration/global-configuration/globalconfiguration-resource/) resource. | ``string`` | No |
+{{% /table %}}
+
 ### VirtualServer.ExternalDNS
 
 The externalDNS field configures controlling DNS records dynamically for VirtualServer resources using [ExternalDNS](https://github.com/kubernetes-sigs/external-dns). Please see the [ExternalDNS configuration documentation](https://kubernetes-sigs.github.io/external-dns/v0.12.0/) for more information on deploying and configuring ExternalDNS and Providers. Example:

docs/content/tutorials/virtual-server-with-custom-listener-ports.md

@@ -0,0 +1,171 @@
+---
+title: VirtualServer with Custom listener ports
+description: |
+  How to configure a VirtualServer with custom HTTP and HTTPS listener ports.
+weight: 1800
+doctypes: ["concept"]
+toc: true
+---
+## Configuring a VirtualServer with custom HTTP and HTTPS listener ports.
+
+This tutorial outlines how to configure and deploy a VirtualServer resource to with custom HTTP and HTTPS listener ports.
+Previously this was task had to be performed manually as documented in [Customizing NGINX Ingress Controller Ports](/nginx-ingress-controller/tutorials/custom-listen-ports/).
+
+VirtualServer now explicitly defines custom HTTP and HTTPS listener ports using the `spec.listener.http` and `spec.listener.https` fields.
+Each field must reference a valid listener defined by in a [GlobalConfiguration](/nginx-ingress-controller/configuration/global-configuration/globalconfiguration-resource/) resource.
+
+## Deploy GlobalConfiguration
+
+1. Create a yaml file called `nginx-configuration.yaml` with the below content:
+```yaml
+apiVersion: k8s.nginx.org/v1alpha1
+kind: GlobalConfiguration
+metadata:
+  name: nginx-configuration
+  namespace: nginx-ingress
+spec:
+  listeners:
+  - name: http-8083
+    port: 8083
+    protocol: HTTP
+  - name: https-8443
+    port: 8443
+    protocol: HTTP
+    ssl: true
+```
+
+2. Deploy `nginx-configuration.yaml` file:
+```console
+kubectl apply -f nginx-configuration.yaml
+```
+
+## Deploying NGINX Ingress Controller with GlobalConfiguration resource
+
+### Manifest
+
+1. Add the below argument to the manifest file of the NGINX Ingress Controller:
+```yaml
+args:
+  - -$(POD_NAMESPACE)/nginx-configuration
+```
+
+2. Follow the [installation](/nginx-ingress-controller/installation/installation-with-manifests/) instructions to deploy the NGINX Ingress Controller with custom resources enabled.
+
+3. If you have a NodePort service or Loabalancer service deployed, these will need to be configured to expose the custom listener ports. Below is an example yaml using NodePort. This same configuration will also apply to a Loadbalancer service:
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: nginx-ingress
+  namespace: nginx-ingress
+spec:
+  type: NodePort
+  ports:
+  - port: 8083
+    targetPort: 8083 # Custom HTTP listener port
+    protocol: TCP
+    name: http-8083
+  - port: 8443
+    targetPort: 8443 # Custom HTTPS listener port
+    protocol: TCP
+    name: https-8443
+  selector:
+    app: nginx-ingress
+
+```
+
+### HELM
+1. Add the below content to your `values.yaml` file in `controller.globalConfiguration`:
+```yaml
+spec:
+  listeners:
+  - name: http-8083
+    port: 8083
+    protocol: HTTP
+  - name: https-8443
+    port: 8443
+    protocol: HTTP
+    ssl: true
+```
+
+2. Ensure your NodePort or Loadbalancer service is configured to expose the custom listener ports. This is set in the `customPorts` section under `controller.service.customPorts`
+```yaml
+customPorts:
+  - name: http-8083
+    port: 8083
+    protocol: TCP
+    targetPort: 8083
+  - name: https-8443
+    port: 8443
+    protocol: TCP
+    targetPort: 8443
+```
+
+3. Follow the [HELM installation](/nginx-ingress-controller/installation/installation-with-helm/) instructions to deploy the NGINX Ingress Controller with custom resources enabled.
+
+## Deploying VirtualServer with custom listeners
+Deploy the example resources in the [custom listeners](/examples/custom-resources/custom-listeners/) folder. This will deploy all the required resources, including the VirtualServer.
+
+Below is a snippet of the VirtualServer resource that will be deployed:
+```yaml
+apiVersion: k8s.nginx.org/v1
+kind: VirtualServer
+metadata:
+  name: cafe
+spec:
+  listener:
+    http: http-8083
+    https: https-8443
+  host: cafe.example.com
+  tls:
+    secret: cafe-secret
+  upstreams:
+    ...
+```
+
+Below is a snippet of the NGINX configuration for this VirtualServer.
+
+```nginx
+server {
+    listen 8083;
+    listen [::]:8083;
+
+    server_name cafe.example.com;
+
+    set $resource_type "virtualserver";
+    set $resource_name "cafe";
+    set $resource_namespace "default";
+
+    listen 8443 ssl;
+    listen [::]:8443 ssl;
+
+    ssl_certificate /etc/nginx/secrets/default-cafe-secret;
+    ssl_certificate_key /etc/nginx/secrets/default-cafe-secret;
+}
+```
+
+## Testing custom listener ports
+
+Since the VirtualServer resource is deployed with non-default ports, these ports must be explicitly specified when sending requests.
+
+`curl` using port `8443`:
+```console
+curl -k https://cafe.example.com:8443/coffee
+
+Server address: 10.32.0.40:8080
+Server name: coffee-7dd75bc79b-qmhmv
+...
+URI: /coffee
+...
+```
+
+`curl` using port `8083`:
+```console
+curl -k http://cafe.example.com:8083/coffee
+
+Server address: 10.32.0.40:8080
+Server name: coffee-7dd75bc79b-qmhmv
+...
+URI: /coffee
+...
+```