Report Ingress Status (#10)

Update the address field in the status of Ingresses resources. The source for the external status can be a service of type LoadBalancer, or a config map key specifying the address to report.

New command-line arguments: report-ingress-status, external-service string, and enable-leader-election.
New config map key: external-status-address.

Uses Leader Election, if enabled, to avoid multiple Ingress controllers attempting to update ingress status.

docs/cli-arguments.md

@@ -9,6 +9,11 @@ Usage of ./nginx-ingress:
 	If not set, certificate and key in the file "/etc/nginx/secrets/default" are used. If a secret is set,
 	but the Ingress controller is not able to fetch it from Kubernetes API or a secret is not set and
 	the file "/etc/nginx/secrets/default" does not exist, the Ingress controller will fail to start
+  -enable-leader-election
+    	Enable Leader election to avoid multiple replicas of the controller reporting the status of Ingress resources -- only one replica will report status. See -report-ingress-status flag.
+  -external-service string
+    	Specifies the name of the service with the type LoadBalancer through which the Ingress controller pods are exposed externally.
+    	The external address of the service is used when reporting the status of Ingress resources. Requires -report-ingress-status.
   -health-status
     	Add a location "/nginx-health" to the default server. The location responds with the 200 status code for any request.
 	Useful for external health-checking of the Ingress controller
@@ -35,8 +40,10 @@ Usage of ./nginx-ingress:
   -nginx-plus
     	Enable support for NGINX Plus
   -proxy string
-    	Use a proxy server to connect to Kubernetes API started by "kubectl proxy" command. For testing purposes only.
-	The Ingress controller does not start NGINX and does not write any generated NGINX configuration files to disk
+        Use a proxy server to connect to Kubernetes API started by "kubectl proxy" command. For testing purposes only.
+        The Ingress controller does not start NGINX and does not write any generated NGINX configuration files to disk
+  -report-ingress-status
+    	Update the address field in the status of Ingresses resources. Requires the -external-service flag, or the 'external-status-address' key in the ConfigMap.
   -stderrthreshold value
     	logs at or above this threshold go to stderr
   -use-ingress-class-only
@@ -49,4 +56,4 @@ Usage of ./nginx-ingress:
     	comma-separated list of pattern=N settings for file-filtered logging
   -watch-namespace string
     	Namespace to watch for Ingress resources. By default the Ingress controller watches all namespaces
-```
+```

docs/installation.md

@@ -137,6 +137,10 @@ Use the public IP of the load balancer to access the Ingress controller. To get
     ```
     $ nslookup <dns-name>
     ```
+The public IP can be reported in the status of an ingress resource. To enable:
+1. Run the Ingress controller with the `-report-ingress-status` [command-line argument](cli-arguments.md).
+1. Configure the Ingress controller to use the `nginx-ingress` service name as the source of the IP with the arg `-external-service=nginx-ingress`.
+1. See the [Report Ingress Status doc](report-ingress-status.md) for more details.
 
 Read more about the type LoadBalancer [here](https://kubernetes.io/docs/concepts/services-networking/service/#type-loadbalancer).
 

docs/nginx-ingress-controllers.md

@@ -31,7 +31,7 @@ The table below summarizes the key difference between nginxinc/kubernetes-ingres
 | TLS certificate and key for the default server | Required as a command-line argument/ auto-generated | Required as a command-line argument | Required as a command-line argument |
 | Helm chart | Supported | Supported | Supported |
 | **Operational** |
-| Reporting the IP address(es) of the Ingress controller into Ingress resources | Supported | Coming soon | Coming soon |
+| Reporting the IP address(es) of the Ingress controller into Ingress resources | Supported | Supported | Supported |
 | Extended Status | Supported via a third-party module | Not supported | Supported |
 | Prometheus Integration | Supported | Not supported | Supported |
 | Dynamic reconfiguration of endpoints (no configuration reloading) | Supported with a third-party Lua module | Not supported | Supported |

docs/report-ingress-status.md

@@ -0,0 +1,21 @@
+# Reporting Status of Ingress Resources
+
+An Ingress resource can have a status that includes the address (an IP address or a DNS name), through which the hosts of that Ingress resource are publicly accessible.
+You can see the address in the output of the `kubectl get ingress` command, in the ADDRESS column, as shown below:
+
+```
+$ kubectl get ingresses
+NAME           HOSTS              ADDRESS           PORTS     AGE
+cafe-ingress   cafe.example.com   12.13.23.123      80, 443   2m
+```
+
+The Ingress controller must be configured to report an Ingress status:
+
+1. Use the command-line flag `-report-ingress-status`.
+2. Define a source for an external address. This can be either of:
+    1. A user defined address, specified in the `external-status-address` [ConfigMap key](../examples/customization).
+    2. A Service of the type LoadBalancer configured with an external IP or address and specified by the `-external-service` command-line flag.
+3. If you're running multiple replicas of the Ingress controller, enable leader election with the `-enable-leader-election` flag
+to ensure that only one replica updates an Ingress status.
+
+Notes: The Ingress controller does not clear the status of Ingress resources when it is being shut down.

examples/customization/README.md

@@ -66,6 +66,7 @@ The table below summarizes all of the options. For some of them, there are examp
 | `nginx.com/health-checks-mandatory` | N/A | Configures active health checks as mandatory. | `False` | [Support for Active Health Checks](../health-checks). |
 | `nginx.com/health-checks-mandatory-queue` | N/A | When active health checks are mandatory, configures a queue for temporary storing incoming requests during the time when NGINX Plus is checking the health of the endpoints after a configuration reload. | `0` | [Support for Active Health Checks](../health-checks). |
 | `nginx.com/slow-start` | N/A | Sets the upstream server [slow-start period](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/#server-slow-start). By default, slow-start is activated after a server becomes [available](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/#passive-health-checks) or [healthy](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/#active-health-checks). To enable slow-start for newly added servers, configure [mandatory active health checks](../health-checks). | `"0s"` | |
+| N/A | `external-status-address` | Sets the address to be reported in the status of Ingress resources. Requires the `-report-status` command-line argument. Overrides the `-external-service` argument. | N/A | [Report Ingress Status](../../docs/report-ingress-status.md). |
 
 ## Using ConfigMaps
 

examples/openshift/nginx-ingress-rc.yaml

@@ -28,6 +28,10 @@ spec:
           valueFrom:
             fieldRef:
               fieldPath: metadata.namespace
+        - name: POD_NAME
+          valueFrom:
+            fieldRef:
+              fieldPath: metadata.name
         # Uncomment the lines below to enable extensive logging and/or customization of
         # NGINX configuration with configmaps
         args:

examples/openshift/nginx-plus-ingress-rc.yaml

@@ -30,6 +30,10 @@ spec:
           valueFrom:
             fieldRef:
               fieldPath: metadata.namespace
+        - name: POD_NAME
+          valueFrom:
+            fieldRef:
+              fieldPath: metadata.name
         # Uncomment the lines below to enable extensive logging and/or customization of
         # NGINX configuration with configmaps
         args:

helm-chart/templates/controller-daemonset.yaml

@@ -57,6 +57,10 @@ spec:
           valueFrom:
             fieldRef:
               fieldPath: metadata.namespace
+        - name: POD_NAME
+          valueFrom:
+            fieldRef:
+              fieldPath: metadata.name
         args:
 {{- if .Values.controller.nginxplus }}
           - -nginx-plus

helm-chart/templates/controller-deployment.yaml

@@ -43,6 +43,10 @@ spec:
           valueFrom:
             fieldRef:
               fieldPath: metadata.namespace
+        - name: POD_NAME
+          valueFrom:
+            fieldRef:
+              fieldPath: metadata.name
         args:
 {{- if .Values.controller.nginxplus }}
           - -nginx-plus

helm-chart/templates/rbac.yaml

@@ -15,17 +15,27 @@ rules:
   - services
   - endpoints
   verbs:
+  - get
   - list
   - watch
 - apiGroups:
   - ""
   resources:
-  - configmaps
   - secrets
   verbs:
   - get
   - list
   - watch
+- apiGroups:
+  - ""
+  resources:
+  - configmaps
+  verbs:
+  - get
+  - list
+  - watch
+  - update
+  - create
 - apiGroups:
   - ""
   resources:
@@ -46,6 +56,12 @@ rules:
   verbs:
   - list
   - watch
+- apiGroups:
+  - "extensions"
+  resources:
+  - ingresses/status
+  verbs:
+  - update
 ---
 kind: ClusterRoleBinding
 apiVersion: rbac.authorization.k8s.io/v1beta1

install/daemon-set/nginx-ingress.yaml

@@ -22,13 +22,20 @@ spec:
           hostPort: 80
         - name: https
           containerPort: 443
-          hostPort: 443 
+          hostPort: 443
         env:
         - name: POD_NAMESPACE
           valueFrom:
             fieldRef:
               fieldPath: metadata.namespace
+        - name: POD_NAME
+          valueFrom:
+            fieldRef:
+              fieldPath: metadata.name
         args:
           - -nginx-configmaps=$(POD_NAMESPACE)/nginx-config
           - -default-server-tls-secret=$(POD_NAMESPACE)/default-server-secret
          #- -v=3 # Enables extensive logging. Useful for trooublshooting.
+         #- -report-ingress-status
+         #- -external-service=nginx-ingress
+         #- -enable-leader-election

install/daemon-set/nginx-plus-ingress-with-prometheus.yaml

@@ -31,11 +31,18 @@ spec:
           valueFrom:
             fieldRef:
               fieldPath: metadata.namespace
+        - name: POD_NAME
+          valueFrom:
+            fieldRef:
+              fieldPath: metadata.name
         args:
           - -nginx-plus
           - -nginx-configmaps=$(POD_NAMESPACE)/nginx-config
           - -default-server-tls-secret=$(POD_NAMESPACE)/default-server-secret
          #- -v=3 # Enables extensive logging. Useful for trooublshooting.
+         #- -report-ingress-status
+         #- -external-service=nginx-ingress
+         #- -enable-leader-election
       - image: nginx/nginx-prometheus-exporter:0.1.0
         name: nginx-prometheus-exporter
         ports:

install/daemon-set/nginx-plus-ingress.yaml

@@ -28,8 +28,15 @@ spec:
           valueFrom:
             fieldRef:
               fieldPath: metadata.namespace
+        - name: POD_NAME
+          valueFrom:
+            fieldRef:
+              fieldPath: metadata.name
         args:
           - -nginx-plus
           - -nginx-configmaps=$(POD_NAMESPACE)/nginx-config
           - -default-server-tls-secret=$(POD_NAMESPACE)/default-server-secret
          #- -v=3 # Enables extensive logging. Useful for trooublshooting.
+         #- -report-ingress-status
+         #- -external-service=nginx-ingress
+         #- -enable-leader-election

install/deployment/nginx-ingress.yaml

@@ -27,7 +27,14 @@ spec:
           valueFrom:
             fieldRef:
               fieldPath: metadata.namespace
+        - name: POD_NAME
+          valueFrom:
+            fieldRef:
+              fieldPath: metadata.name
         args:
           - -nginx-configmaps=$(POD_NAMESPACE)/nginx-config
           - -default-server-tls-secret=$(POD_NAMESPACE)/default-server-secret
          #- -v=3 # Enables extensive logging. Useful for trooublshooting.
+         #- -report-ingress-status
+         #- -external-service=nginx-ingress
+         #- -enable-leader-election

install/deployment/nginx-plus-ingress-with-prometheus.yaml

@@ -30,11 +30,18 @@ spec:
           valueFrom:
             fieldRef:
               fieldPath: metadata.namespace
+        - name: POD_NAME
+          valueFrom:
+            fieldRef:
+              fieldPath: metadata.name
         args:
           - -nginx-plus
           - -nginx-configmaps=$(POD_NAMESPACE)/nginx-config
           - -default-server-tls-secret=$(POD_NAMESPACE)/default-server-secret
          #- -v=3 # Enables extensive logging. Useful for trooublshooting.
+         #- -report-ingress-status
+         #- -external-service=nginx-ingress
+         #- -enable-leader-election
       - image: nginx/nginx-prometheus-exporter:0.1.0
         name: nginx-prometheus-exporter
         ports:

install/deployment/nginx-plus-ingress.yaml

@@ -27,8 +27,15 @@ spec:
           valueFrom:
             fieldRef:
               fieldPath: metadata.namespace
+        - name: POD_NAME
+          valueFrom:
+            fieldRef:
+              fieldPath: metadata.name
         args:
           - -nginx-plus
           - -nginx-configmaps=$(POD_NAMESPACE)/nginx-config
           - -default-server-tls-secret=$(POD_NAMESPACE)/default-server-secret
          #- -v=3 # Enables extensive logging. Useful for trooublshooting.
+         #- -report-ingress-status
+         #- -external-service=nginx-ingress
+         #- -enable-leader-election

install/rbac/rbac.yaml

@@ -8,18 +8,28 @@ rules:
   resources:
   - services
   - endpoints
-  verbs: 
+  verbs:
+  - get
   - list
   - watch
-- apiGroups: 
+- apiGroups:
   - ""
   resources:
-  - configmaps
   - secrets
   verbs:
   - get
   - list
   - watch
+- apiGroups:
+  - ""
+  resources:
+  - configmaps
+  verbs:
+  - get
+  - list
+  - watch
+  - update
+  - create
 - apiGroups:
   - ""
   resources:
@@ -40,6 +50,12 @@ rules:
   verbs:
   - list
   - watch
+- apiGroups:
+  - "extensions"
+  resources:
+  - ingresses/status
+  verbs:
+  - update
 ---
 kind: ClusterRoleBinding
 apiVersion: rbac.authorization.k8s.io/v1beta1
@@ -51,5 +67,5 @@ subjects:
   namespace: nginx-ingress
 roleRef:
   kind: ClusterRole
-  name: nginx-ingress 
-  apiGroup: rbac.authorization.k8s.io
+  name: nginx-ingress
+  apiGroup: rbac.authorization.k8s.io