diff --git a/docs/blog/2016-10-28.md b/docs/blog/2016-10-28.md index 20a51808c..5a639f357 100644 --- a/docs/blog/2016-10-28.md +++ b/docs/blog/2016-10-28.md @@ -1,8 +1,14 @@ -# 0.8 Release +# 0.8.1 Release -October release is [out](https://github.com/vmware/docker-volume-vsphere/releases) +October release is [out and updated to 0.8.1](https://github.com/vmware/docker-volume-vsphere/releases) This is a big release, it includes multi tenancy additions and the backend VMDK_OPS service is now multi-threaded. +## Tenancy +- [Feature + Overview](https://vmware.github.io/docker-volume-vsphere/features/tenancy) +- [Tenancy + CLI](https://vmware.github.io/docker-volume-vsphere/user-guide/admin-cli/) + # Containers and persistent storage meetup. Docker volume plugin was presented at the [first meetup](https://www.meetup.com/Containers-and-persistent-storage/events/232635184/) of the (Containers and persistent storage meetup group](https://www.meetup.com/Containers-and-persistent-storage/) diff --git a/docs/features/tenancy.md b/docs/features/tenancy.md new file mode 100644 index 000000000..f4d4ca6d8 --- /dev/null +++ b/docs/features/tenancy.md @@ -0,0 +1,13 @@ +# Tenancy + +Multi-tenancy is implemented via assigning VMs and Datastore to a tenant. A tenant can be granted access to create, delete or mount volumes on a specific datastore. VMs assigned to a tenant can then execute Docker volume APIs on an assigned datastores. Within a datastore multiple tenants can store their Docker volumes. A tenant cannot access volumes created by a different tenant, i.e. tenants have their own independent namespace even if tenants share datastores. VMs cannot be shared between tenants. + +## Admin CLI + +Tenants can be created and managed via the [Admin +CLI](/user-guide/admin-cli/#tenant) + +## References + +- [Design Spec for tenancy](https://github.com/vmware/docker-volume-vsphere/blob/master/docs/misc/docker-volume-auth-proposal.v1_2.md) +- [Introduction to vSphere Storage](https://pubs.vmware.com/vsphere-60/index.jsp#com.vmware.vsphere.storage.doc/GUID-F602EB17-8D24-400A-9B05-196CEA66464F.html) diff --git a/docs/index.md b/docs/index.md index bfb36d99a..8ff2b0ffe 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,6 +14,8 @@ zero credential management. 5. Backup of Docker volumes (under development) This plugin is integrated with [Docker Volume Plugin framework](https://docs.docker.com/engine/extend/plugins_volume/). This plugin does not need credential management or configuration management. + + # Feedback diff --git a/docs/user-guide/admin-cli.md b/docs/user-guide/admin-cli.md index 8eb31721e..7501bfd94 100644 --- a/docs/user-guide/admin-cli.md +++ b/docs/user-guide/admin-cli.md @@ -1,6 +1,7 @@ [TOC] # Introduction + In the context of the Docker volume plugin for vSphere, each ESXi host manages multiple VMs, with each of them acting as a Docker host. The Docker engine on these hosts communicates with the Docker volume plugin in order to create and delete virtual disks (VMDKs), as well as mount them as Docker @@ -9,14 +10,342 @@ by the Docker user via the Docker CLI. However, the Docker CLI is limited in wha provide to the user. Furthermore, it is desirable that an administrator be able to get a global view of all virtual disks created and in use on the host. For these reasons, an admin CLI has been created that runs on the ESXi host and that provides access to information not visible from the -Docker CLI. The remainder of this document will describe each admin CLI command and provide examples -of their usage. +Docker CLI. + +The admin cli also enables ESX admins to implement tenancy. +The remainder of this document will describe each admin CLI command and provide examples +of their usage. -# ls +## Tenant ### Help + +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant -h +usage: vmdkops_admin.py tenant [-h] {access,rm,create,ls,vm} ... + +positional arguments: + {access,rm,create,ls,vm} + access Add or remove Datastore access and quotas for a tenant + rm Delete a tenant + create Create a new tenant + ls List tenants and the VMs they are applied to + vm Add, removes and lists VMs in a tenant + +optional arguments: + -h, --help show this help message and exit +``` + +### Access + +Change the access control for a tenant. +This includes ability to control which datastores are accessible by a tenant and controlling what a +tenant can do on a given datastore. + +#### Help +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant access -h +usage: vmdkops_admin.py tenant access [-h] {rm,add,set,ls} ... + +positional arguments: + {rm,add,set,ls} + rm Remove all access to a datastore for a tenant + add Add a datastore access for a tenant + set Modify datastore access for a tenant + ls List all access info for a tenant + +optional arguments: + -h, --help show this help message and exit +``` +#### Add + +Add a datastore to be access by a tenant. + +Sample: + +```bash +/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant access add --name tenant1 --datastore datastore1 --rights create,delete,mount +{'mount_volume': 1, 'global_visibility': 0, 'max_volume_size': 0, 'create_volume': 1, 'delete_volume': 1, 'datastore': 'datastore1', 'usage_quota': 0} +tenant access add succeeded +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant access ls --name tenant1 +Datastore Create_volume Delete_volume Mount_volume Max_volume_size Total_size +---------- ------------- ------------- ------------ --------------- ---------- +datastore1 1 1 1 0B 0B +``` + +By default no rights are given + +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant access add --name tenant1 --datastore datastore1 +{'mount_volume': 0, 'global_visibility': 0, 'max_volume_size': 0, 'create_volume': 0, 'delete_volume': 0, 'datastore': 'datastore1', 'usage_quota': 0} +tenant access add succeeded +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant access ls --name tenant1 +Datastore Create_volume Delete_volume Mount_volume Max_volume_size Total_size +---------- ------------- ------------- ------------ --------------- ---------- +datastore1 0 0 0 0B 0B +``` + +- For capability 0 indicates false +- For capacity 0 indicates no limits + +##### Help + +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant access add -h +usage: vmdkops_admin.py tenant access add [-h] + [--volume-totalsize Num{MB,GB,TB} - e.g. 2TB] + --name NAME + [--volume-maxsize Num{MB,GB,TB} - e.g. 2TB] + --datastore DATASTORE + [--rights create,delete,mount] + +optional arguments: + -h, --help show this help message and exit + --volume-totalsize Num{MB,GB,TB} - e.g. 2TB + Maximum total size of all volume that can be created + on the datastore for this tenant + --name NAME The name of the tenant + --volume-maxsize Num{MB,GB,TB} - e.g. 2TB + Maximum size of the volume that can be created + --datastore DATASTORE + Datastore which access is controlled + --rights create,delete,mount + Datastore access Permissions granted: Choices = + ['create', 'delete', 'mount', 'all'] +``` + +#### List + +List the current access control granted to a tenant. + +When displaying the result keep in mind: + +- For capability 0 indicates false +- For capacity 0 indicates no limits + +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant access ls --name tenant1 +Datastore Create_volume Delete_volume Mount_volume Max_volume_size Total_size +---------- ------------- ------------- ------------ --------------- ---------- +datastore1 1 1 1 0B 0B +``` + +##### Help +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant access ls -h +usage: vmdkops_admin.py tenant access ls [-h] --name NAME + +optional arguments: + -h, --help show this help message and exit + --name NAME The name of the tenant +``` +#### Remove +Remove access to a datastore for a tenant. +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant access rm --name tenant1 --datastore datastore1 +tenant access rm succeeded +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant access ls --name tenant1 +Datastore Create_volume Delete_volume Mount_volume Max_volume_size Total_size +--------- ------------- ------------- ------------ --------------- ---------- +``` +##### Help +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant access rm -h +usage: vmdkops_admin.py tenant access rm [-h] --name NAME --datastore + DATASTORE + +optional arguments: + -h, --help show this help message and exit + --name NAME The name of the tenant + --datastore DATASTORE + Datstore which access is controlled +``` +#### Set + +Set command allows to change the existing access control in place for a tenant. + +Sample: + +```shell +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant access ls --name tenant1 +Datastore Create_volume Delete_volume Mount_volume Max_volume_size Total_size +---------- ------------- ------------- ------------ --------------- ---------- +datastore1 0 0 0 0B 0B +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant access set --volume-totalsize 2TB --volume-maxsize 500GB --volume-maxcount 100 --add-rights all --name tenant1 --datastore datastore1 +tenant access set succeeded +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant access ls --name tenant1 +Datastore Create_volume Delete_volume Mount_volume Max_volume_size Total_size +---------- ------------- ------------- ------------ --------------- ---------- +datastore1 1 1 1 500.00GB 2.00TB +``` + +##### Help +``` +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant access set -h +usage: vmdkops_admin.py tenant access set [-h] + [--volume-totalsize Num{MB,GB,TB} - e.g. 2TB] + [--volume-maxsize Num{MB,GB,TB} - e.g. 2TB] + [--volume-maxcount VOLUME_MAXCOUNT] + [--rm-rights create,delete,mount,all] + [--add-rights create,delete,mount,all] + --name NAME --datastore DATASTORE + +optional arguments: + -h, --help show this help message and exit + --volume-totalsize Num{MB,GB,TB} - e.g. 2TB + Maximum total size of all volume that can be created + on the datastore for this tenant + --volume-maxsize Num{MB,GB,TB} - e.g. 2TB + Maximum size of the volume that can be created + --volume-maxcount VOLUME_MAXCOUNT + Maximum number of volumes to create on the datastore + for this tenant + --rm-rights create,delete,mount,all + Datastore access Permissions removed: Choices = + ['create', 'delete', 'mount', 'all'] + --add-rights create,delete,mount,all + Datastore access Permissions granted: Choices = + ['create', 'delete', 'mount', 'all'] + --name NAME Tenant name + --datastore DATASTORE + Datastore name +``` +### Create + +Create a tenant that can be assigned VMs. Only the VMs assigned to the tenant will be able to +access the datastores assigned to the tenant. + +Sample: +``` +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant create --name DevAppX +tenant create succeeded +``` + +The tenant to VM association can be done at create time. + +Sample: +``` +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant ls +Uuid Name Description Default_datastore VM_list +------------------------------------ ------- ----------- ----------------- --------------------------- +dc17b3b1-1f4d-4f8b-a6f4-3dba064ba88f tenant1 default_ds photon.vsan.1,photon.vsan.2 + +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant create --name DevAppX --vm-list ubuntu +tenant create succeeded +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant ls +Uuid Name Description Default_datastore VM_list +------------------------------------ ------- ----------- ----------------- --------------------------- +dc17b3b1-1f4d-4f8b-a6f4-3dba064ba88f tenant1 default_ds photon.vsan.1,photon.vsan.2 +5afa4767-ecd8-489e-9d97-5c46ae50d3fc DevAppX default_ds ubuntu + +[root@localhost:~] + +``` + +#### Help +``` +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant create -h +usage: vmdkops_admin.py tenant create [-h] --name NAME + [--vm-list vm1, vm2, ...] + +optional arguments: + -h, --help show this help message and exit + --name NAME The name of the tenant + --vm-list vm1, vm2, ... + A list of VM names to place in this Tenant +``` + +### Remove + +Remove a tenant, optionally all volumes for a tenant can be removed as well. + +Sample: +``` +/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant rm tenant1 --remove-volumes True +``` + +#### Help +``` +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant rm -h +usage: vmdkops_admin.py tenant rm [-h] [--remove-volumes REMOVE_VOLUMES] name + +positional arguments: + name The name of the tenant + +optional arguments: + -h, --help show this help message and exit + --remove-volumes REMOVE_VOLUMES + BE CAREFUL: Removes this tenant volumes when removing + a tenant ``` +### List + +List existing tenants, the datastores tenants have access to and the VMs assigned. +``` +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant ls +Uuid Name Description Default_datastore VM_list +------------------------------------ ------- ----------- ----------------- --------------------------- +dc17b3b1-1f4d-4f8b-a6f4-3dba064ba88f tenant1 default_ds photon.vsan.1,photon.vsan.2 +5afa4767-ecd8-489e-9d97-5c46ae50d3fc DevAppX default_ds ubuntu +``` +#### Help +``` +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant ls +Uuid Name Description Default_datastore VM_list +------------------------------------ ------- ----------- ----------------- --------------------------- +dc17b3b1-1f4d-4f8b-a6f4-3dba064ba88f tenant1 default_ds photon.vsan.1,photon.vsan.2 +5afa4767-ecd8-489e-9d97-5c46ae50d3fc DevAppX default_ds ubuntu + +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant ls -h +usage: vmdkops_admin.py tenant ls [-h] + +optional arguments: + -h, --help show this help message and exit +``` + +### Virtual Machine +#### Add +Add a VM to a tenant. A VM can only access the datastores for the tenant it is assigned to. +VMs can be assigned to only one tenant at a time. +#### List +``` +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant vm ls --name tenant1 +Uuid Name +------------------------------------ ------------- +564d6f23-eabb-1b63-c79d-2086cca704d5 photon.vsan.2 + +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant vm add --name tenant1 --vm-list photon.vsan.1 +tenant vm add succeeded +``` +#### Remove +Remove a VM from a tenant's list of VMs. VM will no longer be able to access the volumes created for the tenant. +``` +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant vm rm --name tenant1 --vm-list photon.vsan.1 +tenant vm rm succeeded +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant vm ls --name tenant1 +Uuid Name +------------------------------------ ------------- +564d6f23-eabb-1b63-c79d-2086cca704d5 photon.vsan.2 +``` +#### Help +``` +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant vm -h +usage: vmdkops_admin.py tenant vm [-h] {rm,add,ls} ... + +positional arguments: + {rm,add,ls} + rm Remove VM(s) from a tenant + add Add a VM(s) to a tenant + ls list VMs in a tenant + +optional arguments: + -h, --help show this help message and exit +``` +## Volume +### List +#### Help +```bash [root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py ls -h usage: vmdkops_admin.py ls [-h] [-c Col1,Col2,...] @@ -27,11 +356,11 @@ optional arguments: 'policy', 'capacity', 'used'] ``` -### List All +#### List All List all properties for all Docker volumes that exist on datastores accessible to the host. -``` +```bash [root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py ls Volume Datastore Created By VM Created Attached To VM Policy Capacity Used --------- ---------- ------------- ------------------------ -------------- ------ -------- ------- @@ -43,11 +372,11 @@ Note that the `Policy` column shows the named VSAN storage policy created with t (vmdkops_admin.py). Since these example virtual disks live on a VMFS datastore they do not have a storage policy and show up as `N/A'. -### List selected columns +#### List selected columns Show only the selected columns. -``` +```bash [root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py ls -c volume,datastore,attached-to Volume Datastore Attached To VM --------- ---------- -------------- @@ -58,12 +387,39 @@ vol datastore1 detached Note that the that the choices are given in a comma separated list with no spaces, and are shown in the help given above with `vmdkops_admin ls -h`. -# policy +### Set +Modify attribute settings on a given volume. The volume is identified by its name and datastore, +for example if the volume name is `container-vol` then the volume is specified as "container-vol@datastore-name". +The attributes to set/modify are specified as a comma separated list as "=, =....". For example, +a command line would look like this. + +```bash +$ vmdkops-admin set --volume= --options="=, =, ..." +``` + +The volume attributes are set and take effect only the next time the volume attached to a VM. The changes do not impact any VM +thats currently using the volume. For the present, only the "access" attribute is supported to be modified via this command, and +can be set to either of the allowed values "read-only" or "read-write". + +Set command allows the admin to enforce a volume to be read-only. +This removes the need to depend on [Docker's run command options for volume access](https://docs.docker.com/engine/tutorials/dockervolumes/) (``` docker run -v /vol:/vol:ro```). + +A sample use case: + +1. Create a volume, attach to a container (default is read-write). +2. Master the volume with libraries commonly used by the target application (or a cluster of apps that form a docker app bundle). +3. Use admin CLI to flip the access attribute to read-only. +4. Make those libraries available to the containers in the app bundle and they can all share the same libraries. + +The container images themselves can be smaller as they share the libs and possibly binaries from read-only volumes. + + +## Policy Create, configure and show the VSAN policy names and their corresponding VSAN policy strings. Also show whether or not they are in use. -### Help -``` +#### Help +```bash [root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py policy -h usage: vmdkops_admin.py policy [-h] {rm,create,ls,update} ... @@ -79,11 +435,11 @@ optional arguments: -h, --help show this help message and exit ``` -### Create +#### Create Create a VSAN storage policy. -``` +```bash [root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py policy create --name some-policy --content '(("proportionalCapacity" i0)("hostFailuresToTolerate" i0)' Successfully created policy: some-policy ``` @@ -92,11 +448,11 @@ Note that the VSAN storage policy string given with `--content` is a standard VS string. Please refer to the [VSAN documentation](https://pubs.vmware.com/vsphere-60/index.jsp?topic=%2Fcom.vmware.vcli.ref.doc%2Fesxcli_vsan.html) for storage policy options. -### List +#### List List all VSAN storage policies. -``` +```bash [root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py policy ls Policy Name Policy Content Active ----------- --------------------------------------------------------- ------ @@ -107,7 +463,7 @@ When creating a virtual disk using `docker volume create`, the policy name shoul option such as `docker volume create --driver=vmdk --name=some-vol -o vsan-policy-name=some-policy`. The number of virtual disks using the policy will then show up in the `Active` column. -### Update +#### Update Update a VSAN storage policy. @@ -116,13 +472,13 @@ the command fails, the number of virtual disks that were successfully updated an failed to update will be shown. The names of the virtual disks that failed to update will be logged so that manual action can be taken. -``` +```bash [root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py policy update --name some-policy --content '(("proportionalCapacity" i1)' This operation may take a while. Please be patient. Successfully updated policy: some-policy ``` -### Remove +#### Remove Remove a VSAN storage policy. Note that a storage policy cannot be removed if it is currently in use by one or more virtual disks. @@ -131,41 +487,15 @@ The ability to list which virtual disks are using a specific storage policy, cha for a virtual disk, and reset virtual disks to the default storage policy is a necessary enhancement tracked [here](https://github.com/vmware/docker-volume-vsphere/issues/577). -``` +```bash [root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py policy rm some-policy Successfully removed policy: some-policy ``` -# Set -Modify attribute settings on a given volume. The volume is identified by its name and datastore, -for example if the volume name is `container-vol` then the volume is specified as "container-vol@datastore-name". -The attributes to set/modify are specified as a comma separated list as "=, =....". For example, -a command line would look like this. - -``` -$ vmdkops-admin set --volume= --options="=, =, ..." -``` - -The volume attributes are set and take effect only the next time the volume attached to a VM. The changes do not impact any VM -thats currently using the volume. For the present, only the "access" attribute is supported to be modified via this command, and -can be set to either of the allowed values "read-only" or "read-write". - -Set command allows the admin to enforce a volume to be read-only. -This removes the need to depend on [Docker's run command options for volume access](https://docs.docker.com/engine/tutorials/dockervolumes/) (``` docker run -v /vol:/vol:ro```). - -A sample use case: - -1. Create a volume, attach to a container (default is read-write). -2. Master the volume with libraries commonly used by the target application (or a cluster of apps that form a docker app bundle). -3. Use admin CLI to flip the access attribute to read-only. -4. Make those libraries available to the containers in the app bundle and they can all share the same libraries. - -The container images themselves can be smaller as they share the libs and possibly binaries from read-only volumes. - -# Status +## Status Show config and run-time information about the service. -``` +```bash [root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py status Version: 1.0.0-0.0.1 Status: Running diff --git a/mkdocs.yml b/mkdocs.yml index 76850a323..7e908417d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,8 +2,9 @@ site_name: Docker Volume Driver for vSphere pages: - Home: index.md - Features: - - Integration with vCenter: features/vcenter.md + - Tenancy: features/tenancy.md - VSAN Policy: features/vsan-policy.md + - Integration with vCenter: features/vcenter.md - Documentation: - Installation and Deployment: user-guide/install.md - Admin CLI: user-guide/admin-cli.md @@ -17,6 +18,8 @@ pages: - 2016: - September: - Release announcement and updates: blog/2016-9-28.md + - October: + - 0.8.1 Release (Tenancy) and stateful containers meetup: blog/2016-10-28.md theme: readthedocs google_analytics: ['UA-81413942-1', 'https://vmware.github.io/docker-volume-vsphere/'] site_favicon: favicon.ico @@ -28,3 +31,4 @@ markdown_extensions: - toc: permalink: True - sane_lists + - fenced_code