TELCODOCS-2198 Docs update for OpenShift AI

Author: kquinn1204

content/patterns/openshift-ai/_index.adoc

@@ -28,5 +28,5 @@ include::modules/rhoai-architecture.adoc[leveloffset=+1]
 [id="next-steps_rhoai-index"]
 == Next steps
 
-* link:getting-started[Deploy the Pattern] using Helm.
+* link:getting-started[Deploy the Pattern].
 

modules/rhoai-deploying.adoc

@@ -8,130 +8,255 @@
 
 * An OpenShift cluster
  ** To create an OpenShift cluster, go to the https://console.redhat.com/[Red Hat Hybrid Cloud console].
- ** Select *Services \-> Containers \-> Create cluster*.
- ** The cluster must have a dynamic `StorageClass` to provision `PersistentVolumes`. See link:../../multicloud-gitops/mcg-cluster-sizing[sizing your cluster].
-* Optional: A second OpenShift cluster for multicloud demonstration.
-//Replaced git and podman prereqs with the tooling dependencies page
-* https://validatedpatterns.io/learn/quickstart/[Install the tooling dependencies].
-
-The use of this pattern depends on having at least one running Red Hat OpenShift cluster. However, consider creating a cluster for deploying the GitOps management hub assets and a separate cluster for the managed cluster.
+ ** Select *OpenShift \-> Red Hat OpenShift Container Platform \-> Create cluster*.
+ ** The cluster must have a dynamic `StorageClass` to provision `PersistentVolumes`. Verify that a dynamic `StorageClass` exists before creating one by running the following command: 
++
+[source,terminal]
+----
+$ oc get storageclass -o custom-columns=NAME:.metadata.name,PROVISIONER:.provisioner,DEFAULT:.metadata.annotations."storageclass\.kubernetes\.io/is-default-class"
+----
++
+.Example output
++
+[source,terminal]
+----
+NAME      PROVISIONER       DEFAULT
+gp2-csi   ebs.csi.aws.com   <none>
+gp3-csi   ebs.csi.aws.com   true
+----
++
+For more information about creating a dynamic `StorageClass`, see the https://docs.openshift.com/container-platform/latest/storage/dynamic-provisioning.html[Dynamic provisioning] documentation.
 
-If you do not have a running Red Hat OpenShift cluster, you can start one on a
-public or private cloud by using https://console.redhat.com/openshift/create[Red Hat Hybrid Cloud Console].
 
 .Procedure
 
-. Fork the https://github.com/validatedpatterns-sandbox/openshift-ai[openshift-ai] repository on GitHub.
-. Clone the forked copy of this repository.
-+
-[source,terminal]
-----
-git clone [email protected]:your-username/openshift-ai.git
-----
-
-//. Create a local copy of the secret values file that can safely include credentials. Run the following commands:
-//+
-//[source,terminal]
-//----
-//cp values-secret.yaml.template ~/values-secret-travelops.yaml
-//----
-//+
-//[source,yaml]
-//----
-//version: "2.0"
-//# Ideally you NEVER COMMIT THESE VALUES TO GIT (although if all passwords are
-//# automatically generated inside the vault this should not really matter)
-//
-//secrets:
-//  - name: mysql-credentials
-//    vaultPrefixes:
-//    - global
-//    fields:
-//    - name: rootpasswd
-//      onMissingValue: generate
-//      vaultPolicy: validatedPatternDefaultPolicy
-//
-//# Uncomment the following if you want to enable HTPasswd oAuth 
-//#  - name: htpasswd
-//#    vaultPrefixes:
-//#    - global
-//#    fields:
-//#    - name: htpasswd
-//#      path: '/path/to/users.htpasswd'
-//----
-//+
-//[WARNING]
-//====
-//Do not commit this file. You do not want to push personal credentials to GitHub. If you do not want to customize the secrets, these steps are not needed. The framework generates a random password for the config-demo application.
-//====
-//
-. If you want a peak under the covers to see what the pattern contains, you can do so with the following command:
-+
-[source,terminal]
-----
-cat values-hub.yaml
-----
-
-But don't worry if it looks intimidating.
-
-. Deploy the pattern by running `./pattern.sh make install` or by using the link:/infrastructure/using-validated-pattern-operator/[Validated Patterns Operator].
+. From the https://github.com/validatedpatterns-sandbox/openshift-ai[openshift-ai] repository on GitHub click the Fork button.
 
