OSDOCS-14942: corrections to ingress controller docs MicroShift

Author: ShaunaDiaz

modules/microshift-config-parameters-table.adoc

@@ -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`.
 

modules/microshift-ingress-controller-config.adoc

@@ -13,17 +13,25 @@ You can use detailed ingress control settings by updating the {microshift-short}
 
 * You installed the OpenShift CLI (`oc`).
 * 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 it, the `config.yaml` file takes precedence over built-in settings. The configuration 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.
 +
@@ -78,27 +86,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.
+|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.
+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 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.
+The in-use certificate, whether generated or user-specified, is 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.
-
-`clientTLS` has the required subfields, `spec.clientTLS.clientCertificatePolicy` and `spec.clientTLS.ClientCA`.
+|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. To use `clientTLS`, setting the subfields, `spec.clientTLS.clientCertificatePolicy` and `spec.clientTLS.ClientCA` is required.
+//again, does that mean we can only use ASP if we are also using the other two? it is dependent?
 
-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.ClientCertificatePolicy`
+|Accepts `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.
+|`clientTLS.ClientCA`
+|Specifies a required config map that is in the `openshift-ingress` namespace. The config map must contain a CA certificate bundle.
 
-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.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.
@@ -118,7 +128,7 @@ The `AllowedSubjectPatterns` is an optional value that specifies a list of regul
 * `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`
-|`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`. 
+|`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 `httpEmptyRequestsPolicy` type accepts either one of two values:
 
@@ -204,19 +214,19 @@ Setting this field is not recommended because increasing the number of `HAProxy`
 
 * `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. 
+* `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 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 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 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 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. 
+** 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.
 
-** 
+**
 
 |===