Skip to content

Commit 9dc44c7

Browse files
vepatelvepatel
authored
Update helm readme and website docs (#4476)
1 parent 5b31f15 commit 9dc44c7

File tree

3 files changed

+296
-13
lines changed

3 files changed

+296
-13
lines changed

‎deployments/helm-chart/README.md‎

Lines changed: 137 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@ This chart deploys the NGINX Ingress Controller in your Kubernetes cluster.
66

77
## Prerequisites
88

9+
**Note** All documentation should only be used with the latest stable release, indicated on
10+
[the releases page](https://github.com/nginxinc/kubernetes-ingress/releases) of the GitHub repository.
11+
912
- A [Kubernetes Version Supported by the Ingress
1013
Controller](https://docs.nginx.com/nginx-ingress-controller/technical-specifications/#supported-kubernetes-versions)
1114
- Helm 3.0+.
@@ -190,6 +193,131 @@ The command removes all the Kubernetes components associated with the release an
190193
Uninstalling the release does not remove the CRDs. To remove the CRDs, see [Uninstalling the
191194
CRDs](#uninstalling-the-crds).
192195

196+
## Upgrading without downtime
197+
198+
### Background
199+
200+
In NGINX Ingress Controller version 3.1.0, [changes were introduced](https://github.com/nginxinc/kubernetes-ingress/pull/3606)
201+
to Helm resource names, labels and annotations to fit with Helm best practices.
202+
When using Helm to upgrade from a version prior to 3.1.0, certain resources like Deployment, DaemonSet and Service will
203+
be recreated due to the aforementioned changes, which will result in downtime.
204+
205+
Although the advisory is to update all resources in accordance with new naming convention, to avoid the downtime
206+
please follow the steps listed in this page.
207+
208+
### Upgrade Steps
209+
210+
**Note** The following steps apply to both 2.x and 3.0.x releases.
211+
212+
The steps you should follow depend on the Helm release name:
213+
214+
{{<tabs>}}<!-- markdownlint-disable-line MD033 -->
215+
216+
{{%tab name="Helm release name is `nginx-ingress`"%}}
217+
218+
1. Use `kubectl describe` on deployment/daemonset to get the `Selector` value:
219+
220+
```shell
221+
kubectl describe deployments -n <namespace>
222+
```
223+
224+
Copy the key=value under `Selector`, such as:
225+
226+
```shell
227+
Selector: app=nginx-ingress-nginx-ingress
228+
```
229+
230+
2. Checkout the latest available tag using `git checkout v3.3.0`
231+
232+
3. Navigate to `/kubernates-ingress/deployments/helm-chart`
233+
234+
4. Update the `selectorLabels: {}` field in the `values.yaml` file located at `/kubernates-ingress/deployments/helm-chart`
235+
with the copied `Selector` value.
236+
237+
```shell
238+
selectorLabels: {app: nginx-ingress-nginx-ingress}
239+
```
240+
241+
5. Run `helm upgrade` with following arguments set:
242+
243+
```shell
244+
--set serviceNameOverride="nginx-ingress-nginx-ingress"
245+
--set controller.name=""
246+
--set fullnameOverride="nginx-ingress-nginx-ingress"
247+
```
248+
249+
It could look as follows:
250+
251+
```shell
252+
helm upgrade nginx-ingress oci://ghcr.io/nginxinc/charts/nginx-ingress --version 0.19.0 --set controller.kind=deployment/daemonset --set controller.nginxplus=false/true --set controller.image.pullPolicy=Always --set serviceNameOverride="nginx-ingress-nginx-ingress" --set controller.name="" --set fullnameOverride="nginx-ingress-nginx-ingress" -f values.yaml
253+
```
254+
255+
6. Once the upgrade process has finished, use `kubectl describe` on the deployment to verify the change by
256+
reviewing its events:
257+
258+
```shell
259+
Type Reason Age From Message
260+
---- ------ ---- ---- -------
261+
Normal ScalingReplicaSet 9m11s deployment-controller Scaled up replica set nginx-ingress-nginx-ingress-<old_version> to 1
262+
Normal ScalingReplicaSet 101s deployment-controller Scaled up replica set nginx-ingress-nginx-ingress-<new_version> to 1
263+
Normal ScalingReplicaSet 98s deployment-controller Scaled down replica set nginx-ingress-nginx-ingress-<old_version> to 0 from 1
264+
```
265+
266+
{{%/tab%}}
267+
268+
{{%tab name="Helm release name is not `nginx-ingress`"%}}
269+
270+
1. Use `kubectl describe` on deployment/daemonset to get the `Selector` value:
271+
272+
```shell
273+
kubectl describe deployment/daemonset -n <namespace>
274+
```
275+
276+
Copy the key=value under ```Selector```, such as:
277+
278+
```shell
279+
Selector: app=<helm_release_name>-nginx-ingress
280+
```
281+
282+
2. Checkout the latest available tag using `git checkout v3.3.0`
283+
284+
3. Navigate to `/kubernates-ingress/deployments/helm-chart`
285+
286+
4. Update the `selectorLabels: {}` field in the `values.yaml` file located at `/kubernates-ingress/deployments/helm-chart`
287+
with the copied `Selector` value.
288+
289+
```shell
290+
selectorLabels: {app: <helm_release_name>-nginx-ingress}
291+
```
292+
293+
5. Run `helm upgrade` with following arguments set:
294+
295+
```shell
296+
--set serviceNameOverride="<helm_release_name>-nginx-ingress"
297+
--set controller.name=""
298+
```
299+
300+
It could look as follows:
301+
302+
```shell
303+
helm upgrade test-release oci://ghcr.io/nginxinc/charts/nginx-ingress --version 0.19.0 --set controller.kind=deployment/daemonset --set controller.nginxplus=false/true --set controller.image.pullPolicy=Always --set serviceNameOverride="test-release-nginx-ingress" --set controller.name="" -f values.yaml
304+
```
305+
306+
6. Once the upgrade process has finished, use `kubectl describe` on the deployment to verify the change by
307+
reviewing its events:
308+
309+
```shell
310+
Type Reason Age From Message
311+
---- ------ ---- ---- -------
312+
Normal ScalingReplicaSet 9m11s deployment-controller Scaled up replica set test-release-nginx-ingress-<old_version> to 1
313+
Normal ScalingReplicaSet 101s deployment-controller Scaled up replica set test-release-nginx-ingress-<new_version> to 1
314+
Normal ScalingReplicaSet 98s deployment-controller Scaled down replica set test-release-nginx-ingress-<old_version> to 0 from 1
315+
```
316+
317+
{{%/tab%}}
318+
319+
{{</tabs>}}<!-- markdownlint-disable-line MD033 -->
320+
193321
## Running Multiple Ingress Controllers
194322

195323
If you are running multiple Ingress Controller releases in your cluster with enabled custom resources, the releases will
@@ -225,8 +353,8 @@ The following tables lists the configurable parameters of the NGINX Ingress Cont
225353
|`controller.config.annotations` | The annotations of the Ingress Controller configmap. | {} |
226354
|`controller.config.entries` | The entries of the ConfigMap for customizing NGINX configuration. See [ConfigMap resource docs](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/configmap-resource/) for the list of supported ConfigMap keys. | {} |
227355
|`controller.customPorts` | A list of custom ports to expose on the NGINX Ingress Controller pod. Follows the conventional Kubernetes yaml syntax for container ports. | [] |
228-
|`controller.defaultTLS.cert` | The base64-encoded TLS certificate for the default HTTPS server. **Note:** By default, a pre-generated self-signed certificate is used. It is recommended that you specify your own certificate. Alternatively, omitting the default server secret completely will configure NGINX to reject TLS connections to the default server. | A pre-generated self-signed certificate. |
229-
|`controller.defaultTLS.key` | The base64-encoded TLS key for the default HTTPS server. **Note:** By default, a pre-generated key is used. It is recommended that you specify your own key. Alternatively, omitting the default server secret completely will configure NGINX to reject TLS connections to the default server. | A pre-generated key. |
356+
|`controller.defaultTLS.cert` | The base64-encoded TLS certificate for the default HTTPS server. **Note:** It is recommended that you specify your own certificate. Alternatively, omitting the default server secret completely will configure NGINX to reject TLS connections to the default server. |
357+
|`controller.defaultTLS.key` | The base64-encoded TLS key for the default HTTPS server. **Note:** It is recommended that you specify your own key. Alternatively, omitting the default server secret completely will configure NGINX to reject TLS connections to the default server. |
230358
|`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. **Note:** Alternatively, omitting the default server secret completely will configure NGINX to reject TLS connections to the default server. | None |
231359
|`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 |
232360
|`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 |
@@ -329,10 +457,17 @@ The following tables lists the configurable parameters of the NGINX Ingress Cont
329457
|`prometheus.port` | Configures the port to scrape the metrics. | 9113 |
330458
|`prometheus.scheme` | Configures the HTTP scheme to use for connections to the Prometheus endpoint. | http |
331459
|`prometheus.secret` | The namespace / name of a Kubernetes TLS Secret. If specified, this secret is used to secure the Prometheus endpoint with TLS connections. | "" |
460+
|`prometheus.service.create` | Create a Headless service to expose prometheus metrics. Requires `prometheus.create`. | false |
461+
|`prometheus.service.labels` | Kubernetes object labels to attach to the service object. | {service: "nginx-ingress-prometheus-service"} |
462+
|`prometheus.serviceMonitor.create` | Create a ServiceMonitor custom resource. Requires ServiceMonitor CRD to be installed. For the latest CRD, check the latest release on the [prometheus-operator](https://github.com/prometheus-operator/prometheus-operator) GitHub repo under `example/prometheus-operator-crd/monitoring.coreos.com_servicemonitors.yaml` | false |
463+
|`prometheus.serviceMonitor.labels` | Kubernetes object labels to attach to the serviceMonitor object. | {} |
464+
|`prometheus.serviceMonitor.selectorMatchLabels` | A set of labels to allow the selection of endpoints for the ServiceMonitor. | {service: "nginx-ingress-prometheus-service"} |
465+
|`prometheus.serviceMonitor.endpoints` | A list of endpoints allowed as part of this ServiceMonitor. | [port: prometheus] |
332466
|`serviceInsight.create` | Expose NGINX Plus Service Insight endpoint. | false |
333467
|`serviceInsight.port` | Configures the port to expose endpoints. | 9114 |
334468
|`serviceInsight.scheme` | Configures the HTTP scheme to use for connections to the Service Insight endpoint. | http |
335469
|`serviceInsight.secret` | The namespace / name of a Kubernetes TLS Secret. If specified, this secret is used to secure the Service Insight endpoint with TLS connections. | "" |
470+
|`serviceNameOverride` | Used to prevent cloud load balancers from being replaced due to service name change during helm upgrades. | "" |
336471
|`nginxServiceMesh.enable` | Enable integration with NGINX Service Mesh. See the NGINX Service Mesh [docs](https://docs.nginx.com/nginx-service-mesh/tutorials/kic/deploy-with-kic/) for more details. Requires `controller.nginxplus`. | false |
337472
|`nginxServiceMesh.enableEgress` | Enable NGINX Service Mesh workloads to route egress traffic through the Ingress Controller. See the NGINX Service Mesh [docs](https://docs.nginx.com/nginx-service-mesh/tutorials/kic/deploy-with-kic/#enabling-egress) for more details. Requires `nginxServiceMesh.enable`. | false |
338473

0 commit comments

Comments
 (0)