-[id="deploying-cluster-using-patternsh-file"]
-== Deploying the cluster by using the pattern.sh file
+. Clone the forked copy of this repository by running the following command.
++
+[source,terminal]
+----
+$ git clone [email protected]:<your-username>/openshift-ai.git
+----
 
-To deploy the cluster by using the `pattern.sh` file, complete the following steps:
+. Navigate to your repository: Ensure you are in the root directory of your Git repository by using:
++
+[source,terminal]
+----
+$ cd /path/to/your/repository 
+----
+
+. Run the following command to set the upstream repository:
++
+[source,terminal]
+----
+$ git remote add -f upstream [email protected]:validatedpatterns-sandbox/openshift-ai.git 
+----
 
-. Login to your cluster by running the following command:
+. Verify the setup of your remote repositories by running the following command:
 +
 [source,terminal]
 ----
- oc login
+$ git remote -v
 ----
 +
-Optional: Set the `KUBECONFIG` variable for the `kubeconfig` file path:
+.Example output
 +
 [source,terminal]
 ----
- export KUBECONFIG=~/<path_to_kubeconfig>
+origin	[email protected]:<your-username>/openshift-ai.git (fetch)
+origin	[email protected]:<your-username>/openshift-ai.git (push)
+upstream	[email protected]:validatedpatterns-sandbox/openshift-ai.git (fetch)
+upstream	[email protected]:validatedpatterns-sandbox/openshift-ai.git (push)
 ----
 
-. Deploy the pattern to your cluster. Run the following command:
+. Create a local copy of the secret values file that can safely include credentials. Run the following commands:
 +
 [source,terminal]
 ----
- ./pattern.sh make install
+$ cp values-secret.yaml.template ~/values-secret-openshift-ai.yaml
 ----
++
+[NOTE]
+====
+Putting the `values-secret.yaml` in your home directory ensures that it does not get pushed to your git repository. It is based on the `values-secrets.yaml.template` file provided by the pattern in the top level directory. When you create your own patterns you will add your secrets to this file and save.
+====
 
-[id="verify-rhoai-pattern-install"]
-== Verify Red Hat OpenShift AI Pattern installation
+. Create a new feature branch, for example `my-branch` from the `rhoai` branch for your content:
++
+[source,terminal]
+----
+$ git checkout -b my-branch rhoai
+----
 
-. Verify that the Operators have been installed.
- .. To verify, in the OpenShift Container Platform web console, navigate to *Operators → Installed Operators* page.
- .. Set your project to `All Projects` and verify the operators are isntalled and have a status of `Succeeded`.
-. Verify that all applications are synchronized. Under the project `openshift-ai-hub` click the URL for the `hub` gitops `server`. 
+. Create a local branch and push it to origin to gain the flexibility needed to customize the OpenShift AI pattern by running the following command:
 +
-image::rhoai/rhods-sync-success.png[ArgoCD Applications,link="/images/rhoai/rhods-sync-success.png"]
+[source,terminal]
+----
+$ git push origin my-branch
+----
+
+You can proceed to install the OpenShift AI pattern by using the web console or from command line by using the script `./pattern.sh` script. 
+
+To install the OpenShift AI pattern by using the web console you must first install the Validated Patterns Operator. The Validated Patterns Operator installs and manages Validated Patterns. 
+
+//Include Procedure module here
+[id="installing-validated-patterns-operator_{context}"]
+== Installing the {validated-patterns-op} using the web console
+
+.Prerequisites
+* Access to an {ocp} cluster by using an account with `cluster-admin` permissions.
+
+.Procedure
 
+. Navigate in the {hybrid-console-first} to the *Operators* → *OperatorHub* page.
+
+. Scroll or type a keyword into the *Filter by keyword* box to find the Operator you want. For example, type `validated patterns` to find the {validated-patterns-op}.
+
+. Select the Operator to display additional information.
 +
