1
0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 12:46:18 +01:00

OSDOCS-13371-2:Ingress Controller Parameters

This commit is contained in:
Ted Avery
2025-04-02 15:51:26 -04:00
committed by openshift-cherrypick-robot
parent 6023dd7b8b
commit 104cfdf753
5 changed files with 220 additions and 45 deletions

View File

@@ -12,6 +12,10 @@ include::modules/microshift-ingress-controller-conc.adoc[leveloffset=+1]
include::modules/microshift-ingress-controller-config.adoc[leveloffset=+1]
include::modules/microshift-ingress-controller-create-certificate-secret.adoc[leveloffset=+2]
include::modules/microshift-ingress-controller-tls-config.adoc[leveloffset=+2]
[id="additional-resources_microshift-ingress-controller_{context}"]
[role="_additional-resources"]
== Additional resources

View File

@@ -13,4 +13,11 @@ With more configuration options, you can fine-tune ingress to meet your specific
* If your application starts processing requests from clients but the connection is
closed before it can respond, you can set the `ingress.tuningOptions.serverTimeout` parameter in the configuration file to a higher value to accommodate the speed of the response from the server.
* If the router has many connections open because an application running on the cluster does not close connections properly, you can set the `ingress.tuningOptions.serverTimeout` and `spec.tuningOptions.serverFinTimeout` parameters to a lower value, forcing those connections to close sooner.
* If the router has many connections open because an application running on the cluster does not close connections properly, you can set the `ingress.tuningOptions.serverTimeout` and `spec.tuningOptions.serverFinTimeout` parameters to a lower value, forcing those connections to close sooner.
* If you need to configure the ingress controller to verify client certificates, you can use the `ingress.clientTLS` parameter to set a clientCA value, which is a reference to a config map. The config map contains the PEM-encoded CA certificate bundle that is used to verify a client's certificate. Optionally, you can also configure a list of certificate subject filters.
* If you need to configure a TLS security profile for an ingress controller, you can use the `ingress.tlsSecurityProfile` parameter to specify a default or custom individual TLS security profiles. The TLS security profile defines the minimum TLS version and the TLS ciphers for TLS connections for the ingress controllers.
If a TLS security profile is not configured, the default value is based on the TLS security profile set for the API server.
* If you need to define a policy for handling new route claims, you can use the `routeAdmission` parameter to allow or deny claims across namespaces. You set the `routeAdmission` parameter to describe how hostname claims across namespaces should be handled and to describe how routes with wildcard policies are handled by the ingress controller.

View File

