Add documentation for tenancy. #689

kerneltime · 2016-11-03T00:13:23Z

Add documentation for github page.
Fixes #687

kerneltime · 2016-11-03T04:36:21Z

cc @asomaiah

kerneltime · 2016-11-03T04:36:56Z

@pdhamdhere I split the commits for the bug fix and the documentation update. We do need both to cut a release.

pdhamdhere

This commit looks good!

pdhamdhere · 2016-11-03T04:48:10Z

esx_service/vmdk_ops.py

@@ -478,6 +478,7 @@ def get_vol_path(datastore, tenant_name=None):
    # volumes is created on <datastore>/DOCK_VOLS_DIR
    # If the command is running under a tenant, the foler for Dock volume
    # is created on <datastore>/DOCK_VOLS_DIR/tenant_name
+    dock_vol_path = os.path.join("/vmfs/volumes", datastore, DOCK_VOLS_DIR)
    if tenant_name:
        path = os.path.join("/vmfs/volumes", datastore, DOCK_VOLS_DIR, tenant_name)


os.path.join(dock_vol_path, tenant_name). I am okay if you decide to leave it as-is.

Makes sense.

pdhamdhere

Overall looks good. I think we need to re-order tenant admin CLI commands.

pdhamdhere · 2016-11-03T04:53:04Z

docs/blog/2016-10-28.md


-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.


I would avoid adjectives like "big"! Perhaps highlight 2-3 most significant feature under "What's new?"?

I would also qualify "Multi-tenancy" as tech-preview.

pdhamdhere · 2016-11-03T04:55:05Z

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.


How about restructuring little bit;

Tenants can be used to provide isolation between independent groups in shared environment, where multiple groups are using a common infrastructure (compute, storage, network) fabric. Tenants are useful for isolating resources from one tenant from those of other tenants. For e.g. volumes created by TenantA will neither be visible nor accessible to TenantB, even if those volumes reside on storage shared by multiple tenants. In addition, vSphere Administrator can enforce access control policies and set storage quotas for each tenant.
Some attributes that define Tenant;

vSphere Administrator can define group of one or more Docker Host (VM) as Tenant.

Docker Host (VM) can be member of one and only one Tenant.

Docker Host (VM) if not assigned to any Tenant are member of _Default tenant.

vSphere Administrator can grant Tenant privileges & set resource consumption limits at granularity of datastore.

Ok will think about it. I do not want to explain tenancy itself but just how we implement it.

pdhamdhere · 2016-11-03T04:55:41Z

docs/features/tenancy.md

+## 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)


What is relevance of this link here?

We are introducing terms such as datastore without giving any background.. the design spec is public and a good read, we can skip that.

The logic to handle _Default tenant is not implemented yet.

What do you mean "tenancy:ant privileges"? I don't understand. Any typo?

Made some changes to the write up.

@kerneltime datastore is vSphere basics and to use this feature you already need to be familiar with vSphere. I suggest to remove link to vSphere Storage. It seems out of place.

pdhamdhere · 2016-11-03T04:57:15Z

docs/user-guide/admin-cli.md

+```
+#### Add
+
+Add a datastore to be access by a tenant.


Grant datastore access to Tenant?

pdhamdhere · 2016-11-03T04:59:49Z

docs/user-guide/admin-cli.md

+```
+### Create
+
+Create a tenant that can be assigned VMs. Only the VMs assigned to the tenant will be able to


Just limit it to "Creates a new named Tenant and assign VMs to Tenant". Also this should be first command in Admin CLI doc.

pdhamdhere · 2016-11-03T05:01:52Z

docs/user-guide/admin-cli.md

