From 9ee797e0882ba0e35eb6a52ba75f2f44e3f56f6f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CShauna=20Diaz=E2=80=9D?= Date: Tue, 4 Nov 2025 07:32:50 -0500 Subject: [PATCH] OSDOCS-15648: mods and updates responsive restarts MicroShift --- _topic_maps/_topic_map_ms.yml | 2 +- .../microshift-responsive-restarts-cas.adoc | 27 +++++++++++ .../microshift-things-to-know.adoc | 24 ---------- modules/microshift-certificate-lifetime.adoc | 48 +++---------------- modules/microshift-certificate-rotation.adoc | 17 +++++++ .../microshift-ip-address-clock-changes.adoc | 14 ++++++ ...oshift-long-term-certificate-rotation.adoc | 21 ++++++++ ...shift-short-term-certificate-rotation.adoc | 21 ++++++++ 8 files changed, 107 insertions(+), 67 deletions(-) create mode 100644 microshift_troubleshooting/microshift-responsive-restarts-cas.adoc delete mode 100644 microshift_troubleshooting/microshift-things-to-know.adoc create mode 100644 modules/microshift-certificate-rotation.adoc create mode 100644 modules/microshift-ip-address-clock-changes.adoc create mode 100644 modules/microshift-long-term-certificate-rotation.adoc create mode 100644 modules/microshift-short-term-certificate-rotation.adoc diff --git a/_topic_maps/_topic_map_ms.yml b/_topic_maps/_topic_map_ms.yml index f3ad58660d..14a6c90a72 100644 --- a/_topic_maps/_topic_map_ms.yml +++ b/_topic_maps/_topic_map_ms.yml @@ -296,7 +296,7 @@ Topics: - Name: Troubleshoot etcd File: microshift-etcd-troubleshoot - Name: Additional information - File: microshift-things-to-know + File: microshift-responsive-restarts-cas - Name: Data cleanup File: microshift-cleanup-data --- diff --git a/microshift_troubleshooting/microshift-responsive-restarts-cas.adoc b/microshift_troubleshooting/microshift-responsive-restarts-cas.adoc new file mode 100644 index 0000000000..7a6129c6f2 --- /dev/null +++ b/microshift_troubleshooting/microshift-responsive-restarts-cas.adoc @@ -0,0 +1,27 @@ +:_mod-docs-content-type: ASSEMBLY +[id="microshift-responsive-restarts-cas"] += Responsive restarts and security certificates + +include::_attributes/attributes-microshift.adoc[] +:context: microshift-responsive-restarts-cas + +toc::[] + +[role="_abstract"] +{microshift-short} responds to system configuration changes and restarts after alterations are detected, including IP address changes, clock adjustments, and security certificate age. + +include::modules/microshift-ip-address-clock-changes.adoc[leveloffset=+1] + +include::modules/microshift-certificate-lifetime.adoc[leveloffset=+1] + +include::modules/microshift-certificate-rotation.adoc[leveloffset=+1] + +include::modules/microshift-short-term-certificate-rotation.adoc[leveloffset=+2] + +include::modules/microshift-long-term-certificate-rotation.adoc[leveloffset=+2] + +[id="additional-resources_microshift-responsive-restarts-cas"] +[role="_additional-resources"] +== Additional resources + +* xref:../microshift_configuring/microshift_auth_security/microshift-custom-ca.adoc#microshift-custom-ca[Configuring custom certificate authorities] diff --git a/microshift_troubleshooting/microshift-things-to-know.adoc b/microshift_troubleshooting/microshift-things-to-know.adoc deleted file mode 100644 index bc641af44b..0000000000 --- a/microshift_troubleshooting/microshift-things-to-know.adoc +++ /dev/null @@ -1,24 +0,0 @@ -:_mod-docs-content-type: ASSEMBLY -[id="microshift-things-to-know"] -= Responsive restarts and security certificates -include::_attributes/attributes-microshift.adoc[] -:context: microshift-things-to-know - -toc::[] - -{microshift-short} responds to system configuration changes and restarts after alterations are detected, including IP address changes, clock adjustments, and security certificate age. - -[id="microshift-ip-address-clock-changes_{context}"] -== IP address changes or clock adjustments - -{microshift-short} depends on device IP addresses and system-wide clock settings to remain consistent during its runtime. However, these settings may occasionally change on edge devices, such as DHCP or Network Time Protocol (NTP) updates. - -When such changes occur, some {microshift-short} components may stop functioning properly. To mitigate this situation, {microshift-short} monitors the IP address and system time and restarts if either setting change is detected. - -The threshold for clock changes is a time adjustment of greater than 10 seconds in either direction. Smaller drifts on regular time adjustments performed by the Network Time Protocol (NTP) service do not cause a restart. - -include::modules/microshift-certificate-lifetime.adoc[leveloffset=+1] -[role="_additional-resources"] -.Additional resources - -* xref:../microshift_configuring/microshift_auth_security/microshift-custom-ca.adoc#microshift-custom-ca[Configuring custom certificate authorities]. \ No newline at end of file diff --git a/modules/microshift-certificate-lifetime.adoc b/modules/microshift-certificate-lifetime.adoc index 78a1cf83f5..a5fe9526d4 100644 --- a/modules/microshift-certificate-lifetime.adoc +++ b/modules/microshift-certificate-lifetime.adoc @@ -1,51 +1,15 @@ // Module included in the following assemblies: // -// * microshift/microshift-things-to-know.adoc +// * microshift_troubleshooting/microshift-responsive-restarts-cas.adoc :_mod-docs-content-type: CONCEPT [id="microshift-certificate-lifetime_{context}"] = Security certificate lifetime -{microshift-short} certificates are separated into two basic groups: +[role="_abstract"] +{microshift-short} certificates are digital certificates that secure communication with communication protocols such as HTTPS. They fall into two basic categories: -. Short-lived certificates having certificate validity of one year. -. Long-lived certificates having certificate validity of 10 years. +Short-lived certificates:: Have a certificate validity of one year. Most server or leaf certificates are short-lived. +Long-lived certificates:: Have a certificate validity of 10 years. An example of a long-lived certificate is the client certificate for `system:admin user` authentication, or the certificate of the signer of the `kube-apiserver` external serving certificate. -Most server or leaf certificates are short-lived. - -An example of a long-lived certificate is the client certificate for `system:admin user` authentication, or the certificate of the signer of the `kube-apiserver` external serving certificate. - -[id="microshift-certificate-rotation_{context}"] -== Certificate rotation -Certificates that are expired or close to their expiration dates need to be rotated to ensure continued {microshift-short} operation. When {microshift-short} restarts for any reason, certificates that are close to expiring are rotated. A certificate that is set to expire imminently, or has expired, can cause an automatic {microshift-short} restart to perform a rotation. - -[IMPORTANT] -==== -If the rotated certificate is a {microshift-short} certificate authority (CA), then all of the signed certificates rotate. If you created any custom CAs, ensure the CAs manually rotate. -==== - -[id="microshift-st-certificate-rotation_{context}"] -=== Short-term certificates -The following situations describe {microshift-short} actions during short-term certificate lifetimes: - -. No rotation: -.. When a short-term certificate is up to 5 months old, no rotation occurs. - -. Rotation at restart: -.. When a short-term certificate is 5 to 8 months old, it is rotated when {microshift-short} starts or restarts. - -. Automatic restart for rotation: -.. When a short-term certificate is more than 8 months old, {microshift-short} can automatically restart to rotate and apply a new certificate. - -[id="microshift-lt-certificate-rotation_{context}"] -=== Long-term certificates -The following situations describe {microshift-short} actions during long-term certificate lifetimes: - -. No rotation: -.. When a long-term certificate is up to 8.5 years old, no rotation occurs. - -. Rotation at restart: -.. When a long-term certificate is 8.5 to 9 years old, it is rotated when {microshift-short} starts or restarts. - -. Automatic restart for rotation: -.. When a long-term certificate is more than 9 years old, {microshift-short} might automatically restart so that it can rotate and apply a new certificate. \ No newline at end of file +{microshift-short} restarts automatically in certain cases, depending on certificate age. diff --git a/modules/microshift-certificate-rotation.adoc b/modules/microshift-certificate-rotation.adoc new file mode 100644 index 0000000000..41da03678c --- /dev/null +++ b/modules/microshift-certificate-rotation.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * microshift_troubleshooting/microshift-responsive-restarts-cas.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-certificate-rotation_{context}"] += Certificate rotation + +[role="_abstract"] +Certificates that are expired or close to their expiration dates must be rotated to ensure continued {microshift-short} operation. This rotation can be an automatic process. + +When {microshift-short} restarts for any reason, certificates that are close to expiring are rotated. A certificate that expires soon, or has already expired, can also cause an automatic {microshift-short} restart to perform a rotation. + +[IMPORTANT] +==== +If the rotated certificate is a {microshift-short} certificate authority (CA), then all of the signed certificates rotate. If you created any custom CAs, ensure that the CAs manually rotate. +==== diff --git a/modules/microshift-ip-address-clock-changes.adoc b/modules/microshift-ip-address-clock-changes.adoc new file mode 100644 index 0000000000..bf2a42770e --- /dev/null +++ b/modules/microshift-ip-address-clock-changes.adoc @@ -0,0 +1,14 @@ +// Module included in the following assemblies: +// +// * microshift_troubleshooting/microshift-responsive-restarts-cas.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-ip-address-clock-changes_{context}"] += IP address changes or clock adjustments + +[role="_abstract"] +{microshift-short} depends on device IP addresses and system-wide clock settings to remain consistent during its runtime. However, these settings might occasionally change on edge devices. + +For example, DHCP or Network Time Protocol (NTP) updates can change times. When these changes occur, some {microshift-short} components might stop functioning properly. To mitigate this situation, {microshift-short} monitors the IP address and system time and restarts if either setting changes. + +The threshold for clock changes is a time change of greater than 10 seconds in either direction. Smaller drifts on regular time adjustments performed by the Network Time Protocol (NTP) service do not cause a restart. diff --git a/modules/microshift-long-term-certificate-rotation.adoc b/modules/microshift-long-term-certificate-rotation.adoc new file mode 100644 index 0000000000..542d66655e --- /dev/null +++ b/modules/microshift-long-term-certificate-rotation.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * microshift_troubleshooting/microshift-responsive-restarts-cas.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-long-term-certificate-rotation_{context}"] += Long-term certificates rotation + +[role="_abstract"] +Long-term certificates that are expired or close to their expiration dates must be rotated to ensure continued {microshift-short} operation. + +The following situations describe {microshift-short} actions during long-term certificate lifetimes: + +No rotation:: +When a long-term certificate is up to 8.5 years old, no rotation occurs. + +Rotation at restart:: +When a long-term certificate is 8.5 to 9 years old, it is rotated when {microshift-short} starts or restarts. + +Automatic restart for rotation:: +When a long-term certificate is more than 9 years old, {microshift-short} might automatically restart so that it can rotate and apply a new certificate. diff --git a/modules/microshift-short-term-certificate-rotation.adoc b/modules/microshift-short-term-certificate-rotation.adoc new file mode 100644 index 0000000000..0f3ae9efd6 --- /dev/null +++ b/modules/microshift-short-term-certificate-rotation.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * microshift_troubleshooting/microshift-responsive-restarts-cas.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-short-term-certificate-rotation_{context}"] += Short-term certificates rotation + +[role="_abstract"] +Short-term certificates that are expired or close to their expiration dates must be rotated to ensure continued {microshift-short} operation. + +The following situations describe {microshift-short} actions during short-term certificate lifetimes: + +No rotation:: +When a short-term certificate is up to 5 months old, no rotation occurs. + +Rotation at restart:: +When a short-term certificate is 5 to 8 months old, it is rotated when {microshift-short} starts or restarts. + +Automatic restart for rotation:: +When a short-term certificate is more than 8 months old, {microshift-short} can automatically restart to rotate and apply a new certificate.