Chapter 20. Configure Visual Studio Code - Open Source ("Code - OSS")

Procedure

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

   {
   	"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.

2. Define the VSCODE_DEFAULT_WORKSPACE environment variable in your devfile with the path to an alternative workspace file.

      env:
        - name: VSCODE_DEFAULT_WORKSPACE
          value: "/projects/project-name/workspace-file"

3. Define the VSCODE_DEFAULT_WORKSPACE environment variable and set it to / to open a workspace in single-root mode.

      env:
        - name: VSCODE_DEFAULT_WORKSPACE
          value: "/"

Procedure

1. Define the VSCODE_TRUSTED_EXTENSIONS environment variable in devfile.yaml:

      env:
        - name: VSCODE_TRUSTED_EXTENSIONS
          value: "<publisher1>.<extension1>,<publisher2>.<extension2>"

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

   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: '<publisher1>.<extension1>,<publisher2>.<extension2>'

Procedure

1. 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:

   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'

2. 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:

   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

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

   1. Create a directory and place your selected .vsix extensions in this directory.

   2. Create a Dockerfile with the following content:

      # 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

   3. Build the image and then push it to a registry:

      $ docker build -t yourname/che-code:next .
      $ docker push yourname/che-code:next

   4. Add the new ConfigMap to the user’s project, 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 project.

      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'

   5. Open the OpenShift Dev Spaces Dashboard and navigate to the Create Workspace tab on the left side.
   6. In the Editor Selector section, expand the Use an Editor Definition dropdown and set the editor URI to yourname/che-code:next.
   7. Create a workspace by selecting a sample or entering a Git repository URL.

Procedure

1. Add a new ConfigMap in valid JSON format to the user’s project, define the supported sections, and specify the properties you want to add.

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: vscode-editor-configurations
     labels:
        app.kubernetes.io/part-of: che.eclipse.org
   data:
     extensions.json: |
       {
         "recommendations": [
             "dbaeumer.vscode-eslint",
             "github.vscode-pull-request-github"
         ]
       }
     settings.json: |
       {
         "window.header": "A HEADER MESSAGE",
         "window.commandCenter": false,
         "workbench.colorCustomizations": {
           "titleBar.activeBackground": "#CCA700",
           "titleBar.activeForeground": "#ffffff"
         }
       }
     product.json: |
       {
         "extensionEnabledApiProposals": {
           "ms-python.python": [
             "contribEditorContentMenu",
             "quickPickSortByLabel"
           ]
         },
         "trustedExtensionAuthAccess": [
           "<publisher1>.<extension1>",
           "<publisher2>.<extension2>"
         ]
       }
     configurations.json: |
       {
         "extensions.install-from-vsix-enabled": false
       }

   where:

   <publisher1>.<extension1>, <publisher2>.<extension2>

   The publisher and extension name pairs for extensions that are granted trusted authentication access. Use the format publisher.extensionName.

2. Optional: To replicate the ConfigMap across all user projects while preventing user modifications, add the ConfigMap to the openshift-devspaces namespace instead of individual user projects.
3. Start or restart your workspace.

Verification

1. 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.
   • 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.

2. Verify that extensions defined in the ConfigMap are applied:

   • Go to the Extensions view (F1 View: Show Extensions) and check that the extensions are installed
   • Ensure that the extensions from the ConfigMap are present in the .code-workspace file by using the F1 File: Open File…​ command. By default, the workspace file is placed at /projects/.code-workspace.

3. Verify that product properties defined in the ConfigMap are being added to the Visual Studio Code product.json:

   • Open a terminal, run the command cat /checode/entrypoint-logs.txt | grep -a "Node.js dir" and copy the Visual Studio Code path.
   • Press Ctrl + O, paste the copied path and open product.json file.
   • Ensure that product.json file contains all the properties defined in the ConfigMap.

4. Verify that extensions.install-from-vsix-enabled property defined in the ConfigMap is applied to the Code - OSS editor:

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

Procedure

1. Add a new ConfigMap to the openshift-devspaces namespace and specify the properties you want to add:

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: vscode-editor-configurations
     namespace: openshift-devspaces
     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.

2. Optional: To completely disable extension installation instead of using fine-grained control, set all extensions to disallowed:

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: vscode-editor-configurations
     namespace: openshift-devspaces
     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
         }
       }

3. Start or restart your workspace.

4. Optional: Add the ConfigMap in the user’s project:

   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 project, the user can edit its values.

Verification

1. 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".

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

3. Verify that the BlockInstallFromVSIXCommandExtensionsInstallation property is applied:

   • Check Settings for the property.
   • The workbench.extensions.command.installFromVSIX API command is blocked.

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