CNV-57758: Document virtualization with IBM fusion access for SAN

# CNV-57758: Documented secret creation, still need verification step

 # CNV-57758: Added new module for creating the extension machineconfig file needed to add kernel-devel to worker nodes

 # CNV-57758: fixed formatting issue and added text at beginning of procedure

 # CNV-57758: vale nits

 # CNV-57758: mnore nits

 # CNV-57758: About section written

 # CNV-57758: About section written

 # CNV-57758: added registry prereq to operator installation procedure

_attributes/common-attributes.adoc

@@ -119,7 +119,8 @@ endif::[]
 :CNVOperatorDisplayName: OpenShift Virtualization Operator
 :CNVSubscriptionSpecSource: redhat-operators
 :CNVSubscriptionSpecName: kubevirt-hyperconverged
-:IBMFusionSAN: IBM Fusion Access for SAN
+:IBMFusionFirst: IBM Fusion Access for SAN
+:FusionSAN: Fusion Access for SAN
 :delete: image:delete.png[title="Delete"]
 ifdef::openshift-origin[]
 :VirtProductName: OKD Virtualization

_topic_maps/_topic_map.yml

@@ -4700,6 +4700,13 @@ Topics:
     File: virt-configuring-higher-vm-workload-density
   - Name: Configuring certificate rotation
     File: virt-configuring-certificate-rotation
+- Name: Virtualization with IBM Fusion Access for SAN
+  Dir: fusion_access_SAN
+  Topics:
+  - Name: IBM Fusion Access for SAN overview
+    File: fusion-access-san-overview
+  - Name: Install and configure IBM Fusion Access for SAN
+    File: install-configure-fusion-access-san
 - Name: Updating
   Dir: updating
   Topics:

modules/virt-about-fusion-access-san.adoc

@@ -0,0 +1,28 @@
+// Module included in the following assemblies:
+//
+// * virt/fusion_access_SAN/about-fusion-access-san.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="about-fusion-access-san_{context}"]
+= About {IBMFusionFirst}
+
+{IBMFusionFirst} is a solution that provides a scalable clustered file system for enterprise storage, primarily designed to offer access to consolidated, block-level data storage. It presents storage devices, such as disk arrays, to the operating system as if they were direct-attached storage.
+
+This solution is particularly geared towards enterprise storage for Red Hat {VirtProductName} and leverages existing Storage Area Network (SAN) infrastructure. A SAN is a dedicated network of storage devices that is typically not accessible through the local area network (LAN).
+
+[id="why-use-fusion-san_{context}"]
+== Why use {FusionSAN}?
+
+Easy user experience:: {FusionSAN} features a wizard-driven user interface (UI) for installing and configuring storage clusters, file systems, and storage classes, to simplify the setup process.
+
+Leverage existing infrastructure:: Organizations can leverage their existing SAN investments, including Fibre Channel (FC) and iSCSI technologies, as they transition to or expand with {VirtProductName}.
+
+Scalability:: The storage cluster is designed to scale with {product-title} clusters and virtual machine (VM) workloads. It can support up to approximately 3000 VMs on 6 bare-metal hosts, with possibilities for further scaling by adding more file systems or using specific storage class parameters.
+
+Consolidated and shared storage:: SANs enable multiple servers to access a large, shared data storage capacity. This architecture facilitates automatic data backup and continuous monitoring of the storage and backup processes.
+
+High-speed data transfer:: By using a dedicated high-speed network for storage, {FusionSAN} overcomes the data transfer bottlenecks that can occur over a traditional LAN, especially for large volumes of data.
+
+File-level access:: Although a SAN primarily operates at the block level, file systems built on top of SAN storage can provide file-level access through shared-disk file systems.
+
+Centralized management:: The underlying SAN software manages servers, storage devices, and the network to ensure that data moves directly between storage devices with minimal server intervention. It also supports centralized management and configuration of SAN components like Logical Unit Numbers (LUNs).

modules/virt-creating-filesystem-fusion-access-san.adoc

