docs: everest mount page refresh #9601

nopcoder · 2025-10-25T09:03:54Z

improved structure of mount documentation
more information about how everest mount cache works

github-actions · 2025-10-25T09:04:26Z

📚 Documentation preview at https://pr-9601.docs-lakefs-preview.io/

(Updated: 10/30/2025, 10:11:18 AM - Commit: 8075bcb)

nopcoder · 2025-10-26T09:37:09Z

@talSofer updated the documentation structure - let me know if it is better now/
@yonipeleg33 added information on how everest v1 cache works

talSofer

Thank you for improving the docs!!

I suggested multiple changes to structure, let me know what you think

talSofer · 2025-10-26T11:54:04Z

docs/src/reference/mount.md

-### OS and Protocol Support
+- **Simplified Data Loading**: Use your existing tools to read and write files directly from the filesystem with no need for custom data loaders or SDKs.
+- **Seamless Scalability**: Scale from a few local files to billions without changing your tools or workflow. Use the same code from experimentation to production.
+- **Enhanced Performance**: Everest supports billions of files and offers fast, lazy data fetching, making it ideal for optimizing GPU utilization and other performance-sensitive tasks.


The use case title sounds like a technical benefit of mount. But there is a use case for performant data loading which I believe should be highlighted instead. WDYT?

talSofer · 2025-10-26T11:55:52Z

docs/src/reference/mount.md

-
-### OS and Protocol Support
+- **Simplified Data Loading**: Use your existing tools to read and write files directly from the filesystem with no need for custom data loaders or SDKs.
+- **Seamless Scalability**: Scale from a few local files to billions without changing your tools or workflow. Use the same code from experimentation to production.


Can the use case be called "workflow scalability"? If you can describe what scales with lakeFS mount it will add clarity.

talSofer · 2025-10-26T11:59:17Z

docs/src/reference/mount.md