+  -h, --help            show this help message and exit
+```
+
+### Access


IMO, we should start with "create tenant".

pdhamdhere · 2016-11-03T05:08:04Z

CC/ @asomaiah It would be great if you can take a quick look at docs.

kerneltime · 2016-11-03T06:30:21Z

Updated. Will review this again tomorrow.

kerneltime · 2016-11-03T06:33:08Z

if a reviewer wants to look at the final output that will get posted to the project page

git fetch
git checkout tenancy-doc-n-fix.kerneltime
make documentation # needs make and docker installed
mkdocs serve -a 0.0.0.0:8000

Open browser on same machine and head to 127.0.0.1:8000

More info https://github.com/vmware/docker-volume-vsphere/blob/master/CONTRIBUTING.md

lipingxue · 2016-11-03T16:32:22Z

docs/features/tenancy.md

+## 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)


The logic to handle _Default tenant is not implemented yet.

lipingxue · 2016-11-03T16:34:03Z

docs/features/tenancy.md

+## 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)


What do you mean "tenancy:ant privileges"? I don't understand. Any typo?

lipingxue · 2016-11-03T16:38:09Z

docs/user-guide/admin-cli.md

+  -h, --help  show this help message and exit
+```
+
+### Virtual Machine


I think it would be better to move the AdminCLI to add/remove virtual machine before those commands to manipulate datastore access privileges.

lipingxue · 2016-11-03T16:42:38Z

docs/user-guide/admin-cli.md

+
+```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}


remove this line. It is a "print" which I forget to remove in the code. Please remove this print at Line 1008 (in function "tenant_access_add")

If it is part of this release we should keep it, once we update the CLI the documentation will need updating as well.

Is it possible for you to include the small fix in this PR too? Just remove remove this print at Line 1008 (in function "tenant_access_add")? This should not affect any existing functionality. Just remove a unused print command which I added for debugging.

lipingxue · 2016-11-03T16:43:24Z

docs/user-guide/admin-cli.md

+
+```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}


remove this line.

Once the CLI is updated we can change the documentation.

lipingxue · 2016-11-03T16:46:27Z

docs/user-guide/admin-cli.md

+
+### Virtual Machine
+#### Add
+Add a VM to a tenant. A VM can only access the datastores for the tenant it is assigned to.


It would be more clear to move the example for "tenant vm add" command here.

lipingxue · 2016-11-03T16:50:14Z

docs/user-guide/admin-cli.md

 ```
+### Remove
+
+Remove a tenant, optionally all volumes for a tenant can be removed as well.


The "tenant rm" command will print "tenant rm succeeded" if command succeeded. Please include that in the command example.

lipingxue · 2016-11-03T16:52:25Z

docs/user-guide/admin-cli.md

+```
+
+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


I think set command now also support "attached_as" attribute.

It does not show up in help, when the help is updated we can update the documentation.