@@ -0,0 +1,68 @@
+// Module included in the following assemblies:
+//
+// * virt/fusion_access_SAN/install-configure-fusion-access-san.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="creating-filesystem-fusion-access-san_{context}"]
+= Creating a file system with {FusionSAN}
+
+You need to create a file system to represent your required storage.
+
+The file system is based on the storage available in the worker nodes you selected when creating the storage cluster.
+
+.Prerequisites
+
+* You created a {FusionSAN} storage cluster.
+
+.Procedure
+
+. In the {product-title} web console, navigate to *Storage* -> *{FusionSAN}*.
+
+. In the *File systems* tab, click *Create file system*.
+
+. Enter a *Name* for the new file system.
+
+. Select the LUNs that you want to use as the storage volumes for your file system.
+
+. Click *Create file system*. 
++
+The *{FusionSAN}* page reloads, and the new file system appears in the *File systems* tab.
+
+.Next steps
+
+Repeat this procedure for each file system that you want to create.
+
+.Verification
+
+. Watch the *Status* of the file system in the *File systems* tab until it is marked as *Healthy*.
++
+[NOTE]
+====
+This may take several minutes.
+====
+
+. Click on the *StorageClass* for the file system.
+
+. In the *YAML* tab, verify the following:
++
+.. The value in the `name` field is the name of the file system you created.
+.. The value in the `provisioner` field is `spectrumscale.csi.ibm.com`.
+.. The value in the `volBackendFs` field matches the name of the file system you created.
++
+[source,yaml,subs="attributes+"]
+----
+kind: StorageClass
+apiVersion: storage.k8s.io/v1
+metadata:
+  name: filesystem1
+  uid: eb410309-a043-a89b-9bb05483872a
+  resourceVersion: '87746'
+  creationTimestamp: '2025-05-14T12:30:08Z'
+  managedFields:
+provisioner: spectrumscale.csi.ibm.com
+parameters:
+  volBackendFs: filesystem1
+reclaimPolicy: Delete
+allowVolumeExpansion: true
+volumeBindingMode: Immediate
+----

modules/virt-creating-fusionaccess-cr.adoc

@@ -0,0 +1,41 @@
+// Module included in the following assemblies:
+//
+// * virt/fusion_access_SAN/install-configure-fusion-access-san.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="creating-fusionaccess-cr_{context}"]
+= Creating the FusionAccess CR
+
+After installing the {FusionSAN} Operator and creating a Kubernetes pull secret, you must create the `FusionAccess` custome resource (CR).
+
+Creating the `FusionAccess` CR triggers the installation of the correct version of IBM Storage Scale and detects worker nodes with shared LUNs.
+
+.Prerequisites
+
+* You have access to the cluster as a user with the `cluster-admin` role.
+* You installed the {FusionSAN} Operator.
+* You created a Kubernetes pull secret.
+
+.Procedure
+
+. In the {product-title} web console, navigate to *Operators* -> *Installed Operators*.
+
+. Click on the {FusionSAN} Operator you installed.
+
+. In the *Fusion Access for SAN* page, select the *Fusion Access* tab.
+
+. Click *Create FusionAccess*.
+
+. On the *Create FusionAccess* page, enter the object *Name*.
+
+. Optional: You can choose to add *Labels* if they are relevant.
+
+. Select the *IBM Storage Scale Version* from the drop-down list.
++
+This version is the same version that was used to install the {FusionSAN} Operator.
+
+. Click *Create*.
+
+.Verification
+
+* In the *Fusion Access for SAN* Operator page, in the *Fusion Access* tab, verify that the created `FusionAccess` CR appears with the status *Ready*.

modules/virt-creating-pull-secret-fusion-san.adoc

