OSDOCS-1002 Document Ingress Access Logging

modules/nw-configure-ingress-access-logging.adoc

@@ -0,0 +1,124 @@
+// Module included in the following assemblies:
+//
+// * ingress/configure-ingress-operator.adoc
+
+[id="nw-configure-ingress-access-logging_{context}"]
+= Configuring Ingress access logging
+
+You can configure the Ingress Controller to enable access logs. If you have clusters that do not receive much traffic, then you can log to a sidecar. If you have high traffic clusters, to avoid exceeding the capacity of the logging stack or  to integrate with a logging infrastructure outside of {product-title}, you can forward logs to a custom syslog endpoint. You can also specify the format for access logs.
+
+Container logging is useful to enable access logs on low-traffic clusters when there is no existing Syslog logging infrastructure, or for short-term use while diagnosing problems with the Ingress Controller.
+
+Syslog is needed for high-traffic clusters where access logs could exceed the cluster logging stack's capacity, or for environments where any logging solution needs to integrate with an existing Syslog logging infrastructure. The Syslog use-cases can overlap.
+
+.Prerequisites
+
+* Log in as a user with `cluster-admin` privileges.
+
+.Procedure
+
+Configure Ingress access logging to a sidecar.
+
+* To configure Ingress access logging, you must specify a destination using `spec.logging.access.destination`. To specify logging to a sidecar container, you must specify `Container` `spec.logging.access.destination.type`. The following example is an Ingress Controller definition that logs to a `Container` destination:
++
+[source, yaml]
+----
+apiVersion: operator.openshift.io/v1
+kind: IngressController
+metadata:
+  name: default
+  namespace: openshift-ingress-operator
+spec:
+  replicas: 2
+  endpointPublishingStrategy:
+    type: NodePortService <1>
+  logging:
+    access:
+      destination:
+        type: Container
+----
+<1> `NodePortService` is not required to configure Ingress access logging to a sidecar. Ingress logging is compatible with any `endpointPublishingStrategy`.
++
+* When you configure the Ingress Controller to log to a sidecar, the operator creates a container named `logs` inside the Ingress Controller Pod:
++
+----
+$ oc -n openshift-ingress logs deployment.apps/router-default -c logs
+----
++
+.Sample output:
+----
+2020-05-11T19:11:50.135710+00:00 router-default-57dfc6cd95-bpmk6 router-default-57dfc6cd95-bpmk6 haproxy[108]: 174.19.21.82:39654 [11/May/2020:19:11:50.133] public be_http:hello-openshift:hello-openshift/pod:hello-openshift:hello-openshift:10.128.2.12:8080 0/0/1/0/1 200 142 - - --NI 1/1/0/0/0 0/0 "GET / HTTP/1.1"
+----
+
+Configure Ingress access logging to a Syslog endpoint.
+
+* To configure Ingress access logging, you must specify a destination using `spec.logging.access.destination`. To specify logging to a Syslog endpoint destination, you must specify `Syslog` for `spec.logging.access.destination.type`. If the destination type is `Syslog`, you must also specify a destination endpoint using `spec.logging.access.destination.syslog.endpoint` and you can specify a facility using `spec.logging.access.destination.syslog.facility`. The following example is an Ingress Controller definition that logs to a `Syslog` destination:
++
+[source, yaml]
+----
+apiVersion: operator.openshift.io/v1
+kind: IngressController
+metadata:
+  name: default
+  namespace: openshift-ingress-operator
+spec:
+  replicas: 2
+  endpointPublishingStrategy:
+    type: NodePortService
+  logging:
+    access:
+      destination:
+        type: Syslog
+        syslog:
+          address: 1.2.3.4
+          port: 10514
+----
++
+[NOTE]
+====
+The `syslog` destination port must be UDP.
+====
+
+Configure Ingress access logging with a specific log format.
+
+* You can specify `spec.logging.access.httpLogFormat` to customize the log format. The following example is an Ingress Controller definition that logs to a `syslog` endpoint with IP address 1.2.3.4 and port 10514:
++
+[source, yaml]
+----
+apiVersion: operator.openshift.io/v1
+kind: IngressController
+metadata:
+  name: default
+  namespace: openshift-ingress-operator
+spec:
+  replicas: 2
+  endpointPublishingStrategy:
+    type: NodePortService
+  logging:
+    access:
+      destination:
+        type: Syslog
+        syslog:
+          address: 1.2.3.4
+          port: 10514
+      httpLogFormat: '%ci:%cp [%t] %ft %b/%s %B %bq %HM %HU %HV'
+----
+
+Disable Ingress access logging.
+
+* To disable Ingress access logging, leave `spec.logging` or `spec.logging.access` empty:
++
+[source, yaml]
+----
+apiVersion: operator.openshift.io/v1
+kind: IngressController
+metadata:
+  name: default
+  namespace: openshift-ingress-operator
+spec:
+  replicas: 2
+  endpointPublishingStrategy:
+    type: NodePortService
+  logging:
+    access: null
+----