-As part of this pattern, HashiCorp Vault has been installed. Refer to the section on https://validatedpatterns.io/secrets/vault/[Vault].
+[NOTE]
+====
+Choosing a Community Operator warns that Red Hat does not certify Community Operators; you must acknowledge the warning before continuing.
+====
 
+. Read the information about the Operator and click *Install*.
 
-[id="verify-rhoai-dashboards"]
-== Verify installation by checking the OpenShift AI Dashboard
+. On the *Install Operator* page:
+
+.. Select an *Update channel* (if more than one is available).
+
+.. Select a *Version* (if more than one is available).
+
+.. Select an *Installation mode*:
++
+The only supported mode for this Operator is *All namespaces on the cluster (default)*. This installs the Operator in the default `openshift-operators` namespace to watch and be made available to all namespaces in the cluster. This option is not always available.
+
+.. Select *Automatic* or *Manual* approval strategy.
+
+. Click *Install* to make the Operator available to the default `openshift-operators` namespace on this {ocp} cluster.
+
+.Verification
+To confirm that the installation is successful:
+
+. Navigate to the *Operators* → *Installed Operators* page.
+
+. Check that the Operator is installed in the selected namespace and its status is `Succeeded`.
+
+//Include Procedure module here
+[id="create-pattern-instance_{context}"]
+== Creating the OpenShift AI instance
 
-. Access the OpenShift AI dashboard
+.Prerequisites
+The {validated-patterns-op} is successfully installed in the relevant namespace.
+
+.Procedure
+
+. Navigate to the *Operators* → *Installed Operators* page.
 
+. Click the installed *{validated-patterns-op}*.
+
+. Under the *Details* tab, in the *Provided APIs* section, in the
+*Pattern* box, click *Create instance* that displays the *Create Pattern* page.
+
+. On the *Create Pattern* page, select *Form view* and enter information in the following fields:
+
+** *Name* - A name for the pattern deployment that is used in the projects that you created.
+** *Labels* - Apply any other labels you might need for deploying this pattern.
+** *Cluster Group Name* - Select a cluster group name to identify the type of cluster where this pattern is being deployed. For example, if you are deploying the {ie-pattern}, the cluster group name is `datacenter`. If you are deploying the {mcg-pattern}, the cluster group name is `hub`.
++
+To know the cluster group name for the patterns that you want to deploy, check the relevant pattern-specific requirements.
+. Expand the *Git Config* section to reveal the options and enter the required information.
+. Leave *In Cluster Git Server* unchanged. 
+.. Change the *Target Repo* URL to your forked repository URL. For example, change `https://github.com/validatedpatterns/<pattern_name>` to `https://github.com/<your-git-username>/<pattern-name>`
+.. Optional: You might need to change the *Target Revision* field. The default value is `HEAD`. However, you can also provide a value for a branch, tag, or commit that you want to deploy. For example, `v2.1`, `main`, or a branch that you created, `my-branch`.
+. Click *Create*.
 +
-[source, terminal]
+[NOTE]
+====
+A pop-up error with the message "Oh no! Something went wrong." might appear during the process. This error can be safely disregarded as it does not impact the installation of the OpenShift AI pattern. Use the Hub ArgoCD UI, accessible through the nines menu, to check the status of ArgoCD instances, which will display states such as progressing, healthy, and so on, for each managed application. The Cluster ArgoCD provides detailed status on each application, as defined in the clustergroup values file.
+====
+
+The *{rh-gitops} Operator* displays in list of *Installed Operators*. The *{rh-gitops} Operator* installs the remaining assets and artifacts for this pattern. To view the installation of these assets and artifacts, such as *{rh-rhacm-first}*, ensure that you switch to *Project:All Projects*.
+
+Wait some time for everything to deploy. You can track the progress through the `Hub ArgoCD` UI from the nines menu. The `config-demo` project  appears stuck in a `Degraded` state. This is the expected behavior when installing using the OpenShift Container Platform console.
+
+* To resolve this you need to run the following to load the secrets into the vault:
++
+[source,terminal]
 ----