@@ -33,27 +33,42 @@ You can use detailed ingress control settings by updating the {microshift-short}
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
certificateSecret: router-certs-custom
clientTLS:
allowedSubjectPatterns: ^/CN=example.com/ST=NC/C=US/O=Security/OU=OpenShift$
clientCA: ca-config-map
clientCertificatePolicy: Required
defaultHTTPVersion: 1
forwardedHeaderPolicy: Append
httpCompression:
mimeTypes:
- ""
httpEmptyRequestsPolicy: Respond
logEmptyRequests: Log
routeAdmission:
namespaceOwnership: InterNamespaceAllowed
wildcardPolicy: WildcardPolicyAllowed
tlsSecurityProfile:
type: Custom
custom:
ciphers:
- ECDHE-ECDSA-CHACHA20-POLY1305
- ECDHE-RSA-CHACHA20-POLY1305
- ECDHE-RSA-AES128-GCM-SHA256
- ECDHE-ECDSA-AES128-GCM-SHA256
minTLSVersion: VersionTLS12
tuningOptions:
clientFinTimeout: 1s
clientTimeout: 30s
headerBufferBytes: 0
headerBufferMaxRewriteBytes: 0
healthCheckInterval: 5s
maxConnections: 0
serverFinTimeout: 1s
serverTimeout: 30s
threadCount: 4
tlsInspectDelay: 5s
tunnelTimeout: 1h
# ...
----
+
@@ -62,6 +77,29 @@ ingress:
|===
|Parameter |Description
|`certificateSecret`
|The `certificateSecret` value is a reference to a secret that contains the default certificate that is served by the ingress controller. When routes do not specify their own certificate, `certificateSecret` is used.
The secret must contain the following keys and data:
* `tls.crt`: certificate file contents
* `tls.key`: key file contents
If not set, a wildcard certificate is automatically generated and used. The certificate is valid for the ingress controller `domain` and `subdomains`, and the generated certificate's CA is automatically integrated with the cluster's truststore.
The in-use certificate, whether generated or user-specified, is automatically integrated with {microshift-short} built-in OAuth server.
|`clientTLS`
|`clientTLS` authenticates client access to the cluster and services. As a result, mutual TLS authentication is enabled. If not set, then client TLS is not enabled.
`clientTLS` has the required subfields, `spec.clientTLS.clientCertificatePolicy` and `spec.clientTLS.ClientCA`.
The `ClientCertificatePolicy` subfield accepts one of the two values: `Required` or `Optional`. The ingress controller only checks client certificates for edge-terminated and re-encrypted TLS routes. The ingress controller cannot check certificates for plain text HTTP or passthrough TLS routes.
The `ClientCA` subfield specifies a config map that is in the openshift-ingress namespace. The config map should contain a CA certificate bundle. A config map is required for this field.
The `AllowedSubjectPatterns` is an optional value that specifies a list of regular expressions, which are matched against the distinguished name on a valid client certificate to filter requests. The regular expressions must use PCRE syntax. This field must contain a valid expression or the MicroShift service fails. At least one pattern must match a client certificate's distinguished name; otherwise, the ingress controller rejects the certificate and denies the connection. If the field value is not set, the ingress controller does not reject certificates based on the distinguished name.
|`defaultHTTPVersion`
|Sets the HTTP version for the ingress controller. Default value is `1` for HTTP 1.1.
//Q: do we need to configure a load balancer for 2 and 3?
@@ -77,62 +115,109 @@ ingress:
|`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 link:https://datatracker.ietf.org/doc/html/rfc1341#page-7[RFC1341] (IETF Datatracker documentation).
* `httpCompressionmimeTypes` defines a list of MIME types to which compression should be 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).
|`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:
|`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`.
* `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.
The `httpEmptyRequestsPolicy` type accepts either one of two values:
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.
* `Respond`: If the field is set to `Respond`, the ingress controller sends an HTTP `400` or `408` response, logs the connection if access logging is enabled, and counts the connection in the appropriate metrics.
* `Ignore`: Setting the option to `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.
These connections come from load-balancer health probes or preconnects and can be safely ignored. However, these requests can be caused by network errors, so setting this field to `Ignore` can impede detection or diagnosis of problems. These requests can be caused by port scans, in which case logging empty requests can aid in detecting 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.
|`logEmptyRequests` specifies connections for which no request is received and logged. These empty requests come from load balancer health probes or web browser speculative connections (preconnect) and logging these requests can be undesirable. However, these requests can be caused by network errors, in which case logging empty requests can be useful for diagnosing the errors. These requests can be caused by port scans, and logging empty requests can aid in detecting intrusion attempts. Allowed values for this field are `Log` and `Ignore`. The default is `Log`.
The following are valid values:
The `LoggingPolicy` type accepts either one of two values:
* `Log`, which indicates that an event should be logged.
* `Ignore`, which sets the `dontlognull` option in the `HAproxy` configuration.
* `Log`: Setting this value to `Log` indicates that an event should be logged.
* `Ignore`: Setting this value to `Ignore` sets the `dontlognull` option in the HAproxy configuration.
|`routeAdmission`
|`routeAdmission` defines a policy for handling new route claims, such as allowing or denying claims across namespaces.
`namespaceOwnership` describes how hostname claims across namespaces should be handled. The default is `InterNamespaceAllowed`.
* `Strict`: does not allow routes to claim the same hostname across namespaces.
* `InterNamespaceAllowed`: allows routes to claim different paths of the same hostname across namespaces.
`wildcardPolicy` describes how routes with wildcard policies are handled by the ingress controller.
* `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 The default value can change in future releases.
|`tlsSecurityProfile`
|`tlsSecurityProfile` specifies settings for TLS connections for Ingress Controllers.
If not set, the default value is based on the `apiservers.config.openshift.io/cluster` resource.
`Intermediate` is the default setting.
The minimum TLS version for ingress controllers is `1.1`. The maximum TLS version is `1.3`.
[NOTE]
====
Ciphers and the minimum TLS version of the configured security profile are reflected in the `TLSProfile` status.
====
[IMPORTANT]
====
The TLS `1.0` version of an `Old` or `Custom` profile is automatically converted to `1.1` by the ingress controller.
====
|`tuningOptions`
|Specifies options for tuning the performance of ingress controller pods.
|`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`.
* `clientFinTimeout` 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`.
* `clientTimeout` 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.
* `headerBufferBytes` 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.
* `headerBufferMaxRewriteBytes` 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`. `headerBufferBytes` 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.
Setting this field is not recommended because `headerBufferMaxRewriteBytes` values that are too small can break the ingress controller and `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`.
* `healthCheckInterval` 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`.
* `serverFinTimeout` 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`.
* `serverTimeout` 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.
* `threadCount` 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, the ingress controller uses the default value of `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.
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. Reducing the number of threads can cause the ingress controller to perform poorly.
====
* 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`.
* `tlsInspectDelay` 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`.
* `tunnelTimeout` specifies how long a tunnel connection, including websockets, remains open while the tunnel is idle. The default timeout is `1h`.
* `maxConnections` specifies the maximum number of simultaneous connections that can be established per HAProxy process. Increasing this value allows each ingress controller pod to handle more connections at the cost of additional system resources. Permitted values are `0`, `-1`, any value within the range `2000` and `2000000`, or the field can be left empty.
** If this field is left empty or has the value `0`, the ingress controller uses the default value of `50000`. This value is subject to change in future releases.
** If the field has the value of `-1`, then HAProxy dynamically computes a maximum value based on the available `ulimits` in the running container. This process results in a large computed value that incurs significant memory usage compared to the current default value of `50000`.
** If the field has a value that is greater than the current operating system limit, the `HAProxy` processes do not start.
** If you choose a discrete value and the router pod is migrated to a new node, it is possible that the new node does not have an identical `ulimit` configured. In such cases, the pod fails to start.
** If you have nodes with different `ulimits` configured, and you choose a discrete value, it is recommended to use the value of `-1` for this field so that the maximum number of connections is calculated at runtime.
**
* The `tuningOptions.tunnelTimeout` parameter specifies how long a tunnel connection, including websockets, remains open while the tunnel is idle. The default timeout is `1h`.
|===
. Complete any other configurations you require, then start or restart {microshift-short} by running one the following commands:

