Improve documentation

docs/configure-with-groovy.md

@@ -0,0 +1,107 @@
+# Configure the plugin with Groovy
+
+It is recommended that you use the `configuration-as-code` plugin for automating the plugin configuration. If you can't do that for some reason then you can use groovy script
+
+Here is a sample groovy script that creates a new Azure cloud and VM template. You can run it in Manage Jenkins -> Script Console.
+
+## Built-in image
+
+```groovy
+//Configure cloud with built-in image
+import com.microsoft.azure.vmagent.builders.*
+def myCloud = new AzureVMCloudBuilder()
+.withCloudName("myAzure")
+.withAzureCredentialsId("<your azure credential ID>")
+.withNewResourceGroupName("<your Resource Group Name>")
+.addNewTemplate()
+    .withName("ubuntu")
+    .withLabels("ubuntu")
+    .withLocation("East US")
+    .withVirtualMachineSize("Standard_DS2_v2")
+    .withNewStorageAccount("<your Storage Account Name>")
+    .addNewBuiltInImage()
+        .withBuiltInImageName("Ubuntu 16.14 LTS")
+        .withInstallGit(true)
+        .withInstallMaven(true)
+        .withInstallDocker(true)
+        .withInstallQemu(true)
+    .endBuiltInImage()
+    .withAdminCredential("<your admin credential ID>")
+.endTemplate()
+.build()
+Jenkins.getInstance().clouds.add(myCloud)
+```
+
+## Advanced image
+
+```groovy
+//Configure cloud with mutli-template of advanced images
+import com.microsoft.azure.vmagent.builders.*
+def firstTemplate = new AzureVMTemplateBuilder()
+.withName("first-template")
+.withLabels("ubuntu")
+.withLocation("East US")
+.withVirtualMachineSize("Standard_DS2_v2")
+.withNewStorageAccount("<your Storage Account Name>")
+.addNewAdvancedImage()
+    .withReferenceImage("Canonical", "UbuntuServer", "16.04-LTS", "latest")
+    .withInitScript("sudo add-apt-repository ppa:openjdk-r/ppa -y \n" +
+                    "sudo apt-get -y update \n" +
+                    "sudo apt-get install openjdk-8-jre openjdk-8-jre-headless openjdk-8-jdk -y")
+.endAdvancedImage()
+.withAdminCredential("<your admin credential ID>")
+.build()
+def myCloud = new AzureVMCloudBuilder()
+.withCloudName("myAzure")
+.withAzureCredentialsId("<your azure credential ID>")
+.withNewResourceGroupName("<your Resource Group Name>")
+.addToTemplates(firstTemplate)
+.addNewTemplate()
+    .withName("second-template")
+    .withLabels("windows")
+    .withLocation("Southeast Asia")
+    .withVirtualMachineSize("Standard_DS2_v2")
+    .withNewStorageAccount("<your Storage Account Name>")
+    .addNewAdvancedImage()
+        .withReferenceImage("MicrosoftWindowsServer", "WindowsServer", "2016-Datacenter", "latest")
+    .endAdvancedImage()
+    .withAdminCredential("<your admin credential ID>")
+.endTemplate()
+.build()
+Jenkins.getInstance().clouds.add(myCloud)
+```
+
+## Inherit existing template
+
+```groovy
+//inherit existing template
+import com.microsoft.azure.vmagent.builders.*
+import com.microsoft.azure.vmagent.*
+AzureVMAgentTemplate baseTemplate = new AzureVMTemplateBuilder()
+.withLocation("Southeast Asia")
+.withVirtualMachineSize("Standard_DS2_v2")
+.withStorageAccountType("Premium_LRS")
+.withNewStorageAccount("<your Storage Account Name>")
+    .addNewAdvancedImage()
+         .withReferenceImage("Canonical", "UbuntuServer", "16.04-LTS", "latest")
+    .endAdvancedImage()
+    .withAdminCredential("<your admin credential ID>")
+.build()
+def myCloud = new AzureVMCloudBuilder()
+.withCloudName("myAzure")
+.withAzureCredentialsId("<your azure credential ID>")
+.withNewResourceGroupName("<your Resource Group Name>")
+.addNewTemplateLike(baseTemplate)
+    .withName("inherit")
+    .withLabels("inherit")
+    .addNewAdvancedImageLike(baseTemplate.getAdvancedImageInside())
+        .withInitScript("sudo add-apt-repository ppa:openjdk-r/ppa -y \n" +
+                        "sudo apt-get -y update \n" +
+                        "sudo apt-get install openjdk-8-jre openjdk-8-jre-headless openjdk-8-jdk -y")
+    .endAdvancedImage()
+.endTemplate()
+.build()
+Jenkins.getInstance().clouds.add(myCloud)
+```
+
+This sample only contains a few arguments of builder, please find all the arguments in folder [builders](src/main/java/com/microsoft/azure/vmagent/builders).

