diff --git a/jekyll-docs/admin-cli.md b/jekyll-docs/admin-cli.md index e9e989467..612a90492 100644 --- a/jekyll-docs/admin-cli.md +++ b/jekyll-docs/admin-cli.md @@ -14,17 +14,64 @@ of all virtual disks created and in use on the host. For these reasons, an admi created that runs on the ESXi host and that provides access to information not visible from the Docker CLI. -The admin cli also enables ESX admins to implement tenancy. +The admin CLI also enables ESX admins to implement access control and basic storage quotas. + +Admin CLI is located at `/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py`. It supports `--help` at +every command and sub-command. e.g. + +**NOTE** Access control is not supported for Stateless ESXi , as the code relies on Authorization Config DB (aka "Config DB"), or symlink to the Confg DB, being in /etc/vmware/vmdksops/auth-db. + +``` +[root@localhost:~] alias vmdkops_admin=/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py +[root@localhost:~] vmdkops_admin --help +usage: vmdkops_admin.py [-h] {volume,policy,status,config,vmgroup} ... + +vSphere Docker Volume Service admin CLI + +optional arguments: + -h, --help show this help message and exit + +Manage VMDK-based Volumes for Docker: + + {volume,policy,status,config,vmgroup} + action + volume Manipulate volumes + policy Configure and display storage policy information + status Show the status of the vmdk_ops service + config Init and manage Config DB which enables quotas and + access control + vmgroup Administer and monitor volume access control +[root@localhost:~] vmdkops_admin volume --help +usage: vmdkops_admin.py volume [-h] {set,ls} ... + +optional arguments: + -h, --help show this help message and exit + +Manipulate volumes: + + {set,ls} action + set Edit settings for a given volume + ls List volumes +``` + +It also prompts for available choices, e.g. +``` +[root@localhost:~] vmdkops_admin volume hm +usage: vmdkops_admin.py volume [-h] {set,ls} ... +vmdkops_admin.py volume: error: invalid choice: 'hm' (choose from 'set', 'ls') +``` + The remainder of this document will describe each admin CLI command and provide examples of their usage. ## Vmgroup -Help for VMgroup command: +vmgroups allow placing access control restrictions on all Docker storage requests issued from a group of VMs. Administrator can create a vmgroup, place a set of VMs in it (`create` and ``vm add`` subcommands, and then associate this group with a specific set of Datastores and access privileges (`access` and `update` subcommands). -``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup -h +### Help +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup -h usage: vmdkops_admin.py vmgroup [-h] {create,vm,update,access,ls,rm} ... positional arguments: @@ -41,105 +88,172 @@ optional arguments: -h, --help show this help message and exit ``` -Create - +### Create A vmgroup named "_DEFAULT" will be created automatically post install. +``` +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls +Uuid Name Description Default_datastore VM_list +------------------------------------ -------- ------------------------- ----------------- ------- +11111111-1111-1111-1111-111111111111 _DEFAULT This is a default vmgroup _VM_DS +``` + +The "Default_datastore" field is set to "_VM_DS" for "_DEFAULT" vmgroup. Any volume create from VM which belongs to "_DEFAULT" vmgroup will be created on the datastore where VM resides. + +When configuration is initialized with 'config init', the access to _ALL_DS and _VM_DS for all VMs is automatically enabled. +``` +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=_DEFAULT +Datastore Allow_create Max_volume_size Total_size +--------- ------------ --------------- ---------- +_ALL_DS True Unset Unset +_VM_DS True Unset Unset +``` Creates a new named vmgroup and optionally assigns VMs. Valid vmgroup name is only allowed to be "[a-zA-Z0-9_][a-zA-Z0-9_.-]*" +"Default_datastore" is a required parameter. The value is either a valid datastore name, or special string "_VM_DS. +After setting the "default_datastore" of a named vmgroup, a full access privilege to the "default_datastore" will be added automatically +and the volume will be created on the "default_datastore" if using short name. +After default_datastore is set, all VMs in the group have full access to it. Also, all volumes created with [short names](/features/tenancy/#Default datastore) +will be placed on this datastore. +Users can modify this privilege using `vmgroup access` subcommands. + Sample: +``` +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup create --name=vmgroup1 --default-datastore=datastore1 +vmgroup 'vmgroup1' is created. Do not forget to run 'vmgroup vm add' to add vm to vmgroup. +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls +Uuid Name Description Default_datastore VM_list +------------------------------------ -------- ------------------------- ----------------- ------- +11111111-1111-1111-1111-111111111111 _DEFAULT This is a default vmgroup _VM_DS +9de84179-6894-44ad-b444-470e8619a5ed vmgroup1 datastore1 +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 +Datastore Allow_create Max_volume_size Total_size +---------- ------------ --------------- ---------- +datastore1 True Unset Unset ``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup create --name=vmgroup1 -vmgroup 'vmgroup1' is created. Do not forget to run 'vmgroup vm add' and 'vmgroup access add' commands to enable access control. -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls -Uuid Name Description Default_datastore VM_list ------------------------------------- --------- -------------------------- ----------------- ------- -11111111-1111-1111-1111-111111111111 _DEFAULT This is a default vmgroup -1ddb5b46-6a9f-4649-8e48-c47039905752 vmgroup1 +The "default_datastore" can be also set to a special value "_VM_DS" during vmgroup create. ``` +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls +Uuid Name Description Default_datastore VM_list +------------------------------------ -------- --------------------------- ----------------- ------- +11111111-1111-1111-1111-111111111111 _DEFAULT This is the default vmgroup _VM_DS -The vmgroup to VM association can be done at create time. +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup create --name=vmgroup1 --default-datastore="_VM_DS" +vmgroup 'vmgroup1' is created. Do not forget to run 'vmgroup vm add' to add vm to vmgroup. +[root@localhost:~] +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls +Uuid Name Description Default_datastore VM_list +------------------------------------ -------- --------------------------- ----------------- ------- +11111111-1111-1111-1111-111111111111 _DEFAULT This is the default vmgroup _VM_DS +30545fdc-20e0-409a-8330-6ebe027fcc34 vmgroup1 _VM_DS -Sample: +[root@localhost:~] +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 +Datastore Allow_create Max_volume_size Total_size +--------- ------------ --------------- ---------- +_VM_DS True Unset Unset ``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup create --name=vmgroup1 --vm-list=photon6 -vmgroup 'vmgroup1' is created. Do not forget to run 'vmgroup vm add' and 'vmgroup access add' commands to enable access control. -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls -Uuid Name Description Default_datastore VM_list ------------------------------------- --------- -------------------------- ----------------- -------- -11111111-1111-1111-1111-111111111111 _DEFAULT This is a default vmgroup -035ddfb7-349b-4ba1-8abf-e77a430d5098 vmgroup1 photon6 +"Default_datastore" cannot be set to "_ALL_DS". An attempt to do so will generate an error" +``` +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup create --name=vmgroup2 --default-datastore="_ALL_DS" +Cannot use _ALL_DS as default datastore. Please use specific datastore name or _VM_DS special datastore +``` + +The vmgroup to VM association can be done at create time. +Sample: ``` +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup create --name=vmgroup1 --default-datastore=datastore1 --vm-list=photon7 +vmgroup 'vmgroup1' is created. Do not forget to run 'vmgroup vm add' to add vm to vmgroup. +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls +Uuid Name Description Default_datastore VM_list +------------------------------------ -------- ------------------------- ----------------- ------- +11111111-1111-1111-1111-111111111111 _DEFAULT This is a default vmgroup _VM_DS +04423382-efa4-4525-b0a6-16b98ce38f0f vmgroup1 datastore1 photon7 +``` +#### Help ``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup create -h -usage: vmdkops_admin.py vmgroup create [-h] --name NAME - [--description DESCRIPTION] - [--vm-list vm1, vm2, ...] +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup create -h +usage: vmdkops_admin.py vmgroup create [-h] --name NAME --default-datastore + DEFAULT_DATASTORE + [--description DESCRIPTION] + [--vm-list vm1, vm2, ...] optional arguments: -h, --help show this help message and exit --name NAME The name of the vmgroup + --default-datastore DEFAULT_DATASTORE + Datastore to be used by default for volumes placement --description DESCRIPTION The description of the vmgroup --vm-list vm1, vm2, ... A list of VM names to place in this vmgroup ``` - -List - +### List List existing vmgroups, the datastores vmgroups have access to and the VMs assigned. - ``` -#usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls -Uuid Name Description Default_datastore VM_list ------------------------------------- --------- -------------------------- ----------------- -------- -11111111-1111-1111-1111-111111111111 _DEFAULT This is a default vmgroup -035ddfb7-349b-4ba1-8abf-e77a430d5098 vmgroup1 photon6 +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls +Uuid Name Description Default_datastore VM_list +------------------------------------ -------- ------------------------- ----------------- ------- +11111111-1111-1111-1111-111111111111 _DEFAULT This is a default vmgroup _VM_DS +04423382-efa4-4525-b0a6-16b98ce38f0f vmgroup1 datastore1 photon7 ``` - +#### Help ``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls -h +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls -h usage: vmdkops_admin.py vmgroup ls [-h] optional arguments: -h, --help show this help message and exit ``` -Update - +### Update Update existing vmgroup. This command allows to update "Description" and "Default_datastore" fields, or rename an existing vmgroup. - +"Default_datastore" is either a valid datastore name or a special value "_VM_DS". +After changing the "default_datastore" for a vmgroup, a full access privilege to the new "default_datastore" will be created automatically, and the existing access privilege to old "default_datastore" will remain. User can remove the access privilege to old "default_datastore" if not needed using `vmgroup access rm` subcommands. +Sample: ``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls -Uuid Name Description Default_datastore VM_list ------------------------------------- --------- -------------------------- ----------------- -------- -11111111-1111-1111-1111-111111111111 _DEFAULT This is a default vmgroup -035ddfb7-349b-4ba1-8abf-e77a430d5098 vmgroup1 photon6 +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls +Uuid Name Description Default_datastore VM_list +------------------------------------ -------- ------------------------- ----------------- ------- +11111111-1111-1111-1111-111111111111 _DEFAULT This is a default vmgroup _VM_DS +0767f5f8-73de-4382-8c38-1935bb636ef4 vmgroup1 datastore1 photon7 +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 +Datastore Allow_create Max_volume_size Total_size +---------- ------------ --------------- ---------- +datastore1 True Unset Unset -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup update --name=vmgroup1 --description="New description of vmgroup1" --new-name=new-vmgroup1 --default-datastore=datastore1 +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup update --name=vmgroup1 --description="New description of vmgroup1" --new-name=new-vmgroup1 --default-datastore=datastore2 vmgroup modify succeeded -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls -Uuid Name Description Default_datastore VM_list ------------------------------------- ------------- ---------------------------- ----------------- -------- -11111111-1111-1111-1111-111111111111 _DEFAULT This is a default vmgroup -035ddfb7-349b-4ba1-8abf-e77a430d5098 new-vmgroup1 New description of vmgroup1 datastore1 photon6 +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls +Uuid Name Description Default_datastore VM_list +------------------------------------ ------------ --------------------------- ----------------- ------- +11111111-1111-1111-1111-111111111111 _DEFAULT This is a default vmgroup _VM_DS +0767f5f8-73de-4382-8c38-1935bb636ef4 new-vmgroup1 New description of vmgroup1 datastore2 photon7 + +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=new-vmgroup1 +Datastore Allow_create Max_volume_size Total_size +---------- ------------ --------------- ---------- +datastore1 True Unset Unset +datastore2 True Unset Unset ``` +Please use the test suggested above, for "create". +#### Help ``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup update -h +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup update -h usage: vmdkops_admin.py vmgroup update [-h] --name NAME [--default-datastore DEFAULT_DATASTORE] [--description DESCRIPTION] @@ -157,26 +271,29 @@ optional arguments: ``` -Remove - +### Remove Remove a vmgroup, optionally all volumes for a vmgroup can be removed as well. Sample: - ``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup rm --name=vmgroup1 --remove-volumes +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup rm --name=vmgroup1 --remove-volumes All Volumes will be removed vmgroup rm succeeded -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls Uuid Name Description Default_datastore VM_list ------------------------------------ -------- -------------------------- ----------------- ------- 11111111-1111-1111-1111-111111111111 _DEFAULT This is a default vmgroup ``` - +In MultiNode mode, VMs from different hosts can be a part of a vmgroup. +When in this mode, vmgroup which has member VMs in it cannot be directly deleted. +First remove the VMs individually from the vmgroup using admin cli +on the same host on which the VM resides. +Then remove the vmgroup. +#### Help ``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup rm -h +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup rm -h usage: vmdkops_admin.py vmgroup rm [-h] --name NAME [--remove-volumes] optional arguments: @@ -187,71 +304,71 @@ optional arguments: ``` -## Virtual Machine - -Add +### Virtual Machine +#### Add Add a VM to a vmgroup. A VM can only access the datastores for the vmgroup it is assigned to. VMs can be assigned to only one vmgroup at a time. - ``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls Uuid Name Description Default_datastore VM_list ------------------------------------ --------- -------------------------- ----------------- -------- 11111111-1111-1111-1111-111111111111 _DEFAULT This is a default vmgroup 6d810c66-ffc7-47c8-8870-72114f86c2cf vmgroup1 photon6 -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup vm add --name=vmgroup1 --vm-list=photon7 +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup vm add --name=vmgroup1 --vm-list=photon7 vmgroup vm add succeeded ``` -List - +#### List ``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup vm ls --name=vmgroup1 +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup vm ls --name=vmgroup1 Uuid Name ------------------------------------ -------- 564d5849-b135-1259-cc73-d2d3aa1d9b8c photon6 564d99a2-4097-9966-579f-3dc4082b10c9 photon7 ``` -Remove - +#### Remove Remove a VM from a vmgroup's list of VMs. VM will no longer be able to access the volumes created for the vmgroup. - ``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup vm rm --name=vmgroup1 --vm-list=photon7 +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup vm rm --name=vmgroup1 --vm-list=photon7 vmgroup vm rm succeeded -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup vm ls --name=vmgroup1 +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup vm ls --name=vmgroup1 Uuid Name ------------------------------------ -------- 564d5849-b135-1259-cc73-d2d3aa1d9b8c photon6 ``` -Replace - +### Replace Replace VMs from a vmgroup's list of VMs. VMs which are replaced will no longer be able to access the volumes created for the vmgroup. - ``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup vm ls --name=vmgroup1 +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup vm ls --name=vmgroup1 Uuid Name ------------------------------------ -------- 564d5849-b135-1259-cc73-d2d3aa1d9b8c photon6 -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup vm replace --name=vmgroup1 --vm-list=photon7 +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup vm replace --name=vmgroup1 --vm-list=photon7 vmgroup vm replace succeeded -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup vm ls --name=vmgroup1 +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup vm ls --name=vmgroup1 Uuid Name ------------------------------------ -------- 564d99a2-4097-9966-579f-3dc4082b10c9 photon7 ``` +Note: If the VMs have volumes attached (containers running), their membership change i.e. changing the vmgroup to which +they belong is not permitted. Make sure no volumes are attached. +To do so: +1. Get the list of containers running. (docker ps) +2. If the container has any vDVS volume mounted (docker inspect container_name), stop the container. +3. Ensure that the dvs volumes have status detached (docker volume inspect) +#### Help ``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup vm -h +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup vm -h usage: vmdkops_admin.py vmgroup vm [-h] {rm,add,ls,replace} ... positional arguments: @@ -266,14 +383,13 @@ optional arguments: ``` -Access - +### Access Change the access control for a vmgroup. This includes ability to grant privileges & set resource consumption limits for a datastore. - -``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access -h +#### Help +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access -h usage: vmdkops_admin.py vmgroup access [-h] {rm,add,set,ls} ... positional arguments: @@ -288,119 +404,120 @@ optional arguments: ``` -Add - +#### Add Grants datastore access to a vmgroup. - -The datastore will be automatically set as "default_datastore" for the vmgroup -when you grant first datastore access for a vmgroup. - +Valid value for "datastore" includes the name of valid datastores in the ESX host , special value "_VM_DS" or "_ALL_DS". +When DS is set to _VM_DS, access to vm_datastore where vm lives is allowed for vms in vmgroup. +When DS is set to _ALL_DS, access to all DS is allowed for vms in vmgroup. Sample: -``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access add --name=vmgroup1 --datastore=datastore1 --volume-maxsize=500MB --volume-totalsize=1GB -vmgroup access add succeeded - -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls -Uuid Name Description Default_datastore VM_list ------------------------------------- --------- -------------------------- ----------------- ------- -11111111-1111-1111-1111-111111111111 _DEFAULT This is a default vmgroup -6d810c66-ffc7-47c8-8870-72114f86c2cf vmgroup1 datastore1 photon7 -``` - -The datastore will be set as "default_datastore" for the vmgroup when you grant datastore access for a vmgroup with "--default-datastore" flag. - -Sample: +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 +Datastore Allow_create Max_volume_size Total_size +---------- ------------ --------------- ---------- +datastore1 True Unset Unset -``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access add --name=vmgroup1 --datastore=datastore2 --allow-create --default-datastore --volume-maxsize=500MB --volume-totalsize=1GB +[root@localhost:~] +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access add --name=vmgroup1 --datastore=datastore2 --volume-maxsize=500MB --volume-totalsize=1GB vmgroup access add succeeded - -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 +[root@localhost:~] +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 Datastore Allow_create Max_volume_size Total_size ---------- ------------ --------------- ---------- -datastore1 False 500.00MB 1.00GB -datastore2 True 500.00MB 1.00GB - -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls -Uuid Name Description Default_datastore VM_list ------------------------------------- --------- -------------------------- ----------------- ------- -11111111-1111-1111-1111-111111111111 _DEFAULT This is a default vmgroup -6d810c66-ffc7-47c8-8870-72114f86c2cf vmgroup1 datastore2 photon7 +datastore1 True Unset Unset +datastore2 False 500.00MB 1.00GB ``` By default no "allow_create" right is given -``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access add --name=vmgroup1 --datastore=datastore1 --volume-maxsize=500MB --volume-totalsize=1GB +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access add --name=vmgroup1 --datastore=datastore2 --volume-maxsize=500MB --volume-totalsize=1GB vmgroup access add succeeded - -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 +[root@localhost:~] +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 Datastore Allow_create Max_volume_size Total_size ---------- ------------ --------------- ---------- -datastore1 False 500.00MB 1.00GB +datastore1 True Unset Unset +datastore2 False 500.00MB 1.00GB ``` "allow_create" right is given when you run the command with "--allow-create" flag. - -``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access add --name=vmgroup1 --datastore=datastore2 --allow-create --default-datastore --volume-maxsize=500MB --volume-totalsize=1GB +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access add --name=vmgroup1 --datastore=datastore2 --volume-maxsize=500MB --volume-totalsize=1GB --allow-create vmgroup access add succeeded - -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 +[root@localhost:~] +[root@localhost:~] +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 Datastore Allow_create Max_volume_size Total_size ---------- ------------ --------------- ---------- -datastore1 False 500.00MB 1.00GB +datastore1 True Unset Unset datastore2 True 500.00MB 1.00GB ``` - +For _VM_DS and _ALL_DS special DS names, --volume-totalzie has to be "Unset". +``` +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access add --name=vmgroup1 --datastore=_VM_DS --volume-maxsize=500MB --volume-totalsize=1GB --allow-create +Canont set volume-totalsize for _VM_DS +[root@localhost:~] +[root@localhost:~] +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access add --name=vmgroup1 --datastore=_ALL_DS --volume-maxsize=500MB --volume-totalsize=1GB --allow-create +Canont set volume-totalsize for _VM_DS +[root@localhost:~] +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access add --name=vmgroup1 --datastore=_ALL_DS --volume-maxsize=500MB --allow-create +vmgroup access add succeeded +[root@localhost:~] +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 +Datastore Allow_create Max_volume_size Total_size +---------- ------------ --------------- ---------- +datastore1 True Unset Unset +_ALL_DS True 500.00MB Unset ``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access add -h + + +##### Help +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access add -h usage: vmdkops_admin.py vmgroup access add [-h] - [--volume-totalsize Num{MB,GB,TB} - e.g. 2TB] - [--volume-maxsize Num{MB,GB,TB} - e.g. 2TB] - [--allow-create] --name NAME - [--default-datastore] --datastore - DATASTORE + [--volume-totalsize Num{MB,GB,TB} - e.g. 2TB] + --name NAME + [--volume-maxsize Num{MB,GB,TB} - e.g. 2TB] + [--allow-create] --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 vmgroup + --name NAME The name of the vmgroup --volume-maxsize Num{MB,GB,TB} - e.g. 2TB Maximum size of the volume that can be created --allow-create Allow create and delete on datastore if set - --name NAME The name of the vmgroup - --default-datastore Mark datastore as a default datastore for this vm- - group --datastore DATASTORE Datastore which access is controlled ``` -List - +#### List List the current access control granted to a vmgroup. When displaying the result keep in mind: - For capacity Unset indicates no limits -``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 Datastore Allow_create Max_volume_size Total_size ---------- ------------ --------------- ---------- -datastore1 False 500.00MB 1.00GB +datastore1 True Unset Unset datastore2 True 500.00MB 1.00GB ``` - -``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls -h +##### Help +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls -h usage: vmdkops_admin.py vmgroup access ls [-h] --name NAME optional arguments: @@ -409,29 +526,39 @@ optional arguments: ``` -Remove - +#### Remove Remove access to a datastore for a vmgroup. - -``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 +Removing of access privilege to "default_datastore" is not suported +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls +Uuid Name Description Default_datastore VM_list +------------------------------------ -------- ------------------------- ----------------- ------- +11111111-1111-1111-1111-111111111111 _DEFAULT This is a default vmgroup _VM_DS +2a97fef4-30cd-4a50-bf31-3dbc7d130be2 vmgroup1 datastore1 photon7 + +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 Datastore Allow_create Max_volume_size Total_size ---------- ------------ --------------- ---------- -datastore1 False 500.00MB 1.00GB +datastore1 True Unset Unset datastore2 True 500.00MB 1.00GB -# /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access rm --name=vmgroup1 --datastore=datastore1 +[root@localhost:~] +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access rm --name=vmgroup1 --datastore=datastore1 +Removing of access privilege to "default_datastore" is not supported +[root@localhost:~] +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access rm --name=vmgroup1 --datastore=datastore2 vmgroup access rm succeeded - -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 +[root@localhost:~] +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 Datastore Allow_create Max_volume_size Total_size ---------- ------------ --------------- ---------- -datastore2 True 500.00MB 1.00GB -``` - +datastore1 True Unset Unset ``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access rm -h + +##### Help +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access rm -h usage: vmdkops_admin.py vmgroup access rm [-h] --name NAME --datastore DATASTORE @@ -443,34 +570,49 @@ optional arguments: ``` -Set - +#### Set Set command allows to change the existing access control in place for a vmgroup. Sample: -``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 +```shell +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 Datastore Allow_create Max_volume_size Total_size ---------- ------------ --------------- ---------- -datastore1 False 500.00MB 1.00GB +datastore1 False Unset Unset +_ALL_DS True 500.00MB Unset -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access set --name=vmgroup1 --datastore=datastore1 --allow-create=True --volume-maxsize=1000MB --volume-totalsize=2GB +[root@localhost:~] +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access set --name=vmgroup1 --datastore=datastore1 --allow-create=True --volume-maxsize=1000MB --volume-totalsize=2GB vmgroup access set succeeded - -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls -usage: vmdkops_admin.py vmgroup access ls [-h] --name NAME -vmdkops_admin.py vmgroup access ls: error: argument --name is required -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 +[root@localhost:~] +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 Datastore Allow_create Max_volume_size Total_size ---------- ------------ --------------- ---------- datastore1 True 1000.00MB 2.00GB +_ALL_DS True 500.00MB Unset +``` +"-volume-totalsize" cannot be set to the value other than unlimit when add privilege for special value "_VM_DS" and "_ALL_DS". ``` +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access ls --name=vmgroup1 +Datastore Allow_create Max_volume_size Total_size +---------- ------------ --------------- ---------- +datastore1 True 1000.00MB 2.00GB +_ALL_DS True 500.00MB Unset +_VM_DS True Unset Unset + +[root@localhost:~] +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access set --name=vmgroup1 --datastore=_VM_DS --volume-totalsize=1GB +Canont set volume-totalsize for _VM_DS +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access set --name=vmgroup1 --datastore=_ALL_DS --volume-totalsize=1GB +Canont set volume-totalsize for _ALL_DS +``` +##### Help ``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access set -h +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access set -h usage: vmdkops_admin.py vmgroup access set [-h] [--volume-totalsize Num{MB,GB,TB} - e.g. 2TB] --name NAME @@ -497,9 +639,9 @@ optional arguments: ## Volume - -``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py volume ls -h +#### Help +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py volume ls -h usage: vmdkops_admin.py volume ls [-h] [-c Col1,Col2,...] optional arguments: @@ -509,12 +651,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. -``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py volume ls +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py volume ls Volume Datastore VMGroup Capacity Used Filesystem Policy Disk Format Attached-to Access Attach-as Created By Created Date ------ ---------- --------- -------- ---- ---------- ------ ----------- ----------- ---------- ---------------------- ---------- ------------------------ vol1 datastore1 _DEFAULT 100MB 13MB ext4 N/A thin detached read-write independent_persistent photon-6 Sun Sep 11 21:36:13 2016 @@ -523,14 +664,14 @@ vol1 datastore1 vmgroup1 100MB 13MB ext4 N/A thin d vol2 datastore1 vmgroup1 100MB 13MB ext4 N/A thin detached read-write independent_persistent photon-6 Sun Sep 11 22:48:23 2016 ``` -Note that the `Policy` column shows the named vSAN storage policy created with the same tool +Note that the `Policy` column shows the named VSAN storage policy created with the same tool (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'. Note that the `VMGroup` column shows the vmgroup by which the volume was created. If the vmgroup which created the volume has been removed, the `VMGroup` column shows up as 'N/A'. See the following example: -``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py volume ls +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py volume ls Volume Datastore VMGroup Capacity Used Filesystem Policy Disk Format Attached-to Access Attach-as Created By Created Date ------ ---------- -------- -------- ---- ---------- ------ ----------- ----------- ---------- ---------------------- ---------- ------------------------ vol1 datastore1 _DEFAULT 100MB 13MB ext4 N/A thin detached read-write independent_persistent photon-6 Sun Sep 11 21:36:13 2016 @@ -539,12 +680,12 @@ vol1 datastore1 N/A 100MB 13MB ext4 N/A thin d vol2 datastore1 N/A 100MB 13MB ext4 N/A thin detached read-write independent_persistent photon-6 Sun Sep 11 22:48:23 2016 ``` -List Selected Columns +#### List selected columns Show only the selected columns. -``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py volume ls -c volume,datastore,attached-to +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py volume ls -c volume,datastore,attached-to Volume Datastore Attached To VM --------- ---------- -------------- large-vol datastore1 detached @@ -554,14 +695,13 @@ 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`. -Set - +### Set Modify attribute settings on a given volume. The volume is identified by its name, vmgroup_name which the volume belongs to 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= --vmgroup= --options="=, =, ..." ``` @@ -582,9 +722,8 @@ A sample use case: The container images themselves can be smaller as they share the libs and possibly binaries from read-only volumes. Example: - -``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py volume ls +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py volume ls Volume Datastore VMGroup Capacity Used Filesystem Policy Disk Format Attached-to Access Attach-as Created By Created Date ------ ---------- -------- -------- ---- ---------- ------ ----------- ----------- ---------- ---------------------- ---------- ------------------------ vol1 datastore1 _DEFAULT 100MB 13MB ext4 N/A thin detached read-write independent_persistent photon-6 Sun Sep 11 21:36:13 2016 @@ -592,10 +731,10 @@ vol12 datastore1 _DEFAULT 100MB 13MB ext4 N/A thin d vol1 datastore1 N/A 100MB 13MB ext4 N/A thin detached read-write independent_persistent photon-6 Sun Sep 11 22:48:13 2016 vol2 datastore1 N/A 100MB 13MB ext4 N/A thin detached read-write independent_persistent photon-6 Sun Sep 11 22:48:23 2016 -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py volume set --volume=vol1@datastore1 --vmgroup=_DEFAULT --options="access=read-only" +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py volume set --volume=vol1@datastore1 --vmgroup=_DEFAULT --options="access=read-only" Successfully updated settings for : vol1@datastore1 -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py volume ls +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py volume ls Volume Datastore VMGroup Capacity Used Filesystem Policy Disk Format Attached-to Access Attach-as Created By Created Date ------ ---------- -------- -------- ---- ---------- ------ ----------- ----------- ---------- ---------------------- ---------- ------------------------ vol1 datastore1 _DEFAULT 100MB 13MB ext4 N/A thin detached read-only independent_persistent photon-6 Sun Sep 11 21:36:13 2016 @@ -608,11 +747,11 @@ vol2 datastore1 N/A 100MB 13MB ext4 N/A thin d ## Policy -Create, configure and show the vSAN policy names and their corresponding vSAN policy strings. Also show whether or not they are in use. - +Create, configure and show the VSAN policy names and their corresponding VSAN policy strings. Also show whether or not they are in use. -``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py policy -h +#### Help +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py policy -h usage: vmdkops_admin.py policy [-h] {rm,create,ls,update} ... positional arguments: @@ -620,32 +759,32 @@ positional arguments: rm Remove a storage policy create Create a storage policy ls List storage policies and volumes using those policies - update Update the definition of a storage policy and all vSAN + update Update the definition of a storage policy and all VSAN objects using that policy optional arguments: -h, --help show this help message and exit ``` -Create +#### Create -Create a vSAN storage policy. +Create a VSAN storage policy. -``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py policy create --name some-policy --content '(("proportionalCapacity" i0)("hostFailuresToTolerate" i0))' +```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 ``` -Note that the vSAN storage policy string given with `--content` is a standard vSAN storage policy -string. Please refer to the [vSAN documentation](https://pubs.vmware.com/vsphere-60/index.jsp?topic=%2Fcom.vmware.vcli.ref.doc%2Fesxcli_vsan.html) +Note that the VSAN storage policy string given with `--content` is a standard VSAN storage policy +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. +List all VSAN storage policies. -``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py policy ls +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py policy ls Policy Name Policy Content Active ----------- ---------------------------------------------------------- ------ some-policy (("proportionalCapacity" i0)("hostFailuresToTolerate" i0)) Unused @@ -655,46 +794,182 @@ When creating a virtual disk using `docker volume create`, the policy name shoul option such as `docker volume create --driver=vsphere --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. +Update a VSAN storage policy. -This command will update a vSAN storage policy for all virtual disks currently using this policy. If +This command will update a VSAN storage policy for all virtual disks currently using this policy. If the command fails, the number of virtual disks that were successfully updated and the number that 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. -``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py policy update --name some-policy --content '(("proportionalCapacity" i1))' +```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 (`rm`) -Remove a vSAN storage policy. Note that a storage policy cannot be removed if it is currently in use +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. The ability to list which virtual disks are using a specific storage policy, change storage policies 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). -``` -#/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py policy rm --name=some-policy +```bash +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py policy rm --name=some-policy Successfully removed policy: some-policy ``` +## `Config` (Authorization DB configuration) + +**THIS FEATURE IS EXPERIMENTAL** + +Creates, removes, moves and reports on status of Authorization config DB (referred to as `Config DB`). Config DB keeps authorization information - vmgroups, datastore access control, quota information - and without initializing it no access control is supported. Also, before Config DB is initialized, any attempt to configure access control will fail, e.g. +``` +[root@localhost:~] vmdkops_admin vmgroup create --name MY +Internal Error(Error: Please init configuration in vmdkops_admin before trying to change it) +``` + +If the Config DB is not initialized, Docker Volume Service will use "Config DB NotConfigured" Mode, when any request to create, remove, mount or unmount Docker volume is accepted. + +After initialization the service can use SingleNode mode - when the DB itself is located on the local ESXi node in `/etc/vmware/vmdkps/auth-db` file, or MultiNode mode - when the above location is a symlin to a shared datastore location. + +In SingleNode mode all vmgroups and authorization control is local for each ESXi node, and node do not share this information. + +In MultiNode mode, VSphere Docker Volume Service Authorization Config DB needs to be initialized on each ESXi host (`config init --datastore=`, and the nodes will share the authoration control. + +#### Init (`config init`) + +Initializing the config is optional. If the config is not initialized, there will be no access control and all `vmgroup` commands will fail with appropriate messages. + +Before configuring access control or quotas, the config needs to be inited to either SingleNode (`init --local`) or MultiNode (`init --datastore=ds_name`) mode. + +``` +[root@localhost:~] vmdkops_admin config init -h +usage: vmdkops_admin.py config init [-h] [--local] [--force] + [--datastore DATASTORE] + +optional arguments: + -h, --help show this help message and exit + --local Allows local (SingleNode) Init + --force Force operation, ignore warnings + --datastore DATASTORE + Config DB will be placed on a shared datastore +``` + +Example: + +``` +[root@localhost:~] vmdkops_admin status +Version: 0.12.fea683a-0.0.1 +Status: Running +DB_LocalPath: /etc/vmware/vmdkops/auth-db +DB_SharedLocation: n/a +DB_Mode: NotConfigured (no local DB or symlink) <===== NOT CONFIGURED +Pid: 5979199 +Port: 1019 +LogConfigFile: /etc/vmware/vmdkops/log_config.json +LogFile: /var/log/vmware/vmdk_ops.log +LogLevel: DEBUG + +[root@localhost:~] vmdkops_admin config init --local +Creating new DB at /etc/vmware/vmdkops/auth-db +Restarting the vmdkops service to pick up new configuration +Stopping vmdkops-opsd with PID=5979199 +vmdkops-opsd is not running +Starting vmdkops-opsd +vmdkops-opsd is running pid=5979684 + +[root@localhost:~] vmdkops_admin status +Version: 0.12.fea683a-0.0.1 +Status: Running +DB_LocalPath: /etc/vmware/vmdkops/auth-db +DB_SharedLocation: /etc/vmware/vmdkops/auth-db +DB_Mode: SingleNode (local DB exists) <==== LOCAL configuration +Pid: 5979684 +Port: 1019 +LogConfigFile: /etc/vmware/vmdkops/log_config.json +LogFile: /var/log/vmware/vmdk_ops.log +LogLevel: DEBUG +``` + + +#### Remove (`config rm`) + +Allows to remove local configuration DB. Since this is a destructive operation, admin needs to type both `--local` flag (to confirm it's local only operation and does not impact shared database, if any) , and `--confirm` flag to confirm that she actually wants to delete the local Config DB. + +Running `vmdkops_admin config rm` with no flags prints an explanation on how to remove the shared config DB, if any. + +``` +usage: vmdkops_admin.py config rm [-h] [--local] [--no-backup] [--confirm] + +optional arguments: + -h, --help show this help message and exit + --local Remove only local link or local DB + --no-backup Do not create DB backup before removing + --confirm Explicitly confirm the operation +``` + + +#### Status + +To get config DB status, use `/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py status` command. + +#### Move (`config mv`) + +[Not implemented yet] Allows to relocate config DB between datastores. + ## Status Show config and run-time information about the service. ``` -# /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py status - Version: 1.0.0-0.0.1 - Status: Running - Pid: 161104 - Port: 1019 - LogConfigFile: /etc/vmware/vmdkops/log_config.json - LogFile: /var/log/vmware/vmdk_ops.log - LogLevel: INFO -``` +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py status -h +usage: vmdkops_admin.py status [-h] [--fast] + +optional arguments: + -h, --help show this help message and exit + --fast SKip some of the data collection (port, version) + ``` + + +```bash +[root@localhost:~] time /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py status +Version: 0.12.0afa0ec-0.0.1 +Status: Running +DB_LocalPath: /etc/vmware/vmdkops/auth-db +DB_SharedLocation: N/A +DB_Mode: SingleNode (local DB exists) +Pid: 6298936 +Port: 1019 +LogConfigFile: /etc/vmware/vmdkops/log_config.json +LogFile: /var/log/vmware/vmdk_ops.log +LogLevel: DEBUG + +real 0m 2.01s +user 0m 0.59s +sys 0m 0.00s +``` + + Some of the information retrieval may be slow (e.g. VIB version (`Version` field) # or VMCI port number (`Port` field). `--fast` flag skips slow data collection and prints `?` for fields with no information. + +```bash +[root@localhost:~] time /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py status --fast +Version: ? +Status: Running +DB_LocalPath: /etc/vmware/vmdkops/auth-db +DB_SharedLocation: N/A +DB_Mode: SingleNode (local DB exists) +Pid: 6298936 +Port: ? +LogConfigFile: /etc/vmware/vmdkops/log_config.json +LogFile: /var/log/vmware/vmdk_ops.log +LogLevel: DEBUG + +real 0m 0.72s +user 0m 0.51s +sys 0m 0.00s +``` \ No newline at end of file diff --git a/jekyll-docs/docker-volume-cli.md b/jekyll-docs/docker-volume-cli.md index 13c859c07..a8db48323 100644 --- a/jekyll-docs/docker-volume-cli.md +++ b/jekyll-docs/docker-volume-cli.md @@ -33,7 +33,7 @@ docker volume create --driver=vsphere --name=MyVolume -o size=10gb -o vsan-polic You can find more details about policy management using vSAN in page [Storage policy based management](policy-based-management.md) ##### Disk Format (diskformat) -The docker volumes are backed by VMDK and there are types of VMDK. At the moment following types of VMDKs are supported: +The docker volumes are backed by VMDK and VMDKs support multiple [types](https://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=1022242). At the moment following types of VMDKs are supported: @@ -58,6 +58,11 @@ The docker volumes are backed by VMDK and there are types of VMDK. At the moment
+``` +docker volume create --driver=vsphere --name=MyVolume -o size=10gb -o diskformat=zeroedthick +docker volume create --driver=vsphere --name=MyVolume -o size=10gb -o diskformat=thin +docker volume create --driver=vsphere --name=MyVolume -o size=10gb -o diskformat=eagerzeroedthick +``` ##### Disk Modes (attach-as) Docker volumes used in vDVS are backed by VMDKs. VMDKs are attached to hosts on which containers are running. These VMDKs can be attached in [different modes.](http://cormachogan.com/2013/04/16/what-are-dependent-independent-disks-persistent-and-non-persisent-modes/) diff --git a/jekyll-docs/faq.md b/jekyll-docs/faq.md index ae2782c11..bb03bc556 100644 --- a/jekyll-docs/faq.md +++ b/jekyll-docs/faq.md @@ -4,6 +4,9 @@ title: FAQs ## General +### Where do I get the binaries? What about the source? +Please look at [GitHub Releases](https://github.com/vmware/docker-volume-vsphere/releases) for binaries. Github releases allow downloading of source for a release in addition to git clone. + ### How to install and use the driver? Please see README.md in the for the release by clicking on the tag for the release. Example: [README](https://github.com/vmware/docker-volume-vsphere/tree/0.1.0.tp.2) @@ -36,6 +39,20 @@ It occurs if the Docker volume service cannot communicate to the ESX back end. T It occurs if the linux kernel does not know about the AF family used for VMCI communication. Please read ["What is VMCI and vSock and why is it needed?"](https://vmware.github.io/docker-volume-vsphere/user-guide/faq/#what-is-vmci-and-vsock-and-why-is-it-needed) above. +#### I'm not able to create volume after upgrading to vDVS managed plugin, what is the cause? +``` +# docker volume create -d vsphere vol5 +Error response from daemon: create vol5: Post http://%2Frun%2Fdocker%2Fplugins%2Fvsphere.sock/VolumeDriver.Create: dial unix /run/docker/plugins/vsphere.sock: connect: no such file or directory +``` + +Restart docker service is required. + +e.g. +``` +systemctl restart docker +``` + + ## Upgrade to version 0.10 (Dec 2016) release Tenancy changes in release 0.10 need a manual upgrade process enumerated below. @@ -118,19 +135,14 @@ Step 4: Recreate the vmgroup configuration with new name “new-vmgroup1” (ass ***Note: Please DO NOT create the vmgroup with the old name “vmgroup1”!!!*** ``` -[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup create --name=new-vmgroup1 --vm-list=photon-6 -vmgroup 'new-vmgroup1' is created. Do not forget to run 'vmgroup vm add' and 'vmgroup access add' commands to enable access control. -[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup access add --name=new-vmgroup1 --datastore=datastore1 --volume-maxsize=500MB --volume-totalsize=1GB --allow-create -vmgroup access add succeeded +[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup create --name=new-vmgroup1 --vm-list=photon-6 --default-datastore=datastore1 +vmgroup 'new-vmgroup1' is created. Do not forget to run 'vmgroup vm add' to add vm to vmgroup. [root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vmgroup ls Uuid Name Description Default_datastore VM_list ------------------------------------ ------------- -------------------------- ----------------- -------- 11111111-1111-1111-1111-111111111111 _DEFAULT This is a default vmgroup 5c0927fb-86b5-4034-87db-8bdfa24018d4 new-vmgroup1 datastore1 photon-6 - - - ``` Step 4: Run “docker volume ls” from VM “photon-6”, volume which belongs to “vmgroup1” which was created before will not be visible diff --git a/jekyll-docs/faqs.md b/jekyll-docs/faqs.md deleted file mode 100644 index 4ebaaddd5..000000000 --- a/jekyll-docs/faqs.md +++ /dev/null @@ -1,168 +0,0 @@ -[TOC] - -# General - -## Where do I get the binaries ? What about the source ? -Please look at [GitHub Releases](https://github.com/vmware/docker-volume-vsphere/releases) for binaries. Github releases allow downloading of source for a release in addition to git clone. - -## How to install and use the driver? -Please see README.md in the for the release by clicking on the tag for the release. Example: [README](https://github.com/vmware/docker-volume-vsphere/tree/0.1.0.tp.2) - -## How do I run the setup on my laptop? -Follow the [guide on the wiki](https://github.com/vmware/docker-volume-vsphere/wiki/Using-laptop-for-running-the-entire-stack) - -# Troubleshooting - -## Docker Service to ESX Backend Communication. - -### What is VMCI and vSock and why is it needed? - -vSphere Docker Volume Service uses VMCI and vSock to communicate with the hypervisor to implement the volume operations. It comes installed on Photon OS and on Ubuntu follow [VMware tools installation](http://pubs.vmware.com/vsphere-60/index.jsp#com.vmware.vsphere.vm_admin.doc/GUID-08BB9465-D40A-4E16-9E15-8C016CC8166F.html#GUID-08BB9465-D40A-4E16-9E15-8C016CC8166F) or use open vmtools -```apt-get install open-vm-tools```. -Additional reading for differences between VMware tools and open vm tools: - -* [Open-VM-Tools (OVT): The Future Of VMware Tools For Linux](http://blogs.vmware.com/vsphere/2015/09/open-vm-tools-ovt-the-future-of-vmware-tools-for-linux.html) -* [VMware Tools vs Open VM Tools](http://superuser.com/questions/270112/open-vm-tools-vs-vmware-tools) - -### I see "connection reset by peer (errno=104)" in the [service's logs](https://github.com/vmware/docker-volume-vsphere#logging), what is the cause? -104 is a standard linux error (```#define ECONNRESET 104 /* Connection reset by peer */```) - -It occurs if the Docker volume service cannot communicate to the ESX back end. This can happen if: - * VMCI and/or vSock kernel modules are not loaded or the kernel does not support VMCI and vSock. Please read "What is VMCI and vSock and why is it needed?" above. - * ESX service is not running. ```/etc/init.d/vmdk-opsd status```. Check [ESX Logs](https://github.com/vmware/docker-volume-vsphere#logging) - * ESX service and the docker volume service are not communicating on the same port. ```ps -c | grep vmdk #On ESX``` and ```ps aux| grep docker-volume-vsphere # On VM``` check the port param passed in and make sure they are the same - -### I see "address family not supported by protocol (errno=97)" in the [service's logs](https://github.com/vmware/docker-volume-vsphere#logging), what is the cause? -97 is a standard linux error (```#define EAFNOSUPPORT 97 /* Address family not supported by protocol */```) - -It occurs if the linux kernel does not know about the AF family used for VMCI communication. Please read ["What is VMCI and vSock and why is it needed?"](https://vmware.github.io/docker-volume-vsphere/user-guide/faq/#what-is-vmci-and-vsock-and-why-is-it-needed) above. - -## Upgrade to version 0.10 (Dec 2016) release - -Tenancy changes in release 0.10 need a manual upgrade process enumerated below. -***Save the desired tenancy configuration before upgrade*** - -### How to know if auth-db upgrade is needed post install? - -After installing the new build, type command “vm-group ls” -Check for failure to connect to auth DB. - -``` -/usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vm-group ls -Failed to connect auth DB(DB connection error /etc/vmware/vmdkops/auth-db) -``` - -The corresponding errors in the vmdk_ops.log file. - -``` -[root@localhost:~] cat /var/log/vmware/vmdk_ops.log - -08/29/16 08:20:23 297059 [MainThread] [ERROR ] version 0.0 in auth-db does not match latest DB version 1.0 -08/29/16 08:20:23 297059 [MainThread] [ERROR ] DB upgrade is not supported. Please remove the DB file at /etc/vmware/vmdkops/auth-db. All existing configuration will be removed and need to be recreated after removing the DB file. -``` - -### How to handle the upgrade manually? - -#### Case 1: No vm-group configured before - -If no vm-group has been configured, user just needs to delete the auth-db file - -Step 1: Remove auth-db file at /etc/vmware/vmdkops/auth-db - -``` -[root@localhost:/etc/vmware/vmdkops]rm /etc/vmware/vmdkops/auth-db -``` - -Step 2: Verify “vm-group ls” command -``` -[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vm-group ls -Uuid Name Description Default_datastore VM_list ------------------------------------- --------- -------------------------- ----------------- ------- -11111111-1111-1111-1111-111111111111 _DEFAULT This is a default vm-group - -``` - -After this point, the manually upgrade is done, and tenancy operations will succeed. - -#### Case2: Has vm-group configured before -Step 1: Backup data manually. - -Example below has a vm-group ```vm-group1``` with VM ```photon-6``` assigned to this vm-group1 and one volumes: vol1@datastore1 created. - -``` -root@photon-JQQBWNwG6 [ ~ ]# docker volume ls -DRIVER VOLUME NAME -vmdk vol1@datastore1 -``` - -User needs to manually backup data stored in vol1@datastore1. - -Step 2: Move the auth-db file at /etc/vmware/vmdkops/auth-db - -``` -[root@localhost:/etc/vmware/vmdkops]mv /etc/vmware/vmdkops/auth-db /etc/vmware/vmdkops/auth-db.backup.v10.upgrade -``` - -Step 3: Verify “vm-group ls” command, now only ```_DEFAULT``` should be listed. - -``` -[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vm-group ls -Uuid Name Description Default_datastore VM_list ------------------------------------- -------- -------------------------- ----------------- ------- -11111111-1111-1111-1111-111111111111 _DEFAULT This is a default vm-group - - -``` - -Step 4: Recreate the vm-group configuration with new name “new-vm-group1” (associate the same VM photon-6 to this new-vm-group1), see the following example: - -***Note: Please DO NOT create the vm-group with the old name “vm-group1”!!!*** - -``` -[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vm-group create --name=new-vm-group1 --vm-list=photon-6 -vm-group create succeeded -[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vm-group access add --name=new-vm-group1 --datastore=datastore1 --volume-maxsize=500MB --volume-totalsize=1GB --allow-create -vm-group access add succeeded - -[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vm-group vm rm --name=new-vm-group1 --vm-list=photon7 -vm-group vm rm succeeded -[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py vm-group ls -Uuid Name Description Default_datastore VM_list ------------------------------------- ------------- -------------------------- ----------------- -------- -11111111-1111-1111-1111-111111111111 _DEFAULT This is a default vm-group -5c0927fb-86b5-4034-87db-8bdfa24018d4 new-vm-group1 datastore1 photon-6 - - - -``` - -Step 4: Run “docker volume ls” from VM “photon-6”, volume which belongs to “vm-group1” which was created before will not be visible -``` -root@photon-JQQBWNwG6 [ ~ ]# docker volume ls -DRIVER VOLUME NAME -``` - -Step 5: Run “docker volume create” to create a new volume “new-vol1” and run “docker volume ls”, should only able to see this volume which was just created -``` -root@photon-KwqUODFXp [ ~ ]# docker volume create --driver=vsphere --name=new-vol1 -o size=100MB -new-vol1 -root@photon-KwqUODFXp [ ~ ]# docker volume ls -DRIVER VOLUME NAME -vsphere new-vol1@datastore1 -``` - -Volume “vol1” which was created before still exists, and can be seen from the following AdminCLI command - -``` -[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py volume ls -Volume Datastore Created By VM Created Attached To VM (name/uuid) Policy Capacity Used Disk Format Filesystem Type Access Attach As --------- ---------- ------------- ------------------------ -------------------------- ------ -------- ---- ----------- --------------- ---------- ---------------------- -vol1 datastore1 photon-6 Sun Sep 11 07:30:47 2016 detached N/A 100MB 13MB thin ext4 read-write independent_persistent -new-vol1 datastore1 photon-6 Sun Sep 11 08:03:56 2016 detached N/A 100MB 13MB thin ext4 read-write independent_persistent - -``` - -Step6: Manually copy the data from backup to the new volume "new-vol1@datastore1". -The path which stores this new volume is "/vmfs/volumes/datastore1/dockvols/new-vm-group1".Internet. It uses a dictionary of over 200 Latin words, combined with a handful of model sentence structures, to generate Lorem Ipsum which looks reasonable. The generated Lorem Ipsum is therefore always free from repetition, injected humour, or non-characteristic words etc. - -{% include links.html %} diff --git a/jekyll-docs/pages/product1/docker-plugin-drivers.md b/jekyll-docs/pages/product1/docker-plugin-drivers.md index 8f4c79cd0..422d4cf7a 100644 --- a/jekyll-docs/pages/product1/docker-plugin-drivers.md +++ b/jekyll-docs/pages/product1/docker-plugin-drivers.md @@ -34,7 +34,7 @@ The docker volume plugin supports two drivers, namely, `photon` and `vsphere` fo ## Sample plugin configuration ``` { - "Driver": "" + "Driver": "", "MaxLogAgeDays": 28, "MaxLogSizeMb": 100, "LogPath": "/var/log/docker-volume-vsphere.log",