@@ -0,0 +1,42 @@
+// Module included in the following assemblies:
+//
+// * virt/fusion_access_SAN/install-configure-fusion-access-san.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="creating-pull-secret-fusion-san_{context}"]
+= Creating a Kubernetes pull secret
+
+After installing the {FusionSAN} Operator, you must create a Kubernetes secret object to hold the IBM entitlement key for pulling the required container images from the IBM container registry.
+
+.Prerequisites
+
+* You installed the `oc` CLI.
+* You have access to the cluster as a user with the `cluster-admin` role.
+* You installed the {FusionSAN} Operator and created the `ibm-fusion-access` namespace in the process.
+
+.Procedure
+
+. Log in to the https://myibm.ibm.com/products-services/containerlibrary[*IBM Container software library*] with your {FusionSAN} *IBMid* and *password*.
+
+. In the *IBM Container software library*, get the entitlement key:
+
+.. If you do not have an entitlement key yet, click *Get entitlement key* or *Add new key*, and then click *Copy*.
+
+.. If you already have an entitlement key, click *Copy*.
+
+. Save the entitlement key in a safe place.
+
+. Create the secret object by running the `oc create` command:
++
+[source,terminal]
+----
+$ oc create secret -n ibm-fusion-access generic fusion-pullsecret \
+--from-literal=ibm-entitlement-key=<ibm-entitlement-key> <1>
+----
+<1> This is the entitlement key you copied in step 2 from the *IBM Container software library*.
+
+.Verification
+
+. In the {product-title} web console, navigate to *Workloads* -> *Secrets*.
+
+. Find the `fusion-pullsecret` in the list.

modules/virt-creating-storage-cluster-fusion-access-san.adoc

@@ -0,0 +1,36 @@
+// Module included in the following assemblies:
+//
+// * virt/fusion_access_SAN/install-configure-fusion-access-san.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="creating-storage-cluster-fusion-access-san_{context}"]
+= Creating a storage cluster with {FusionSAN}
+
+Once you have installed the {FusionSAN} Operator, you can create a storage cluster with shared storage nodes.
+
+The wizard for creating the storage cluster in the {product-title} web console provides easy-to-follow steps and lists the relevant worker nodes with shared disks.
+
+.Prerequisites
+
+* You have bare-metal worker nodes with visible and attached shared LUNs.
++
+A shared LUN is a shared disk that is accessed by all workers simultaneously.
+* You installed the {FusionSAN} Operator.
+* You created the `FusionAccess` custom resource (CR) in the `ibm-fusion-access` namespace.
+
+.Procedure
+
+. In the {product-title} web console, navigate to *Storage* -> *{FusionSAN}*.
+
+. Click *Create storage cluster*.
+
+. Select the worker nodes that have shared LUNs.
++
+[NOTE]
+====
+You can only select worker nodes with a minimum of 20 GB of RAM from the list.
+====
+
+. Click *Create storage cluster*.
++
+The page reloads, opening the {FusionSAN} page for the new storage cluster.

modules/virt-fusion-access-san-prereqs.adoc

@@ -0,0 +1,23 @@
+// Module included in the following assemblies:
+//
+// * virt/fusion_access_SAN/about-fusion-access-san.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="fusion-access-san-prereqs_{context}"]
+= Prerequisites and Limitations for {FusionSAN}
+
+== Prerequisites
+
+Installing and configuring {FusionSAN} require the following prerequisites:
+
+* Bare-metal worker nodes with attached SAN storage.
+* A working container registry enabled.
+* All worker nodes must connect to the same LUNs.
++
+A shared LUN is a shared disk that is accessed by all worker nodes simultaneously.
+* A Kubernetes pull secret.
+
+== Limitations
+
+* Limitations for {FusionSAN} rely on the IBM Storage Scale container native limitations and can be found in the documentation for https://www.ibm.com/docs/en/scalecontainernative/5.2.3?topic=overview-limitations[IBM Storage Scale container native].
+* Hosted control planes (HCP) clusters are not supported.

modules/virt-installing-fusion-access-operator.adoc