-RHODS=https://$(oc get route -n redhat-ods-applications -o jsonpath='{.spec.host}')
-echo ${RHODS}
+$ ./pattern.sh make load-secrets
 ----
++
+[NOTE]
+====
+You must have created a local copy of the secret values file by running the following command:
 
-You can also get to the dashboard from the OpenShift Console by selecting the application shortcut icon and then selecting the link for Red Hat OpenShift Ai
+[source,terminal]
+----
+$ cp values-secret.yaml.template ~/values-secret-openshift-ai.yaml
+----
+====
 
-image:rhoai/rhods-application_menu.png[Application ShortCut,link="/images/rhoai/rhods-application_menu.png"]
+The deployment will not take long but it should deploy successfully.
+
+Alternatively you can deploy the OpenShift AI pattern by using the command line script `pattern.sh`. 
+
+[id="deploying-cluster-using-patternsh-file"]
+== Deploying the cluster by using the pattern.sh script
+
+To deploy the cluster by using the `pattern.sh` script, complete the following steps:
 
-Log in to the Dashboard using your OpenShift credentials. You will find an environment that is ready for further configuration. This pattern provides the fundamental platform pieces to support MLOps workflows. The installation of OpenShift Pipelines enables the immediate use of pipelines if that is the desired approach for deployment.
+. Navigate to the root directory of the cloned repository by running the following command:
++
+[source,terminal]
+----
+$ cd /path/to/your/repository
+----
 
-image:rhoai/rhods-ai_dashboard.png[OpenShift AI Dashboard,link="/images/rhoai/rhods-ai_dashboard.png"]
+. Log in to your cluster by running the following this procedure:
+
+.. Obtain an API token by visiting https://oauth-openshift.apps.<your-cluster>.<domain>/oauth/token/request
+
+.. Log in with this retrieved token by running the following command:
++
+[source,terminal]
+----
+$ oc login --token=<retrieved-token> --server=https://api.<your-cluster>.<domain>:6443
+----
+
+. Alternatively log in by running the following command: 
++
+[source,terminal]
+----
+$ export KUBECONFIG=~/<path_to_kubeconfig>
+----
+
+. Deploy the pattern to your cluster by running the following command:
++
+[source,terminal]
+----
+$ ./pattern.sh make install
+----
+
+. Verify that the Operators have been installed.
+ .. To verify, in the OpenShift Container Platform web console, navigate to *Operators → Installed Operators* page.
+ .. Check that *{rh-gitops} Operator* is installed in the `openshift-operators` namespace and its status is `Succeeded`.
+. Verify that all applications are synchronized. Under *Networking \-> Routes* select the *Location URL* associated with the *hub-gitops-server* . All application are report status as `Synched`. 
++
+image::rhoai/rhods-sync-success.png[ArgoCD Applications,link="/images/rhoai/rhods-sync-success.png"]
+
+As part of installing by using the script `pattern.sh` pattern, HashiCorp Vault is installed. Running `./pattern.sh make install` also calls the `load-secrets` makefile target. This `load-secrets` target looks for a YAML file describing the secrets to be loaded into vault and in case it cannot find one it will use the `values-secret.yaml.template` file in the git repository to try to generate random secrets.
+
+For more information, see section on https://validatedpatterns.io/secrets/vault/[Vault].
+
+[id="verify-rhoai-dashboards"]
+== Verify installation by checking the OpenShift AI Dashboard
+
+. Access the OpenShift AI dashboard from nines menu on the OpenShift Console and select the link for **Red Hat OpenShift AI**. 
++
+image:rhoai/rhods-application_menu.png[Application ShortCut,link="/images/rhoai/rhods-application_menu.png"]
+
+. Log in to the dashboard using your OpenShift credentials. You will find an environment that is ready for further configuration. This pattern provides the fundamental platform pieces to support MLOps workflows. The installation of OpenShift Pipelines enables the immediate use of pipelines if that is the desired approach for deployment.
++
+image:rhoai/rhods-ai_dashboard.png[OpenShift AI Dashboard,link="/images/rhoai/hods-ai_dashboard.png"]