Chapter 6. Managing IDE extensions

Procedure

1. Log in to the cluster as an administrator.

2. Edit the

   CheCluster

   custom resource to update the

   openVSXURL

   value:

   spec:
     components:
       pluginRegistry:
         openVSXURL: "<url_of_an_open_vsx_registry_instance>" 

   1

   1

   For example: openVSXURL: "https://open-vsx.org".

Verification

1. Confirm that the

   plugin-registry

   pod has restarted.
2. Open a workspace and verify that extensions are available from the selected registry instance in the Extensions view.

Procedure

1. Identify the publisher and extension name for each extension you want to add:

   1. Find the extension on the Open VSX registry website.
   2. Copy the URL of the extension’s listing page.

   3. Extract the

      <publisher>

      and

      <name>

      from the URL:

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

      Tip

      If the extension is only available from Microsoft Visual Studio Marketplace, but not Open VSX, you can ask the extension publisher to 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. Open the

   openvsx-sync.json

   file in the workspace.

3. Add or remove extensions using the following JSON syntax:

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

   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>"
   }

   Read the Terms of Use for the Microsoft Visual Studio Marketplace before using its resources.

4. Log in to the Red Hat registry:

   1. Navigate to Terminal Run Task…​ devfile.
   2. Run the 1. Login to registry.redhat.io task.
   3. Enter your Red Hat Registry Service Account credentials when prompted.

5. Build and publish the custom plugin registry:

   1. Navigate to Terminal Run Task…​ devfile.

   2. Run the 2. Build and Publish a Custom Plugin Registry task.

      Note

      Verify that the

      CHE_CODE_VERSION

      in the

      build-config.json

      file matches the version of the editor currently used with OpenShift Dev Spaces. Update it if necessary.

6. Configure OpenShift Dev Spaces to use the custom plugin registry:

   1. Navigate to Terminal Run Task…​ devfile.
   2. Run the 3. Configure Che to use the Custom Plugin Registry task.

Verification

1. Check that the

   plugin-registry

   pod has restarted and is running.
2. Restart your workspace.
3. Open the Extensions view in the IDE and verify that your added extensions are available.

Procedure

1. Clone the plugin registry repository:

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

2. Change to the plugin registry directory:

   $ cd che-plugin-registry

3. Log in to the Red Hat registry:

   $ podman login registry.redhat.io

4. Identify the publisher and extension name for each extension you want to add:

   1. Find the extension on the Open VSX registry website.
   2. Copy the URL of the extension’s listing page.

   3. Extract the

      <publisher>

      and

      <name>

      from the URL:

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

      Tip

      If the extension is only available from Microsoft Visual Studio Marketplace, but not Open VSX, you can ask the extension publisher to 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.

5. Open the

   openvsx-sync.json

   file.

6. Add or remove extensions using the following JSON syntax:

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

   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>"
   }

7. Build the plugin registry container image:

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

   Note

   Verify that the

   CHE_CODE_VERSION

   in the

   build-config.json

   file matches the version of the editor currently used with OpenShift Dev Spaces. Update it if necessary.

8. Push the image to a container registry such as quay.io:

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

9. Edit the

   CheCluster

   custom resource in your organization’s cluster to point to the image and save the changes:

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

Verification

1. Check that the

   plugin-registry

   pod has restarted and is running.
2. Restart your workspace.
3. Open the Extensions view in the IDE and verify that your added extensions are available.

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.26

   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

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.26 \
      | oc apply -f -

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}'

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)

   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');\""

   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');\""

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}"

   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)

   2. Download the .vsix extension:

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

   3. Create an extension namespace:

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

   4. Publish the extension:

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

   5. Delete the downloaded extension file:

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

      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"

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

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}"