@@ -0,0 +1,47 @@
+// Module included in the following assemblies:
+//
+// * virt/fusion_access_SAN/install-configure-fusion-access-san.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="installing-fusion-access-operator_{context}"]
+= Installing the {FusionSAN} Operator
+
+Install the {FusionSAN} Operator from the *OperatorHub* in the {product-title} web console.
+
+.Prerequisites
+
+* You have access to the cluster as a user with the `cluster-admin` role.
+* You have a working container registry enabled.
+
+.Procedure
+
+. In the {product-title} web console, navigate to *Operators* -> *OperatorHub*.
+
+. In the *Filter by keyword* field, type `Fusion Access for SAN`.
+
+. Select the *{FusionSAN}* tile and click *Install*.
+
+. On the *Install Operator* page, keep the default selections for *Update Channel*, *Version*, and *Installation mode*.
+
+. Verify that *Operator recommended Namespace* is selected for *Installed Namespace*. 
++
+This installs the Operator in the `ibm-fusion-access` namespace. If this namespace does not yet exist, it is automatically created.
++
+[WARNING]
+====
+If you install the {FusionSAN} Operator in a namespace other than `ibm-fusion-access`, {FusionSan} does not work.
+====
+
+. Verify that the *Automatic* default is selected for *Update Approval*.
++
+This enables automatic updates when a new z-stream release is available.
+
+. Click *Install*.
++
+This installs the Operator.
+
+.Verification
+
+. Navigate to *Operators* -> *Installed Operators*.
+
+. Verify that the {FusionSAN} Operator is displayed.

virt/fusion_access_SAN/_attributes

@@ -0,0 +1 @@
+../../_attributes/

virt/fusion_access_SAN/fusion-access-san-overview.adoc

@@ -0,0 +1,13 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="fusion-access-san-overview"]
+= {IBMFusionFirst} overview
+
+include::_attributes/common-attributes.adoc[]
+:context: fusion-access-san-overview
+
+toc::[]
+
+include::modules/virt-about-fusion-access-san.adoc[leveloffset=+1]
+
+include::modules/virt-fusion-access-san-prereqs.adoc[leveloffset=+1]
+

virt/fusion_access_SAN/images

@@ -0,0 +1 @@
+../../images/

virt/fusion_access_SAN/install-configure-fusion-access-san.adoc

@@ -0,0 +1,35 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="install-configure-fusion-access-san"]
+= Installing and configuring {IBMFusionFirst}
+
+include::_attributes/common-attributes.adoc[]
+:context: install-configure-fusion-access-san
+
+toc::[]
+
+To use Red Hat {VirtProductName} with {IBMFusionFirst}, you must first install the {FusionSAN} Operator.
+
+Then you must create a Kubernetes pull secret and create the FusionAccess custom resource (CR).
+
+Finally, follow the Red Hat {product-title} web console wizard to configure the storage cluster, local disk, and file systems.
+
+include::modules/virt-installing-fusion-access-operator.adoc[leveloffset=+1]
+
+include::modules/virt-creating-pull-secret-fusion-san.adoc[leveloffset=+1]
+
+include::modules/virt-creating-fusionaccess-cr.adoc[leveloffset=+1]
+
+include::modules/virt-creating-storage-cluster-fusion-access-san.adoc[leveloffset=+1]
+
+include::modules/virt-creating-filesystem-fusion-access-san.adoc[leveloffset=+1]
+
+[id="fusion-san-next-steps_{context}"]
+== Next steps
+
+Once you create a storage cluster with file systems, you can create a virtual machine (VM) on the storage cluster.
+
+Create a VM from an instance type or template and select one of the file systems you created as the storage type.
+
+* xref:../../virt/creating_vm/virt-creating-vms-from-instance-types.adoc#virt-creating-vms-from-instance-types[Creating virtual machines from instance types].
+
+* xref:../../virt/creating_vm/virt-creating-vms-from-templates.adoc#virt-creating-vms-from-templates[Creating virtual machines from templates].

virt/fusion_access_SAN/modules

@@ -0,0 +1 @@
+../../modules/

virt/fusion_access_SAN/snippets

@@ -0,0 +1 @@
+../../snippets/