Chapter 3. Using ingress control for a MicroShift cluster

Procedure

1. Apply ingress control settings in one of the two following ways:

   1. Update the MicroShift config.yaml configuration file by making a copy of the provided config.yaml.default file in the /etc/microshift/ directory, naming it config.yaml and keeping it in the source directory.

      • After you create it, the config.yaml file takes precedence over built-in settings. The configuration file is read every time the MicroShift service starts.

   2. Use a configuration snippet to apply the ingress control settings you want. To do this, create a configuration snippet YAML file and put it in the /etc/microshift/config.d/ configuration directory.

      • Configuration snippet YAMLs take precedence over both built-in settings and a config.yaml configuration file. See the Additional resources links for more information.

2. Replace the default values in the network section of the MicroShift YAML with your valid values, or create a configuration snippet file with the sections you need.

   Ingress controller configuration fields with default values

   apiServer:
   # ...
   ingress:
       defaultHTTPVersion: 1
       forwardedHeaderPolicy: Append
       httpCompression:
           mimeTypes:
               - ""
       httpEmptyRequestsPolicy: Respond
   # ...
       logEmptyRequests: Log
   # ...
       tuningOptions:
           clientFinTimeout: 1s
           clientTimeout: 30s
           headerBufferBytes: 0
           headerBufferMaxRewriteBytes: 0
           healthCheckInterval: 5s
           maxConnections: 0
           serverFinTimeout: 1s
           serverTimeout: 30s
           threadCount: 4
           tlsInspectDelay: 5s
           tunnelTimeout: 1h
   # ...

   Table 3.1. Ingress controller configuration fields definitions table

   Parameter	Description
   defaultHTTPVersion	Sets the HTTP version for the ingress controller. Default value is 1 for HTTP 1.1.
   forwardedHeaderPolicy	Specifies when and how the ingress controller sets the Forwarded, X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Port, X-Forwarded-Proto, and X-Forwarded-Proto-Version HTTP headers. The following values are valid: Append, preserves any existing headers by specifying that the ingress controller appends them. Replace, removes any existing headers by specifying that the ingress controller sets the headers. IfNone sets the headers set by specifying that the ingress controller sets the headers if they are not already set. Never, preserves any existing headers by specifying that the ingress controller never sets the headers.
   httpCompression	Defines the policy for HTTP traffic compression. httpCompression.mimeTypes defines a list of or a single MIME type to which compression is applied. For example, text/css; charset=utf-8, text/html, text/*, image/svg+xml, application/octet-stream, X-custom/customsub, using the format pattern, type/subtype; [;attribute=value]. The types are: application, image, message, multipart, text, video, or a custom type prefaced by X-. To see the full notation for MIME types and subtypes, see RFC1341 (IETF Datatracker documentation).
   httpEmptyRequestsPolicy	Describes how HTTP connections are handled if the connection times out before a request is received. Allowed values for this field are Respond and Ignore. The default value is Respond. The following are valid values: Respond, causes the ingress controller to send an HTTP 400 or 408 response, logs the connection if access logging is enabled, and counts the connection in the appropriate metrics. Ignore, adds the http-ignore-probes parameter in the HAproxy configuration. If the field is set to Ignore, the ingress controller closes the connection without sending a response, then logs the connection or incrementing metrics. Usually, empty request connections come from load balancer health probes or web browser preconnects and can be safely ignored. However, network errors and port scans can also create these empty requests, so setting this field to Ignore can impede detecting or diagnosing problems and also impede the detection of intrusion attempts.
   logEmptyRequests	Specifies connections for which no request is received and logged. Usually, these empty requests come from load balancer health probes or web browser speculative connections such as preconnects. Logging these types of empty requests can be undesirable. However, network errors and port scans can also create empty requests, so setting this field to Ignore can impede detecting or diagnosing problems and also impede the detection of intrusion attempts. The following are valid values: Log, which indicates that an event should be logged. Ignore, which sets the dontlognull option in the HAproxy configuration.
   tuningOptions	Specifies options for tuning the performance of ingress controller pods. The tuningOptions.clientFinTimeout parameter specifies how long a connection is held open while waiting for the client response to the server closing the connection. The default timeout is 1s. The tuningOptions.clientTimeout parameter specifies how long a connection is held open while waiting for a client response. The default timeout is 30s. The tuningOptions.headerBufferBytes parameter specifies how much memory is reserved, in bytes, for Ingress Controller connection sessions. This value must be at least 16384 if HTTP/2 is enabled for the Ingress Controller. If not set, the default value is 32768 bytes. Important Setting this field not recommended because headerBufferMaxRewriteBytes parameter values that are too small can break the ingress controller. Conversely, values for headerBufferMaxRewriteBytes that are too large could cause the ingress controller to use significantly more memory than necessary. The tuningOptions.headerBufferMaxRewriteBytes parameter specifies how much memory should be reserved, in bytes, from headerBufferBytes for HTTP header rewriting and appending for Ingress Controller connection sessions. The minimum value for headerBufferMaxRewriteBytes is 4096. The headerBufferBytes value must be greater than the headerBufferMaxRewriteBytes value for incoming HTTP requests. If not set, the default value is 8192 bytes. Important Setting this field is not recommended because headerBufferMaxRewriteBytes parameter values that are too small can break the ingress controller. Conversely, values for headerBufferMaxRewriteBytes that are too large could cause the ingress controller to use significantly more memory than necessary. The tuningOptions.healthCheckInterval parameter specifies how long the router waits between health checks. The default is 5s. The tuningOptions.serverFinTimeout parameter specifies how long a connection is held open while waiting for the server response to the client that is closing the connection. The default timeout is 1s. The tuningOptions.serverTimeout parameter specifies how long a connection is held open while waiting for a server response. The default timeout is 30s. The tuningOptions.threadCount parameter specifies the number of threads to create per HAProxy process. Creating more threads allows each ingress controller pod to handle more connections, at the cost of more system resources being used. HAProxy supports up to 64 threads. If this field is empty, default value is 4 threads. Important Setting this field is not recommended because increasing the number of HAProxy threads allows ingress controller pods to use more CPU time under load, and prevent other pods from receiving the CPU resources they need to perform. The tuningOptions.tlsInspectDelay parameter specifies how long the router can hold data to find a matching route. Setting this value too short can cause the router to fall back to the default certificate for edge-terminated, re-encrypted, or passthrough routes, even when using a better-matched certificate. The default inspect delay is 5s. The tuningOptions.tunnelTimeout parameter specifies how long a tunnel connection, including websockets, remains open while the tunnel is idle. The default timeout is 1h.

3. Complete any other configurations you require, then start or restart MicroShift by running one the following commands:

   $ sudo systemctl start microshift

   $ sudo systemctl restart microshift