Chapter 6. Managing IDE extensions

Procedure

1. Get the publisher and extension name of each chosen extension:

   1. Find the extension on the Open VSX registry website and copy the URL of the extension’s listing page and extension’s version.

   2. Extract the <publisher> and <extension> name from the copied URL:

      https://open-vsx.org/extension/<publisher>/<name>

      Copy to Clipboard Toggle word wrap
      Tip

      If the extension is only available from Microsoft Visual Studio Marketplace, but not Open VSX, you can ask the extension publisher to also publish it on open-vsx.org according to these instructions, potentially using this GitHub action.

      If the extension publisher is unavailable or unwilling to publish the extension to open-vsx.org, and if there is no Open VSX equivalent of the extension, consider reporting an issue to the Open VSX team.

2. Build the custom plugin registry image and update CheCluster custom resource:

   Tip
   • During the build process, each extension will be verified for compatibility with the version of Visual Studio Code used in OpenShift Dev Spaces.

   1. Using OpenShift Dev Spaces instance:

      Important

      For IBM Power (ppc64le) and IBM Z (s390x), the custom plugin registry is expected to be built locally on the corresponding architecture.

      1. Login to your OpenShift Dev Spaces instance as an administrator.

3. Create a new Red Hat Registry Service Account and copy username and token.

   1. Start a workspace using the plugin registry repository.
   2. Open the openvsx-sync.json file and add or remove extensions.
   3. Run 1. Login to registry.redhat.io task in the workspace (Terminal Run Task…​ devfile 1. Login to registry.redhat.io) and login to registry.redhat.io.

   4. Run 2. Build and Publish a Custom Plugin Registry task in the workspace (Terminal Run Task…​ devfile 2. Build and Publish a Custom Plugin Registry).

      Note

      Check CHE_CODE_VERSION in the build-config.json file and update it if necessary. This variable must match the version of the editor currently used with OpenShift Dev Spaces.

   5. Run 3. Configure Che to use the Custom Plugin Registry task in the workspace (Terminal Run Task…​ devfile 3. Configure Che to use the Custom Plugin Registry).

      1. Using Linux operating system:

         Tip
         • Podman and NodeJS version 18.20.3 or higher should be installed in the system.

   6. Download or fork and clone the Plugin registry repository.

      git clone https://github.com/redhat-developer/che-plugin-registry.git

      Copy to Clipboard Toggle word wrap

   7. Go to the plugin registry project directory:

      cd che-plugin-registry/

      Copy to Clipboard Toggle word wrap
   8. Create a new Red Hat Registry Service Account and copy username and token.

   9. Login to registry.redhat.io:

      podman login registry.redhat.io

      Copy to Clipboard Toggle word wrap

   10. For each extension that you need to add or remove, edit the openvsx-sync.json file:

       • To add extensions, add the publisher, name and extension version to the openvsx-sync.json file.
       • To remove extensions, remove the publisher, name and extension version from the openvsx-sync.json file.

       • Use the following JSON syntax:

             {
                 "id": "<publisher>.<name>",
                 "version": "<extension_version>"
             }

         Copy to Clipboard Toggle word wrap
         Tip

         • If you have a closed-source extension or an extension developed only for internal use in your organization, you can add the extension directly from a .vsix file by using a URL accessible to your custom plugin registry container:

               {
                   "id": "<publisher>.<name>",
                   "download": "<url_to_download_vsix_file>",
                   "version": "<extension_version>"
               }

           Copy to Clipboard Toggle word wrap
         • Read the Terms of Use for the Microsoft Visual Studio Marketplace before using its resources.

   11. Build the plugin registry container image and publish it to a container registry such as quay.io:

       1. $ ./build.sh -o <username> -r quay.io -t custom

          Copy to Clipboard Toggle word wrap

       2. $ podman push quay.io/<username/plugin_registry:custom>

          Copy to Clipboard Toggle word wrap

   12. Edit the CheCluster custom resource in your organization’s cluster to point to the image (for example, on quay.io) and save the changes:

       spec:
         components:
           pluginRegistry:
             deployment:
               containers:
                 - image: quay.io/<username/plugin_registry:custom>
             openVSXURL: ''

       Copy to Clipboard Toggle word wrap

Verification

1. Check that the plugin-registry pod has restarted and is running.
2. Restart the workspace and check the available extensions in the Extensions view of the workspace IDE.

Procedure

1. Start a workspace using the Open VSX repository.

   Create a workspace by using the following Eclipse Open VSX repository.

   Warning

   The .devfile.yaml includes an elasticsearch component that does not support IBM Power (ppc64le) or IBM Z (s390x) architectures. To successfully start the workspace on these architectures, the only option is to remove this component from the devfile. Alternatively, you can refer to Using OpenShift CLI tool documentation, which describes how to run Open VSX separately without starting a workspace.

   Tip

   The environment, including all necessary commands, is defined in the .devfile.yaml file.

