Enhance install.md documentation #2341

rakeshgm · 2025-11-17T12:58:07Z

Enhancement to PR #2332: refines and simplifies the installation documentation.
Changes:

Reorganised prerequisites and simplified sections
Streamlined installation steps and verification procedures
Updated command formatting and section titles
Clarified DR modes and storage requirements

This PR focuses only on install.md improvements.

Signed-off-by: Chris Blum <cblum@ibm.com> (cherry picked from commit 568d24e) Signed-off-by: rakeshgm <rakeshgm@redhat.com>

ShyamsundarR

Initial set of comments

ShyamsundarR · 2025-11-24T22:23:24Z

docs/install.md

+
+**Supported versions:**
+
+- Kubernetes 1.20 or higher


Make this 1.30 and above; 1.20 is quite old at present.

ShyamsundarR · 2025-11-24T22:43:40Z

docs/install.md

+
+**Requirements:**
+
+- OCM hub cluster with `multicluster-engine` installed


I am not sure about "multicluster-engine" installation.

We have a few addons that we require, as we install in drenv, and we should leverage that as an example here.

See:

ramen/test/addons/ocm-hub/start

Lines 19 to 28 in a5256ba

ADDONS = (

{

"name": "application-manager",

"version": BUNDLE_VERSION,

},

{

"name": "governance-policy-framework",

"version": BUNDLE_VERSION,

},

)

ramen/test/addons/ocm-controller/kustomization.yaml

Line 11 in a5256ba

- https://github.com/stolostron/multicloud-operators-foundation.git/deploy/foundation/hub/overlays/ocm-controller?ref=main&timeout=300s

(for managed cluster)

ramen/test/addons/ocm-cluster/start

Lines 22 to 35 in a5256ba

ADDONS = (

{

"name": "application-manager",

"deployment": "application-manager",

},

{

"name": "governance-policy-framework",

"deployment": "governance-policy-framework",

},

{

"name": "config-policy-controller",

"deployment": "config-policy-controller",

},

)

I have added all the add-ons list now but I have not added any explicit installation links for any

ShyamsundarR · 2025-11-24T22:46:45Z

docs/install.md

+#### Sync Mode (Metro DR)
+
+Sync mode uses a dedicated external storage cluster that all managed clusters
+connect to, enabling synchronous, real-time data replication.


Remove this "enabling synchronous, real-time data replication.".

The use of an external shared storage is not the one providing sync replication, hence the latter part of the sentence is misleading.

We could add something like ", providing all clusters access to the same storage backend."

ShyamsundarR · 2025-11-24T22:47:34Z

docs/install.md

+
+#### Sync Mode (Metro DR)
+
+Sync mode uses a dedicated external storage cluster that all managed clusters


drop "dedicated" the storage cluster can be of other forms as well.

ShyamsundarR · 2025-11-24T22:48:54Z

docs/install.md

+
+**Supported:**
+
+- Any CSI-compatible storage that supports synchronous replication


Reword to "Any CSI-compatible storage that supports connecting to a shared external storage cluster"

ShyamsundarR · 2025-11-24T22:50:32Z

docs/install.md

+**Supported:**
+
+- Any CSI-compatible storage that supports synchronous replication
+- External storage clusters accessible from all managed clusters


Replace this line with, "CSI drivers support static provisioning for PVCs and have the ability to attach the same storage when a PV is transferred from one cluster to the other, when sharing the same storage backend" (or something along these lines, to indicate that we do PV transfers and the CSI drivers should allow static provisioning etc.)

ShyamsundarR · 2025-11-24T22:51:54Z

docs/install.md

+
+- Dedicated external storage cluster
+- Storage provider installed that supports CSI and synchronous replication
+- StorageClasses on managed clusters with the same `storageID` label


The reference to a storageID label here is incomplete, i.e we need the entire label. Also the label is storageid (no caps at the end) as in code.

ShyamsundarR · 2025-11-24T22:53:28Z

docs/install.md

+
+**Supported:**
+
+- Any CSI-compatible storage that supports VolumeReplication or VolSync


Replace Volsync with VolumeSnapshots, as the storage CSI need not support Volsync, it only needs to support VolumeSnapshots.

Hmmm next line seems to state the same thing as well, so maybe we fold it into one.

Provide link to csi-addons spec repository for VolRep.

ShyamsundarR · 2025-11-24T22:54:27Z

docs/install.md

+
+#### Async Mode (Regional DR)
+
+Async mode uses local storage in each managed cluster with asynchronous


