Refreshing vDVS installation user guide for 0.13 release #1124

shuklanirdesh82 · 2017-03-31T00:53:45Z

Refreshing vDVS installation user guide for 0.13 release

Adding reference of bintray to down load VIB
managed plugin will be pulled from docker store
Adding command reference to deal with managed plugin

tusharnt · 2017-03-31T01:17:45Z

docs/user-guide/install.md


 # Install on VM

-We currently package the service as a RPM and Deb package. This is to be able to start the service before Docker engine starts. We will also support Docker plugin framework once it is ready.
+vDVS 0.13 comes with managed plugin support using Docker plugin framework and please note DEB/RPM packages will be deprecated going forward and will not be available.


Can be split into two separate sentences.
Starting 0.13 release, vDVS supports a managed plugin that is available for download from Docker store. DEB/RPM packages will be deprecated.

tusharnt · 2017-03-31T01:18:53Z

docs/user-guide/install.md

+**For Docker 1.13 and above**, install managed plugin from [Docker store](https://store.docker.com/plugins/e15dc9d5-e20e-4fb8-8876-9615e6e6e852?tab=description).
+```
+docker plugin install --grant-all-permissions --alias vsphere vmware/docker-volume-vsphere:latest
+```


This can be removed since we explicitly cover installation for managed plugin.

We need to keep it here as this is installation user guide.

We have exact same thing on line 36 under installation section. Why do we need to repeat it twice?

make sense ... Thanks for elaborating.

tusharnt · 2017-03-31T01:23:59Z

docs/user-guide/install.md

+docker plugin install --grant-all-permissions --alias vsphere vmware/docker-volume-vsphere:latest
+```
+
+**Using vDVS managed plugin**


Using vDVS managed plugin -> vDVS managed plugin
Prerequisite : Docker 1.13 and above

Using vDVS managed plugin -> vDVS managed plugin
changed it to vDVS managed plugin life cycle; basically plan is to give some commands handy

Prerequisite : Docker 1.13 and above
It is mentioned at L31 so avoid repetition

Here's the structure I am proposing -
vDVS managed plugin
Prerequisite : Docker 1.13 and above
Plugin lifecycle
-Installation
-Enable/Disable
-Removal

vDVS RPM/DEB based installation
Prerequisite : Docker 1.12 and earlier
Deprecated starting 0.13 release.

tusharnt · 2017-03-31T01:29:28Z

docs/user-guide/install.md

+vsphere
+~# docker plugin ls
+ID                  NAME                DESCRIPTION                           ENABLED
+de30e65cda7b        vsphere:latest      VMWare vSphere Docker Volume plugin   true


Content can be made more concise as follows -

After installation, the plugin needs to be enabled explicitly.
~# docker plugin ls
ID NAME DESCRIPTION ENABLED
de30e65cda7b vsphere:latest VMWare vSphere Docker Volume plugin false
~# docker plugin enable vsphere
vsphere
~# docker plugin ls
ID NAME DESCRIPTION ENABLED
de30e65cda7b vsphere:latest VMWare vSphere Docker Volume plugin true

After installation, the plugin needs to be enabled explicitly.

It's not always true, there is possibility that plugin is enabled already right after installation.

Anyway, inline text is updated in the latest diff.

tusharnt · 2017-03-31T01:30:36Z

docs/user-guide/install.md

+
+**Using vDVS managed plugin**
+
+* **Install vDVS plugin**


Install vDVS plugin -> Installation
No need to include "vDVS plugin" in each header.

Updated to Installation L38 in latest diff

Removed "vDVS plugin" where ever it was referenced

tusharnt · 2017-03-31T01:32:47Z

docs/user-guide/install.md

+ID                  NAME                DESCRIPTION         ENABLED
+```
+
+**For Docker 1.12 and earlier**, use DEB or RPM package.


RPM/DEB based installation.
Deprecated starting 0.13 release.
Prerequisite - Docker 1.12 or earlier.

This is time being block and will be removed by next release so kept it as it is.

Let me know what you think.

tusharnt · 2017-03-31T01:33:12Z

docs/user-guide/install.md

+de30e65cda7b        vsphere:latest      VMWare vSphere Docker Volume plugin   true
+```
+
+* **Disable vDVS plugin** Using `docker plugin disable <plugin_name>`


Disable vDVS plugin Using docker plugin disable <plugin_name> -> Disabling the plugin

tusharnt · 2017-03-31T01:33:37Z

docs/user-guide/install.md

+de30e65cda7b        vsphere:latest      VMWare vSphere Docker Volume plugin   false
+```
+
+* **Remove vDVS plugin** Using `docker plugin rm <plugin_name>`


Remove vDVS plugin Using docker plugin rm <plugin_name> -> Removing the plugin

tusharnt

Some suggestions to make the content more concise.

tusharnt · 2017-03-31T03:37:54Z

docs/user-guide/install.md

+
+Let's verify the installed plugin using `docker plugin ls` command. In following example, you can see that vDVS plugin is not enabled yet.
+
+**Note**: After installation, the plugin needs to be enabled explicitely.


Is this accurate? If the plugin is enabled by default then we can skip "enabling/disabling plugin" section.

in all my work install was auto-enabling the plugin

I will wait for 0.13 vDVS plugin, after pushing to vmware (docker hub) with0.13 and latest tag; I will perform the steps manually and update accordingly.

Plugin was always enabled in my case too. Never had to explicitly enable it.

steps are updated after pushing 0.13/latest plugin to vmware/docker-volume-vsphere

tusharnt · 2017-03-31T03:39:14Z

docs/user-guide/install.md

+~# docker plugin disable vsphere
+vsphere
+~# docker plugin ls
+ID                  NAME                DESCRIPTION                           ENABLED


This section might not be needed if plugin is enabled by default. We can simply say that refer to Docker documentation for operations on plugins - https://docs.docker.com/engine/extend/

removed, thanks!

tusharnt · 2017-03-31T03:39:32Z

docs/user-guide/install.md

+
+* **Removing plugin**
+
+Using `docker plugin rm <plugin_name>`


Line 78 : Redundant and can be removed.

can you clarify, why it is redundant?

I would keep it just in case so that all commands come handy in one place.

@pdhamdhere : Here's what I am suggesting.
Current format -
Using Removing plugin
Using docker plugin rm <plugin_name>
~# docker plugin rm vsphere
vsphere

which can be changed to

Removing plugin
~# docker plugin rm vsphere
vsphere

I am not asking to remove the output of the command.

tusharnt

Some more comments.

msterin

it feels the instructions were not tested. Can we make sure we do test the steps before asking customers to follow ?

msterin · 2017-03-31T03:41:29Z

docs/user-guide/install.md

+
+* **Installation**
+```
+~# docker plugin install --grant-all-permissions --alias vsphere vmware/docker-volume-vsphere:latest


I assume we'll put the 'latest' tag on it later ? Without the 'latest' tag it wont install

Yeah that's correct. The idea behind this PR was flashing out install user guide for early review.

msterin · 2017-03-31T03:42:58Z

docs/user-guide/install.md

+
+Let's verify the installed plugin using `docker plugin ls` command. In following example, you can see that vDVS plugin is not enabled yet.
+
+**Note**: After installation, the plugin needs to be enabled explicitely.


in all my work install was auto-enabling the plugin

pdhamdhere · 2017-03-31T04:12:22Z

docs/user-guide/install.md


+vDVS 0.13 comes with managed plugin support using Docker plugin framework.


You can remove this line since it will be redundant after tomorrow.

pdhamdhere · 2017-03-31T04:12:37Z

docs/user-guide/install.md


+vDVS 0.13 comes with managed plugin support using Docker plugin framework.
+
+**vDVS managed plugin life cycle**


This too can be skipped

pdhamdhere · 2017-03-31T04:14:00Z

docs/user-guide/install.md


 [VIB](http://blogs.vmware.com/vsphere/2011/09/whats-in-a-vib.html) and [Offline Depot](https://pubs.vmware.com/vsphere-60/index.jsp#com.vmware.vsphere.install.doc/GUID-29491174-238E-4708-A78F-8FE95156D6A3.html?resultof=%2522%256f%2566%2566%256c%2569%256e%2565%2522%2520%2522%256f%2566%2566%256c%2569%256e%2522%2520%2522%2564%2565%2570%256f%2574%2522%2520) are the packages built to install the backend for the service on ESX. The backend can be installed using esxcli or vmware tools such as [VUM](http://pubs.vmware.com/vsphere-60/topic/com.vmware.ICbase/PDF/vsphere-update-manager-601-install-administration-guide.pdf)

-Here is a demo show casing esxcli
+Log into ESXi host and download the [latest release](https://bintray.com/vmware/vDVS/VIB/_latestVersion) [![VIB_Download](https://api.bintray.com/packages/vmware/vDVS/VIB/images/download.svg)](https://bintray.com/vmware/vDVS/VIB/_latestVersion) of vDVS driver VIB on ESXi and initiate the install by specifying the full path to the VIB.


Remove one of the badge either from L9 or L13

L13 is removed.

pdhamdhere · 2017-03-31T04:16:09Z

docs/user-guide/install.md

+
+Let's verify the installed plugin using `docker plugin ls` command. In following example, you can see that vDVS plugin is not enabled yet.
+
+**Note**: After installation, the plugin needs to be enabled explicitely.


Plugin was always enabled in my case too. Never had to explicitly enable it.

pdhamdhere · 2017-03-31T04:19:15Z

docs/user-guide/install.md

+de30e65cda7b        vsphere:latest      VMWare vSphere Docker Volume plugin   true
+```
+
+Now plugin is enabled and ready to use (The `docker volume` command behaves as before and driver name should be what we passed as `--alias` )


pdhamdhere · 2017-03-31T04:20:02Z

docs/user-guide/install.md

+
+* **Removing plugin**
+
+Using `docker plugin rm <plugin_name>`


I would keep it just in case so that all commands come handy in one place.

pdhamdhere · 2017-03-31T04:20:31Z

docs/user-guide/install.md

+
+**vDVS DEB/RPM based installation**
+
+**Note** DEB/RPM packages will be deprecated going forward and will not be available. It is recommeded upgrading Docker 1.13/17.03 and above and install vDVS managed plugin.


You can drop "it is recommeded upgrading Docker 1.13/17.03 and above and install vDVS managed plugin."

pdhamdhere · 2017-03-31T04:21:39Z

docs/user-guide/install.md

+* **Installation**
+```
+~# docker plugin install --grant-all-permissions --alias vsphere vmware/docker-volume-vsphere:latest
+0.12: Pulling from vmware/docker-volume-vsphere


Dont forget to update output after you run these commands with 0.13 plugin.

done!

~# docker plugin install --grant-all-permissions --alias vsphere vmware/docker-volume-vsphere:latest latest: Pulling from vmware/docker-volume-vsphere```

pdhamdhere · 2017-03-31T04:23:19Z

docs/user-guide/install.md

+```
+- sudo dpkg -i <name>.deb # Ubuntu or deb based distros
+- sudo rpm -ivh <name>.rpm # Photon or rpm based distros
+```
 Here is a demo showcasing the install in a Photon OS VM.


Remove this demo too.

tusharnt

LGTM

govint · 2017-03-31T06:18:21Z

docs/user-guide/install.md

+   VIBs Installed: VMWare_bootbank_esx-vmdkops-service_0.12.ccfc38f-0.0.1
+   VIBs Removed:
+   VIBs Skipped:
+```


Do we need an ugrade section also? If not then could mention so and also say how an upgrade can be done.

Will all volumes be available post upgrade? Could clarify on that.

Good point! Instead of creating new section, shouldn't upgrade instruction goes to separate user guide. This is just an installation guide.

What do you think?

#1169 addresses this. Thanks @govint !

Will all volumes be available post upgrade? Could clarify on that

Yeah, all volumes are available post upgrade.

govint · 2017-03-31T06:20:59Z

docs/user-guide/install.md

+~# docker plugin ls
+ID                  NAME                DESCRIPTION                           ENABLED
+831fd45343af        vsphere:latest      VMWare vSphere Docker Volume plugin   true
+```


Same comment as above have a new section for upgrade from package user (all current users) to plugin.

And for plugin users how they can upgrade to a newer version. At least mention if any steps are needed for upgrade.

Will all volumes be available post upgrade?

#1169 addresses this. Thanks @govint !

And for plugin users how they can upgrade to a newer version. At least mention if any steps are needed for upgrade.

0.13 is the first release for plugin users, it is better to have such information post 0.14 release.

govint · 2017-03-31T06:34:58Z

docs/user-guide/install.md

+```
+- sudo dpkg -i <name>.deb # Ubuntu or deb based distros
+- sudo rpm -ivh <name>.rpm # Photon or rpm based distros
+```


Could add a note that all current containers that are using vsphere volumes will continue to be able to run and that there is no impact (yes).

Also, one more good/must have is that Docker/containerd doesn't have to be restarted to install the plugin - meaning all containers stop and start (unless live-restore is in use).

Could also verify and mention behavior with swarm mode in use.

govint

Should add notes on upgrade scenarios, availability of existing volumes to the sections.

shuklanirdesh82 · 2017-03-31T07:16:15Z

Should add notes on upgrade scenarios, availability of existing volumes to the sections.

Good point!
Just for the reference, separate PR will be generate to address this issue.

shuklanirdesh82 requested review from tusharnt, asomaiah and pdhamdhere March 31, 2017 00:53

vmwclabot added the cla-not-required label Mar 31, 2017

tusharnt reviewed Mar 31, 2017

View reviewed changes

tusharnt suggested changes Mar 31, 2017

View reviewed changes

shuklanirdesh82 force-pushed the updateInstallUserGuide.shuklanirdesh82 branch 7 times, most recently from 4356793 to 92fb4ab Compare March 31, 2017 03:21

tusharnt reviewed Mar 31, 2017

View reviewed changes

tusharnt suggested changes Mar 31, 2017

View reviewed changes

msterin reviewed Mar 31, 2017

View reviewed changes

pdhamdhere reviewed Mar 31, 2017

View reviewed changes

Refreshing vDVS installation user guide

2e6c741

shuklanirdesh82 force-pushed the updateInstallUserGuide.shuklanirdesh82 branch from 92fb4ab to 2e6c741 Compare March 31, 2017 05:50

tusharnt approved these changes Mar 31, 2017

View reviewed changes

govint reviewed Mar 31, 2017

View reviewed changes

govint approved these changes Mar 31, 2017

View reviewed changes

shuklanirdesh82 merged commit 15d313a into vmware-archive:master Mar 31, 2017

shuklanirdesh82 deleted the updateInstallUserGuide.shuklanirdesh82 branch March 31, 2017 07:16


		Let's verify the installed plugin using `docker plugin ls` command. In following example, you can see that vDVS plugin is not enabled yet.

		Note: After installation, the plugin needs to be enabled explicitely.


		vDVS 0.13 comes with managed plugin support using Docker plugin framework.


		vDVS 0.13 comes with managed plugin support using Docker plugin framework.

		vDVS managed plugin life cycle


		vDVS DEB/RPM based installation

		Note DEB/RPM packages will be deprecated going forward and will not be available. It is recommeded upgrading Docker 1.13/17.03 and above and install vDVS managed plugin.

Refreshing vDVS installation user guide for 0.13 release #1124

Refreshing vDVS installation user guide for 0.13 release #1124

Conversation

shuklanirdesh82 commented Mar 31, 2017

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

tusharnt Mar 31, 2017 • edited Loading

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

shuklanirdesh82 Mar 31, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tusharnt Mar 31, 2017 • edited Loading

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

tusharnt left a comment • edited Loading

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

tusharnt Mar 31, 2017 • edited Loading

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

tusharnt left a comment

Choose a reason for hiding this comment

msterin 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

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

tusharnt 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

govint left a comment

Choose a reason for hiding this comment

shuklanirdesh82 commented Mar 31, 2017

tusharnt Mar 31, 2017 •

edited

Loading

shuklanirdesh82 Mar 31, 2017 •

edited

Loading

tusharnt Mar 31, 2017 •

edited

Loading

tusharnt left a comment •

edited

Loading

tusharnt Mar 31, 2017 •

edited

Loading