consulfs

package module
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 10, 2018 License: Apache-2.0 Imports: 12 Imported by: 1

README

ConsulFS

ConsulFS implements a FUSE filesystem that is backed by a Consul Key-Value store. Each key in the key store is represented by a file. Read and write the file to get and put the key's value. "/" characters in a key name are used to break up the keys into different directories.

This project should be considered alpha-quality. It works, but it might not handle everything you can throw at it.

Installation

ConsulFS uses FUSE to implement a file system as a user-space process. Most popular Linux distributions will already include a FUSE module, so no further packages need to be installed. OS X systems will need to install a third-party file system package to mount FUSE volumes. FUSE for OS X is the preferred FUSE package at the time of this writing.

There are currently no binary packages available for ConsulFS, so you will need to build the package yourself. ConsulFS is written in Go, so install the Go toolchain available for your system. Look for a "golang" package in your system's package manager (Linux) or in Homebrew (OS X). Binary packages can also be downloaded from golang.org.

Once FUSE and Go are installed, you can download, build, and install ConsulFS by running the following command:

$ go get github.com/bwester/consulfs/cmd/consulfs

That will create the binary $GOPATH/bin/consulfs, which you can call directly or copy to your preferred location for binaries.

Command line usage

The consulfs command is used to mount a Consul Key-Value store onto a file system path. The basic form of the command is:

$ consulfs [options] [consul_address] /mount/path

There aren't many options, but you can run consulfs --help to see them. The address of a Consul agent is optional, and if you omit it, the local agent will be used.

ConsulFS runs in the foreground, where it displays all error messages. If you interrupt the process with ^C or send it a SIGTERM or SIGINT, it will attempt to unmount the file system before exiting. Or, if the mount point is unmounted through other means ("umount" or "fusermount"), the process will exit.

File system model

ConsulFS represents each key in Consul as a file in the file system. The slash character "/" is a key interpreted as a directory separator, and key names are broken up in the straightforward way. Reads and writes on a file will cause GETs and PUTs, respectively, to the key in order to fetch and update the key's value.

Consul doesn't itself store directores; those are simply inferred from the keys. As such, Consul is not updated when creating or removing an empty directory.

For example, the key "foo/bar" is exposed to the file system as the file "bar" in the directory "foo". When "bar" is read, a GET is performed for "foo/bar" and its value will be read. Writes to "bar" first GET "foo/bar", change the written bytes, then save them with a PUT to "foo/bar" containing the entire key's contents. In the directory "foo", if you write to a new file "baz", the key "foo/baz" will be written.

ConsulFS does not currently support durable timestamps, owners, or mode bits--there isn't enough metadata in Consul to store these! The timestamps are faked, and owner/mode bits are fixed: attempts to change them will return an error.

Consistency

ConsulFS doesn't perform any local caching of key values (this was much easier to write!), so every read will always get the latest value. Writes to a file atomically PUT the key's value. This might cause an occasional write() syscall to fail in the presence of concurrent writers. As you might imagine, ConsulFS is currently kinda slow when accessing remote file systems. Future versions may introduce a data cache.

Directory listings are briefly cached, for about 1 second. The access patterns generated by FUSE repeatedly access this kind of metadata, so a small cache is required to get any kind of usable performance.

Documentation

Overview

Package consulfs implements a FUSE filesystem that is backed by a Consul Key-Value store.

API Usage --------- ConsulFS is implemented using the "bazil.org/fuse" package as a file system service. Refer to the fuse package for complete documentation on how to create a new FUSE connection that services a mount point. To have that mount point serve ConsulFS files, create a new instance of `ConsulFS` and pass it to the "bazil.org/fuse/fs".Server.Serve() method. The source code for the mounter at "github.com/bwester/consulfs/cmd/consulfs" gives a full example of how to perform the mounting.

The `ConsulFS` instance contains common configuration data and is referenced by all file and directory inodes. Notably, 'UID' and 'GID' set the uid and gid ownership of all files. The `Consul` option is used to perform all Consul HTTP RPCs. The `CancelConsulKV` struct is included in this package as a wrapper around the standard Consul APIs. It is vital for system stability that the file system not get into an uninteruptable sleep waiting for a remote RPC to complete, so CancelConsulKV will abandon requests when needed.

