diff --git a/modules/administration-guide/examples/snip_che-non-default-vsx-registry-instance.adoc b/modules/administration-guide/examples/snip_che-non-default-vsx-registry-instance.adoc index 33fe46d511..5804cbb69b 100644 --- a/modules/administration-guide/examples/snip_che-non-default-vsx-registry-instance.adoc +++ b/modules/administration-guide/examples/snip_che-non-default-vsx-registry-instance.adoc @@ -1 +1 @@ -* The embedded instance of the Open VSX registry that runs in the `plugin-registry` pod of {prod-short} to support air-gapped, offline, and proxy-restricted environments. The embedded Open VSX registry contains only a subset of the extensions published on link:https://open-vsx.org[open-vsx.org]. This subset is xref:adding-or-removing-extensions-in-the-embedded-open-vsx-registry-instance[customizable]. +* The embedded instance of the Open VSX registry that runs in the `plugin-registry` pod of {prod-short} to support air-gapped, offline, and proxy-restricted environments. The embedded Open VSX registry contains only a subset of the extensions published on link:https://open-vsx.org[open-vsx.org]. You can customize this subset xref:adding-or-removing-extensions-in-a-workspace_{context}[using a workspace] or xref:adding-or-removing-extensions-on-linux_{context}[using a Linux operating system]. \ No newline at end of file diff --git a/modules/administration-guide/examples/snip_che-steps-to-add-or-remove-extensions-in-openvsx-sync-json.adoc b/modules/administration-guide/examples/snip_che-steps-to-add-or-remove-extensions-in-openvsx-sync-json.adoc deleted file mode 100644 index 132aa13fae..0000000000 --- a/modules/administration-guide/examples/snip_che-steps-to-add-or-remove-extensions-in-openvsx-sync-json.adoc +++ /dev/null @@ -1,3 +0,0 @@ -... Download or fork and clone the link:https://github.com/eclipse-che/che-plugin-registry[plugin registry repository]. - -... For each extension that you need to add or remove, edit link:https://github.com/eclipse-che/che-plugin-registry/blob/main/openvsx-sync.json[the `openvsx-sync.json` file]: diff --git a/modules/administration-guide/examples/snip_che-steps-to-build-custom-plugin-registry-in-workspace.adoc b/modules/administration-guide/examples/snip_che-steps-to-build-custom-plugin-registry-in-workspace.adoc deleted file mode 100644 index fc829f216a..0000000000 --- a/modules/administration-guide/examples/snip_che-steps-to-build-custom-plugin-registry-in-workspace.adoc +++ /dev/null @@ -1,14 +0,0 @@ -... Start a workspace using the link:https://github.com/eclipse-che/che-plugin-registry[plugin registry repository]. - -... Open a terminal and check out the Git tag that corresponds to your {prod-short} version (for example, `7.87.0`): -+ -[source] ----- -git checkout $PRODUCT_VERSION ----- - -... Open the `che-plugin-registry/openvsx-sync.json` file and add or remove extensions. - -... Execute `1. Build and Publish a Custom Plugin Registry` task in the workspace (Terminal -> Run Task... -> devfile -> 1. Build and Publish a Custom Plugin Registry). - -... Execute `2. Configure Che to use the Custom Plugin Registry` task in the workspace (Terminal -> Run Task... -> devfile -> 2. Configure Che to use the Custom Plugin Registry). diff --git a/modules/administration-guide/pages/extensions-for-microsoft-visual-studio-code-open-source.adoc b/modules/administration-guide/pages/extensions-for-microsoft-visual-studio-code-open-source.adoc index 7831e77d4f..bf8486108d 100644 --- a/modules/administration-guide/pages/extensions-for-microsoft-visual-studio-code-open-source.adoc +++ b/modules/administration-guide/pages/extensions-for-microsoft-visual-studio-code-open-source.adoc @@ -7,9 +7,9 @@ [id="extensions-for-microsoft-visual-studio-code-open-source"] = Extensions for Microsoft Visual Studio Code - Open Source -To manage extensions, link:https://github.com/microsoft/vscode[this IDE] uses one of these link:https://open-vsx.org/about[Open VSX] registry instances: +To manage extensions, {prod-short} uses one of the following Open VSX registry instances: -* The embedded instance of the Open VSX registry that runs in the `plugin-registry` pod of {prod-short} to support air-gapped, offline, and proxy-restricted environments. The embedded Open VSX registry contains only a subset of the extensions published on link:https://open-vsx.org[open-vsx.org]. This subset is xref:adding-or-removing-extensions-in-the-embedded-open-vsx-registry-instance[customizable]. +* The embedded instance of the Open VSX registry that runs in the `plugin-registry` pod of {prod-short} to support air-gapped, offline, and proxy-restricted environments. The embedded Open VSX registry contains only a subset of the extensions published on link:https://open-vsx.org[open-vsx.org]. You can customize this subset xref:adding-or-removing-extensions-in-a-workspace_{context}[using a workspace] or xref:adding-or-removing-extensions-on-linux_{context}[using a Linux operating system]. * The public link:https://open-vsx.org[open-vsx.org] registry that is accessed over the internet. @@ -19,4 +19,6 @@ include::example$snip_{project-context}-default-vsx-registry.adoc[] include::partial$proc_selecting-an-open-vsx-registry-instance.adoc[leveloffset=+1] -include::partial$proc_adding-or-removing-extensions-in-the-embedded-open-vsx-registry-instance.adoc[leveloffset=+1] +include::partial$proc_adding-or-removing-extensions-in-a-workspace.adoc[leveloffset=+1] + +include::partial$proc_adding-or-removing-extensions-on-linux.adoc[leveloffset=+1] \ No newline at end of file diff --git a/modules/administration-guide/partials/proc_adding-or-removing-extensions-in-a-workspace.adoc b/modules/administration-guide/partials/proc_adding-or-removing-extensions-in-a-workspace.adoc new file mode 100644 index 0000000000..6517f9005c --- /dev/null +++ b/modules/administration-guide/partials/proc_adding-or-removing-extensions-in-a-workspace.adoc @@ -0,0 +1,105 @@ +:_content-type: PROCEDURE + +[id="adding-or-removing-extensions-in-a-workspace_{context}"] += Adding or removing extensions by using a {prod-short} workspace + +[role="_abstract"] +You can add or remove extensions in the embedded Open VSX registry instance directly within a {prod-short} workspace to create a custom build for your organization. + +[IMPORTANT] +==== +The embedded plugin registry will be deprecated in future releases and replaced by the Open VSX registry. Setting up an internal, on-premises Open VSX registry provides full control over the extension lifecycle, enables offline use, and improves compliance. Refer to the xref:running-the-open-vsx-on-premises.adoc[Running the Open VSX On-Premises] procedure for detailed setup instructions. +==== + +.Prerequisites + +* You are logged in to your {prod-short} instance as an administrator. +* You have started a workspace using the link:https://github.com/eclipse-che/che-plugin-registry[plugin registry repository]. +* You have created a link:https://access.redhat.com/terms-based-registry/[Red Hat Registry Service Account] and have the username and token available. +* For IBM Power (`ppc64le`) and IBM Z (`s390x`) architectures, you must build the custom plugin registry locally on the corresponding hardware. +* (Optional) You can rebuild the container based on the latest tag or SHA to get the latest security fixes after a {prod-short} update. + +.Procedure + +. Open a terminal in your workspace. + +. Check out the Git tag that corresponds to your {prod-short} version: ++ +[source,bash,subs="+quotes"] +---- +$ git checkout ____ +---- + +. Identify the publisher and extension name for each extension you want to add: +.. Find the extension on the link:https://open-vsx.org/[Open VSX registry website]. +.. Copy the URL of the extension's listing page. +.. Extract the `` and `` from the URL: ++ +[subs="+quotes"] +---- +https://open-vsx.org/extension/____/____ +---- ++ +[TIP] +==== +If the extension is only available from link:https://marketplace.visualstudio.com/VSCode[Microsoft Visual Studio Marketplace], but not link:https://open-vsx.org[Open VSX], you can ask the extension publisher to publish it on link:https://open-vsx.org[open-vsx.org] according to these link:https://github.com/eclipse/openvsx/wiki/Publishing-Extensions#how-to-publish-an-extension[instructions], potentially using this link:https://github.com/marketplace/actions/publish-vs-code-extension[GitHub action]. + +If the extension publisher is unavailable or unwilling to publish the extension to link:https://open-vsx.org[open-vsx.org], and if there is no Open VSX equivalent of the extension, consider link:https://github.com/open-vsx/publish-extensions/issues[reporting an issue] to the Open VSX team. +==== + +. Open the `openvsx-sync.json` file in the repository. + +. Add or remove extensions using the following JSON syntax: ++ +[source,json,subs="+quotes"] +---- +{ + "id": "____.____", + "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: + +[source,json,subs="+quotes"] +---- +{ + "id": "____.____", + "download": "____", + "version": "____" +} +---- + +Read the link:https://aka.ms/vsmarketplace-ToU[Terms of Use] for the link:https://marketplace.visualstudio.com/VSCode[Microsoft Visual Studio Marketplace] before using its resources. +==== + +. Log in to the Red Hat registry: +.. Navigate to *Terminal* -> *Run Task...* -> *devfile*. +.. Run the *1. Login to registry.redhat.io* task. +.. Enter your Red Hat Registry Service Account credentials when prompted. + +. Build and publish the custom plugin registry: +.. Navigate to *Terminal* -> *Run Task...* -> *devfile*. +.. 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 {prod-short}. Update it if necessary. +==== + +. Configure {prod-short} to use the custom plugin registry: +.. Navigate to *Terminal* -> *Run Task...* -> *devfile*. +.. Run the *3. Configure Che to use the Custom Plugin Registry* task. + +.Verification + +. Check that the `plugin-registry` pod has restarted and is running. +. Restart your workspace. +. Open the *Extensions* view in the IDE and verify that your added extensions are available. + +.Additional resources + +* link:https://github.com/eclipse-che/che-plugin-registry[Plugin registry repository] +* xref:running-the-open-vsx-on-premises.adoc[Running the Open VSX On-Premises] diff --git a/modules/administration-guide/partials/proc_adding-or-removing-extensions-in-the-embedded-open-vsx-registry-instance.adoc b/modules/administration-guide/partials/proc_adding-or-removing-extensions-in-the-embedded-open-vsx-registry-instance.adoc deleted file mode 100644 index 4b42b04c2c..0000000000 --- a/modules/administration-guide/partials/proc_adding-or-removing-extensions-in-the-embedded-open-vsx-registry-instance.adoc +++ /dev/null @@ -1,135 +0,0 @@ -:_content-type: PROCEDURE - -[id="adding-or-removing-extensions-in-the-embedded-open-vsx-registry-instance"] -= Adding or removing extensions in the embedded Open VSX registry instance - -[IMPORTANT] -==== -You can manage Visual Studio Code extensions by setting up an internal, on-premises Open VSX Registry. This approach provides full control over the extension lifecycle, enables offline use, and improves compliance. The embedded plugin registry is deprecated; the Open VSX Registry is its successor. See xref:running-the-open-vsx-on-premises.adoc[Running the Open VSX Registry on premises] for detailed setup instructions. -==== - -You can add or remove extensions in the embedded Open VSX registry instance. This results in a custom build of the Open VSX registry that can be used in your organization’s workspaces. - -pass:[] - -TIP: To get the latest security fixes after a {prod-short} update, rebuild your container based on the latest tag or SHA. - -pass:[] - -.Procedure - -. Get the publisher and extension name of each chosen extension: - -.. Find the extension on the link:https://open-vsx.org/[Open VSX registry website] and copy the URL of the extension's listing page and extension's version. - -.. Extract the ____ and ____ name from the copied URL: -+ -[subs="+quotes"] ----- -https://open-vsx.org/extension/____/____ ----- -+ -[TIP] -==== - -If the extension is only available from link:https://marketplace.visualstudio.com/VSCode[Microsoft Visual Studio Marketplace], but not link:https://open-vsx.org[Open VSX], you can ask the extension publisher to also publish it on link:https://open-vsx.org[open-vsx.org] according to these link:https://github.com/eclipse/openvsx/wiki/Publishing-Extensions#how-to-publish-an-extension[instructions], potentially using this link:https://github.com/marketplace/actions/publish-vs-code-extension[GitHub action]. - -If the extension publisher is unavailable or unwilling to publish the extension to link:https://open-vsx.org[open-vsx.org], and if there is no Open VSX equivalent of the extension, consider link:https://github.com/open-vsx/publish-extensions/issues[reporting an issue] to the Open VSX team. - -==== - -. 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 {prod-short}. - -==== - -.. Using {prod-short} instance: -+ -[IMPORTANT] -==== -For IBM Power (`ppc64le`) and IBM Z (`s390x`), the custom plugin registry is expected to be built locally on the corresponding architecture. -==== - -... Log in to your {prod-short} instance as an administrator. - -include::example$snip_{project-context}-steps-to-build-custom-plugin-registry-in-workspace.adoc[] - -.. Using Linux operating system: -+ -[TIP] -==== - -* Podman and NodeJS version 18.20.3 or higher should be installed in the system. - -==== - -include::example$snip_{project-context}-steps-to-add-or-remove-extensions-in-openvsx-sync-json.adoc[] - -** 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: -+ -[source,json,subs="+quotes"] ----- - { - "id": "____.____", - "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: -+ -[source,json,subs="+quotes"] ----- - { - "id": "____.____", - "download": "____", - "version": "____" - } ----- - -* Read the link:https://aka.ms/vsmarketplace-ToU[Terms of Use] for the link:https://marketplace.visualstudio.com/VSCode[Microsoft Visual Studio Marketplace] before using its resources. - -==== - -... Build the plugin registry container image and publish it to a container registry such as link:https://quay.io/[quay.io]: - -.... {empty} -+ -[subs="+attributes,+quotes"] ----- -$ ./build.sh -o ____ -r quay.io -t custom ----- - -.... {empty} -+ -[subs="+attributes,+quotes"] ----- -$ {docker-cli} push quay.io/____ ----- - -... Edit the `CheCluster` custom resource in your organization's cluster to point to the image (for example, on link:https://quay.io/[quay.io]) and save the changes: -+ -[source,yaml,subs="+quotes"] ----- -spec: - components: - pluginRegistry: - deployment: - containers: - - image: quay.io/____ - openVSXURL: '' ----- - -.Verification - -. Check that the `plugin-registry` pod has restarted and is running. - -. Restart the workspace and check the available extensions in the *Extensions* view of the workspace IDE. diff --git a/modules/administration-guide/partials/proc_adding-or-removing-extensions-on-linux.adoc b/modules/administration-guide/partials/proc_adding-or-removing-extensions-on-linux.adoc new file mode 100644 index 0000000000..23ca6af54d --- /dev/null +++ b/modules/administration-guide/partials/proc_adding-or-removing-extensions-on-linux.adoc @@ -0,0 +1,131 @@ +:_content-type: PROCEDURE + +[id="adding-or-removing-extensions-on-linux_{context}"] += Adding or removing extensions by using a Linux operating system + +[role="_abstract"] +You can build and publish a custom plugin registry using the Linux command line. This results in a custom build of the Open VSX registry that can be used in your organization's workspaces. + +.Prerequisites + +* Podman is installed. +* Node.js version 18.20.3 or higher is installed. +* You have created a link:https://access.redhat.com/terms-based-registry/[Red Hat Registry Service Account] and have the username and token available. +* You have read the link:https://aka.ms/vsmarketplace-ToU[Terms of Use] for the link:https://marketplace.visualstudio.com/VSCode[Microsoft Visual Studio Marketplace] before using its resources. +* (Optional) You can rebuild the container based on the latest tag or SHA to get the latest security fixes after a {prod-short} update. + +.Procedure + +. Clone the plugin registry repository: ++ +[source,bash] +---- +$ git clone https://github.com/eclipse-che/che-plugin-registry.git +---- + +. Change to the plugin registry directory: ++ +[source,bash] +---- +$ cd che-plugin-registry +---- + +. Check out the Git tag that corresponds to your {prod-short} version: ++ +[source,bash,subs="+quotes"] +---- +$ git checkout ____ +---- + +. Log in to the Red Hat registry: ++ +[source,bash] +---- +$ podman login registry.redhat.io +---- + +. Identify the publisher and extension name for each extension you want to add: +.. Find the extension on the link:https://open-vsx.org/[Open VSX registry website]. +.. Copy the URL of the extension's listing page. +.. Extract the `` and `` from the URL: ++ +[subs="+quotes"] +---- +https://open-vsx.org/extension/____/____ +---- ++ +[TIP] +==== +If the extension is only available from link:https://marketplace.visualstudio.com/VSCode[Microsoft Visual Studio Marketplace], but not link:https://open-vsx.org[Open VSX], you can ask the extension publisher to publish it on link:https://open-vsx.org[open-vsx.org] according to these link:https://github.com/eclipse/openvsx/wiki/Publishing-Extensions#how-to-publish-an-extension[instructions], potentially using this link:https://github.com/marketplace/actions/publish-vs-code-extension[GitHub action]. + +If the extension publisher is unavailable or unwilling to publish the extension to link:https://open-vsx.org[open-vsx.org], and if there is no Open VSX equivalent of the extension, consider link:https://github.com/open-vsx/publish-extensions/issues[reporting an issue] to the Open VSX team. +==== + +. Open the `openvsx-sync.json` file. + +. Add or remove extensions using the following JSON syntax: ++ +[source,json,subs="+quotes"] +---- +{ + "id": "____.____", + "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: + +[source,json,subs="+quotes"] +---- +{ + "id": "____.____", + "download": "____", + "version": "____" +} +---- +==== + +. Build the plugin registry container image: ++ +[source,bash,subs="+quotes"] +---- +$ ./build.sh -o ____ -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 {prod-short}. Update it if necessary. +==== + +. Push the image to a container registry such as link:https://quay.io/[quay.io]: ++ +[source,bash,subs="+quotes"] +---- +$ podman push quay.io/____/plugin_registry:custom +---- + +. Edit the `CheCluster` custom resource in your organization's cluster to point to the image and save the changes: ++ +[source,yaml,subs="+quotes"] +---- +spec: + components: + pluginRegistry: + deployment: + containers: + - image: quay.io/____/plugin_registry:custom + openVSXURL: '' +---- + +.Verification + +. Check that the `plugin-registry` pod has restarted and is running. +. Restart your workspace. +. Open the *Extensions* view in the IDE and verify that your added extensions are available. + +.Additional resources + +* link:https://github.com/eclipse-che/che-plugin-registry[Plugin registry repository] +* xref:running-the-open-vsx-on-premises.adoc[Running the Open VSX On-Premises] diff --git a/modules/administration-guide/partials/proc_selecting-an-open-vsx-registry-instance.adoc b/modules/administration-guide/partials/proc_selecting-an-open-vsx-registry-instance.adoc index 617d9581ee..984f3be017 100644 --- a/modules/administration-guide/partials/proc_selecting-an-open-vsx-registry-instance.adoc +++ b/modules/administration-guide/partials/proc_selecting-an-open-vsx-registry-instance.adoc @@ -1,19 +1,25 @@ -:_content-type: CONCEPT +:_content-type: PROCEDURE -[id="selecting-an-open-vsx-registry-instance"] +[id="selecting-an-open-vsx-registry-instance_{context}"] = Selecting an Open VSX registry instance include::example$snip_{project-context}-default-vsx-registry.adoc[] -If the default Open VSX registry instance is not what you need, you can select one of the following instances: +If the default Open VSX registry instance does not meet your requirements, you can select one of the following instances: include::example$snip_{project-context}-non-default-vsx-registry-instance.adoc[] * A standalone Open VSX registry instance that is deployed on a network accessible from {prod-short} workspace pods. +.Prerequisites + +* You have administrator access to the cluster where {prod-short} is deployed. +* You have the `oc` CLI tool installed if you are using the command line. + .Procedure -* Edit the `openVSXURL` value in the `CheCluster` custom resource: +. Log on to the cluster as an administrator. +. Edit the `CheCluster` custom resource to update the `openVSXURL` value: + [source,yaml,subs="+quotes"] ---- @@ -23,18 +29,19 @@ spec: openVSXURL: "____" # <1> ---- <1> For example: `openVSXURL: "pass:c,a,q[https://open-vsx.org]"`. -+ -[WARNING] -==== -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 link:https://github.com/EclipseFdn/open-vsx.org/wiki/rate-limiting[Rate Limits and Usage Tiers] and the link:https://github.com/EclipseFdn/open-vsx.org/wiki[open-vsx.org wiki]. -==== -+ + +.Save the changes to the custom resource. + [IMPORTANT] ==== -* Using link:https://open-vsx.org[https://open-vsx.org] is not recommended in an air-gapped environment, isolated from the internet. In order 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. - -* To select the embedded Open VSX registry instance in the `plugin-registry` pod, use `openVSXURL: ''`. You can xref:adding-or-removing-extensions-in-the-embedded-open-vsx-registry-instance[customize the list of included extensions]. +* Do not use link:https://open-vsx.org[https://open-vsx.org] in an air-gapped environment or an environment that is isolated from the internet. To reduce the risk of malware infections and unauthorized access to your code, use the embedded or a self-hosted Open VSX registry with a curated set of extensions. -* You can also point `openVSXURL` at the URL of a standalone Open VSX registry instance if its URL is accessible from within your organization's cluster and not blocked by a proxy. +* To select the embedded Open VSX registry instance in the `plugin-registry` pod, use `openVSXURL: ''`. You can customize the list of included extensions xref:adding-or-removing-extensions-in-a-workspace_{context}[using a workspace] or xref:adding-or-removing-extensions-on-linux_{context}[using a Linux operating system]. +* You can point `openVSXURL` to the URL of a standalone Open VSX registry instance if the URL is accessible from within the organization's cluster and not blocked by a proxy. ==== + +.Verification + +. Confirm that the `plugin-registry` pod has restarted. +. Open a workspace and verify that extensions are available from the selected registry instance in the *Extensions* view. \ No newline at end of file