Chapter 19. Manage IDE extensions

Procedure

1. Edit the CheCluster custom resource to update the openVSXURL value:

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

   where:

   <url_of_an_open_vsx_registry_instance>

   The URL of the Open VSX registry instance. For example: openVSXURL: "https://open-vsx.org".

   • To select the embedded Open VSX registry instance in the plugin-registry pod, use openVSXURL: ''. You can customize the list of included extensions using a workspace or using a Linux operating system.
   • You can also point openVSXURL at the URL of a standalone Open VSX registry instance. The URL must be accessible from within your organization’s cluster and not blocked by a proxy.

   Note

   To ensure the stability and performance of the community-supported Open VSX Registry, API usage is organized into defined tiers. The Eclipse Foundation implements these limits to protect infrastructure from high-frequency automated traffic and to provide consistent service quality for all users. For more information, see Rate Limits and Usage Tiers and the open-vsx.org wiki.

   Important

   Using https://open-vsx.org is not recommended in an air-gapped environment, isolated from the internet. To reduce the risk of malware infections and unauthorized access to your code, use the embedded or self-hosted Open VSX registry with a curated set of extensions.

   Warning

   Due to the dedicated Microsoft Terms of Use, Visual Studio Code Marketplace is not supported by Red Hat OpenShift Dev Spaces.

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 and not Open VSX, ask the extension publisher to publish it on open-vsx.org. See the publishing instructions and the GitHub action.

      If the publisher is unavailable or unwilling, and no Open VSX equivalent exists, consider reporting an issue to the Open VSX team.

2. Open the openvsx-sync.json file in the repository.

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

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

   Tip

   If you have a closed-source or internal-only extension, you can add it directly from a .vsix file. Use 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 and not Open VSX, ask the extension publisher to publish it on open-vsx.org. See the publishing instructions and the GitHub action.

      If the publisher is unavailable or unwilling, and no Open VSX equivalent exists, 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 or internal-only extension, you can add it directly from a .vsix file. Use 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.

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. Create a workspace by using the Eclipse Open VSX repository v0.31.0.

   Important

   Use the v0.31.0 tag specifically to avoid database schema compatibility issues. Later versions require additional database columns that are not handled by the devfile tasks.

2. Run the 2.1. Create Namespace for OpenVSX task in the workspace (Terminal > Run Task…​ > devfile > 2.1. Create Namespace for OpenVSX). A new OpenShift project with the name openvsx is created on the cluster.

3. Run the 2.4.1. Deploy Custom OpenVSX task in the workspace (Terminal > Run Task…​ > devfile > 2.4.1. Deploy Custom OpenVSX). When the task prompts for the Open VSX server image, enter registry.redhat.io/devspaces/openvsx-rhel9:3.27.1.

   After the deployment completes, the openvsx project has two components: PostgreSQL database and Open VSX server. The Open VSX UI is accessible through an exposed route in the OpenShift cluster. Deployment information is in the deploy/openshift/openvsx-deployment-no-es.yml file with default values such as OVSX_PAT_BASE64.

4. 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 prompts for the Open VSX username and user PAT. The default values are used if no custom values are entered.

   The user PAT must match the decoded value of OVSX_PAT_BASE64 specified in the deployment file. If you update OVSX_PAT_BASE64, use the new decoded value as the user PAT.

5. 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). The task patches the CheCluster custom resource to use the specified Open VSX URL for the extension registry.
6. After the openvsx-server pod is running and in the Ready state, run the 2.8. Publish a Visual Studio Code Extension from a VSIX file task to publish an extension from a .vsix file (Terminal > Run Task…​ > devfile > 2.8. Publish a Visual Studio Code Extension from a VSIX file). The command prompts for the extension’s namespace name and the path to the .vsix file.
7. Optional: To publish multiple extensions, update the deploy/openshift/extensions.txt file with the download URLs of each .vsix file, then run the 2.9. Publish list of Visual Studio Code Extensions task (Terminal > Run Task…​ > devfile > 2.9. Publish list of Visual Studio Code Extensions).

Procedure

1. Create a new OpenShift project for Open VSX:

   oc new-project openvsx