View File

@@ -0,0 +1,36 @@
// Module included in the following assemblies:
//
// * microshift_configuring/microshift-ingress-controller.adoc
:_mod-docs-content-type: PROCEDURE
[id="microshift-ingress-controller-create-certificate-secret_{context}"]
= Creating a secret for the ingress controller certificate
* The `certificateSecret` parameter value is a reference to a secret that contains the default certificate that is served by the ingress controller. When routes do not specify their own certificate, the `certificateSecret` parameter is used. The certificate is valid for the ingress controller domain and subdomains, and the generated certificate's CA is automatically integrated with the cluster's truststore.
The in-use certificate, whether generated or user-specified, is automatically integrated with the {microshift-short} built-in OAuth server.
.Prerequisites
* The private key must be unencrypted. If your key is encrypted, decrypt it before importing it into {microshift-short}.
* The certificate must include the `subjectAltName` extension showing `*.apps.<clustername>.<domain>`.
.Procedure
. Create a secret that contains the wildcard certificate chain and key:
+
[source,terminal]
----
$ oc create secret tls <secret> <1>
--cert=</path/to/cert.crt> <2>
--key=</path/to/cert.key> <3>
-n openshift-ingress
----
<1> `<secret>` is the name of the secret that contains the certificate chain and private key.
<2> `</path/to/cert.crt>` is the path to the certificate chain on your local file system.
<3> `</path/to/cert.key>` is the path to the private key associated with this certificate.
+
. Update the `certificateSecret` parameter value in the {microshift-short} YAML configuration file with the newly created secret.
+
. Restart the {microshift-short} service.

View File

@@ -0,0 +1,43 @@
// Module included in the following assemblies:
//
// * microshift_configuring/microshift-ingress-controller.adoc
:_mod-docs-content-type: PROCEDURE
[id="microshift-ingress-controller-config_{context}"]
= Configuring the TLS security profile for the ingress controller
You can configure the TLS security profile for the ingress controller to use by setting the type in {microshift-short} configuration YAML.
.Prerequisites
* You have root access to the {microshift-short} cluster.
.Procedure
. Add the `spec.tlsSecurityProfile` field to the {microshift-short} YAML configuration file.
+
[source,yaml]
----
...
spec:
tlsSecurityProfile:
type: Custom <1>
custom: <2>
ciphers: <3>
- ECDHE-ECDSA-CHACHA20-POLY1305
- ECDHE-RSA-CHACHA20-POLY1305
- ECDHE-RSA-AES128-GCM-SHA256
- ECDHE-ECDSA-AES128-GCM-SHA256
minTLSVersion: VersionTLS11
...
----
<1> Specify the TLS security profile type (`Old`, `Intermediate`, or `Custom`). The default is `Intermediate`.
<2> Specify the appropriate field for the selected type:
* `old: {}`
* `intermediate: {}`
* `custom:`
<3> For the `custom` type, specify a list of TLS ciphers and minimum accepted TLS version.
+
. Save the file to apply the changes.
+
. Restart the {microshift-short} service.