Extend docs and example about wildcard TLS secret

cmd/nginx-ingress/main.go

@@ -142,8 +142,8 @@ var (
 		`The timeout in milliseconds which the Ingress Controller will wait for a successful NGINX reload after a change or at the initial start. (default 60000)`)
 
 	wildcardTLSSecret = flag.String("wildcard-tls-secret", "",
-		`A Secret with a TLS certificate and key for TLS termination of every Ingress host for which TLS termination is enabled but the Secret is not specified.
-		Format: <namespace>/<name>. If the argument is not set, for such Ingress hosts NGINX will break any attempt to establish a TLS connection.
+		`A Secret with a TLS certificate and key for TLS termination of every Ingress/VirtualServer host for which TLS termination is enabled but the Secret is not specified.
+		Format: <namespace>/<name>. If the argument is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection.
 		If the argument is set, but the Ingress controller is not able to fetch the Secret from Kubernetes API, the Ingress controller will fail to start.`)
 
 	enablePrometheusMetrics = flag.Bool("enable-prometheus-metrics", false,

deployments/helm-chart/README.md

@@ -162,9 +162,9 @@ Parameter | Description | Default
 `controller.defaultTLS.cert` | The base64-encoded TLS certificate for the default HTTPS server. If not specified, a pre-generated self-signed certificate is used. **Note:** It is recommended that you specify your own certificate. | A pre-generated self-signed certificate.
 `controller.defaultTLS.key` | The base64-encoded TLS key for the default HTTPS server. **Note:** If not specified, a pre-generated key is used. It is recommended that you specify your own key. | A pre-generated key.
 `controller.defaultTLS.secret` | The secret with a TLS certificate and key for the default HTTPS server. The value must follow the following format: `<namespace>/<name>`. Used as an alternative to specifying a certificate and key using `controller.defaultTLS.cert` and `controller.defaultTLS.key` parameters. | None
-`controller.wildcardTLS.cert` | The base64-encoded TLS certificate for every Ingress host that has TLS enabled but no secret specified. If the parameter is not set, for such Ingress hosts NGINX will break any attempt to establish a TLS connection. | None
-`controller.wildcardTLS.key` | The base64-encoded TLS key for every Ingress host that has TLS enabled but no secret specified. If the parameter is not set, for such Ingress hosts NGINX will break any attempt to establish a TLS connection. | None
-`controller.wildcardTLS.secret` | The secret with a TLS certificate and key for every Ingress host that has TLS enabled but no secret specified. The value must follow the following format: `<namespace>/<name>`. Used as an alternative to specifying a certificate and key using `controller.wildcardTLS.cert` and `controller.wildcardTLS.key` parameters. | None
+`controller.wildcardTLS.cert` | The base64-encoded TLS certificate for every Ingress/VirtualServer host that has TLS enabled but no secret specified. If the parameter is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection. | None
+`controller.wildcardTLS.key` | The base64-encoded TLS key for every Ingress/VirtualServer host that has TLS enabled but no secret specified. If the parameter is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection. | None
+`controller.wildcardTLS.secret` | The secret with a TLS certificate and key for every Ingress/VirtualServer host that has TLS enabled but no secret specified. The value must follow the following format: `<namespace>/<name>`. Used as an alternative to specifying a certificate and key using `controller.wildcardTLS.cert` and `controller.wildcardTLS.key` parameters. | None
 `controller.nodeSelector` | The node selector for pod assignment for the Ingress controller pods. | {}
 `controller.terminationGracePeriodSeconds` | The termination grace period of the Ingress controller pod. | 30
 `controller.tolerations` | The tolerations of the Ingress controller pods. | []

deployments/helm-chart/values.yaml

@@ -80,15 +80,15 @@ controller:
     secret:
 
   wildcardTLS:
-    ## The base64-encoded TLS certificate for every Ingress host that has TLS enabled but no secret specified.
-    ## If the parameter is not set, for such Ingress hosts NGINX will break any attempt to establish a TLS connection.
+    ## The base64-encoded TLS certificate for every Ingress/VirtualServer host that has TLS enabled but no secret specified.
+    ## If the parameter is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection.
     cert: ""
 
-    ## The base64-encoded TLS key for every Ingress host that has TLS enabled but no secret specified.
-    ## If the parameter is not set, for such Ingress hosts NGINX will break any attempt to establish a TLS connection.
+    ## The base64-encoded TLS key for every Ingress/VirtualServer host that has TLS enabled but no secret specified.
+    ## If the parameter is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection.
     key: ""
 
-    ## The secret with a TLS certificate and key for every Ingress host that has TLS enabled but no secret specified.
+    ## The secret with a TLS certificate and key for every Ingress/VirtualServer host that has TLS enabled but no secret specified.
     ## The value must follow the following format: `<namespace>/<name>`.
     ## Used as an alternative to specifying a certificate and key using `controller.wildcardTLS.cert` and `controller.wildcardTLS.key` parameters.
     ## Format: <namespace>/<secret_name>

docs/content/configuration/global-configuration/command-line-arguments.md

@@ -38,9 +38,9 @@ Format: `<namespace>/<name>`
 
 ### -wildcard-tls-secret `<string>`
 
-A Secret with a TLS certificate and key for TLS termination of every Ingress host for which TLS termination is enabled but the Secret is not specified.
+A Secret with a TLS certificate and key for TLS termination of every Ingress/VirtualServer host for which TLS termination is enabled but the Secret is not specified.
 
-* If the argument is not set, for such Ingress hosts NGINX will break any attempt to establish a TLS connection.
+* If the argument is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection.
 
 * If the argument is set, but the Ingress controller is not able to fetch the Secret from Kubernetes API, the Ingress controller will fail to start.
 

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

@@ -73,7 +73,7 @@ redirect:
 {{% table %}}
 |Field | Description | Type | Required |
 | ---| ---| ---| --- |
-|``secret`` | The name of a secret with a TLS certificate and key. The secret must belong to the same namespace as the VirtualServer. The secret must be of the type ``kubernetes.io/tls`` and contain keys named ``tls.crt`` and ``tls.key`` that contain the certificate and private key as described [here](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls). If the secret doesn't exist or is invalid, NGINX will break any attempt to establish a TLS connection to the host of the VirtualServer. | ``string`` | No |
+|``secret`` | The name of a secret with a TLS certificate and key. The secret must belong to the same namespace as the VirtualServer. The secret must be of the type ``kubernetes.io/tls`` and contain keys named ``tls.crt`` and ``tls.key`` that contain the certificate and private key as described [here](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls). If the secret doesn't exist or is invalid, NGINX will break any attempt to establish a TLS connection to the host of the VirtualServer. If the secret is not specified but [wildcard TLS secret](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments#cmdoption-wildcard-tls-secret) is configured, NGINX will use the wildcard secret for TLS termination. | ``string`` | No |
 |``redirect`` | The redirect configuration of the TLS for a VirtualServer. | [tls.redirect](#virtualservertlsredirect) | No | ### VirtualServer.TLS.Redirect |
 {{% /table %}}
 

docs/content/installation/installation-with-helm.md

@@ -168,9 +168,9 @@ The following tables lists the configurable parameters of the NGINX Ingress cont
 |``controller.defaultTLS.cert`` | The base64-encoded TLS certificate for the default HTTPS server. If not specified, a pre-generated self-signed certificate is used. **Note:** It is recommended that you specify your own certificate. | A pre-generated self-signed certificate. | 
 |``controller.defaultTLS.key`` | The base64-encoded TLS key for the default HTTPS server. **Note:** If not specified, a pre-generated key is used. It is recommended that you specify your own key. | A pre-generated key. | 
 |``controller.defaultTLS.secret`` | The secret with a TLS certificate and key for the default HTTPS server. The value must follow the following format: ``<namespace>/<name>``. Used as an alternative to specifying a certificate and key using ``controller.defaultTLS.cert`` and ``controller.defaultTLS.key`` parameters. | None | 
-|``controller.wildcardTLS.cert`` | The base64-encoded TLS certificate for every Ingress host that has TLS enabled but no secret specified. If the parameter is not set, for such Ingress hosts NGINX will break any attempt to establish a TLS connection. | None | 
-|``controller.wildcardTLS.key`` | The base64-encoded TLS key for every Ingress host that has TLS enabled but no secret specified. If the parameter is not set, for such Ingress hosts NGINX will break any attempt to establish a TLS connection. | None | 
-|``controller.wildcardTLS.secret`` | The secret with a TLS certificate and key for every Ingress host that has TLS enabled but no secret specified. The value must follow the following format: ``<namespace>/<name>``. Used as an alternative to specifying a certificate and key using ``controller.wildcardTLS.cert`` and ``controller.wildcardTLS.key`` parameters. | None | 
+|``controller.wildcardTLS.cert`` | The base64-encoded TLS certificate for every Ingress/VirtualServer host that has TLS enabled but no secret specified. If the parameter is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection. | None | 
+|``controller.wildcardTLS.key`` | The base64-encoded TLS key for every Ingress/VirtualServer host that has TLS enabled but no secret specified. If the parameter is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection. | None | 
+|``controller.wildcardTLS.secret`` | The secret with a TLS certificate and key for every Ingress/VirtualServer host that has TLS enabled but no secret specified. The value must follow the following format: ``<namespace>/<name>``. Used as an alternative to specifying a certificate and key using ``controller.wildcardTLS.cert`` and ``controller.wildcardTLS.key`` parameters. | None | 
 |``controller.nodeSelector`` | The node selector for pod assignment for the Ingress controller pods. | {} | 
 |``controller.terminationGracePeriodSeconds`` | The termination grace period of the Ingress controller pod. | 30 | 
 |``controller.tolerations`` | The tolerations of the Ingress controller pods. | [] | 

examples/wildcard-tls-certificate/README.md

@@ -1,12 +1,12 @@
 # Wildcard TLS Certificate
 
-The wildcard TLS certificate simplifies the configuration of TLS termination if you need to use the same TLS certificate in multiple Ingress resources from various namespaces. Typically, such a certificate is for a subdomain (for example, `*.example.com`), while the hosts in the Ingress resources include that subdomain (for example, `foo.example.com`, `bar.example.com`).
+The wildcard TLS certificate simplifies the configuration of TLS termination if you need to use the same TLS certificate in multiple Ingress and VirtualServer resources from various namespaces. Typically, such a certificate is for a subdomain (for example, `*.example.com`), while the hosts in the Ingress and VirtualServer resources include that subdomain (for example, `foo.example.com`, `bar.example.com`).
 
 ## Example
 
 ### Prerequisites
 
-Start the Ingress Controller with the `-wildcard-tls-secret` [command-line argument](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/command-line-arguments/) set to a TLS secret with a wildcard cert/key. For example:
+Start the Ingress Controller with the `-wildcard-tls-secret` [command-line argument](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/command-line-arguments/#cmdoption-wildcard-tls-secret) set to a TLS secret with a wildcard cert/key. For example:
 
 ```yaml
 -wildcard-tls-secret=nginx-ingress/wildlcard-tls-secret
@@ -16,16 +16,16 @@ Start the Ingress Controller with the `-wildcard-tls-secret` [command-line argum
 
 ### Configuring TLS Termination
 
-In the example below we configure TLS termination for two Ingress resources for the hosts `foo.example.com` and `bar.example.com` respectively:
+In the example below we configure TLS termination for an Ingress for the host `foo.example.com` and a VirtualServer for the host `bar.example.com`:
 
-`foo-ingress` from the namespace `foo-namespace`:
+`foo` Ingress from the namespace `foo`:
 
  ```yaml
 apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
-  name: foo-ingress
-  namespace: foo-namespace
+  name: foo
+  namespace: foo
   annotations:
     kubernetes.io/ingress.class: "nginx"
 spec:
@@ -45,31 +45,26 @@ spec:
               number: 80
  ```
 
-`bar-ingress` from the namespace `bar-namespace`:
+`bar` VirtualServer from the namespace `bar`:
 
 ```yaml
-apiVersion: networking.k8s.io/v1
-kind: Ingress
+apiVersion: k8s.nginx.org/v1
+kind: VirtualServer
 metadata:
-  name: bar-ingress
-  namespace: bar-namespace
-  annotations:
-    kubernetes.io/ingress.class: "nginx"
+  name: bar
+  namespace: bar
 spec:
+  host: bar.example.com
   tls:
-  - hosts:
-    - bar.example.com
-  rules:
-  - host: bar.example.com
-    http:
-      paths:
-      - path: /
-        pathType: Prefix
-        backend:
-          service:
-            name: bar-service
-            port:
-              number: 80
+    secret: "" 
+  upstreams:
+  - name: bar 
+    service: bar-service
+    port: 80
+  routes:
+  - path: /
+    action:
+      pass: bar
 ```
 
-Because we don't reference any TLS secret in the `tls` section (there is no `secretName` field) in both Ingress resources, NGINX will use the wildcard secret specified in the `-wildcard-tls-secret` command-line argument.
+Because we don't reference any TLS secret in the resources above -- there is no `secret` field in the `tls` section of the Ingress resource and the `secret` field is empty in the VirtualServer -- NGINX will use the wildcard secret specified in the `-wildcard-tls-secret` command-line argument.