Merge pull request #92896 from tedaveryredhat/OSDOCS-14402

OSDOCS-14402:YAML parameter additions

Author: jab-rh

microshift_configuring/microshift-using-config-yaml.adoc

@@ -29,3 +29,5 @@ include::modules/microshift-config-nodeport-limits.adoc[leveloffset=+2]
 == Additional resources
 
 * xref:../../microshift-greenboot-checking-status.adoc#microshift-greenboot-checking-status[Checking Greenboot status]
+
+* xref:../microshift_configuring/microshift-ingress-controller.adoc#microshift-ingress-controller[Using ingress control for a {microshift-short} cluster]

modules/microshift-config-parameters-table.adoc

@@ -63,11 +63,11 @@ The following table explains {microshift-short} configuration YAML parameters an
 
 |`tls.minVersion`
 |`VersionTLS12` or `VersionTLS13`
-|Specifies the minimum version of TLS to serve from the API serve. Default is value is `VersionTLS12`. TLS 1.3 ciphers are preset and not configurable.
+|Specifies the minimum version of TLS to serve from the API server. The default value is `VersionTLS12`.
 
 |`debugging.logLevel`
 |`Normal`, `Debug`, `Trace`, or `TraceAll`
-|Log verbosity. Default value is `Normal`.
+|Log verbosity. The default value is `Normal`.
 
 |`dns.baseDomain`
 |`valid domain`
@@ -77,25 +77,46 @@ The following table explains {microshift-short} configuration YAML parameters an
 |`number`
 |By default, `etcd` uses as much memory as needed to handle the load on the system. However, in memory constrained systems, it might be preferred or necessary to limit the amount of memory `etcd` can to use at a given time.
 
+|`ingress.certificateSecret`
+|`string`
+|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 you do not set one of these values, a wildcard certificate is automatically generated and used. The certificate is valid for the ingress controller `domain` and `subdomains` fields, and the generated CA for the certificate is automatically integrated with the truststore for the cluster.
+
+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`.
+
+* 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.
+
+* 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.defaultHTTPVersion`
 |`number`
-|Determines the default HTTP version to be used for ingress. Default value is `1`, which is the HTTP/1.1 protocol.
+|Determines the default HTTP version to be used for ingress. The default value is `1`, which is the HTTP/1.1 protocol.
 
 |`ingress.forwardedHeaderPolicy`
 |`Append`, `Replace`, `IfNone`, `Never`
-|Specifies when and how the ingress router sets the `Forwarded`, `X-Forwarded-For`, `X-Forwarded-Host`, `X-Forwarded-Port`, `X-Forwarded-Proto`, and `X-Forwarded-Proto-Version` HTTP headers.
+|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 default value is `Append`.
 
-* `Append` specifies that the ingress router appends existing headers. `Append` is the default value.
+* `Append` specifies that the ingress controller appends existing headers.
 
-* `Replace` specifies that the ingress router sets the headers and replaces any existing `Forwarded` or `X-Forwarded-*` headers.
+* `Replace` specifies that the ingress controller sets the headers and replaces any existing `Forwarded` or `X-Forwarded-*` headers.
 
-* `IfNone` specifies that the ingress router sets headers if they are not already set.
+* `IfNone` specifies that the ingress controller sets headers if they are not already set.
 
-* `Never` specifies that ingress router never sets the headers, preserving any existing headers.
+* `Never` specifies that ingress controller never sets the headers, preserving any existing headers.
 
 |`ingress.httpCompression`
 |`object`
-|`httpCompression` defines a policy for HTTP traffic compression. There is no HTTP compression by default.
+|Defines a policy for HTTP traffic compression. There is no HTTP compression by default.
 
 |`ingress.httpCompression.mimeTypes`
 |`array` or null
@@ -117,7 +138,7 @@ Not all MIME types benefit from compression, but `HAProxy` uses resources to try
 
 |`ingress.httpEmptyRequestsPolicy`
 |`Respond` or `Ignore`
-|The default value is `Respond`. Describes how HTTP connections should be handled if the connection times out before a request is received. These connections typically come from the health probes of a load balancer service health or a web browser's speculative connections, such as a `preconnect`.
+|The default value is `Respond`. Describes how HTTP connections should be handled if the connection times out before a request is received. These connections typically come from the health probes of a load balancer service or a web browser's speculative connections, such as a `preconnect`.
 
 * 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.
 
@@ -129,23 +150,59 @@ Not all MIME types benefit from compression, but `HAProxy` uses resources to try
 
 |`ingress.logEmptyRequests`
 |`Log` or `Ignore`
-|Default value is `Log`. Specifies how connections on which empty requests are received are logged. These connections typically come from the health probes of a load balancer service health or a web browser's speculative connections, such as a `preconnect`. Logging typical requests might be undesirable, but requests can also be caused by network errors or port scans, in which case logging can be useful for diagnosing errors and detecting intrusion attempts.
+|The default value is `Log`. Specifies how connections on which empty requests are received are logged. These connections typically come from the health probes of a load balancer service health or a web browser's speculative connections, such as a `preconnect`. Logging typical requests might be undesirable, but requests can also be caused by network errors or port scans, in which case logging can be useful for diagnosing errors and detecting intrusion attempts.
 
 |`ingress.ports.http`
 |`80`
