# Create an Ingress Controller

## Overview

To route traffic to applications deployed in Kubernetes it is good practice to use an Ingress Controller which proxies incoming request to the correct services and can handle things like TLS offloading. For more information on Ingress resources and Ingress Controllers see the [official Kubernetes documentation](<https://kubernetes.io/docs/concepts/services-networking/ingress/>).

## NGINX Ingress Controller

A popular ingress controller is the [nginx ingress controller](<https://kubernetes.github.io/ingress-nginx/>).

### Installation

You can install it manually through Helm. This will automatically create a [Load Balancer service](<https://documentation.syseleven.de/en/prior-docs/metakube-core/concepts/network/loadbalancers/index.md>) for you.

Depending on the wanted outcome, follow the below mentioned steps that apply to you. You can create the ingress controller within another existing namespace.

#### External only

```bash
helm install ingress-nginx ingress-nginx/ingress-nginx \
--repo https://kubernetes.github.io/ingress-nginx
--namespace ingress-nginx \
--create-namespace \
```

#### Internal and External

This will create a internal and external [Load Balancer service](<https://documentation.syseleven.de/en/prior-docs/metakube-core/concepts/network/loadbalancers/index.md>). The internal loadbalancer will be named `nginx-ingress-ingress-nginx-controller-internal` and the internal IP can be found via the `EXTERNAL IP` field via for example `kubectl get svc -n nginx-ingress -o wide`

```bash
helm install ingress-nginx ingress-nginx/ingress-nginx \
--repo https://kubernetes.github.io/ingress-nginx \
--namespace ingress-nginx \
--create-namespace \
-f values.yml
```

```yaml
# example values.yml
controller:
  service:
    enabled: true
    internal:
      enabled: true
      annotations:
        service.beta.kubernetes.io/openstack-internal-load-balancer: true
```

#### Internal only

To create only an internal loadbalancer, the same principle applies like mentioned above.

```bash
helm install ingress-nginx ingress-nginx/ingress-nginx \
--repo https://kubernetes.github.io/ingress-nginx \
--namespace ingress-nginx \
--create-namespace \
-f values.yml
```

```yaml
# example values.yml
controller:
  service:
    enabled: true
    external:
      enabled: false
    internal:
      enabled: true
      annotations:
        service.beta.kubernetes.io/openstack-internal-load-balancer: true
```

## Cert-Manager

To use [Let's Encrypt](<https://letsencrypt.org/>) to automatically manage TLS certificates for your ingress resources, you also have to install [cert-manager](<https://cert-manager.io/docs/>).

### Cert-Manager Installation

#### Manual installation

This can be done through Helm:

```bash
helm repo add jetstack https://charts.jetstack.io

helm repo update

helm install \
  cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.11.0 \
  --set installCRDs=true
```

To use the [DNS service](<https://documentation.syseleven.de/en/prior-docs/openstack-cloud/reference/dns/index.md>) for certificate DNS validation (for example required for wildcard certificates) you need to install the [designate webhook](<https://github.com/syseleven/designate-certmanager-webhook>) in the cluster. Please follow instructions from the provided [Readme](<https://github.com/syseleven/designate-certmanager-webhook/blob/master/README.md>).

### Configure cluster issuer

After installing the cert-manager you have to configure how it shall fetch certificates. For that you have to add a *ClusterIssuer* to your Kubernetes cluster:

```bash
cat <<'EOF' | kubectl apply -f -
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    # The ACME server URL
    server: https://acme-v02.api.letsencrypt.org/directory
    # Email address used for ACME registration
    email: your-email@example.com
    # Name of a secret used to store the ACME account private key
    privateKeySecretRef:
      name: letsencrypt-prod
    # Add a single challenge solver, HTTP01 using nginx
    solvers:
    - http01:
        ingress:
          class: nginx
EOF
```

To use DNS validation, please use the ClusterIssuer accordingly:

```bash
cat <<'EOF' | kubectl apply -f -
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    # The ACME server URL
    server: https://acme-v02.api.letsencrypt.org/directory
    # Email address used for ACME registration
    email: your-email@example.com
    # Name of a secret used to store the ACME account private key
    privateKeySecretRef:
      name: letsencrypt-prod
    # Use designate webhook for DNS01 validations
    solvers:
    - dns01:
        webhook:
          groupName: acme.syseleven.de
          solverName: designatedns
EOF
```

In [Deploy Application](<https://documentation.syseleven.de/en/prior-docs/metakube-core/how-to/deploy-an-application/index.md>) you can see how you can use this issuer to fetch a certificate.

## Further information

- [Nginx Ingress Controller Documentation](<https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/>)
- [Cert Manager Documentation](<https://cert-manager.io/docs/>)