+    After completing this getting started guide, we recommend reading the [Core Concepts](#core-concepts) section to understand caching, consistency, and performance characteristics.

-## Authenticate with lakeFS Credentials
+### 1. Prerequisites


nit; I would remove the numbers, it reduces clarity

talSofer · 2025-10-26T12:00:04Z

docs/src/reference/mount.md

+3.  **Configuration File:** `~/.lakectl.yaml` (or the file specified by `--lakectl-config`).

-### Prerequisites
+#### Authentication Methods


Can we keep this heading outside the toc?

talSofer · 2025-10-26T12:00:55Z

docs/src/reference/mount.md

-    If you choose to configure IAM provider using the same lakectl file (i.e `lakectl.yaml`) that you use for the **lakectl cli**, 
-    you must upgrade lakectl to version (`≥ v1.57.0`) otherwise lakectl will raise errors when using it.
-
+### 3. Your First Mount (Read-Only)


Suggested change

### 3. Your First Mount (Read-Only)

### Create Your First Mount

talSofer · 2025-10-26T12:10:12Z

docs/src/reference/mount.md

+### Consistency & Data Behavior

-### Commit Command (write-mode only)
+Understanding how Everest handles data consistency is crucial for working effectively with mounted lakeFS repositories.


I would remove this line

docs/src/reference/mount.md

talSofer · 2025-10-26T12:22:19Z

docs/src/reference/mount.md

+-   **Security Context:** Setting Pod `securityContext` (e.g., `runAsUser`) is not currently supported.

-**Helm Chart default values:**
+### 1. Prerequisites


It's confusing to have this prerequisites section after we have a general prerequisites section

Prerequisites at this level is part of the CSI driver

talSofer · 2025-10-26T12:38:48Z

docs/src/reference/mount.md

+---

-## Authentication Chain for lakeFS
+## Getting Started


IIUC the getting started part is only relevant to local mounts (as opposed to CSI mounts).
I think that it will be easier to follow the docs if we:

Change the overall outline (see suggested outline below)

Exclude headings 4+ from the toc

Suggested outline:

Use Cases

Core Concepts

Cache Behavior

Consistency & Data Behavior

Performance Considerations

Mount a local filesystem or Working with local data (whatever works better)

Getting Started

Prerequisites

Authentication & Configuration

Create Your First Mount

Mount Modes

Read-Only

Write

Mount on Kubernetes (CSI Driver)

How it Works

Getting Started

Prerequisites

Deploy the CSI Driver

Use in Pods

Troubleshooting

Limitations

Command-Line Reference

Advanced Topics

Write Mode Limitations

Integration with Git

FAQ

WDYT?

talSofer · 2025-10-26T12:42:27Z

docs/src/reference/mount.md


-* **Optimized selective data access**: The lazy prefetch strategy saves storage space and reduces latency by only fetching the required data.
-* **Reduced initial latency**: Start working on your data immediately without waiting for downloads.
+While both tools work with local data, they serve different needs. Use `lakectl local` for Git-like workflows where you need to pull and push entire directories. Use **lakeFS Mount** for cases where you want immediate, on-demand access to a large repository without downloading it first, making it ideal for exploration, training ML models, or any task that benefits from lazy loading.


Here I would not highlight any advantages of lakectl local, because mount can do anything it does. I would say that mount enables anything lakectl local enables plus all the advantages you mentioned here.

update - don't think we say that lakectl is better, as we wrote that it will download all the files. try to emphasis the part where mount can be use for cases you like to have fast and transparent work for ml.

yonipeleg33

Only reviewed cache-related parts - LGTM, thanks!

yonipeleg33 · 2025-10-27T12:00:04Z

docs/src/reference/mount.md

+**Benefits of persistent cache:**

-The `umount` command is used to unmount a currently mounted lakeFS repository.
+-   Faster startup times when remounting the same data.


Just to clarify - Is this referring to downloading metadata?

it is relevant for both. if we remount using the same cache directory, all the data we accessed should be already available in the cache.

yonipeleg33 · 2025-10-27T12:01:46Z

docs/src/reference/mount.md

+-   **Commit-Based Caching**: Each commit ID has its own cache namespace. This ensures that cached data always corresponds to the correct version of your files.
+-   **Cache Invalidation on Commit**: When you commit changes in write mode using `everest commit`, the mount point's source commit ID is updated to the new HEAD of the branch. As a result, the cache associated with the old commit ID is no longer used, and new data will be cached under the new commit ID.


This is currently true, but might not be in the foreseeable future (we might want to share cached objects across commits) - so just remember to update the docs accordingly

sure - each release we will need to update the documentation to reflect the user whats running on their machine.

Co-authored-by: talSofer <[email protected]>

nopcoder · 2025-10-30T09:56:55Z

@talSofer addressed some of the feedback, I would like to do it incremental and enable other updates for the Everest for Windows before address more layout changes.

Will open a new PR to address the rest of the comments.

docs: mount doc refresh

1691d30

nopcoder self-assigned this Oct 25, 2025

nopcoder added docs Improvements or additions to documentation exclude-changelog PR description should not be included in next release changelog minor-change Used for PRs that don't require issue attached labels Oct 25, 2025

nopcoder added 3 commits October 25, 2025 17:26

docs: revert some of the missing information

468d9f1

remove refactoring to mount.md

508ed11

Improved Everest mount documentation for clarity and organization

6d1702b

nopcoder requested review from Isan-Rivkin, talSofer and yonipeleg33 October 26, 2025 09:35

nopcoder marked this pull request as ready for review October 26, 2025 09:37

talSofer previously requested changes Oct 26, 2025

View reviewed changes

yonipeleg33 approved these changes Oct 27, 2025

View reviewed changes

nopcoder and others added 5 commits October 30, 2025 11:06

doc review changes

ad448d1

Apply suggestion from @talSofer

be450a3

Co-authored-by: talSofer <[email protected]>

Apply suggestion from @talSofer

398cf16

Co-authored-by: talSofer <[email protected]>

level 4 heading not as part of toc

29785d8

more docs review changes

8075bcb

nopcoder requested a review from talSofer October 30, 2025 09:56

nopcoder requested review from talSofer and removed request for talSofer October 30, 2025 09:58

nopcoder enabled auto-merge (squash) October 30, 2025 09:59

nopcoder merged commit 4a26109 into master Oct 30, 2025
41 checks passed

nopcoder deleted the docs/mount-refresh branch October 30, 2025 10:10

	### 3. Your First Mount (Read-Only)
	### Create Your First Mount

		- Commit-Based Caching: Each commit ID has its own cache namespace. This ensures that cached data always corresponds to the correct version of your files.
		- Cache Invalidation on Commit: When you commit changes in write mode using `everest commit`, the mount point's source commit ID is updated to the new HEAD of the branch. As a result, the cache associated with the old commit ID is no longer used, and new data will be cached under the new commit ID.

docs: everest mount page refresh #9601

docs: everest mount page refresh #9601

Uh oh!

Conversation

nopcoder commented Oct 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Oct 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nopcoder commented Oct 26, 2025

Uh oh!

talSofer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yonipeleg33 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nopcoder commented Oct 30, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

nopcoder commented Oct 25, 2025 •

edited

Loading

github-actions bot commented Oct 25, 2025 •

edited

Loading