modules/nw-ingress-controller-configuration-parameters.adoc

@@ -116,6 +116,20 @@ Ciphers and the minimum TLS version of the configured security profile are refle
 
 * `WildcardsDisallowed`: Indicates only routes with a wildcard policy of `None` are admitted by the Ingress Controller. Updating `wildcardPolicy` from `WildcardsAllowed` to `WildcardsDisallowed` causes admitted routes with a wildcard policy of `Subdomain` to stop working. These routes must be recreated to a wildcard policy of `None` to be readmitted by the Ingress Controller. `WildcardsDisallowed` is the default setting.
 
+|`IngressControllerLogging`
+|`logging` defines parameters for what is logged where. If this field is empty, operational logs are enabled but access logs are disabled.
+
+* `access` describes how client requests are logged. If this field is empty, access logging is disabled.
+** `destination` describes a destination for log messages.
+*** `type` is the type of destination for logs:
+**** `Container` specifies that logs should go to a sidecar container. The Ingress Operator configures the container, named *logs*, on the Ingress Controller Pod and configures the Ingress Controller to write logs to the container. The expectation is that the administrator configures a custom logging solution that reads logs from this container. Using container logs means that logs may be dropped if the rate of logs exceeds the container runtime capacity or the custom logging solution capacity.
+**** `Syslog` specifies that logs are sent to a Syslog endpoint. The administrator must specify an endpoint that can receive Syslog messages. The expectation is that the administrator has configured a custom Syslog instance.
+*** `container` describes parameters for the `Container` logging destination type. Currently there are no parameters for container logging, so this field must be empty.
+*** `syslog` describes parameters for the `Syslog` logging destination type:
+**** `address` is the IP address of the syslog endpoint that receives log messages.
+**** `port` is the UDP port number of the syslog endpoint that receives log messages.
+**** `facility` specifies the syslog facility of log messages. If this field is empty, the facility is `local1`. Otherwise, it must specify a valid syslog facility: `kern`, `user`, `mail`, `daemon`, `auth`, `syslog`, `lpr`, `news`, `uucp`, `cron`, `auth2`, `ftp`, `ntp`, `audit`, `alert`, `cron2`, `local0`, `local1`, `local2`, `local3`. `local4`, `local5`, `local6`, or `local7`.
+** `httpLogFormat` specifies the format of the log message for an HTTP request. If this field is empty, log messages use the implementation's default HTTP log format. For HAProxy's default HTTP log format, see link:the HAProxy documentation[http://cbonte.github.io/haproxy-dconv/2.0/configuration.html#8.2.3].
 |===
 
 

networking/ingress-operator.adoc

@@ -36,6 +36,8 @@ include::modules/nw-ingress-setting-a-custom-default-certificate.adoc[leveloffse
 
 include::modules/nw-scaling-ingress-controller.adoc[leveloffset=+1]
 
+include::modules/nw-configure-ingress-access-logging.adoc[leveloffset=+1]
+
 include::modules/nw-ingress-sharding-route-labels.adoc[leveloffset=+1]
 
 include::modules/nw-ingress-sharding-namespace-labels.adoc[leveloffset=+1]