From 70653f16901d2bc411a9c69f143a9db3e30b1a0b Mon Sep 17 00:00:00 2001 From: Agil Antony Date: Mon, 29 Sep 2025 20:09:22 +0530 Subject: [PATCH] ROX28969 Improve Clarity and Completeness of 'Reissuing Internal Certificates' section ROX28969 Review comments ROX28969 Review comments ROX28969 Review comments ROX28969 Review comments ROX28969 Review comments ROX28969 Review comments ROX28969 Review comments ROX28969 Review comments --- configuration/add-custom-certificates.adoc | 5 ++- configuration/add-trusted-ca.adoc | 5 ++- configuration/configure-endpoints.adoc | 5 ++- .../reissue-internal-certificates.adoc | 31 +++++++++++---- ...reissue-internal-certificates-central.adoc | 38 ------------------- ...reissue-internal-certificates-scanner.adoc | 30 --------------- ...-internal-certificates-for-central-db.adoc | 25 ++++++++++++ ...nal-certificates-for-central-services.adoc | 30 +++++++++++++++ ...ing-internal-certificates-for-central.adoc | 25 ++++++++++++ ...-internal-certificates-for-scanner-v4.adoc | 24 ++++++++++++ ...ing-internal-certificates-for-scanner.adoc | 24 ++++++++++++ modules/restart-central-container.adoc | 31 --------------- ...tart-scanner-and-scannerdb-containers.adoc | 26 ------------- modules/restarting-the-central-container.adoc | 26 +++++++++++++ .../restarting-the-central-db-container.adoc | 26 +++++++++++++ ...the-scanner-and-scanner-db-containers.adoc | 31 +++++++++++++++ .../restarting-the-scanner-v4-containers.adoc | 38 +++++++++++++++++++ 17 files changed, 281 insertions(+), 139 deletions(-) delete mode 100644 modules/reissue-internal-certificates-central.adoc delete mode 100644 modules/reissue-internal-certificates-scanner.adoc create mode 100644 modules/reissuing-internal-certificates-for-central-db.adoc create mode 100644 modules/reissuing-internal-certificates-for-central-services.adoc create mode 100644 modules/reissuing-internal-certificates-for-central.adoc create mode 100644 modules/reissuing-internal-certificates-for-scanner-v4.adoc create mode 100644 modules/reissuing-internal-certificates-for-scanner.adoc delete mode 100644 modules/restart-central-container.adoc delete mode 100644 modules/restart-scanner-and-scannerdb-containers.adoc create mode 100644 modules/restarting-the-central-container.adoc create mode 100644 modules/restarting-the-central-db-container.adoc create mode 100644 modules/restarting-the-scanner-and-scanner-db-containers.adoc create mode 100644 modules/restarting-the-scanner-v4-containers.adoc diff --git a/configuration/add-custom-certificates.adoc b/configuration/add-custom-certificates.adoc index 68d407adb9e8..2d2c7fecae89 100644 --- a/configuration/add-custom-certificates.adoc +++ b/configuration/add-custom-certificates.adoc @@ -1,3 +1,4 @@ +:_mod-docs-content-type: ASSEMBLY [id="add-custom-cert"] = Adding custom certificates include::modules/common-attributes.adoc[] @@ -25,8 +26,8 @@ include::modules/custom-cert-existing.adoc[leveloffset=+2] //Updating certificates on an existing installation include::modules/update-custom-certificate-central.adoc[leveloffset=+2] -//Restart Central -include::modules/restart-central-container.adoc[leveloffset=+3] +//Restarting the Central container +include::modules/restarting-the-central-container.adoc[leveloffset=+3] [id="configure-sensor-to-trust-cert"] == Configuring Sensor to trust custom certificates diff --git a/configuration/add-trusted-ca.adoc b/configuration/add-trusted-ca.adoc index 5f548bca771c..83a58aecfb66 100644 --- a/configuration/add-trusted-ca.adoc +++ b/configuration/add-trusted-ca.adoc @@ -1,3 +1,4 @@ +:_mod-docs-content-type: ASSEMBLY [id="add-trusted-ca"] = Adding trusted certificate authorities include::modules/common-attributes.adoc[] @@ -33,8 +34,8 @@ After you configure trusted CAs, you must make {product-title} services trust th * Additionally, if you are also adding certificates for integrating with image registries, you must restart both Central and Scanner. //TODO: Add link to integrating with image registries -//Restart Central -include::modules/restart-central-container.adoc[leveloffset=+2] +//Restarting the Central container +include::modules/restarting-the-central-container.adoc[leveloffset=+2] //Restart Scanner include::modules/restart-scanner-container.adoc[leveloffset=+2] diff --git a/configuration/configure-endpoints.adoc b/configuration/configure-endpoints.adoc index 2f532038f3ad..1c363bcd0b4b 100644 --- a/configuration/configure-endpoints.adoc +++ b/configuration/configure-endpoints.adoc @@ -1,3 +1,4 @@ +:_mod-docs-content-type: ASSEMBLY [id="configure-endpoints"] = Configuring endpoints include::modules/common-attributes.adoc[] @@ -18,6 +19,6 @@ include::modules/configure-endpoints-new-install.adoc[leveloffset=+1] include::modules/configure-endpoints-existing.adoc[leveloffset=+1] -include::modules/restart-central-container.adoc[leveloffset=+2] +include::modules/restarting-the-central-container.adoc[leveloffset=+2] -include::modules/enable-traffic-flow-through-custom-ports.adoc[leveloffset=+1] +include::modules/enable-traffic-flow-through-custom-ports.adoc[leveloffset=+1] \ No newline at end of file diff --git a/configuration/reissue-internal-certificates.adoc b/configuration/reissue-internal-certificates.adoc index 3d84e99148fa..2e80d4a3d132 100644 --- a/configuration/reissue-internal-certificates.adoc +++ b/configuration/reissue-internal-certificates.adoc @@ -13,17 +13,32 @@ You can view the certificate expiration dates by selecting *Platform Configurati //Add link to role based permissions and resources -//reissue internal certificates for Central -include::modules/reissue-internal-certificates-central.adoc[leveloffset=+1] +//Reissuing internal certificates for Central services +include::modules/reissuing-internal-certificates-for-central-services.adoc[leveloffset=+1] -//Restart Central -include::modules/restart-central-container.adoc[leveloffset=+2] +//Reissuing internal certificates for Central +include::modules/reissuing-internal-certificates-for-central.adoc[leveloffset=+2] -//reissue internal certificates for Scanner -include::modules/reissue-internal-certificates-scanner.adoc[leveloffset=+1] +//Restarting the Central container +include::modules/restarting-the-central-container.adoc[leveloffset=+3] -//Restart Scanner & Scanner DB -include::modules/restart-scanner-and-scannerdb-containers.adoc[leveloffset=+2] +//Reissuing internal certificates for Central DB +include::modules/reissuing-internal-certificates-for-central-db.adoc[leveloffset=+2] + +//Restarting the Central DB container +include::modules/restarting-the-central-db-container.adoc[leveloffset=+3] + +//Reissuing internal certificates for Scanner +include::modules/reissuing-internal-certificates-for-scanner.adoc[leveloffset=+2] + +//Restarting the Scanner and Scanner DB containers +include::modules/restarting-the-scanner-and-scanner-db-containers.adoc[leveloffset=+3] + +//Reissuing internal certificates for Scanner V4 +include::modules/reissuing-internal-certificates-for-scanner-v4.adoc[leveloffset=+2] + +//Restarting the Scanner V4 containers +include::modules/restarting-the-scanner-v4-containers.adoc[leveloffset=+3] [id="reissue-internal-certificates-secured-clusters_{context}"] == Reissuing internal certificates for secured clusters diff --git a/modules/reissue-internal-certificates-central.adoc b/modules/reissue-internal-certificates-central.adoc deleted file mode 100644 index 6a2553c2bfbd..000000000000 --- a/modules/reissue-internal-certificates-central.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// * configuration/reissue-internal-certificates.adoc -:_mod-docs-content-type: PROCEDURE -[id="reissue-internal-certificates-central_{context}"] -= Reissuing internal certificates for Central - -Central uses a built-in server certificate for authentication when communicating with other {product-title} services. -This certificate is unique to your Central installation. -The {product-title-short} portal shows an information banner when the Central certificate is about to expire. - -[NOTE] -==== -The information banner only appears 15 days before the certificate expiration date. -==== - -For Operator-based installations, beginning with {product-title-short} version 4.3.4, the Operator will automatically rotate all Central components' service transport layer security (TLS) certificates 6 months before they expire. The following conditions apply: - -* The rotation of certificates in the secrets does not trigger the components to automatically reload them. However, reloads typically occur when the pod is replaced as part of an {product-title-short} upgrade or as a result of node reboots. If neither of those events happens at least every 6 months, you must restart the pods before the old (in-memory) service certificates expire. For example, you can delete the pods with an `app` label that contains one of the values of `central`, `central-db`, `scanner`, or `scanner-db`. - -* CA certificates are not updated. They are valid for 5 years. - -For non-Operator based installations, you must manually rotate TLS certificates. Instructions for manually rotating certificates are included in the following section. - -.Prerequisites - -* To reissue, or rotate, certificates, you must have `write` permission for the `Administration` resource. - -.Procedure - -. In the {product-title-short} portal, click on the link in the banner that announces the certificate expiration to download a YAML configuration file, which contains a new secret. The secret includes the certificate and key values. -. Apply the new YAML configuration file to the cluster where you have installed Central by running the following command: -+ -[source,terminal] ----- -$ oc apply -f ----- -. Restart Central to apply the changes. diff --git a/modules/reissue-internal-certificates-scanner.adoc b/modules/reissue-internal-certificates-scanner.adoc deleted file mode 100644 index 85a555887569..000000000000 --- a/modules/reissue-internal-certificates-scanner.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * configuration/reissue-internal-certificates.adoc -:_mod-docs-content-type: PROCEDURE -[id="reissue-internal-certificates-scanner_{context}"] -= Reissuing internal certificates for Scanner - -Scanner has a built-in certificate that it uses to communicate with Central. - -The {product-title-short} portal shows an information banner when the Scanner certificate is about to expire. - -[NOTE] -==== -The information banner only appears 15 days before the certificate expiry date. -==== - -.Prerequisites - -* To reissue certificates, you must have `write` permission for the `Administration` resource. - -.Procedure - -. Click on the link in the banner to download a YAML configuration file, which contains a new {ocp} secret, including the certificate and key values. -. Apply the new YAML configuration file to the cluster where you installed Scanner. -+ -[source,terminal] ----- -$ oc apply -f ----- -. Restart Scanner to apply the changes. diff --git a/modules/reissuing-internal-certificates-for-central-db.adoc b/modules/reissuing-internal-certificates-for-central-db.adoc new file mode 100644 index 000000000000..d0f8278d05d9 --- /dev/null +++ b/modules/reissuing-internal-certificates-for-central-db.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * configuration/reissue-internal-certificates.adoc + +:_mod-docs-content-type: PROCEDURE +[id="reissuing-internal-certificates-for-central-db_{context}"] += Reissuing internal certificates for Central DB + +You can maintain a secure communication between Central DB and other {rh-rhacs-first} components by reissuing the internal certificates. + +.Prerequisites + +* You have `write` permission for the `Administration` resource. + +.Procedure + +. In the {product-title-short} portal, click the link in the banner that announces the certificate expiration to download a YAML configuration file, which contains a new secret. The secret includes the certificate and key values. +. To apply the new YAML configuration file to the cluster where you have installed Central DB, run the following command: ++ +[source,terminal] +---- +$ oc apply -f +---- + +. To apply the changes, restart Central DB. \ No newline at end of file diff --git a/modules/reissuing-internal-certificates-for-central-services.adoc b/modules/reissuing-internal-certificates-for-central-services.adoc new file mode 100644 index 000000000000..d0841cacfa97 --- /dev/null +++ b/modules/reissuing-internal-certificates-for-central-services.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * configuration/reissue-internal-certificates.adoc + +:_mod-docs-content-type: CONCEPT +[id="reissuing-internal-certificates-for-central-services_{context}"] += Reissuing internal certificates for Central services + +The Central services contain the Central, Central DB, Scanner, and Scanner V4 components. +The Central services use a built-in server certificate for authentication when communicating with other {rh-rhacs-first} services. +This certificate is unique to your Central service installation. +The {product-title-short} portal shows an informational banner when a Central service certificate is about to expire. + +[NOTE] +==== +The informational banner only appears 15 days before the certificate expiration date. +==== + +Beginning with {product-title-short} 4.3.4, the Operator automatically rotates the service transport layer security (TLS) certificates for all of the Central components 6 months before they expire. + +[IMPORTANT] +==== +* The automated rotation of the TLS certificates applies only to Operator-based installations. For all other installation methods, you must manually rotate the TLS certificates. + +* The rotation of the TLS certificates within the secrets does not automatically trigger the components to reload them. If the corresponding pods are not restarted at least every 6 months, you must manually restart the pods to load the new certificates before the old ones expire. + +ifeval::["{rhacs-version}" < "4.9.0"] +* Certificate authority (CA) certificates are not updated. They are valid for 5 years. +endif::[] +==== \ No newline at end of file diff --git a/modules/reissuing-internal-certificates-for-central.adoc b/modules/reissuing-internal-certificates-for-central.adoc new file mode 100644 index 000000000000..3fe0742533e5 --- /dev/null +++ b/modules/reissuing-internal-certificates-for-central.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * configuration/reissue-internal-certificates.adoc + +:_mod-docs-content-type: PROCEDURE +[id="reissuing-internal-certificates-for-central_{context}"] += Reissuing internal certificates for Central + +You can maintain a secure communication between Central and other {rh-rhacs-first} components by reissuing the internal certificates. + +.Prerequisites + +* You have `write` permission for the `Administration` resource. + +.Procedure + +. In the {product-title-short} portal, click the link in the banner that announces the certificate expiration to download a YAML configuration file, which contains a new secret. The secret includes the certificate and key values. +. To apply the new YAML configuration file to the cluster where you have installed Central, run the following command: ++ +[source,terminal] +---- +$ oc apply -f +---- + +. To apply the changes, restart Central. \ No newline at end of file diff --git a/modules/reissuing-internal-certificates-for-scanner-v4.adoc b/modules/reissuing-internal-certificates-for-scanner-v4.adoc new file mode 100644 index 000000000000..2060215f7adb --- /dev/null +++ b/modules/reissuing-internal-certificates-for-scanner-v4.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * configuration/reissue-internal-certificates.adoc + +:_mod-docs-content-type: PROCEDURE +[id="reissuing-internal-certificates-for-scanner-v4_{context}"] += Reissuing internal certificates for Scanner V4 + +You can maintain a secure communication between Scanner V4 and other {rh-rhacs-first} components by reissuing the internal certificates. + +.Prerequisites + +* You have `write` permission for the `Administration` resource. + +.Procedure + +. Click the link in the banner to download a YAML configuration file, which contains a new {ocp} secret, including the certificate and key values. +. To apply the new YAML configuration file to the cluster where you have installed Scanner V4, run the following command: ++ +[source,terminal] +---- +$ oc apply -f +---- +. To apply the changes, restart Scanner V4. \ No newline at end of file diff --git a/modules/reissuing-internal-certificates-for-scanner.adoc b/modules/reissuing-internal-certificates-for-scanner.adoc new file mode 100644 index 000000000000..f4b0248918ec --- /dev/null +++ b/modules/reissuing-internal-certificates-for-scanner.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * configuration/reissue-internal-certificates.adoc + +:_mod-docs-content-type: PROCEDURE +[id="reissuing-internal-certificates-for-scanner_{context}"] += Reissuing internal certificates for Scanner + +You can maintain a secure communication between Scanner and other {rh-rhacs-first} components by reissuing the internal certificates. + +.Prerequisites + +* You have `write` permission for the `Administration` resource. + +.Procedure + +. Click the link in the banner to download a YAML configuration file, which contains a new {ocp} secret, including the certificate and key values. +. To apply the new YAML configuration file to the cluster where you have installed Scanner, run the following command: ++ +[source,terminal] +---- +$ oc apply -f +---- +. To apply the changes, restart Scanner. \ No newline at end of file diff --git a/modules/restart-central-container.adoc b/modules/restart-central-container.adoc deleted file mode 100644 index eb78d76ddaa0..000000000000 --- a/modules/restart-central-container.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * configuration/add-trusted-ca.adoc -// * configuration/configure-endpoints.adoc - -:_mod-docs-content-type: PROCEDURE -[id="restart-central_{context}"] -= Restarting the Central container - -[role="_abstract"] -You can restart the Central container by killing the Central container or by deleting the Central pod. - -.Procedure - -* Run the following command to kill the Central container: -+ -[NOTE] -==== -You must wait for at least 1 minute, until {ocp} propagates your changes and restarts the Central container. -==== -+ -[source,terminal] ----- -$ oc -n stackrox exec deploy/central -c central -- kill 1 ----- -* Or, run the following command to delete the Central pod: -+ -[source,terminal] ----- -$ oc -n stackrox delete pod -lapp=central ----- diff --git a/modules/restart-scanner-and-scannerdb-containers.adoc b/modules/restart-scanner-and-scannerdb-containers.adoc deleted file mode 100644 index 738ca93e62fc..000000000000 --- a/modules/restart-scanner-and-scannerdb-containers.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * configuration/reissue-internal-certificates.adoc - -:_mod-docs-content-type: PROCEDURE -[id="restart-scanner_{context}"] -= Restarting the Scanner and Scanner DB containers - -[role="_abstract"] -You can restart the Scanner and Scanner DB container by deleting the pods. - -.Procedure - -* To delete the Scanner and Scanner DB pods, run the following command: -** On {ocp}: -+ -[source,terminal] ----- -$ oc delete pod -n stackrox -l app=scanner; oc -n stackrox delete pod -l app=scanner-db ----- -** On Kubernetes: -+ -[source,terminal] ----- -$ kubectl delete pod -n stackrox -l app=scanner; kubectl -n stackrox delete pod -l app=scanner-db ----- diff --git a/modules/restarting-the-central-container.adoc b/modules/restarting-the-central-container.adoc new file mode 100644 index 000000000000..0e5a41ade7be --- /dev/null +++ b/modules/restarting-the-central-container.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * configuration/add-trusted-ca.adoc +// * configuration/configure-endpoints.adoc +// * configuration/add-custom-certificates.adoc + +:_mod-docs-content-type: PROCEDURE +[id="restarting-the-central-container_{context}"] += Restarting the Central container + +[role="_abstract"] +You can restart the Central container by deleting the Central pod. + +[IMPORTANT] +==== +If you use Kubernetes, enter `kubectl` instead of `oc`. +==== + +.Procedure + +* To delete the Central pod, run the following command: ++ +[source,terminal] +---- +$ oc -n stackrox delete pod -lapp=central +---- \ No newline at end of file diff --git a/modules/restarting-the-central-db-container.adoc b/modules/restarting-the-central-db-container.adoc new file mode 100644 index 000000000000..dbe025b9dd65 --- /dev/null +++ b/modules/restarting-the-central-db-container.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * configuration/add-trusted-ca.adoc +// * configuration/configure-endpoints.adoc +// * configuration/add-custom-certificates.adoc + +:_mod-docs-content-type: PROCEDURE +[id="restarting-the-central-db-container_{context}"] += Restarting the Central DB container + +[role="_abstract"] +You can restart the Central DB container by deleting the Central DB pod. + +[IMPORTANT] +==== +If you use Kubernetes, enter `kubectl` instead of `oc`. +==== + +.Procedure + +* To delete the Central DB pod, run the following command: ++ +[source,terminal] +---- +$ oc -n stackrox delete pod -lapp=central-db +---- \ No newline at end of file diff --git a/modules/restarting-the-scanner-and-scanner-db-containers.adoc b/modules/restarting-the-scanner-and-scanner-db-containers.adoc new file mode 100644 index 000000000000..275df5e833a3 --- /dev/null +++ b/modules/restarting-the-scanner-and-scanner-db-containers.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * configuration/reissue-internal-certificates.adoc + +:_mod-docs-content-type: PROCEDURE +[id="restarting-the-scanner-and-scanner-db-containers_{context}"] += Restarting the Scanner and Scanner DB containers + +[role="_abstract"] +You can restart the Scanner and Scanner DB containers by deleting the pods. + +[IMPORTANT] +==== +If you use Kubernetes, enter `kubectl` instead of `oc`. +==== + +.Procedure + +* To delete the Scanner pods, run the following command: ++ +[source,terminal] +---- +$ oc delete pod -n stackrox -l app=scanner +---- + +* To delete the Scanner DB pods, run the following command: ++ +[source,terminal] +---- +$ oc -n stackrox delete pod -l app=scanner-db +---- \ No newline at end of file diff --git a/modules/restarting-the-scanner-v4-containers.adoc b/modules/restarting-the-scanner-v4-containers.adoc new file mode 100644 index 000000000000..de19c15024ec --- /dev/null +++ b/modules/restarting-the-scanner-v4-containers.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * configuration/reissue-internal-certificates.adoc + +:_mod-docs-content-type: PROCEDURE +[id="restarting-the-scanner-v4-containers_{context}"] += Restarting the Scanner V4 containers + +[role="_abstract"] +You can restart the Scanner V4 Matcher, Indexer and DB containers by deleting their corresponding pods. + +[IMPORTANT] +==== +If you use Kubernetes, enter `kubectl` instead of `oc`. +==== + +.Procedure + +* To delete the Scanner V4 Matcher pod, run the following command: ++ +[source,terminal] +---- +$ oc delete pod -n stackrox -l app=scanner-v4-matcher +---- + +* To delete the Scanner V4 Indexer pod, run the following command: ++ +[source,terminal] +---- +$ oc delete pod -n stackrox -l app=scanner-v4-indexer +---- + +* To delete the Scanner V4 DB pod, run the following command: ++ +[source,terminal] +---- +$ oc delete pod -n stackrox -l app=scanner-v4-db +---- \ No newline at end of file