diff --git a/microshift_configuring/microshift-ingress-controller.adoc b/microshift_configuring/microshift-ingress-controller.adoc index 127b2717cefd..4e8dbe4cd965 100644 --- a/microshift_configuring/microshift-ingress-controller.adoc +++ b/microshift_configuring/microshift-ingress-controller.adoc @@ -12,7 +12,7 @@ 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-create-cert-secret.adoc[leveloffset=+2] include::modules/microshift-ingress-controller-tls-config.adoc[leveloffset=+2] @@ -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.openshift.com/container-platform/4.17/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] (OpenShift Container Platform documentation) diff --git a/modules/microshift-config-parameters-table.adoc b/modules/microshift-config-parameters-table.adoc index 0c90191b7cf0..b196bef63be1 100644 --- a/modules/microshift-config-parameters-table.adoc +++ b/modules/microshift-config-parameters-table.adoc @@ -9,7 +9,7 @@ The following table explains {microshift-short} configuration YAML parameters and valid values for each: .{microshift-short} `config.yaml` parameters -[cols="1,2,3a","15%,10%,75%",options="header"] +[cols="1,2,3a","15%,10%,50%",options="header"] |=== |Field|Type|Description @@ -91,12 +91,24 @@ If you do not set one of these values, a wildcard certificate is automatically g Any certificate in use is automatically integrated in the {microshift-short} OAuth server. |`ingress.clientTLS` -|`spec.clientTLS.clientCertificatePolicy`, `spec.clientTLS.ClientCA`, `AllowedSubjectPatterns` -|`clientTLS` authenticates client access to the cluster and services; as a result, mutual TLS authentication is enabled. If you do not set a value, the client TLS is not enabled. The `clientTLS` parameter has the required subfields, `spec.clientTLS.clientCertificatePolicy` and `spec.clientTLS.ClientCA`. +|`AllowedSubjectPatterns`, `spec.clientTLS.ClientCA`, `spec.clientTLS.clientCertificatePolicy` +|Authenticates client access to the cluster and services. Mutual TLS authentication is enabled when using these settings. If you do not set values for the `spec.clientTLS.clientCertificatePolicy` and `spec.clientTLS.ClientCA` required subfields, client TLS is not enabled. +//are the values in the config.yaml defaults? +//if I don't want to use client TLS, do I leave all three subfields empty? -* The `ClientCertificatePolicy` subfield accepts the following two values: `Required` or `Optional`. Note that the ingress controller only checks client certificates for edge-terminated and reencrypt TLS routes; the ingress controller cannot check certificates for cleartext 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. +|`ingress.clientTLS.AllowedSubjectPatterns` +|`list in PCRE syntax` +|Optional subfield which 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. If you configure this field, it must contain a valid expression or the {microshift-short} 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. +//can I use this field by itself? or only in combination with the other two? "If you do not set values for the `spec.clientTLS.clientCertificatePolicy` and `spec.clientTLS.ClientCA` required subfields, client TLS is not enabled." -* The `AllowedSubjectPatterns` is an optional subfield 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 the Perl Compatible Regular Expressions (PCRE) syntax. This field must contain a valid expression or the {microshift-short} 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 you do not specify a value, the ingress controller does not reject certificates based on the distinguished name. +|`ingress.clientTLS.ClientCA` +|`string` +|Required subfield that specifies a config map in the `openshift-ingress` namespace. The config map must contain a CA certificate bundle. +//is `ca-config-map` meant to be an example value? is this default in the microshift config.yaml, or is the default value in the microshift config yaml empty? + +|`ingress.clientTLS.ClientCertificatePolicy` +|`Required`, `Optional` +|Required subfield that creates a secure route using reencrypt TLS termination with a custom certificate. You must have a certificate/key pair in PEM-encoded files, where the certificate is valid for the route host. The ingress controller only checks client certificates for edge-terminated and reencrypt TLS routes. Certificates for plain text HTTP or passthrough TLS routes are not checked with this setting. |`ingress.defaultHTTPVersion` |`number` @@ -120,7 +132,7 @@ Any certificate in use is automatically integrated in the {microshift-short} OAu |`ingress.httpCompression.mimeTypes` |`array` or null -|`mimeTypes` is a list of MIME types to compress. When the list is empty, the ingress controller does not apply any compression. To define a list, use the format of the Content-Type definition in RFC 1341 that specifies the type and subtype of data in the body of a message and the native encoding of the data. For example, `Content-Type := type \"/\" subtype *[\";\" parameter]`. +|A list of MIME types to compress. When the list is empty, the ingress controller does not apply any compression. To define a list, use the format of the Content-Type definition in RFC 1341 that specifies the type and subtype of data in the body of a message and the native encoding of the data. For example, `Content-Type := type \"/\" subtype *[\";\" parameter]`. * The value of `Content-Type` can be one of the following types: application, audio, image, message, multipart, text, video, or a custom type preceded by `\"X-\"` and followed by a token. The token must be defined in one of the following ways: @@ -162,7 +174,7 @@ Not all MIME types benefit from compression, but `HAProxy` uses resources to try |`ingress.routeAdmissionPolicy` |`namespaceOwnership` or `wildcardPolicy` -|Defines a policy for handling new route claims, such as allowing or denying claims across namespaces. By default, allows routes to claim different paths of the same hostname across namespaces. +|Defines a policy for handling new route claims, such as allowing or denying claims across namespaces. By default, allows routes to claim different paths of the same hostname across namespaces. |`ingress.routeAdmissionPolicy.namespaceOwnership` |`Strict` or `InterNamespaceAllowed` @@ -189,7 +201,7 @@ Not all MIME types benefit from compression, but `HAProxy` uses resources to try |Specifies settings for ingress controllers TLS connections. If you do not set one, the default value is based on the `apiservers.config.openshift.io/cluster` resource. |`ingress.tlsSecurityProfile.type` -|`Old`, `Intermediate`, `Modern`, `Custom` +|`Old`, `Intermediate`, `Modern`, `Custom` |Specifies the profile type for the TLS Security. The default value is `Intermediate`. When using the `Old`, `Intermediate`, and `Modern` profile types, the effective profile configuration is subject to change between releases. For example, given a specification to use the `Intermediate` profile deployed on release `X.Y.Z`, an upgrade to release `X.Y.Z+1` might cause a new profile configuration to be applied to the ingress controller, resulting in a rollout. @@ -230,7 +242,7 @@ The minimum TLS version is `1.1`, and the maximum TLS version is `1.3`. |`ingress.tuningOptions.healthCheckInterval: ""` |`string` with pattern: `^(0\|([0-9]+(\\.[0-9]+)?(ns\|us\|µs\|μs\|ms\|s\|m\|h))+)$` -|The default `healthCheckInterval` value is `5s`, which is 5 seconds. This parameter value defines how long the router waits between two consecutive health checks on the router's configured backends. Currently the minimum allowed value is `1s` and the maximum allowed value is `2147483647ms`, which is 24.85 days. The range might change in future releases. +|The default `healthCheckInterval` value is `5s`, which is 5 seconds. This parameter value defines how long the router waits between two consecutive health checks on the router's configured backends. The minimum allowed value is `1s` and the maximum allowed value is `2147483647ms`, which is 24.85 days. * This value is applied globally as a default for all routes, but can be overridden per-route by the route annotation `router.openshift.io/haproxy.health.check.interval`. diff --git a/modules/microshift-ingress-controller-config.adoc b/modules/microshift-ingress-controller-config.adoc index 398a85844ad6..bcbfbb4006a8 100644 --- a/modules/microshift-ingress-controller-config.adoc +++ b/modules/microshift-ingress-controller-config.adoc @@ -11,21 +11,29 @@ You can use detailed ingress control settings by updating the {microshift-short} .Prerequisites -* You installed the OpenShift CLI (`oc`). +* You installed the {oc-first}. * You have root access to the cluster. -* Your cluster uses the OVN-Kubernetes network plugin. +* Your cluster uses the OVN-Kubernetes Container Network Interface (CNI) plugin. .Procedure . Apply ingress control settings in one of the two following ways: .. 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. -* 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. ++ +[IMPORTANT] +==== +After you create the `config.yaml`, the configuration file takes precedence over built-in settings. The `config.yaml` file is read every time the {microshift-short} service starts. +==== .. 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. ++ +[IMPORTANT] +==== +Configuration snippet YAMLs take precedence over both built-in settings and the `config.yaml` configuration file. +==== -. 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. +. Replace the default values in the `ingress` section of the {microshift-short} YAML with your valid values, or create a configuration snippet file with the sections you need. + .Ingress controller configuration fields with default values [source,yaml] @@ -35,28 +43,33 @@ apiServer: ingress: certificateSecret: router-certs-custom clientTLS: - allowedSubjectPatterns: ^/CN=example.com/ST=NC/C=US/O=Security/OU=OpenShift$ - clientCA: ca-config-map - clientCertificatePolicy: Required + allowedSubjectPatterns: [] + clientCA: + name: "" + clientCertificatePolicy: "" defaultHTTPVersion: 1 forwardedHeaderPolicy: Append httpCompression: mimeTypes: - "" httpEmptyRequestsPolicy: Respond + listenAddress: [] logEmptyRequests: Log - routeAdmission: + ports: + http: 80 + https: 443 + routeAdmissionPolicy: namespaceOwnership: InterNamespaceAllowed - wildcardPolicy: WildcardPolicyAllowed + wildcardPolicy: WildcardsDisallowed + status: Managed tlsSecurityProfile: - type: Custom + type: custom: - ciphers: - - ECDHE-ECDSA-CHACHA20-POLY1305 - - ECDHE-RSA-CHACHA20-POLY1305 - - ECDHE-RSA-AES128-GCM-SHA256 - - ECDHE-ECDSA-AES128-GCM-SHA256 - minTLSVersion: VersionTLS12 + ciphers:[] + minTLSVersion:"" + intermediate: {} + old: {} + type: "" tuningOptions: clientFinTimeout: 1s clientTimeout: 30s @@ -77,28 +90,36 @@ 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: +|`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`. -* `tls.crt`: certificate file contents -* `tls.key`: key file contents +|`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. -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. +* When the `certificateSecret` parameter is not set, a wildcard certificate is automatically generated and used. The wildcard certificate is valid for the ingress controller default `domain` and its `subdomains`. The generated certificate authority (CA) is automatically integrated with the truststore of the cluster. -The in-use certificate, whether generated or user-specified, is automatically integrated with {microshift-short} built-in OAuth server. +* In-use generated and user-specified certificates are automatically integrated with the {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. +|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? + +|`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. -`clientTLS` has the required subfields, `spec.clientTLS.clientCertificatePolicy` and `spec.clientTLS.ClientCA`. +[IMPORTANT] +==== +When configured, this field must contain a valid expression or the {microshift-short} 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. +==== -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. +|`clientTLS.ClientCA` +|Specifies a required config map that is in the `openshift-ingress` namespace. Required to enable client TLS. The config map must contain a certificate authority (CA) bundle. -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. +|`clientTLS.ClientCA.name` +|The `metadata.name` of the config map referenced in the `clientTLS.ClientCA` value. -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. +|`clientTLS.ClientCertificatePolicy` +|`Required` or `Optional` are valid values. Set to `Required` to enable client TLS. 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. |`defaultHTTPVersion` |Sets the HTTP version for the ingress controller. Default value is `1` for HTTP 1.1. @@ -107,116 +128,159 @@ The `AllowedSubjectPatterns` is an optional value that specifies a list of regul |`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. +* `Append` preserves any existing headers by specifying that the ingress controller appends them. 'Append` is the default value. +* `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. +* `Never` preserves any existing headers by specifying that the ingress controller never sets the headers. |`httpCompression` |Defines the policy for HTTP traffic compression. -* `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). +|`httpCompression.mimeTypes` +|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`, in the, `type/subtype; [;attribute=value]` format. +* Valid `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` -|`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`. +|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`. Empty requests typically come from load-balancer health probes or preconnects and can often be safely ignored. However, these requests can also be caused by network errors and port scans. Therefore, setting this field to `Ignore` can impede detection or diagnosis of network problems and detecting intrusion attempts. -The `httpEmptyRequestsPolicy` type accepts either one of two values: +* When the policy 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. -* `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. +* When the policy is set to `Ignore`, the `http-ignore-probes` parameter is added to the `HAproxy` process configuration. After this parameter is added, the ingress controller closes the connection without sending a response, then either logs the connection or incrementing metrics. +//Q: are the incrementing metrics in this case config'd by the admin, or are they automatic to our config? -* `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. +|`logEmptyRequests` +|Specifies connections for which no request is received and logged. `Log` and `Ignore` are valid values. Empty requests typically come from load-balancer health probes or preconnects and can often be safely ignored. However, these requests can also be caused by network errors and port scans. Therefore, setting this field to `Ignore` can impede detection or diagnosis of network problems and detecting intrusion attempts. The default value is `Log`. -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. +* 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. -|`logEmptyRequests` -|`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`. +|`ports` +|Defines default router ports. -The `LoggingPolicy` type accepts either one of two values: +|`ports.http` +|Default router http port. Must be in range 1-65535. Default value is `80`. -* `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. +|`ports.https` +|Default router https port. Must be in range 1-65535. Default value is `443`. |`routeAdmission` -|`routeAdmission` defines a policy for handling new route claims, such as allowing or denying claims across namespaces. +|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`. +|`routeAdmission.namespaceOwnership` +|Describes how hostname claims across namespaces should be 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. +* `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. +|`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`. -* `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. +* `WildcardPolicyAllowed` means that routes with any wildcard policy are admitted by the ingress controller. + +* `WildcardPolicyDisallowed` means that only routes with a wildcard policy of `None` are admitted by the ingress controller. + +[IMPORTANT] +==== +Changing the wildcard policy 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. +==== -If not set, the default value is based on the `apiservers.config.openshift.io/cluster` resource. +|`status` +|Default router status. `Managed` or `Removed` are valid values. -`Intermediate` is the default setting. +|`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. The TLS `1.0` version of an `Old` or `Custom` profile is automatically converted to `1.1` by the ingress controller. `Intermediate` is the default setting. -The minimum TLS version for ingress controllers is `1.1`. The maximum TLS version is `1.3`. +* 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. +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. ==== -[IMPORTANT] -==== -The TLS `1.0` version of an `Old` or `Custom` profile is automatically converted to `1.1` by the ingress controller. -==== +|`tlsSecurityProfile.custom` +|User-defined TLS security profile. If you configure this parameter and related parameters, use extreme caution. + +|`tlsSecurityProfile.custom.ciphers` +|Specifies the cipher algorithms that are negotiated during the TLS handshake. Operators might remove entries their operands do not support. + +|`tlsSecurityProfile.custom.minTLSVersion` +|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)]. + +|`tlsSecurityProfile.old` +|Used for backward compatibility. link:https://wiki.mozilla.org/Security/Server_Side_TLS#Old_backward_compatibility[Old backward compatibility]. + +|`tlsSecurityProfile.type` +|Valid values are `Intermediate`, `Old`, or `Custom`. The `Modern` value is not supported. |`tuningOptions` -|`tuningOptions` specifies options for tuning the performance of ingress controller pods. +|Specifies options for tuning the performance of ingress controller pods. -* `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`. +|`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`. -* `clientTimeout` specifies how long a connection is held open while waiting for a client response. The default timeout is `30s`. +|`tuningOptions.clientTimeout` +|Specifies how long a connection is held 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. -* `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. ==== -* `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. -+ +|`tuningOptions.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` 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. ==== -* `healthCheckInterval` specifies how long the router waits between health checks. The default is `5s`. +|`tuningOptions.healthCheckInterval` +|Specifies how long the router waits between health checks, set in seconds. The default is `5s`. -* `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`. +|`tuningOptions.maxConnections` +|Specifies the maximum number of simultaneous connections that can be established for each `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. -* `serverTimeout` specifies how long a connection is held open while waiting for a server response. The default timeout is `30s`. +* If this field is left empty or has the value `0`, the ingress controller uses the default value of `50000`. -* `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. Reducing the number of threads can cause the ingress controller to perform poorly. -==== +* If the field has the value of `-1`, then the `HAProxy` process 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`. -* `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`. +* If the field has a value that is greater than the current operating system limit, the `HAProxy` processes do not start. -* `tunnelTimeout` specifies how long a tunnel connection, including websockets, remains open while the tunnel is idle. The default timeout is `1h`. +* 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. -* `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 you have nodes with different `ulimits` configured, and you choose a discrete value, you can use the value of `-1` for this field so that the maximum number of connections is calculated at runtime. -** 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. +* You can monitor memory usage for router containers with the `container_memory_working_set_bytes{container="router",namespace="openshift-ingress"}` metric. -** 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`. +* You can monitor memory usage of individual `HAProxy` processes in router containers with the `container_memory_working_set_bytes{container="router",namespace="openshift-ingress"}/container_processes{container="router",namespace="openshift-ingress"}` metric. -** If the field has a value that is greater than the current operating system limit, the `HAProxy` processes do not start. +|`tuningOptions.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`. -** 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. +|`tuningOptions.serverTimeout` +|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. + +[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. Reducing the number of threads can cause the ingress controller to perform poorly. +==== -** 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. +|`tuningOptions.tlsInspectDelay` +|Specifies how long the router can hold data to find a matching route. Setting this value too low 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`. -** +|`tuningOptions.tunnelTimeout` +|Specifies how long a tunnel connection, including websockets, remains open while the tunnel is idle. The default timeout is `1h`. |=== diff --git a/modules/microshift-ingress-controller-create-cert-secret.adoc b/modules/microshift-ingress-controller-create-cert-secret.adoc new file mode 100644 index 000000000000..c3c7aa4a0fc4 --- /dev/null +++ b/modules/microshift-ingress-controller-create-cert-secret.adoc @@ -0,0 +1,55 @@ + +// Module included in the following assemblies: +// +// * microshift_configuring/microshift-ingress-controller.adoc + +:_mod-docs-content-type: PROCEDURE +[id="microshift-ingress-controller-create-cert-secret_{context}"] += Creating a secret for the ingress controller certificateSecret + +Use this procedure to create a secret that is referenced by the `certificateSecret` parameter value in the {microshift-short} configuration file. This secret contains the default certificate served by the ingress controller. + +[NOTE] +==== +Any in-use certificates is automatically integrated with the {microshift-short} built-in OAuth server. +==== + +.Prerequisites + +* You have root access to {microshift-short}. +* You installed the {oc-first}. +* Your private key is not encrypted or you have decrypted it for importing into {microshift-short}. + +.Procedure + +. Create a secret that contains the wildcard certificate chain and key: ++ +[source,terminal] +---- +$ oc create secret tls <1> + --cert= <2> + --key= <3> + -n openshift-ingress +---- +<1> `` is the name of the secret that contains the certificate chain and private key. +<2> `` is the path to the certificate chain on your local file system. +<3> `` is the path to the private key associated with this certificate. ++ +[IMPORTANT] +==== +The certificate must include the `subjectAltName` extension showing `*.apps..`. +==== + +. Update the `certificateSecret` parameter value in the {microshift-short} configuration YAML with the newly created secret. + +. Complete any other configurations you require, then start or restart {microshift-short} by running one the following commands: ++ +[source,terminal] +---- +$ sudo systemctl start microshift +---- ++ +[source,terminal] +---- +$ sudo systemctl restart microshift +---- \ No newline at end of file diff --git a/modules/microshift-ingress-controller-create-certificate-secret.adoc b/modules/microshift-ingress-controller-create-certificate-secret.adoc deleted file mode 100644 index 462ac211b43e..000000000000 --- a/modules/microshift-ingress-controller-create-certificate-secret.adoc +++ /dev/null @@ -1,36 +0,0 @@ - -// 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..`. - -.Procedure - -. Create a secret that contains the wildcard certificate chain and key: -+ -[source,terminal] ----- -$ oc create secret tls <1> - --cert= <2> - --key= <3> - -n openshift-ingress ----- -<1> `` is the name of the secret that contains the certificate chain and private key. -<2> `` is the path to the certificate chain on your local file system. -<3> `` 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. \ No newline at end of file diff --git a/modules/microshift-ingress-controller-tls-config.adoc b/modules/microshift-ingress-controller-tls-config.adoc index 5e1636df9cbe..9bc00bfc5495 100644 --- a/modules/microshift-ingress-controller-tls-config.adoc +++ b/modules/microshift-ingress-controller-tls-config.adoc @@ -38,6 +38,16 @@ spec: * `custom:` <3> For the `custom` type, specify a list of TLS ciphers and minimum accepted TLS version. + +[WARNING] +==== +If you choose a `custom` TLS configuration, use extreme caution. Using self-signed TLS certificates can introduce security risks. +==== ++ . Save the file to apply the changes. + -. Restart the {microshift-short} service. \ No newline at end of file +. Restart {microshift-short} by running the following command: ++ +[source,terminal] +---- +$ sudo systemctl restart microshift +----