2. Create a new OpenShift project for Open VSX.

   Run 2.1. Create Namespace for OpenVSX task in the workspace (Terminal Run Task… devfile 2.1. Create Namespace for OpenVSX). A new project with the name openvsx should be created on the cluster.

3. Deploy Open VSX.

   Run 2.4.1. Deploy Custom OpenVSX task in the workspace (Terminal Run Task… devfile 2.4.1. Deploy Custom OpenVSX). This task will ask to provide the Open VSX server image. Enter registry.redhat.io/devspaces/openvsx-rhel9:3.23 into the terminal. As a result, in the OpenShift console, you can find the openvsx project with two components: PostgreSQL database and Open VSX server. Additionally, the Open VSX UI should be accessible through an exposed route in the OpenShift cluster.

   Tip

   All deployment information is described in the deploy/openshift/openvsx-deployment-no-es.yml file with some default values such as OVSX_PAT_BASE64.

4. Add Open VSX user with PAT to the database.

   Run the 2.5. Add OpenVSX user with PAT to the DB task in the workspace (Terminal Run Task… devfile 2.5. Add OpenVSX user with PAT to the DB). The command will ask for the Open VSX username and user PAT. You can just click enter to use the default values.

   Important

   The user PAT must match the decoded value of OVSX_PAT_BASE64 specified in the deployment file. If OVSX_PAT_BASE64 has been updated, use the new token’s decoded value as the user PAT.

5. Configure OpenShift Dev Spaces to use the internal Open VSX.

   Run the 2.6. Configure Che to use the internal Open VSX registry task in the workspace (Terminal Run Task… devfile 2.6. Configure Che to use the internal OpenVSX registry). It applies the patch to the CheCluster custom resource, updating its configuration to use the specified Open VSX URL for the extension registry.

6. Publish an extension from a .vsix file.

   At the beginning, the Open VSX registry does not provide any extension. Once the openvsx-server pod is running and in the Ready state, extensions can be published to the registry. The 2.8. Publish a Visual Studio Code Extension from a VSIX file command publishes an extension to the local Open VSX registry directly from a .vsix file. It prompts you to provide the extension’s namespace name and the path to the .vsix file.

7. Publish list of extensions.

   The 2.9. Publish list of Visual Studio Code Extensions command automates the process of publishing a predefined list of Microsoft Visual Studio Code extensions based on download URLs to the internal Open VSX registry.

   Tip

   The command reads from the deploy/openshift/extensions.txt file, which lists the URLs of .vsix files for each extension to be published. To publish your extensions to Open VSX, update the extensions.txt file as needed, then run the 2.9. Publish list of Visual Studio Code Extensions task from the workspace: Terminal Run Task… devfile 2.9. Publish list of Visual Studio Code Extensions.

8. Verify that OpenShift Dev Spaces uses internal Open VSX.

   Start any workspace and check the available extensions in the Extensions view of the workspace IDE or by opening the internal route in the OpenVSX OpenShift project.

Procedure

1. Create a new OpenShift project for Open VSX.

   oc new-project openvsx

   Copy to Clipboard Toggle word wrap

2. Deploy Open VSX.

   Save openvsx-deployment-no-es.yml file on your file system, then navigate to that directory and run command to deploy Open VSX:

   oc process -f openvsx-deployment-no-es.yml \
      -p OPENVSX_SERVER_IMAGE=registry.redhat.io/devspaces/openvsx-rhel9:3.23 \
      | oc apply -f -

   Copy to Clipboard Toggle word wrap

3. Verify that all pods in the openvsx namespace are running and ready. It might take a few minutes for all pods to become ready. Run the following command:

   oc get pods -n openvsx \
     -o jsonpath='{range .items[*]}{@.metadata.name}{"\t"}{@.status.phase}{"\t"}{.status.containerStatuses[*].ready}{"\n"}{end}'

   Copy to Clipboard Toggle word wrap

4. Add Open VSX user with PAT to the database.

   Find PostgreSQL pod:

   export POSTGRESQL_POD_NAME=$(oc get pods -n openvsx \
      -o jsonpath="{.items[*].metadata.name}" | tr ' ' '\n' | grep '^postgresql' | head -n 1)

   Copy to Clipboard Toggle word wrap

   Insert username into OpenVSX database:

   oc exec -n openvsx "$POSTGRESQL_POD_NAME" -- bash -c \
      "psql -d openvsx -c \"INSERT INTO user_data (id, login_name, role) VALUES (1001, 'eclipse-che', 'privileged');\""

   Copy to Clipboard Toggle word wrap

   Insert user PAT into OpenVSX database:

   oc exec -n openvsx "$POSTGRESQL_POD_NAME" -- bash -c \
      "psql -d openvsx -c \"INSERT INTO personal_access_token (id, user_data, value, active, created_timestamp, accessed_timestamp, description) VALUES (1001, 1001, 'eclipse_che_token', true, current_timestamp, current_timestamp, 'extensions publisher');\""

   Copy to Clipboard Toggle word wrap

