# ingress-nginx

**NOTE**: This version is for Kubernetes version >= 1.22.0. Please use `ack-ingress-nginx` for 1.18.0 and below. Please note to change the parameters `controller.ingressClassResource.name` and `controller.ingressClassResource.controllerValue` to unique values when using.

**NOTE:** If you want delete annotations of service from default values (eg. `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-address-type`), please set the annotation value to `null` instead of removing it directly.

[ingress-nginx](https://github.com/kubernetes/ingress-nginx) Ingress controller for Kubernetes using NGINX as a reverse proxy and load balancer

To use, add `ingressClassName: nginx` spec field or the `kubernetes.io/ingress.class: nginx` annotation to your Ingress resources.

This chart bootstraps an ingress-nginx deployment on a [Kubernetes](http://kubernetes.io) cluster using the [Helm](https://helm.sh) package manager.

## Release Note

| 镜像版本              | Chart 版本 | 变更时间       | 变更内容                                                                                                                                                                                                                                                                                                                                                                                                   |
|-------------------|----------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `v1.9.3-aliyun.1` | `4.0.19` | 2024-7-24  | Disable the feature of adding snippets in annotations by default; To mitigate CVE-2023-5044, join the --enable-annotation-validation parameter, which enables annotation validation by default.                                                                                                                                                                                                        |
| `v1.8.0-aliyun.1` | `4.0.18` | 2023-10-24 | Remove `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-instance-charge-type` annotation of service from default values.                                                                                                                                                                                                                                                                         |
| `v1.8.0-aliyun.1` | `4.0.17` | 2023-06-20 | **Support only ACK clusters that run Kubernetes 1.22.0 or later.** Upgrade the Alpine image version to 1.18;  Add `strict-validate-path-type` configuration option for strict path validation (currently disabled by default); Fix vulnerabilities such as CVE-2023-28322 and CVE-2023-2650.                                                                                                           |
| `v1.2.1-aliyun.1` | `4.0.16` | 2022-08-30 | Default service type set to `NodePort` for edge clusters.                                                                                                                                                                                                                                                                                                                                              |
| `v1.2.1-aliyun.1` | `4.0.15` | 2022-07-11 | The `alias` and `root` directives are deleted to reduce the potential risks; Some stability issues are fixed.                                                                                                                                                                                                                                                                                          |
| `v1.2.0-aliyun.1` | `4.0.14` | 2022-05-30 | The deep inspection feature for Ingresses is added and enabled by default. This feature can prevent you from configuring Ingresses that contain sensitive fields. This feature fixes the CVE-2021-25745 vulnerability; Some stability issues are fixed.                                                                                                                                                |
| `v1.1.2-aliyun.2` | `4.0.13` | 2022-04-15 | Support edge clusters.                                                                                                                                                                                                                                                                                                                                                                                 |
| `v1.1.2-aliyun.2` | `4.0.12` | 2022-04-12 | Fix crashes when the `cors-allow-origin`configuration is invalid; Fix the Ingresses that use the same webhook URL conflict with each other when the system checks the webhook URLs of the Ingresses that belong to different IngressClasses; Fix the InitContainer modifies the kernel parameters of nodes if hostNetwork is set to true; CVE-2022-0778 and CVE-2022-23308 vulnerabilities are patched. |
| `v1.1.0-aliyun.2` | `4.0.11` | 2022-03-18 | Support Edge cluster initially；fix the conflicts during primary Ingress controller election.                                                                                                                                                                                                                                                                                                           |
| `v1.1.0-aliyun.2` | `4.0.10` | 2022-01-12 | The AHAS Sentinel plug-in is updated and the Java module is replaced by the C++ module. This greatly improves performance; Protocol Buffers (Protobuf) is used to communicate with the Kubernetes API server of a cluster. This improves communication efficiency.                                                                                                                                     |
| `v1.1.0-aliyun.1` | `4.0.10` | 2021-12-17 | Networking v1 Ingresses are used to support ACK clusters that run Kubernetes 1.22 and later.                                                                                                                                                                                                                                                                                                           |

For more information, please see [Nginx Ingress Controller Release Notes](https://www.alibabacloud.com/help/en/container-service-for-kubernetes/latest/nginx-ingress-controller).

## Major parameters

| **Parameter**                                   | **Description**                                                                                                                                                                                                                                                                                                                                           |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| controller.image.repository                     | The image registry of ingress-nginx.                                                                                                                                                                                                                                                                                                                      |
| controller.image.tag                            | The image version of ingress-nginx. For more information, see [Nginx Ingress Controller](https://www.alibabacloud.com/help/en/container-service-for-kubernetes/latest/nginx-ingress-controller#concept-2461414).                                                                                                                                          |
| controller.ingressClassResource.name            | The Ingress class of the Ingress controller. The Ingress controller handles only the Ingresses that are annotated with the Ingress class. **The Ingress class of each Ingress controller must be unique within a cluster. The Ingress class of the default Ingress controller in a cluster is `nginx`. Therefore, do not set this parameter to `nginx`.** |
| controller.ingressClassResource.controllerValue | The controller class of the Ingress controller. **The controller class of each Ingress controller must be unique within a cluster. The controller class of the default Ingress controller in a cluster is `k8s.io/ingress-nginx`. Therefore, do not set this parameter to `k8s.io/ingress-nginx`.**                                                       |
| controller.replicaCount                         | The number of pods that are provisioned for the Ingress controller.                                                                                                                                                                                                                                                                                       |
| controller.service.enabled                      | Specifies whether to use Internet-facing SLB instances and internal-facing SLB instances for load balancing.                                                                                                                                                                                                                                              |
| controller.service.external.enabled             | Specifies whether to use an Internet-facing SLB instance for load balancing. If you do not want to use an Internet-facing SLB instance, set this parameter to false.                                                                                                                                                                                      |
| controller.service.internal.enabled             | Specifies whether to use an internal-facing SLB instance for load balancing. If you want to use an internal-facing SLB instance, set this parameter to true.                                                                                                                                                                                              |
| controller.kind                                 | The deployment mode of the Ingress controller. Valid values: Deployment and DaemonSet.                                                                                                                                                                                                                                                                    |
| controller.metrics.enabled                      | Specifies whether to enable the ingress-nginx metrics.                                                                                                                                                                                                                                                                                                    |
| controller.metrics.serviceMonitor.enabled       | Specifies whether to enable the ServiceMonitor, which provides the configuration on how metrics are collected. We recommend that you enable the ServiceMonitor after you enable the ingress-nginx metrics. Then, the system automatically generates the Prometheus configuration to collect metrics.                                                      |

For other parameter explanations, please refer to the annotation above the corresponding parameter.

## Prerequisites

- Chart version 3.x.x: Kubernetes v1.16+
- Chart version 4.x.x and above: Kubernetes v1.19+

## Get Repo Info

```console
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
```

## Install Chart

**Important:** only helm3 is supported

```console
helm install [RELEASE_NAME] ingress-nginx/ingress-nginx
```

The command deploys ingress-nginx on the Kubernetes cluster in the default configuration.

_See [configuration](#configuration) below._

_See [helm install](https://helm.sh/docs/helm/helm_install/) for command documentation._

## Uninstall Chart

```console
helm uninstall [RELEASE_NAME]
```

This removes all the Kubernetes components associated with the chart and deletes the release.

_See [helm uninstall](https://helm.sh/docs/helm/helm_uninstall/) for command documentation._

## Upgrading Chart

```console
helm upgrade [RELEASE_NAME] [CHART] --install
```

_See [helm upgrade](https://helm.sh/docs/helm/helm_upgrade/) for command documentation._

### Upgrading With Zero Downtime in Production

By default the ingress-nginx controller has service interruptions whenever it's pods are restarted or redeployed. In order to fix that, see the excellent blog post by Lindsay Landry from Codecademy: [Kubernetes: Nginx and Zero Downtime in Production](https://medium.com/codecademy-engineering/kubernetes-nginx-and-zero-downtime-in-production-2c910c6a5ed8).

### Migrating from stable/nginx-ingress

There are two main ways to migrate a release from `stable/nginx-ingress` to `ingress-nginx/ingress-nginx` chart:

1. For Nginx Ingress controllers used for non-critical services, the easiest method is to [uninstall](#uninstall-chart) the old release and [install](#install-chart) the new one
2. For critical services in production that require zero-downtime, you will want to:
   1. [Install](#install-chart) a second Ingress controller
   2. Redirect your DNS traffic from the old controller to the new controller
   3. Log traffic from both controllers during this changeover
   4. [Uninstall](#uninstall-chart) the old controller once traffic has fully drained from it
   5. For details on all of these steps see [Upgrading With Zero Downtime in Production](#upgrading-with-zero-downtime-in-production)

Note that there are some different and upgraded configurations between the two charts, described by Rimas Mocevicius from JFrog in the "Upgrading to ingress-nginx Helm chart" section of [Migrating from Helm chart nginx-ingress to ingress-nginx](https://rimusz.net/migrating-to-ingress-nginx). As the `ingress-nginx/ingress-nginx` chart continues to update, you will want to check current differences by running [helm configuration](#configuration) commands on both charts.

## Configuration

See [Customizing the Chart Before Installing](https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing). To see all configurable options with detailed comments, visit the chart's [values.yaml](./values.yaml), or run these configuration commands:

```console
helm show values ingress-nginx/ingress-nginx
```

### PodDisruptionBudget

Note that the PodDisruptionBudget resource will only be defined if the replicaCount is greater than one,
else it would make it impossible to evacuate a node. See [gh issue #7127](https://github.com/helm/charts/issues/7127) for more info.

### Prometheus Metrics

The Nginx ingress controller can export Prometheus metrics, by setting `controller.metrics.enabled` to `true`.

You can add Prometheus annotations to the metrics service using `controller.metrics.service.annotations`.
Alternatively, if you use the Prometheus Operator, you can enable ServiceMonitor creation using `controller.metrics.serviceMonitor.enabled`. And set `controller.metrics.serviceMonitor.additionalLabels.release="prometheus"`. "release=prometheus" should match the label configured in the prometheus servicemonitor ( see `kubectl get servicemonitor prometheus-kube-prom-prometheus -oyaml -n prometheus`)

### ingress-nginx nginx\_status page/stats server

Previous versions of this chart had a `controller.stats.*` configuration block, which is now obsolete due to the following changes in nginx ingress controller:

- In [0.16.1](https://github.com/kubernetes/ingress-nginx/blob/main/Changelog.md#0161), the vts (virtual host traffic status) dashboard was removed
- In [0.23.0](https://github.com/kubernetes/ingress-nginx/blob/main/Changelog.md#0230), the status page at port 18080 is now a unix socket webserver only available at localhost.
  You can use `curl --unix-socket /tmp/nginx-status-server.sock http://localhost/nginx_status` inside the controller container to access it locally, or use the snippet from [nginx-ingress changelog](https://github.com/kubernetes/ingress-nginx/blob/main/Changelog.md#0230) to re-enable the http server

### ExternalDNS Service Configuration

Add an [ExternalDNS](https://github.com/kubernetes-incubator/external-dns) annotation to the LoadBalancer service:

```yaml
controller:
  service:
    annotations:
      external-dns.alpha.kubernetes.io/hostname: kubernetes-example.com.
```

### AWS L7 ELB with SSL Termination

Annotate the controller as shown in the [nginx-ingress l7 patch](https://github.com/kubernetes/ingress-nginx/blob/main/deploy/aws/l7/service-l7.yaml):

```yaml
controller:
  service:
    targetPorts:
      http: http
      https: http
    annotations:
      service.beta.kubernetes.io/aws-load-balancer-ssl-cert: arn:aws:acm:XX-XXXX-X:XXXXXXXXX:certificate/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX
      service.beta.kubernetes.io/aws-load-balancer-backend-protocol: "http"
      service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "https"
      service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout: '3600'
```

### AWS route53-mapper

To configure the LoadBalancer service with the [route53-mapper addon](https://github.com/kubernetes/kops/tree/master/addons/route53-mapper), add the `domainName` annotation and `dns` label:

```yaml
controller:
  service:
    labels:
      dns: "route53"
    annotations:
      domainName: "kubernetes-example.com"
```

### Additional Internal Load Balancer

This setup is useful when you need both external and internal load balancers but don't want to have multiple ingress controllers and multiple ingress objects per application.

By default, the ingress object will point to the external load balancer address, but if correctly configured, you can make use of the internal one if the URL you are looking up resolves to the internal load balancer's URL.

You'll need to set both the following values:

`controller.service.internal.enabled`
`controller.service.internal.annotations`

If one of them is missing the internal load balancer will not be deployed. Example you may have `controller.service.internal.enabled=true` but no annotations set, in this case no action will be taken.

`controller.service.internal.annotations` varies with the cloud service you're using.

Example for AWS:

```yaml
controller:
  service:
    internal:
      enabled: true
      annotations:
        # Create internal ELB
        service.beta.kubernetes.io/aws-load-balancer-internal: "true"
        # Any other annotation can be declared here.
```

Example for GCE:

```yaml
controller:
  service:
    internal:
      enabled: true
      annotations:
        # Create internal LB. More informations: https://cloud.google.com/kubernetes-engine/docs/how-to/internal-load-balancing
        # For GKE versions 1.17 and later
        networking.gke.io/load-balancer-type: "Internal"
        # For earlier versions
        # cloud.google.com/load-balancer-type: "Internal"

        # Any other annotation can be declared here.
```

Example for Azure:

```yaml
controller:
  service:
      annotations:
        # Create internal LB
        service.beta.kubernetes.io/azure-load-balancer-internal: "true"
        # Any other annotation can be declared here.
```

Example for Oracle Cloud Infrastructure:

```yaml
controller:
  service:
      annotations:
        # Create internal LB
        service.beta.kubernetes.io/oci-load-balancer-internal: "true"
        # Any other annotation can be declared here.
```

An use case for this scenario is having a split-view DNS setup where the public zone CNAME records point to the external balancer URL while the private zone CNAME records point to the internal balancer URL. This way, you only need one ingress kubernetes object.

Optionally you can set `controller.service.loadBalancerIP` if you need a static IP for the resulting `LoadBalancer`.

### Ingress Admission Webhooks

With nginx-ingress-controller version 0.25+, the nginx ingress controller pod exposes an endpoint that will integrate with the `validatingwebhookconfiguration` Kubernetes feature to prevent bad ingress from being added to the cluster.
**This feature is enabled by default since 0.31.0.**

With nginx-ingress-controller in 0.25.* work only with kubernetes 1.14+, 0.26 fix [this issue](https://github.com/kubernetes/ingress-nginx/pull/4521)

### Helm Error When Upgrading: spec.clusterIP: Invalid value: ""

If you are upgrading this chart from a version between 0.31.0 and 1.2.2 then you may get an error like this:

```console
Error: UPGRADE FAILED: Service "?????-controller" is invalid: spec.clusterIP: Invalid value: "": field is immutable
```

Detail of how and why are in [this issue](https://github.com/helm/charts/pull/13646) but to resolve this you can set `xxxx.service.omitClusterIP` to `true` where `xxxx` is the service referenced in the error.

As of version `1.26.0` of this chart, by simply not providing any clusterIP value, `invalid: spec.clusterIP: Invalid value: "": field is immutable` will no longer occur since `clusterIP: ""` will not be rendered.
