Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update README to provide pointers on how to set up ssh #36

Closed
wants to merge 4 commits into from
Closed

Update README to provide pointers on how to set up ssh #36

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6822cd4
Update README to include gotcha for setting up a Windows agent with SSH.
ssk2 Jun 23, 2016
fa6799a
Formatting fixes.
ssk2 Jun 23, 2016
822c711
Break out ssh configuration.
ssk2 Jun 23, 2016
6677880
Add note on using the classic Azure portal.
ssk2 Jun 23, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
102 changes: 42 additions & 60 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,10 @@ Jenkins Plugin to create Azure slaves.

Supports creating

1. Windows slave on Azure Cloud using SSH and JNLP
* For windows images to launch via SSH, the image needs to be preconfigured with ssh.
For preparing custom windows image, refer to [Azure documentation](http://azure.microsoft.com/en-us/documentation/articles/virtual-machines-capture-image-windows-server/)
2. Linux slaves on Azure Cloud using SSH
* For preparing custom linux image, refer to [Azure documentation]( http://azure.microsoft.com/en-us/documentation/articles/virtual-machines-linux-capture-image/)
1. Windows slave on Azure Cloud using SSH and JNLP:
* For preparing custom Windows image, refer to [Azure documentation](http://azure.microsoft.com/en-us/documentation/articles/virtual-machines-capture-image-windows-server/). (**Make sure** you're using the classic Azure Portal at [manage.windowsazure.com](https://manage.windowsazure.com/).)
2. Linux slaves on Azure Cloud using SSH:
* For preparing custom Linux image, refer to [Azure documentation]( http://azure.microsoft.com/en-us/documentation/articles/virtual-machines-linux-capture-image/).

## How to install the Azure Slave plugin
1. Within the Jenkins dashboard, click Manage Jenkins.
Expand All @@ -21,74 +20,54 @@ Supports creating

## Configure the plugin : Azure profile configuration
1. Within the Jenkins dashboard, click Manage Jenkins --> Configure System --> Scroll to the bottom of the page
and find the section with the dropdown "Add new cloud" --> click on it and select "Microsoft Azure"
2. Enter the subscription ID and the management certificate from your publish settings file.
and find the section with the dropdown "Add new cloud" --> click on it and select "Microsoft Azure".
2. Enter the subscription ID and the management certificate from your publish settings file.
If you don’t have a publish settings file, click on the help button and follow the directions to
download the publish settings file.
3. Click on “Verify configuration” to make sure that the profile configuration is done correctly.
4. Save and continue with the template configuration (See instructions below)
4. Save and continue with the template configuration (see instructions below).

## Configure the plugin : Template configuration.
1. Click on the "Add" option to add a template. A template is used to define an Azure slave configuration, like
its VM size, its region, or its retention time.
2. For the template name, provide a valid DNS name. Jenkins will create a cloud service with same name if one
does not already exists.
3. For the description, provide any remarks you wish about this template configuration. This field is not
used for slave provisioning.
4. For the label, provide any valid string. E.g. “windows” or “linux”. The label defined in a template can be
used during a job configuration.
1. Click on the "Add" option to add a template. A template is used to define an Azure slave configuration, like its VM size, its region, or its retention time.
2. For the template name, provide a valid DNS name. Jenkins will create a cloud service with same name if one does not already exists.
3. For the description, provide any remarks you wish about this template configuration. This field is not used for slave provisioning.
4. For the label, provide any valid string. E.g. “windows” or “linux”. The label defined in a template can beused during a job configuration.
5. Select the desired region from the combo box.
6. Select the desired VM size.
7. Specify the Azure Storage account name. Please note that the storage account and cloud service should use the
same region. Alternatively you can leave it blank to let Jenkins create a storage account automatically if needed.
8. Specify the retention time in minutes. This defines the number of minutes Jenkins can wait before automatically
deleting an idle slave. Specify 0 if you do not want idle slaves to be deleted automatically.
7. Specify the Azure Storage account name. Please note that the storage account and cloud service should use the same region. Alternatively you can leave it blank to let Jenkins create a storage account automatically if needed.
8. Specify the retention time in minutes. This defines the number of minutes Jenkins can wait before automatically deleting an idle slave. Specify 0 if you do not want idle slaves to be deleted automatically.
9. Select a usage option:
* If "Utilize this node as much as possible" is selected, then Jenkins may run any job on the slave as long as it
is available.
* If "Leave this node for tied jobs only" is selected, Jenkins will only build a project (or job) on this node
when that project specifically was tied to that node.This allows a slave to be reserved for certain kinds of jobs.
* If "Utilize this node as much as possible" is selected, then Jenkins may run any job on the slave as long as it is available.
* If "Leave this node for tied jobs only" is selected, Jenkins will only build a project (or job) on this node when that project specifically was tied to that node.This allows a slave to be reserved for certain kinds of jobs.
10. For the Image Family or ID , enter either an available image family name or a specific image ID.
* If you want to specify an image family, then just enter the first character with the proper case to see an
automatically generated list of available families. Jenkins will use the latest image within the selected family.
* If you want to specify a specific image ID, enter the name of the image. Note that since image ID’s are not auto
populated, the exact name needs to be entered manually. Also, if you are referring to an image using an image ID from
the public Azure image gallery rather than your own account, note that such public images with specific IDs are
available in Azure only for a limited time as they eventually get deprecated in favor of newer images in the same
family. For this reason, it is recommended that you use the image family to refer to public platform images, and image
ID’s for your own custom-prepared images.
11. For the launch method, select SSH or JNLP.
* If you want to specify an image family, then just enter the first character with the proper case to see an automatically generated list of available families. Jenkins will use the latest image within the selected family.
* If you want to specify a specific image ID, enter the name of the image. Note that since image ID’s are not auto populated, the exact name needs to be entered manually. Also, if you are referring to an image using an image ID from the public Azure image gallery rather than your own account, note that such public images with specific IDs are available in Azure only for a limited time as they eventually get deprecated in favor of newer images in the same family. For this reason, it is recommended that you use the image family to refer to public platform images, and image IDs for your own custom-prepared images.
11. For the launch method, select SSH or JNLP:
* Linux slaves can be launched using SSH only.
* Windows slaves can be launched using SSH or JNLP. For Windows slaves, if the launch method is SSH then
image needs to be custom-prepared with an SSH server pre-installed.<br>

* Windows slaves can be launched using SSH or JNLP. For Windows slaves, if the launch method is SSH then the image needs to be custom-prepared with an SSH server pre-installed.<br>

When using the JNLP launch option, ensure the following:
* Jenkins URL (Manage Jenkins --> configure system --> Jenkins Location)
* The URL needs to be reachable by the Azure slave, so make sure to configure any relevant firewall rules accordingly.
* Jenkins URL (Manage Jenkins --> configure system --> Jenkins Location).
* The URL needs to be reachable by the Azure slave, so make sure to configure any relevant firewall rules accordingly.
* TCP port for JNLP slave agents (Manage Jenkins --> configure global security --> Enable security --> TCP port for JNLP slaves).
* The TCP port needs to be reachable from the Azure slave launched using JNLP. It is recommended to use a fixed port so that any necessary firewall exceptions can be made.
* The TCP port needs to be reachable from the Azure slave launched using JNLP. It is recommended to use a fixed port so that any necessary firewall exceptions can be made.

If the Jenkins master is running on Azure, then open an endpoint for "TCP port for JNLP slave agents" and, in case of
Windows, add the necessary firewall rules inside virtual machine (Run --> firewall.cpl).
12. For the Init script, provide a script to install at least a Java runtime if the image does not have Java
pre-installed.
If the Jenkins master is running on Azure, then open an endpoint for "TCP port for JNLP slave agents" and, in case of Windows, add the necessary firewall rules inside virtual machine (Run --> firewall.cpl).
12. For the Init script, provide a script to install at least a Java runtime if the image does not have Java pre-installed.

For the JNLP launch method, the init script must be in PowerShell.
If the init script is expected to take a long time to execute, it is recommended to prepare custom images with the necessary software pre-installed.<br>
If the init script is expected to take a long time to execute, it is recommended to prepare custom images with the necessary software pre-installed.<br>

For more details about how to prepare custom images, refer to the below links:
* [Capture Windows Image](http://azure.microsoft.com/en-us/documentation/articles/virtual-machines-capture-image-windows-server/)
* [Capture Linux Image](http://azure.microsoft.com/en-us/documentation/articles/virtual-machines-linux-capture-image/)

13. Specify a user name and a password as per the rules explained in the help text.
14. Make sure to validate the template configuration by clicking on the link “Verify Template”. This will connect
to your Azure account to verify the correctness of the supplied information.
14. Make sure to validate the template configuration by clicking on the link “Verify Template”. This will connect to your Azure account to verify the correctness of the supplied information.

## Template Configuration for Ubuntu images.
1. Configure an Azure profile and Template as per the above instructions.
2. If the init script is expected to take a long time to complete, it is recommended to use a custom-prepared Ubuntu
image that has the required software pre-installed, including a Java runtime
2. If the init script is expected to take a long time to complete, it is recommended to use a custom-prepared Ubuntu image that has the required software pre-installed, including a Java runtime.
3. For platform images, you may specify an Init script as below to install Java, Git and Ant:

```
Expand All @@ -107,20 +86,27 @@ Supports creating
sudo apt-get install -y ant
```

## Template configuration for Windows images with launch method JNLP.
## Template configuration for Windows images with launch method JNLP
1. Make sure to follow the instructions specified above for JNLP.
2. If the Jenkins master does not have a security configuration, leave the Init script blank for the default
script to execute on the slave.
3. If the Jenkins master has a security configuration, then refer to the script at
https://gist.github.com/snallami/5aa9ea2c57836a3b3635 and modify the script with the proper
Jenkins credentials.
2. If the Jenkins master does not have a security configuration, leave the Init script blank for the default script to execute on the slave.
3. If the Jenkins master has a security configuration, then refer to the script at https://gist.github.com/snallami/5aa9ea2c57836a3b3635 and modify the script with the proper Jenkins credentials.

At a minimum, the script needs to be modified with the Jenkins user name and API token.
To get the API token, click on your username --> configure --> show api token<br>

The below statement in the script needs to be modified:
$credentails="username:apitoken"


## Template configuration for Windows images with launch method SSH
For Windows images to launch via SSH, the image needs to be preconfigured with ssh and a JDK.

1. [Win32 OpenSSH](https://github.com/PowerShell/Win32-OpenSSH) works well, follow [their install instructions](https://github.com/PowerShell/Win32-OpenSSH/wiki/Install-Win32-OpenSSH).
2. Make sure to update the `sftp` subsystem line to point to the correct sftp-server.exe (this is mandatory for Jenkins to launch):

```
Subsystem sftp C:\Program Files\OpenSSH-Win64\sftp-server.exe
```

## Create a Jenkins job that runs on a Linux slave node on Azure
1. In the Jenkins dashboard, click New Item/Job.
2. Enter a name for the task/Job you are creating.
Expand All @@ -147,10 +133,6 @@ Supports creating
ant
````
8. Save Job and click on Build now.
9. Jenkins will create a slave node on Azure cloud using the template created in the previous section and
execute the script you specified in the build step for this task.
9. Jenkins will create a slave node on Azure cloud using the template created in the previous section and execute the script you specified in the build step for this task.
10. Logs are available @ Manage Jenkins --> System logs --> All Jenkins logs.
11. Once the node is provisined in Azure, which typically takes about 5 to 7 minutes, node gets added to Jenkins.