8000 Extend docs and example about wildcard TLS secret (#2288) · nginx/kubernetes-ingress@54472e9 · GitHub
[go: up one dir, main page]
Skip to content

Commit 54472e9

Browse files
pleshakovpleshakov
authored
Extend docs and example about wildcard TLS secret (#2288)
1 parent e5bf0a7 commit 54472e9

File tree

7 files changed

+38
-43
lines changed

7 files changed

+38
-43
lines changed

‎cmd/nginx-ingress/main.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -142,8 +142,8 @@ var (
142142
`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)`)
143143

144144
wildcardTLSSecret = flag.String("wildcard-tls-secret", "",
145-
`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.
146-
Format: <namespace>/<name>. If the argument is not set, for such Ingress hosts NGINX will break any attempt to establish a TLS connection.
145+
`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.
146+
Format: <namespace>/<name>. If the argument is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection.
147147
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.`)
148148

149149
enablePrometheusMetrics = flag.Bool("enable-prometheus-metrics", false,

‎deployments/helm-chart/README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -162,9 +162,9 @@ Parameter | Description | Default
162162
`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.
163163
`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.
164164
`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
165-
`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
166-
`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
167-
`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
165+
`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
166+
`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
167+
`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
168168
`controller.nodeSelector` | The node selector for pod assignment for the Ingress controller pods. | {}
169169
`controller.terminationGracePeriodSeconds` | The termination grace period of the Ingress controller pod. | 30
170170
`controller.tolerations` | The tolerations of the Ingress controller pods. | []

‎deployments/helm-chart/values.yaml‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -80,15 +80,15 @@ controller:
8080
secret:
8181

8282
wildcardTLS:
83-
## The base64-encoded TLS certificate for every Ingress host that has TLS enabled but no secret specified.
84-
## If the parameter is not set, for such Ingress hosts NGINX will break any attempt to establish a TLS connection.
83+
## The base64-encoded TLS certificate for every Ingress/VirtualServer host that has TLS enabled but no secret specified.
84+
## If the parameter is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection.
8585
cert: ""
8686

87-
## The base64-encoded TLS key for every Ingress host that has TLS enabled but no secret specified.
88-
## If the parameter is not set, for such Ingress hosts NGINX will break any attempt to establish a TLS connection.
87+
## The base64-encoded TLS key for every Ingress/VirtualServer host that has TLS enabled but no secret specified.
88+
## If the parameter is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection.
8989
key: ""
9090

91-
## The secret with a TLS certificate and key for every Ingress host that has TLS enabled but no secret specified.
91+
## The secret with a TLS certificate and key for every Ingress/VirtualServer host that has TLS enabled but no secret specified.
9292
## The value must follow the following format: `<namespace>/<name>`.
9393
## Used as an alternative to specifying a certificate and key using `controller.wildcardTLS.cert` and `controller.wildcardTLS.key` parameters.
9494
## Format: <namespace>/<secret_name>

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,9 @@ Format: `<namespace>/<name>`
3838

3939
### -wildcard-tls-secret `<string>`
4040

41-
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.
41+
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.
4242

43-
* If the argument is not set, for such Ingress hosts NGINX will break any attempt to establish a TLS connection.
43+
* If the argument is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection.
4444

4545
* 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.
4646

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ redirect:
7373
{{% table %}}
7474
|Field | Description | Type | Required |
7575
| ---| ---| ---| --- |
76-
|``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 |
76+
|``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 |
7777
|``redirect`` | The redirect configuration of the TLS for a VirtualServer. | [tls.redirect](#virtualservertlsredirect) | No | ### VirtualServer.TLS.Redirect |
7878
{{% /table %}}
7979

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -168,9 +168,9 @@ The following tables lists the configurable parameters of the NGINX Ingress cont
168168
|``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. |
169169
|``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. |
170170
|``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 |
171-
|``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 |
172-
|``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 |
173-
|``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 |
171+
|``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 |
172+
|``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 |
173+
|``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 |
174174
|``controller.nodeSelector`` | The node selector for pod assignment for the Ingress controller pods. | {} |
175175
|``controller.terminationGracePeriodSeconds`` | The termination grace period of the Ingress controller pod. | 30 |
176176
|``controller.tolerations`` | The tolerations of the Ingress controller pods. | [] |

‎examples/wildcard-tls-certificate/README.md‎

Lines changed: 22 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
# Wildcard TLS Certificate
22

3-
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`).
3+
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`).
44

55
## Example
66

77
### Prerequisites
88

9-
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:
9+
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:
1010

1111
```yaml
1212
-wildcard-tls-secret=nginx-ingress/wildlcard-tls-secret
@@ -16,16 +16,16 @@ Start the Ingress Controller with the `-wildcard-tls-secret` [command-line argum
1616

1717
### Configuring TLS Termination
1818

19-
In the example below we configure TLS termination for two Ingress resources for the hosts `foo.example.com` and `bar.example.com` respectively:
19+
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`:
2020

21-
`foo-ingress` from the namespace `foo-namespace`:
21+
`foo` Ingress from the namespace `foo`:
2222

2323
```yaml
2424
apiVersion: networking.k8s.io/v1
2525
kind: Ingress
2626
metadata:
27-
name: foo-ingress
28-
namespace: foo-namespace
27+
name: foo
28+
namespace: foo
2929
annotati 6D4F ons:
3030
kubernetes.io/ingress.class: "nginx"
3131
spec:
@@ -45,31 +45,26 @@ spec:
4545
number: 80
4646
```
4747
48-
`bar-ingress` from the namespace `bar-namespace`:
48+
`bar` VirtualServer from the namespace `bar`:
4949

5050
```yaml
51-
apiVersion: networking.k8s.io/v1
52-
kind: Ingress
51+
apiVersion: k8s.nginx.org/v1
52+
kind: VirtualServer
5353
metadata:
54-
name: bar-ingress
55-
namespace: bar-namespace
56-
annotations:
57-
kubernetes.io/ingress.class: "nginx"
54+
name: bar
55+
namespace: bar
5856
spec:
57+
host: bar.example.com
5958
tls:
60-
- hosts:
61-
- bar.example.com
62-
rules:
63-
- host: bar.example.com
64-
http:
65-
paths:
66-
- path: /
67-
pathType: Prefix
68-
backend:
69-
service:
70-
name: bar-service
71-
port:
72-
number: 80
59+
secret: ""
60+
upstreams:
61+
- name: bar
62+
service: bar-service
63+
port: 80
64+
routes:
65+
- path: /
66+
action:
67+
pass: bar
7368
```
7469

75-
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.
70+
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.

0 commit comments

Comments
 (0)
0