diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index ce364864e8..888188e328 100644 --- a/modules/administration-guide/nav.adoc +++ b/modules/administration-guide/nav.adoc @@ -85,7 +85,7 @@ *** xref:configuring-storage-classes.adoc[] *** xref:configuring-the-storage-strategy.adoc[] *** xref:configuring-storage-sizes.adoc[] -*** xref:about-persistent-user-home.adoc[] +*** xref:con_persistent-user-home.adoc[] ** xref:configuring-dashboard.adoc[] *** xref:configuring-getting-started-samples.adoc[] *** xref:configuring-editors-definitions.adoc[] diff --git a/modules/administration-guide/pages/about-persistent-user-home.adoc b/modules/administration-guide/pages/about-persistent-user-home.adoc deleted file mode 100644 index 4ec6b97471..0000000000 --- a/modules/administration-guide/pages/about-persistent-user-home.adoc +++ /dev/null @@ -1,65 +0,0 @@ -:_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, the `persistUserHome` 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. diff --git a/modules/administration-guide/pages/con_persistent-user-home.adoc b/modules/administration-guide/pages/con_persistent-user-home.adoc new file mode 100644 index 0000000000..58f15d24c5 --- /dev/null +++ b/modules/administration-guide/pages/con_persistent-user-home.adoc @@ -0,0 +1,75 @@ +:_content-type: CONCEPT +:description: Persistent user home preserves the /home/user directory across workspace restarts +:keywords: administration guide, {prod-id-short}, persistent, user, home +:navtitle: Persistent user home +:page-aliases: about-persistent-user-home.adoc + +[id="persistent-user-home"] += Persistent user home + +[role="_abstract"] +{prod} preserves the `/home/user` directory across workspace restarts for each non-ephemeral workspace, so that user-specific configurations, shell history, and tooling settings persist between sessions. + +This feature is enabled by default. To disable it, set `spec.devEnvironments.persistUserHome.enabled` to `false` in the CheCluster custom resource. + +For newly started workspaces, this feature creates a persistent volume claim (PVC) mounted to the `/home/user` path of the tools container. +The tools container is the first container defined in the devfile. +This is the container that includes the project source code by default. + +When the PVC is mounted for the first time, the persistent volume's contents 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. +It runs a `stow` command to create symbolic links in the persistent volume, populating the `/home/user` directory. + +[NOTE] +==== +For files that cannot be symbolically linked to the `/home/user` directory, such as `.viminfo` and `.bashrc`, `cp` is used instead of `stow`. +==== + +The primary function of the `stow` command is to run: + +[source,bash,subs="+quotes,+attributes"] +---- +stow -t /home/user/ -d /home/tooling/ --no-folding +---- + +This command 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, the `persistUserHome` feature expects the tooling image to have its `/home/user/` content within `/home/tooling`. + +For example, if the tools container image contains `.config` and `.config-folder/another-file` in the `/home/tooling` directory, `stow` creates symbolic links as follows: + +.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 only runs `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. The persistent volume contains symbolic links, not the actual files. +. If the tools image is updated with newer versions of existing binaries, configs, and files, the init container does not need to rerun `stow`. The existing symbolic links already point to the newer versions in `/home/tooling`. + +[NOTE] +==== +If the tooling image is updated with additional binaries or files, they are not symbolically linked to the `/home/user` directory. The `stow` command does not run again automatically. + +To rerun `stow`, delete the `/home/user/.stow_completed` file and restart the workspace. +==== + +== `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, the tools image must meet three requirements to support the `persistUserHome` feature. + +* The tools image must contain `stow` version >= 2.4.0. +* The `$HOME` environment variable is set to `/home/user`. +* The directory intended to contain the `/home/user` content is `/home/tooling`. + +Because the `/home/user` content must reside in `/home/tooling`, the default UDI image for example adds the `/home/user` content to `/home/tooling` instead, and runs: + +[source,dockerfile,subs="+quotes,+attributes"] +---- +RUN stow -t /home/user/ -d /home/tooling/ --no-folding +---- + +This `RUN` instruction in the Dockerfile ensures that files in `/home/tooling` are accessible from `/home/user` even when the `persistUserHome` feature is not enabled. diff --git a/modules/administration-guide/pages/configuring-storage.adoc b/modules/administration-guide/pages/configuring-storage.adoc index 7fcfdc3952..5ef860496d 100644 --- a/modules/administration-guide/pages/configuring-storage.adoc +++ b/modules/administration-guide/pages/configuring-storage.adoc @@ -7,10 +7,10 @@ [id="configuring-storage"] = Configuring storage -[IMPORTANT] - -.Understanding supported storage protocols and requirements +[role="_abstract"] +Configure storage classes, strategies, sizes, and persistent user home to control how {prod-short} workspaces store project files and user data. +[IMPORTANT] ==== {prod} workspaces require storage with **volumeMode: FileSystem** because the development environment is designed to store project files, code, and configurations in a standard, hierarchical directory structure (such as /projects). @@ -25,4 +25,4 @@ To overcome these stability and quota issues, it is recommended to use certified * xref:configuring-storage-classes.adoc[] * xref:configuring-the-storage-strategy.adoc[] * xref:configuring-storage-sizes.adoc[] -* xref:about-persistent-user-home.adoc[] +* xref:con_persistent-user-home.adoc[]