-|Default port shown. Configurable. Valid value is a single, unique port in the `1-65535` range. The values of the `ports.http` and `ports.https` fields cannot be the same.
+|The default port shown. Configurable. Valid value is a single, unique port in the `1-65535` range. The values of the `ports.http` and `ports.https` fields cannot be the same.
 
 |`ingress.ports.https`
 |`443`
-|Default port shown. Configurable. Valid value is a single, unique port in the `1-65535` range. The values of the `ports.http` and `ports.https` fields cannot be the same.
+|The default port shown. Configurable. Valid value is a single, unique port in the `1-65535` range. The values of the `ports.http` and `ports.https` fields cannot be the same.
+
+|`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. 
 
 |`ingress.routeAdmissionPolicy.namespaceOwnership`
 |`Strict` or `InterNamespaceAllowed`
-|Describes how hostname claims across namespaces are handled. By default, allows routes to claim different paths of the same hostname across namespaces. Specifying `Strict` prevents routes in different namespaces from claiming the same hostname. If the value is deleted in a customized {microshift-short} `config.yaml`, the `InterNamespaceAllowed` value is automatically set.
+|Describes how hostname claims across namespaces should be handled. The default value is `InterNamespaceAllowed`. Specifying `Strict` prevents routes in different namespaces from claiming the same hostname. If the value is deleted in a customized {microshift-short} `config.yaml` file, the `InterNamespaceAllowed` value is automatically set.
+
+* `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.
+
+|`ingress.routeAdmissionPolicy.wildcardPolicy`
+|`WildcardsAllowed` or `WildcardsDisallowed`
+|Describes how routes with wildcard policies are handled by the ingress controller.
+
+* `WildcardsAllowed`: Indicates routes with any wildcard policy are admitted 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 controller. `WildcardsDisallowed` is the default setting.
 
 |`ingress.status`
 |`Managed` or `Removed`
-|Router status. Default is `Managed`.
+|Router status. The default is `Managed`.
+
+|`ingress.tlsSecurityProfile`
+|`object`
+|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` 
+|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.
+
+|`ingress.tlsSecurityProfile.minTLSVersion`
+|`number`
+|Specifies the TLS version for ingress controllers.
+
+The minimum TLS version is `1.1`, and the maximum TLS version is `1.3`.
+
+* Ciphers and the minimum TLS version of the configured security profile are reflected in the `TLSProfile` status.
+
+* The ingress controller converts the TLS `1.0` of an `Old` or `Custom` profile to `1.1`.
 
 |`ingress.tuningOptions`
 |Objects
@@ -161,13 +218,13 @@ Not all MIME types benefit from compression, but `HAProxy` uses resources to try
 
 |`ingress.tuningOptions.headerBufferBytes`
 |An `integer` with the `format` of `int32`; `16384` is the minimum value when HTTP/2 is enabled.
-|Describes how much memory in bytes must be reserved for `IngressController` connection sessions. Default value is `32768` in bytes.
+|Describes how much memory in bytes must be reserved for `IngressController` connection sessions. The default value is `32768` in bytes.
 
 * Setting this field is generally not recommended because `headerBufferBytes` values that are too small can break the `IngressController` and `headerBufferBytes` values that are too large can cause the `IngressController` to use significantly more memory than necessary.
 
 |`ingress.tuningOptions.headerBufferMaxRewriteBytes`
 |`integer`, formatted `int32`; `4096` is the minimum value
-|Describes how much memory in bytes must be reserved from `headerBufferBytes` for HTTP header rewriting and appending for `IngressController` connection sessions. Default value is `8192` bytes. Incoming HTTP requests are limited to the `headerBufferBytes` bytes minus the `headerBufferMaxRewriteBytes` bytes, meaning that the value of `headerBufferBytes` must be greater than the value of `headerBufferMaxRewriteBytes`.
+|Describes how much memory in bytes must be reserved from `headerBufferBytes` for HTTP header rewriting and appending for `IngressController` connection sessions. The default value is `8192` bytes. Incoming HTTP requests are limited to the `headerBufferBytes` bytes minus the `headerBufferMaxRewriteBytes` bytes, meaning that the value of `headerBufferBytes` must be greater than the value of `headerBufferMaxRewriteBytes`.
 
 * Setting this field is generally not recommended because `headerBufferMaxRewriteBytes` values that are too small can break the `IngressController` and `headerBufferMaxRewriteBytes` values that are too large can cause the `IngressController` to use significantly more memory than necessary.
 
@@ -187,7 +244,7 @@ Not all MIME types benefit from compression, but `HAProxy` uses resources to try
 
 |`ingress.tuningOptions.maxConnections`
 |`integer`, valid values are: `empty`, `0`, `-1`, and the range `2000-2000000`
-|Default value is `0`. defines 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 being consumed.
+|The default value is `0`. defines 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 being consumed.
 
 * If this field is empty or `0`, the `IngressController` uses the default value of `50000`, but the default is subject to change in future releases.
 
@@ -235,31 +292,31 @@ container_memory_working_set_bytes{container=`router`,namespace=`openshift-ingre
 
 |`kubelet`
 |See the {microshift-short} low-latency instructions
