Setting up NGINX Controller

Recently NGINX Controller has completely moved to kubernetes platform. That is great since it makes operations, maintenance, and upgrade of controller software much easier and reliable. However it also requires some kubernetes knowledge from a team.

I personally faced couple bumps when installed controller for fist time and ended up writing this article to help community to have smooth experience with controller installation.

So this article contains exact steps on how to install NGINX Controller software on fresh centOS 7.

1) Before you start make sure your system fits official technical specs

2) (Optional) Update CentOS packages

[centos@ip-10-1-1-11 ~]$ sudo yum update

4) (Optional) Follow official docker documentation to install and run docker on the system if not yet installed

[centos@ip-10-1-1-11 ~]$ docker -v
Docker version 19.03.5, build 633a0ea

5) Install jq tool

[centos@ip-10-1-1-11 ~]$ curl -Lo jq https://github.com/stedolan/jq/releases/download/jq-1.6/jq-linux64 && chmod +x ./jq && sudo cp jq /usr/bin

6) Store controller installer archive locally

[centos@ip-10-1-1-10 ~]$ ls ~/
controller-installer-2.9.0.tar.gz

7) Extract archive

[centos@ip-10-1-1-10 ~]$ tar xzf controller-installer-2.9.0.tar.gz && ls
controller-installer controller-installer-2.9.0.tar.gz

8) (Optional) Installation may fail on step 16

[centos@ip-10-1-1-10 controller-installer]$ ./install.sh
...
16. Running database initialization task...
failed
...

This usually means that besides OS can resolve domain names a pod which runs in k8s can't. Coredns k8s service needs little config change to make pods to use proper name server as well. To archive that modify coredns config map:

[centos@ip-10-1-1-10 ~]$ kubectl edit cm coredns -n kube-system
apiVersion: v1
data:
  Corefile: |
    .:53 {
        errors
        health
        kubernetes cluster.local in-addr.arpa ip6.arpa {
           pods insecure
           upstream
           fallthrough in-addr.arpa ip6.arpa
           ttl 30
        }
        prometheus :9153
        forward . resolv.conf
        cache 30
        loop
        reload
        loadbalance
    }
kind: ConfigMap
...omitted

Change line "forward . resolv.conf" to "forward . YOUR_DNS_NAME_SERVER"

[centos@ip-10-1-1-10 ~]$ kubectl edit cm coredns -n kube-system
apiVersion: v1
data:
  Corefile: |
    .:53 {
        errors
        health
        kubernetes cluster.local in-addr.arpa ip6.arpa {
           pods insecure
           upstream
           fallthrough in-addr.arpa ip6.arpa
           ttl 30
        }
        prometheus :9153
        forward . 10.1.1.5
        cache 30
        loop
        reload
        loadbalance
    }
kind: ConfigMap
...omitted

9) Start controller installation and follow guidance

[centos@ip-10-1-1-10 controller-installer]$ ./install.sh

 --- This script will install the NGINX Controller system ---
  1. Checking required ports... OK
  2. Checking for existing installation...
  3. Attempting to detect your Operating System... Found core
  4. Checking for required tools: grep sed less tee sort head ps cat awk id mkdir dirname basename getent rev tar gunzip envsubst jq base64 openssl numfmt. All found.
  5. Checking Docker version...
 Docker version 19.03.5, build 633a0ea
     We recommend setting native.cgroupdriver to systemd for Docker.
     WARNING! Docker configuration does not seem to have log rotation enabled. We recommend enabling log rotation for docker containers.
     For steps to enable log rotation follow this link: https://success.docker.com/article/how-to-setup-log-rotation-post-installation
  6. Checking Kubernetes...
  7. Checking resource requirements...
