RHOAI-30438 custom workbench namespace (#897)

* RHOAI-30438 custom workbench namespace

* coderabbit comments

* peer review edits

* missed a configuration spot

Author: aduquett

_artifacts/document-attributes-global.adoc

@@ -11,6 +11,11 @@ ifdef::cloud-service[]
 :install-package: Add-on
 :openshift-platform: OpenShift
 :dbd-config-default-namespace: redhat-ods-applications
+:operator-default-namespace: redhat-ods-operator
+:workbench-default-namespace: rhods-notebooks
+:authorino-default-namespace: redhat-ods-applications-auth-provider
+:mr-default-namespace: rhoai-model-registries
+:monitoring-default-namespace: redhat-ods-monitoring
 endif::[]
 
 // conditional entities for RHOAI-SM
@@ -25,13 +30,20 @@ ifdef::self-managed[]
 :openshift-platform: OpenShift Container Platform
 :openshift-platform-url: openshift-container-platform
 :dbd-config-default-namespace: redhat-ods-applications
+:operator-default-namespace: redhat-ods-operator
+:workbench-default-namespace: rhods-notebooks
+:authorino-default-namespace: redhat-ods-applications-auth-provider
+:mr-default-namespace: rhoai-model-registries
+:monitoring-default-namespace: redhat-ods-monitoring
 endif::[]
 
 ifdef::upstream[]
 :productname-long: Open Data Hub
 :productname-short: Open Data Hub
 :odh-user-group: pass:q,a[`odh-users`]
 :odh-admin-group: pass:q,a[`odh-admins`]
+:user-group: pass:q,a[`odh-users`]
+:admin-group: pass:q,a[`odh-admins`]
 :url-productname-long: open_data_hub
 :url-productname-short: open_data_hub
 // change this to match the stage-<ver> branch, e.g. 1-latest, 1.n, to get the correct title for release notes
@@ -41,11 +53,18 @@ ifdef::upstream[]
 :openshift-platform-url: openshift-container-platform
 :odhdocshome: https://opendatahub.io/docs
 :dbd-config-default-namespace: opendatahub
+:operator-default-namespace: openshift-operators
+:workbench-default-namespace: opendatahub
+:authorino-default-namespace: opendatahub-auth-provider
+:mr-default-namespace: odh-model-registries
+:monitoring-default-namespace: opendatahub
 endif::[]
 
 ifndef::upstream[]
 :oai-user-group: pass:q,a[`rhoai-users`]
 :oai-admin-group: pass:q,a[`rhoai-admins`]
+:user-group: pass:q,a[`rhoai-users`]
+:admin-group: pass:q,a[`rhoai-admins`]
 endif::[]
 
 // conditional entities for release note titles using numbers or not

installing-open-data-hub.adoc

@@ -18,7 +18,7 @@ include::_artifacts/document-attributes-global.adoc[]
 
 include::assemblies/installing-odh-v2.adoc[leveloffset=+1]
 
-include::assemblies/installing-odh-v1.adoc[leveloffset=+1]
+//include::assemblies/installing-odh-v1.adoc[leveloffset=+1]
 
 include::modules/installing-the-distributed-workloads-components.adoc[leveloffset=+1]
 

modules/about-deleting-users-and-resources.adoc

@@ -3,15 +3,13 @@
 [id='about-deleting-users-and-resources_{context}']
 = About deleting users and their resources
 
-If you have administrator access to {openshift-platform}, you can revoke a user's access to Jupyter and delete the user's resources from {productname-long}.
+If you have administrator access to {openshift-platform}, you can revoke a user's access to workbenches and delete the user's resources from {productname-long}. Before you delete a user from {productname-short}, it is good practice to back up the data on your persistent volume claims (PVCs). 
 
 Deleting a user and the user's resources involves the following tasks:
 
-* Before you delete a user from {productname-short}, it is good practice to back up the data on your persistent volume claims (PVCs). 
-
 * Stop workbenches owned by the user.
 
-* Revoke user access to Jupyter.
+* Revoke user access to workbenches.
 
 * Remove the user from the allowed group in your OpenShift identity provider.
 

modules/accessing-the-administration-interface-for-basic-workbenches.adoc

@@ -11,18 +11,22 @@ You can use the administration interface to control basic workbenches in your {p
 * You have logged in to {productname-short} as a user with {productname-short} administrator privileges. 
 
 .Procedure
-** To access the administration interface for basic workbenches from {productname-short}, perform the following actions:
-... In {productname-short}, in the *Applications* section of the left menu, click *Enabled*.
-... Locate the *Start basic workbench* tile and click *Launch application*.
-... On the page that opens when you launch a basic workbench, click the *Administration* tab.
+To access the administration interface for basic workbenches from {productname-short}, perform the following actions:
+
+. In {productname-short}, in the *Applications* section of the left menu, click *Enabled*.
+. Locate the *Start basic workbench* tile and click *Open application*.
+. On the page that opens, click the *Administration* tab.
 +
 The *Administration* page opens.
 
+////
+Removing until RHOAIENG-31369 is resolved
 ** To access the administration interface for basic workbenches from JupyterLab, perform the following actions:
 ... Click *File* -> *Hub Control Panel*.
 ... On the page that opens in {productname-short}, click the *Administration* tab. 
 +
 The *Administration* page opens.
+////
 
 .Verification
 

modules/accessing-the-odh-dashboard.adoc

@@ -4,19 +4,18 @@
 = Accessing the Open Data Hub dashboard
 
 [role='_abstract']
-You can access and share the URL for your Open Data Hub dashboard with other users to let them log in and work on their models.
+After you have installed {productname-short}, you can access and share the URL for your {productname-short} dashboard with other users to let them log in and work on their models.
 
 .Prerequisites
-* You have installed the Open Data Hub Operator.
+* You have installed the {productname-short} Operator.
 
 .Procedure
-. In the OpenShift web console, select *Networking* -> *Routes*.
-. On the *Routes* page, click the *Project* list and select the `odh` project. The page filters to only display routes in the `odh` project.
-. In the *Location* column, copy the URL for the *odh-dashboard* route.
-. Give this URL to your users to let them log in to Open Data Hub dashboard.
+. Log in to {openshift-platform} web console.
+. Click the application launcher (image:images/osd-app-launcher.png[The application launcher]).
+. Right-click *{productname-long}* and copy the URL for your {productname-short} instance.
+. Give this URL to your users to let them log in to {productname-short} dashboard.
 
 .Verification
-* Confirm that you and your users can log in to the Open Data Hub dashboard by using the URL.
-
-*Note:* In the {productname-long} dashboard, users can view the list of the installed {productname-short} components, their corresponding source (upstream) components, and the versions of the installed components, as described in link:{odhdocshome}/installing-open-data-hub/#viewing-installed-components_get-started[Viewing installed {productname-short} components].
+* Confirm that you and your users can log in to the {productname-short} dashboard by using the URL.
 
+*Note:* In the {productname-long} dashboard, users can view the list of the installed {productname-short} components, their corresponding source (upstream) components, and the versions of the installed components, as described in link:{odhdocshome}/installing-open-data-hub/#viewing-installed-components_get-started[Viewing installed {productname-short} components].

modules/cleaning-up-after-deleting-users.adoc

@@ -4,35 +4,30 @@
 = Cleaning up after deleting users
 
 [role='_abstract']
-ifdef::upstream,self-managed[]
-After you remove a user's access to {productname-long} or Jupyter, you must also delete the configuration files for the user from {openshift-platform}.
-endif::[]
-ifdef::cloud-service[]
-After you remove a user's access to {productname-long} or Jupyter, you must also delete the configuration files for the user from OpenShift.
-endif::[]
+After you remove a user's access to {productname-long}, you must also delete the configuration files for the user from {openshift-platform}.
 {org-name} recommends that you back up the user's data before removing their configuration files.
 
 .Prerequisites
 
 * (Optional) If you want to completely remove the user's access to {productname-short}, you have removed their credentials from your identity provider.
-* You have revoked the user's access to Jupyter.
-
 ifdef::cloud-service[]
 * You have backed up the user's storage data from Amazon EBS or Google Persistent Disk.
 endif::[]
-
 ifdef::self-managed[]
 * You have backed up the user's storage data.
 endif::[]
-
 * You have logged in to the {openshift-platform} web console as a user with the `cluster-admin` role.
 
-//* You have logged in to {productname-short} as a user with {productname-short} administrator privileges.
-
 .Procedure
+
 . Delete the user's persistent volume claim (PVC).
 .. Click *Storage* -> *PersistentVolumeClaims*.
-.. If it is not already selected, select the `rhods-notebooks` project from the project list.
+ifdef::cloud-service[]
+.. If it is not already selected, select the `pass:attributes[{workbench-default-namespace}]` project from the project list.
+endif::[]
+ifdef::self-managed,upstream[]
+.. If it is not already selected, select the default workbench project (`pass:attributes[{workbench-default-namespace}]` or your custom workbench namespace) from the project list.
+endif::[]
 .. Locate the  `jupyter-nb-<username>` PVC.
 +
 Replace `<username>` with the relevant user name.
@@ -43,7 +38,12 @@ The *Delete PersistentVolumeClaim* dialog appears.
 .. Click *Delete*.
 . Delete the user's ConfigMap.
 .. Click *Workloads* -> *ConfigMaps*.
-.. If it is not already selected, select the `rhods-notebooks` project from the project list.
+ifdef::cloud-service[]
+.. If it is not already selected, select the `pass:attributes[{workbench-default-namespace}]` project from the project list.
+endif::[]
+ifdef::self-managed,upstream[]
+.. If it is not already selected, select the default workbench project (`pass:attributes[{workbench-default-namespace}]` or your custom workbench namespace) from the project list.
+endif::[]
 .. Locate the `jupyterhub-singleuser-profile-<username>` ConfigMap.
 +
 Replace `<username>` with the relevant user name.
@@ -54,8 +54,6 @@ The *Delete ConfigMap* dialog appears.
 .. Click *Delete*.
 
 .Verification
-// TODO: When RHOAIENG-1137 is corrected, change to:
-//* The user is not visible in the administration interface for basic workbenches.
-* The user cannot access Jupyter any more, and sees an "Access permission needed" message if they try. 
+* The user cannot access {productname-short} and sees an "Access permission needed" message if they try. 
 * The user's single-user profile, persistent volume claim (PVC), and ConfigMap are not visible in {openshift-platform}.
 

modules/configuring-custom-namespaces.adoc

@@ -4,30 +4,75 @@
 = Configuring custom namespaces
 
 [role='_abstract']
-By default, {productname-short} uses predefined namespaces, but you can define a custom namespace for the operator and `DSCI.applicationNamespace` as needed. Namespaces created by {productname-short} typically include `openshift` or `redhat` in their name. Do not rename these system namespaces because they are required for {productname-short} to function properly.
+
+By default, {productname-short} uses the following predefined namespaces:
+
+* `pass:attributes[{operator-default-namespace}]` contains the {productname-long} Operator
+* `pass:attributes[{dbd-config-default-namespace}]` includes the dashboard and other required components of {productname-short}
+* `pass:attributes[{workbench-default-namespace}]` is where basic workbenches are deployed by default
+//* `pass:attributes[{monitoring-default-namespace}]` contains services for monitoring
+
+If needed, you can define custom namespaces to use instead of the predefined ones before installing {productname-short}. This flexibility supports environments with naming policies or conventions and allows cluster administrators to control where components such as workbenches are deployed.
+
+ifndef::upstream[]
+Namespaces created by {productname-short} typically include `openshift` or `redhat` in their name. Do not rename these system namespaces because they are required for {productname-short} to function properly.
+endif::[]
+ifdef::upstream[]
+Namespaces created by {productname-short} typically include `openshift` or `opendatahub` in their name. Do not rename these system namespaces because they are required for {productname-short} to function properly.
+endif::[]
 
 .Prerequisites
+
 * You have access to an {productname-short} cluster with cluster administrator privileges.
 * You have downloaded and installed the OpenShift command-line interface (CLI). See link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-latest-version}/html/cli_tools/openshift-cli-oc#installing-openshift-cli[Installing the OpenShift CLI^].
+* You have not yet installed the {productname-long} Operator.
 
 .Procedure
+
 . In a terminal window, if you are not already logged in to your OpenShift cluster as a cluster administrator, log in to the OpenShift CLI as shown in the following example:
 +
 [source,subs="+quotes"]
 ----
 oc login __<openshift_cluster_url>__ -u __<admin_username>__ -p __<password>__
 ----
-. Enter the following command to create the custom namespace:
+
+. Optional: To configure a custom operator namespace:
+
+.. Create a new namespace:
 +
 [source]
 ----
-oc create namespace <custom_namespace>
+oc create namespace <operator_namespace>
 ----
-. If you are creating a namespace for a `DSCI.applicationNamespace`, enter the following command to add the correct label:
+
+.. When you install the {productname-long} Operator, use this namespace instead of `pass:attributes[{operator-default-namespace}]`.
+
+. Optional: To configure a custom applications namespace: 
+
+.. Create the namespace:
++
+[source]
+----
+oc create namespace <application_namespace>
+----
+
+.. Add the required label:
 +
 [source]
 ----
 oc label namespace <application_namespace> opendatahub.io/application-namespace=true
 ----
 
-//.Additional information
+. Optional: To configure a custom workbench namespace: 
+
+.. Create the namespace:
++
+[source]
+----
+oc create namespace <workbench_namespace>
+----
+
+.. When you install the {productname-long} components, specify this namespace for the `spec.workbenches.workbenchNamespace` field. You cannot change the default workbench namespace after you have installed the {productname-long} Operator.
+
+.Next step
+* Install the {productname-long} Operator.

modules/installing-odh-components.adoc

@@ -4,10 +4,10 @@
 = Installing Open Data Hub components
 
 [role='_abstract']
-You can use the OpenShift web console to install specific components of Open Data Hub on your cluster when version 2 of the Open Data Hub Operator is already installed on the cluster.
+You can use the OpenShift web console to install specific components of Open Data Hub on your cluster when the Open Data Hub Operator is already installed on the cluster.
 
 .Prerequisites
-* You have installed version 2 of the Open Data Hub Operator.
+* You have installed the Open Data Hub Operator.
 * You can log in as a user with `cluster-admin` privileges.
 ifdef::upstream[]
 * If you want to use the `trustyai` component, you must enable user workload monitoring as described in link:{odhdocshome}/monitoring-data-science-models/#configuring-monitoring-for-the-multi-model-serving-platform_monitor[Configuring monitoring for the multi-model serving platform].
@@ -47,8 +47,10 @@ endif::[]
 . On the *Create DSCInitialization* page, configure by using *Form* view or *YAML* view. For general information about the supported components, see link:https://opendatahub.io/docs/tiered-components[Tiered Components].
 * Configure by using *Form* view:
 .. In the *Name* field, enter a value.
+.. If you are using a custom applications namespace, enter the namespace in the *Applications Namespace* field.
 .. In the *Components* section, expand each component and set the *managementState* to *Managed* or *Removed*.
 * Configure by using *YAML* view:
+.. If you are using a custom applications namespace, specify the namespace in the `spec.applicationsNamespace` field.
 .. In the `spec.components` section, for each component shown, set the value of the `managementState` field to either `Managed` or `Removed`.
 . Click *Create*.
 . Wait until the status of the DSCInitialization is *Ready*.
@@ -57,8 +59,10 @@ endif::[]
 * Configure by using *Form* view:
 .. In the *Name* field, enter a value.
 .. In the *Components* section, expand each component and set the *managementState* to *Managed* or *Removed*.
+.. If you are using a custom workbench namespace, enter the namespace in the *workbenchNamespace* field.
 * Configure by using *YAML* view:
 .. In the `spec.components` section, for each component shown, set the value of the `managementState` field to either `Managed` or `Removed`.
+.. If you are using a custom workbench namespace, specify the namespace in the `spec.workbenches.workbenchNamespace` field.
 . Click *Create*.
 
 
@@ -68,7 +72,7 @@ endif::[]
 
 *Note:* In the {productname-long} dashboard, users can view the list of the installed {productname-short} components, their corresponding source (upstream) components, and the versions of the installed components, as described in link:{odhdocshome}/installing-open-data-hub/#viewing-installed-components_get-started[Viewing installed {productname-short} components].
 
-.Next Step
+.Next step
 * link:{odhdocshome}/installing-open-data-hub/#accessing-the-odh-dashboard_installv2[Accessing the Open Data Hub dashboard].
 
 [role="_additional-resources"]

modules/installing-the-odh-operator-v2.adoc

@@ -42,7 +42,7 @@ Version 2 of the Open Data Hub Operator represents an alpha release, accessible
 --
 .. For *Version*, select the version of the Operator that you want to install. 
 .. For *Installation mode*, leave *All namespaces on the cluster (default)* selected.
-.. For *Installed Namespace*, select the *openshift-operators* namespace.
+.. For *Installed Namespace*, select the *{operator-default-namespace}* namespace or select your custom operator namespace.
 .. For *Update approval*, select automatic or manual updates. 
 * *Automatic*: When a new version of the Operator is available, Operator Lifecycle Manager (OLM) automatically upgrades the running instance of your Operator.
 * *Manual*: When a new version of the Operator is available, OLM notifies you with an update request that you must manually approve to upgrade the running instance of your Operator.
@@ -51,7 +51,7 @@ Version 2 of the Open Data Hub Operator represents an alpha release, accessible
 .Verification
 * Select *Operators* -> *Installed Operators* to verify that the *Open Data Hub Operator* is listed with *Succeeded* status.
 
-.Next Step
+.Next step
 * Install Open Data Hub components.
 
 [role="_additional-resources"]