diff --git a/microshift_configuring/microshift-ingress-controller.adoc b/microshift_configuring/microshift-ingress-controller.adoc index 4e8dbe4cd965..1e302385f87b 100644 --- a/microshift_configuring/microshift-ingress-controller.adoc +++ b/microshift_configuring/microshift-ingress-controller.adoc @@ -22,4 +22,4 @@ include::modules/microshift-ingress-controller-tls-config.adoc[leveloffset=+2] * xref:../microshift_configuring/microshift-using-config-yaml.adoc#microshift-config-snippets_microshift-configuring[Using configuration snippets] -* link:https://docs.redhat.com/container-platform/latest/networking/networking_operators/ingress-operator.html#nw-http2-haproxy_configuring-ingress[Enabling HTTP/2 Ingress connectivity] (OpenShift Container Platform documentation) +* link:https://docs.redhat.com/container-platform/latest/networking/networking_operators/ingress-operator.html#nw-http2-haproxy_configuring-ingress[Enabling HTTP/2 Ingress connectivity] ({OCP} documentation) diff --git a/modules/microshift-config-yaml-custom.adoc b/modules/microshift-config-yaml-custom.adoc index 4ec296564d87..3645e1caeeef 100644 --- a/modules/microshift-config-yaml-custom.adoc +++ b/modules/microshift-config-yaml-custom.adoc @@ -5,6 +5,7 @@ :_mod-docs-content-type: CONCEPT [id="microshift-yaml-custom_{context}"] = Using custom settings + To create custom configurations, make a copy of the `config.yaml.default` file that is provided in the `/etc/microshift/` directory, renaming it `config.yaml`. Keep this file in the `/etc/microshift/` directory, and then you can change supported settings that are expected to override the defaults before starting or restarting {microshift-short}. [IMPORTANT] diff --git a/modules/microshift-default-settings.adoc b/modules/microshift-default-settings.adoc index 9670adef7269..6cd2f30cab70 100644 --- a/modules/microshift-default-settings.adoc +++ b/modules/microshift-default-settings.adoc @@ -33,7 +33,15 @@ apiServer: subjectAltNames: [] tls: cipherSuites: - - "" + - TLS_AES_128_GCM_SHA256 + - TLS_AES_256_GCM_SHA384 + - TLS_CHACHA20_POLY1305_SHA256 + - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 + - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 + - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 + - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 + - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 + - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 minVersion: VersionTLS12 debugging: logLevel: "Normal" @@ -42,6 +50,31 @@ dns: etcd: memoryLimitMB: 0 ingress: + accessLogging: + destination: + type: + container: + maxLength: 1024 + syslog: + address: "" + facility: "" + maxLength: 1024 + port: 0 + type: "" + httpCaptureCookies: + - matchType: "" + maxLength: 0 + name: "" + namePrefix: "" + httpCaptureHeaders: + request: + - maxLength: 0 + name: "" + response: + - maxLength: 0 + name: "" + httpLogFormat: "" + status: Disabled certificateSecret: router-certs-default clientTLS: allowedSubjectPatterns: @@ -54,8 +87,9 @@ ingress: mimeTypes: - "" httpEmptyRequestsPolicy: Respond - listenAddress: - - "" + httpErrorCodePages: + name: "" + listenAddress: [] logEmptyRequests: Log ports: http: 80 @@ -65,14 +99,7 @@ ingress: wildcardPolicy: WildcardPolicyAllowed status: Managed 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 + type: Intermediate tuningOptions: clientFinTimeout: "1s" clientTimeout: "30s" diff --git a/modules/microshift-ingress-controller-conc.adoc b/modules/microshift-ingress-controller-conc.adoc index 4a9734cc79d7..1c16f98c7e61 100644 --- a/modules/microshift-ingress-controller-conc.adoc +++ b/modules/microshift-ingress-controller-conc.adoc @@ -6,18 +6,31 @@ [id="microshift-ingress-control-concept_{context}"] = Using ingress control in {microshift-short} -When you create your {microshift-short} cluster, each pod and service running on the cluster is allocated an IP address. These IP addresses are accessible to other pods and services running nearby by default, but are not accessible to external clients. {microshift-short} uses a minimal implementation of the {ocp} `IngressController` API to enable external access to cluster services. +When you create your {microshift-short} cluster, each pod and service running on the cluster is allocated an IP address. These IP addresses are accessible to other pods and services running nearby by default, but are not accessible to external clients. {microshift-short} uses a minimal implementation of the {OCP} `IngressController` API to enable external access to cluster services. -With more configuration options, you can fine-tune ingress to meet your specific needs. To use enhanced ingress control, update the parameters in the {microshift-short} configuration file and restart the service. Ingress configuration is useful in a variety of ways, for example: +With more configuration options, you can fine-tune ingress to meet your specific needs. To use enhanced ingress control, update the parameters in the {microshift-short} configuration file and restart the service. +Ingress configuration is useful in a variety of ways, for example: + +Accommodate server response speed:: * 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. +Closing router connections:: * 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. +Verify client certificates:: +* 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. +Configure a TLS security profile:: * 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. \ No newline at end of file +Create policies for new route claims:: +* 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. + +Customize error pages:: +* If you want more than the default error pages, which are usually empty and only return the http status code, configure custom error pages. + +Capture HTTP headers or cookies:: +* If you want to include the capture of HTTP headers or cookies, configure access logging. \ No newline at end of file diff --git a/modules/microshift-ingress-controller-config.adoc b/modules/microshift-ingress-controller-config.adoc index bcbfbb4006a8..37fd3b7a1b9e 100644 --- a/modules/microshift-ingress-controller-config.adoc +++ b/modules/microshift-ingress-controller-config.adoc @@ -41,6 +41,30 @@ Configuration snippet YAMLs take precedence over both built-in settings and the apiServer: # ... ingress: + accessLogging: + destination: + container: + maxLength: 1024 + syslog: + address: "" + facility: "" + maxLength: 1024 + port: 0 + type: "" + httpCaptureCookies: + - matchType: "" + maxLength: 0 + name: "" + namePrefix: "" + httpCaptureHeaders: + request: + - maxLength: 0 + name: "" + response: + - maxLength: 0 + name: "" + httpLogFormat: "" + status: Disabled certificateSecret: router-certs-custom clientTLS: allowedSubjectPatterns: [] @@ -53,6 +77,8 @@ ingress: mimeTypes: - "" httpEmptyRequestsPolicy: Respond + httpErrorCodePages: + name: "" listenAddress: [] logEmptyRequests: Log ports: @@ -69,7 +95,6 @@ ingress: minTLSVersion:"" intermediate: {} old: {} - type: "" tuningOptions: clientFinTimeout: 1s clientTimeout: 30s @@ -91,7 +116,108 @@ ingress: |Parameter |Description |`ingress` -|The `ingress` section of the {microshift-short} `config.yaml` file defines the configurable parameters for the implemented portions of the {OCP} Ingress Control Operator. All parameters in the rest of this table are subsections in the `ingress` section of the `config.yaml`. +|The `ingress` section of the {microshift-short} `config.yaml` file defines the configurable parameters for the implementation of the {OCP} `IngressController` API. All of the following parameters in this table are subsections in the `ingress` section of the {microshift-short} `config.yaml`. + +|`accessLogging` +|This `ingress` subsection describes how client requests are logged. If the `status` field is empty, access logging is disabled. When the status field is set to `Enabled`, access requests are logged as configured with the `accessLogging` parameters and the `accessLogging.destination.type` is automatically set to `Container`. + +* When enabled, access logging is part of the `openshift-router` logs. Logs from this pod are captured in the sos report procedure for {microshift-short}. +//Q: how come `status` is not first in this list? is it typical for this to be way at the bottom of the config section? it seems like the "on switch") + +|`accessLogging.destination` +|A destination for logs. The destination for logs can be a local sidecar container or remote. Default value is null. + +|`accessLogging.destination.type` +|The type of destination for logs. Valid values are `Container` or `Syslog`. + +* Setting this value to `Container` specifies that logs should go to a sidecar container. When the destination type is set to `Container`, a container is called `access-log` and is automatically created. Using container logs means that logs might be dropped if the rate of logs exceeds the container runtime capacity or the custom logging solution capacity. You must have a custom logging solution that reads logs from this sidecar. + +* Setting this value to `Syslog` specifies that logs are sent to a Syslog endpoint. You must configure a custom Syslog instance and specify an endpoint that can receive Syslog messages. You must have a custom Syslog instance. +//Q: should we supply instructions or links for these actions? + +|`accessLogging.destination.container` +|Describes parameters for the `Container` logging destination type. You must configure a custom logging solution that reads logs from this sidecar. + +|`accessLogging.destination.container.maxLength` +|Optional configuration. The default value is `1024` bytes. Message length must be at least `480` and not greater than `8192` bytes. + +|`accessLogging.destination.syslog` +|Describes parameters for the `Syslog` logging destination type. You must configure a custom Syslog instance with an endpoint that can receive Syslog messages. + +|`accessLogging.destination.syslog.address` +|Required configuration when the `Syslog` destination type is set. Valid value is the IP address of the syslog endpoint that receives log messages. +//Q: any conformance for values that we should know about? + +|`accessLogging.destination.syslog.facility` +|Optional configuration when the `Syslog` destination type is set. Specifies the syslog facility of log messages. If this field is empty, the facility is `local1`. Otherwise, the field must specify one of the following valid syslog facilities: `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`. + +|`accessLogging.destination.syslog.maxLength` +|Optional configuration when the `Syslog` destination type is set. The maximum length of the `Syslog` message. Message length must be at least `480` and not greater than `4096` bytes. If this field is empty, the maximum length is set to the default value of `1024` bytes. + +|`accessLogging.destination.syslog.port` +|Required configuration when the `Syslog` destination type is set. The UDP port number of the syslog endpoint that receives log messages. The default value is `0`. + +|`httpCaptureCookies` +|Specifies HTTP cookies that you want to capture in access logs. If the `httpCaptureCookies` field is empty, access logs do not capture the cookies. Default value is empty. Configuring `ingress.accessLogging.httpCaptureCookies` automatically enables ingress access logging. For any cookie that you want to capture, you must also set the `matchType` and `maxLength` parameters. + +* For example: ++ +[source,yam] +---- + httpCaptureCookies: + - matchType: Exact + maxLength: 128 + name: MYCOOKIE +---- + +|`httpCaptureCookies.matchType` +|Specifies whether the field name of the cookie exactly matches the capture cookie setting or is a prefix of the capture cookie setting. Valid values are `Exact` for an exact string match and `Prefix` for a string prefix match. + +* If the `Exact` setting is used, a name must also be specified in the `httpCaptureCookiesname` field. +* If the `Prefix` setting is used, a prefix must be specified in the `httpCaptureCookiesnamePrefix` field. For example, specifying matchType "Prefix" and namePrefix "foo" will capture a cookie named "foo" or "foobar" but not one named "bar". The first matching cookie is captured. + +|`httpCaptureCookies.maxLength` +|Specifies tha maximum length of the cookie that is logged, which includes the cookie name, cookie value, and +one-character delimiter. If the log entry exceeds this length, the value is truncated in the log message. The ingress controller might impose a separate bound on the total length of HTTP headers in a request. The minimum value is `1` byte, maximum value is `1024` bytes. + +|`httpCaptureCookies.name` +|Specifies the exact name used for a cookie name match as set in the `httpCaptureCookies.matchType` parameter. The value must be a valid HTTP cookie name as defined in link:https://datatracker.ietf.org/doc/html/rfc6265#section-4.1[RFC 6265 section 4.1]. The minimum length is `0` bytes and the maximum length is `1024` bytes. + +|`httpCaptureCookies.namePrefix` +|Specifies the prefix for a cookie name match as set in the `httpCaptureCookies.matchType` parameter. The value must be a valid HTTP cookie name as defined in link:https://datatracker.ietf.org/doc/html/rfc6265#section-4.1[RFC 6265 section 4.1]. The minimum length is `0` bytes and the maximum length is `1024` bytes. + +|`httpCaptureHeaders` +|Defines the HTTP headers that should be captured in the access logs. This field is a list and allows capturing request and response headers independently. If this field is empty, no headers are captured. This option only applies to 1) plain text HTTP connections and 2) to secure HTTP connections for which the ingress controller terminates encryption: for example, edge-terminated or reencrypt connections. Headers cannot be captured for TLS `passthrough` connections. Configuring `ingress.accessLogging.httpCaptureCookies` automatically enables ingress access logging. + +|`httpCaptureHeaders.request` +|Specifies which HTTP request headers to capture. If this field is empty, no request headers are captured. + +|`httpCaptureHeaders.request.maxLength` +|Specifies a maximum length for the header value. If a header value exceeds this length, the value is truncated in the log message. The minimum required value is `1` byte. The ingress controller might impose a separate bound on the total length of HTTP headers in a request. + +|`httpCaptureHeaders.request.name` +|Specifies a header name. The value must be a valid HTTP header name as defined in link:https://datatracker.ietf.org/doc/html/rfc2616#section-4.2[RFC 2616 section 4.2]. If you configure this value, you must specify `maxLength` and `name` values. + +|`httpCaptureHeaders.response` +|Specifies which HTTP response headers to capture. If this field is empty, no response headers are captured. + +|`httpCaptureHeaders.response.maxLength` +|Specifies a maximum length for the header value. If a header value exceeds this length, the value is truncated in the +log message. The ingress controller might impose a separate bound on the total length of HTTP headers in a request. + +|`httpCaptureHeaders.response.name` +|Specifies a header name. The value must be a valid HTTP header name as defined in link:https://datatracker.ietf.org/doc/html/rfc2616#section-4.2[RFC 2616 section 4.2]. + +|`httpLogFormat` +|Specifies the format of the log message for an HTTP request. If this field is empty, log messages use the default HTTP log format. For HAProxy default HTTP log format, see the link:https://cbonte.github.io/haproxy-dconv/2.0/configuration.html#8.2.3[HAProxy documentation]. + +|`status` +|Specifies whether access is logged or not. Valid values are `Enabled` and `Disabled`. Default value is `Disabled`. + +* Configuring either `ingress.accessLogging.httpCaptureHeaders` or +`ingress.accessLogging.httpCaptureCookies` automatically sets `ingress.accessLogging.status` to `Enabled`. +* When the `ingress.status` field is set to `Enabled`, the `accessLogging.destination.type` is automatically set to `Container` and the router logs all requests in the `access-log` container. +* If this value is set to `Disabled`, the router does not log any requests in the access log. |`certificateSecret` |A reference to a `kubernetes.io/tls` type of secret that contains the default certificate that is served by the {microshift-short} ingress controller. When routes do not specify their own certificate, the `certificateSecret` parameter is used. All secrets used must contain `tls.key` key file contents and `tls.crt` certificate file contents. @@ -102,7 +228,7 @@ ingress: |`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. You must set the `spec.clientTLS.clientCertificatePolicy` and `spec.clientTLS.ClientCA` parameters to use client TLS. -//Does this mean we can only use ASP if we are also using the other two? it is dependent? +//Q: Does this mean we can only use ASP if we are also using the other two? it is dependent? |`clientTLS.AllowedSubjectPatterns` |Optional subfield that specifies a list of regular expressions that are matched against the distinguished name on a valid client certificate to filter requests. Use this parameter to cause the ingress controller to reject certificates based on the distinguished name. The Perl Compatible Regular Expressions (PCRE) syntax is required. @@ -156,6 +282,13 @@ When configured, this field must contain a valid expression or the {microshift-s * Setting this value to `Log` indicates that an event should be logged. * Setting this value to `Ignore` sets the `dontlognull` option in the `HAproxy` configuration. +|`httpErrorCodePages` +|Describes custom error code pages. To use this setting, you must configure the `httpErrorCodePages.name` parameter. +//Q: so if I set up `name`, is this setting automatically turned on? + +|`httpErrorCodePages.name` +|Specifies custom error code pages. Only errors for `503` and `404` page codes can be customized. To customize error code pages, specify a `ConfigMap` name. The `ConfigMap` object must be in the `openshift-config` namespace and contain keys in the `error-page-.http` format where `` is an HTTP status code. Each value in the `ConfigMap` must be the full response, including HTTP headers. The default value of this parameter is null. + |`ports` |Defines default router ports. @@ -169,17 +302,17 @@ When configured, this field must contain a valid expression or the {microshift-s |Defines a policy for handling new route claims, such as allowing or denying claims across namespaces. |`routeAdmission.namespaceOwnership` -|Describes how hostname claims across namespaces should be handled. The default is `InterNamespaceAllowed`. The following are valid values: +|Describes how hostname claims across namespaces are handled. The default is `InterNamespaceAllowed`. The following are valid values: * `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. |`routeAdmission.wildcardPolicy` -|Controls how routes with configured wildcard policies are handled by the ingress controller. `WildcardsAllowed` and `WildcardsDisallowed` are valid values. Default value is `WildcardsDisallowed`. +|Controls how the ingress controller handles routes with configured wildcard policies. `WildcardsAllowed` and `WildcardsDisallowed` are valid values. Default value is `WildcardsDisallowed`. -* `WildcardPolicyAllowed` means that routes with any wildcard policy are admitted by the ingress controller. +* `WildcardPolicyAllowed` means that the ingress controller admits routes with any wildcard policy. -* `WildcardPolicyDisallowed` means that only routes with a wildcard policy of `None` are admitted by the ingress controller. +* `WildcardPolicyDisallowed` means that the ingress controller admits only routes with a wildcard policy of `None`. [IMPORTANT] ==== @@ -196,7 +329,7 @@ Changing the wildcard policy from `WildcardsAllowed` to `WildcardsDisallowed` ca [NOTE] ==== -Ciphers and the minimum TLS version of the configured security profile are reflected in the `TLSProfile` status. Profiles are intent-based and change over time when new ciphers are developed and existing ciphers are found to be insecure. The usable list can be reduced depending on which ciphers are available to a specific process. +The `TLSProfile` status shows the ciphers and the minimum TLS version of the configured security profile. Profiles are intent-based and change over time when new ciphers are developed and existing ciphers are found to be insecure. The usable list can be reduced depending on which ciphers are available to a specific process. ==== |`tlsSecurityProfile.custom` @@ -209,7 +342,7 @@ Ciphers and the minimum TLS version of the configured security profile are refle |Specifies the minimal version of the TLS protocol that is negotiated during the TLS handshake. For example, to use TLS versions 1.1, 1.2 and 1.3, set the value to `VersionTLS11`. The highest valid value for `minTLSVersion` is `VersionTLS12`. |`tlsSecurityProfile.intermediate` -|This TLS profile can be used for a majority of services. link:https://wiki.mozilla.org/Security/Server_Side_TLS#Intermediate_compatibility_.28recommended.29[Intermediate compatibility (recommended)]. +|You can use this TLS profile for a majority of services. link:https://wiki.mozilla.org/Security/Server_Side_TLS#Intermediate_compatibility_.28recommended.29[Intermediate compatibility (recommended)]. |`tlsSecurityProfile.old` |Used for backward compatibility. link:https://wiki.mozilla.org/Security/Server_Side_TLS#Old_backward_compatibility[Old backward compatibility]. @@ -221,10 +354,10 @@ Ciphers and the minimum TLS version of the configured security profile are refle |Specifies options for tuning the performance of ingress controller pods. |`tuningOptions.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`. +|Specifies how long the ingress controller holds a connection open while waiting for a client response before the server closes the connection. The default timeout is `1s`. |`tuningOptions.clientTimeout` -|Specifies how long a connection is held open while waiting for a client response. The default timeout is `30s`. +|Specifies how long the ingress controller holds a connection open while waiting for a client response. The default timeout is `30s`. |`tuningOptions.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. @@ -269,7 +402,7 @@ Setting this field is not recommended because `headerBufferMaxRewriteBytes` valu |Specifies how long a connection is held open while waiting for a server response. The default timeout is `30s`. |`tuningOptions.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. The `HAProxy` load balancer supports up to `64` threads. If this field is empty, the ingress controller uses the default value of `4` threads. +|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 using more system resources. The `HAProxy` load balancer supports up to `64` threads. If this field is empty, the ingress controller uses the default value of `4` threads. [IMPORTANT] ==== @@ -298,7 +431,7 @@ $ sudo systemctl restart microshift .Verification -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. +After making ingress configuration changes and restarting {microshift-short}, you can check the age of the router pod to ensure that changes are applied. * To check the status of the router pod, run the following command: +