Merge pull request #89670 from ShaunaDiaz/OSDOCS-11187

OSDOCS-11187: adds TLS config procedure MicroShift

Author: ShaunaDiaz

_topic_maps/_topic_map_ms.yml

@@ -122,16 +122,21 @@ Topics:
   File: microshift-nw-ipv6-config
 - Name: Using ingress control for a MicroShift cluster
   File: microshift-ingress-controller
-- Name: Cluster access with kubeconfig
-  File: microshift-cluster-access-kubeconfig
-- Name: Using custom certificate authorities
-  File: microshift-custom-ca
-- Name: Checking the status of Greenboot health checks
-  File: microshift-greenboot-checking-status
-- Name: Configuring audit logging policies
-  File: microshift-audit-logs-config
 - Name: Disabling LVMS CSI provider and CSI snapshot
   File: microshift-disable-lvms-csi-provider-csi-snapshot
+- Name: Checking the status of Greenboot health checks
+  File: microshift-greenboot-checking-status
+- Name: Cluster access with kubeconfig
+  File: microshift-cluster-access-kubeconfig
+- Name: Configuring MicroShift authentication and security
+  Dir: microshift_auth_security
+  Topics:
+  - Name: Using custom certificate authorities
+    File: microshift-custom-ca
+  - Name: Configuring TLS security profiles
+    File: microshift-tls-config
+  - Name: Configuring audit logging policies
+    File: microshift-audit-logs-config
 - Name: Configuring low latency
   Dir: microshift_low_latency
   Topics:

microshift_configuring/microshift_auth_security/_attributes

@@ -0,0 +1 @@
+../_attributes/

microshift_configuring/microshift_auth_security/images

@@ -0,0 +1 @@
+../images/

microshift_configuring/microshift-audit-logs-config.adoc renamed to microshift_configuring/microshift_auth_security/microshift-audit-logs-config.adoc

@@ -0,0 +1,27 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="microshift-tls-config"]
+= Configuring TLS security profiles
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-tls-config
+
+toc::[]
+
+Use transport layer security (TLS) protocols to help prevent known insecure protocols, ciphers, or algorithms from accessing the applications you run on {microshift-short}.
+
+include::modules/microshift-tls-config-con.adoc[leveloffset=+1]
+
+include::modules/microshift-tls-config-proc.adoc[leveloffset=+1]
+
+include::modules/microshift-tls-default-cipher-suites.adoc[leveloffset=+2]
+
+[id="additional-resources_microshift-tls-config_{context}"]
+[role="_additional-resources"]
+== Additional resources
+
+* xref:../../microshift_configuring/microshift-using-config-yaml.adoc#microshift-config-snippets_microshift-configuring[Using configuration snippets].
+
+* To secure pods using security content constraints (SCC), see xref:../../microshift_running_apps/microshift-authentication.adoc#authentication-microshift[Pod security authentication and authorization].
+
+* xref:../../microshift_configuring/microshift-cluster-access-kubeconfig.adoc#microshift-kubeconfig[Cluster access with kubeconfig].
+
+* xref:../microshift_auth_security/microshift-custom-ca.adoc#microshift-custom-ca[Configuring custom certificate authorities].

microshift_configuring/microshift-custom-ca.adoc renamed to microshift_configuring/microshift_auth_security/microshift-custom-ca.adoc

@@ -0,0 +1 @@
+../modules/

microshift_configuring/microshift_auth_security/microshift-tls-config.adoc

@@ -0,0 +1 @@
+../snippets/

microshift_configuring/microshift_auth_security/modules

@@ -0,0 +1,22 @@
+// Module included in the following assemblies:
+//
+// * microshift_configurig/microshift_tls-config.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="microshift-tls-config-con_{context}"]
+= Using TLS with {microshift-short}
+
+Transport layer security (TLS) profiles provide a way for servers to regulate which ciphers a client can use when connecting to the server. Using TLS helps to ensure that {microshift-short} applications use cryptographic libraries that do not allow known insecure protocols, ciphers, or algorithms. You can use either the TLS 1.2 or TLS 1.3 security profiles with {microshift-short}.
+
+{microshift-short} API server cipher suites apply automatically to the following internal control plane components:
+
+* API server
+* Kubelet
+* Kube controller manager
+* Kube scheduler
+* etcd
+* Route controller manager
+
+The API server uses the configured minimum TLS version and the associated cipher suites. If you leave the cipher suites parameter empty, the defaults for the configured minimum version are used automatically.
+
+include::snippets/microshift-tls-ciphers.adoc[leveloffset=+2]

microshift_configuring/microshift_auth_security/snippets

@@ -0,0 +1,59 @@
+// Module included in the following assemblies:
+//
+// * microshift_configurig/microshift_tls-config.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="microshift-tls-config-proc_{context}"]
+= Configuring TLS for {microshift-short}
+
+You can choose to use either the TLS 1.2 or TLS 1.3 security profiles with {microshift-short} for system hardening.
+
+.Prerequisites
+
+* You have access to the cluster as a root user.
+* {microshift-short} has either not started for the first time, or is stopped.
+* The OpenShift CLI (`oc`) is installed.
+* The certificate authority has issued the custom certificates (CAs).
+
+.Procedure
+
+. Make a copy of the provided `config.yaml.default` file in the `/etc/microshift/` directory, renaming it `config.yaml`.
+
+. Keep the new {microshift-short} `config.yaml` in the `/etc/microshift/` directory. Your `config.yaml` file is read every time the {microshift-short} service starts.
++
+[NOTE]
+====
+After you create it, the `config.yaml` file takes precedence over built-in settings.
+====
+
+. Optional: Use a configuration snippet if you are using an existing {microshift-short} YAML. See "Using configuration snippets" in the Additional resources section for more information.
+
+. Replace the default values in the `tls` section of the {microshift-short} YAML with your valid values.
++
+.Example TLS 1.2 configuration
+[source,yaml]
+----
+apiServer:
+# ...
+  tls:
+    cipherSuites: # <1>
+    - <cipher_suite_1> # <2>
+    - ...
+    minVersion: VersionTLS12 # <3>
+# ...
+----
+<1> Defaults to the suites of the configured `minVersion`. If `minVersion` is not configured, the default value is TLS 1.2.
+<2> Specify the cipher suites you want to use from the list of supported cipher suites. If you do not configure this list, all of the supported cipher suites are used. All clients connecting to the API server must support the configured cipher suites or the connections fail during the TLS handshake phase. Be sure to add the CA certificate bundle to the list of CA certificates that the TLS client or server trusts.
+<3> Specify `VersionTLS12` or `VersionTLS13`.
++
+[IMPORTANT]
+====
+When you choose TLS 1.3 as the minimum TLS version, only the default {microshift-short} cipher suites can be used. Additional cipher suites are not configurable. If other cipher suites to use with TLS 1.3 are configured, those suites are ignored and overwritten by the {microshift-short} defaults.
+====
+
+. Complete any other additional configurations that you require, then restart {microshift-short} by running the following command:
++
+[source,terminal]
+----
+$ sudo systemctl restart microshift
+----