{"id":13416294,"url":"https://github.com/blockbridge/blockbridge-docker-volume","last_synced_at":"2025-03-14T23:31:34.834Z","repository":{"id":97290989,"uuid":"40025292","full_name":"blockbridge/blockbridge-docker-volume","owner":"blockbridge","description":"Blockbridge volume plugin for Docker","archived":false,"fork":false,"pushed_at":"2021-06-08T13:50:20.000Z","size":201,"stargazers_count":92,"open_issues_count":0,"forks_count":19,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-07-31T21:56:06.133Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blockbridge.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,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2015-07-31T21:17:53.000Z","updated_at":"2024-07-09T06:16:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"f6307c10-6dce-44a3-b879-7dd017b2c39f","html_url":"https://github.com/blockbridge/blockbridge-docker-volume","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockbridge%2Fblockbridge-docker-volume","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockbridge%2Fblockbridge-docker-volume/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockbridge%2Fblockbridge-docker-volume/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockbridge%2Fblockbridge-docker-volume/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blockbridge","download_url":"https://codeload.github.com/blockbridge/blockbridge-docker-volume/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243663514,"owners_count":20327300,"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":[],"created_at":"2024-07-30T21:00:56.566Z","updated_at":"2025-03-14T23:31:29.826Z","avatar_url":"https://github.com/blockbridge.png","language":"Ruby","readme":"# Blockbridge Volume Plugin for Docker\n\nVersion 3.1\n\nThe Blockbridge volume plugin is available as a \"Managed Docker Plugin\" for\nDocker 1.13+ and as a \"Legacy Plugin\" for Docker 1.12 and earlier. Both options\nrun as a container. The Managed plugin is preferred, as installation and\nlifecycle management of the plugin is taken care of by Docker natively. The\nBlockbridge Managed Volume Plugin is available both on the Docker Hub and the\nDocker Store as a Docker Certified Plugin.\n\n*Why use a Blockbridge storage backend?*  Blockbridge enables tenant isolation,\nautomated provisioning, encryption, secure deletion, snapshots and QoS for any\nstorage backend: on local storage or with any storage vendor over any protocol.\n\nThe Blockbridge volume plugin is a full-featured volume plugin for Docker,\nenabling multi-host access to block storage data volumes. Many functions are\navailable through the native Docker API and command line tools. More advanced\nfunctionality is accessible via the API exposed by the Blockbridge Volume\nDriver and accompanying command lines tools.\n\nThe table below presents the base feature list along with interface support guidelines.\n\n| Blockbridge Feature      | Via Docker API | Via Blockbridge API |\n| ------------------------ | :------------: | :-----------------: |\n| Create Volume            | Yes            | Yes |\n| Inspect Volume           | Yes            | Yes |\n| List Volumes             | Yes            | Yes |\n| Remove Volume            | Yes            | Yes |\n| Secure Transport Volumes | Yes            | Yes |\n| Authenticated Volumes    | Yes            | Yes |\n| Encrypted Volumes        | Yes            | Yes |\n| QoS Volumes              | Yes            | Yes |\n| Create Volume Profile    | –              | Yes |\n| Inspect Volume Profile   | –              | Yes |\n| List Volume Profiles     | –              | Yes |\n| Remove Volume Profiles   | –              | Yes |\n| Volume Backup            | –              | Yes |\n| Volume Restore           | Yes            | Yes |\n| Inspect Backup           | –              | Yes |\n| List Backups             | –              | Yes |\n| Remove Backup            | –              | Yes |\n\n## Quick Start\n\n````\n$ docker plugin install --alias blockbridge blockbridge/volume-plugin BLOCKBRIDGE_API_HOST=\"YOUR HOST\" \\\n    BLOCKBRIDGE_API_KEY=\"YOUR KEY\"\n````\n\nThe plugin requires two environment variables to be set: `BLOCKBRIDGE_API_HOST` to point to the Blockbridge backend, and `BLOCKBRIDGE_API_KEY` as the access token to be used. For a quick-start, use the Blockbridge Storage Container as your backend. Please see [https://github.com/blockbridge/blockbridge-simulator](https://github.com/blockbridge/blockbridge-simulator) for the Blockbridge container quick-start setup.\n\n## Table of Contents \n- [Blockbridge Volume Plugin for Docker](#blockbridge-volume-plugin-for-docker)\n    - [Quick Start](#quick-start)\n    - [Table of Contents](#table-of-contents)\n    - [Configuration](#configuration)\n    - [Volumectl](#volumectl)\n    - [Volume Create](#volume-create)\n        - [Volume Options](#volume-options)\n            - [Profile](#profile)\n            - [User](#user)\n            - [Capacity](#capacity)\n            - [Type](#type)\n            - [IOPS](#iops)\n            - [Transport](#transport)\n            - [From Backup](#from-backup)\n            - [OTP](#otp)\n            - [Attribute based provisioning](#attribute-based-provisioning)\n    - [Volume Create Examples](#volume-create-examples)\n    - [Create a volume in Docker (in-band)](#create-a-volume-in-docker-in-band)\n        - [Docker volume create (Explicit)](#docker-volume-create-explicit)\n        - [Docker volume create (Implicit)](#docker-volume-create-implicit)\n        - [Docker run with volume](#docker-run-with-volume)\n        - [List volumes with docker](#list-volumes-with-docker)\n        - [Inspect volume with docker](#inspect-volume-with-docker)\n    - [Volume Profiles](#volume-profiles)\n        - [Default profile](#default-profile)\n        - [Volume Profiles Provisioning Attributes](#volume-profiles-provisioning-attributes)\n            - [(Example) Gold Storage Profile](#example-gold-storage-profile)\n            - [(Example) Availability Zone East Profile](#example-availability-zone-east-profile)\n            - [(Example) Rack42 Profile](#example-rack42-profile)\n        - [List Profiles](#list-profiles)\n        - [Inspect one Profile](#inspect-one-profile)\n        - [Full command help](#full-command-help)\n    - [Volume Backups](#volume-backups)\n        - [Volume backup](#volume-backup)\n        - [Volume restore](#volume-restore)\n        - [List backups](#list-backups)\n        - [Inspect backup](#inspect-backup)\n        - [Remove backup](#remove-backup)\n    - [Blockbridge Storage Simulator](#blockbridge-storage-simulator)\n        - [Legacy Quick Start](#legacy-quick-start)\n        - [Additional Configuration required?](#additional-configuration-required)\n    - [What is Blockbridge?](#what-is-blockbridge)\n    - [Support](#support)\n\n## Configuration\n\n## Volumectl\n\nFor full management of the Blockbridge Volume Plugin, use the Blockbridge `volumectl` command, available as a container.\n\nIt it recommended to set a shell alias:\n\n`$ alias volumectl='docker run --rm -v /run/docker/plugins:/run/docker/plugins blockbridge/volumectl'`\n\n````\n$ volumectl\n\nUsage:\n    volumectl [OPTIONS] SUBCOMMAND [ARG] ...\n\nParameters:\n    SUBCOMMAND                    subcommand\n    [ARG] ...                     subcommand arguments\n\nSubcommands:\n    volume                        manage volumes\n    profile                       manage volume profiles\n    backup                        manage volume backups\n    version                       volumectl version\n\nGlobal options (8 hidden):\n    -h, --help                    print help (use --verbose to show hidden options)\n    --verbose                     enable verbose output\n    --debug                       enable additional debug\n    --raw, -R                     enable raw output\n    --yaml                        print yaml for raw output\n````\n\n## Volume Create\n\nCreate a volume by specifying the driver as `blockbridge` (or the alias you\nspecified when the plugin was installed). The Blockbridge volume driver\nsupports multiple volume options and provisioning attributes to be specified.\n\n````\n$ volumectl volume create --name testvol\n== Volume: testvol\nuser                  default\ncapacity              1GiB   \n````\n\n### Volume Options\n\nThe volume is provisioned according to the options specified.  As Blockbridge\nis multi-tenant storage, a **User** is always required. The Blockbridge Storage\nContainer creates a `default` user for ease-of-use with the plugin.\n\n#### Profile\n\nThe storage profile to use for the volume. A storage profile contains volume\ncreate options that make specifying the options easier as a group. See below\nfor full description. The Blockbridge Storage Container creates a `default`\nprofile.\n\nIf a default profile exists, this parameter is Optional.\n\nParameter name: **profile**\n\n#### User\n\nRequired. The user (tenant) to provision the volume for.\n\nParameter name: **user**\n\n#### Capacity\n\nRequired. The volume capacity.\n\nParameter name: **capacity**\n\n#### Type\n\nOptional. The volume type. This is defined by the backend and determines\ncertain volume characteristics, such as IOPS rating, performance, etc.\n\nParameter name: **type**\n\n#### IOPS\n\nOptional. Depends on `type` specified. The volume quality of service (QoS).\nThis is a reserved, guaranteed minimum IOPS performance of the volume. It\nrequires QoS configuration on the backend.\n\nParameter name: **iops**\n\n#### Transport\n\nOptional. Blockbridge volumes support transport security. Specify `tls` to\naccess your volumes over the network with TLS.\n\nParameter name: **transport**\n\n#### From Backup\n\nOptional. The volume source to restore from. On volume create, restore from the\nspecified backup.\n\nParameter name: **from_backup**\n\n#### OTP\n\nOptional. If the volume is configured for authentication, specify the\none-time-password (OTP) in order to access the volume.\n\nParameter name: **otp**\n\n#### Attribute based provisioning\n\nIn addition to the required volume options, volume provisioning attributes can\nbe specified to determine particular qualities of the storage to provision\nfrom.\n\nThese attributes are configured by an administrator on the Blockbridge storage\nbackend, and then specified by the volume driver as query parameters.\n\nAttributes such as SSD, IOPS 30000, Rack 42, New York, Chicago, Production, all\nidentify unique sets of storage pools.\n\nSpecifying provisioning attributes provides an automated and fundamental way to\ndescribe the exact storage characteristics you want to provision for your\nvolume.\n\nParameter name: **attributes**\n\n## Volume Create Examples\n\n````\n$ volumectl volume create --name vol1 --user default --capacity 32GiB --type gp\n== Volume: vol1\ntype                  gp     \nuser                  default\ncapacity              32GiB  \n````\n\n````\n$ volumectl volume create --name vol2 --user default --capacity 32GiB --type provisioned --iops 10000\n== Volume: vol2\ntype                  piops  \nuser                  default\ncapacity              100GiB \niops                  10000\n````\n\n````\n$ volumectl volume create --name vol3 --user default --capacity 1TiB --type piops --iops 20000\n== Volume: vol3\ntype                  piops  \nuser                  default\ncapacity              1TiB   \niops                  20000\n````\n\n## Create a volume in Docker (in-band)\n\nThere are two ways in Docker to create a volume, either explicitly via *docker\nvolume create* or implicitly at *docker run* time.\n\n### Docker volume create (Explicit)\n\nCreate a blockbridge volume:\n````\n$ docker volume create --driver blockbridge --name datavol --opt user=block --opt capacity=32GiB\n````\n\n### Docker volume create (Implicit)\n\nOnce a default profile has been configured (see below), create a blockbridge volume:\n````\n$ docker run --volume-driver blockbridge -v datavol:/data -it busybox sh\n````\n\nNOTE: you cannot pass volume options on the commandline during *docker run*,\nthese can only be specified explicitly with *docker volume create --opt*, or a\nBlockbridge default volume profile must be setup. If doing an implicit volume\ncreate, a default profile must be setup\n\n### Docker run with volume\n\nReference existing Blockbridge volume at docker run:\n````\n$ docker run -v datavol:/data -it busybox sh\n````\n\n### List volumes with docker\n````\n$ docker volume ls\n````\n\n### Inspect volume with docker\n````\n$ docker volume inspect datavol\n````\n\n## Volume Profiles\n\nBlockbridge volume profiles are a way to describe different sets of volume\noptions and provisioning attributes as a **Storage Profile** or **Storage\nTemplate**.  Instead of specifying each individual option every time a volume is\ncreated, a volume profile can be referenced.\n\nCreate a profile with the volume driver:\n````\n$ volumectl profile create --name profile-test --user default --capacity 32GiB\n== Profile: profile-test\nuser                  default \ncapacity              32GiB   \ntransport             insecure\n\n````\n\nReference the profile to create a volume. Each volume that uses this\n**profiletest** will be created for the **default** user with a capacity of\n**32GiB**.\n````\n$ docker volume create --driver blockbridge --name datavol2 --opt profile=profile-test\n````\n\n### Default profile\n\nBy naming a profile `default`, it will be used if no other profile is\nspecified. NOTE: the Blockbridge Storage Container already creates a `default`\nprofile.\n\nCreate a default profile:\n````\n$ volumectl profile create --name default --user default --capacity 32GiB --type gp2\n````\n\n### Volume Profiles Provisioning Attributes\n\nThe power of volume profiles comes from defining sets of options and defining\nstorage provisioning attributes. For example, you may have different classes of\nstorage, Gold and Silver. You may have storage in different availability zones,\ndifferent racks in a datacenter, different storage media (ssd, spinners), and\nfor different users.\n\nDefine profiles that make sense for your environment.\n\n#### (Example) Gold Storage Profile\n````\n$ volumectl profile create --name gold --user default --type provisioned-iops --iops 10000 --capacity 1TiB +ssd +production +multipath +high-iops\n````\n\n#### (Example) Availability Zone East Profile\n````\n$ volumectl profile create --name us-east --user default --capacity 10GiB +us-east +ssd -production\n````\n\n#### (Example) Rack42 Profile\n````\n$ volumectl profile create profile create --name rack42 --user block --capacity 16GiB +rack42\n````\n\n### List Profiles\n````\n$ volumectl profile ls\n````\n\n### Inspect one Profile\n````\n$ volumectl profile inspect rack42\n````\n\n### Full command help\n````\n$ volumectl profile --help\n````\n\nBlockbridge volumes are accessible on any host, with no data copy required.\n\n## Volume Backups\n\nBackup any volume directly to any S3-compatible object store. Your filesystem\nis frozen, a snapshot is taken, and your block device is converted to objects.\nAll operations take place on the Blockbridge backend, so your backup is taken\ndirectly from your data. No host dependencies are required, and if your host\ncrashes during your backup, the backup still takes place successfully.  Backups\nare managed directly via the Blockbridge volume driver. Specify a volume\nprofile to manage backups for, or with none specified the default is used.\n\n### Volume backup\n\nBackup a volume with the volume driver\n\n````\n$ volumectl backup testvol\n````\n\n### Volume restore\n\nRestore a volume that was backed up. Use standard volume create options with a backup source specified.\n\n````\n$ volumectl volume create --name testvol-restore --from-backup testvol-backup\n````\n\n### List backups\nList backups for default profile.\n````\n$ volumectl backup ls\n````\n\nList backups for specified profile.\n````\n$ volumectl backup ls --profile profile-test\n````\n\n### Inspect backup\n````\n$ volumectl backup inspect datavol-backup\n````\n\n### Remove backup\n````\n$ volumectl backup rm datavol-backup\n````\n\n## Blockbridge Storage Simulator\n\nThe Blockbridge storage backend is available as a simulator running as a Docker\ncontainer.\n\n* [blockbridge-simulator](https://github.com/blockbridge/blockbridge-simulator)\n\n### Legacy Quick Start\nFor Docker version 1.12 or earlier, the Blockbridge Volume Driver is available\nas a legacy plugin. A compose file is available to start the driver (as a\ncontainer).  For most cases, using the Docker compose file will start the\nvolume driver, and connect to the Blockbridge simulator.\n\n````\ndocker-compose up\n````\n\n### Additional Configuration required?\n\nFor running against Blockbridge storage (not the simulator), or for more\ncomplicated setups, additional configuration may be required.  A startup script\nis provided for these cases. \n\nTwo environment variables are required in order to use the startup script:\n````\nBLOCKBRIDGE_API_HOST\nBLOCKBRIDGE_API_KEY\n````\n\nSet these environment variables to point to the Blockbridge backend\nstorage, and to authenticate with the management API.  The Blockbridge\nsimulator, or any other Blockbridge storage can be configured for use\nwith the volume driver.\n\n## What is Blockbridge?\n\nBlockbridge is Elastic Block Storage for everyone. Run Blockbridge on\nbare-metal, on a VM, or in a container, in any cloud, on any provider. Access\nyour data directly from any Linux or Windows host as a standard block device,\nor use it as a Docker volume through the volume plugin in a swarm. Manage your\nstorage via Web UI, cross-platform command-line tools, or REST API. See\n[https://blockbridge.com](https://blockbridge.com) for more information and to\ndownload fully functional trial software, or contact us at info@blockbridge.com\nwith any questions. We’d love to hear from you!\n\n## Support\n\nPlease let us know what you think! Contact us at support@blockbridge.com or on\ngithub.\n","funding_links":[],"categories":["Container Operations","Volume management and plugins"],"sub_categories":["Volume Management / Data"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblockbridge%2Fblockbridge-docker-volume","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblockbridge%2Fblockbridge-docker-volume","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblockbridge%2Fblockbridge-docker-volume/lists"}