From 819a8c9d479bc872ae9a30c5bd3aefbd24e24c3b Mon Sep 17 00:00:00 2001 From: Ed McClanahan Date: Tue, 25 Jan 2022 12:01:34 -0800 Subject: [PATCH] Added 2.00.0 Release Notes --- README.md | 58 ++++++++++++++++++++++++++++++++++++++------ release_notes.md | 63 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 114 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 3a79b027..3be85e88 100644 --- a/README.md +++ b/README.md @@ -2,12 +2,13 @@ [![Coverage Status](https://coveralls.io/repos/github/swiftstack/ProxyFS/badge.svg?branch=development)](https://coveralls.io/github/swiftstack/ProxyFS?branch=development) # ProxyFS -Integrated File and Object Access for Swift Object Storage +Provides a POSIX compliant file system mount of an OpenStack Swift Object Storage Container ## Synopsis ProxyFS is a disributed read/write hierarchical POSIX file system layered on top of -[Swift object storage](http://swift.openstack.org). +[Swift object storage](http://swift.openstack.org). File system accesses map to Objects +inside a Swift Container. ## How to Contribute @@ -32,12 +33,55 @@ or the [ProxyFS Slack group](https://proxyfs.slack.com), which you can join thro * git clone git@github.com:NVIDIA/proxyfs.git * cd proxyfs -## How to run unit tests (in your Development Environment) +## Docker-based Development Environment -* [Host shell] docker compose build -* [Host shell] docker compose up -d dev -* [dev shell] make -* [dev shell] make test +ProxyFS develoment/building leverages Docker Containers and Docker Compose. + +A Multi-Stage `Dockerfile` is provided that builds the following three images: + +* `dev` - used to build, debug, and unit test a simple ProxyFS deployment +* `build` - used to provide a clean build environment for constructing `deploy` +* `deploy` - a space/dependency efficient deployable Docker Container holding: + * `ickpt` - an optional, replicable, strictly consistent service to store ProxyFS checkpoints that are, otherwise, the only element of a ProxyFS file system subject to the Eventual Consistency risk of using OpenStack Swift as a storage back-end + * `imgr` - a service capable of managing the metadata for a collection of ProxyFS file systems + * `iclient` - the FUSE service deployed to support the mounting of a ProxyFS file system + +To build the images: + +* docker-compose build + +To instantiate either a development or test environment, a `docker-compose.yml` is provided that instantiates the following Docker Containers: + +* `swift` - a deployment of a Swift "All-in-One" Container instance +* `dev` - an instance of the `dev` image with your ProxyFS repo dir mapped to `/src` +* `ickpt` - an instance of the `deploy` image that launches the `ickpt` service +* `imgr` - an instance of the `deploy` image that launches the `imgr` service +* `iclient` - an instance of the `deploy` image that launches the `iclient` service setup to present its FUSE mount point at `/mnt` + +To kick off development activities: + +* [Host shell] docker-compose up -d dev +* [Host shell] docker-compose exec dev sh +* [`dev` /src#] make +* [`dev` /src#] rm -rf /tmp/ickptDB +* [`dev` /src#] ickpt/ickpt ickpt/dev.conf & +* [`dev` /src#] imgr/imgr imgr/dev.conf & +* [`dev` /src#] imgr/mkmount.sh -fs +* [`dev` /src#] iclient/iclient iclient/dev.conf & + +Note that `imgr` and `iclient` will be logging to $StdOut in this example launching. Each of the above can be terminated by delivering a SIGINT or SIGTERM to their processes. + +For a more appropriate environment in which to perform functional testing, the `docker-compose.yml` file my also be used to launch the suite of Docker Containers: + +* [Host shell] docker-compose up -d iclient +* [Host shell] docker-compose exec iclient sh + +At this point, you have a separate Docker Container running each of the ProxyFS services. Inside the `iclient` Docker Container, the `/mnt` directory will be the FUSE mount point to your ProxyFS file system. + +Both the `imgr` and `iclient` services provide an HTTP endpoint that, due to the port mapping specified in `docker-compose.yml`, should be reachable from a browser in the host: + +* `imgr` - http://localhost:15346/ +* `iclient` - http://localhost:15347/ ## License diff --git a/release_notes.md b/release_notes.md index 50c2ae1d..880c4d07 100644 --- a/release_notes.md +++ b/release_notes.md @@ -1,5 +1,68 @@ # ProxyFS Release Notes +## 2.00.0 (January 25, 2022) + +### Notes: + +This release marks the transition to the re-implementation of ProxyFS. The primary goal +of the new release was to better support distributed FUSE clients of a ProxyFS file system. +Initially, ProxyFS ran on one of an OpenStack Swift's Proxy nodes and was tighly integrated +with the Proxy "ring" such that Object API access to a ProxyFS-managed portion of the namespace +would map to a single ProxyFS service supporting that file system. For network file access, both +NFS (via nfsd) and SMB (via Samba) were integrated. This approach had a number of drawbacks not +the least of which was file system access data paths all traversed a single ProxyFS instance. +Notably, Object API access only routed control path through the ProxyFS instance. Data transfers +via the Object API to ProxyFS file systems still benefitted from the scale-out nature of OpenStack +Swift. + +To better address the scale-out need of the file system data path when accessed via POSIX, a +FUSE client called PFSAgent was constructed as well. This approach nicely moved the POSIX file +system access off of a Swift Proxy node. Alas, PFSAgent still imposed a single data path limitation +for POSIX file system access to a ProxyFS file system. + +In designing the changes required to PFSAgent to support a truly distributed data path, the +complexities of integrating with the existing ProxyFS architecture proved overwhelming. Indeed, +much of the complexity derived from the continued access to the file system provided directly +by the central ProxyFS service that had become redundant. In addition, supporting Object API +access as well presented even more challenge. Finally, even the tighly coupled integration of +ProxyFS with the Proxy "ring" of Swift was less than ideal. + +So a new approach was taken. This presented an opportunity to significantly clean up the "on-disk" +layout of the file system. In addition, improvements to OpenStack Swift to support very large +Containers obsoleted the previous requirement to map a ProxyFS file system on top of an entire +Swift Account. Along the way, a couple of key ProxyFS features were deprecated: + +* Object API Access - what was often termed "Bi-Modal", the ability to read and write to file system +elements depended upon the otherwise undesireable tight integration with each Swift Proxy... so was, for the time being, thought to be expendable + +* SnapShots - similarly, the ability to access a read-only view of the file system at some +scheduled point in the past was a rarely cited feature that, for now, is not supported anymore + +This is a big change to consume all at once. To aid in this, there are a couple of ways to start +looking at the codebase: + +* The leading `i` convention - a quick perusal of the ProxyFS repo will reveal that a large body of code has been removed. Meanwhile, a new set of directories have arrived - each starting with the letter `i`. Also, many subdirectories follow a convention of containing a command line program in the parent directory `iXXX/` with a package implementation subdirectory with the `pkg` suffix (i.e. `iXXX/iXXXpkg/`). These are: + * `iauth` - a simplified "AUTH" plug-in framework for which a Swift Auth-compliant example is provided (in `iauth/iauth-swift/`) + * `icert` - a command-line tool to generate RootCA and signed certificates + * `ickpt` - an optional service to provide a highly available, strictly consistent solution for the CheckPoint record of each file system that is the only Swift entity subject to Eventual Consistency imprecision + * `iclient` - a FUSE client for a ProxyFS file system of which there can be many + * `idestroy` - a simple tool to clean out an OpenStack Swift Container + * `ihtml` - support files for embedded HTTP servers in `iclient` and `imgr` + * `ilayout` - a complete specification of the "on-disk" layout of a ProxyFS file system + * `imgr` - a centralized service that provides a CheckPoint'd management of a ProxyFS file system's Inode Table as well as a Lease Manager enabling the scale-out of `iclient` instances presenting a ProxyFS file system + * `iswift` - a minimal RAM emulation of OpenStack Swift API + +* A move to GoDoc (away from readme's and other forms of often out-of-date documentation) has been provided: + * To launch the GoDoc server: `godoc -goroot ` + * Browse to: http://localhost:6060/pkg/ for things like + * `github.com/NVIDIA/proxyfs/ilayout` - the entire "on-disk" file system layout description + * `github.com/NVIDIA/proxyfs/imgr/imgrpkg` - config and API info for `imgr` + * `github.com/NVIDIA/proxyfs/iclient/iclientpkg` - config and API info for `iclient` + +With such a dramatic departure from the 1.XX line, it should be expected that the current ProxyFS code base is in flux as problems are identified and addressed. In addition, a large body of performance tuning remains outstanding. + +Welcome to 2.XX !!! + ## 1.19.1 (May 13, 2021) ### Bug Fixes: