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