docs/init-scripts/linux-inbound-agent.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 
-JENKINS_URL=$1
-AGENT_NAME=$2
+export JENKINS_URL=$1
+export AGENT_NAME=$2
 SECRET=$3
 
 # Update if your user is called something different
@@ -28,7 +28,6 @@ chown $USER:$USER /home/$USER/inbound-agent
   echo "${SECRET}" > agent-secret
 
   curl -O https://raw.githubusercontent.com/jenkinsci/azure-vm-agents-plugin/HEAD/docs/init-scripts/systemd-unit.service
-  export AGENT_URL="$JENKINS_URL/computer/$AGENT_NAME/jenkins-agent.jnlp"
   envsubst < systemd-unit.service > /etc/systemd/system/jenkins-agent.service
   rm -f systemd-unit.service
 

docs/init-scripts/systemd-unit.service

@@ -4,7 +4,7 @@ Wants=network.target
 After=network.target
 
 [Service]
-ExecStart=/usr/bin/java -jar /home/${USER}/inbound-agent/agent.jar -jnlpUrl ${AGENT_URL} -secret @/home/${USER}/inbound-agent/agent-secret -workDir /home/${USER}/inbound-agent
+ExecStart=/usr/bin/java -jar /home/${USER}/inbound-agent/agent.jar -url ${JENKINS_URL} -secret @/home/${USER}/inbound-agent/agent-secret -name ${AGENT_NAME} -webSocket -workDir /home/${USER}/inbound-agent
 User=${USER}
 WorkingDirectory=/home/${USER}/inbound-agent
 Restart=on-failure

docs/init-scripts/windows-inbound-agent.ps1

@@ -48,7 +48,7 @@ $wc.DownloadFile("https://raw.githubusercontent.com/Azure/jenkins/master/agents_
 # Prepare config
 Write-Output "Executing agent process "
 $configExec = "java"
-$configArgs = "-jnlpUrl `"${jenkinsserverurl}/computer/${vmname}/jenkins-agent.jnlp`" -workDir C:\jenkins\workDir"
+$configArgs = "-url `"${jenkinsserverurl}`" -workDir C:\jenkins\workDir -webSocket -name `"${vmname}`""
 if ($secret) {
     $configArgs += " -secret `"$secret`""
 }

src/main/resources/com/microsoft/azure/vmagent/AzureVMAgentTemplate/help-launcher.html

@@ -1,11 +1,24 @@
 <div>
-    For Windows agents, if you want to use SSH then the image needs to be custom-prepared with an SSH server preinstalled.<br><br>
+    <p>Controls how Jenkins starts this agent.</p>
+    <p><strong>Launch agents via SSH</strong></p>
+    <p>Required on Windows only: Ensure either your Virtual Machine image includes SSH pre-installed or you select the
+        Pre-Install SSH in Windows Agent option below</p>
 
-    When using connecting to the controller, ensure the following:<br>
-    1)  Jenkins URL (Manage Jenkins --> System --> Jenkins Location) <br>
-        &nbsp;&nbsp;&nbsp;&nbsp;This URL needs to be reachable by the agent, so make sure to configure the firewall rules accordingly. <br>
-    2)  TCP port for JNLP agent agents (Manage Jenkins --> Security --> TCP port for inbound agents). <br><br>
+    <p><strong>Launch agents by connecting it to the controller</strong></p>
+    <p>
+        Allows an agent to be connected to the Jenkins controller whenever it is ready.
+        The agent machine will establish a connection to the Jenkins controller from the agenrt.
+        This means that the agent does not need to be reachable from the controller; the agent just needs to be able to
+        reach the controller.
+    </p>
 
-        &nbsp;&nbsp;&nbsp;&nbsp;This port needs to be reachable from the agent. It is recommended to use a fixed port
-        so that the necessary firewall exceptions can be specified. <br><br>
+    <p>
+        The created Virtual Machine needs to automatically connect to Jenkins on startup. This can be achieved by
+        installing the Jenkins agent as a service using the <em>Initialization script</em> in the <em>VM first startup configuration</em>.
+        The following scripts are provided to help you with this:
+    </p>
+    <ul>
+        <li><a href="https://github.com/jenkinsci/azure-vm-agents-plugin/blob/master/docs/init-scripts/linux-inbound-agent.sh">Linux</a>
+        <li><a href="https://github.com/jenkinsci/azure-vm-agents-plugin/blob/master/docs/init-scripts/windows-inbound-agent.ps1">Windows</a>
+    </ul>
 </div>

src/main/webapp/help-preInstallSsh.html

@@ -1,4 +1,3 @@
 <div>
-    Pre-install SSH in Windows Agent.<br>
-    Please always check when using Windows Agent and SSH except for using a custom vhd with installed SSH.<br>
+    Installs SSH for you on Windows which is required when using 'Launch agents via SSH', unless you are using an image that comes with SSH.
 </div>