5. Configure OpenShift Dev Spaces to use the internal Open VSX.

   export CHECLUSTER_NAME="$(oc get checluster --all-namespaces -o json | jq -r '.items[0].metadata.name')" &&
   export CHECLUSTER_NAMESPACE="$(oc get checluster --all-namespaces -o json | jq -r '.items[0].metadata.namespace')" &&
   export OPENVSX_ROUTE_URL="$(oc get route internal -n openvsx -o jsonpath='{.spec.host}')" &&
   export PATCH='{"spec":{"components":{"pluginRegistry":{"openVSXURL":"https://'"$OPENVSX_ROUTE_URL"'"}}}}' &&
   oc patch checluster "${CHECLUSTER_NAME}" --type=merge --patch "${PATCH}" -n "${CHECLUSTER_NAMESPACE}"

   Copy to Clipboard Toggle word wrap
   Tip

   Refer to the Section 6.3, “Open VSX registry URL” for detailed instructions on configuring the Open VSX registry URL in OpenShift Dev Spaces.

6. Publish Visual Studio Code extensions with the ovsx command.

   Note

   At the beginning, the Open VSX registry does not provide any extension.

   With everything configured, the next step is to publish a Visual Studio Code extension from inside the openvsx-server container. To do this, you need two pieces of information: the extension namespace name (used for publishing), the download URL of the .vsix extension package. Once you have this information, run the following commands to publish the extension:

   1. Retrieve the name of the pod running the Open VSX server:

      export OVSX_POD_NAME=$(oc get pods -n openvsx -o jsonpath="{.items[*].metadata.name}" | tr ' ' '\n' | grep ^openvsx-server)

      Copy to Clipboard Toggle word wrap

   2. Download the .vsix extension:

      oc exec -n openvsx "${OVSX_POD_NAME}" -- bash -c "wget -O /tmp/extension.vsix EXTENSION_DOWNLOAD_URL "

      Copy to Clipboard Toggle word wrap

   3. Create an extension namespace:

      oc exec -n openvsx "${OVSX_POD_NAME}" -- bash -c "ovsx create-namespace EXTENSION_NAMESPACE_NAME" || true

      Copy to Clipboard Toggle word wrap

   4. Publish the extension:

      oc exec -n openvsx "${OVSX_POD_NAME}" -- bash -c "ovsx publish /tmp/extension.vsix"

      Copy to Clipboard Toggle word wrap

   5. Delete the downloaded extension file:

      oc exec -n openvsx "${OVSX_POD_NAME}" -- bash -c "rm /tmp/extension.vsix"

      Copy to Clipboard Toggle word wrap
      Tip

      Example: Publish the redhat.vscode-yaml extension version 1.18.0:

      oc exec -n openvsx "${OVSX_POD_NAME}" -- bash -c "wget -O /tmp/extension.vsix https://open-vsx.org/api/redhat/vscode-yaml/1.18.0/file/redhat.vscode-yaml-1.18.0.vsix " &&
      oc exec -n openvsx "${OVSX_POD_NAME}" -- bash -c "ovsx create-namespace redhat" || true &&
      oc exec -n openvsx "${OVSX_POD_NAME}" -- bash -c "ovsx publish /tmp/extension.vsix" &&
      oc exec -n openvsx "${OVSX_POD_NAME}" -- bash -c "rm /tmp/extension.vsix"

      Copy to Clipboard Toggle word wrap

7. Verify Open VSX extension registry.

   Check the list of published extensions by navigating to the URL defined in the OPENVSX_ROUTE_URL environment variable.

1. Remove the Public Route.

   Delete the public route associated with the Open VSX registry to restrict external access:

   oc delete route internal -n openvsx

   Copy to Clipboard Toggle word wrap

2. Set the Internal Open VSX Service URL.

   Update the CheCluster custom resource to use the internal cluster service DNS:

   export CHECLUSTER_NAME="$(oc get checluster --all-namespaces -o json | jq -r '.items[0].metadata.name')" &&
   export CHECLUSTER_NAMESPACE="$(oc get checluster --all-namespaces -o json | jq -r '.items[0].metadata.namespace')" &&
   export PATCH='{"spec":{"components":{"pluginRegistry":{"openVSXURL":"http://openvsx-server.openvsx.svc:8080"}}}}' &&
   oc patch checluster "${CHECLUSTER_NAME}" --type=merge --patch "${PATCH}" -n "${CHECLUSTER_NAMESPACE}"

   Copy to Clipboard Toggle word wrap