2. Save the openvsx-deployment-no-es.yml file on your file system.

3. Deploy Open VSX from the directory where you saved the file:

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

4. Verify that all pods in the openvsx namespace are running and ready:

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

5. Add an Open VSX user with PAT to the database.

   1. Find the PostgreSQL pod:

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

   2. Insert the username into the 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');\""

   3. Insert the user PAT into the 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');\""

6. 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 Section 19.2, “Configure the Open VSX registry URL” for detailed instructions on configuring the Open VSX registry URL in OpenShift Dev Spaces.

7. Publish Visual Studio Code extensions with the ovsx command. The Open VSX registry does not provide any extension by default. You need the extension namespace name and the download URL of the .vsix package.

   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"

8. Optional: Remove the public route to configure internal access to the Open VSX service:

   oc delete route internal -n openvsx

9. Optional: Set the internal Open VSX service URL so that OpenShift Dev Spaces uses internal cluster service routing instead of a public route:

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

Procedure

1. Add the Open VSX administrator user and PAT to the database:

   POD=$(oc get pods -n openvsx -l app=openvsx-db -o jsonpath='{.items[0].metadata.name}')

   oc exec -n openvsx "$POD" -- psql -d openvsx -c \
     "INSERT INTO user_data (id, login_name, role) VALUES (1002, 'openvsx-admin', 'admin');"

   oc exec -n openvsx "$POD" -- psql -d openvsx -c \
     "INSERT INTO personal_access_token (id, user_data, value, active, created_timestamp, accessed_timestamp, description) VALUES (1002, 1002, '<your_admin_token>', true, current_timestamp, current_timestamp, 'Admin API Token');"

   Note

   Use a strong, unique value for <your_admin_token> in production environments.

2. Delete an extension and all its versions:

   curl -X POST \
     "https://<your_openvsx_server_url>/admin/api/extension/<publisher>/<extension>/delete?token=<your_admin_token>"

   where:

   <your_openvsx_server_url>

   The URL of the Open VSX server.

   <publisher>

   The extension publisher name.

   <extension>

   The extension name.

   <your_admin_token>

   The PAT value created in step 1.

3. Optional: Delete a specific version of an extension:

   curl -X POST \
     -H "Content-Type: application/json" \
     -d '[{"version": "<version>", "targetPlatform": "<platform>"}]' \
     "https://<your_openvsx_server_url>/admin/api/extension/<publisher>/<extension>/delete?token=<your_admin_token>"

   You can list multiple version and platform pairs in the JSON array.

Procedure

1. Identify the PostgreSQL pod:

   POD=$(oc get pods -n openvsx -l app=openvsx-db -o jsonpath='{.items[0].metadata.name}')

2. Connect to the PostgreSQL database:

   oc exec -it -n openvsx "$POD" -- psql

   \c openvsx

3. Find the namespace ID and extension ID:

   SELECT id, name FROM namespace WHERE name = '<namespace_name>';

   SELECT id, name, namespace_id FROM extension WHERE namespace_id = <namespace_id> AND name = '<extension_name>';

4. Optional: Preview extension versions and file resources before deleting:

   SELECT id, version, target_platform FROM extension_version WHERE extension_id = <extension_id>;

   SELECT id, name, storage_type FROM file_resource WHERE extension_id = <extension_id>;

   If storage_type is local, you must also remove the files from the file system after deleting the database records.

5. Delete the extension from the database:

   BEGIN;
   DELETE FROM file_resource WHERE extension_id = <extension_id>;
   DELETE FROM extension_review WHERE extension_id = <extension_id>;
   DELETE FROM extension_version WHERE extension_id = <extension_id>;
   DELETE FROM extension WHERE id = <extension_id>;
   COMMIT;

   Important

   Run these commands in order within one transaction. Do not skip the COMMIT statement.

6. If the storage_type is local, remove the extension files from local storage:

   SERVER_POD=$(oc get pods -n openvsx -l app=openvsx-server -o jsonpath='{.items[0].metadata.name}')

   oc exec -n openvsx "$SERVER_POD" -- rm -rf /tmp/extensions/<publisher>/<extension>