Merge pull request #93890 from gaurav-nelson/ROX-29354-byodb-req

[RHACS] Add external database requirements documentation

Author: gaurav-nelson

installing/acs-default-requirements.adoc

@@ -11,3 +11,10 @@ include::modules/acs-requirements.adoc[leveloffset=+1]
 include::modules/default-requirements-central-services.adoc[leveloffset=+1]
 
 include::modules/default-requirements-secured-cluster-services.adoc[leveloffset=+1]
+
+include::modules/default-requirements-external-db.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../installing/installing-rhacs-on-red-hat-openshift#provision-postgresql-database_install-central-ocp[Provisioning a database in your PostgreSQL instance]

installing/installing_ocp/install-central-ocp.adoc

@@ -42,6 +42,7 @@ include::modules/install-central-operator-external-db.adoc[leveloffset=+2]
 [role="_additional-resources"]
 .Additional resources
 
+* xref:../../installing/acs-default-requirements.adoc#default-requirements-central-services_acs-default-requirements[Requirements for using an external database]
 * xref:../installing_ocp/install-central-config-options-ocp.adoc#install-central-config-options-ocp[Central configuration options]
 * xref:https://www.postgresql.org/docs/15/libpq-connect.html#LIBPQ-CONNSTRING[PostgreSQL Connection String Docs]
 

modules/default-requirements-external-db.adoc

@@ -0,0 +1,45 @@
+// Module included in the following assemblies:
+//
+// * installing/acs-default-requirements.adoc
+:_mod-docs-content-type: CONCEPT
+[id="external-db-req_{context}"]
+= Requirements for using an external database
+
+[role="_abstract"]
+You can configure {product-title} Central services to use an external PostgreSQL-compatible database for data persistence instead of deploying its own database pod.
+
+[IMPORTANT]
+====
+When you use an external database, note the following guidance:
+
+* The database infrastructure manages persistent storage for Central DB. Therefore, do not configure persistence settings for the Central DB within the {product-title-short} installation configuration.
+* Red Hat supports the configuration and operation of {product-title-short} Central connected to that database. However, support for database-specific operations such as backup and restore, performance diagnosis and potential tuning, software and version upgrades, and high availability/disaster recovery operation falls under third-party support. Manually upgrading or customizing your database outside of a full platform upgrade also limits supportability.
+====
+
+If you select an external database, your database instance and the user connecting to it must meet the requirements listed in the following sections.
+
+[discrete]
+== Database type and version
+The database must be a PostgreSQL-compatible database that supports PostgreSQL 13 or later.
+
+[discrete]
+== User permissions
+The user account that Central uses to connect to the database must be a `superuser` account with connection rights to the database and the following permissions:
+
+* `Usage` and `Create` permissions on the schema.
+* `Select`, `Insert`, `Update`, and `Delete` permissions on all tables in the schema.
+* `Usage` permissions on all sequences in the schema.
+* The ability to create and delete databases as a `superuser`.
+
+[discrete]
+== Connection string
+Central connects to the external database by using a connection string, which must be in `keyword=value` format. The connection string should specify details such as the host, port, database name, user, and SSL/TLS mode. For example, `host=<host> port=5432 database=stackrox user=stackrox sslmode=verify-ca`.
+
+[NOTE]
+====
+Connections through *PgBouncer* are not supported.
+====
+
+[discrete]
+== CA certificates
+If your external database uses a certificate issued by a private or untrusted Certificate Authority (CA), you might need to specify the CA certificate so that Central trusts the database certificate. You can add this by using a TLS block in the Central custom resource configuration.

modules/install-central-operator-external-db.adoc

@@ -18,16 +18,12 @@ For more information about {product-title-short} databases, see the link:https:/
 
 .Prerequisites
 * You must be using {ocp} {ocp-supported-version} or later. For more information about supported {ocp} versions, see the link:https://access.redhat.com/articles/7045053[Red Hat Advanced Cluster Security for Kubernetes Support Matrix].
-* You must have a database in your database instance that supports PostgreSQL 13 or 15 and a user with the following permissions:
-** Connection rights to the database.
-** `Usage` and `Create` on the schema.
-** `Select`, `Insert`, `Update`, and `Delete` on all tables in the schema.
-** `Usage` on all sequences in the schema.
 +
 [NOTE]
 ====
 Postgres 15 is the recommended and supported version. Red{nbsp}Hat has deprecated the support for Postgres 13 and will remove it in the newer versions of {product-title-short}.
 ====
+* For detailed requirements, see "Requirements for using an external database" in the additional resources section.
 
 .Procedure
 . On the {ocp} web console, go to the *Operators* -> *Installed Operators* page.

upgrading/upgrade-operator.adoc

@@ -40,7 +40,8 @@ To roll back an Operator upgrade, you must perform the steps described in one of
 
 [NOTE]
 ====
-If you are rolling back from {product-title-short} 4.0, you can only rollback to the latest patch release version of {product-title-short} 3.74.
+* If you are rolling back from {product-title-short} 4.0, you can only roll back to the latest patch release version of {product-title-short} 3.74.
+* If you are rolling back from {product-title-short} 4.8 or newer, you can only roll back to the latest patch release version of {product-title-short} 4.8.
 ====
 
 include::modules/rollback-operator-upgrades-cli.adoc[leveloffset=+2]