Chapter 16. Managing 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. See Section 16.3, “Add or remove extensions in an OpenShift Dev Spaces workspace” or Section 16.4, “Add or remove extensions from the Linux command line”.
   • 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 workspace.

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 new OpenShift project for Open VSX:

   oc new-project openvsx

2. Save the openvsx-deployment-no-es.yml deployment template 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.28 \
      | oc apply -f -

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

   {orch-cli} 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 a Personal Access Token (PAT) to the database.

   1. Find the PostgreSQL pod:

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

   2. Insert the username into the Open VSX 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 Open VSX 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, notified) VALUES (1001, 1001, 'eclipse_che_token', true, current_timestamp, current_timestamp, 'extensions publisher', false);\""

      Important

      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.

6. Configure OpenShift Dev Spaces to use the internal Open VSX registry:

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

   Tip

   For detailed instructions on configuring the Open VSX registry URL, see Section 16.2, “Configure the Open VSX registry URL”.

7. Publish a Visual Studio Code extension from a .vsix file. The Open VSX registry does not provide any extension by default. You need the extension publisher 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=$({orch-cli} 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 publisher:

      oc exec -n openvsx "${OVSX_POD_NAME}" -- bash -c "ovsx create-namespace <EXTENSION_PUBLISHER_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: Publish multiple extensions from a list. Update the deploy/openshift/extensions.txt file with the download URLs of each .vsix file, then publish all listed extensions:

   while IFS= read -r url; do
     oc exec -n openvsx "${OVSX_POD_NAME}" -- bash -c "wget -O /tmp/extension.vsix '$url' && ovsx publish /tmp/extension.vsix && rm /tmp/extension.vsix"
   done < deploy/openshift/extensions.txt

Procedure

1. Create a new OpenShift project for Open VSX:

   oc new-project openvsx

2. Clone the Open VSX repository and navigate to the deployment directory:

   git clone https://github.com/eclipse-openvsx/openvsx.git &&
   cd openvsx/deploy/openshift

3. Build and push the Open VSX server image:

   export REGISTRY=<registry_hostname>
   export NAMESPACE=<registry_namespace>
   export OPENVSX_VERSION=<openvsx_version>
   export OPENVSX_SERVER_IMAGE=$\{REGISTRY}/$\{NAMESPACE}/openvsx-server:$\{OPENVSX_VERSION}
   
   podman build -t "$\{OPENVSX_SERVER_IMAGE}" \
     --build-arg "OPENVSX_VERSION=$\{OPENVSX_VERSION}" -f openvsx.Dockerfile . &&
   podman login "$\{REGISTRY}" &&
   podman push "$\{OPENVSX_SERVER_IMAGE}"

   where:

   <registry_hostname>

   The container registry hostname. For example: quay.io.

   <registry_namespace>

   Your organization or account in the registry. For example: myuser.

   <openvsx_version>

   The Open VSX version tag to build. For example: v0.33.0. Available versions are listed on the Open VSX releases page.

   Important

   Ensure that the image is publicly accessible or that the cluster can pull from the registry with appropriate credentials.

4. Build and push the Open VSX CLI image:

   export OPENVSX_CLI_VERSION=<cli_version>
   export OPENVSX_CLI_IMAGE=$\{REGISTRY}/$\{NAMESPACE}/openvsx-cli:$\{OPENVSX_CLI_VERSION}
   
   podman build -t "$\{OPENVSX_CLI_IMAGE}" \
     --build-arg "OVSX_VERSION=$\{OPENVSX_CLI_VERSION}" -f cli.Dockerfile . &&
   podman push "$\{OPENVSX_CLI_IMAGE}"

   where:

   <cli_version>

   The Open VSX CLI version. For example: 0.10.9.

5. Deploy Open VSX with the custom images:

   {orch-cli} process -f openvsx-deployment.yml \
     -p OPENVSX_SERVER_IMAGE="${OPENVSX_SERVER_IMAGE}" \
     -p OPENVSX_CLI_IMAGE="${OPENVSX_CLI_IMAGE}" \
     | {orch-cli} apply -f -

6. Verify that all pods in the openvsx project are running and ready:

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

7. Add an Open VSX user with a Personal Access Token (PAT) to the database.

   1. Find the PostgreSQL pod:

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

   2. Insert the username into the Open VSX 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 Open VSX 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, notified) VALUES (1001, 1001, 'eclipse_che_token', true, current_timestamp, current_timestamp, 'extensions publisher', false);\""

      Important

      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.

8. Configure OpenShift Dev Spaces to use the internal Open VSX registry:

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

