|
| 1 | + |
| 2 | +// Module included in the following assemblies: |
| 3 | +// |
| 4 | +// * microshift_configuring/microshift-ingress-controller.adoc |
| 5 | + |
| 6 | +:_mod-docs-content-type: PROCEDURE |
| 7 | +[id="microshift-ingress-control-config_{context}"] |
| 8 | += Configuring ingress control in {microshift-short} |
| 9 | + |
| 10 | +You can use detailed ingress control settings by updating the {microshift-short} service configuration file. |
| 11 | + |
| 12 | +.Prerequisites |
| 13 | + |
| 14 | +* You installed the OpenShift CLI (`oc`). |
| 15 | +* You have root access to the cluster. |
| 16 | +* Your cluster uses the OVN-Kubernetes network plugin. |
| 17 | +
|
| 18 | +.Procedure |
| 19 | + |
| 20 | +. Apply ingress control settings in one of the two following ways: |
| 21 | + |
| 22 | +.. Update the {microshift-short} `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. |
| 23 | +* After you create it, the `config.yaml` file takes precedence over built-in settings. The configuration file is read every time the {microshift-short} service starts. |
| 24 | +
|
| 25 | +.. 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 the `/etc/microshift/config.d/` configuration directory. |
| 26 | +* Configuration snippet YAMLs take precedence over both built-in settings and a `config.yaml` configuration file. See the Additional resources links for more information. |
| 27 | +
|
| 28 | +. Replace the default values in the `network` section of the {microshift-short} YAML with your valid values, or create a configuration snippet file with the sections you need. |
| 29 | ++ |
| 30 | +.Ingress controller configuration fields with default values |
| 31 | +[source,yaml] |
| 32 | +---- |
| 33 | +apiServer: |
| 34 | +# ... |
| 35 | +ingress: |
| 36 | + defaultHTTPVersion: 1 |
| 37 | + forwardedHeaderPolicy: Append |
| 38 | + httpCompression: |
| 39 | + mimeTypes: |
| 40 | + - "" |
| 41 | + httpEmptyRequestsPolicy: Respond |
| 42 | +# ... |
| 43 | + logEmptyRequests: Log |
| 44 | +# ... |
| 45 | + tuningOptions: |
| 46 | + clientFinTimeout: 1s |
| 47 | + clientTimeout: 30s |
| 48 | + headerBufferBytes: 0 |
| 49 | + headerBufferMaxRewriteBytes: 0 |
| 50 | + healthCheckInterval: 5s |
| 51 | + maxConnections: 0 |
| 52 | + serverFinTimeout: 1s |
| 53 | + serverTimeout: 30s |
| 54 | + threadCount: 4 |
| 55 | + tlsInspectDelay: 5s |
| 56 | + tunnelTimeout: 1h |
| 57 | +# ... |
| 58 | +---- |
| 59 | ++ |
| 60 | +.Ingress controller configuration fields definitions table |
| 61 | +[cols="3a,8a",options="header"] |
| 62 | +|=== |
| 63 | +|Parameter |Description |
| 64 | + |
| 65 | +|`defaultHTTPVersion` |
| 66 | +|Sets the HTTP version for the ingress controller. Default value is `1` for HTTP 1.1. |
| 67 | +//Q: do we need to configure a load balancer for 2 and 3? |
| 68 | + |
| 69 | +|`forwardedHeaderPolicy` |
| 70 | +|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: |
| 71 | + |
| 72 | +* `Append`, preserves any existing headers by specifying that the ingress controller appends them. |
| 73 | +* `Replace`, removes any existing headers by specifying that the ingress controller sets the headers. |
| 74 | +* `IfNone` sets the headers set by specifying that the ingress controller sets the headers if they are not already set. |
| 75 | +* `Never`, preserves any existing headers by specifying that the ingress controller never sets the headers. |
| 76 | +
|
| 77 | +|`httpCompression` |
| 78 | +|Defines the policy for HTTP traffic compression. |
| 79 | + |
| 80 | +* `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 link:https://datatracker.ietf.org/doc/html/rfc1341#page-7[RFC1341] (IETF Datatracker documentation). |
| 81 | +
|
| 82 | +|`httpEmptyRequestsPolicy` |
| 83 | +|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: |
| 84 | + |
| 85 | +* `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. |
| 86 | +* `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. |
| 87 | +
|
| 88 | +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. |
| 89 | + |
| 90 | +|`logEmptyRequests` |
| 91 | +|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. |
| 92 | + |
| 93 | +The following are valid values: |
| 94 | + |
| 95 | +* `Log`, which indicates that an event should be logged. |
| 96 | +* `Ignore`, which sets the `dontlognull` option in the `HAproxy` configuration. |
| 97 | +
|
| 98 | +|`tuningOptions` |
| 99 | +|Specifies options for tuning the performance of ingress controller pods. |
| 100 | + |
| 101 | +* 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`. |
| 102 | +
|
| 103 | +* The `tuningOptions.clientTimeout` parameter specifies how long a connection is held open while waiting for a client response. The default timeout is `30s`. |
| 104 | +
|
| 105 | +* 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. |
| 106 | ++ |
| 107 | +[IMPORTANT] |
| 108 | +==== |
| 109 | +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. |
| 110 | +==== |
| 111 | +
|
| 112 | +* 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. |
| 113 | +* If not set, the default value is `8192` bytes. |
| 114 | ++ |
| 115 | +[IMPORTANT] |
| 116 | +==== |
| 117 | +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. |
| 118 | +==== |
| 119 | +
|
| 120 | +* The `tuningOptions.healthCheckInterval` parameter specifies how long the router waits between health checks. The default is `5s`. |
| 121 | +
|
| 122 | +* 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`. |
| 123 | +
|
| 124 | +* The `tuningOptions.serverTimeout` parameter specifies how long a connection is held open while waiting for a server response. The default timeout is `30s`. |
| 125 | +
|
| 126 | +* 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. |
| 127 | ++ |
| 128 | +[IMPORTANT] |
| 129 | +==== |
| 130 | +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. |
| 131 | +==== |
| 132 | +
|
| 133 | +* 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`. |
| 134 | +
|
| 135 | +* The `tuningOptions.tunnelTimeout` parameter specifies how long a tunnel connection, including websockets, remains open while the tunnel is idle. The default timeout is `1h`. |
| 136 | +|=== |
| 137 | +
|
| 138 | +. Complete any other configurations you require, then start or restart {microshift-short} by running one the following commands: |
| 139 | ++ |
| 140 | +[source,terminal] |
| 141 | +---- |
| 142 | +$ sudo systemctl start microshift |
| 143 | +---- |
| 144 | ++ |
| 145 | +[source,terminal] |
| 146 | +---- |
| 147 | +$ sudo systemctl restart microshift |
| 148 | +---- |
| 149 | + |
| 150 | +.Verification |
| 151 | + |
| 152 | +After making ingress configuration changes and restarting {microshift-short}, you can check the age of the router pod to ensure that changes have been applied. |
| 153 | + |
| 154 | +* To check the status of the router pod, run the following command: |
| 155 | ++ |
| 156 | +[source,terminal] |
| 157 | +---- |
| 158 | +$ oc get pods -n openshift-ingress |
| 159 | +---- |
| 160 | ++ |
| 161 | +.Example output |
| 162 | ++ |
| 163 | +[source,terminal] |
| 164 | +---- |
| 165 | +NAME READY STATUS RESTARTS AGE |
| 166 | +router-default-8649b5bf65-w29cn 1/1 Running 0 6m10s |
| 167 | +---- |
0 commit comments