Skip to content

Commit 995d37f

Browse files
ADubhlaoichADubhlaoich
authored
feat: Rework Helm installation for NGINX Ingress Controller (#1500)
This commit re-works the information for installing Helm from a singular document covering all use cases and information into its own section, delineating installation into NGINX Open Source and NGINX Plus. The chart parameters and uninstall instructions have also been added to their own pages. Example output has been added for instructional steps, and information involving conditional usage of a private registry has been removed, reflecting the majority of contemporary usage. Additionally, there is now a "Quickstart" section of "Before you begin" under the NGINX Plus use case reflecting the shortest possible path to a functional installation if the user already has the requirements and context. NGINX Open Source does not include a quickstart due to the reduced amount of steps involved. The Install section has been re-ordered to reflect usage, and may be subject to more restructuring as this pattern is applied to onboarding documentation.
1 parent 6f98cd8 commit 995d37f

File tree

12 files changed

+563
-182
lines changed

12 files changed

+563
-182
lines changed

‎content/nic/_index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,10 @@ It supports standard [Ingress]({{< ref "/nic/glossary.md#ingress">}}) features s
2727
## Featured content
2828

2929
{{<card-section showAsCards="true" isFeaturedSection="true">}}
30-
{{<card title="Install NGINX Ingress Controller with Helm" titleUrl="/nginx-ingress-controller/installation/installing-nic/installation-with-helm">}}
30+
{{<card title="Install NGINX Ingress Controller with Helm" titleUrl="/nginx-ingress-controller/install/helm">}}
3131
Use Helm to deploy and configure a NGINX Ingress Controller cluster
3232
{{</card>}}
33-
{{<card title="Migrate from Ingress-NGINX Controller" titleUrl="/nginx-ingress-controller/installation/ingress-nginx">}}
33+
{{<card title="Migrate from Ingress-NGINX Controller" titleUrl="/nginx-ingress-controller/install/ingress-nginx">}}
3434
Replace an Ingress-NGINX cluster with NGINX Ingress Controller
3535
{{</card>}}
3636
{{<card title="Changelog" titleUrl="/nginx-ingress-controller/changelog">}}

‎content/nic/install/helm/_index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: Helm
3+
weight: 100
4+
url: /nginx-ingress-controller/install/helm/
5+
---

‎content/nic/install/helm/open-source.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
title: Use Helm to Install NGINX Ingress Controller with NGINX Open Source
3+
linkTitle: NGINX Open Source
4+
toc: true
5+
weight: 100
6+
nd-content-type: how-to
7+
nd-product: INGRESS
8+
---
9+
10+
This page describes how to use Helm to install F5 NGINX Ingress Controller with NGINX Open Source.
11+
12+
It explains the requirements for NGINX Ingress Controller, how to obtain and install the Helm chart, and what custom resource definitions (CRDs) are installed during the process.
13+
14+
By following these instructions, you will finish with a functional NGINX Ingress Controller instance for your Kubernetes cluster.
15+
16+
## Before you begin
17+
18+
- A [supported Kubernetes version]({{< ref "/nic/technical-specifications.md#supported-kubernetes-versions" >}})
19+
- A functional Kubernetes cluster
20+
- [Helm 3.19+.](https://helm.sh/docs/intro/install)
21+
22+
Throughout this page, you will see placeholder values indicated with angular brackets, such as **\<my-release\>**. Replace them accordingly for your installation.
23+
24+
{{< call-out "warning" >}}
25+
26+
The `edge` version **is not intended for production use**. It is intended for testing and development purposes only.
27+
28+
{{< /call-out >}}
29+
30+
If you'd like to test the latest changes in NGINX Ingress Controller before a new release, you can install the `edge` version, which is built from the `main` branch of the [NGINX Ingress Controller repository](https://github.com/nginx/kubernetes-ingress).
31+
32+
You can install the `edge` version by specifying the `--version` flag with the value `0.0.0-edge`:
33+
34+
```shell
35+
helm install <my-release> oci://ghcr.io/nginx/charts/nginx-ingress --version 0.0.0-edge
36+
```
37+
38+
## Install the Helm chart
39+
40+
You have two options for installing the Helm chart: directly from the OCI registry, or using the source.
41+
42+
### OCI Registry
43+
44+
To install NGINX Ingress Controller using the OCI registry, run this command with your release name:
45+
46+
```shell
47+
helm install <my-release> oci://ghcr.io/nginx/charts/nginx-ingress --version {{< nic-helm-version >}}
48+
```
49+
50+
{{< details summary="Example output" >}}
51+
52+
```text
53+
Pulled: ghcr.io/nginx/charts/nginx-ingress:2.3.1
54+
Digest: sha256:bb452d593c31b6be39f459f9604882e170227429821bac01e7ddd7da16d91ba1
55+
NAME: h4-oss
56+
LAST DEPLOYED: Fri Nov 28 11:53:57 2025
57+
NAMESPACE: default
58+
STATUS: deployed
59+
REVISION: 1
60+
DESCRIPTION: Install complete
61+
TEST SUITE: None
62+
NOTES:
63+
NGINX Ingress Controller 5.2.1 has been installed.
64+
65+
For release notes for this version please see: https://docs.nginx.com/nginx-ingress-controller/releases/
66+
67+
Installation and upgrade instructions: https://docs.nginx.com/nginx-ingress-controller/installation/installing-nic/installation-with-helm/
68+
```
69+
70+
{{< /details >}}
71+
72+
### From source
73+
74+
To install NGINX Ingress Controller from source, first pull the chart by running this command:
75+
76+
```shell
77+
helm pull oci://ghcr.io/nginx/charts/nginx-ingress --untar --version {{< nic-helm-version >}}
78+
```
79+
80+
{{< details summary="Example output" >}}
81+
82+
```text
83+
Pulled: ghcr.io/nginx/charts/nginx-ingress:2.3.1
84+
Digest: sha256:bb452d593c31b6be39f459f9604882e170227429821bac01e7ddd7da16d91ba1
85+
```
86+
87+
{{< /details >}}
88+
89+
Then use the `cd` command to change your working directory to _nginx-ingress_:
90+
91+
```shell
92+
cd nginx-ingress
93+
```
94+
95+
Finally, install the chart with your release name with `helm install`:
96+
97+
```shell
98+
helm install <my-release> .
99+
```
100+
101+
{{< details summary="Example output" >}}
102+
103+
```text
104+
NAME: h4-oss-source
105+
LAST DEPLOYED: Fri Nov 28 12:06:07 2025
106+
NAMESPACE: default
107+
STATUS: deployed
108+
REVISION: 1
109+
DESCRIPTION: Install complete
110+
TEST SUITE: None
111+
NOTES:
112+
NGINX Ingress Controller 5.2.1 has been installed.
113+
114+
For release notes for this version please see: https://docs.nginx.com/nginx-ingress-controller/releases/
115+
116+
Installation and upgrade instructions: https://docs.nginx.com/nginx-ingress-controller/installation/installing-nic/installation-with-helm/
117+
```
118+
119+
{{< /details >}}
120+
121+
## Verify the deployment
122+
123+
To verify that NGINX Ingress Controller has been installed correctly, you can review `ingressclasses` with `kubectl get`:
124+
125+
```shell
126+
kubectl get ingressclasses
127+
```
128+
129+
{{< details summary="Example output" >}}
130+
131+
```text
132+
NAME CONTROLLER PARAMETERS AGE
133+
nginx nginx.org/ingress-controller <none> 10m
134+
```
135+
136+
{{< /details >}}
137+
138+
## Custom Resource Definitions
139+
140+
When installing the chart, Helm will install the required CRDs. Without them, NGINX Ingress Controller pods will not become _Ready_.
141+
142+
If you do not use the custom resources that require those CRDs, add the parameter `--skip-crds` in your `helm install` command.
143+
144+
The following chart parameters should be set to `false`:
145+
146+
- `controller.enableCustomResources`
147+
- `controller.appprotect.enable`
148+
- `controller.appprotectdos.enable`
149+
150+
## Next steps
151+
152+
- [NGINX Ingress Controller Helm chart parameters]({{< ref "/nic/install/helm/parameters.md" >}})
153+
- [Security recommendations]({{< ref "/nic/configuration/security.md" >}})
154+
- [Basic configuration]({{< ref "/nic/configuration/ingress-resources/basic-configuration.md" >}})
155+
- [Extensibility with NGINX Plus]({{< ref "/nic/overview/nginx-plus.md" >}})

0 commit comments

Comments
 (0)