Skip to main content
Version: v2.0.5

Dfstore

dfstore is a storage client for dragonfly. It can rely on different types of object storage, such as S3 or OSS, to provide stable object storage capabilities.

Dfstore uses the entire P2P network as a cache when storing objects. Rely on S3 or OSS as the backend to ensure storage reliability. In the process of object storage, P2P Cache is effectively used for fast read and write storage.

Features

  • Provides object storage service.
  • Provides two modes for writing backend including AsyncWriteBack and WriteBack.
  • Backend is third-party object service and supports S3 and OSS.
  • Multiple copies can be replicated within a P2P cluster, and the number of copies is controllable.

Architecture

Put Object

Upload object to dragonfly object storage service.

dfstore-put-object

Put Object With AsyncWriteBack Mode

Dfstore puts object to peer synchronously, to backend asynchronously, and to other peer asynchronously.

dfstore-put-object-async

Put Object With WriteBack Mode

Dfstore puts object to peer synchronously, to backend synchronously, and to other peer asynchronously.

dfstore-put-object-sync

Get Object

Download object from dragonfly object storage service.

dfstore-get-object

Hit Peer Cache

Dfstore download object hits the cache of peer and returns immediately.

dfstore-get-object-hit-peer

Hit Other Peers(include seed peer) Cache

Dfstore download object hits the cache of other peers and download object from other peers. Other peers includes seed peers and peers that have cached object.

dfstore-get-object-hit-other-peer

Hit Backend

Dfstore download object from backend.

dfstore-get-object-hit-backend

Protocol

Dragonfly object storage protocol name is dfs, and the URL is defined as dfs://${bucketName}/${objectKey}.

  • bucketName: The bucket name of the backend third-party object storage service.
  • objectKey: The key of the object storage, that is, the storage path.

For example:

If the Backend is S3 and the upload object is dfs://dragonfly/bar/foo/baz.jpg. Then upload the image /bar/foo/baz.jpg in the S3 dragonfly bucket.

Usage

Step 1: Create the backend object storage service

Create the backend third-party object storage service, bucket and AccessKey and AccessSecretKey. Now backend supports AWS S3 and Aliyun OSS.

How to create an object storage service refer to AWS S3 or Aliyun OSS.

Step 2: Configure the third-party object storage service to the manager

Enable the object storage service in the manager's configuration file.

objectStorage:
# Enable object storage
enable: true
# Object storage name of type, it can be s3 or oss
name: s3
# Storage region
region: 'us-east-2'
# Datacenter endpoint
endpoint: 's3.us-east-2.amazonaws.com'
# Access key ID
accessKey: ''
# Access key secret
secretKey: ''

Step 3: Enable object storage in the peer

Enable the object storage service in the dfdaemon's configuration file.

objectStorage:
# Enable object storage service
enable: true
# Filter is used to generate a unique Task ID by
# filtering unnecessary query params in the URL,
# it is separated by & character.
# When filter: "Expires&Signature&ns", for example:
# http://localhost/xyz?Expires=111&Signature=222&ns=docker.io and http://localhost/xyz?Expires=333&Signature=999&ns=docker.io
# is same task
filter: 'Expires&Signature&ns'
# MaxReplicas is the maximum number of replicas of an object cache in seed peers.
maxReplicas: 3
# Object storage service security option
security:
insecure: true
tlsVerify: true
tcpListen:
# Listen address
listen: 0.0.0.0
# Listen port
port: 65004

Step 4: Install dragofly system

Install dragonfly system with object storage, refer to install dragonfly.

Step 5: Install the dfstore command-line tool

Install the last version of dfstore. You can install one of the version for Dragonfly on the github releases page.

go install d7y.io/dragonfly/v2/cmd/dfstore@latest

dfstore and peer need to be in the same instance, because the 127.0.0.1:65004 endpoint of the peer will be called by default when uploading and downloading. If dfstore and peer are not the same instance, you can specify the endpoint of the peer's object storage through the --endpoint parameter of dfstore command-line tool. Detailed parameters refer to dfstore-cli.

Step 6: Upload object to dragonfly object storage

Upload baz.jpg image to /bar/foo/baz.jpg in S3 dragonfly bucket.

dfstore cp ./baz.jpg dfs://dragonfly/bar/foo/baz.jpg

Step 7: Download object from dragonfly object storage

Download baz.jpg image from /bar/foo/baz.jpg in S3 dragonfly bucket.

dfstore cp dfs://dragonfly/bar/foo/baz.jpg ./baz.jpg

Step 8: Delete object from dragonfly object storage

Delete /bar/foo/baz.jpg image in S3 dragonfly bucket.

dfstore rm dfs://dragonfly/bar/foo/baz.jpg