Configure Open Data Hub

After installing Red Hat® OpenShift® Service on AWS, configuring Keycloak, and assigning users to groups, you're ready to configure Open Data Hub. In this lesson, you will install the ODH operator and its prerequisites, apply the DSCInitialization and DataScienceCluster resources, and configure the data science gateway to authenticate users through your Keycloak OIDC provider.  

Prerequisites:

• An Amazon Web Services account.
• A Red Hat account.
• A configured ROSA cluster.
• Configured Keycloak, users, and groups.

In this lesson, you will:

• Install Open Data Hub Operator.
• Create DSCInitialization.
• Configure gateway for OpenID Connect (OIDC).
• Deploy a data science cluster.
• Learn additional testing and troubleshooting.

Install required operators

Before you can install Open Data Hub Operator, you need to install a few necessary operators from OperatorHub within the Red Hat® OpenShift® console. These are needed for ODH to function properly within your newly configured cluster:  

1. Navigate to the OpenShift console.
2. From OperatorHub, find and install the following operators:
   1. Red Hat Connectivity Link                                                                                                                                                                                  
   2. Leader Worker Set Operator
   3. Job Set Operator                                                                                                                                                                                           
   4. cert-manager Operator for Red Hat OpenShift   

3. Navigate to the console once again and create the JobSetOperator CR with a name cluster via the following command:

   cat <<EOF | oc apply -f -                                                                                                                                                                                          
     apiVersion: operator.openshift.io/v1                                                                                                                                                                               
     kind: JobSetOperator                                                                                                                                                                                               
     metadata:                                                                                                                                                                                                          
       name: cluster                                                                                                                                                                                                    
     spec:                                                                                                                                                                                                              
       logLevel: Normal                                                                                                                                                                                                 
       operatorLogLevel: Normal
       managementState: Managed                                                                                                                                                                                         
   EOF

4. Now you can install Open Data Hub Operator. It’s important to perform this step before creating any ODH resources. 

5. In the OpenShift console, navigate to the Operators menu, select OperatorHub, and search for ODH (Figure 1).

   

6. Click on Open Data Hub Operator and install it.

Create DSCInitialization, configure the gateway, and deploy a data science cluster

An important step before deploying a data science cluster is ensuring that ODH is using the most up-to-date samples from its repository. Only after initializing that, can you then safely connect your Keycloak authentication and deploy. 

1. Use the latest DSCInitialization sample from the Open Data Hub Operator repository:
   1. DSCInitialization samples (e.g., dscinitialization_v2_dscinitialization.yaml), or the RHOAI samples under config/rhoai/samples/ if applicable.

2. Apply the DSCInitialization CR (adjust the file path or URL to the sample you use):

   oc apply -f https://raw.githubusercontent.com/opendatahub-io/opendatahub-operator/main/config/samples/dscinitialization_v2_dscinitialization.yaml

3. Wait for initialization:

   kubectl wait --for=jsonpath='{.status.phase}'=Ready dscinitialization/default-dsci -n opendatahub --timeout=300s 

4. Verify the opendatahub namespace is created and configured.

5. Retrieve the cluster domain from the cluster you already have or created in the first resource of this learning path. 

   Should you need to retrieve it again, use the following command: 

   CLUSTER_DOMAIN=apps.rosa.$(rosa describe cluster -c $CLUSTER_NAME -o json | jq -r '.api.url' | sed 's|https://api.||;s|:6443||;s|:443||')

6. If you do not have jq installed, use this alternative command:

   CLUSTER_DOMAIN=apps.rosa.$(rosa describe cluster -c $CLUSTER_NAME | grep "API URL" | awk '{print $3}' | sed 's|https://api.||;s|:6443||;s|:443||')
   echo "Cluster domain: $CLUSTER_DOMAIN"

7. Create a client secret:

   oc create secret generic keycloak-client-secret \
     --from-literal=clientSecret=$KEYCLOAK_CLIENT_SECRET -n openshift-ingress

8. Update GatewayConfig for OIDC. Make sure to use the method most suited to your certificate creation during Keycloak configuration in earlier resources:

   1. Without CA (using publicly trusted certificate)

   oc patch gatewayconfig default-gateway --type='merge' -p='{
     "spec": {
       "ingressMode": "LoadBalancer",
       "oidc": {
         "issuerURL": "https://'$KEYCLOAK_DOMAIN'/realms/'$KEYCLOAK_REALM'",
         "clientID": "'$KEYCLOAK_CLIENT_ID'",
         "clientSecretRef": {
           "name": "keycloak-client-secret",
           "key": "clientSecret"
         }
       },
       "verifyProviderCertificate": true
     }
   }'

   1. With CA Certificate (self-signed or custom CA)

   oc create secret generic keycloak-ca-cert \
     --from-file=ca.crt=keycloak-ca.crt \
     -n openshift-ingress
   oc patch gatewayconfig default-gateway --type='merge' -p='{
     "spec": {
       "ingressMode": "LoadBalancer",
       "oidc": {
         "issuerURL": "https://'$KEYCLOAK_DOMAIN'/realms/'$KEYCLOAK_REALM'",
         "clientID": "'$KEYCLOAK_CLIENT_ID'",
         "clientSecretRef": {
           "name": "keycloak-client-secret",
           "key": "clientSecret"
         }
       },
       "providerCASecretName": "keycloak-ca-cert",
       "verifyProviderCertificate": true
     }
   }'

   1. Disable CA validation (dev only; self-signed or custom CA)

   oc patch gatewayconfig default-gateway --type='merge' -p='{
     "spec": {
       "ingressMode": "LoadBalancer",
       "oidc": {
         "issuerURL": "https://'$KEYCLOAK_DOMAIN'/realms/'$KEYCLOAK_REALM'",
         "clientID": "'$KEYCLOAK_CLIENT_ID'",
         "clientSecretRef": {
           "name": "keycloak-client-secret",
           "key": "clientSecret"
         }
       },
       "verifyProviderCertificate": false
     }
   }'

9. Verify that Secret exists and GatewayConfig shows OIDC configuration.

Finally, you can run Open Data Hub with OIDC authentication and deploy your data science cluster. 

1. Use the latest DataScienceCluster sample from the Open Data Hub Operator repository:

   DataScienceCluster samples (e.g., datasciencecluster_v2_datasciencecluster.yaml), or the RHOAI samples under config/rhoai/samples/ if applicable.

2. Apply the CR (adjust the file path or URL to the sample you use):

   oc apply -f https://raw.githubusercontent.com/opendatahub-io/opendatahub-operator/main/config/samples/datasciencecluster_v2_datasciencecluster.yaml
   Or download the file and run: oc apply -f datasciencecluster_v2_datasciencecluster.yaml

3. Wait for the cluster to become ready (pods in opendatahub namespace).

   kubectl wait --for=jsonpath='{.status.phase}'=Ready datasciencecluster/default-dsc -n opendatahub --timeout=300s 

4. Verify that the pods are running in the opendatahub namespace.

Congratulations! You have successfully set up ODH for your environment. 

Validation testing and troubleshooting

In the event that you need to do any sort of testing and validation to check everything is working as intended, there are a few ways to do so. 

Testing OpenShift Console access

1. Access the console.
2. Log in with Keycloak credentials.

Testing OC CLI access

1. Log in via command-line interface (CLI).

   CLUSTER_DOMAIN=$(rosa describe cluster -c $CLUSTER_NAME -o json | jq -r '.api.url' | sed 's|https://api.||;s|:6443||;s|:443||')
   # Without jq
   CLUSTER_DOMAIN=$(rosa describe cluster -c $CLUSTER_NAME | grep "API URL" | awk '{print $3}' | sed 's|https://api.||;s|:6443||;s|:443||')
   echo "Cluster domain: $CLUSTER_DOMAIN"
   oc login --exec-plugin=oc-oidc \
     --issuer-url=https://$KEYCLOAK_DOMAIN/realms/$KEYCLOAK_REALM \
     --client-id=$KEYCLOAK_CLIENT_ID \
     --callback-port=8080 \
     --server=https://api.$CLUSTER_DOMAIN:443 \
     --client-secret=$KEYCLOAK_CLIENT_SECRET

Testing ODH Gateway access

1. Access the gateway. This is the default subdomain for ODH 3.0. Legacy data-science-gateway may redirect here)
2. Log in with Keycloak credentials.
3. Verify ODH components are accessible.

Troubleshooting critical issues

1. Authentication fails or redirect errors:

   1. Verify redirect URIs in Keycloak client match your cluster domain.
   2. Ensure all three redirect URIs are configured in Keycloak:
      1. https://console-openshift-console.${CLUSTER_DOMAIN}/auth/callback
      2. http://localhost:8080/*
      3. https://rh-ai.${CLUSTER_DOMAIN}/oauth2/callback
   3. Verify Keycloak client secret matches the value in ROSA and GatewayConfig.

2. Gateway returns 403 Forbidden:

   1. Check kube-auth-proxy: oc get pods -n openshift-ingress -l app=kube-auth-proxy
   2. Verify GatewayConfig: oc get gatewayconfig default-gateway -o yaml

3. Groups not showing in OpenShift:

   1. In Keycloak, set group mapper Full group path to OFF.
   2. Confirm the user is in the odh-admin group.
   3. Verify ClusterRoleBinding: oc get clusterrolebinding rosa-hcp-admins

Essential debug commands

# Cluster authentication mode
oc get authentication cluster -o jsonpath='{.spec.type}'
# Gateway configuration
oc get gatewayconfig default-gateway -o yaml
# Auth proxy pods
oc get pods -n openshift-ingress -l app=kube-auth-proxy
# External auth provider
rosa list external-auth-providers -c $CLUSTER_NAME
# User groups
oc get user $(oc whoami) -o jsonpath='{.groups}{"\n"}'

Learning path summary

Congratulations! You now have a working OIDC instance on your ROSA-enabled cluster. As you work within this new environment, some things to further explore include Red Hat® OpenShift® AI (RHOAI). This can be used to deploy and run things like large language models (LLMs) on an AWS cluster. Read more about it here.   

Ready to learn more?

• Red Hat OpenShift Service on AWS with hosted control planes quick start guide — prerequisites, CLI, VPC, OIDC config, Operator roles, create cluster
• Creating a ROSA cluster with external OIDC — HCP + Keycloak/external auth
• Configuring a shared VPC for ROSA clusters — shared VPC (VPC Owner / Cluster Creator)
• Creating a private cluster on ROSA — private cluster, private subnets
• Creating ROSA clusters with egress zero — disconnected / egress-zero
• Open Data Hub Documentation
• Keycloak Documentation