[GitHub] [hadoop-ozone] xiaoyuyao commented on a change in pull request #1144: HDDS-3803. [OFS] Add User Guide

[GitBox <gi...@apache.org>]

xiaoyuyao commented on a change in pull request #1144:
URL: https://github.com/apache/hadoop-ozone/pull/1144#discussion_r447315619



##########
File path: hadoop-hdds/docs/content/design/ofs.md
##########
@@ -22,12 +22,140 @@ author: Siyao Meng
 
 # Abstract
 
-  Existing scheme: o3fs://bucket.volume/key/../...
+  Scheme: ofs://<Hostname[:Port] or Service ID>/[<volumeName>/<bucketName>/path/to/key]
+
+# The Basics
+
+Examples of valid OFS paths:
+
+```
+ofs://om1/
+ofs://om3:9862/
+ofs://omservice/
+ofs://omservice/volume1/
+ofs://omservice/volume1/bucket1/
+ofs://omservice/volume1/bucket1/dir1
+ofs://omservice/volume1/bucket1/dir1/key1
+
+ofs://omservice/tmp/
+ofs://omservice/tmp/key1
+```
+
+Volumes and mount(s) are located at the root level of an OFS Filesystem.
+Buckets are listed naturally under volumes.
+Keys and directories are under each buckets.
+
+Note that for mounts, only temp mount `/tmp` is supported at the moment.
+
+# Differences from existing o3fs
+
+## Creating files
+
+OFS doesn't allow creating keys(files) directly under root or volumes.
+Users will receive an error message when they try to do that:
+
+```
+$ ozone fs -touch /volume1/key1
+touch: Cannot create file under root or volume.
+```
+
+## Simplify fs.defaultFS
+
+With OFS, fs.defaultFS (in core-site.xml) no longer needs to have a specific
+volume and bucket in its path like o3fs did.
+Simply put the OM host or service ID:
+
+```
+<property>
+<name>fs.defaultFS</name>
+<value>ofs://omservice</value>
+</property>
+```
+
+The client would then be able to access every volume and bucket on the cluster
+without specifying the hostname or service ID.
+
+```
+$ ozone fs -mkdir -p /volume1/bucket1
+```
+
+## Volume and bucket management directly from FileSystem shell
+
+Admins can create and delete volumes and buckets easily with Hadoop FS shell.
+Volumes and buckets are treated similar to directories so they will be created
+if they don't exist with `-p`:
+
+```
+$ ozone fs -mkdir -p ofs://omservice/volume1/bucket1/dir1/
+```
+
+Note that the supported volume and bucket name character set rule still applies.
+For instance, bucket and volume names don't take underscore(`_`):
+
+```
+$ ozone fs -mkdir -p /volume_1
+mkdir: Bucket or Volume name has an unsupported character : _
+```
+
+# Mounts
+
+In order to be compatible with legacy Hadoop applications that use /tmp/,
+we have a special temp mount located at the root of the FS.
+This feature may be expanded in the feature to support custom mount paths.
+
+Important: To use it, first, an **admin** needs to create the volume tmp
+(the volume name is hardcoded for now) and set its ACL to world ALL access.
+Namely:
+
+```
+$ ozone sh volume create tmp

Review comment:
       I think we could add a separate admin command called *provisionTmp* to hide these details. This can be a separate JIRA. 




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: ozone-issues-unsubscribe@hadoop.apache.org
For additional commands, e-mail: ozone-issues-help@hadoop.apache.org