13 Installing and Configuring Ingress Controller

An Ingress controller is a load balancer that enables simple host or URL-based HTTO routing.

This chapter includes the following topics:

• Kubernetes Services
  The Kubernetes services are created as part of the Ingress deployment.
• Variables Used in this Chapter
  The later sections of this chapter provide instructions to create a number of files. These sample files contain variables which you need to substitute with values applicable to your deployment.
• Creating a Kubernetes Namespace
  The Kubernetes namespace is used to store the Ingress controller.
• Creating a Registry Secret
  The nginx Ingress controller is obtained from the container registry on GitHub. To download the image on demand, you should create a registry secret with your GitHub credentials.
• Adding the Ingress Image to the Helm Repository
  Use the helm commands to add the nginx container image to the Helm repository.
• Installing an Ingress Controller to Support HTTPS/HTTP and LDAPS/LDAP
  When you create an Ingress controller, it will support HTTP and/or HTTPS traffic. If you terminate the SSL traffic behind a load balancer, there is no need to enable the HTTPS traffic.

Kubernetes Services

The Kubernetes services are created as part of the Ingress deployment.

Table 13-1 Kubernetes Services

Service Name	Type	Service Port	Mapped Port
nginx-ingress-ingress-nginx-idmedg	NodePort	80 443	30777 30443

These are the ports you will use to interact with the controller.

Variables Used in this Chapter

The later sections of this chapter provide instructions to create a number of files. These sample files contain variables which you need to substitute with values applicable to your deployment.

Variables are formatted as <VARIABLE_NAME>. The following table provides the values you should set for each of these variables.

Table 13-2 The Variables to be Changed

Variable	Sample Value	Description
<INGRESSNS>	ingressns	The name of the Ingress namespace.
<GIT_USER>	mygituser	The name of the user to log in to GitHub.
<GIT_TOKEN>	mytoken	The git login token.
<WORKDIR>	/workdir/INGRESS/	The working directory for Ingress.
<INGRESS_SERVICE_TYPE>	NodePort	The type of Ingress service type to create. Options are NodePort and LoadBalancer.
<INGRESS_NAME>	idmedg	An arbitrary name for the controller.
<INGRESS_REPLICAS>	2	The number of copies of the Ingress controller you want to start. For highly available implementations, this value should be 2 or greater.
<INGRESS_HTTP_K8>	30777	The Kubernetes service port you want to use for HTTP communications.
<INGRESS_HTTPS_K8>	30443	The Kubernetes service port you want to use for HTTPS communications.
<LDAPNS>	oudns	The namespace where the LDAP directory is running.
<LDAP_K8>	30389	The Kubernetes port you want to use to expose the Ingress LDAP traffic.
<LDAPS_K8>	30636	The Kubernetes port you want to use to expose the Ingress LDAPS traffic.
<OUD_POD_PREFIX>	edg	The prefix used in the name of the service in the LDAP namespace to which you want to send traffic.
<USE_PROM>	false	Set to true if you want Ingress metrics to be sent to Prometheus.

Creating a Kubernetes Namespace

The Kubernetes namespace is used to store the Ingress controller.

Use the following command to create a namespace for Ingress:

kubectl create namespace <INGRESSNS>

For example:

kubectl create namespace ingressns

Creating a Registry Secret

The nginx Ingress controller is obtained from the container registry on GitHub. To download the image on demand, you should create a registry secret with your GitHub credentials. See Logging in to GitHub.

To create a secret called gitcred in the Ingress namespace, use the following command:

kubectl create secret docker-registry gitcred –n <INGRESSNS> --docker-server=ghcr.io --docker-username=<GIT_USER> --docker-password="<GIT_TOKEN>"

For example:

kubectl create secret docker-registry gitcred –n ingressns --docker-server=ghcr.io --docker-username=mygituser --docker-password="mytoken"

Adding the Ingress Image to the Helm Repository

Use the helm commands to add the nginx container image to the Helm repository.

The commands are:

helm repo add stable https://kubernetes.github.io/ingress-nginx

helm repo update

Installing an Ingress Controller to Support HTTPS/HTTP and LDAPS/LDAP

