Ingress NGINX Controller

This app installs the Ingress NGINX Controller into your cluster.

Its job is to satisfy external requests to services running in the cluster. See the Kubernetes Ingress documentation for a higher level overview.

Table of Contents

• Ingress NGINX Controller
• Prerequisites
• Installation
  • Using our web interface
  • Directly creating the App resource
• Configuration
  • IngressClass resource
  • Internal Ingress NGINX Controller
  • AWS & PROXY protocol
• Migration from nginx-ingress-controller-app
• Development
  • Local installation
  • Sync chart changes from upstream
  • Release process

Prerequisites

• Kubernetes version >= v1.20.0
• Ingress API version >= networking.k8s.io/v1 (extensions/v1beta1 & networking.k8s.io/v1beta1 are no longer supported)

Additionally, you'll have to make sure your Ingress resources are using the .spec.ingressClassName, matching the name of your IngressClass resource (default: nginx).

Installation

There are two ways to install this app into your cluster:

1. Using our web interface.
2. Directly creating the App resource.

Using our web interface

This is an example of the values file you could upload using our web interface:

controller:
  config:
    error-log-level: info

Directly creating the App resource

If you have access to management cluster, you can create the App & ConfigMap resources directly. These sample values deploy the ingress-nginx app to your cluster abc12:

apiVersion: v1
kind: ConfigMap
metadata:
  name: ingress-nginx-user-values
  namespace: abc12
data:
  values: |
    controller:
      config:
        error-log-level: info
---
apiVersion: application.giantswarm.io/v1alpha1
kind: App
metadata:
  name: ingress-nginx
  namespace: abc12
spec:
  catalog: giantswarm
  name: ingress-nginx
  version: 4.2.0
  userConfig:
    configMap:
      name: ingress-nginx-user-values
      namespace: abc12
  namespace: kube-system

See our app configuration reference for more details.

Configuration

All configuration options are documented in the values.yaml.

IngressClass resource

In case it is not possible to update all Ingress resources to specify the .spec.ingressClassName, you can add the --watch-ingress-without-class argument using the controller.extraArgs. Please make sure there is no other Ingress Controller doing so deployed to your cluster.

If you are running multiple Ingress NGINX Controllers, each needs to have an unique IngressClass resource. You can use the values structure below:

controller:
  ingressClassResource:
    name: nginx-internal
    controllerValue: k8s.io/ingress-nginx-internal

Note: It is not possible to change the controller.ingressClassResource values after installation, except you are also changing controller.ingressClassResource.name. If you need to change these values, you will need to uninstall the app first.

Internal Ingress NGINX Controller

This chart contains a template for an additional internal service to cover the use case of having separate external & internal services with a single Ingress NGINX Controller instance.

Valid configuration options are as follows:

External only (default)

This is the default behavior. No additional configuration required.

Internal only

This configures the default service to create an internal facing load balancer:

controller:
 service:
   public: false

External & internal

This enables the additional internal service and creates an internal facing load balancer.

controller:
  service:
    internal:
      enabled: true

AWS & PROXY protocol

Since version v2.17.0, this chart has the use-proxy-procotol enabled by default when installed in AWS.

To disable this behavior, it is still possible to set controller.config.use-proxy-protocol to "false" in the values.

Migration from nginx-ingress-controller-app

Please see our migration guide if you want to update your nginx-ingress-controller-app deployment to the new ingress-nginx chart.

Development

Local installation

To install the chart locally:

$ git clone https://github.com/giantswarm/ingress-nginx-app.git
$ cd ingress-nginx-app
$ helm install helm/ingress-nginx

Provide a custom values.yaml:

$ helm install helm/ingress-nginx --values values.yaml

Sync chart changes from upstream

This chart is synced from the upstream ingress-nginx repository using vendir. The sync process fetches the upstream chart and applies Giant Swarm specific patches.

To update to a new upstream version, modify the ref field in vendir.yml to point to the desired upstream tag (e.g., helm-chart-4.14.2).

Make sure the required container image tags are available in the Giant Swarm registry. (Example retagger commit).

To sync the chart (requires vendir, yq and helm-docs):

$ ./sync/sync.sh

Then: Update CHANGELOG.md, commit changes + push.

This will:

1. Fetch the upstream chart version specified in vendir.yml
2. Apply all patches from sync/patches/
3. Generate diff files in the diffs/ directory

Patches are stored in sync/patches/ and are applied in the order specified in sync/sync.sh. Each patch directory contains a patch.sh script and the corresponding .patch files.

Testing

This App includes E2E tests using the apptest-framework. You can trigger the configured tests on any open PR by adding the following as a comment:

/run app-test-suites

E2E tests include:

Suite	Test	Description	Providers
Basic	App install	Check if the App is installed correctly and marked as deployed	CAPA
Basic	Hello World	Deploy hello-world app and verify that it's reachable through the Ingress	CAPA

Release process

• Ensure CHANGELOG.md is up to date.
• Create a new branch with name release#vx.x.x. Automation will create a release PR.
• Merging the release PR will push a new Git tag and trigger a new tarball to be pushed to the [giantswarm-catalog].