# Ingress-NGINX

## Overview

The source code and default configuration of the Building Block is available in our [code.syseleven.de](<https://code.syseleven.de/syseleven/building-blocks/helmfiles/ingress-nginx>). For information on release notes and new features please follow the link: [Release notes ingress-nginx](<https://code.syseleven.de/syseleven/building-blocks/helmfiles/ingress-nginx/-/blob/main/RELEASE-NOTES.md>)

### Ingress-Nginx

The Ingress Controller which is used by for example by Kubernetes for reverse proxy and load balancing capabilities.

### Prerequisites On Ingress-Nginx

Proceed with the following prerequisite description to use the Building Block out of the box.

#### Recommended Setup

A recommended resource overview is listed in the table below.

| CPU / vCPU | Memory |
| --- | --- |
| 1.26 | 532MiB |

No further activities need to be carried out in advance.

### Adding The Building Block

Add the directory `syseleven-ingress-nginx` to your control repository as well as the `.gitlab-ci.yml` to the directory with the following content:

```yaml
include:
  - project: syseleven/building-blocks/helmfiles/ingress-nginx
    file: JobDevelopment.yaml
    ref: {{ site.building_blocks.ingress_nginx.version|e }}
  - project: syseleven/building-blocks/helmfiles/ingress-nginx
    file: JobStaging.yaml
    ref: {{ site.building_blocks.ingress_nginx.version|e }}
  - project: syseleven/building-blocks/helmfiles/ingress-nginx
    file: JobProduction.yaml
    ref: {{ site.building_blocks.ingress_nginx.version|e }}
```

Remove environments you are not using by removing their include.

### Required Configuration

No configuration is required.

### Example Configuration

The following Ingress resource will create an ingress for the domain: `testdomain-cert.<customerdomain>.de`. Due to the spec.tls section in the configuration, a certificate is generated for the domain. The building block ingress-nginx creates a load balancer that binds an external IP address. See `kubectl get svc -n syseleven-ingess-nginx` A DNS A record pointing to the IP address of the load balancer is created for the ingress resource described here.

> [!NOTE]
>
> **Info**
>
> To make the following Ingress resource fully available, other Building Blocks besides the `ingress-nginx` must be installed: - external-dns - cert-manager - Use [DNSaaS](<https://documentation.syseleven.de/en/prior-docs/openstack-cloud/how-to/dnsaas/index.md>) to configure your DNS records

### Prepare

Create a namespace for the example:

```shell
kubectl create ns example-ingress
```

Create an http service:

```shell
kubectl apply -n example-ingress -f https://raw.githubusercontent.com/istio/istio/master/samples/httpbin/httpbin.yaml
```

This creates an application including a service `httpbin` in the namespace `example-ingress`.

### Create The Ingress Resource

The service endpoint should be available outside the cluster with its own domain name using https. The ingress must exist in the same namespace as the Service object.

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: test-ingress
  namespace: example-ingress
  annotations:
    # Use ClusterIssuer: letsencrypt-production.
    cert-manager.io/cluster-issuer: letsencrypt-production
  labels:
    # Use acme/solver: dns01defined in ClusterIssuer: letsencrypt-production.
    cert-manager.io/solver: dns01
spec:
  ingressClassName: nginx
  rules:

  - host: testdomain-cert.<customerdomain>.de
    http:
      paths:
      - backend:
          service:
            name: httpbin
            port:
              number: 8000
        pathType: ImplementationSpecific
  tls:
    - hosts:
        - testdomain-cert.<customerdomain>.de
      # Store the certificate as secret named testdomain-cert-secret in namespace: example-ingress
      secretName: testdomain-cert-secret
```

Check the generated certificate:

```shell
kubectl describe certificate -n example-ingress testdomain-cert-secret
```

or

```shell
kubectl get -n example-ingress  secret testdomain-cert-secret -o jsonpath='{.data.tls\.crt}'| base64 -d -| openssl x509 -dates -subject -noout
```

Check the generated DNS configuration: Providing the DNS record can take a few minutes. Please check regularly with the following command:

```shell
dig @ns01.cloud.syseleven.net testdomain-cert.<customerdomain>.de
```

Check access to internal HTTPBIN service:

```shell
curl https://testdomain-cert.<customerdomain>.de/get
```

### Cleanup

To remove the example again it is sufficient to delete the namespace.

```shell
kubectl delete ns example-ingress
```

### Customize The Default Backend

The Building Block delivers a custom default backend. This default backend is used for all URLs the ingress-controller can not process (that is, all the requests that are not mapped with an Ingress) or for requests that got a 502, 503 or 504 from the upstream backend server. This default backend delivers configurable static pages while still maintaining the original error code.

You can customize the default backend by overriding `maintenancePages` in `values-ingress-nginx-extension.yaml`. See the [values.yaml](<https://code.syseleven.de/syseleven/building-blocks/helmfiles/ingress-nginx/-/blob/main/ingress-nginx-extension/values.yaml>) for the default maintenance page.

Here is an example on how to configure different error pages for different error codes.

```yaml
maintenancePages:
  404.html: |-
    <!DOCTYPE html>
    <html>
      <head>
        <title>Error</title>
      </head>
      <body>
        ...
      </body>
    </html>
  418.html: |-
    ...
  429.html: |-
    ...
  500.html: |-
    ...
  502.html: |-
    ...
  503.html: |-
    ...
  523.html: |-
    ...
```

### Monitoring

#### Additional Alert-Rules

- None

#### Additional Grafana dashboards

- Request Handling Performance
- An overview of performance metrics of handled requests by the ingress-controller
- NGINX Ingress controller
- An overview of overall metrics collected by the ingress-controller (for example, request volume, network pressure, ingress success rate, ingress throughput/requests, SSL certificates, ...)

### Scale Setup

- Choose between *kind* [Deployment](<https://kubernetes.io/docs/concepts/workloads/controllers/deployment/>)(default and recommended) or *kind* [DaemonSet](<https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/>)
- Replicas - you can statically configure the amount of replicas you need (when using the Deployment *kind*)
- Autoscale replicas - you can configure the [horizontal pod autoscaler](<https://kubernetes.io/de/docs/tasks/run-application/horizontal-pod-autoscale/>) to autoscale the ingress-nginx Deployment. See [values.yaml](<https://github.com/kubernetes/ingress-nginx/blob/master/charts/ingress-nginx/values.yaml>) for possible options.
- Requirements/Limits for CPU/Memory can be adjusted. We recommend not setting CPU limits so as not to throttle the Ingress controller and slow down the entire application.

### Release-Notes

Please find more infos on release notes and new features [Release notes Ingres-Nginx](<https://code.syseleven.de/syseleven/building-blocks/helmfiles/ingress-nginx/-/blob/main/RELEASE-NOTES.md>).
