Install the Ingress Controller
An Ingress Controller receives incoming HTTP and HTTPS traffic at a single external address and routes it to the services in the cluster based on hostnames and paths.
The centron and Kubernetes do not come with an Ingress Controller pre-installed. You must install it yourself within the cluster.
Why use an ingress controller?
Without Ingress, every externally accessible service requires its own NodePort – in other words, a separate port for each service, which you must make a note of and allow through the firewall.
With an ingress controller, a single entry point is sufficient for any number of HTTP services, which are distinguished by their hostnames and paths. In addition, it handles TLS termination centrally, meaning that certificates do not need to be managed within each individual application.
Prerequisites
- A cluster with the status Running
- A verified connection via
kubectl; see Connecting to the cluster - Helm installed
Installing ingress-nginx
The ingress-nginx controller is the most widely used option.
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm install ingress-nginx ingress-nginx/ingress-nginx \
--namespace ingress-nginx \
--create-namespace \
--set controller.service.type=NodePort \
--set controller.service.nodePorts.http=30080 \
--set controller.service.nodePorts.https=30443
LoadBalancer services are not currently available, so the controller is published via NodePort. Ports 30080 (HTTP) and 30443 (HTTPS) are then opened on each worker node.
Determine external address
kubectl get service -n ingress-nginx ingress-nginx-controller
It takes a moment to allocate the address. As long as ‘<pending>’ is still shown in column EXTERNAL-IP, the address has not been allocated:
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
ingress-nginx-controller NodePort 10.43.201.15 <none> 80:30080/TCP,443:30443/TCP 2m
You then need to add this address as an A record in your domain’s DNS.
Check the installation
kubectl get pods -n ingress-nginx
kubectl get ingressclass
The controller pod should have the status Running, and there should be an IngressClass named nginx.
Creating your first Ingress
This requires an existing deployment with an associated service – see Deploying the first image. The service behind it does not need its own NodePort; ClusterIP is sufficient:
apiVersion: v1
kind: Service
metadata:
name: web
spec:
type: ClusterIP
selector:
app: web
ports:
- port: 80
targetPort: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
spec:
ingressClassName: nginx
rules:
- host: app.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web
port:
number: 80
How to use:
kubectl apply -f ingress.yaml
Check status:
kubectl get ingress
kubectl describe ingress web-ingress
Multiple services via a single ingress
This is precisely where the advantage over individual NodePorts lies – multiple hosts and paths share a single entry point:
spec:
ingressClassName: nginx
rules:
- host: app.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web
port:
number: 80
- host: api.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: api
port:
number: 8080
Troubleshooting
| Symptom | Possible cause |
|---|---|
| Controller unreachable | Check that the NodePorts are allowed through the firewall and that the node has a reachable address |
Request ends with 404 | The requested hostname does not match host in the Ingress |
Call ends with 503 | The referenced service or its pods are unreachable; check kubectl get endpoints <service-name> |
| Ingress has no address | ingressClassName is missing or does not match the installed IngressClass |
Controller logs:
kubectl logs -n ingress-nginx -l app.kubernetes.io/component=controller
Next steps
Once the installation is complete, set up TLS encryption: