{"id":15127646,"url":"https://github.com/quobyte/docker-volume","last_synced_at":"2025-07-25T21:06:08.105Z","repository":{"id":57547664,"uuid":"50249713","full_name":"quobyte/docker-volume","owner":"quobyte","description":"Docker volume plugin for Quobyte","archived":false,"fork":false,"pushed_at":"2019-05-08T08:59:34.000Z","size":4732,"stargazers_count":22,"open_issues_count":0,"forks_count":6,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-06T15:47:39.829Z","etag":null,"topics":["docker","docker-volumes","software-defined-storage","storage-container"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/quobyte.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-01-23T17:34:39.000Z","updated_at":"2024-10-12T02:14:06.000Z","dependencies_parsed_at":"2022-09-26T18:40:56.331Z","dependency_job_id":null,"html_url":"https://github.com/quobyte/docker-volume","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/quobyte/docker-volume","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quobyte%2Fdocker-volume","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quobyte%2Fdocker-volume/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quobyte%2Fdocker-volume/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quobyte%2Fdocker-volume/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/quobyte","download_url":"https://codeload.github.com/quobyte/docker-volume/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quobyte%2Fdocker-volume/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265508288,"owners_count":23779112,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","docker-volumes","software-defined-storage","storage-container"],"created_at":"2024-09-26T02:05:11.168Z","updated_at":"2025-07-25T21:06:07.842Z","avatar_url":"https://github.com/quobyte.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/quobyte/docker-volume.svg?branch=master)](https://travis-ci.org/quobyte/docker-volume)\n\n# Quobyte volume plug-in for Docker\n\nThis plugin allows you to use [Quobyte](https://www.quobyte.com) with Docker. The plugin is intended to run without installing the Quobyte client on the host system (e.g. for Rancher/CoreOS) but by using a Quobyte client run in a Docker container.\n\n## Tested\n\nOS              | Docker Version\n--------------- | :------------:\nCentOS 7.2      |     1.10.3\nUbuntu 16.04    |     1.11.2\nUbuntu 16.04    |     1.12.0\nCoreOS 1097.0.0 |     1.11.2\n\n## Setup\n\n### Prerequisite: Quobyte client mount\n\nAs described previously a Quobyte multi volume mount has to be available on the host the plugin is intended to run upon. For this setup we recommend running a dockerized Quobyte client. For more information on how to set up a Quobyte Client Docker container look at the example in [docs/coreos.md](docs/coreos.md) or the Quobyte manual (Integration -\u003e Quobyte and Container Infrastructures -\u003e Quobyte Containers - Deep Dive -\u003e Running a Quobyte Client inside a Container).\n\nUsing a locally installed client works fine, too, if this type of installation is preferred.\n\n### Binary\n\nDownload the latest binary and the systemd files from the [releases](https://github.com/quobyte/docker-volume/releases) page. For example, in order to download version `1.3.1` of this plugin run the following step:\n\n```bash\ncurl -LO https://github.com/quobyte/docker-volume/releases/download/v1.3.1/docker-quobyte-plugin.tar.gz\ntar xfz docker-quobyte-plugin.tar.gz\n```\n\n### Create a user in Quobyte for the plug-in:\n\nThis step is optional and should only be used if Quobytes build-in user database is used.\n\n```\n$ qmgmt -u \u003capi-url\u003e user config add docker \u003cemail\u003e\n```\n\n### Systemd Files\n\nInstall systemd files and set your variables in systemd/docker-quobyte.env.sample\n\n```\n$ cp systemd/docker-quobyte.env.sample /etc/quobyte/docker-quobyte.env\n$ cp bin/docker-quobyte-plugin /usr/local/bin/\n$ cp systemd/docker-quobyte-plugin.service /lib/systemd/system\n\n$ systemctl daemon-reload\n$ systemctl start docker-quobyte-plugin\n$ systemctl enable docker-quobyte-plugin\n$ systemctl status docker-quobyte-plugin\n```\n\nAlso ensure that the `\"MountFlags=slave\"` option is not active in the docker systemd unit file, as noted in the Quobyte manual container setup section.\n\n### Configuration\n\nConfiguration is done mainly through the systemd environment file (please note that the QUOBYTE_MOUNT_PATH is required to match the mount point of the Quobyte Clients Docker volume mount point):\n\n```\n# Maximum number of filesystem checks when a Volume is created before returning an error\nMAX_FS_CHECKS=5\n# Maximum wait time for filesystem checks to complete when a Volume is created before returning an error\nMAX_WAIT_TIME=30\n# Group to create the unix socket\nSOCKET_GROUP=root\nQUOBYTE_API_URL=http://localhost:7860\nQUOBYTE_API_PASSWORD=quobyte\nQUOBYTE_API_USER=admin\nQUOBYTE_MOUNT_PATH=/run/docker/quobyte/mnt\nQUOBYTE_MOUNT_OPTIONS=-o user_xattr\nQUOBYTE_REGISTRY=localhost:7861\n# ID of the Quobyte tenant in whose domain volumes are managed by this plugin\nQUOBYTE_TENANT_ID=replace_me\n# Default volume config for new volumes, can be overridden via --opt flag 'configuration_name'\nQUOBYTE_VOLUME_CONFIG_NAME=BASE\n```\n\n### Usage\n\nThe cli allows passing all options.:\n\n```\n$ bin/docker-quobyte-plugin  -h\nUsage of bin/docker-quobyte-plugin:\n  -api string\n        URL to the API server(s) in the form http(s)://host[:port][,host:port] or SRV record name (default \"http://localhost:7860\")\n  -configuration_name string\n        Name of the volume configuration of new volumes (default \"BASE\")\n  -group string\n        Group to create the unix socket (default \"root\")\n  -max-fs-checks int\n        Maximimum number of filesystem checks when a Volume is created before returning an error (default 5)\n  -max-wait-time float\n        Maximimum wait time for filesystem checks to complete when a Volume is created before returning an error (default 64)\n  -options string\n        Fuse options to be used when Quobyte is mounted (default \"-o user_xattr\")\n  -password string\n        Password for the user to connect to the Quobyte API server (default \"quobyte\")\n  -path string\n        Path where Quobyte is mounted on the host (default \"/run/docker/quobyte/mnt\")\n  -registry string\n        URL to the registry server(s) in the form of host[:port][,host:port] or SRV record name (default \"localhost:7861\")\n  -tenant_id string\n        Id of the Quobyte tenant in whose domain the operation takes place (default \"NO-DEFAULT-CHANGE-ME\")\n  -user string\n        User to connect to the Quobyte API server (default \"admin\")\n  -version\n        Shows version string\n```\n __Please note__ that using the environment file for setting the password is strongly encouraged over using the cli parameter.\n\n\nThe following plugin specific options can be injected through the docker client:\n\n```\n  --opt user=\u003cdefault user for the given volume\u003e\n  --opt group=\u003cdefault group for the given volume\u003e\n  --opt configuration_name=\u003cvolume configuration name\u003e\n  --opt tenant_id=\u003ctenant id for the given volume operation\u003e\n```\n\n\n## Examples\n\n### Create a volume\n\n```\n$ docker volume create --driver quobyte --name \u003cvolumename\u003e \n# Set user, group and a non default volume configuration for the new volume\n$ docker volume create --driver quobyte --name \u003cvolumename\u003e --opt user=docker --opt group=docker --opt configuration_name=SSD_ONLY\n```\n\n#### Create a volume with an inital directory path\n\nYou can create a new volume with a specific initial directory path inside by adding the directory path to be initialized to the volume name:\n\n```\n$ docker volume create --driver quobyte --name \u003cvolumename/with/a/path\u003e\n```\n\nThis results in a new volume with name `volumename` containing the directory path `/with/a/path`.\n\n### Delete a volume\n\n__Important__: Be careful when using this. The volume removal allows removing any volume accessible in the configured tenant!\n\n```\n$ docker volume rm \u003cvolumename\u003e\n```\n\n### List all volumes\n\n```\n$ docker volume ls\n```\n\n### Attach volume to container\n\n```\n$ docker run --volume-driver=quobyte -v \u003cvolumename\u003e:/vol busybox sh -c 'echo \"Hello World\" \u003e /vol/hello.txt'\n```\n\n## Development\n\n### Build\n\nGet the code\n\n```\n$ go get -u github.com/quobyte/docker-volume\n```\n\n#### Dependency Management\n\nFor the dependency management we use [golang dep](https://github.com/golang/dep)\n\n#### Linux\n\n```\n$ go build -ldflags \"-s -w\" -o bin/docker-quobyte-plugin .\n```\n\n#### OSX/MacOS\n\n```\n$ GOOS=linux GOARCH=amd64 go build -ldflags \"-s -w\" -o bin/docker-quobyte-plugin .\n```\n\n#### Docker\n\n```\n$ docker run --rm -v \"$GOPATH\":/work -e \"GOPATH=/work\" -w /work/src/github.com/quobyte/docker-volume golang:1.8 go build -v -ldflags \"-s -w\" -o bin/quobyte-docker-plugin\n```\n\n## Troubleshooting\n\nCommon issues or pitfalls.\n\n#### Plugin creates volumes but shows 'no such file or directory' or 'operation not permitted' error\n\n##### Reason\nThe Docker Quobyte plugin can successfully access the backend and create the volume but the new volume is not shown in the plugins mount point.\n\n##### Solution\nIn this case ensure that the Quobyte client mount on the plugins host is working properly. This means ensuring the Quobyte client is running, can contact the registry service and can access the volumes of the tenant used by the Docker Quobyte plugin. If IP based access control is used ensure the host belongs to the IP address range the Quobyte tenant is restricted to.\n\n#### Plugin logs shows \"... invalid character '\u003c' looking for beginning of value\"\n\n##### Reason\nThe API service used by the plugin does not return JsonRPC data.\n\n##### Solution\nCheck the Docker Quobyte plugins API settings. Either the configured API URL/port is wrong, and the plugin connects to the wrong service/port, or the authentication to the API service uses incorrect userid/password values.\n\n#### Updates in a volume take several seconds to show up in another mount of that volume\n\n##### Reason\nThis may be caused by metadata caching.\n\n##### Solution\nDisable metadata caching in the volume configuration of the given volume, e.g. by setting:\n\n```\n  metadata_cache_configuration {\n    cache_ttl_ms: 0\n    negative_cache_ttl_ms: 0\n    enable_write_back_cache: false\n  }\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquobyte%2Fdocker-volume","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquobyte%2Fdocker-volume","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquobyte%2Fdocker-volume/lists"}