Warning: Available CPU cores: 2. The Controller needs at least 8 CPU cores to work effectively.
numfmt: invalid format ‘%.2f’, directive must be %['][-][N]f
Warning: Available memory: @{available_memory_gb}B. The Controller needs at least 8GB of RAM to work effectively.
numfmt: invalid format ‘%.2f’, directive must be %['][-][N]f
Warning: Available disk space: B. The Controller needs at least 80GB of disk space to work effectively.


In order to avoid performance issues, consider installing the Controller with the recommended specifications.
  8. End User License Agreement
Do you accept this End User License Agreement [y/n]?
Do you accept this End User License Agreement [y/n]? y
  9. Loading docker images...
Loaded image: python:3.6-alpine
Loaded image: controller/controller-init:2.9.5-1035548
Loaded image: controller/controller-prod:2.9.5-1035548
Loaded image: postgres:9.5
Loaded image: controller-frontend/frontend:2.9.5-1035543
Loaded image: controller-installer/apigw:2.9.0-1035620
Loaded image: controller/controller-audit-log:2.9.5-1035548
Loaded image: controller/controller-cron:2.9.5-1035548
Loaded image: rabbitmq:3.7
  10. Database configuration
Provide the database hostname: postgres.mgmt.lab
Provide the database port (for example, 5432): 5432
Provide the database username: naas
Provide the database password:
Repeat password:
  11. SMTP settings
Provide the SMTP host: smtp.mgmt.lab
Provide the SMTP port: 25
Use SMTP authentication? [y/n]: n
Use TLS for SMTP communication? [y/n]: n
Provide a do-not-reply email address: dnr@mgmt.lab
  12. Admin user configuration
The FQDN, for example, controller.mycompany.com, will be used to access NGINX Controller in the browser as https://{FQDN}.
Provide the FQDN for your Controller: nginx-controller@mgmt.lab
 Domain must be resolvable on this system. Check your entry and try again.
Provide the FQDN for your Controller: nginx-controller.mgmt.lab
Provide the organization name: Lab
Provide the admin's first name: admin
Provide the admin's last name: admin
Provide the admin's email address: admin@mgmt.lab
Provide the admin's password. Passwords must be 6 to 64 characters, and must include letters and digits:
Repeat password:
  13. Checking HTTPS certificates...
A certificate for HTTPS connection was not found in the /opt/nginx-controller/certs/controller/ directory.
This certificate is required to establish a TLS connection between the Controller and
your web browser. If you choose not to generate a self-signed certificate,
you will be prompted to provide the path to your certificate and key files.
 Would you like to generate a self-signed certificate now? [y/n]? y
Generating a 4096 bit RSA private key
......................................................++
.........................................++
writing new private key to './certs/controller/server.key'
-----
  14. Generating password and session salts... OK.
 15. Generating Kubernetes resource files...
 Restored the original Kubernetes config files.
 Cleaned up certs.
 16. Running database initialization task...
     NGINX Controller database has been initialized.
 17. Starting up Controller stack...
configmap/controller-config-6gbfmmd72g created
configmap/frontend-kbg4g4fd8h created
configmap/nginx-config-d9f9f7bk4m created
configmap/rabbitmq-5fcdtt75g4 created
secret/controller-reverseproxy-tls-bmk8dtt9t9 created
secret/controller-secrets-488cf7285g created
secret/rabbitmq-7k4d2bg7g9 created
service/apigw created
service/apimgmt created
service/appregistry created
service/coreapi created
service/frontend created
service/rabbitmq created
service/receiver created
deployment.apps/apigw created
deployment.apps/apimgmt created
deployment.apps/appregistry created
deployment.apps/celery created
deployment.apps/coreapi created
deployment.apps/cron created
deployment.apps/frontend created
deployment.apps/rabbitmq created
deployment.apps/receiver created
     NGINX Controller services are ready.

 OK, everything went just fine!
 Thank you for installing NGINX Controller.
 You can find your installation in /opt/nginx-controller.
 You can find the install log file in /var/log/nginx-controller/nginx-controller-install.log.
 Access the system using your web browser at https://nginx-controller.mgmt.lab.
 Documentation is available at https://nginx-controller.mgmt.lab/docs/.

As you see controller installation process is still pretty straightforward. I hope this article will save someone time on controller installation.

Good luck!