Cherry pick security best practices doc update

antora.yml

@@ -1,8 +1,8 @@
 ---
 name: docs
 title: Documentation
-version: next
-prerelease: true
+version: 7.95.x
+prerelease: false
 start_page: overview:introduction-to-eclipse-che.adoc
 nav:
   - modules/overview/nav.adoc
@@ -25,7 +25,7 @@ asciidoc:
     # for the project
     che-plugin-registry-directory: che-plugin-registry
     devworkspace-operator-index-disconnected-install: quay.io/devfile/devworkspace-operator-index:release-digest
-    devworkspace-operator-version-patch: "0.31.1"
+    devworkspace-operator-version-patch: "0.31.2"
     devworkspace: DevWorkspace
     devworkspace-id: devworkspace
     docker-cli: docker
@@ -98,8 +98,8 @@ asciidoc:
     prod-upstream: Eclipse Che
     prod-url: "https://__<che_fqdn>__"
     prod-ver-major: "7"
-    prod-ver-patch: "7.94.0"
-    prod-ver: "7.94"
+    prod-ver-patch: "7.95.0"
+    prod-ver: "7.95"
     prod-workspace: che-ws
     prod: Eclipse Che
     prod2: Eclipse Che

modules/administration-guide/examples/snip_che-curated-access.adoc

@@ -0,0 +1,4 @@
+With this setup, you achieve a curated access to {prod-short},
+where cluster administrators control provisioning for each user
+and can explicitly configure various settings including resource limits and quotas.
+Learn more about project provisioning in the xref:administration-guide:provisioning-namespaces-in-advance.adoc[].

modules/administration-guide/nav.adoc

@@ -1,5 +1,6 @@
 .Administration Guide
 
+* xref:security-best-practices.adoc[]
 * xref:preparing-the-installation.adoc[]
 ** xref:supported-platforms.adoc[]
 ** xref:installing-the-chectl-management-tool.adoc[]
@@ -50,7 +51,6 @@
 *** xref:enabling-users-to-run-multiple-workspaces-simultaneously.adoc[]
 *** xref:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[]
 *** xref:configuring-workspaces-nodeselector.adoc[]
-*** xref:configuring-the-open-vsx-registry-url.adoc[]
 *** xref:configuring-allowed-urls-for-cloud-development-environments.adoc[]
 ** xref:caching-images-for-faster-workspace-start.adoc[]
 *** xref:installing-kubernetes-image-puller.adoc[]
@@ -79,6 +79,7 @@
 *** xref:configuring-storage-classes.adoc[]
 *** xref:configuring-the-storage-strategy.adoc[]
 *** xref:configuring-storage-sizes.adoc[]
+*** xref:about-persistent-user-home.adoc[]
 ** xref:configuring-dashboard.adoc[]
 *** xref:configuring-getting-started-samples.adoc[]
 *** xref:configuring-editors-definitions.adoc[]
@@ -101,6 +102,7 @@
 *** xref:enabling-fuse-for-all-workspaces.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:configuring-visual-studio-code.adoc[]
 ** xref:configuring-single-and-multiroot-workspaces.adoc[]
 ** xref:trusted-extensions-for-microsoft-visual-studio-code.adoc[]

modules/administration-guide/pages/about-persistent-user-home.adoc

@@ -0,0 +1,65 @@
+:_content-type: CONCEPT
+:description: About persistent user home
+:keywords: administration guide, about, {prod-id-short}, persistent, user, home
+:navtitle: Persistent user home
+:page-aliases:
+
+[id="about-persistent-user-home"]
+= Persistent user home
+
+
+{prod} provides a persistent home directory feature that allows each non-ephemeral workspace to have their `/home/user` directory be persisted across workspace restarts.
+You can enable this feature in the CheCluster by setting `spec.devEnvironments.persistUserHome.enabled` to `true`.
+
+For newly started workspaces, this feature creates a PVC mounted to the `/home/user` path of the tools container.
+In this documentation, a "tools container" will be used to refer to the first container in the devfile.
+This container is the container that includes the project source code by default.
+
+When the PVC is mounted for the first time, the persistent volume's content are empty and therefore must be populated with the `/home/user` directory content.
+
+By default, the `persistUserHome` feature creates an init container for each new workspace pod named `init-persistent-home`.
+This init container is created with the tools container image and is responsible for running a `stow` command to create symbolic links
+in the persistent volume to populate the `/home/user` directory.
+
+NOTE: For files that cannot be symbolically linked to the `/home/user` directory such as the `.viminfo` and `.bashrc` file, `cp` is used instead of `stow`.
+
+The primary function of the `stow` command is to run:
+[subs="+quotes,attributes"]
+----
+stow -t /home/user/ -d /home/tooling/ --no-folding
+----
+
+The command above creates symbolic links in `/home/user` for files and directories located in /home/tooling. This populates the persistent volume with symbolic links to the content in `/home/tooling`. As a result, it the `persistentUserHome` feature expects the tooling image to have its `/home/user/` content within `/home/tooling`.
+
+For example, if the tools container image contains files in the `home/tooling` directory such as `.config` and `.config-folder/another-file`, stow will create symbolic links in the persistent volume in the following manner:
+
+.Tools container with `persistUserHome` enabled
+image::persistent-user-home/tools-container-example.png[Persistent user home example scenario]
+
+The init container writes the output of the `stow` command to `/home/user/.stow.log` and will only run `stow` the first time the persistent volume is mounted to the workspace. 
+
+Using the `stow` command to populate `/home/user` content in the persistent volume provides two main advantages:
+
+. Creating symbolic links is faster and consumes less storage than creating copies of the `/home/user` directory content in the persistent volume. To put it differently, the persistent volume in this case contains symbolic links and not the actual files themselves.
+. If the tools image is updated with newer versions of existing binaries, configs, and files, the init container does not need to `stow` the new versions, as the existing symbolic links will link to the newer versions in `/home/tooling` already.
+
+NOTE: If the tooling image is updated with additional binaries or files, they won't be symbolically linked to the `/home/user` directory since the `stow` command won't be run again. In this case, the user must delete the `/home/user/.stow_completed` file and restart the workspace to rerun `stow`.
+
+.`persistUserHome` tools image requirements
+
+The `persistUserHome` depends on the tools image used for the workspace. By default {prod-short} uses the Universal Developer Image (UDI) for sample workspaces, which supports `persistUserHome` out of the box.
+
+If you are using a custom image, there are three requirements that should be met to support the `persistUserHome` feature.
+
+. The tools image should contain `stow` version >= 2.4.0.
+. The `$HOME` environment variable is set to `/home/user`.
+. In the tools image, the directory that is intended to contain the `/home/user` content is `/home/tooling`.
+
+Due to requirement three, the default UDI image for example adds the `/home/user` content to `/home/tooling` instead, and runs:
+
+[subs="+quotes,attributes"]
+----
+RUN stow -t /home/user/ -d /home/tooling/ --no-folding 
+----
+
+in the Dockerfile so that files in `/home/tooling` are accessible from `/home/user` even when not using the `persistUserHome` feature.

modules/administration-guide/pages/caching-images-for-faster-workspace-start.adoc

@@ -23,4 +23,5 @@ include::partial$snip_configuring-kubernetes-image-puller.adoc[]
 
 .Additional resources
 
+* xref:retrieving-default-list-of-images-for-kubernetes-image-puller.adoc[]
 * link:https://github.com/che-incubator/{image-puller-repository-name}[{image-puller-name} source code repository]

modules/administration-guide/pages/configuring-storage.adoc

@@ -14,4 +14,5 @@
 
 * xref:configuring-storage-classes.adoc[]
 * xref:configuring-the-storage-strategy.adoc[]
-* xref:configuring-storage-sizes.adoc[]
+* xref:configuring-storage-sizes.adoc[]
+* xref:about-persistent-user-home.adoc[]

modules/administration-guide/pages/configuring-the-open-vsx-registry-url.adoc

@@ -22,6 +22,11 @@ spec:
        openVSXURL: __<your_open_vsx_registy>__
 # [...]
 ----
++
+[WARNING]
+====
+Due to the dedicated Microsoft link:https://cdn.vsassets.io/v/M190_20210811.1/_content/Microsoft-Visual-Studio-Marketplace-Terms-of-Use.pdf[Terms of Use], link:https://marketplace.visualstudio.com/vscode[Visual Studio Code Marketplace] is not supported by {prod}.
+====
 
 .Additional resources
 * xref:using-the-cli-to-configure-the-checluster-custom-resource.adoc[]

modules/administration-guide/pages/enabling-fuse-for-all-workspaces.adoc

@@ -7,42 +7,19 @@
 [id="enabling-fuse-overlayfs-for-all-workspaces"]
 = Enabling fuse-overlayfs for all workspaces
 
+Learn about configuring the workspace's container entrypoint script so that fuse-overlayfs is used for all workspaces using that container.
+
+The Universal Developer Image (UDI) already contains the necessary configuration by default.
+However, you must configure the script manually if you use custom images due to Podman 5.x requiring the `/home/user/.config` folder to be owned by the current user.
+
 .Prerequisites
 
-* The xref:administration-guide:enabling-access-to-dev-fuse-for-openshift.adoc[] section has been completed. This is not required for OpenShift versions 4.15 and later.
+* For OpenShift versions 4.14 and lower, the xref:administration-guide:enabling-access-to-dev-fuse-for-openshift.adoc[] section has been completed.
 
 * An active `{orch-cli}` session with administrative permissions to the destination OpenShift cluster. See {orch-cli-link}.
 
 .Procedure
 
-. Create a ConfigMap that mounts the `storage.conf` file for all user workspaces. 
-+
-====
-[source,yaml,subs="+quotes,+attributes"]
-----
-kind: ConfigMap
-apiVersion: v1
-metadata:
-  name: fuse-overlay
-  namespace: {prod-namespace}
-  labels:
-    app.kubernetes.io/part-of: che.eclipse.org
-    app.kubernetes.io/component: workspaces-config
-  annotations:
-    controller.devfile.io/mount-as: subpath
-    controller.devfile.io/mount-path: /home/user/.config/containers/
-data:
-  storage.conf: |
-    [storage]
-    driver = "overlay"
-
-    [storage.options.overlay]
-    mount_program="/usr/bin/fuse-overlayfs"
-----
-====
-+
-WARNING: Creating this ConfigMap will cause all running workspaces to restart.
-
 . Set the necessary annotation in the `spec.devEnvironments.workspacesPodAnnotations` field of the CheCluster custom resource.
 +
 ====
@@ -59,12 +36,51 @@ spec:
 +
 [NOTE]
 ====
-For OpenShift versions before 4.15, the `io.openshift.podman-fuse: ""` annotation is also required.
+For OpenShift versions 4.14 and lower, the `io.openshift.podman-fuse: ""` annotation is also required.
+====
+
+. Optional: If you are using a custom image for the workspace container, create the `/home/user/.config` folder and configure the `storage.conf` file on runtime via the entrypoint.
+To do this, add the following to the workspace container image's entrypoint script before building the image.
+Creating the `/home/user/.config` folder in the entrypoint results in the folder being owned by the current user which is not known at image build time.
++
+====
+[source,subs="+quotes,+macros"]
+----
+# Configure container builds to use vfs or fuse-overlayfs
+if [ ! -d "${HOME}/.config/containers" ]; then
+  mkdir -p ${HOME}/.config/containers
+  if [ -c "/dev/fuse" ] && [ -f "/usr/bin/fuse-overlayfs" ]; then
+    (echo '[storage]';echo 'driver = "overlay"';echo '[storage.options.overlay]';echo 'mount_program = "/usr/bin/fuse-overlayfs"') > ${HOME}/.config/containers/storage.conf
+  else
+    (echo '[storage]';echo 'driver = "vfs"') > "${HOME}"/.config/containers/storage.conf
+  fi
+fi
+----
 ====
++
+This ensures that if the `/home/user/.config` doesn't already exist, the folder is created and owned by `user`.
+The `/home/user/.config` may already exist for example, if it was stored in a persistent volume.
++
 
 .Verification steps
 
-. Start a workspace and verify that the storage driver is `overlay`.
+. Start a workspace and verify that the owner for `/home/user/.config` is `user`.
++
+[subs="+attributes,+quotes"]
+----
+$ ls -la /home/user
+----
+
++
+Example output:
++
+[subs="+attributes,+quotes"]
+----
+...
+drwxrwsr-x.  3 user 1000660000   24 Dec 24 15:40 .config
+----
+
+. Verify that the storage driver is `overlay`.
 +
 [subs="+attributes,+quotes"]
 ----
@@ -79,8 +95,8 @@ Example output:
 graphDriverName: overlay
   overlay.mount_program:
     Executable: /usr/bin/fuse-overlayfs
-    Package: fuse-overlayfs-1.12-1.module+el8.9.0+20326+387084d0.x86_64
-      fuse-overlayfs: version 1.12
+    Package: fuse-overlayfs-1.14-1.el9.x86_64
+      fuse-overlayfs: version 1.13-dev
   Backing Filesystem: overlayfs
 ----
 +

modules/administration-guide/pages/installing-che-on-red-hat-openshift-local.adoc

@@ -14,7 +14,7 @@ You can create a single-node OpenShift cluster for deploying a {prod-short} inst
 
 * `{prod-cli}`. See: xref:installing-the-chectl-management-tool.adoc[].
 
-* A running instance of {rh-os-local}. See link:https://console.redhat.com/openshift/create/local[Installing {rh-os-local}].```
+* A running instance of {rh-os-local}. See link:https://developers.redhat.com/products/openshift-local/overview[{rh-os-local} overview].```
 
 * The file path of the user's {rh-os-local} pull secret.
 
@@ -77,4 +77,4 @@ $ {prod-cli} dashboard:open
 
 .Additional resources
 
-* link:https://access.redhat.com/documentation/en-us/red_hat_openshift_local/[Product documentation for {rh-os-local}].
+* link:https://developers.redhat.com/products/openshift-local/overview[{rh-os-local}].

modules/administration-guide/pages/installing-image-puller-on-openshift-using-cli.adoc

@@ -9,15 +9,19 @@
 
 You can install the {image-puller-name} on OpenShift by using OpenShift `oc` management tool.
 
+[IMPORTANT]
+====
+If the ImagePuller is installed with the `oc` CLI, it cannot be configured via the `CheCluster` Custom Resource.
+====
+
 .Prerequisites
 
 * An active `oc` session with administrative permissions to the OpenShift cluster. See link:https://docs.openshift.com/container-platform/{ocp4-ver}/cli_reference/openshift_cli/getting-started-cli.html[Getting started with the OpenShift CLI].
 
 .Procedure
 
-. Gather a list of relevant container images to pull by navigating to the links:
-* `pass:c,a,q[{prod-url}]/plugin-registry/v3/external_images.txt`
-* `pass:c,a,q[{prod-url}]/devfile-registry/devfiles/external_images.txt`
+. Gather a list of relevant container images to pull by following the doc:
+xref:retrieving-default-list-of-images-for-kubernetes-image-puller.adoc[]
 
 . Define the memory requests and limits parameters to ensure pulled containers and the platform have enough memory to run.
 +
@@ -37,8 +41,8 @@ Pulling 5 images on 20 nodes, with a container memory limit of `20Mi` requires `
 +
 [subs="+attributes,+quotes"]
 ----
-$ git clone https://github.com/che-incubator/{image-puller-repository-name}
-$ cd {image-puller-repository-name}/deploy/openshift
+git clone https://github.com/che-incubator/{image-puller-repository-name}
+cd {image-puller-repository-name}/deploy/openshift
 ----
 
 . Configure the `app.yaml`, `configmap.yaml` and `serviceaccount.yaml` OpenShift templates using following parameters:
@@ -133,16 +137,16 @@ $ cd {image-puller-repository-name}/deploy/openshift
 +
 [subs="+attributes,+quotes"]
 ----
-$ oc new-project __<{image-puller-namespace}>__
+oc new-project __<{image-puller-namespace}>__
 ----
 
 . Process and apply the templates to install the puller:
 +
 [subs="+attributes,+quotes"]
 ----
-$ oc process -f serviceaccount.yaml | oc apply -f -
-$ oc process -f configmap.yaml | oc apply -f -
-$ oc process -f app.yaml | oc apply -f -
+oc process -f serviceaccount.yaml | oc apply -f -
+oc process -f configmap.yaml | oc apply -f -
+oc process -f app.yaml | oc apply -f -
 ----
 
 
@@ -152,12 +156,16 @@ $ oc process -f app.yaml | oc apply -f -
 +
 [source%nowrap,dummy,subs="+quotes,+attributes"]
 ----
-$ oc get deployment,daemonset,pod --namespace __<{image-puller-namespace}>__
+oc get deployment,daemonset,pod --namespace __<{image-puller-namespace}>__
 ----
 
 . Verify the values of the __<{image-puller-deployment-name}>__ `ConfigMap`.
 +
 [source%nowrap,dummy,subs="+quotes,+attributes"]
 ----
-$ oc get configmap __<{image-puller-deployment-name}>__ --output yaml
+oc get configmap __<{image-puller-deployment-name}>__ --output yaml
 ----
+
+.Additional resources
+
+* xref:retrieving-default-list-of-images-for-kubernetes-image-puller.adoc[]

modules/administration-guide/pages/managing-ide-extensions.adoc

@@ -10,3 +10,5 @@
 IDEs use extensions or plugins to extend their functionality, and the mechanism for managing extensions differs between IDEs.
 
 * xref:extensions-for-microsoft-visual-studio-code-open-source.adoc[]
+* xref:configuring-the-open-vsx-registry-url.adoc[]
+

modules/administration-guide/pages/permissions-to-install-che.adoc

@@ -1,7 +1,7 @@
 :_content-type: ASSEMBLY
 :description: Permissions to install {prod}
 :keywords: administration-guide, installing, permissions
-:navtitle: Permissions to install Che
+:navtitle: Permissions to install {prod-short}
 :page-aliases:
 
 [id="permissions-to-install-che"]