diff --git a/.gitignore b/.gitignore index bed5638306..d7a37026fe 100644 --- a/.gitignore +++ b/.gitignore @@ -43,3 +43,4 @@ yarn.lock # Do not commit diagrams generated for downstream crw* +CLAUDE.md diff --git a/antora.yml b/antora.yml index 38635b88fa..323a3927d5 100644 --- a/antora.yml +++ b/antora.yml @@ -11,6 +11,7 @@ nav: - modules/upgrade/nav.adoc - modules/secure/nav.adoc - modules/optimize/nav.adoc + - modules/extend/nav.adoc - modules/administration-guide/nav.adoc - modules/extensions/nav.adoc - modules/glossary/nav.adoc @@ -29,7 +30,7 @@ asciidoc: che-plugin-registry-directory: che-plugin-registry plugin-registry-repo-url: "https://github.com/redhat-developer/che-plugin-registry" devworkspace-operator-index-disconnected-install: quay.io/devfile/devworkspace-operator-index:release-digest - devworkspace-operator-version-patch: "0.42.0" + devworkspace-operator-version-patch: "0.41.0" devworkspace: DevWorkspace devworkspace-id: devworkspace docker-cli: docker @@ -101,8 +102,8 @@ asciidoc: prod-upstream: Eclipse Che prod-url: "https://__<che_fqdn>__" prod-ver-major: "7" - prod-ver-patch: "7.120.0" - prod-ver: "7.120" + prod-ver-patch: "7.119.0" + prod-ver: "7.119" prod-workspace: che-ws prod: Eclipse Che prod2: Eclipse Che diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index 844c4820c7..c83716672e 100644 --- a/modules/administration-guide/nav.adoc +++ b/modules/administration-guide/nav.adoc @@ -43,13 +43,6 @@ *** xref:con_persistent-user-home.adoc[] ** xref:configuring-dashboard.adoc[] *** xref:configuring-getting-started-samples.adoc[] -*** xref:configuring-editors-definitions.adoc[] -*** xref:show-deprecated-editors.adoc[] -*** xref:configuring-default-editor.adoc[] -*** xref:concealing-editors.adoc[] -*** xref:configuring-editors-download-urls.adoc[] -*** xref:configuring-ai-providers.adoc[] -**** xref:ai-provider-api-key-secret-reference.adoc[] *** xref:customizing-openshift-che-branding-images.adoc[] ** xref:configuring-oauth-for-git-providers.adoc[] *** xref:configuring-oauth-2-for-github.adoc[] @@ -64,18 +57,4 @@ ** xref:devworkspace-backup.adoc[] *** xref:devworkspace-backup-integrated-openshift-registry.adoc[] *** xref:devworkspace-backup-regular-oci-registry.adoc[] -* xref:managing-ide-extensions.adoc[] -** xref:extensions-for-microsoft-visual-studio-code-open-source.adoc[] -** xref:configuring-the-open-vsx-registry-url.adoc[] -** xref:proc_deploy-open-vsx-from-source.adoc[] -** xref:proc_deploy-open-vsx-from-workspace.adoc[] -** xref:proc_configure-internal-open-vsx-access.adoc[] -** xref:proc_deleting-extension-using-openvsx-admin-api.adoc[] -** xref:proc_deleting-extension-from-postgresql-database.adoc[] -* xref:configuring-visual-studio-code.adoc[] -** xref:configuring-single-and-multiroot-workspaces.adoc[] -** xref:trusted-extensions-for-microsoft-visual-studio-code.adoc[] -** xref:default-extensions-for-microsoft-visual-studio-code.adoc[] -** xref:manage-extension-installation.adoc[] -** xref:editor-configurations-for-microsoft-visual-studio-code.adoc[] * xref:managing-workloads-using-the-che-server-api.adoc[] diff --git a/modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc b/modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc index 2d4a2989e3..6629d7d385 100644 --- a/modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc +++ b/modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc @@ -191,5 +191,5 @@ Optional. A JSON array of provider `id` values that are pre-selected in the AI S .Additional resources -* xref:configuring-ai-providers.adoc[] -* xref:ai-provider-api-key-secret-reference.adoc[] +* xref:extend:configuring-ai-providers.adoc[] +* xref:extend:ai-provider-api-key-secret-reference.adoc[] diff --git a/modules/administration-guide/pages/concealing-editors.adoc b/modules/administration-guide/pages/concealing-editors.adoc deleted file mode 100644 index e4c0160410..0000000000 --- a/modules/administration-guide/pages/concealing-editors.adoc +++ /dev/null @@ -1,36 +0,0 @@ -:_content-type: PROCEDURE -:description: Concealing editors in the Dashboard UI -:keywords: administration guide, concealing, dashboard, editors -:navtitle: Concealing editors - -[id="concealing-editors"] -= Concealing editors - -Learn how to conceal {prod-short} editors. This is useful when you want to hide selected editors from the Dashboard UI, for example hide the IntelliJ IDEA Ultimate and have only Visual Studio Code - Open Source visible. - -.Prerequisites - -* An active `{orch-cli}` session with administrative permissions to the {orch-name} cluster. See {orch-cli-link}. - -* `jq`. See link:https://stedolan.github.io/jq/download/[Downloading `jq`]. - -.Procedure - -include::example$snip_che-editor-id-list.adoc[] - -. Configure the `CheCluster` Custom Resource. See xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. -+ -[source,yaml] ----- -spec: - components: - dashboard: - deployment: - containers: - - env: - - name: CHE_HIDE_EDITORS_BY_ID - value: 'che-incubator/che-webstorm-server/latest, che-incubator/che-webstorm-server/next' <1> ----- -<1> A string containing comma-separated IDs of editors to hide. - -include::example$snip_{project-context}-concealing-editors-additional-resources.adoc[] diff --git a/modules/administration-guide/pages/configuring-dashboard.adoc b/modules/administration-guide/pages/configuring-dashboard.adoc index 56047f6105..8a7e2cbae9 100644 --- a/modules/administration-guide/pages/configuring-dashboard.adoc +++ b/modules/administration-guide/pages/configuring-dashboard.adoc @@ -9,15 +9,15 @@ * xref:configuring-getting-started-samples.adoc[] -* xref:configuring-editors-definitions.adoc[] +* xref:extend:configuring-editors-definitions.adoc[] * xref:configuring-editors-download-urls.adoc[] -* xref:show-deprecated-editors.adoc[] +* xref:extend:show-deprecated-editors.adoc[] -* xref:configuring-default-editor.adoc[] +* xref:extend:configuring-default-editor.adoc[] -* xref:concealing-editors.adoc[] +* xref:extend:concealing-editors.adoc[] * xref:customizing-openshift-che-branding-images.adoc[] diff --git a/modules/administration-guide/pages/configuring-editors-download-urls.adoc b/modules/administration-guide/pages/configuring-editors-download-urls.adoc deleted file mode 100644 index ea073a5620..0000000000 --- a/modules/administration-guide/pages/configuring-editors-download-urls.adoc +++ /dev/null @@ -1,43 +0,0 @@ -:_content-type: PROCEDURE -:description: Configuring editors download urls -:keywords: administration guide, dashboard, editors -:navtitle: Configuring editors download urls - -[id="configuring-editors-download-urls"] -= Configuring editors download URLs - -This procedure describes how to configure download URLs for editors. This feature is valuable in air-gapped environments where editors cannot be retrieved from the public internet. - -[IMPORTANT] -==== -This configuration option is currently supported only for JetBrains editors. Do not use this feature with other editor types. -==== - -.Prerequisites - -* You have an active `_orch-cli_` session with administrative permissions to the `{orch-name}` cluster. For more information, see {orch-cli-link}. - -* `jq`. See link:https://stedolan.github.io/jq/download/[Downloading `jq`]. - -.Procedure - -include::example$snip_che-editor-id-list.adoc[] - -. Configure the download URLs for editors: -+ -[source,subs="+quotes,+attributes"] ----- -{orch-cli} patch checluster/{prod-checluster} \ - --namespace {prod-namespace} \ - --type='merge' \ - -p '{ - "spec": { - "devEnvironments": { - "editorsDownloadUrls": [ - { "editor": "publisher1/editor-name1/version1", "url": "https://example.com/editor1.tar.gz" }, - { "editor": "publisher2/editor-name2/version2", "url": "https://example.com/editor2.tar.gz" } - ] - } - } - }' ----- diff --git a/modules/administration-guide/pages/configuring-single-and-multiroot-workspaces.adoc b/modules/administration-guide/pages/configuring-single-and-multiroot-workspaces.adoc deleted file mode 100644 index cd4004999c..0000000000 --- a/modules/administration-guide/pages/configuring-single-and-multiroot-workspaces.adoc +++ /dev/null @@ -1,91 +0,0 @@ -:_content-type: PROCEDURE -:description: Configuring single and multiroot workspaces -:keywords: singleroot, multiroot, workspace -:navtitle: Configuring single and multiroot workspaces -// :page-aliases: - -[id="configuring-single-and-multiroot-workspaces"] -= Configuring single and multi root workspaces - -With the multi-root workspace feature, you can work with multiple project folders in the same workspace. This is useful when you are working on several related projects at once, such as product documentation and product code repositories. - -TIP: See link:https://code.visualstudio.com/docs/editing/workspaces/workspaces[What is a VS Code workspace] for better understanding and authoring the workspace files. - -[NOTE] -==== -The workspace is set to open in multi-root mode by default. -==== - -Once workspace is started, the `/projects/.code-workspace` workspace file is generated. The workspace file will contain all the projects described in the devfile. - -[source,json] ----- -{ - "folders": [ - { - "name": "project-1", - "path": "/projects/project-1" - }, - { - "name": "project-2", - "path": "/projects/project-2" - } - ] -} ----- - -If the workspace file already exist, it will be updated and all missing projects will be taken from the devfile. -If you remove a project from the devfile, it will be left in the workspace file. - -You can change the default behavior and provide your own workspace file or switch to a single-root workspace. - -.Procedure - -* Provide your own workspace file. - -** Put a workspace file with the name `.code-workspace` into the root of your repository. After workspace creation, the Visual Studio Code - Open Source ("Code - OSS") will use the workspace file as it is. -+ -[source,json] ----- -{ - "folders": [ - { - "name": "project-name", - "path": "." - } - ] -} ----- -+ -[IMPORTANT] -==== -Be careful when creating a workspace file. In case of errors, an empty Visual Studio Code - Open Source ("Code - OSS") will be opened instead. -==== -+ -[IMPORTANT] -==== -If you have several projects, the workspace file will be taken from the first project. -If the workspace file does not exist in the first project, a new one will be created and placed in the `/projects` directory. -==== - -* Specify alternative workspace file. - -** Define the __VSCODE_DEFAULT_WORKSPACE__ environment variable in your devfile and specify the right location to the workspace file. -+ -[source,yaml] ----- - env: - - name: VSCODE_DEFAULT_WORKSPACE - value: "/projects/project-name/workspace-file" ----- - -* Open a workspace in a single-root mode. - -** Define __VSCODE_DEFAULT_WORKSPACE__ environment variable and set it to the root. -+ -[source,yaml] ----- - env: - - name: VSCODE_DEFAULT_WORKSPACE - value: "/" ----- diff --git a/modules/administration-guide/pages/configuring-visual-studio-code.adoc b/modules/administration-guide/pages/configuring-visual-studio-code.adoc deleted file mode 100644 index d25bd834d7..0000000000 --- a/modules/administration-guide/pages/configuring-visual-studio-code.adoc +++ /dev/null @@ -1,16 +0,0 @@ -:_content-type: CONCEPT -:description: Configuring Visual Studio Code - Open Source ("Code - OSS") -:keywords: vscode, workspace -:navtitle: Configuring Visual Studio Code - Open Source ("Code - OSS") -//:page-aliases: - -[id="configuring-visual-studio-code"] -= Configuring Visual Studio Code - Open Source ("Code - OSS") - -Learn how to configure Visual Studio Code - Open Source ("Code - OSS"). - -* xref:configuring-single-and-multiroot-workspaces.adoc[] -* xref:trusted-extensions-for-microsoft-visual-studio-code.adoc[] -* xref:default-extensions-for-microsoft-visual-studio-code.adoc[] -* xref:editor-configurations-for-microsoft-visual-studio-code.adoc[] -* xref:manage-extension-installation.adoc[] \ No newline at end of file diff --git a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc b/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc deleted file mode 100644 index 06e7692b5e..0000000000 --- a/modules/administration-guide/pages/default-extensions-for-microsoft-visual-studio-code.adoc +++ /dev/null @@ -1,176 +0,0 @@ -:_content-type: PROCEDURE -:description: Configure default extensions -:keywords: extensions, workspace -:navtitle: Configure default extensions -// :page-aliases: - -[id="visual-studio-code-default-extensions"] -= Configuring default extensions - -Default extensions are a pre-installed set of extensions, specified by putting the extension binary `.vsix` file path to the __DEFAULT_EXTENSIONS__ environment variable. - -After startup, the editor checks for this environment variable, and if it is specified, takes the path to the extensions and installs it in the background without disturbing the user. - -Configuring default extensions is useful for installing .vsix extensions from the editor level. - -[NOTE] -==== -If you want to specify multiple extensions, separate them by semicolon. - -[source,yaml] ----- - DEFAULT_EXTENSIONS='/projects/extension-1.vsix;/projects/extension-2.vsix' ----- -==== - -Read on to learn how to define the DEFAULT_EXTENSIONS environment variable, including multiple examples of adding `.vsix` files to your workspace. - -There are three different ways to embed default `.vsix` extensions into your workspace: - -* Put the extension binary into the source repository. -* Use the devfile `postStart` event to fetch extension binaries from the network. -* Include the extensions' `.vsix` binaries in the `che-code` image. - -.Putting the extension binary into the source repository - -Putting the extension binary into the Git repository and defining the environment variable in the devfile is the easiest way to add default extensions to your workspace. -If the `extension.vsix` file exists in the repository root, you can set the __DEFAULT_EXTENSIONS__ for a tooling container. - -.Procedure -* Specify __DEFAULT_EXTENSIONS__ in your `.devfile.yaml` as shown in the following example: -+ -==== -[source,yaml] ----- -schemaVersion: 2.3.0 -metadata: - generateName: example-project -components: - - name: tools - container: - image: quay.io/devfile/universal-developer-image:ubi8-latest - env: - - name: 'DEFAULT_EXTENSIONS' - value: '/projects/example-project/extension.vsix' ----- -==== - -.Using the devfile *postStart* event to fetch extension binaries from the network - -You can use cURL or GNU Wget to download extensions to your workspace. -For that you need to: - --- -* specify a devfile command to download extensions to your workpace -* add a `postStart` event to run the command on workspace startup -* define the __DEFAULT_EXTENSIONS__ environment variable in the devfile --- - -.Procedure -* Add the values shown in the following example to the devfile: -+ -==== -[source,yaml] ----- -schemaVersion: 2.3.0 -metadata: - generateName: example-project -components: - - name: tools - container: - image: quay.io/devfile/universal-developer-image:ubi8-latest - env: - - name: DEFAULT_EXTENSIONS - value: '/tmp/extension-1.vsix;/tmp/extension-2.vsix' - -commands: - - id: add-default-extensions - exec: - # name of the tooling container - component: tools - # download several extensions using curl - commandLine: | - curl https://.../extension-1.vsix --location -o /tmp/extension-1.vsix - curl https://.../extension-2.vsix --location -o /tmp/extension-2.vsix - -events: - postStart: - - add-default-extensions ----- -==== -+ -[WARNING] -==== -In some cases curl may download a `.gzip` compressed file. This might make installing the extension impossible. -To fix that try to save the file as a *.vsix.gz* file and then decompress it with *gunzip*. This will replace the *.vsix.gz* file with an unpacked *.vsix* file. - -[source,yaml] ----- -curl https://some-extension-url --location -o /tmp/extension.vsix.gz -gunzip /tmp/extension.vsix.gz ----- -==== - -.Including the extensions `.vsix` binaries in the `che-code` image. - -With default extensions bundled in the editor image, and the __DEFAULT_EXTENSIONS__ environment variable defined in the ConfigMap, you can apply the default extensions without changing the devfile. - -Following the steps below to add the extensions you need to the editor image. - -.Procedure -* Create a directory and place your selected `.vsix` extensions in this directory. - -* Create a Dockerfile with the following content: -+ -==== -[source,] ----- -# inherit che-incubator/che-code:latest -FROM quay.io/che-incubator/che-code:latest -USER 0 - -# copy all .vsix files to /default-extensions directory -RUN mkdir --mode=775 /default-extensions -COPY --chmod=755 *.vsix /default-extensions/ - -# add instruction to the script to copy default extensions to the working container -RUN echo "cp -r /default-extensions /checode/" >> /entrypoint-init-container.sh ----- -==== - -* Build the image and then push it to a registry: -+ -==== -[,console] ----- -$ docker build -t yourname/che-code:next . -$ docker push yourname/che-code:next ----- -==== - -* Add the new ConfigMap to the user's {orch-namespace}, define the __DEFAULT_EXTENSIONS__ environment variable, and specify the absolute paths to the extensions. This ConfigMap sets the environment variable to all workspaces in the user's {orch-namespace}. -+ -==== -[source,yaml] ----- -kind: ConfigMap -apiVersion: v1 -metadata: - name: vscode-default-extensions - labels: - controller.devfile.io/mount-to-devworkspace: 'true' - controller.devfile.io/watch-configmap: 'true' - annotations: - controller.devfile.io/mount-as: env -data: - DEFAULT_EXTENSIONS: '/checode/default-extensions/extension1.vsix;/checode/default-extensions/extension2.vsix' ----- -==== - -* Create a workspace using `yourname/che-code:next` image. -First, open the dashboard and navigate to the *Create Workspace* tab on the left side. -+ --- -.. In the *Editor Selector* section, expand the *Use an Editor Definition* dropdown and set the editor URI to the *Editor Image*. -.. Create a workspace by clicking on any sample or by using a Git repository URL. --- diff --git a/modules/administration-guide/pages/manage-extension-installation.adoc b/modules/administration-guide/pages/manage-extension-installation.adoc deleted file mode 100644 index 73c80af147..0000000000 --- a/modules/administration-guide/pages/manage-extension-installation.adoc +++ /dev/null @@ -1,153 +0,0 @@ -:_content-type: PROCEDURE -:description: Manage extension installation with ConfigMap -:keywords: extensions, workspace -:navtitle: Manage extension installation with ConfigMap -// :page-aliases: - -[id="visual-studio-code-manage-extensions-installation"] -= Manage extension installation with ConfigMap - -This page describes how Code - OSS manages extension installation using a ConfigMap. -With these controls, you can enforce a fine-grained allow/deny list using the `AllowedExtensions` policy and block installs via the CLI, default extensions, and the `workbench.extensions.command.installFromVSIX` API command. -The sections below show how to enable and enforce these controls in Code - OSS. - - -The following items are currently supported: - -* BlockCliExtensionsInstallation property - when enabled, blocks installation of extensions via CLI -* BlockDefaultExtensionsInstallation property - when enabled, blocks installation of default extensions, see xref:default-extensions-for-microsoft-visual-studio-code.adoc[] -* BlockInstallFromVSIXCommandExtensionsInstallation property - when enabled, blocks installation of extensions via the workbench.extensions.command.installFromVSIX API command -* AllowedExtensions section - provides fine-grained control over Code - OSS extension installation; when this policy is applied, already installed extensions that are not allowed are disabled and show the warning `Some extensions are disabled because they are not allowed by your system administrator`. For conceptual background, see link:https://code.visualstudio.com/docs/setup/enterprise#_configure-allowed-extensions/[Configure allowed extensions]. - -.Procedure - -* Add a new ConfigMap to the {prod-namespace} namespace and specify the properties you want to add. -+ -==== -[source,yaml] ----- -kind: ConfigMap -apiVersion: v1 -metadata: - name: vscode-editor-configurations - namespace: eclipse-che - - labels: - app.kubernetes.io/component: workspaces-config - app.kubernetes.io/part-of: che.eclipse.org - annotations: - controller.devfile.io/mount-as: subpath - controller.devfile.io/mount-path: /checode-config - controller.devfile.io/read-only: 'true' - -data: - policy.json: | - { - "BlockCliExtensionsInstallation": true, - "BlockDefaultExtensionsInstallation": true, - "BlockInstallFromVSIXCommandExtensionsInstallation": true, - "AllowedExtensions": { - "*": true, - "dbaeumer.vscode-eslint": false, - "ms-python.python": false, - "redhat": false - } - } ----- -==== - -[NOTE] -==== -Make sure that the Configmap contains data in a valid JSON format. -==== - -* Start or restart your workspace - - -TIP: To completely disable extension installation, set all extensions to disallowed: -==== -[source,yaml] ----- -kind: ConfigMap -apiVersion: v1 -metadata: - name: vscode-editor-configurations - namespace: eclipse-che - - labels: - app.kubernetes.io/component: workspaces-config - app.kubernetes.io/part-of: che.eclipse.org - annotations: - controller.devfile.io/mount-as: subpath - controller.devfile.io/mount-path: /checode-config - controller.devfile.io/read-only: 'true' - -data: - policy.json: | - { - "AllowedExtensions": { - "*": false - } - } ----- -==== - -* Optional: To add the ConfigMap in the user's namespace, use the following example: -+ -==== -[source,yaml] ----- -kind: ConfigMap -apiVersion: v1 -metadata: - name: vscode-editor-configurations - labels: - controller.devfile.io/mount-to-devworkspace: 'true' - controller.devfile.io/watch-configmap: 'true' - annotations: - controller.devfile.io/mount-as: subpath - controller.devfile.io/mount-path: /checode-config - controller.devfile.io/read-only: 'true' -data: - policy.json: | - { - "AllowedExtensions": { - "*": false - } - } ----- -==== -+ -[WARNING] -==== -When the ConfigMap is stored in the user's namespace, the user can edit its values. -==== - -.Verification -. Verify that the `BlockCliExtensionsInstallation` property is applied: -* Press `F1` → `Preferences: Open Settings (UI)`, and enter `BlockCliExtensionsInstallation` in the search field => The setting from the ConfigMap should appear in Settings. -* Provide a file with the `.vsix` extension (for example, `redhat.java-1.43.1.vsix`) in your workspace. -* Open a terminal and use the CLI to install the extension, for example: `/checode/checode-linux-libc/ubi9/bin/remote-cli/code-oss --install-extension /projects/web-nodejs-sample/redhat.java-1.43.1.vsix` -* The extension should not install; the terminal shows: `Installation of extensions via CLI has been blocked by an administrator`. - -. Verify that the `BlockDefaultExtensionsInstallation` property is applied: -* Press `F1` → `Preferences: Open Settings (UI)`, and enter `BlockDefaultExtensionsInstallation` in the search field => The setting from the ConfigMap should appear in Settings. -* Configure default extensions: see xref:default-extensions-for-microsoft-visual-studio-code.adoc[]. -* Open the Extensions view. -* Verify that default extensions are not installed when the workspace started/restarted. - -. Verify that the `BlockInstallFromVSIXCommandExtensionsInstallation` property is applied: -* Press `F1` → `Preferences: Open Settings (UI)`, and enter `BlockInstallFromVSIXCommandExtensionsInstallation` in the search field => The setting from the ConfigMap should appear in Settings. -* This property blocks installing extensions via the `workbench.extensions.command.installFromVSIX` API command. -* For example, an extension might call: `vscode.commands.executeCommand('workbench.extensions.command.installFromVSIX', URL);` -* It is not possible to install an extension from a `.vsix` when this property is set to `true`. - -. Verify that rules defined in the `AllowedExtensions` section are applied: -* Press `F1` → `Preferences: Open Settings (UI)`, and enter `extensions.allowed` in the search field. -* All settings from the `AllowedExtensions` section of the ConfigMap should be present in Settings. -* Use `F1 → Open View → Extensions` to open the Extensions view, disallowed extensions has `This extension cannot be installed because it is not in the allowed list` warning -* Try to install allowed and disallowed extensions to verify that the ConfigMap rules are enforced. - -. Verify that rules defined in the `AllowedExtensions` section are applied: -* Press `F1` → `Preferences: Open Settings (UI)`, and enter `extensions.allowed` in the search field. -* All settings from the `AllowedExtensions` section of the ConfigMap should be present in Settings. diff --git a/modules/administration-guide/pages/trusted-extensions-for-microsoft-visual-studio-code.adoc b/modules/administration-guide/pages/trusted-extensions-for-microsoft-visual-studio-code.adoc deleted file mode 100644 index af6c22ae7b..0000000000 --- a/modules/administration-guide/pages/trusted-extensions-for-microsoft-visual-studio-code.adoc +++ /dev/null @@ -1,68 +0,0 @@ -:_content-type: PROCEDURE -:description: Configure trusted extensions for Microsoft Visual Studio Code -:keywords: extensions, vs-code, vsx, open-vsx, marketplace -:navtitle: Configure trusted extensions for Microsoft Visual Studio Code - -[id="visual-studio-code-trusted-extensions"] -= Configure trusted extensions for Microsoft Visual Studio Code - - -You can use the `trustedExtensionAuthAccess` field in the `product.json` file of Microsoft Visual Studio Code to specify which extensions are trusted to access authentication tokens. -[source,json] ----- - "trustedExtensionAuthAccess": [ - ".", - "." - ] ----- - -This is particularly useful when you have extensions that require access to services such as GitHub, Microsoft, or any other service that requires OAuth. By adding the extension IDs to this field, you are granting them the permission to access these tokens. - -You can define the variable in the devfile or in the ConfigMap. Pick the option that better suits your needs. -With a ConfigMap, the variable will be propagated on all your workspaces and you do not need to add the variable to each the devfile you are using. -[WARNING] -==== -Use the `trustedExtensionAuthAccess` field with caution as it could potentially lead to security risks if misused. Give access only to trusted extensions. -==== - -.Procedure -[IMPORTANT] -==== -Since the Microsoft Visual Studio Code editor is bundled within `che-code` image, you can only change the `product.json` file when the workspace is started up. -==== - - -. Define the __VSCODE_TRUSTED_EXTENSIONS__ environment variable. Choose between defining the variable in devfile.yaml or mounting a ConfigMap with the variable instead. -.. Define the __VSCODE_TRUSTED_EXTENSIONS__ environment variable in devfile.yaml: -+ -==== -[source,yaml] ----- - env: - - name: VSCODE_TRUSTED_EXTENSIONS - value: ".,." ----- -==== - -.. Mount a ConfigMap with __VSCODE_TRUSTED_EXTENSIONS__ environment variable: -+ -==== -[source,yaml] ----- - kind: ConfigMap - apiVersion: v1 - metadata: - name: trusted-extensions - labels: - controller.devfile.io/mount-to-devworkspace: 'true' - controller.devfile.io/watch-configmap: 'true' - annotations: - controller.devfile.io/mount-as: env - data: - VSCODE_TRUSTED_EXTENSIONS: '.,.' ----- -==== - -.Verification - -* The value of the variable will be parsed on the workspace startup and the corresponding `trustedExtensionAuthAccess` section will be added to the `product.json`. 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 deleted file mode 100644 index bb051b047e..0000000000 --- a/modules/administration-guide/partials/proc_adding-or-removing-extensions-in-a-workspace.adoc +++ /dev/null @@ -1,96 +0,0 @@ -:_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 is deprecated. 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:proc_deploy-open-vsx-from-source.adoc[] procedure for detailed setup instructions. -==== - -.Prerequisites - -* You have started a workspace using the link:{plugin-registry-repo-url}[plugin registry repository]. -* You are logged in to the cluster as a cluster administrator from the workspace terminal: `$ oc login --token= --server=` -* 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 - -. 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 workspace. - -. 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:{plugin-registry-repo-url}[Plugin registry repository] -* xref:proc_deploy-open-vsx-from-source.adoc[] 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 deleted file mode 100644 index 7c9333607f..0000000000 --- a/modules/administration-guide/partials/proc_adding-or-removing-extensions-on-linux.adoc +++ /dev/null @@ -1,124 +0,0 @@ -:_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,subs="+attributes"] ----- -$ git clone {plugin-registry-repo-url}.git ----- - -. Change to the plugin registry directory: -+ -[source,bash] ----- -$ cd che-plugin-registry ----- - -. 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:{plugin-registry-repo-url}[Plugin registry repository] -* xref:proc_deploy-open-vsx-from-source.adoc[] diff --git a/modules/end-user-guide/pages/microsoft-visual-studio-code-open-source-ide.adoc b/modules/end-user-guide/pages/microsoft-visual-studio-code-open-source-ide.adoc index 046b3d954c..c5a2bde08a 100644 --- a/modules/end-user-guide/pages/microsoft-visual-studio-code-open-source-ide.adoc +++ b/modules/end-user-guide/pages/microsoft-visual-studio-code-open-source-ide.adoc @@ -9,7 +9,7 @@ The {prod-short} build of link:https://github.com/microsoft/vscode[Microsoft Visual Studio Code - Open Source] is the default IDE of a new workspace. -You can automate installation of Microsoft Visual Studio Code extensions from the xref:administration-guide:extensions-for-microsoft-visual-studio-code-open-source.adoc[Open VSX registry] at workspace startup. See _Automating installation of Microsoft Visual Studio Code extensions at workspace startup_. +You can automate installation of Microsoft Visual Studio Code extensions from the xref:extend:extensions-for-microsoft-visual-studio-code-open-source.adoc[Open VSX registry] at workspace startup. See _Automating installation of Microsoft Visual Studio Code extensions at workspace startup_. [TIP] ==== diff --git a/modules/end-user-guide/partials/proc_automating-installation-of-microsoft-visual-studio-code-extensions-at-workspace-startup.adoc b/modules/end-user-guide/partials/proc_automating-installation-of-microsoft-visual-studio-code-extensions-at-workspace-startup.adoc index a00e2c5f11..a4ce43957f 100644 --- a/modules/end-user-guide/partials/proc_automating-installation-of-microsoft-visual-studio-code-extensions-at-workspace-startup.adoc +++ b/modules/end-user-guide/partials/proc_automating-installation-of-microsoft-visual-studio-code-extensions-at-workspace-startup.adoc @@ -5,13 +5,13 @@ To have the Microsoft Visual Studio Code - Open Source IDE automatically install chosen extensions, you can add an `extensions.json` file to the remote Git repository that contains your project source code and that will be cloned into workspaces. .Prerequisites -* The public OpenVSX registry at link:https://open-vsx.org[open-vsx.org] is selected and accessible over the internet. See xref:administration-guide:extensions-for-microsoft-visual-studio-code-open-source.adoc[Selecting an Open VSX registry instance]. +* The public OpenVSX registry at link:https://open-vsx.org[open-vsx.org] is selected and accessible over the internet. See xref:extend:extensions-for-microsoft-visual-studio-code-open-source.adoc[Selecting an Open VSX registry instance]. + [TIP] ==== To install recommended extensions in a restricted environment, consider the following options instead: -* xref:administration-guide:configuring-the-open-vsx-registry-url.adoc[] to point to your OpenVSX registry. +* xref:extend:configuring-the-open-vsx-registry-url.adoc[] to point to your OpenVSX registry. * xref:defining-a-common-ide.adoc[]. diff --git a/modules/administration-guide/examples/snip_che-concealing-editors-additional-resources.adoc b/modules/extend/examples/snip_che-concealing-editors-additional-resources.adoc similarity index 66% rename from modules/administration-guide/examples/snip_che-concealing-editors-additional-resources.adoc rename to modules/extend/examples/snip_che-concealing-editors-additional-resources.adoc index 3c98c8da29..fcce627017 100644 --- a/modules/administration-guide/examples/snip_che-concealing-editors-additional-resources.adoc +++ b/modules/extend/examples/snip_che-concealing-editors-additional-resources.adoc @@ -4,6 +4,6 @@ * xref:install:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[] -* xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] +* xref:administration-guide:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] * {editor-definition-samples-link} diff --git a/modules/administration-guide/examples/snip_che-default-vsx-registry.adoc b/modules/extend/examples/snip_che-default-vsx-registry.adoc similarity index 100% rename from modules/administration-guide/examples/snip_che-default-vsx-registry.adoc rename to modules/extend/examples/snip_che-default-vsx-registry.adoc diff --git a/modules/administration-guide/examples/snip_che-editor-id-list.adoc b/modules/extend/examples/snip_che-editor-id-list.adoc similarity index 73% rename from modules/administration-guide/examples/snip_che-editor-id-list.adoc rename to modules/extend/examples/snip_che-editor-id-list.adoc index a6146c6d09..2312d652cc 100644 --- a/modules/administration-guide/examples/snip_che-editor-id-list.adoc +++ b/modules/extend/examples/snip_che-editor-id-list.adoc @@ -1,6 +1,6 @@ :_content-type: SNIPPET -. An editor ID has the following format: `publisher/name/version`. Find out the IDs of the available editors: +. Determine the IDs of the available editors. An editor ID has the following format: `publisher/name/version`. + [source,subs="+quotes,+attributes"] ---- diff --git a/modules/administration-guide/examples/snip_che-managing-extensions.adoc b/modules/extend/examples/snip_che-managing-extensions.adoc similarity index 100% rename from modules/administration-guide/examples/snip_che-managing-extensions.adoc rename to modules/extend/examples/snip_che-managing-extensions.adoc diff --git a/modules/administration-guide/examples/snip_che-non-default-vsx-registry-instance.adoc b/modules/extend/examples/snip_che-non-default-vsx-registry-instance.adoc similarity index 100% rename from modules/administration-guide/examples/snip_che-non-default-vsx-registry-instance.adoc rename to modules/extend/examples/snip_che-non-default-vsx-registry-instance.adoc diff --git a/modules/extend/nav.adoc b/modules/extend/nav.adoc new file mode 100644 index 0000000000..93a8157d86 --- /dev/null +++ b/modules/extend/nav.adoc @@ -0,0 +1,24 @@ +.Extend +* Choose which editors are available +** xref:configuring-editors-definitions.adoc[] +** xref:configuring-default-editor.adoc[] +** xref:concealing-editors.adoc[] +** xref:show-deprecated-editors.adoc[] +** xref:configuring-editors-download-urls.adoc[] +* xref:configuring-visual-studio-code.adoc[] +** xref:configuring-single-and-multiroot-workspaces.adoc[] +** xref:trusted-extensions-for-microsoft-visual-studio-code.adoc[] +** xref:default-extensions-for-microsoft-visual-studio-code.adoc[] +** xref:manage-extension-installation.adoc[] +** xref:editor-configurations-for-microsoft-visual-studio-code.adoc[] +* xref:managing-ide-extensions.adoc[] +** xref:extensions-for-microsoft-visual-studio-code-open-source.adoc[] +** xref:configuring-the-open-vsx-registry-url.adoc[] +* Deploy a private extension registry +** xref:proc_deploy-open-vsx-from-source.adoc[] +** xref:proc_deploy-open-vsx-from-workspace.adoc[] +** xref:proc_configure-internal-open-vsx-access.adoc[] +** xref:proc_deleting-extension-using-openvsx-admin-api.adoc[] +** xref:proc_deleting-extension-from-postgresql-database.adoc[] +* xref:configuring-ai-providers.adoc[] +** xref:ai-provider-api-key-secret-reference.adoc[] diff --git a/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc b/modules/extend/pages/ai-provider-api-key-secret-reference.adoc similarity index 87% rename from modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc rename to modules/extend/pages/ai-provider-api-key-secret-reference.adoc index c66835c0ba..2d3e9dfccc 100644 --- a/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc +++ b/modules/extend/pages/ai-provider-api-key-secret-reference.adoc @@ -1,16 +1,16 @@ +:page-aliases: administration-guide:ai-provider-api-key-secret-reference.adoc :_content-type: REFERENCE :description: Kubernetes Secret schema, labels, and naming convention for AI provider API keys that are automatically mounted into workspace containers. :keywords: administration, ai, api key, secret, kubernetes, devworkspace controller, environment variable, mount :navtitle: AI provider API key secret reference -:page-aliases: [id="ai-provider-api-key-secret-reference"] = AI provider API key secret reference [role="_abstract"] -Each user's AI provider API key is stored as a {kubernetes} `Opaque` Secret in the user's personal {orch-namespace}. The {devworkspace} Controller automatically mounts matching Secrets as environment variables into all workspace containers. Use this reference when manually creating or troubleshooting AI provider key Secrets. +Each user's AI provider API key is stored as a {orch-name} `Opaque` Secret in the user's personal {orch-namespace}. The {devworkspace} Controller automatically mounts matching Secrets as environment variables into all workspace containers. Use this reference when manually creating or troubleshooting AI provider key Secrets. -== Secret schema +== What the Secret contains [source,yaml,subs="+quotes,+attributes"] ---- @@ -36,7 +36,7 @@ data: <5> Mounts the Secret data keys as environment variables (not as files). <6> The data key is the environment variable name. The value is base64-encoded. The variable is injected directly into all workspace containers. -== Label and annotation reference +== Required labels and annotations [cols="1,1,2",options="header"] |=== @@ -59,7 +59,7 @@ data: | Used by the {prod-short} dashboard to identify and list AI provider key Secrets when rendering the AI Selector widget. |=== -== Secret naming convention +== How to name your Secret Secret names follow the pattern: @@ -77,7 +77,7 @@ Example: | `ai-provider-openai-api-key` |=== -== Manual Secret creation +== Create the Secret manually Advanced users can create AI provider key Secrets manually using `{orch-cli}` instead of the dashboard UI. Use the same labels and annotations as shown in the schema above: @@ -101,6 +101,7 @@ data: EOF ---- +[role="_additional-resources"] .Additional resources * xref:configuring-ai-providers.adoc[] diff --git a/modules/extend/pages/concealing-editors.adoc b/modules/extend/pages/concealing-editors.adoc new file mode 100644 index 0000000000..e180c46faa --- /dev/null +++ b/modules/extend/pages/concealing-editors.adoc @@ -0,0 +1,52 @@ +:page-aliases: administration-guide:concealing-editors.adoc +:_content-type: PROCEDURE +:description: Hide editors from the dashboard +:keywords: administration guide, concealing, dashboard, editors +:navtitle: Hide editors from the dashboard + +[id="concealing-editors"] += Hide editors from the dashboard + +[role="_abstract"] +Hide selected {prod-short} editors from the Dashboard UI, for example IntelliJ IDEA Ultimate, and have only Visual Studio Code - Open Source visible. + +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the {orch-name} cluster. See {orch-cli-link}. + +* `jq`. See link:https://stedolan.github.io/jq/download/[Downloading `jq`]. + +.Procedure + +include::example$snip_che-editor-id-list.adoc[] + +. Edit the `CheCluster` Custom Resource on the cluster: ++ +[source,subs="+attributes"] +---- +{orch-cli} edit checluster/{prod-checluster} -n {prod-namespace} +---- ++ +[source,yaml] +---- +spec: + components: + dashboard: + deployment: + containers: + - env: + - name: CHE_HIDE_EDITORS_BY_ID + value: 'che-incubator/che-webstorm-server/latest, che-incubator/che-webstorm-server/next' <1> +---- +<1> A string containing comma-separated IDs of editors to hide. + +.Verification + +* In the {prod-short} Dashboard, go to *Create Workspace* and verify that the concealed editors are no longer visible. + +[role="_additional-resources"] +.Additional resources + +* xref:install:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[] + +* xref:administration-guide:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] diff --git a/modules/administration-guide/pages/configuring-ai-providers.adoc b/modules/extend/pages/configuring-ai-providers.adoc similarity index 89% rename from modules/administration-guide/pages/configuring-ai-providers.adoc rename to modules/extend/pages/configuring-ai-providers.adoc index 8be4bd5f88..0b9cafef58 100644 --- a/modules/administration-guide/pages/configuring-ai-providers.adoc +++ b/modules/extend/pages/configuring-ai-providers.adoc @@ -1,19 +1,19 @@ +:page-aliases: administration-guide:configuring-ai-providers.adoc :_content-type: PROCEDURE :description: Register AI providers in Eclipse Che so that developers can select and use AI coding assistants when creating workspaces. :keywords: administration, ai, ai provider, opencode, configmap, ai-tool-registry, api key, injector image, dockerfile -:navtitle: Configuring AI providers -:page-aliases: +:navtitle: Register AI coding assistants [id="configuring-ai-providers"] -= Configure AI providers += Register AI coding assistants :FeatureName: The AI provider feature -include::example$snip_che-technology-preview.adoc[] +include::administration-guide:example$snip_che-technology-preview.adoc[] [role="_abstract"] Register one or more AI providers in {prod-short} so that developers can select and use AI coding assistants when creating workspaces. -The AI tool registry is stored in a {kubernetes} `ConfigMap` with specific labels. When the ConfigMap exists and contains at least one provider with a matching tool, the AI Selector widget is displayed on the dashboard. When the ConfigMap is absent or empty, the widget is hidden. +The AI tool registry is stored in a {orch-name} `ConfigMap` with specific labels. When the ConfigMap exists and contains at least one provider with a matching tool, the AI Selector widget is displayed on the dashboard. When the ConfigMap is absent or empty, the widget is hidden. .Prerequisites @@ -67,8 +67,8 @@ LABEL org.opencontainers.image.description="OpenCode CLI tool for DevWorkspace i Key design points: + ** *Multi-stage build*: the `builder` stage downloads the architecture-specific binary; the minimal runtime stage keeps the final image small. -** *Wrapper script*: redirects `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and related variables to writable paths under `/tmp`, allowing the tool to run as an arbitrary UID on OpenShift. -** *Multi-arch*: pass `--platform linux/amd64,linux/arm64` to `docker build` to produce a multi-arch image. +** *Wrapper script*: redirects `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and related variables to writable paths under `/tmp`, allowing the tool to run as an arbitrary UID on {orch-name}. +** *Multi-arch*: pass `--platform linux/amd64,linux/arm64` to `{docker-cli} build` to produce a multi-arch image. + Build and push the image: + @@ -117,7 +117,7 @@ See link:https://github.com/che-incubator/che-ai-tool-images[che-incubator/che-a <4> Binary name that must be available in `PATH` inside the workspace after injection. <5> Injection pattern: `init` copies a single binary into the shared volume; `bundle` copies a full runtime directory and creates a symlink. <6> Container image that carries the tool binary. Run as an init container at workspace start. -<7> Environment variable name for the API key. The dashboard creates a {kubernetes} Secret using this name as the data key. +<7> Environment variable name for the API key. The dashboard creates a {orch-name} Secret using this name as the data key. <8> Optional. Provider IDs pre-selected in the AI Selector widget for new workspaces. . Create the `ConfigMap` in the `{prod-namespace}` namespace with the required labels: @@ -148,6 +148,7 @@ To disable the AI Selector widget, delete the `ai-tool-registry` ConfigMap. User When you update the registry (for example, to remove a tool or change the injector image tag), existing workspaces are updated automatically before their next start. The dashboard removes stale tool injectors and replaces outdated image tags without user intervention. ==== +[role="_additional-resources"] .Additional resources * xref:ai-provider-api-key-secret-reference.adoc[] diff --git a/modules/administration-guide/pages/configuring-default-editor.adoc b/modules/extend/pages/configuring-default-editor.adoc similarity index 51% rename from modules/administration-guide/pages/configuring-default-editor.adoc rename to modules/extend/pages/configuring-default-editor.adoc index 3db3f7276f..aeb1a72b0b 100644 --- a/modules/administration-guide/pages/configuring-default-editor.adoc +++ b/modules/extend/pages/configuring-default-editor.adoc @@ -1,12 +1,14 @@ +:page-aliases: administration-guide:configuring-default-editor.adoc :_content-type: PROCEDURE -:description: Configuring default editor +:description: Set the default IDE for new workspaces :keywords: administration guide, dashboard, editors -:navtitle: Configuring default editor +:navtitle: Set the default IDE for new workspaces [id="configuring-default-editor"] -= Configuring default editor += Set the default IDE for new workspaces -Learn how to configure {prod-short} default editor. +[role="_abstract"] +Set the default editor that {prod-short} uses when creating new workspaces to ensure a consistent development experience. The default editor is specified by its plugin ID in the `publisher/name/version` format. .Prerequisites @@ -25,10 +27,18 @@ include::example$snip_che-editor-id-list.adoc[] {orch-cli} patch checluster/{prod-checluster} \ --namespace {prod-namespace} \ --type='merge' \ - -p '{"spec":{"devEnvironments":{"defaultEditor": "____"}}}'# <1> + -p '{"spec":{"devEnvironments":{"defaultEditor": "____"}}}' ---- -<1> The default editor for creating a workspace can be specified using either a plugin ID or a URI. The plugin ID should follow the format: `publisher/name/version`. See available editors IDs in the first step. ++ +where: ++ +`____`:: The default editor specified as a plugin ID in `publisher/name/version` format or as a URI. + +.Verification +* Create a new workspace from the {prod-short} Dashboard and verify that the configured default editor opens. + +[role="_additional-resources"] .Additional resources * xref:configuring-editors-definitions.adoc[] @@ -36,4 +46,3 @@ include::example$snip_che-editor-id-list.adoc[] * xref:concealing-editors.adoc[] * {editor-definition-samples-link} - diff --git a/modules/administration-guide/pages/configuring-editors-definitions.adoc b/modules/extend/pages/configuring-editors-definitions.adoc similarity index 82% rename from modules/administration-guide/pages/configuring-editors-definitions.adoc rename to modules/extend/pages/configuring-editors-definitions.adoc index 998f0cebf8..6795882765 100644 --- a/modules/administration-guide/pages/configuring-editors-definitions.adoc +++ b/modules/extend/pages/configuring-editors-definitions.adoc @@ -1,13 +1,14 @@ +:page-aliases: administration-guide:configuring-editors-definitions.adoc, installation-guide:configuring-editors-definitions.adoc :_content-type: PROCEDURE -:description: Configuring editors definitions +:description: Add custom editors to the dashboard :keywords: administration guide, configuring, dashboard, editors -:navtitle: Configuring editors definitions -:page-aliases: installation-guide:configuring-editors-definitions.adoc +:navtitle: Add custom editors to the dashboard [id="configuring-editors-definitions"] -= Configuring editors definitions += Add custom editors to the dashboard -Learn how to configure {prod-short} editor definitions. +[role="_abstract"] +Add custom editor definitions to {prod-short} by creating a devfile with the editor configuration and storing it in a ConfigMap to offer additional IDE options to your users. .Prerequisites @@ -15,19 +16,13 @@ Learn how to configure {prod-short} editor definitions. .Procedure -. Create the `my-editor-definition-devfile.yaml` YAML file with the editor definition configuration. +. Create the `my-editor-definition-devfile.yaml` YAML file with the editor definition configuration. Provide actual values for `publisher` and `version` under `metadata.attributes` because these construct the editor ID in the format `publisher/name/version`. + -[IMPORTANT] -==== -Make sure you provide the actual values for `publisher` and `version` under `metadata.attributes`. -They are used to construct the editor id along with editor name in the following format `publisher/name/version`. -==== -+ -Below you can find the supported values, including optional ones: +For example: + [source,yaml,subs="+quotes,+attributes"] ---- -# Version of the devile schema +# Version of the devfile schema schemaVersion: 2.2.2 # Meta information of the editor metadata: @@ -35,7 +30,7 @@ metadata: # Must consist of lower case alphanumeric characters, '-' or '.' name: editor-name displayName: Display Name - description: Run Editor Foo on top of Eclipse Che + description: Run Editor Foo on top of {prod-short} # (OPTIONAL) Array of tags of the current editor. The Tech-Preview tag means the option is considered experimental and is not recommended for production environments. While it can include new features and improvements, it may still contain bugs or undergo significant changes before reaching a stable version. tags: - Tech-Preview @@ -91,13 +86,13 @@ components: # Defines a container component as a "container contribution". If a flattened DevWorkspace has a container component with the merge-contribution attribute, then any container contributions are merged into that container component controller.devfile.io/container-contribution: true container: - # Can be a dummy image because the component is expected to be injected into workspace dev component + # Can be a placeholder image because the component is expected to be injected into workspace dev component image: quay.io/devfile/universal-developer-image:latest # (OPTIONAL) List of volume mounts that should be mounted in this container volumeMounts: # The name of the mount - name: checode - # (OPTIONAL) The path in the component container where the volume should be mounted. If no path is defined, the default path is the is / + # (OPTIONAL) The path in the component container where the volume should be mounted. If no path is defined, the default path is / path: /checode # (OPTIONAL) The memory limit of the container memoryLimit: 1024Mi @@ -123,7 +118,7 @@ components: cookiesAuthEnabled: true # Defines an endpoint as "discoverable", meaning that a service should be created using the endpoint name (i.e. instead of generating a service name for all endpoints, this endpoint should be statically accessible) discoverable: false - # Used to secure the endpoint with authorization on OpenShift, so that not anyone on the cluster can access the endpoint, the attribute enables authentication. + # Used to secure the endpoint with authorization on {orch-name}, so that not anyone on the cluster can access the endpoint, the attribute enables authentication. urlRewriteSupported: true # Port number to be used within the container component targetPort: 3100 @@ -162,6 +157,10 @@ commands: commandLine: 'nohup /checode/entrypoint-volume.sh > /checode/entrypoint-logs.txt 2>&1 &' ---- ++ +where: ++ +`____`:: The SVG icon data for the editor, displayed in the {prod-short} Dashboard editor selector. . Create a ConfigMap with the editor definition content: + @@ -177,23 +176,23 @@ commands: {orch-cli} label configmap my-editor-definition app.kubernetes.io/part-of=che.eclipse.org app.kubernetes.io/component=editor-definition -n {prod-namespace} ---- -. Refresh the {prod-short} Dashboard page to see new available editor. +.Verification -== Retrieving the editor definition - -The editor definition is also served by the {prod-short} dashboard API from the following URL: +* Refresh the {prod-short} Dashboard page and verify that the new editor is available. +* Verify the editor definition through the {prod-short} Dashboard API: ++ `pass:c,a,q[{prod-url}]/dashboard/api/editors` - -For the example from xref:configuring-editors-definitions.adoc[], the editor definition can be retrieved by accessing the following URL: - ++ +To retrieve a specific editor definition, use the publisher, name, and version values: ++ `pass:c,a,q[{prod-url}]/dashboard/api/editors/devfile?che-editor=publisher/editor-name/version` ++ +When retrieving the editor definition from within the {orch-name} cluster, access the {prod-short} Dashboard API through the dashboard service: `pass:c,a,q[http://{prod-id-short}-dashboard.{prod-namespace}.svc.cluster.local:8080]/dashboard/api/editors` -TIP: When retrieving the editor definition from within the {orch-name} cluster, the {prod-short} dashboard API can be accessed via the dashboard service: `pass:c,a,q[http://{prod-id-short}-dashboard.{prod-namespace}.svc.cluster.local:8080]/dashboard/api/editors` - +[role="_additional-resources"] .Additional resources * link:https://devfile.io/docs/2.2.2/what-is-a-devfile[Devfile documentation] * {editor-definition-samples-link} - diff --git a/modules/extend/pages/configuring-editors-download-urls.adoc b/modules/extend/pages/configuring-editors-download-urls.adoc new file mode 100644 index 0000000000..09974e336c --- /dev/null +++ b/modules/extend/pages/configuring-editors-download-urls.adoc @@ -0,0 +1,57 @@ +:page-aliases: administration-guide:configuring-editors-download-urls.adoc +:_content-type: PROCEDURE +:description: Host editor binaries internally for air-gapped clusters +:keywords: administration guide, dashboard, editors +:navtitle: Host editor binaries internally for air-gapped clusters + +[id="configuring-editors-download-urls"] += Host editor binaries internally for air-gapped clusters + +[role="_abstract"] +Host editor binaries internally by configuring custom download URLs for editors in air-gapped {prod-short} environments where editors cannot be retrieved from the public internet. This option applies only to JetBrains editors. + +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the {orch-name} cluster. See {orch-cli-link}. + +* `jq`. See link:https://stedolan.github.io/jq/download/[Downloading `jq`]. + +.Procedure + +include::example$snip_che-editor-id-list.adoc[] + +. Configure the download URLs for editors: ++ +[source,subs="+quotes,+attributes"] +---- +{orch-cli} patch checluster/{prod-checluster} \ + --namespace {prod-namespace} \ + --type='merge' \ + -p '{ + "spec": { + "devEnvironments": { + "editorsDownloadUrls": [ + { "editor": "publisher1/editor-name1/version1", "url": "https://example.com/editor1.tar.gz" }, + { "editor": "publisher2/editor-name2/version2", "url": "https://example.com/editor2.tar.gz" } + ] + } + } + }' +---- ++ +where: ++ +`editor`:: The editor ID in the format `publisher/name/version`. Determine the IDs by running the command in step 1. ++ +`url`:: The URL of the editor archive to download. + +.Verification + +* Verify that the editor download URLs appear in the `CheCluster` Custom Resource specification. + +[role="_additional-resources"] +.Additional resources + +* xref:configuring-editors-definitions.adoc[] + +* xref:show-deprecated-editors.adoc[] diff --git a/modules/extend/pages/configuring-single-and-multiroot-workspaces.adoc b/modules/extend/pages/configuring-single-and-multiroot-workspaces.adoc new file mode 100644 index 0000000000..b30f9c286e --- /dev/null +++ b/modules/extend/pages/configuring-single-and-multiroot-workspaces.adoc @@ -0,0 +1,89 @@ +:page-aliases: administration-guide:configuring-single-and-multiroot-workspaces.adoc +:_content-type: PROCEDURE +:description: Work with multiple projects in one workspace +:keywords: singleroot, multiroot, workspace +:navtitle: Work with multiple projects in one workspace + +[id="configuring-single-and-multiroot-workspaces"] += Work with multiple projects in one workspace + + +[role="_abstract"] +Work with multiple project folders in the same workspace by using the multi-root workspace feature. This is useful when you are working on several related projects at once, such as product documentation and product code repositories. + +By default, workspaces open in multi-root mode. After a workspace starts, the `/projects/.code-workspace` workspace file is generated. The workspace file contains all the projects described in the devfile. + +[source,json] +---- +{ + "folders": [ + { + "name": "project-1", + "path": "/projects/project-1" + }, + { + "name": "project-2", + "path": "/projects/project-2" + } + ] +} +---- + +If the workspace file already exists, it is updated and all missing projects are taken from the devfile. If you remove a project from the devfile, it remains in the workspace file. + +You can change the default behavior and provide your own workspace file or switch to a single-root workspace. + +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the {orch-name} cluster. See {orch-cli-link}. + +.Procedure + +. Add a workspace file with the name `.code-workspace` to the root of your repository. After workspace creation, the Visual Studio Code - Open Source ("Code - OSS") uses the workspace file as it is. ++ +[source,json] +---- +{ + "folders": [ + { + "name": "project-name", + "path": "." + } + ] +} +---- ++ +[IMPORTANT] +==== +Be careful when creating a workspace file. In case of errors, an empty Visual Studio Code - Open Source ("Code - OSS") opens instead. If you have several projects, the workspace file is taken from the first project. If the workspace file does not exist in the first project, a new one is created and placed in the `/projects` directory. +==== + +. Define the `VSCODE_DEFAULT_WORKSPACE` environment variable in your devfile with the path to an alternative workspace file. ++ +[source,yaml] +---- + env: + - name: VSCODE_DEFAULT_WORKSPACE + value: "/projects/project-name/workspace-file" +---- + +. Define the `VSCODE_DEFAULT_WORKSPACE` environment variable and set it to `/` to open a workspace in single-root mode. ++ +[source,yaml] +---- + env: + - name: VSCODE_DEFAULT_WORKSPACE + value: "/" +---- + +.Verification + +* Start or restart the workspace and verify that Code - OSS opens with the expected workspace mode (single-root or multi-root). + +[role="_additional-resources"] +.Additional resources + +* link:https://code.visualstudio.com/docs/editing/workspaces/workspaces[What is a VS Code workspace] +* xref:trusted-extensions-for-microsoft-visual-studio-code.adoc[] +* xref:default-extensions-for-microsoft-visual-studio-code.adoc[] +* xref:editor-configurations-for-microsoft-visual-studio-code.adoc[] diff --git a/modules/administration-guide/pages/configuring-the-open-vsx-registry-url.adoc b/modules/extend/pages/configuring-the-open-vsx-registry-url.adoc similarity index 88% rename from modules/administration-guide/pages/configuring-the-open-vsx-registry-url.adoc rename to modules/extend/pages/configuring-the-open-vsx-registry-url.adoc index 5d76369db7..ed6ca34e29 100644 --- a/modules/administration-guide/pages/configuring-the-open-vsx-registry-url.adoc +++ b/modules/extend/pages/configuring-the-open-vsx-registry-url.adoc @@ -1,11 +1,11 @@ +:page-aliases: administration-guide:configuring-the-open-vsx-registry-url.adoc :_content-type: PROCEDURE -:description: Configure the Open VSX registry URL for {prod} workspaces +:description: Use an alternative extension registry in {prod-short} :keywords: administration guide, configuring, openvsx, registry, extensions -:navtitle: Configure the Open VSX registry URL -:page-aliases: +:navtitle: Use an alternative extension registry [id="configuring-the-open-vsx-registry-url"] -= Configure the Open VSX registry URL += Use an alternative extension registry [role="_abstract"] Configure {prod-short} to use an alternative Open VSX registry instance instead of the default embedded registry. Switch to the public open-vsx.org registry for internet-connected environments, or to a standalone on-premises instance for full control over available extensions. @@ -20,7 +20,7 @@ If the default Open VSX registry instance does not meet your requirements, you c .Prerequisites -* You have administrator access to the cluster where {prod-short} is deployed. +* You have administrator access to the {orch-name} cluster where {prod-short} is deployed. * You have an active `{orch-cli}` session with administrative permissions. See {orch-cli-link}. .Procedure @@ -68,5 +68,5 @@ Due to the dedicated Microsoft link:https://cdn.vsassets.io/v/M190_20210811.1/_c [role="_additional-resources"] .Additional resources -* xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] +* xref:administration-guide:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] * link:https://open-vsx.org/[Open VSX registry] diff --git a/modules/extend/pages/configuring-visual-studio-code.adoc b/modules/extend/pages/configuring-visual-studio-code.adoc new file mode 100644 index 0000000000..27ee37cff9 --- /dev/null +++ b/modules/extend/pages/configuring-visual-studio-code.adoc @@ -0,0 +1,18 @@ +:page-aliases: administration-guide:configuring-visual-studio-code.adoc +:_content-type: CONCEPT +:description: Customize the default IDE +:keywords: vscode, workspace +:navtitle: Customize the default IDE + +[id="configuring-visual-studio-code"] += Customize the default IDE + + +[role="_abstract"] +Customize Visual Studio Code - Open Source for {prod-short} workspaces, including multi-root project layout, trusted and default extensions, and editor settings so that developers get a consistent IDE experience. + +* xref:configuring-single-and-multiroot-workspaces.adoc[] +* xref:trusted-extensions-for-microsoft-visual-studio-code.adoc[] +* xref:default-extensions-for-microsoft-visual-studio-code.adoc[] +* xref:editor-configurations-for-microsoft-visual-studio-code.adoc[] +* xref:manage-extension-installation.adoc[] \ No newline at end of file diff --git a/modules/extend/pages/default-extensions-for-microsoft-visual-studio-code.adoc b/modules/extend/pages/default-extensions-for-microsoft-visual-studio-code.adoc new file mode 100644 index 0000000000..8f9ebe372b --- /dev/null +++ b/modules/extend/pages/default-extensions-for-microsoft-visual-studio-code.adoc @@ -0,0 +1,146 @@ +:page-aliases: administration-guide:default-extensions-for-microsoft-visual-studio-code.adoc +:_content-type: PROCEDURE +:description: Preinstall extensions in every workspace +:keywords: extensions, workspace +:navtitle: Preinstall extensions in every workspace + +[id="visual-studio-code-default-extensions"] += Preinstall extensions in every workspace + + +[role="_abstract"] +Preinstall Visual Studio Code extensions in {prod-short} workspaces by configuring the `DEFAULT_EXTENSIONS` environment variable to provide a consistent set of editor extensions on workspace startup. + +After startup, the editor checks for the `DEFAULT_EXTENSIONS` environment variable and installs the specified extensions in the background. To specify multiple extensions, separate the paths with a semicolon. + +There are three ways to embed default `.vsix` extensions into your workspace: + +* Add the extension binary to the source repository. +* Use the devfile `postStart` event to fetch extension binaries from the network. +* Include the extensions' `.vsix` binaries in the `che-code` image. + +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the {orch-name} cluster. See {orch-cli-link}. + +.Procedure + +. Add the extension binary to the source repository. ++ +Adding the extension binary to the Git repository and defining the environment variable in the devfile is the easiest way to add default extensions to your workspace. +If the `extension.vsix` file exists in the repository root, set the `DEFAULT_EXTENSIONS` environment variable for the tooling container in your `.devfile.yaml`: ++ +[source,yaml] +---- +schemaVersion: 2.3.0 +metadata: + generateName: example-project +components: + - name: tools + container: + image: quay.io/devfile/universal-developer-image:ubi8-latest + env: + - name: 'DEFAULT_EXTENSIONS' + value: '/projects/example-project/extension.vsix' +---- + +. Use the devfile `postStart` event to fetch extension binaries from the network. ++ +Use cURL or GNU Wget to download extensions to your workspace. Specify a devfile command to download extensions and add a `postStart` event to run the command on workspace startup. Define the `DEFAULT_EXTENSIONS` environment variable in the devfile: ++ +[source,yaml] +---- +schemaVersion: 2.3.0 +metadata: + generateName: example-project +components: + - name: tools + container: + image: quay.io/devfile/universal-developer-image:ubi8-latest + env: + - name: DEFAULT_EXTENSIONS + value: '/tmp/extension-1.vsix;/tmp/extension-2.vsix' + +commands: + - id: add-default-extensions + exec: + # name of the tooling container + component: tools + # download several extensions using curl + commandLine: | + curl https://.../extension-1.vsix --location -o /tmp/extension-1.vsix + curl https://.../extension-2.vsix --location -o /tmp/extension-2.vsix + +events: + postStart: + - add-default-extensions +---- ++ +[WARNING] +==== +In some cases curl may download a `.gzip` compressed file. This might make installing the extension impossible. To fix that, save the file as a *.vsix.gz* file and then decompress it with *gunzip*. This replaces the *.vsix.gz* file with an unpacked *.vsix* file: `curl https://some-extension-url --location -o /tmp/extension.vsix.gz && gunzip /tmp/extension.vsix.gz` +==== + +. Include the extensions `.vsix` binaries in the `che-code` image. ++ +Bundling extensions in the editor image and defining the `DEFAULT_EXTENSIONS` environment variable in a ConfigMap applies default extensions without changing the devfile. + +.. Create a directory and place your selected `.vsix` extensions in this directory. + +.. Create a Dockerfile with the following content: ++ +[source,dockerfile] +---- +# inherit che-incubator/che-code:latest +FROM quay.io/che-incubator/che-code:latest +USER 0 + +# copy all .vsix files to /default-extensions directory +RUN mkdir --mode=775 /default-extensions +COPY --chmod=755 *.vsix /default-extensions/ + +# add instruction to the script to copy default extensions to the working container +RUN echo "cp -r /default-extensions /checode/" >> /entrypoint-init-container.sh +---- + +.. Build the image and then push it to a registry: ++ +[source,bash] +---- +$ docker build -t yourname/che-code:next . +$ docker push yourname/che-code:next +---- + +.. Add the new ConfigMap to the user's {orch-namespace}, define the `DEFAULT_EXTENSIONS` environment variable, and specify the absolute paths to the extensions. This ConfigMap sets the environment variable to all workspaces in the user's {orch-namespace}. ++ +[source,yaml] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: vscode-default-extensions + labels: + controller.devfile.io/mount-to-devworkspace: 'true' + controller.devfile.io/watch-configmap: 'true' + annotations: + controller.devfile.io/mount-as: env +data: + DEFAULT_EXTENSIONS: '/checode/default-extensions/extension1.vsix;/checode/default-extensions/extension2.vsix' +---- + +.. Open the {prod-short} Dashboard and navigate to the *Create Workspace* tab on the left side. + +.. In the *Editor Selector* section, expand the *Use an Editor Definition* dropdown and set the editor URI to `yourname/che-code:next`. + +.. Create a workspace by selecting a sample or entering a Git repository URL. + +.Verification + +* Verify that the extensions are installed in the workspace by checking the *Extensions* panel in the editor. + +[role="_additional-resources"] +.Additional resources + +* xref:configuring-single-and-multiroot-workspaces.adoc[] +* xref:trusted-extensions-for-microsoft-visual-studio-code.adoc[] +* xref:editor-configurations-for-microsoft-visual-studio-code.adoc[] diff --git a/modules/administration-guide/pages/editor-configurations-for-microsoft-visual-studio-code.adoc b/modules/extend/pages/editor-configurations-for-microsoft-visual-studio-code.adoc similarity index 52% rename from modules/administration-guide/pages/editor-configurations-for-microsoft-visual-studio-code.adoc rename to modules/extend/pages/editor-configurations-for-microsoft-visual-studio-code.adoc index dee52b966e..5f718877b5 100644 --- a/modules/administration-guide/pages/editor-configurations-for-microsoft-visual-studio-code.adoc +++ b/modules/extend/pages/editor-configurations-for-microsoft-visual-studio-code.adoc @@ -1,50 +1,50 @@ +:page-aliases: administration-guide:editor-configurations-for-microsoft-visual-studio-code.adoc :_content-type: PROCEDURE -:description: Applying editor configurations +:description: Apply IDE settings to all workspaces :keywords: settings, extensions, configurations -:navtitle: Applying editor configurations -// :page-aliases: +:navtitle: Apply IDE settings to all workspaces [id="visual-studio-code-editor-configs"] -= Applying editor configurations += Apply IDE settings to all workspaces -You can configure Visual Studio Code - Open Source editor by adding configurations to a ConfigMap. -These configurations are applied to any workspace you open. -Once a workspace is started, the editor checks for this ConfigMap and stores configurations to the corresponding config files. + +[role="_abstract"] +Configure the Code - OSS editor for all workspaces by defining settings, recommended extensions, and product properties in a ConfigMap. When you start a workspace, the editor reads this ConfigMap and applies the configurations to the corresponding config files. The following sections are currently supported: -* settings.json -* extensions.json -* product.json -* configurations.json -* policy.json +`settings.json`:: Contains various settings with which you can customize different parts of the Code - OSS editor. + +`extensions.json`:: Contains recommended extensions that are installed when a workspace is started. + +`product.json`:: Contains properties that you need to add to the editor's *product.json* file. If the property already exists, its value is updated. -The *settings.json* section contains various settings with which you can customize different parts of the Code - OSS editor. + -The *extensions.json* section contains recommended extensions that are installed when a workspace is started. + -The *product.json* section contains properties that you need to add to the editor's *product.json* file. If the property already exists, its value will be updated. + -The *configurations.json* section contains properties for Code - OSS editor configuration. For example, you can use the `extensions.install-from-vsix-enabled` property to disable `Install from VSIX` menu item in the Extensions panel. +`configurations.json`:: Contains properties for Code - OSS editor configuration. For example, you can use the `extensions.install-from-vsix-enabled` property to disable the `Install from VSIX` menu item in the Extensions panel. ++ [NOTE] ==== -The `extensions.install-from-vsix-enabled` property disables only the UI action. Extensions can still be installed via the `workbench.extensions.command.installFromVSIX` API command or the CLI. To block these paths as well, see xref:manage-extension-installation.adoc[]. +The `extensions.install-from-vsix-enabled` property disables only the UI action. Extensions can still be installed by using the `workbench.extensions.command.installFromVSIX` API command or the CLI. To block these paths as well, see xref:manage-extension-installation.adoc[]. ==== +`policy.json`:: Controls Code - OSS extension installation by using the `AllowedExtensions` policy and the ability to fully block extension installation. See xref:manage-extension-installation.adoc[]. + +.Prerequisites -The *policy.json* section allows to control over Code - OSS extension installation using the AllowedExtensions policy, as well as the ability to fully block extension installation. See xref:manage-extension-installation.adoc[]. +* An active `{orch-cli}` session with administrative permissions to the {orch-name} cluster. See {orch-cli-link}. .Procedure -* Add a new ConfigMap to the user's {orch-namespace}, define the supported sections, and specify the properties you want to add. +. Add a new ConfigMap in valid JSON format to the user's {orch-namespace}, define the supported sections, and specify the properties you want to add. + -==== -[source,yaml] +[source,yaml,subs="+quotes"] ---- apiVersion: v1 kind: ConfigMap metadata: name: vscode-editor-configurations labels: - app.kubernetes.io/component: workspaces-config app.kubernetes.io/part-of: che.eclipse.org + app.kubernetes.io/component: workspaces-config data: extensions.json: | { @@ -71,8 +71,8 @@ data: ] }, "trustedExtensionAuthAccess": [ - ".", - "." + "____.____", + "____.____" ] } configurations.json: | @@ -80,20 +80,19 @@ data: "extensions.install-from-vsix-enabled": false } ---- -==== ++ +where: ++ +`____.____`, `____.____`:: The publisher and extension name pairs for extensions that are granted trusted authentication access. Use the format `publisher.extensionName`. -* Start or restart your workspace +. Optional: To replicate the ConfigMap across all user {orch-namespace}s while preventing user modifications, add the ConfigMap to the {prod-namespace} namespace instead of individual user {orch-namespace}s. -[NOTE] -==== -Make sure that the Configmap contains data in a valid JSON format. -==== - -TIP: Consider adding the ConfigMap to the {prod-namespace} namespace. By adding it to the namespace, you replicate the ConfigMap across all user namespaces while preventing modifications within user's namespaces. See xref:configuring-a-user-namespace.adoc[]. +. Start or restart your workspace. .Verification + . Verify that settings defined in the ConfigMap are applied using one of the following methods: -* Use `F1 → Preferences: Open Remote Settings` to check if the defined settings are applied. +* Use `F1 → Preferences: Open Remote Settings` to check if the defined settings are applied. * Ensure that the settings from the ConfigMap are present in the `/checode/remote/data/Machine/settings.json` file by using the `F1 → File: Open File...` command to inspect the file's content. . Verify that extensions defined in the ConfigMap are applied: @@ -109,3 +108,11 @@ TIP: Consider adding the ConfigMap to the {prod-namespace} namespace. By adding * Open the Command Palette (use `F1`) to check that `Install from VSIX` command is not present in the list of commands. * Use `F1 → Open View → Extensions` to open the `Extensions` panel, then click `...` on the view (`Views and More Actions` tooltip) to check that `Install from VSIX` action is absent in the list of actions. * Go to the Explorer, find a file with the `vsix` extension (redhat.vscode-yaml-1.17.0.vsix, for example), open menu for that file. `Install from VSIX` action should be absent in the menu. + +[role="_additional-resources"] +.Additional resources + +* xref:configuring-single-and-multiroot-workspaces.adoc[] +* xref:trusted-extensions-for-microsoft-visual-studio-code.adoc[] +* xref:default-extensions-for-microsoft-visual-studio-code.adoc[] +* xref:manage-extension-installation.adoc[] diff --git a/modules/administration-guide/pages/extensions-for-microsoft-visual-studio-code-open-source.adoc b/modules/extend/pages/extensions-for-microsoft-visual-studio-code-open-source.adoc similarity index 56% rename from modules/administration-guide/pages/extensions-for-microsoft-visual-studio-code-open-source.adoc rename to modules/extend/pages/extensions-for-microsoft-visual-studio-code-open-source.adoc index bf8486108d..46aa671ef3 100644 --- a/modules/administration-guide/pages/extensions-for-microsoft-visual-studio-code-open-source.adoc +++ b/modules/extend/pages/extensions-for-microsoft-visual-studio-code-open-source.adoc @@ -1,17 +1,20 @@ +:page-aliases: administration-guide:extensions-for-microsoft-visual-studio-code-open-source.adoc :_content-type: ASSEMBLY -:description: Extensions for Microsoft Visual Studio Code - Open Source +:description: How the Open VSX extension registry works :keywords: extensions, vs-code, vsx, open-vsx, marketplace -:navtitle: Extensions for Microsoft Visual Studio Code - Open Source -//:page-aliases: +:navtitle: How the Open VSX extension registry works [id="extensions-for-microsoft-visual-studio-code-open-source"] -= Extensions for Microsoft Visual Studio Code - Open Source += How the Open VSX extension registry works -To manage extensions, {prod-short} uses one of the following Open VSX registry instances: +[role="_abstract"] +{prod-short} uses an Open VSX registry instance to manage extensions for Microsoft Visual Studio Code - Open Source. -* 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]. +To manage extensions, this IDE uses one of the Open VSX registry instances: -* The public link:https://open-vsx.org[open-vsx.org] registry that is accessed over the internet. +* 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 the public open-vsx.org registry. This subset is customizable. + +* The public open-vsx.org registry that is accessed over the internet. * A standalone Open VSX registry instance that is deployed on a network accessible from {prod-short} workspace pods. diff --git a/modules/extend/pages/manage-extension-installation.adoc b/modules/extend/pages/manage-extension-installation.adoc new file mode 100644 index 0000000000..5e41d1b6c5 --- /dev/null +++ b/modules/extend/pages/manage-extension-installation.adoc @@ -0,0 +1,142 @@ +:page-aliases: administration-guide:manage-extension-installation.adoc +:_content-type: PROCEDURE +:description: Control which extensions users can install +:keywords: extensions, workspace +:navtitle: Control which extensions users can install + +[id="visual-studio-code-manage-extensions-installation"] += Control which extensions users can install + + +[role="_abstract"] +Control Code - OSS extension installation by using a ConfigMap. Enforce a fine-grained allow or deny list by using the `AllowedExtensions` policy. + +You can also block installs through the CLI, default extensions, and the `workbench.extensions.command.installFromVSIX` API command. The following properties are supported: + +* `BlockCliExtensionsInstallation` -- when enabled, blocks installation of extensions through the CLI. +* `BlockDefaultExtensionsInstallation` -- when enabled, blocks installation of default extensions. See xref:default-extensions-for-microsoft-visual-studio-code.adoc[]. +* `BlockInstallFromVSIXCommandExtensionsInstallation` -- when enabled, blocks installation of extensions through the `workbench.extensions.command.installFromVSIX` API command. +* `AllowedExtensions` -- provides fine-grained control over Code - OSS extension installation. When this policy is applied, already installed extensions that are not allowed are disabled and display a warning. For conceptual background, see link:https://code.visualstudio.com/docs/setup/enterprise#_configure-allowed-extensions[Configure allowed extensions]. + +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the {orch-name} cluster. See {orch-cli-link}. + +.Procedure + +. Add a new ConfigMap to the {prod-namespace} namespace and specify the properties you want to add: ++ +[source,yaml,subs="+attributes,+quotes"] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: vscode-editor-configurations + namespace: {prod-namespace} + labels: + app.kubernetes.io/component: workspaces-config + app.kubernetes.io/part-of: che.eclipse.org + annotations: + controller.devfile.io/mount-as: subpath + controller.devfile.io/mount-path: /checode-config + controller.devfile.io/read-only: 'true' +data: + policy.json: | + { + "BlockCliExtensionsInstallation": true, + "BlockDefaultExtensionsInstallation": true, + "BlockInstallFromVSIXCommandExtensionsInstallation": true, + "AllowedExtensions": { + "*": true, + "dbaeumer.vscode-eslint": false, + "ms-python.python": false, + "redhat": false + } + } +---- ++ +[NOTE] +==== +Ensure that the ConfigMap contains data in a valid JSON format. +==== + +. Optional: To completely disable extension installation instead of using fine-grained control, set all extensions to disallowed: ++ +[source,yaml,subs="+attributes,+quotes"] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: vscode-editor-configurations + namespace: {prod-namespace} + labels: + app.kubernetes.io/component: workspaces-config + app.kubernetes.io/part-of: che.eclipse.org + annotations: + controller.devfile.io/mount-as: subpath + controller.devfile.io/mount-path: /checode-config + controller.devfile.io/read-only: 'true' +data: + policy.json: | + { + "AllowedExtensions": { + "*": false + } + } +---- + +. Start or restart your workspace. + +. Optional: Add the ConfigMap in the user's {orch-namespace}: ++ +[source,yaml,subs="+attributes,+quotes"] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: vscode-editor-configurations + labels: + controller.devfile.io/mount-to-devworkspace: 'true' + controller.devfile.io/watch-configmap: 'true' + annotations: + controller.devfile.io/mount-as: subpath + controller.devfile.io/mount-path: /checode-config + controller.devfile.io/read-only: 'true' +data: + policy.json: | + { + "AllowedExtensions": { + "*": false + } + } +---- ++ +[NOTE] +==== +When the ConfigMap is stored in the user's {orch-namespace}, the user can edit its values. +==== + +.Verification + +. Verify that the `BlockCliExtensionsInstallation` property is applied: +* Press F1, select *Preferences: Open Settings (UI)*, and enter `BlockCliExtensionsInstallation` in search. +* Provide a `.vsix` file and try CLI install. The installation fails with "Installation of extensions via CLI has been blocked by an administrator". + +. Verify that the `BlockDefaultExtensionsInstallation` property is applied: +* Check Settings for the property. +* Configure default extensions and verify they are not installed on workspace start or restart. + +. Verify that the `BlockInstallFromVSIXCommandExtensionsInstallation` property is applied: +* Check Settings for the property. +* The `workbench.extensions.command.installFromVSIX` API command is blocked. + +. Verify that rules defined in the `AllowedExtensions` section are applied: +* Check *Settings* -> `extensions.allowed`. +* Disallowed extensions display a "This extension cannot be installed because it is not in the allowed list" warning. + +[role="_additional-resources"] +.Additional resources + +* xref:editor-configurations-for-microsoft-visual-studio-code.adoc[] +* xref:default-extensions-for-microsoft-visual-studio-code.adoc[] +* link:https://code.visualstudio.com/docs/setup/enterprise#_configure-allowed-extensions[Configure allowed extensions] diff --git a/modules/administration-guide/pages/managing-ide-extensions.adoc b/modules/extend/pages/managing-ide-extensions.adoc similarity index 88% rename from modules/administration-guide/pages/managing-ide-extensions.adoc rename to modules/extend/pages/managing-ide-extensions.adoc index 5ddb74e2b4..68a6f7d87d 100644 --- a/modules/administration-guide/pages/managing-ide-extensions.adoc +++ b/modules/extend/pages/managing-ide-extensions.adoc @@ -1,11 +1,11 @@ +:page-aliases: administration-guide:managing-ide-extensions.adoc :_content-type: CONCEPT -:description: Options for managing IDE extensions in {prod} workspaces +:description: How IDE extensions work in {prod-short} workspaces :keywords: extensions, plugins, openvsx, registry, ide -:navtitle: Managing IDE extensions -:page-aliases: +:navtitle: How IDE extensions work in workspaces [id="managing-ide-extensions"] -= Managing IDE extensions += How IDE extensions work in workspaces [role="_abstract"] Manage IDE extensions in {prod-short} workspaces to control which extensions are available, trusted, and pre-installed for users across different IDE types. Extension management is essential for air-gapped environments, security-conscious organizations, and teams that need consistent developer tooling. diff --git a/modules/administration-guide/pages/proc_configure-internal-open-vsx-access.adoc b/modules/extend/pages/proc_configure-internal-open-vsx-access.adoc similarity index 83% rename from modules/administration-guide/pages/proc_configure-internal-open-vsx-access.adoc rename to modules/extend/pages/proc_configure-internal-open-vsx-access.adoc index 51318e6f6b..3fb28c0a29 100644 --- a/modules/administration-guide/pages/proc_configure-internal-open-vsx-access.adoc +++ b/modules/extend/pages/proc_configure-internal-open-vsx-access.adoc @@ -1,18 +1,18 @@ +:page-aliases: administration-guide:proc_configure-internal-open-vsx-access.adoc :_content-type: PROCEDURE -:description: Restrict the Open VSX registry to internal cluster access +:description: Restrict the extension registry to internal cluster traffic :keywords: administration guide, openvsx, security, internal, routing -:navtitle: Configure internal Open VSX access -:page-aliases: +:navtitle: Restrict the extension registry to internal traffic [id="proc_configure-internal-open-vsx-access"] -= Configure internal access to the Open VSX registry += Restrict the extension registry to internal traffic [role="_abstract"] Restrict your Open VSX registry to internal cluster traffic by removing the public route and configuring {prod-short} to use the internal service URL. Internal routing keeps extension registry traffic within the cluster and avoids public exposure. .Prerequisites -* You have Open VSX deployed in the `openvsx` namespace. +* You have Open VSX deployed in the `openvsx` {orch-namespace}. * You have the `{orch-cli}` tool installed. * You are logged in to the cluster as a cluster administrator. * You have `jq` installed. diff --git a/modules/administration-guide/pages/proc_deleting-extension-from-postgresql-database.adoc b/modules/extend/pages/proc_deleting-extension-from-postgresql-database.adoc similarity index 82% rename from modules/administration-guide/pages/proc_deleting-extension-from-postgresql-database.adoc rename to modules/extend/pages/proc_deleting-extension-from-postgresql-database.adoc index 1785fc5f42..41fb89e82d 100644 --- a/modules/administration-guide/pages/proc_deleting-extension-from-postgresql-database.adoc +++ b/modules/extend/pages/proc_deleting-extension-from-postgresql-database.adoc @@ -1,20 +1,20 @@ +:page-aliases: administration-guide:proc_deleting-extension-from-postgresql-database.adoc :_content-type: PROCEDURE -:description: Delete an extension directly from the PostgreSQL database +:description: Remove an extension directly from the PostgreSQL database :keywords: administration guide, openvsx, delete, extension, postgresql, database -:navtitle: Delete an extension from the PostgreSQL database -:page-aliases: +:navtitle: Remove an extension directly from the database [id="proc_deleting-extension-from-postgresql-database"] -= Delete an extension from the PostgreSQL database += Remove an extension directly from the database [role="_abstract"] Remove extension records and related data directly from the PostgreSQL database when the administrator API is not available or when you need to clean up specific data. If the extension uses local storage, you must also remove its files from the Open VSX server pod. .Prerequisites -* You have access to the cluster where the Open VSX registry is deployed in the `openvsx` namespace. -* You have the `{orch-cli}` tool installed. -* You know the namespace name and extension name that you want to delete. +* An active `{orch-cli}` session with administrative permissions to the {orch-name} cluster. See {orch-cli-link}. +* The Open VSX registry is deployed in the `openvsx` {orch-namespace}. +* You know the publisher name and extension name that you want to delete. .Procedure @@ -43,20 +43,20 @@ At the `postgres=#` prompt, connect to the database: + You are now connected to the `openvsx` database as the `postgres` user. -. Find the namespace ID and extension ID: +. Find the publisher ID and extension ID: + -Identify the extension publisher. Replace `____` with the actual publisher name: +Identify the extension publisher. Replace `____` with the actual publisher name: + [source,sql,subs="+quotes",options="nowrap"] ---- -SELECT id, name FROM namespace WHERE name = '____'; +SELECT id, name FROM namespace WHERE name = '____'; ---- + -Identify the extension ID. Replace `____` and `____` with the values from the previous query: +Identify the extension ID. Replace `____` and `____` with the values from the previous query: + [source,sql,subs="+quotes",options="nowrap"] ---- -SELECT id, name, namespace_id FROM extension WHERE namespace_id = ____ AND name = '____'; +SELECT id, name, namespace_id FROM extension WHERE namespace_id = ____ AND name = '____'; ---- + Note the ID of the extension to use as `____` in the next steps. diff --git a/modules/administration-guide/pages/proc_deleting-extension-using-openvsx-admin-api.adoc b/modules/extend/pages/proc_deleting-extension-using-openvsx-admin-api.adoc similarity index 85% rename from modules/administration-guide/pages/proc_deleting-extension-using-openvsx-admin-api.adoc rename to modules/extend/pages/proc_deleting-extension-using-openvsx-admin-api.adoc index c8c5003474..bb4e66320b 100644 --- a/modules/administration-guide/pages/proc_deleting-extension-using-openvsx-admin-api.adoc +++ b/modules/extend/pages/proc_deleting-extension-using-openvsx-admin-api.adoc @@ -1,19 +1,19 @@ +:page-aliases: administration-guide:proc_deleting-extension-using-openvsx-admin-api.adoc :_content-type: PROCEDURE -:description: Delete an extension from the Open VSX registry using the administrator API +:description: Remove an extension from the Open VSX registry using the administrator API :keywords: administration guide, openvsx, delete, extension, api -:navtitle: Delete an extension using the Open VSX API -:page-aliases: +:navtitle: Remove an extension through the registry API [id="proc_deleting-extension-using-openvsx-admin-api"] -= Delete an extension by using the Open VSX administrator API += Remove an extension through the registry API [role="_abstract"] Delete an extension from your private Open VSX registry by calling the administrator API with an administrator user and a Personal Access Token (PAT). .Prerequisites -* You have access to the cluster where the Open VSX registry is deployed in the `openvsx` namespace. -* You have the `{orch-cli}` tool installed. +* An active `{orch-cli}` session with administrative permissions to the {orch-name} cluster. See {orch-cli-link}. +* The Open VSX registry is deployed in the `openvsx` {orch-namespace}. .Procedure diff --git a/modules/administration-guide/pages/proc_deploy-open-vsx-from-source.adoc b/modules/extend/pages/proc_deploy-open-vsx-from-source.adoc similarity index 92% rename from modules/administration-guide/pages/proc_deploy-open-vsx-from-source.adoc rename to modules/extend/pages/proc_deploy-open-vsx-from-source.adoc index d56f233112..7c865afe85 100644 --- a/modules/administration-guide/pages/proc_deploy-open-vsx-from-source.adoc +++ b/modules/extend/pages/proc_deploy-open-vsx-from-source.adoc @@ -1,11 +1,11 @@ +:page-aliases: administration-guide:proc_deploy-open-vsx-from-source.adoc :_content-type: PROCEDURE -:description: Build Open VSX from source and deploy a customized instance +:description: Build a custom extension registry from source code and deploy it to your cluster :keywords: administration guide, openvsx, build, deploy, registry, extensions -:navtitle: Deploy Open VSX from source -:page-aliases: +:navtitle: Build a custom extension registry from source [id="proc_deploy-open-vsx-from-source"] -= Deploy Open VSX from source += Build a custom extension registry from source [role="_abstract"] Build custom Open VSX server and CLI images from source and deploy them to your cluster. Use this method when you need a specific Open VSX version or custom modifications to the registry. @@ -13,7 +13,7 @@ Build custom Open VSX server and CLI images from source and deploy them to your .Prerequisites * You have the `{orch-cli}` tool installed. -* You are logged in to the cluster where {prod-short} is deployed as a cluster administrator. +* You are logged in to the {orch-name} cluster where {prod-short} is deployed as a cluster administrator. + [TIP] ==== @@ -25,7 +25,7 @@ Build custom Open VSX server and CLI images from source and deploy them to your .Procedure -. Create a new namespace for Open VSX: +. Create a new {orch-namespace} for Open VSX: + [source,bash,subs="+attributes,+quotes"] ---- @@ -94,7 +94,7 @@ where: | {orch-cli} apply -f - ---- -. Verify that all pods in the `openvsx` namespace are running and ready: +. Verify that all pods in the `openvsx` {orch-namespace} are running and ready: + [source,bash,subs="+attributes,+quotes",options="nowrap"] ---- @@ -160,11 +160,11 @@ export OVSX_POD_NAME=$({orch-cli} get pods -n openvsx -o jsonpath="\{.items[*].m {orch-cli} exec -n openvsx "$\{OVSX_POD_NAME}" -- bash -c "wget -O /tmp/extension.vsix ____" ---- -.. Create an extension namespace: +.. Create an extension publisher: + [source,bash,subs="+attributes,+quotes",options="nowrap"] ---- -{orch-cli} exec -n openvsx "$\{OVSX_POD_NAME}" -- bash -c "ovsx create-namespace ____" || true +{orch-cli} exec -n openvsx "$\{OVSX_POD_NAME}" -- bash -c "ovsx create-namespace ____" || true ---- .. Publish the extension: @@ -195,16 +195,12 @@ done < deploy/openshift/extensions.txt * Start any workspace and verify the published extensions are available in the Extensions view of the workspace IDE. * Navigate to the Open VSX route URL to verify the registry UI displays the published extensions. -.Next steps - -* To restrict the registry to internal cluster traffic, see xref:proc_configure-internal-open-vsx-access.adoc[]. -* To remove a published extension, see xref:proc_deleting-extension-using-openvsx-admin-api.adoc[]. - [role="_additional-resources"] .Additional resources +* To restrict the registry to internal cluster traffic, see xref:proc_configure-internal-open-vsx-access.adoc[]. +* To remove a published extension, see xref:proc_deleting-extension-using-openvsx-admin-api.adoc[]. * link:https://github.com/eclipse-openvsx/openvsx/[Eclipse Open VSX sources] * link:https://github.com/eclipse-openvsx/openvsx/releases[Eclipse Open VSX releases] * link:https://github.com/eclipse-openvsx/openvsx/wiki/[Eclipse Open VSX documentation] * xref:proc_deploy-open-vsx-from-workspace.adoc[] -* xref:proc_configure-internal-open-vsx-access.adoc[] diff --git a/modules/administration-guide/pages/proc_deploy-open-vsx-from-workspace.adoc b/modules/extend/pages/proc_deploy-open-vsx-from-workspace.adoc similarity index 94% rename from modules/administration-guide/pages/proc_deploy-open-vsx-from-workspace.adoc rename to modules/extend/pages/proc_deploy-open-vsx-from-workspace.adoc index d08cc4a012..801440ff0c 100644 --- a/modules/administration-guide/pages/proc_deploy-open-vsx-from-workspace.adoc +++ b/modules/extend/pages/proc_deploy-open-vsx-from-workspace.adoc @@ -1,11 +1,11 @@ +:page-aliases: administration-guide:proc_deploy-open-vsx-from-workspace.adoc :_content-type: PROCEDURE -:description: Deploy Open VSX from a Che workspace using devfile tasks +:description: Build the Open VSX extension registry inside a workspace using devfile tasks :keywords: administration guide, openvsx, deploy, workspace, devfile -:navtitle: Deploy Open VSX from a workspace -:page-aliases: +:navtitle: Build the extension registry inside a workspace [id="proc_deploy-open-vsx-from-workspace"] -= Deploy Open VSX from a {prod-short} workspace += Build the extension registry inside a workspace [role="_abstract"] Deploy an on-premises Open VSX extension registry by using predefined devfile tasks in a {prod-short} workspace. The workspace environment includes all necessary tools and commands defined in the `.devfile.yaml` file of the Open VSX repository. @@ -116,15 +116,11 @@ Update the `deploy/openshift/extensions.txt` file with the download URLs of each * Start any workspace and verify the published extensions are available in the Extensions view of the workspace IDE. * Open the `internal` route in the `openvsx` project to verify the registry UI displays the published extensions. -.Next steps - -* To restrict the registry to internal cluster traffic, see xref:proc_configure-internal-open-vsx-access.adoc[]. -* To remove a published extension, see xref:proc_deleting-extension-using-openvsx-admin-api.adoc[]. - [role="_additional-resources"] .Additional resources +* To restrict the registry to internal cluster traffic, see xref:proc_configure-internal-open-vsx-access.adoc[]. +* To remove a published extension, see xref:proc_deleting-extension-using-openvsx-admin-api.adoc[]. * link:https://github.com/eclipse-openvsx/openvsx/[Eclipse Open VSX sources] * link:https://github.com/eclipse-openvsx/openvsx/blob/master/.devfile.yaml[Open VSX devfile] * xref:proc_deploy-open-vsx-from-source.adoc[] -* xref:proc_configure-internal-open-vsx-access.adoc[] diff --git a/modules/administration-guide/pages/show-deprecated-editors.adoc b/modules/extend/pages/show-deprecated-editors.adoc similarity index 54% rename from modules/administration-guide/pages/show-deprecated-editors.adoc rename to modules/extend/pages/show-deprecated-editors.adoc index 54eb992c5b..c400cea9a9 100644 --- a/modules/administration-guide/pages/show-deprecated-editors.adoc +++ b/modules/extend/pages/show-deprecated-editors.adoc @@ -1,13 +1,14 @@ +:page-aliases: administration-guide:show-deprecated-editors.adoc, installation-guide:show-deprecated-editors.adoc :_content-type: PROCEDURE -:description: Show deprecated editors +:description: Restore access to deprecated editors :keywords: administration guide, show deprecated, dashboard, editors -:navtitle: Show deprecated editors -:page-aliases: installation-guide:show-deprecated-editors.adoc +:navtitle: Restore access to deprecated editors [id="show-deprecated-editors"] -= Show deprecated editors += Restore access to deprecated editors -Learn how to show deprecated {prod-short} editors on the Dashboard. By default, the Dashboard UI hides them. +[role="_abstract"] +Restore access to deprecated {prod-short} editors on the Dashboard to support users who need them during migration to a supported editor. By default, the Dashboard UI hides them. .Prerequisites @@ -17,7 +18,7 @@ Learn how to show deprecated {prod-short} editors on the Dashboard. By default, .Procedure -. An editor ID has the following format: `publisher/name/version`. Find out the IDs of the deprecated editors: +. Determine the IDs of the deprecated editors. An editor ID has the following format: `publisher/name/version`. + [source,subs="+quotes,+attributes"] ---- @@ -25,7 +26,12 @@ Learn how to show deprecated {prod-short} editors on the Dashboard. By default, -- curl -s http://localhost:8080/dashboard/api/editors | jq -r '[.[] | select(.metadata.tags != null) | select(.metadata.tags[] | contains("Deprecate")) | "\(.metadata.attributes.publisher)/\(.metadata.name)/\(.metadata.attributes.version)"]' ---- -. Configure the `CheCluster` Custom Resource. See xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]. +. Edit the `CheCluster` Custom Resource on the cluster: ++ +[source,subs="+attributes"] +---- +{orch-cli} edit checluster/{prod-checluster} -n {prod-namespace} +---- + [source,yaml] ---- @@ -39,8 +45,9 @@ spec: value: 'true' ---- +[role="_additional-resources"] .Additional resources * xref:install:using-chectl-to-configure-the-checluster-custom-resource-during-installation.adoc[] -* xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] +* xref:administration-guide:using-the-cli-to-configure-the-checluster-custom-resource.adoc[] diff --git a/modules/extend/pages/trusted-extensions-for-microsoft-visual-studio-code.adoc b/modules/extend/pages/trusted-extensions-for-microsoft-visual-studio-code.adoc new file mode 100644 index 0000000000..8a1aa0a405 --- /dev/null +++ b/modules/extend/pages/trusted-extensions-for-microsoft-visual-studio-code.adoc @@ -0,0 +1,75 @@ +:page-aliases: administration-guide:trusted-extensions-for-microsoft-visual-studio-code.adoc +:_content-type: PROCEDURE +:description: Grant extensions access to OAuth tokens +:keywords: extensions, vs-code, vsx, open-vsx, marketplace +:navtitle: Grant extensions access to OAuth tokens + +[id="visual-studio-code-trusted-extensions"] += Grant extensions access to OAuth tokens + + +[role="_abstract"] +Grant specific extensions access to OAuth authentication tokens in Microsoft Visual Studio Code by configuring the `trustedExtensionAuthAccess` field. This allows extensions that require access to services such as GitHub, Microsoft, or any other OAuth-enabled service to authenticate without manual intervention. + +[source,json,subs="+quotes"] +---- + "trustedExtensionAuthAccess": [ + "__.__", + "__.__" + ] +---- + +Define the variable in the devfile or in a ConfigMap. + +[WARNING] +==== +Use the `trustedExtensionAuthAccess` field with caution as it could potentially lead to security risks if misused. Give access only to trusted extensions. +==== + +[IMPORTANT] +==== +Since the Microsoft Visual Studio Code editor is bundled within `che-code` image, you can only change the `product.json` file when the workspace is started up. +==== + +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the {orch-name} cluster. See {orch-cli-link}. + +.Procedure + +. Define the `VSCODE_TRUSTED_EXTENSIONS` environment variable in devfile.yaml: ++ +[source,yaml,subs="+quotes"] +---- + env: + - name: VSCODE_TRUSTED_EXTENSIONS + value: "__.__,__.__" +---- + +. Alternatively, mount a ConfigMap with the `VSCODE_TRUSTED_EXTENSIONS` environment variable. With a ConfigMap, the variable is propagated to all your workspaces and you do not need to add the variable to each devfile you are using. ++ +[source,yaml,subs="+quotes"] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: trusted-extensions + labels: + controller.devfile.io/mount-to-devworkspace: 'true' + controller.devfile.io/watch-configmap: 'true' + annotations: + controller.devfile.io/mount-as: env +data: + VSCODE_TRUSTED_EXTENSIONS: '__.__,__.__' +---- + +.Verification + +* Start or restart the workspace and verify that the `trustedExtensionAuthAccess` section is added to the `product.json` file. + +[role="_additional-resources"] +.Additional resources + +* xref:configuring-single-and-multiroot-workspaces.adoc[] +* xref:default-extensions-for-microsoft-visual-studio-code.adoc[] +* xref:editor-configurations-for-microsoft-visual-studio-code.adoc[] diff --git a/modules/extend/partials/proc_adding-or-removing-extensions-in-a-workspace.adoc b/modules/extend/partials/proc_adding-or-removing-extensions-in-a-workspace.adoc new file mode 100644 index 0000000000..b0205daefd --- /dev/null +++ b/modules/extend/partials/proc_adding-or-removing-extensions-in-a-workspace.adoc @@ -0,0 +1,102 @@ +:_content-type: PROCEDURE + +[id="adding-or-removing-extensions-in-a-workspace_{context}"] += Add or remove extensions in a workspace + +[role="_abstract"] +Customize the embedded Open VSX registry instance by adding or removing extensions directly within a {prod-short} workspace to create a custom extension catalog for your organization. + +[IMPORTANT] +==== +The embedded plugin registry is deprecated; the Open VSX Registry is its successor. Setting up an internal, on-premises Open VSX Registry provides full control over the extension lifecycle, enables offline use, and improves compliance. See xref:proc_deploy-open-vsx-from-source.adoc[] for detailed setup instructions. +==== + +.Prerequisites + +* You are logged in to the {orch-name} cluster from the workspace terminal with cluster administrator permissions: ++ +[source,bash,subs="+quotes,+attributes"] +---- +{orch-cli} login --token=____ --server=____ +---- +* You have started a workspace using the link:{plugin-registry-repo-url}[plugin registry repository]. +* You have created a link:https://access.redhat.com/RegistryAuthentication[Red Hat Registry Service Account] and have the username and token available. +* You have the custom plugin registry built locally on the corresponding hardware for IBM Power (`ppc64le`) and IBM Z (`s390x`) architectures. +* You have a container image based on the latest tag or SHA to include the latest security fixes. + +.Procedure + +. 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: ++ +[source,text,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] and not link:https://open-vsx.org[Open VSX], ask the extension publisher to publish it on link:https://open-vsx.org[open-vsx.org]. See the link:https://github.com/eclipse-openvsx/openvsx/wiki/Publishing-Extensions#how-to-publish-an-extension[publishing instructions] and the link:https://github.com/marketplace/actions/publish-vs-code-extension[GitHub action]. + +If the publisher is unavailable or unwilling, and no Open VSX equivalent exists, consider link:https://github.com/open-vsx/publish-extensions/issues[reporting an issue] to the Open VSX team. +==== + +. Open the link:{plugin-registry-repo-url}/blob/main/openvsx-sync.json[`openvsx-sync.json`] file in the workspace. + +. Add or remove extensions using the following JSON syntax: ++ +[source,json,subs="+quotes"] +---- + { + "id": "____.____", + "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: + +[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 link:{plugin-registry-repo-url}/blob/main/build-config.json[`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. + +[role="_additional-resources"] +.Additional resources + +* link:{plugin-registry-repo-url}[Plugin registry repository] +* xref:proc_deploy-open-vsx-from-source.adoc[] diff --git a/modules/extend/partials/proc_adding-or-removing-extensions-on-linux.adoc b/modules/extend/partials/proc_adding-or-removing-extensions-on-linux.adoc new file mode 100644 index 0000000000..a51e6f4047 --- /dev/null +++ b/modules/extend/partials/proc_adding-or-removing-extensions-on-linux.adoc @@ -0,0 +1,126 @@ +:_content-type: PROCEDURE + +[id="adding-or-removing-extensions-on-linux_{context}"] += Add or remove extensions from the Linux command line + +[role="_abstract"] +Build and publish a custom plugin registry from the Linux command line to create a tailored Open VSX registry with the specific extensions your organization needs. + +.Prerequisites + +* You have {docker-cli} installed. +* You have Node.js version 18.20.3 or higher installed. +* You have created a link:https://access.redhat.com/RegistryAuthentication[Red Hat Registry Service Account] and have the username and token available. +* You have a container image based on the latest tag or SHA to include the latest security fixes. + +.Procedure + +. Clone the plugin registry repository: ++ +[source,terminal,subs="+attributes"] +---- +$ git clone {plugin-registry-repo-url}.git +---- + +. Change to the plugin registry directory: ++ +[source,terminal] +---- +$ cd che-plugin-registry/ +---- + +. Log in to the Red Hat registry: ++ +[source,terminal,subs="+attributes"] +---- +$ {docker-cli} 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: ++ +[source,text,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] and not link:https://open-vsx.org[Open VSX], ask the extension publisher to publish it on link:https://open-vsx.org[open-vsx.org]. See the link:https://github.com/eclipse-openvsx/openvsx/wiki/Publishing-Extensions#how-to-publish-an-extension[publishing instructions] and the link:https://github.com/marketplace/actions/publish-vs-code-extension[GitHub action]. + +If the publisher is unavailable or unwilling, and no Open VSX equivalent exists, consider link:https://github.com/open-vsx/publish-extensions/issues[reporting an issue] to the Open VSX team. +==== + +. Open the link:{plugin-registry-repo-url}/blob/main/openvsx-sync.json[`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 or internal-only extension, you can add it directly from a `.vsix` file. Use 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: ++ +[source,bash,subs="+attributes,+quotes"] +---- +$ ./build.sh -o ____ -r quay.io -t custom +---- ++ +[NOTE] +==== +Verify that the `CHE_CODE_VERSION` in the link:{plugin-registry-repo-url}/blob/main/build-config.json[`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="+attributes,+quotes"] +---- +$ {docker-cli} push quay.io/____ +---- + +. 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/____ + 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. + +[role="_additional-resources"] +.Additional resources + +* link:{plugin-registry-repo-url}[Plugin registry repository] +* xref:proc_deploy-open-vsx-from-source.adoc[] diff --git a/modules/administration-guide/partials/proc_selecting-an-open-vsx-registry-instance.adoc b/modules/extend/partials/proc_selecting-an-open-vsx-registry-instance.adoc similarity index 86% rename from modules/administration-guide/partials/proc_selecting-an-open-vsx-registry-instance.adoc rename to modules/extend/partials/proc_selecting-an-open-vsx-registry-instance.adoc index 62fc185ed5..12b9799241 100644 --- a/modules/administration-guide/partials/proc_selecting-an-open-vsx-registry-instance.adoc +++ b/modules/extend/partials/proc_selecting-an-open-vsx-registry-instance.adoc @@ -1,7 +1,7 @@ :_content-type: PROCEDURE [id="selecting-an-open-vsx-registry-instance_{context}"] -= Selecting an Open VSX registry instance += Choose which registry to use include::example$snip_{project-context}-default-vsx-registry.adoc[] @@ -13,12 +13,11 @@ include::example$snip_{project-context}-non-default-vsx-registry-instance.adoc[] .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. +* You have administrator access to the {orch-name} cluster where {prod-short} is deployed. +* You have an active `{orch-cli}` session with administrative permissions. See {orch-cli-link}. .Procedure -. Log in to the cluster as an administrator. . Edit the `CheCluster` custom resource to update the `openVSXURL` value: + [source,yaml,subs="+quotes"] @@ -30,7 +29,7 @@ spec: ---- <1> For example: `openVSXURL: "pass:c,a,q[https://open-vsx.org]"`. -.Save the changes to the custom resource. +. Save the changes to the custom resource. [IMPORTANT] ==== diff --git a/modules/extend/partials/snip_persona-admin.adoc b/modules/extend/partials/snip_persona-admin.adoc new file mode 100644 index 0000000000..825defea9a --- /dev/null +++ b/modules/extend/partials/snip_persona-admin.adoc @@ -0,0 +1 @@ +This page is for platform administrators who customize IDE extensions, editors, and AI coding assistants for {prod-short} workspaces. diff --git a/modules/secure/pages/security-best-practices.adoc b/modules/secure/pages/security-best-practices.adoc index 20fa72080c..a237877e85 100644 --- a/modules/secure/pages/security-best-practices.adoc +++ b/modules/secure/pages/security-best-practices.adoc @@ -262,7 +262,7 @@ Open Source editor. Alternatively, cluster administrators can specify a different plugin registry in the Custom Resource, for example https://open-vsx.org that contains thousands of extensions. They can also build a custom Open VSX registry. -include::administration-guide:example$snip_che-managing-extensions.adoc[] +include::extend:example$snip_che-managing-extensions.adoc[] [IMPORTANT] ====