Document and improve UX of ingress status feature.

Fixes projectcontour#403.

Updates the `--ingress-status-address`, `--envoy-service-name`, and `--envoy-service-namespace` flags to be also readable from the config file.

The `serveContext` fields needed to be exported in order for the export to work.

Updated some logging to ensure that you can tell easily which settings are in effect.

Signed-off-by: Nick Young <ynick@vmware.com>

cmd/contour/ingressstatus.go

@@ -74,7 +74,7 @@ func (isw *loadBalancerStatusWriter) Start(stop <-chan struct{}) error {
 			}
 			ingressInformers.Wait()
 
-			isw.log.Info("Received a new address for status.loadBalancer")
+			isw.log.WithField("loadbalancer", lbAddress(lbs)).Info("Received a new address for status.loadBalancer")
 
 			// Create new informer for the new LoadBalancerStatus
 			factory := isw.clients.NewInformerFactory()
@@ -121,3 +121,12 @@ func parseStatusFlag(status string) v1.LoadBalancerStatus {
 		},
 	}
 }
+
+// lbAddress gets the string representation of the first address, for logging.
+func lbAddress(lb v1.LoadBalancerStatus) string {
+	if lb.Ingress[0].IP != "" {
+		return lb.Ingress[0].IP
+	}
+
+	return lb.Ingress[0].Hostname
+}

cmd/contour/serve.go

@@ -103,15 +103,15 @@ func registerServe(app *kingpin.Application) (*kingpin.CmdClause, *serveContext)
 	serve.Flag("root-namespaces", "Restrict contour to searching these namespaces for root ingress routes.").StringVar(&ctx.rootNamespaces)
 
 	serve.Flag("ingress-class-name", "Contour IngressClass name.").StringVar(&ctx.ingressClass)
-	serve.Flag("ingress-status-address", "Address to set in Ingress object status.").StringVar(&ctx.ingressStatusAddress)
+	serve.Flag("ingress-status-address", "Address to set in Ingress object status.").StringVar(&ctx.IngressStatusAddress)
 	serve.Flag("envoy-http-access-log", "Envoy HTTP access log.").StringVar(&ctx.httpAccessLog)
 	serve.Flag("envoy-https-access-log", "Envoy HTTPS access log.").StringVar(&ctx.httpsAccessLog)
 	serve.Flag("envoy-service-http-address", "Kubernetes Service address for HTTP requests.").StringVar(&ctx.httpAddr)
 	serve.Flag("envoy-service-https-address", "Kubernetes Service address for HTTPS requests.").StringVar(&ctx.httpsAddr)
 	serve.Flag("envoy-service-http-port", "Kubernetes Service port for HTTP requests.").IntVar(&ctx.httpPort)
 	serve.Flag("envoy-service-https-port", "Kubernetes Service port for HTTPS requests.").IntVar(&ctx.httpsPort)
-	serve.Flag("envoy-service-name", "Envoy Service Name.").StringVar(&ctx.envoyServiceName)
-	serve.Flag("envoy-service-namespace", "Envoy Service Namespace.").StringVar(&ctx.envoyServiceNamespace)
+	serve.Flag("envoy-service-name", "Envoy Service Name.").StringVar(&ctx.EnvoyServiceName)
+	serve.Flag("envoy-service-namespace", "Envoy Service Namespace.").StringVar(&ctx.EnvoyServiceNamespace)
 	serve.Flag("use-proxy-protocol", "Use PROXY protocol for all listeners.").BoolVar(&ctx.useProxyProto)
 
 	serve.Flag("accesslog-format", "Format for Envoy access logs.").StringVar(&ctx.AccessLogFormat)