When you create an Ingress controller, it will support HTTP and/or HTTPS traffic. If you terminate the SSL traffic behind a load balancer, there is no need to enable the HTTPS traffic.

If you are deploying only Oracle Identity Management Microservices and do not want to place them behind an existing Oracle HTTP server deployment, you would either configure Ingress for end-to-end SSL or terminate SSL at the Ingress.

If you are deploying an Oracle LDAP directory inside a Kubernetes cluster, you can optionally expose the LDAP and LDAPS traffic through Ingress. If you have no direct requirement to access the LDAP directory outside of the Kubernetes cluster, Oracle recommends that you do not enable this option.

Perform the following steps to create an Ingress controller:

• Creating a Self-Signed Certificate for SSL Requests
  
• Creating a Kubernetes Secret with the Certificate
  
• Creating the Helm Override File
  
• Creating the Ingress Controller
  
• Validating the Ingress Controller
  

Creating a Self-Signed Certificate for SSL Requests

You may skip this step if you have purchased your own CA certificate, or if you are placing Ingress behind an Oracle HTTP Server.

If you want to use a self-signed certificate, run the following commands:

1. Create a text file called ssl_cert_config.txt with the following content:

   # Copyright (c) 2022, Oracle Corporation and/or its affiliates.
   # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.
   #
   [req]
   distinguished_name = req_distinguished_name
   req_extensions = v3_req
   prompt = no
   [req_distinguished_name]
   CN = *.example.com
   [v3_req]
   keyUsage = keyEncipherment, dataEncipherment
   extendedKeyUsage = serverAuth
   subjectAltName = @alt_names
   [alt_names]
   DNS.1 = example.com

   Where example.com is the domain from where your requests will originate. For example, if you have an URL similar to http://iadadmin.example.com, your domain will be example.com.

2. Create a certificate by using the Linux command openssl:

   openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /workdir/INGRESS/ingress.key -out /workdir/INGRESS/ingress.crt -config /workdir/INGRESS/ssl_cert_config.txt -extensions v3_req

3. Validate the generated certificate using the command:

   openssl x509 -noout -text /workdir/INGRESS/ingress.crt

Creating a Kubernetes Secret with the Certificate

Load the certificate into a Kubernetes secret. If you have purchased your own certificate, you can use that instead.

To create the secret in Kubernetes, use the following command:

kubectl -n <INGRESSNS> create secret tls common-tls-cert --key /workdir/ingress.key --cert /workdir/ingress.crt

Creating the Helm Override File

Depending on what you want to expose on your Ingress controller, you will use a different override file. The following examples show:

• Creating an Ingress controller for HTTP and HTTPS terminated traffic.
• Creating an Ingress controller for HTTP, HTTPS, and LDAP traffic.

Create a file called ingress_override.yaml in your working directory. Depending on your deployment, the content of the file will be different.

This section includes the following topics:

• Types of Ingress Service
  
• Override File for HTTP and HTTPS
  
• Override File for HTTP, HTTPS, LDAP, and LDAPS
  

Types of Ingress Service

You can create two types of Ingress services.

If you create a NodePort service, then interactions with the Ingress controller are through the Kubernetes worker nodes and the associated Kubernetes service port assigned to the controller.

If you create a LoadBalancer service, then the Ingress controller is assigned to an IP address. Interactions with the Ingress controller are directly through this IP address.

Creating a LoadBalancer type service is dependent on the flavor of Kubernetes you are using. You should refer to your platform's documentation to create this service.

For example, you can use the following steps to create a LoadBalancer service on Oracle Cloud Infrastructure:

1. Using the example files (see Override File for HTTP and HTTPS and Override File for HTTP, HTTPS, LDAP, and LDAPS), make the following changes:

   Set type: LoadBalancer

2. Under the LoadBalancer type, add the following lines:

   annotations:
         service.beta.kubernetes.io/oci-load-balancer-internal: "true"
         service.beta.kubernetes.io/oci-load-balancer-subnet1: "ocid1.subnet.oc1.iad....kdi3ds.....vqri332zdrr3rm"
         service.beta.kubernetes.io/oci-load-balancer-shape-flex-min: "10"
         service.beta.kubernetes.io/oci-load-balancer-shape-flex-max: "10"
         service.beta.kubernetes.io/oci-load-balancer-shape: "flexible"

3. Set oci-load-balancer-subnet1 to the OCID of the subnet in which the Kubernetes nodes reside.

Override File for HTTP and HTTPS

The following is an example of the Helm file for HTTP and HTTPS terminated traffic:

imagePullSecrets:
 - name: gitcred
controller:
  name: <INGRESS_NAME>
  ingressClassResource:
    name: nginx
  config:
    use-forwarded-headers: true
    enable-underscores-in-headers: true
  wildcardTLS:
    secret: tls-cert
  replicaCount: <INGRESS_REPLICAS>
  service:
    type: <INGRESS_SERVICE_TYPE>
    nodePorts:
      http: <INGRESS_HTTP_K8>
      https: <INGRESS_HTTPS_K8>
  admissionWebhooks:
    enabled: false
  metrics:
    enabled: <USE_PROM>
    serviceMonitor:
      enabled: <USE_PROM>

Override File for HTTP, HTTPS, LDAP, and LDAPS

The following is an example of the Helm file for HTTP and HTTPS terminated traffic with the addition of exposing the LDAP/LDAPS directory services:

imagePullSecrets:
 - name: gitcred
tcp:
  1389: <LDAPNS>/<OUD_POD_PREFIX>-oud-ds-rs-lbr-ldap:ldap
  1636: <LDAPNS>/<OUD_POD_PREFIX>-oud-ds-rs-lbr-ldap:ldaps
controller:
  name: <INGRESS_NAME>
  ingressClassResource:
    name: nginx
  config:
    use-forwarded-headers: true
    enable-underscores-in-headers: true
  wildcardTLS:
    secret: tls-cert
  replicaCount: <INGRESS_REPLICAS>
  service:
    type: <INGRESS_SERVICE_TYPE>
    nodePorts:
      http: <INGRESS_HTTP_K8>
      https: <INGRESS_HTTPS_K8>
      tcp:
        1389: <LDAP_K8>
        1636: <LDAPS_K8>
  admissionWebhooks:
    enabled: false
  metrics:
    enabled: <USE_PROM>
    serviceMonitor:
      enabled: <USE_PROM>

Where:

• tls-cert is the name of the SSL certificate you created earlier. See Creating a Self-Signed Certificate for SSL Requests.
• edg-<OUD_POD_PREFIX>-ds-rs-lbr-ldap is the name of the service in the LDAP namespace to which you want to send the traffic.

Creating the Ingress Controller

To create the Ingress controller, you need to run the following helm command specifying the override file you created earlier:

helm install nginx-ingress -n ingressns \
      --values /workdir/INGRESS/ingress_override.yaml \
      stable/ingress-nginx

Where nginx-ingress is the Ingress namespace. For example: ingressns.

1. Enter the text of the first step here.
2. Enter the text of the second step here.

Validating the Ingress Controller

To validate that the Ingress controller has been successfully created, use the following command:

kubectl get all,ingress -n <INGRESSNS>

For example:

kubectl get all,ingress -n ingressns

The output appears as follows:

NAME                                                         READY   STATUS      RESTARTS   AGE
pod/nginx-ingress-ingress-nginx-idmedg-bd4fdc996-794l5       1/1     Running     0         28h
pod/nginx-ingress-ingress-nginx-idmedg-bd4fdc996-qqvqf       1/1     Running     0         28h

NAME                                         TYPE       CLUSTER-IP    EXTERNAL-IP  PORT(S)                                                  AGE
service/nginx-ingress-ingress-nginx-idmedg   NodePort   10.107.148.40 <none>       80:30777/TCP,443:30443/TCP,1389:31389/TCP,1636:31636/TCP 28h

NAME                                                 READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/nginx-ingress-ingress-nginx-idmedg   2/2     2            2           28h

NAME                                                          DESIRED   CURRENT  READY   AGE
replicaset.apps/nginx-ingress-ingress-nginx-idmedg-bd4fdc996  2         2        2       28h