9. Publish a Visual Studio Code extension from a .vsix file. The Open VSX registry does not provide any extension by default.

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

      export OVSX_POD_NAME=$({orch-cli} 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 publisher:

      oc exec -n openvsx "${OVSX_POD_NAME}" -- bash -c "ovsx create-namespace <EXTENSION_PUBLISHER_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"

10. Optional: Publish multiple extensions from a list. Update the deploy/openshift/extensions.txt file with the download URLs of each .vsix file, then publish all listed extensions:

    while IFS= read -r url; do
      oc exec -n openvsx "${OVSX_POD_NAME}" -- bash -c "wget -O /tmp/extension.vsix '$url' && ovsx publish /tmp/extension.vsix && rm /tmp/extension.vsix"
    done < deploy/openshift/extensions.txt

Procedure

1. Start a workspace by using the 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 start the workspace on these architectures, remove the elasticsearch component from the devfile. Alternatively, use the Section 16.5, “Deploy Open VSX with a pre-built image” procedure to deploy Open VSX without starting a workspace.

   Tip

   The environment, including all necessary commands, is defined in the .devfile.yaml file. The numbered task names (such as 2.1., 2.4.1.) are labels defined in the devfile. Use these exact names to locate each task in the Terminal > Run Task…​ menu.

2. Create a new project for Open VSX.

   Select Terminal > Run Task…​ > devfile and run the 2.1. Create Namespace for OpenVSX task. A new project named openvsx is created on the cluster.

3. Deploy Open VSX with the OpenShift Dev Spaces pre-built image.

   Select Terminal > Run Task…​ > devfile and run the 2.4.1. Deploy Custom OpenVSX task. When the task prompts for the Open VSX server image, enter registry.redhat.io/devspaces/openvsx-rhel9:3.28.

   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.

   Tip

   All deployment parameters are described in the deploy/openshift/openvsx-deployment-no-es.yml file. The template includes default values such as OVSX_PAT_BASE64.

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

   Select Terminal > Run Task…​ > devfile and run the 2.5. Add OpenVSX user with PAT to the DB task. The task prompts you for the Open VSX username and user PAT. Press 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 you update OVSX_PAT_BASE64, use the new decoded value as the user PAT.

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

   Select Terminal > Run Task…​ > devfile and run the 2.6. Configure Che to use the internal OpenVSX registry task. This task patches the CheCluster custom resource to use the deployed Open VSX registry URL.

6. Publish a Visual Studio Code extension from a .vsix file.

   Select Terminal > Run Task…​ > devfile and run the 2.8. Publish a VS Code Extension from a VSIX file task. The task prompts you to provide the extension publisher name and the path to the .vsix file.

7. Optional: Publish a predefined list of extensions.

   Update the deploy/openshift/extensions.txt file with the download URLs of each .vsix file, then select Terminal > Run Task…​ > devfile and run the 2.9. Publish list of VS Code Extensions task.

Procedure

1. Delete the public route for the Open VSX registry:

   oc delete route internal -n openvsx

2. Update the CheCluster custom resource to use the internal service DNS URL:

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

3. Restart any running workspaces to apply the new registry URL.

Procedure

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

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

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

   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, notified) VALUES (1002, 1002, '<your_admin_token>', true, current_timestamp, current_timestamp, 'Admin API Token', false);\""

   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. Open a command prompt in the PostgreSQL pod and connect to the database:

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

   Inside the pod, run psql:

   psql

   At the postgres=# prompt, connect to the database:

   \c openvsx

   You are now connected to the openvsx database as the postgres user.

2. Find the publisher ID and extension ID:

   Identify the extension publisher. Replace <publisher_name> with the actual publisher name:

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

   Identify the extension ID. Replace <publisher_id> and <extension_name> with the values from the previous query:

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

   Note the ID of the extension to use as <extension_id> in the next steps.

3. Optional: Preview extension versions and file resources:

   Preview the versions:

   SELECT id, version, pre_release, semver_pre_release, semver_is_pre_release FROM extension_version WHERE extension_id = <extension_id> ORDER BY timestamp DESC;

   Preview the file resources:

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

   If the storage_type value is local, you must also remove the extension files from the file system on the Open VSX server pod.

4. Delete the extension from the database:

   Run the following commands in a single transaction. Replace <extension_id> with the extension ID from step 2.

   BEGIN;
   -- 1. Delete all file resources for the extension
   DELETE FROM file_resource WHERE extension_id = <extension_id>;
   -- 2. Delete all extension reviews
   DELETE FROM extension_review WHERE extension_id = <extension_id>;
   -- 3. Delete all versions of the extension
   DELETE FROM extension_version WHERE extension_id = <extension_id>;
   -- 4. Delete the extension entry itself
   DELETE FROM extension WHERE id = <extension_id>;
   COMMIT;

   Important

   Run these commands in order within one transaction. Do not skip the COMMIT command, or the system does not apply the changes.

5. If the extension used local storage, remove the extension files from the Open VSX server pod:

   Get the Open VSX server pod name:

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

   Delete the extension folder:

   oc exec -it $OPENVSX_POD_NAME -n openvsx -- /bin/bash -c "rm -rf /tmp/extensions/<publisher>/<extension>"