@@ -304,18 +304,20 @@ func doServe(log logrus.FieldLogger, ctx *serveContext) error {
 	g.Add(lbsw.Start)
 
 	// step 12. register an informer to watch envoy's service if we haven't been given static details.
-	if ctx.ingressStatusAddress == "" {
+	if ctx.IngressStatusAddress == "" {
 		ssw := &k8s.ServiceStatusLoadBalancerWatcher{
-			ServiceName: ctx.envoyServiceName,
+			ServiceName: ctx.EnvoyServiceName,
 			LBStatus:    lbsw.lbStatus,
 		}
-		factory := clients.NewInformerFactoryForNamespace(ctx.envoyServiceNamespace)
+		factory := clients.NewInformerFactoryForNamespace(ctx.EnvoyServiceNamespace)
 		factory.Core().V1().Services().Informer().AddEventHandler(ssw)
 		g.Add(startInformer(factory, log.WithField("context", "serviceStatusLoadBalancerWatcher")))
+		log.WithField("envoy-service-name", ctx.EnvoyServiceName).WithField("envoy-service-namespace", ctx.EnvoyServiceNamespace).Info("Watching Service for Ingress status")
 
 	} else {
-		log.Infof("setting Ingress status to %q, disabling watching %q service", ctx.ingressStatusAddress, ctx.envoyServiceName)
-		lbsw.lbStatus <- parseStatusFlag(ctx.ingressStatusAddress)
+		log.WithField("ingress-status-address", ctx.IngressStatusAddress).Info("Using supplied information for Ingress status")
+		log.Infof("setting Ingress status to %q, disabling watching %q service", ctx.IngressStatusAddress, ctx.EnvoyServiceName)
+		lbsw.lbStatus <- parseStatusFlag(ctx.IngressStatusAddress)
 	}
 
 	g.Add(func(stop <-chan struct{}) error {

cmd/contour/servecontext.go

@@ -32,6 +32,9 @@ import (
 )
 
 type serveContext struct {
+	// Note about parameter behavior: if the parameter is going to be in the config file,
+	// it has to be exported. If not, the YAML decoder will not see the field.
+
 	// Enable debug logging
 	Debug bool
 
@@ -63,7 +66,9 @@ type serveContext struct {
 	ingressClass string
 
 	// Address to be placed in status.loadbalancer field of Ingress objects.
-	ingressStatusAddress string
+	// May be either a literal IP address or another string.
+	// The value will be placed directly into the relevant field inside the status.loadBalancer struct.
+	IngressStatusAddress string `yaml:"ingress-status-address,omitempty"`
 
 	// envoy's stats listener parameters
 	statsAddr string
@@ -119,11 +124,11 @@ type serveContext struct {
 
 	// envoy service details
 
-	// Namespace of the envoy service
-	envoyServiceNamespace string `yaml:"-"`
+	// Namespace of the envoy service to inspect for Ingress status details.
+	EnvoyServiceNamespace string `yaml:"envoy-service-namespace,omitempty"`
 
-	// Name of the envoy service
-	envoyServiceName string `yaml:"-"`
+	// Name of the envoy service to inspect for Ingress status details.
+	EnvoyServiceName string `yaml:"envoy-service-name,omitempty"`
 }
 
 // newServeContext returns a serveContext initialized to defaults.
@@ -159,8 +164,8 @@ func newServeContext() *serveContext {
 			Name:          "leader-elect",
 		},
 		UseExperimentalServiceAPITypes: false,
-		envoyServiceName:               "envoy",
-		envoyServiceNamespace:          getEnv("CONTOUR_NAMESPACE", "projectcontour"),
+		EnvoyServiceName:               "envoy",
+		EnvoyServiceNamespace:          getEnv("CONTOUR_NAMESPACE", "projectcontour"),
 	}
 }
 

site/docs/master/configuration.md

@@ -19,6 +19,9 @@ Where Contour settings can also be specified with command-line flags, the comman
 | kubeconfig | string | `$HOME/.kube/config` | Path to a Kubernetes [kubeconfig file][3] for when Contour is executed outside a cluster. |
 | leaderelection | leaderelection | | The [leader election configuration](#leader-election-configuration). |
 | request-timeout | [duration][4] | `0s` | This field specifies the default request timeout as a Go duration string. Zero means there is no timeout. |
+| envoy-service-name | string | `envoy` | This sets the service name that will be inspected for address details to be applied to Ingress objects. |
+| envoy-service-namespace | string | `projectcontour` | This sets the service namespace that will be inspected for address details to be applied to Ingress objects. |
+| ingress-status-address | string | None | If present, this specifies the address that will be copied into the Ingress status for each Ingress Contour manages. It is exclusive with `envoy-service-name` and `envoy-service-namespace`.|
 | tls | TLS | | The default [TLS configuration](#tls-configuration). |
 {: class="table thead-dark table-bordered"}