-|Parameter for passthrough configuration of the kubelet node agent. Used for low-latency configuration. Default value is null.
+|Parameter for passthrough configuration of the kubelet node agent. Used for low-latency configuration. The default value is null.
 
 |`manifests`
 |`list of paths`
-|The locations on the file system to scan for `kustomization` files to use to load manifests. Set to a list of paths to scan only those paths. Set to an empty list to disable loading manifests. The entries in the list can be glob patterns to match multiple subdirectories. Default values are `/usr/lib/microshift/manifests`, `/usr/lib/microshift/manifests.d/`, `/etc/microshift/manifests`, and `/etc/microshift/manifests.d/`.
+|The locations on the file system to scan for `kustomization` files to use to load manifests. Set to a list of paths to scan only those paths. Set to an empty list to disable loading manifests. The entries in the list can be glob patterns to match multiple subdirectories. The default values are `/usr/lib/microshift/manifests`, `/usr/lib/microshift/manifests.d/`, `/etc/microshift/manifests`, and `/etc/microshift/manifests.d/`.
 
 |`network.clusterNetwork`
 |IP address block
-|A block of IP addresses from which pod IP addresses are allocated. IPv4 is the default network. Dual-stack entries are supported. The first entry in this field is immutable after {microshift-short} starts. Default range is `10.42.0.0/16`.
+|A block of IP addresses from which pod IP addresses are allocated. IPv4 is the default network. Dual-stack entries are supported. The first entry in this field is immutable after {microshift-short} starts. The default range is `10.42.0.0/16`.
 
 |`network.cniPlugin`
 |String
 |Deploys the Open Virtual Networking - Kubernetes (OVN-K) network plugin as the default container network interface (CNI) when empty or set to `"ovnk"`. Supported values are empty, `""` or `"ovnk"`. Setting to `"none"` removes the CNI and is not recommended. Only OVN-K is managed by {microshift-short}.
 
 |`network.multus.status`
 |`string`
-|Controls the deployment of the Multus Container Network Interface (CNI). Default status is `Disabled`. If you set the value to `Enabled`, the Multus CNI cannot be deleted.
+|Controls the deployment of the Multus Container Network Interface (CNI). The default status is `Disabled`. If you set the value to `Enabled`, the Multus CNI cannot be deleted.
 
 |`network.serviceNetwork`
 |IP address block
-|A block of virtual IP addresses for Kubernetes services. IP address pool for services. IPv4 is the default. Dual-stack entries are supported. The first entry in this field is immutable after {microshift-short} starts. Default range is `10.43.0.0/16`.
+|A block of virtual IP addresses for Kubernetes services. IP address pool for services. IPv4 is the default. Dual-stack entries are supported. The first entry in this field is immutable after {microshift-short} starts. The default range is `10.43.0.0/16`.
 
 |`network.serviceNodePortRange`
 |`range`
-|The port range allowed for Kubernetes services of type `NodePort`. If not specified, the default range of 30000-32767 is used. Services without a `NodePort` specified are automatically allocated one from this range. This parameter can be updated after {microshift-short} starts.
+|The port range allowed for Kubernetes services of type `NodePort`. If you do not specify the range, the default range of `30000-32767` is used. Services without a `NodePort` specified are automatically allocated one from this range. This parameter can be updated after {microshift-short} starts.
 
 |`node.hostnameOverride`
 |`string`
@@ -271,19 +328,19 @@ container_memory_working_set_bytes{container=`router`,namespace=`openshift-ingre
 
 |`nodeIPv6`
 |IPv6 address
-|The IPv6 address for the node for dual-stack configurations. Cannot be configured in single stack for either IPv4 or IPv6. Default is an empty value or null.
+|The IPv6 address for the node for dual-stack configurations. Cannot be configured in single stack for either IPv4 or IPv6. The default is an empty value or null.
 
 |`storage.driver`
 |`none` or `lvms`
-|Default value is empty. An empty value or null field defaults to LVMS deployment.
+|The default value is empty. An empty value or null field defaults to LVMS deployment.
 
 |`storage.optionalCsiComponents`
 |`array`
-|Default value is null or an empty array. A null or empty array defaults to deploying `snapshot-controller`. Expected values are `csi-snapshot-controller` or `none`. A value of `none` is mutually exclusive with all other values.
+|The default value is null or an empty array. A null or empty array defaults to deploying `snapshot-controller`. Expected values are `csi-snapshot-controller` or `none`. A value of `none` is mutually exclusive with all other values.
 
 |`telemetry.endpoint`
 |`https://infogw.api.openshift.com`
-|The endpoint where telemetry data is sent. No user or private data is included in the metrics reported. Default value is `https://infogw.api.openshift.com`.
+|The endpoint where telemetry data is sent. No user or private data is included in the metrics reported. The default value is `https://infogw.api.openshift.com`.
 
 |`telemetry.status`
 |`Enabled`