Index

Constants

View Source 
const MaxWriteAttempts = 10

MaxWriteAttempts sets the number of time a write will be attempted before an error is returned.

Variables

This section is empty.

Functions

This section is empty.

Types

type CancelConsulKV added in v0.1.1 

type CancelConsulKV struct {
	// The Consul client to use for executing operations.
	Client *consul.Client
	// Logger gets all the logging messages
	Logger *logrus.Logger
}

CancelConsulKV is the concrete implementation of ConsulCanceler. It takes a Consul `Client` object and performs all operations using that client.

func (*CancelConsulKV) CAS added in v0.1.1 

func (cckv *CancelConsulKV) CAS(
	ctx context.Context,
	p *consul.KVPair,
	q *consul.WriteOptions,
) (bool, *consul.WriteMeta, error)

CAS performs a compare-and-swap on a key

func (*CancelConsulKV) Delete added in v0.1.1 

func (cckv *CancelConsulKV) Delete(
	ctx context.Context,
	key string,
	w *consul.WriteOptions,
) (*consul.WriteMeta, error)

Delete removes a key and its data.

func (*CancelConsulKV) Get added in v0.1.1 

func (cckv *CancelConsulKV) Get(
	ctx context.Context,
	key string,
	q *consul.QueryOptions,
) (*consul.KVPair, *consul.QueryMeta, error)

Get returns the current value of a key.

func (*CancelConsulKV) Keys added in v0.1.1 

func (cckv *CancelConsulKV) Keys(
	ctx context.Context,
	prefix string,
	separator string,
	q *consul.QueryOptions,
) ([]string, *consul.QueryMeta, error)

Keys lists all keys under a prefix

func (*CancelConsulKV) Put added in v0.1.1 

func (cckv *CancelConsulKV) Put(
	ctx context.Context,
	p *consul.KVPair,
	q *consul.WriteOptions,
) (*consul.WriteMeta, error)

Put writes a key-value pair to the store

type ConsulCanceler 

type ConsulCanceler interface {
	CAS(
		ctx context.Context,
		p *consul.KVPair,
		q *consul.WriteOptions,
	) (bool, *consul.WriteMeta, error)

	Delete(
		ctx context.Context,
		key string,
		w *consul.WriteOptions,
	) (*consul.WriteMeta, error)

	Get(
		ctx context.Context,
		key string,
		q *consul.QueryOptions,
	) (*consul.KVPair, *consul.QueryMeta, error)

	Keys(
		ctx context.Context,
		prefix string,
		separator string,
		q *consul.QueryOptions,
	) ([]string, *consul.QueryMeta, error)

	Put(
		ctx context.Context,
		p *consul.KVPair,
		q *consul.WriteOptions,
	) (*consul.WriteMeta, error)
}

ConsulCanceler defines an API for accessing a Consul Key-Value store. It's mostly a clone of `github.com/hashicorp/consul/api.KV`, but it adds a parameter for a context to method signatures.

Using this interface is deprecated. As of v0.9.0, the official Consul API package allows API calls be canceled using a Context, making this interface unnecessary.

type ConsulFS added in v0.1.1 

type ConsulFS struct {
	// Consul contains a referene to the ConsulCanceler that should be used for all operations.
	Consul ConsulCanceler

	// UID contains the UID that will own all the files in the file system.
	UID uint32

	// GID contains the GID that will own all the files in the file system.
	GID uint32

	// Perms sets the file permission flags for all files and directories. If zero, a
	// default of 0600 will be used.
	Perms os.FileMode

	// RootPath contains the path to the root of the filesystem in Consul. This
	// string will be prefixed to all paths requested from Consul. A path
	// separator will be added if needed.
	RootPath string

	// Messages will be sent to this logger
	Logger *logrus.Logger
}

ConsulFS is the main file system object that represents a Consul Key-Value store.

func (*ConsulFS) Root added in v0.1.1 

func (f *ConsulFS) Root() (fs.Node, error)

Root implements the fs.FS interface. It is called once to get the root directory inode for the mount point.

Source Files

View all Source files

Directories

Path Synopsis
cmd
consulfs
consulfs is a command for mounting Consul-FS to your filesystem.
 consulfs is a command for mounting Consul-FS to your filesystem.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.