diff --git a/docs/content/tutorials/custom-listen-ports.md b/docs/content/tutorials/custom-listen-ports.md new file mode 100644 index 0000000000..9bf61e8077 --- /dev/null +++ b/docs/content/tutorials/custom-listen-ports.md @@ -0,0 +1,158 @@ +--- +title: Customizing NGINX Ingress Controller Ports +description: | + How to customize F5 NGINX Ingress Controller ports. +weight: 1800 +doctypes: ["concept"] +toc: true +--- +## Customizing NGINX Ingress Controller Ports + +This document explains how to change the default ports that NGINX Ingress Controller is configured to use, as well as how to add additional `listen` settings. For more information, please read the [NGINX Listen documentation](http://nginx.org/en/docs/http/ngx_http_core_module.html#listen). + +## Changing Default Ports + +By default, NGINX Ingress Controller listens on ports 80 and 443. These ports can be changed easily, but modifying the `listen` ports for your NGINX Ingress resources will require the editing of `.tmpl` files. + +If you are using NGINX Ingress Controller CRDs (VirtualServer): +- `nginx-plus-virtualserver.tmpl` for NGINX Plus +- `nginx-virtualserver.tmpl` if using NGINX OSS + +If you are using `Ingress` resource you will need to modify: +- `nginx-plus-ingress.tmpl` if using NGINX Plus +- `nginx-ingress.tmpl` if using NGINX OSS + +In this example, we will use the `nginx-virtualserver.tmpl` template to change the port from 80 to 85. +You can find the [nginx-virtualserver template files in our repository](https://github.com/nginxinc/kubernetes-ingress/tree/main/internal/configs/version2). + +We start by modifying `nginx-virtualserver.tmpl` to change the port setting: + +```nginx +server { + listen 80{{ if $s.ProxyProtocol }} proxy_protocol{{ end }}; + + server_name {{ $s.ServerName }}; + + set $resource_type "virtualserver"; + set $resource_name "{{$s.VSName}}"; + set $resource_namespace "{{$s.VSNamespace}}"; +``` +To change the listen port from `80` to `85`, edit the `listen` line at the start of the server configuration block. + +After changing the number, the file looks like this: + +```nginx +server { + listen 85{{ if $s.ProxyProtocol }} proxy_protocol{{ end }}; + + server_name {{ $s.ServerName }}; + + set $resource_type "virtualserver"; + set $resource_name "{{$s.VSName}}"; + set $resource_namespace "{{$s.VSNamespace}}"; +``` + +Modify the file you need (per the example above). In the example, we modified `nginx-plus-virtualserver.tmpl`: + + +## Rebuild the NGINX Ingress Controller image + +You must rebuild the NGINX Ingress Controller image for the new port settings to take effect. +Once the image is built and pushed, make sure you update your deployment to point to the new image and deploy. +Once deployed, create a new `VirtualServer` resource and run `nginx -T` to confirm if the port change has taken effect. + +Ensure that your `Deployment` and your `Service` match up to the new port you configured in the templates. +Below is an example of `Deployment` and `Service` matching to the new port that NGINX Ingress Controller now listens on. + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-ingress + namespace: nginx-ingress +spec: + replicas: 1 + selector: + matchLabels: + app: nginx-ingress + template: + metadata: + labels: + app: nginx-ingress + annotations: + prometheus.io/scrape: "true" + prometheus.io/port: "9113" + prometheus.io/scheme: http + spec: + serviceAccountName: nginx-ingress + containers: + - image: nginx/nginx-ingress:3.0.2 + imagePullPolicy: IfNotPresent + name: nginx-ingress + ports: + - name: http + containerPort: 85 + - name: https + containerPort: 443 + - name: readiness-port + containerPort: 8081 + - name: prometheus + containerPort: 9113 + readinessProbe: + httpGet: + path: /nginx-ready + port: readiness-port + periodSeconds: 1 + securityContext: +``` + +Notice that now, the `http` port is set to `85`, which reflects the change we made in the template file. + +Here is the `service` file: + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: nginx-ingress + namespace: nginx-ingress +spec: + externalTrafficPolicy: Local + type: LoadBalancer + ports: + - port: 80 + targetPort: 85 + protocol: TCP + name: http + - port: 8443 + targetPort: 8443 + protocol: TCP + name: https + selector: + app: nginx-ingress +``` + +Since NGINX Ingress Controller is now listening on ports 85 and 8443, you must modify the `targetPort` in the NGINX Ingress Controller service to match the change in the deployment to ensure traffic will be sent to the proper port. + +The parameter to change above is `targetPort`. Since we have changed NGINX Ingress Controller to listen on port 85, we need to match that in the service: requests will be sent to NGINX Ingress Controller on port 85 instead of the default value, port 80. + +If you view the `NGINX` configuration .conf file using `nginx -T`, you should see the port you defined in the .template file is now set on the `listen` line. + +Here is an example output of the `NGINX` configuration that has been generated: + +```console +kubectl exec -it -n nginx-ingress nginx-ingress-54bffd78d9-v7bns -- nginx -T +``` + +```nginx +server { + listen 85; + listen [::]:85; + listen 8011; + + server_name cafe.example.com; + + set $resource_type "virtualserver"; + set $resource_name "cafe"; + set $resource_namespace "default"; +```