Report ingress status (#325)

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