We do not need "local storage". I think this also needs to be massaged.

ShyamsundarR · 2025-11-25T11:04:25Z

docs/install.md

+- Low-latency network connectivity between managed clusters and the external
+    storage cluster
+
+#### Async Mode (Regional DR)


(future) Overall we would need a doc on sync/async and what that means in the DR and ramen scope

ShyamsundarR

Done with comments.

ShyamsundarR · 2025-11-25T11:06:28Z

docs/install.md

+**Required:**
+
+- Storage provider installed in each managed cluster that supports CSI and
+    volume replication


volrep or volsnapshot

ShyamsundarR · 2025-11-25T11:09:10Z

docs/install.md

+
+The following tools must be installed on your workstation:
+
+- **kubectl** >= v1.21 - Kubernetes CLI


push version to 1.30

ShyamsundarR · 2025-11-25T11:19:50Z

docs/install.md


- kubectl > v1.21
-    - kubectl version can be verfied using
+### Configuration Prerequisites


Once configure.md is posted, I think I will delete this section in this doc.

ShyamsundarR · 2025-11-25T11:21:33Z

docs/install.md

+- Missing dependencies - ensure OCM is properly installed
+
+### Rollback Installation
+


Add a note to state that if configure, rollback configuration before rolling back the installation.

Signed-off-by: rakeshgm <rakeshgm@redhat.com>

rakeshgm requested review from BenamarMk and ShyamsundarR as code owners November 17, 2025 12:58

rakeshgm force-pushed the install-doc-enhance branch 6 times, most recently from f08b751 to 0262c90 Compare November 17, 2025 14:09

rakeshgm marked this pull request as draft November 17, 2025 14:12

rakeshgm force-pushed the install-doc-enhance branch from 0262c90 to 62ec11a Compare November 17, 2025 14:17

update install doc

dfbe4e1

Signed-off-by: Chris Blum <cblum@ibm.com> (cherry picked from commit 568d24e) Signed-off-by: rakeshgm <rakeshgm@redhat.com>

rakeshgm force-pushed the install-doc-enhance branch from 62ec11a to 5d580a4 Compare November 17, 2025 14:20

rakeshgm marked this pull request as ready for review November 17, 2025 14:21

rakeshgm force-pushed the install-doc-enhance branch from 5d580a4 to ff20e94 Compare November 17, 2025 17:08

This was referenced Nov 19, 2025

DFBUGS-4690: Add new metrics and alert when CG is enabled on DRPC red-hat-storage/ramen#663

Merged

DFBUGS-4691: Add new metrics and alert when CG is enabled on DRPC red-hat-storage/ramen#664

Merged

rakeshgm force-pushed the install-doc-enhance branch from ff20e94 to 59deab5 Compare November 19, 2025 07:49

ShyamsundarR reviewed Nov 25, 2025

View reviewed changes

rakeshgm force-pushed the install-doc-enhance branch from 59deab5 to 0aefbcc Compare November 28, 2025 07:34

install.md: enhancement

d6faa71

Signed-off-by: rakeshgm <rakeshgm@redhat.com>

rakeshgm force-pushed the install-doc-enhance branch from 0aefbcc to d6faa71 Compare November 28, 2025 08:34


		Requirements:

		- OCM hub cluster with `multicluster-engine` installed

	ADDONS = (
	{
	"name": "application-manager",
	"version": BUNDLE_VERSION,
	},
	{
	"name": "governance-policy-framework",
	"version": BUNDLE_VERSION,
	},
	)

	ADDONS = (
	{
	"name": "application-manager",
	"deployment": "application-manager",
	},
	{
	"name": "governance-policy-framework",
	"deployment": "governance-policy-framework",
	},
	{
	"name": "config-policy-controller",
	"deployment": "config-policy-controller",
	},
	)


		#### Sync Mode (Metro DR)

		Sync mode uses a dedicated external storage cluster that all managed clusters


		Supported:

		- Any CSI-compatible storage that supports synchronous replication


		#### Async Mode (Regional DR)

		Async mode uses local storage in each managed cluster with asynchronous


		The following tools must be installed on your workstation:

		- kubectl >= v1.21 - Kubernetes CLI

		- Missing dependencies - ensure OCM is properly installed

		### Rollback Installation

Enhance install.md documentation #2341

Are you sure you want to change the base?

Enhance install.md documentation #2341

Uh oh!

Conversation

rakeshgm commented Nov 17, 2025

Uh oh!

ShyamsundarR left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShyamsundarR left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants