Deploying Wazi Developer for Workspaces by using CASE bundle

This document describes how to install IBM® Wazi Developer for Workspaces into the OperatorHub of an OpenShift® cluster via a CASE bundle. The CASE bundle installer will create a custom resource definition (CRD) instance called wazi-codeready-operator-catalog of type CatalogSource inside your OpenShift cluster. After the resource is successfully installed, you will be able to see the Wazi Developer for Workspaces Operator inside OperatorHub.

The following section walks you through installing the necessary tools.

Prerequisites

Before running the CASE bundle installation script:

  • Ensure that you have a connection to a Red Hat® OpenShift Container Platform (OCP) cluster, and that you have cluster-admin permissions.

  • The Red Hat OpenShift cluster must be configured with a default storage class. For more information, see OpenShift Container Platform documentation.

  • If you plan to use the OpenShift OAuth, then the cluster OAuth must be configured. For more information, see Configuring the internal OAuth server.

  • Install the OpenShift command-line interface (CLI), which lets you create applications and manage OpenShift Container Platform projects from a terminal.

  • Install the IBM Cloud Pak® command-line tool, which is a command line tool to manage Container Application Software for Enterprises (CASEs).

Note: In OpenShift, a project is a Kubernetes namespace with additional annotations. For more information about projects in OpenShift, see Working with projects.

Install the OpenShift CLI

With the OpenShift CLI (oc), you can:

  • Work directly with project source code.

  • Script OpenShift Container Platform operations.

  • Work in a case in which you cannot use the web console.

To install the OpenShift CLI, you can choose either of the following approaches:

  • Follow the procedure provided in Getting started with the CLI. It contains instructions on how to install the OpenShift CLI (oc) and log in to your OpenShift cluster.

  • Download the latest release of the OpenShift CLI (oc) from OpenShift Origin GitHub repository and install it as follows:

    1. Scroll to the "Assets" section in the latest release.

    2. Choose the package that matches your operating system.

    3. Download the package and extract it.

    4. Perform the following tasks based on your operating system:

      For macOS and Linux®:

      After extracting this archive, move the oc and kubectl binary files to a location on your PATH such as /usr/local/bin.

      For Windows:

      1. Add the paths to the oc and kubectl binary files to your PATH environment variable.

      2. Add the KUBECONFIG environment variable as follows:

        1. Type edit the system environment variables in the search bar next to the Windows logo.

        2. Click Environment Variables in the System Properties window that pops up.

        3. Under System variables, click New.

        4. For the variable name, enter KUBECONFIG.

        5. For the variable value, enter a path to a config file where the OpenShift CLI can store information about cluster access. For example, C:\Windows\.kube\config.

        6. Save new system variable by pressing OK.

        Learn more about the KUBECONFIG environment variable.

To verify whether oc was installed correctly, type oc version in your command-line window. If the oc tool is installed successfully, you should see its version, for example:

oc v3.11.0+0cbc58b
kubernetes v1.11.0+d4cacc0
features: Basic-Auth

Install the IBM Cloud Pak command-line tool

  1. Download the latest release package that matches your operating system from IBM Cloud Pak CLI GitHub repository.

  2. Perform the following tasks based on your operating system:

    For macOS or Linux:

    1. Extract the archive:

      tar -xzf <archive-name>

    2. Install the IBM Cloud Pak CLI:

      chmod 755 <executable>
sudo mv <executable> /usr/local/bin/cloudctl

      where <executable> is the path to the file where you just extracted in the previous step.

    3. Verify the installation. Type cloudctl version in your terminal. You should see a similar output:

      cloudctl version
Client Version: v3.3.0-1706+2a7cd62ee2edfb6126d70c13f87275ea46c3c4c0

    For Windows:

    1. Extract the archive. You can use an application such as 7-Zip to extract cloudctl-win-amd64.exe from cloudctl-win-amd64.tar.gz.

    2. Rename cloudctl-win-amd64.exe to cloudctl.exe.

    3. Copy the cloudctl.exe file into the C:\Windows\System32 folder.

    4. Verify the installation by typing cloudctl version in your terminal. You should see a similar output:

      cloudctl version
Client Version: v3.3.0-1706+2a7cd62ee2edfb6126d70c13f87275ea46c3c4c0

For more information, see IBM Cloud Pak CLI GitHub repository.

Download and extract the IBM Wazi Developer for Red Hat CodeReady Workspaces CASE bundle

The CASE bundle contains the installation script for adding IBM Wazi Developer for Red Hat CodeReady Workspaces Operator into the cluster's OperatorHub.

  1. Download the IBM Wazi Developer for Red Hat CodeReady Workspaces CASE archive.

    Navigate to the URL below:

    https://github.com/IBM/cloud-pak/tree/master/repo/case/ibm-wazi-development-client

  2. Click the folder with latest version and download the .tgz file.

  3. Extract the archive.

    For macOS or Linux:

    tar -xzvf ibm-wazi-development-client-<latest-version>.tgz

    For Windows:

    You can use an application such as 7-Zip to extract the ibm-wazi-development-client folder from the .tgz bundle.

Run the CASE bundle installer

The CASE bundle installer will add the IBM Wazi Developer for Red Hat CodeReady Workspaces Operator into the OperatorHub on your cluster. From there, you can choose which project to install the Operator into.

  1. Use the oc client to log in to your cluster.

    oc login https://<your_cluster_hostname> -u <username> -p <password>

    To get the correct login command, take these steps:

    1. Go to your cluster, click your account, and select Copy Login Command from the drop-down menu.

    2. Click Display Token. The token information is displayed.

    3. Copy the command line oc login…. under Log in with this token, and run it from the terminal.

  2. Launch the CASE bundle.

    For macOS or Linux:

    Run the CASE bundle installer in a terminal.

    For Windows:

    You must execute the actions in a Linux VM running on Windows, or from a Windows Subsystem for Linux (WSL) terminal.

    Follow these steps to install WSL:

    • Open PowerShell as administrator, and enable wsl:

     Windows PowerShell
 Copyright (C) Microsoft Corporation. All rights reserved.

 Try the new cross-platform PowerShell https://aka.ms/pscore6

 PS C:\Users\Administrator> dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

 Deployment Image Servicing and Management tool
 Version: 10.0.19041.572

 Image Version: 10.0.19041.572

 Enabling feature(s)
 [==========================100.0%==========================]
 The operation completed successfully.
 PS C:\Users\Administrator>


 PS C:\Users\Administrator> wsl --set-default-version 2
 Please enable the Virtual Machine Platform Windows feature and ensure virtualization is enabled in the BIOS.
 For information please visit https://aka.ms/wsl2-install
 PS C:\Users\Administrator> dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

 Deployment Image Servicing and Management tool
 Version: 10.0.19041.572

 Image Version: 10.0.19041.572

 Enabling feature(s)
 [==========================100.0%==========================]
 The operation completed successfully.

    • Launch Microsoft Store and install ubuntu wsl.

    • Launch ubuntu wsl, which opens a Linux shell.

    Run the installer:

    Run the cloudctl CASE bundle installer as follows:

    cloudctl case launch --case ibm-wazi-developer-for-workspaces --inventory waziDeveloperWorkspaces

    Note: If you edit any config yaml files inside the CASE bundle, it will become invalidated. To avoid invalidation, you must add the --tolerance 1 flag.

    cloudctl case launch --case ibm-wazi-developer-for-workspaces --inventory waziDeveloperWorkspaces --tolerance 1

    You will see an output like this:

     Welcome to the CASE launcher
 Attempting to retrieve and extract the CASE from the specified location
 [✓] CASE has been retrieved and extracted
 Attempting to validate the CASE
 Skipping CASE validation...
 Attempting to locate the launch inventory item, script, and action in the specified CASE
 [✓] Found the specified launch inventory item, action, and script for the CASE
 Attempting to check the cluster and machine for required prerequisites for launching the item
 Checking for required prereqs...

 Prerequisite                                                                       Result
 Cluster has at least one linux node                                                true
 OpenShift Container Platform Kubernetes version is 1.19.0 or greater               true
 Namespace is using the restricted SecurityContextConstraint                        true
 CustomResourceDefinition must have a group and version of apiextensions.k8s.io/v1  true
 Cluster has v1 ClusterRole resource                                                true
 Client has kubectl version 1.19.0 or greater                                       true
 Client has oc version 4.7.0 or greater                                             true

 Required prereqs result: OK
 Checking user permissions...

 Kubernetes RBAC Prerequisite                            Verbs                               Result  Reason
 rbac.authorization.k8s.io.clusterroles/*                get,list,watch,create,patch,update  true
 apiextensions.k8s.io.customresourcedefinitions/v1beta1  get,list,watch,create,patch,update  true
 security.openshift.io.securitycontextconstraints/       get,list,watch,create,patch,update  true

 User permissions result: OK
 [✓] Cluster and Client Prerequisites have been met for the CASE
 Running the CASE waziDeveloperWorkspaces launch script with the following action context: install

 =========================================================================
 Non-IBM License
 =========================================================================
 TERMS AND CONDITIONS FOR SEPARATELY LICENSED CODE

The Programs listed below are licensed under the following License Information terms and conditions in addition to the Program license terms previously agreed to by Client and IBM. If Client does not have previously agreed to license terms in effect for the Program, the International License Agreement for Early Release of Programs (Z125-5544-05) applies.
...
=========================================================================
Please accept all licenses before continuing. Type Yes or No
=========================================================================

    You must accept the license before proceeding with the installation. Type Yes to accept the license in order to proceed.

    You will see the following output:

    yes
You accepted the license. Proceesing with the install...
catalogsource.operators.coreos.com/wazi-codeready-operator-catalog created
[✓] CASE launch script completed successfully
OK

Verify the deployment of wazi-codeready-operator-catalog CRD

  1. Log in to your OpenShift cluster.

  2. Expand the Administration tab on the left-side menu and click Custom Resource Definitions.

  3. On the next page, click CatalogSource.

  4. Click Instances. A new instance is shown up in the list called wazi-codeready-operator-catalog.

  5. Click wazi-codeready-operator-catalog.

  6. Click YAML and check the status section. You will see lastObservedState: READY at the end of the YAML file.

Upgrading

Upgrading Wazi Developer for Workspaces occurs automatically when the latest version of the CASE bundle is deployed. There is no need to uninstall the prior version in order to upgrade to a newer release. Newer workspace settings will not apply until a new workspace is created. You can create a new workspace and copy the changes over to your existing workspace dev-file after an upgrade completes. During the upgrade process, there will be a slight disruption in service and it is recommended that users be logged out.

Uninstall catalog source via the CASE bundle

You can uninstall wazi-codeready-operator-catalog via the CASE bundle with the following command:

cloudctl case launch --case ibm-wazi-developer-for-workspaces --inventory waziDeveloperWorkspacesSetup --action uninstall --namespace openshift-marketplace

This will delete the IBM Wazi Developer for Workspaces operator from the marketplace and other users will no longer be able to find the Operator. If you have existing IBM Wazi Developer for Workspaces deployments, they will not be deleted, however, they will no longer be managed the by Operator.

Troubleshooting

Issue: CASE bundle generates Missing or incomplete configuration error.

User permissions result: OK
[✓] Cluster and Client Prerequisites have been met for the CASE
Running the CASE waziDeveloperWorkspacesSetupWindows launch script with the following action context: install
"License accepted. Continuing the installation..."
error: Missing or incomplete configuration info.  Please login or point to an existing, complete config file:
  1. Via the command-line flag --config
  2. Via the KUBECONFIG environment variable
  3. In your home directory as ~/.kube/config
To view or setup config directly use the 'config' command.
[✓] CASE launch script completed successfully

Solution: If you encountered this error, this most likely means that KUBECONFIG environment variable was not set up. Go to the Install the OpenShift CLI section in the beginning of this page and follow steps to Add the KUBECONFIG environment variable.