Dashboard URLs return 404 errors after RHOAI upgrade from 2.x to 3.x

Environment

Red Hat OpenShift AI

• 3.0
• 3.3

Red Hat OpenShift Container Platform

• 4.19
• 4.20
• 4.21

Issue

After upgrading Red Hat OpenShift AI from version 2.x to 3.x, the dashboard is no longer accessible through previously bookmarked URLs. You might observe the following symptoms:

• Accessing saved dashboard URLs returns HTTP 404 Not Found error or "Application is not available" messages.
• The rhods-dashboard route no longer exists.
• Documentation and training materials with previously distributed dashboard links no longer function.
• Users cannot access the dashboard using previously bookmarked links.

Resolution

IMPORTANT: This solution is only applicable to Red Hat OpenShift AI versions 3.0 and 3.3. For version 3.4ea1 or later, this redirect solution is not required.

To resolve this issue, deploy an nginx-based redirect solution that recreates the old route name and redirects traffic to the new gateway URL.

Prerequisites

• Cluster administrator access
• The OpenShift oc CLI tool installed and configured
• Python 3.6 or later
• An active Red Hat OpenShift AI installation

Solution Steps

1. Download the redirect generator script

   Download dashboard-redirect-solution.zip from the Attachments section and extract it:

   unzip dashboard-redirect-solution.zip
   

   This extracts:

   • generate-dashboard-redirect.py - Script to auto-generate redirect configuration
   • dashboard-redirect.yaml.template - YAML template for redirect infrastructure

2. Make the script executable

   Update the script to allow execution:

   chmod +x generate-dashboard-redirect.py
   

3. Generate the redirect manifest

   Run the script to auto-discover the cluster configuration and generate the redirect manifest:

   ./generate-dashboard-redirect.py
   

   This command performs the following actions:

   • Detects the Red Hat OpenShift AI installation
   • Discovers the new data-science-gateway URL automatically
   • Determines the correct namespace for deployment
   • Generates a dashboard-redirect.yaml manifest file

4. Review the generated manifest

   Verify the dashboard-redirect.yaml file contains the following information:

   • Correct redirect URL pointing to the gateway
   • Expected legacy route hostname
   • Correct namespace for deployment

5. Deploy the redirect infrastructure

   Apply the generated manifest to the cluster:

   oc apply -f dashboard-redirect.yaml
   

   This creates the following resources:

   • ConfigMap with nginx redirect configuration
   • Pod running nginx
   • Service routing traffic to the nginx pod
   • Route recreating the legacy dashboard route name

6. Verify the redirect works

   Test that the legacy URL redirects correctly to the new gateway:

       # Get the legacy route URL
       LEGACY_URL=$(oc get route rhods-dashboard -n redhat-ods-applications -o jsonpath='{.spec.host}')
   
       # Test the redirect (should return HTTP 301)
       curl -Ik "https://${LEGACY_URL}"
   

   Expected output:

   HTTP/1.1 301 Moved Permanently
   Location: https://<new-gateway-url>
   

Advanced Configuration (Optional)

You can override the auto-discovered settings of the dashboard redirect script by using command-line arguments

• Override redirect destination URL:

  ./generate-dashboard-redirect.py --redirect-url https://custom-gateway.apps.example.com
  

• Override route hostname:

  ./generate-dashboard-redirect.py --route-host custom-dashboard.apps.example.com
  

Disconnected Environment Considerations

In air-gapped or disconnected OpenShift clusters, the generated manifest references an nginx image that is not automatically mirrored. You must mirror the image to your internal registry and edit the manifest before deployment.

1. Mirror the nginx image to your internal registry

   The generated manifest uses registry.redhat.io/ubi9/nginx-126:latest.

   a. Find the current image digest:

   skopeo inspect docker://registry.redhat.io/ubi9/nginx-126:latest | grep Digest
   

   Example output:

   Digest: sha256:abc123def456...
   

   b. Mirror the image to your internal registry:

   skopeo copy \
     docker://registry.redhat.io/ubi9/nginx-126:latest \
     docker://<your-internal-registry>/ubi9/nginx-126:latest
   

   NOTE: Replace <your-internal-registry> with your actual registry URL (e.g., mirror.registry.corp.example.com:5000).

2. Prepare the environment for the dashboard redirect script

   Complete steps 1-3 from the main Solution Steps to download, extract, make executable, and generate the redirect manifest.

3. Edit the generated manifest to use your mirrored image

   a. Open the dashboard-redirect.yaml file and locate the image field in the Pod containers section. Update the image field to point to your internal registry.

   Before (generated):

   spec:
     containers:
     - name: nginx
       image: registry.redhat.io/ubi9/nginx-126:latest
   

   After (edited for disconnected):

   spec:
     containers:
     - name: nginx
       image: <your-internal-registry>/ubi9/nginx-126@sha256:<digest>
   

   b. Replace <your-internal-registry> with your registry URL and <digest> with the SHA256 digest from step 1.

   Important: Use digest-based references (@sha256:...) rather than tags (:latest) for disconnected environments to ensure image availability.

4. Deploy and verify the redirect

   Proceed to deploy the edited manifest and verify the redirect works using steps 5-6 from the main Solution Steps.

Additional Resources:

For detailed information on mirroring images in disconnected OpenShift environments, see:
Disconnected installation mirroring

Resources Deployed

All redirects use HTTP 301 (Permanent Redirect) and preserve the requested URI path for deep link compatibility.

Troubleshooting

Platform detection fails

Verify Red Hat OpenShift AI is properly installed:

oc get odhdashboardconfig -A

Cannot discover redirect URL

Manually specify the redirect URL:

./generate-dashboard-redirect.py --redirect-url $(oc get route data-science-gateway -n <namespace> -o jsonpath='{.spec.host}')

Route already exists error

Delete the existing legacy route first:

oc delete route rhods-dashboard -n redhat-ods-applications

Then redeploy the redirect infrastructure.

Lifecycle Management

The redirect infrastructure should remain deployed as long as legacy URLs need support. When all users have updated their bookmarks, remove the redirect resources:

oc delete -f dashboard-redirect.yaml

Root Cause

When upgrading from Red Hat OpenShift AI 2.x to 3.x, the legacy rhods-dashboard route is removed and replaced with the new data-science-gateway route.

This breaking change was implemented to align with the new data science gateway architecture. The route removal breaks existing bookmarks, saved links, and documentation references.

Diagnostic Steps

1. Confirm Red Hat OpenShift AI version after upgrade:

   oc get subscription rhods-operator -n redhat-ods-operator -o jsonpath='{.status.installedCSV}'
   

   Expected output shows version 3.0 or 3.3

2. Check for the legacy dashboard route:

   oc get route rhods-dashboard -n redhat-ods-applications
   

   Expected error message:

   Error from server (NotFound): routes.route.openshift.io "rhods-dashboard" not found
   

3. Verify the new gateway route exists:

   oc get route data-science-gateway -n redhat-ods-applications
   

   Expected output shows the route exists with a hostname

4. Verify that the legacy dashboard URL returns 404:

   curl -Ik https://rhods-dashboard-redhat-ods-applications.apps.<your-cluster-domain>
   

   Expected error output:

   HTTP/1.1 404 Not Found
   

   Alternatively, attempting to access the URL in a browser displays an "Application is not available" message.

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.