TrueCloudLab/distribution
13
0
Fork 3
Code Issues 2 Pull requests Projects Releases 2 Packages Wiki Activity Actions

Merge pull request #243 from stevvooe/storagedriver-docs

Browse source 
doc: move storage driver readmes into docs
This commit is contained in:
Stephen Day 2015-03-06 11:25:42 -08:00
commit 48bf33c038
5 changed files with 0 additions and 109 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

49
docs/storage/driver/README.md
View file

@ -1,49 +0,0 @@
Docker-Registry Storage Driver
==============================
This document describes the registry storage driver model, implementation, and explains how to contribute new storage drivers.
Provided Drivers
================
This storage driver package comes bundled with three default drivers.
1. filesystem: A local storage driver configured to use a directory tree in the local filesystem.
2. s3: A driver storing objects in an Amazon Simple Storage Solution (S3) bucket.
3. inmemory: A temporary storage driver using a local inmemory map. This exists solely for reference and testing.
Storage Driver API
==================
The storage driver API is designed to model a filesystem-like key/value storage in a manner abstract enough to support a range of drivers from the local filesystem to Amazon S3 or other distributed object storage systems.
Storage drivers are required to implement the `storagedriver.StorageDriver` interface provided in `storagedriver.go`, which includes methods for reading, writing, and deleting content, as well as listing child objects of a specified prefix key.
Storage drivers are intended (but not required) to be written in go, providing compile-time validation of the `storagedriver.StorageDriver` interface, although an IPC driver wrapper means that it is not required for drivers to be included in the compiled registry. The `storagedriver/ipc` package provides a client/server protocol for running storage drivers provided in external executables as a managed child server process.
Driver Selection and Configuration
==================================
The preferred method of selecting a storage driver is using the `StorageDriverFactory` interface in the `storagedriver/factory` package. These factories provide a common interface for constructing storage drivers with a parameters map. The factory model is based off of the [Register](http://golang.org/pkg/database/sql/#Register) and [Open](http://golang.org/pkg/database/sql/#Open) methods in the builtin [database/sql](http://golang.org/pkg/database/sql) package.
Storage driver factories may be registered by name using the `factory.Register` method, and then later invoked by calling `factory.Create` with a driver name and parameters map. If no driver is registered with the given name, this factory will attempt to find an executable storage driver with the executable name "registry-storage-\<driver name\>" and return an IPC storage driver wrapper managing the driver subprocess. If no such storage driver can be found, `factory.Create` will return an `InvalidStorageDriverError`.
Driver Contribution
===================
## Writing new storage drivers
To create a valid storage driver, one must implement the `storagedriver.StorageDriver` interface and make sure to expose this driver via the factory system and as a distributable IPC server executable.
### In-process drivers
Storage drivers should call `factory.Register` with their driver name in an `init` method, allowing callers of `factory.New` to construct instances of this driver without requiring modification of imports throughout the codebase.
### Out-of-process drivers
As many users will run the registry as a pre-constructed docker container, storage drivers should also be distributable as IPC server executables. Drivers written in go should model the main method provided in `storagedriver/filesystem/registry-storage-filesystem/filesystem.go`. Parameters to IPC drivers will be provided as a JSON-serialized map in the first argument to the process. These parameters should be validated and then a blocking call to `ipc.StorageDriverServer` should be made with a new storage driver.
Out-of-process drivers must also implement the `ipc.IPCStorageDriver` interface, which exposes a `Version` check for the storage driver. This is used to validate storage driver api compatibility at driver load-time.
## Testing
Storage driver test suites are provided in `storagedriver/testsuites/testsuites.go` and may be used for any storage driver written in go. Two methods are provided for registering test suites, `RegisterInProcessSuite` and `RegisterIPCSuite`, which run the same set of tests for the driver imported or managed over IPC respectively.
## Drivers written in other languages
Although storage drivers are strongly recommended to be written in go for consistency, compile-time validation, and support, the IPC framework allows for a level of language-agnosticism. Non-go drivers must implement the storage driver protocol by mimicing StorageDriverServer in `storagedriver/ipc/server.go`. As the IPC framework is a layer on top of [docker/libchan](https://github.com/docker/libchan), this currently limits language support to Java via [ndeloof/chan](https://github.com/ndeloof/jchan) and Javascript via [GraftJS/jschan](https://github.com/GraftJS/jschan), although contributions to the libchan project are welcome.

16
docs/storage/driver/azure/README.md
View file

@ -1,16 +0,0 @@
# Docker Registry Microsoft Azure Blob Storage Driver
An implementation of the `storagedriver.StorageDriver` interface which uses [Microsoft Azure Blob Storage][azure-blob-storage] for object storage.
## Parameters
The following parameters must be used to authenticate and configure the storage driver (case-sensitive):
* `accountname`: Name of the Azure Storage Account.
* `accountkey`: Primary or Secondary Key for the Storage Account.
* `container`: Name of the root storage container in which all registry data will be stored. Must comply the storage container name [requirements][create-container-api].
[azure-blob-storage]: http://azure.microsoft.com/en-us/services/storage/
[create-container-api]: https://msdn.microsoft.com/en-us/library/azure/dd179468.aspx

8
docs/storage/driver/filesystem/README.md
View file

@ -1,8 +0,0 @@
Docker-Registry Filesystem Storage Driver
=========================================
An implementation of the `storagedriver.StorageDriver` interface which uses the local filesystem.
## Parameters
`rootdirectory`: (optional) The root directory tree in which all registry files will be stored. Defaults to `/tmp/registry/storage`.

10
docs/storage/driver/inmemory/README.md
View file

@ -1,10 +0,0 @@
Docker-Registry In-Memory Storage Driver
=========================================
An implementation of the `storagedriver.StorageDriver` interface which uses local memory for object storage.
**IMPORTANT**: This storage driver *does not* persist data across runs, and primarily exists for testing.
## Parameters
None

26
docs/storage/driver/s3/README.md
View file

@ -1,26 +0,0 @@
Docker-Registry S3 Storage Driver
=========================================
An implementation of the `storagedriver.StorageDriver` interface which uses Amazon S3 for object storage.
## Parameters
`accesskey`: Your aws access key.
`secretkey`: Your aws secret key.
**Note** You can provide empty strings for your access and secret keys if you plan on running the driver on an ec2 instance and will handle authentication with the instance's credentials.
`region`: The name of the aws region in which you would like to store objects (for example `us-east-1`). For a list of regions, you can look at http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html
`bucket`: The name of your s3 bucket where you wish to store objects (needs to already be created prior to driver initialization).
`encrypt`: (optional) Whether you would like your data encrypted on the server side (defaults to false if not specified).
`secure`: (optional) Whether you would like to transfer data to the bucket over ssl or not. Defaults to true (meaning transfering over ssl) if not specified. Note that while setting this to false will improve performance, it is not recommended due to security concerns.
`v4auth`: (optional) Whether you would like to use aws signature version 4 with your requests. This defaults to true if not specified (note that the eu-central-1 region does not work with version 2 signatures, so the driver will error out if initialized with this region and v4auth set to false)
`chunksize`: (optional) The default part size for multipart uploads (performed by WriteStream) to s3. The default is 10 MB. Keep in mind that the minimum part size for s3 is 5MB. You might experience better performance for larger chunk sizes depending on the speed of your connection to s3.
`rootdirectory`: (optional) The root directory tree in which all registry files will be stored. Defaults to the empty string (bucket root).