Chapter 4. Install Red Hat OpenShift Dev Spaces

Procedure

1. Optional: If you previously deployed OpenShift Dev Spaces on this OpenShift cluster, ensure that the previous OpenShift Dev Spaces instance is removed:

   $ dsc server:delete

2. Create the OpenShift Dev Spaces instance:

   $ dsc server:deploy --platform openshift

Verification

1. Verify the OpenShift Dev Spaces instance status:

   $ dsc server:status

2. Navigate to the OpenShift Dev Spaces cluster instance:

   $ dsc dashboard:open

Procedure

1. In the Administrator view of the OpenShift web console, go to Operators OperatorHub and search for Red Hat OpenShift Dev Spaces.

2. Install the Red Hat OpenShift Dev Spaces Operator.

   Tip

   See Installing from OperatorHub using the web console.

   Important

   The Red Hat OpenShift Dev Spaces Operator depends on the Dev Workspace Operator. If you install the Red Hat OpenShift Dev Spaces Operator manually to a non-default namespace, ensure that the Dev Workspace Operator is also installed in the same namespace. The Operator Lifecycle Manager installs the Dev Workspace Operator as a dependency within the Red Hat OpenShift Dev Spaces Operator namespace. If the Dev Workspace Operator is already installed in a different namespace, two conflicting installations can result.

   Important

   If you want to onboard Web Terminal Operator on the cluster, use the same installation namespace as the Red Hat OpenShift Dev Spaces Operator. Both operators depend on the Dev Workspace Operator, so all three must be installed in the same namespace.

3. Create the openshift-devspaces project in OpenShift as follows:

   oc create namespace openshift-devspaces

4. Go to Operators Installed Operators Red Hat OpenShift Dev Spaces instance Specification Create CheCluster YAML view.
5. In the YAML view, replace namespace: openshift-operators with namespace: openshift-devspaces.

6. Select Create.

   Tip

   See Creating applications from installed Operators.

1. In Red Hat OpenShift Dev Spaces instance Specification, go to devspaces, landing on the Details tab.

1. Under Message, check that there is None, which means no errors.
2. Under Red Hat OpenShift Dev Spaces URL, wait until the URL of the OpenShift Dev Spaces instance appears, and then open the URL to check the OpenShift Dev Spaces dashboard.
3. In the Resources tab, view the resources for the OpenShift Dev Spaces deployment and their status.

Procedure

1. Download and execute the mirroring script to install a custom Operator catalog and mirror the related images.

   $ bash prepare-restricted-environment.sh \
     --devworkspace_operator_index registry.redhat.io/redhat/redhat-operator-index:v4.22\
     --devworkspace_operator_version "v0.40.0" \
     --prod_operator_index "registry.redhat.io/redhat/redhat-operator-index:v4.22" \
     --prod_operator_package_name "devspaces" \
     --prod_operator_bundle_name "devspacesoperator" \
     --prod_operator_version "v3.27.0" \
     --my_registry "<my_registry>"

   --my_registry

   The private Docker registry where the images will be mirrored

Procedure

1. Install OpenShift Dev Spaces with the configuration set in the che-operator-cr-patch.yaml during the previous step:

   $ dsc server:deploy \
     --platform=openshift \
     --olm-channel stable \
     --catalog-source-name=devspaces-disconnected-install \
     --catalog-source-namespace=openshift-marketplace \
     --skip-devworkspace-operator \
     --che-operator-cr-patch-yaml=che-operator-cr-patch.yaml

2. Allow incoming traffic from the OpenShift Dev Spaces namespace to all Pods in the user projects. See: Section 12.1, “Configure network policies”.

Procedure

1. Mirror the following images:

   ghcr.io/ansible/ansible-devspaces@sha256:ce1ecc3b3c350eab2a9a417ce14a33f4b222a6aafd663b5cf997ccc8c601fe2c
   registry.access.redhat.com/ubi8/python-39@sha256:301fec66443f80c3cc507ccaf72319052db5a1dc56deb55c8f169011d4bbaacb

2. Configure the cluster proxy to allow access to the following domains:

   .ansible.com
   .ansible-galaxy-ng.s3.dualstack.us-east-1.amazonaws.com

   Note

   Support for the following IDE and CPU architectures is planned for a future release:

   • CPU architectures

     • IBM Power (ppc64le)
     • IBM Z (s390x)

Procedure

1. Define the environment variables:

   # The Keycloak realm used for OpenShift authentication:
   OPENSHIFT_REALM=<realm>
   
   # The Keycloak URL:
   KEYCLOAK_URL=<keycloak_url>

2. Create a devspaces client in the Keycloak Admin Console:

   1. Within the realm used for OpenShift authentication, select Clients on the left side of the navigation bar.
   2. Select the Create client button.

   3. On the General Settings page:

      1. Enter devspaces in the Client ID field.
      2. Optional: Enter a Name and Description for the OAuth client.
      3. Click Next.

   4. On the Capability config page:

      1. Toggle Client authentication to On.
      2. Click Next.
      3. Click Save.
   5. Navigate to the Credentials tab of the newly created client and copy the Client secret value for use when applying the OAuth client secret.

3. Add the devspaces client to the audiences list in the OpenShift authentication configuration:

   oc patch authentication.config/cluster \
     --type='json' \
     -p='[
       {
         "op": "add",
         "path": "/spec/oidcProviders/0/issuer/audiences/-",
         "value": "devspaces"
       }
     ]'

   Note

   If you have multiple OIDC providers configured, adjust the array index in the path (currently 0) to match your Keycloak provider’s position in the configuration.

4. Wait for the kube-apiserver cluster Operator to roll out the configuration changes:

   watch oc get co kube-apiserver

5. Create a project for OpenShift Dev Spaces:

   oc create project openshift-devspaces

6. Create a secret for the OAuth client in the OpenShift Dev Spaces namespace:

   oc apply -f - <<EOF
   apiVersion: v1
   kind: Secret
   metadata:
     name: oauth-secret
     namespace: openshift-devspaces
     labels:
       app.kubernetes.io/part-of: che.eclipse.org
   stringData:
     oAuthSecret: <client_secret>
   EOF

   where:

   <client_secret>

   The client secret value from the devspaces client in Keycloak.

7. Optional: Create the ConfigMap with a Keycloak certificate in the openshift-devspaces namespace. If Keycloak uses a certificate that is already trusted by OpenShift, skip this step.

   openssl s_client \
     -connect "$(echo "$KEYCLOAK_URL" | sed 's|https://||'):443" \
     -showcerts < /dev/null \
   | sed -n '/-----BEGIN CERTIFICATE-----/,/-----END CERTIFICATE-----/p' \
   > keycloak-ca.crt
   
   oc create configmap keycloak-certs \
       --from-file=keycloak-ca.crt=keycloak-ca.crt \
       -n openshift-devspaces && \
   oc label configmap keycloak-certs \
       app.kubernetes.io/part-of=che.eclipse.org \
       app.kubernetes.io/component=ca-bundle \
       -n openshift-devspaces

8. Prepare the CheCluster patch:

   cat > che-patch.yaml << EOF
   kind: CheCluster
   apiVersion: org.eclipse.che/v2
   spec:
     networking:
       auth:
         oAuthClientName: devspaces
         oAuthSecret: oauth-secret
         identityProviderURL: "$KEYCLOAK_URL/realms/$OPENSHIFT_REALM"
         gateway:
           oAuthProxy:
             cookieExpireSeconds: 300
           deployment:
             containers:
               - name: oauth-proxy
                 env:
                   - name: OAUTH2_PROXY_CODE_CHALLENGE_METHOD
                     value: S256
                   - name: OAUTH2_PROXY_BACKEND_LOGOUT_URL
                     value: "$KEYCLOAK_URL/realms/$OPENSHIFT_REALM/protocol/openid-connect/logout?id_token_hint={id_token}"
     components:
       cheServer:
         extraProperties:
           CHE_OIDC_GROUPS__CLAIM: '<GROUPS_CLAIM>'
           CHE_OIDC_GROUPS__PREFIX: '<GROUPS_PREFIX>'
           CHE_OIDC_USERNAME__CLAIM: '<USERNAME_CLAIM>'
           CHE_OIDC_USERNAME__PREFIX: '<USERNAME_PREFIX>'
   EOF

   where:

   CHE_OIDC_GROUPS__CLAIM

   The claim to use for extracting user groups.

   CHE_OIDC_GROUPS__PREFIX

   The prefix to add to group names. Empty string means no prefix.

   CHE_OIDC_USERNAME__CLAIM

   The claim to use for extracting the username.

   CHE_OIDC_USERNAME__PREFIX

   The prefix to add to usernames. Empty string means no prefix.

   Note

   These values must match the corresponding claim and prefix settings configured in the authentication.config/cluster resource. To view the current cluster configuration, run:

   oc get authentication.config/cluster -o yaml

9. Create the OpenShift Dev Spaces instance with dsc:

   dsc server:deploy \
     --platform openshift \
     --che-operator-cr-patch-yaml che-patch.yaml

10. Update the devspaces client to set the OpenShift Dev Spaces redirect URI and web origin.

    Obtain the Red Hat OpenShift Dev Spaces URL:

    echo "$(oc get checluster devspaces -n openshift-devspaces -o jsonpath='{.status.cheURL}')"

    1. In the Valid redirect URIs field, enter the URL above with /oauth/callback appended.
    2. In the Web origins field, enter the URL above.
    3. Click Save.

Verification

1. Verify the OpenShift Dev Spaces instance status:

   dsc server:status

2. Navigate to the OpenShift Dev Spaces cluster instance:

   dsc dashboard:open

3. Log in to the OpenShift Dev Spaces instance.

Procedure

1. Run the following command:

   oc get checluster devspaces -n openshift-devspaces -o jsonpath='{.status.cheURL}'