[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py set -h usage: vmdkops_admin.py set [-h] --volume VOLUME --options OPTIONS optional arguments: -h, --help show this help message and exit --volume VOLUME Volume to set options for, specified as "volume@datastore". --options OPTIONS Options (specifically, access) to be set on the volume.

Could you file a issue to track this? If you don't want to fix this in current PR?

lipingxue · 2016-11-03T16:54:59Z

docs/user-guide/admin-cli.md


 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


This need to be updated. The current output looks like this:

[root@localhost:~] /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py ls Volume Datastore Created By VM Created Attached To VM Policy Capacity Used Filesystem Type Access Attach As --------------- ---------- ------------- ------------------------ -------------- ------ -------- ------- --------------- ---------- ---------------------- non-tenant-vol1 datastore1 photon4 Sun Aug 14 09:36:45 2016 detached N/A 100.00MB 0B ext4 read-write independent_persistent non-tenant-vol2 datastore1 photon4 Sun Aug 14 09:40:53 2016 detached N/A 100.00MB 0B ext4 read-write independent_persistent non-tenant-vol3 datastore1 photon4 Thu Aug 18 07:22:24 2016 detached N/A 100.00MB 13.00MB ext4 read-write independent_persistent

asomaiah

Included a brief write up on tenants

asomaiah · 2016-11-03T20:50:19Z

docs/features/tenancy.md

+## 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)


Made some changes to the write up.

pdhamdhere

LGTM.

Rather than documenting commands in sorted order, I would recommend to document workflow order.

pdhamdhere · 2016-11-03T21:08:22Z

docs/features/tenancy.md

+## 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)


@kerneltime datastore is vSphere basics and to use this feature you already need to be familiar with vSphere. I suggest to remove link to vSphere Storage. It seems out of place.

pdhamdhere · 2016-11-03T21:09:38Z

docs/user-guide/admin-cli.md

+```
+### Create
+
+Creates a new named tenant and optionally assigns VMs.


nit: assigns => assign?

cli cmd Creates and assigns..

pdhamdhere · 2016-11-03T21:10:43Z

docs/user-guide/admin-cli.md

+
+Sample:
+```
+[root@localhost:~]  /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant create --name DevAppX


Change DevAppX to TeamA or ProjectX?

pdhamdhere · 2016-11-03T21:11:43Z

docs/user-guide/admin-cli.md

+
+Sample:
+```
+[root@localhost:~]  /usr/lib/vmware/vmdkops/bin/vmdkops_admin.py tenant ls


Should this sample output reflect result of "tenant create" above?

Will try to keep the flow as much as possible. But then the commands need to follow a script rather than being independent.

pdhamdhere · 2016-11-03T21:12:40Z

docs/user-guide/admin-cli.md

+tenant create succeeded
+```
+
+The tenant to VM association can be done at create time.


I think you need to move line after sample, just before vm-assignment sample.

pdhamdhere · 2016-11-03T21:18:20Z

docs/user-guide/admin-cli.md

+### Access
+
+Change the access control for a tenant.
+This includes ability to control which datastores are accessible by a tenant and controlling what a


This includes ability to grant privileges & set resource consumption limits.

pdhamdhere · 2016-11-03T21:21:03Z

docs/user-guide/admin-cli.md

+  --datastore DATASTORE
+                        Datastore name
+```
+### List


This is covered above with create?

Comments inline for why changes were not made.

kerneltime · 2016-11-29T08:27:09Z

Fixes #663

vmwclabot added the cla-not-required label Nov 3, 2016

kerneltime force-pushed the tenancy-doc-n-fix.kerneltime branch from 6b76cd7 to 4759a30 Compare November 3, 2016 04:35

pdhamdhere reviewed Nov 3, 2016

View reviewed changes

kerneltime force-pushed the tenancy-doc-n-fix.kerneltime branch 2 times, most recently from 6028fc9 to 4950692 Compare November 3, 2016 05:06

pdhamdhere reviewed Nov 3, 2016

View reviewed changes

kerneltime force-pushed the tenancy-doc-n-fix.kerneltime branch from 4950692 to e7fbb8b Compare November 3, 2016 06:09

Ritesh Shukla added 2 commits November 2, 2016 23:29

Fix tenant folder creation on vSAN. Fixes #687

8cb79bd

Add documentation for tenancy

7aab639

kerneltime force-pushed the tenancy-doc-n-fix.kerneltime branch from e7fbb8b to 7aab639 Compare November 3, 2016 06:29

lipingxue previously requested changes Nov 3, 2016

View reviewed changes

Update tenancy.md

cc78eac

asomaiah reviewed Nov 3, 2016

View reviewed changes

pdhamdhere reviewed Nov 3, 2016

View reviewed changes

Update tenancy write up and minor fixes

984c32f

kerneltime force-pushed the tenancy-doc-n-fix.kerneltime branch from 32b029c to 984c32f Compare November 3, 2016 21:46

kerneltime merged commit 413126d into master Nov 3, 2016

kerneltime deleted the tenancy-doc-n-fix.kerneltime branch November 4, 2016 18:02

kerneltime mentioned this pull request Nov 29, 2016

Documentation: Admin CLI user guide needs updates and a tenancy page #663

Closed

		@@ -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.

Add documentation for tenancy. #689

Add documentation for tenancy. #689

Conversation

kerneltime commented Nov 3, 2016

kerneltime commented Nov 3, 2016

kerneltime commented Nov 3, 2016

pdhamdhere left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pdhamdhere left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kerneltime Nov 3, 2016 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kerneltime Nov 3, 2016 • edited

Choose a reason for hiding this comment

pdhamdhere commented Nov 3, 2016

kerneltime commented Nov 3, 2016

kerneltime commented Nov 3, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kerneltime Nov 3, 2016 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

asomaiah left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pdhamdhere left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kerneltime commented Nov 29, 2016

kerneltime Nov 3, 2016 •

edited

kerneltime Nov 3, 2016 •

edited

kerneltime Nov 3, 2016 •

edited