Project

General

Profile

Wiki »

Documentation

Be sure to check known bugs if anything goes wrong.

This documentation presents one way of configuring your Jenkins server. We can not cover all cases, but we will enrich this documentation as new solutions arise.
Please join, provide feedback and collaborate through the forums.

Beginning

You project is pre-configured to interact with our private cloud: your credentials1 are set up, and your slaves will run in an isolate environment (called tenant in the openstack jargon).

While in beta, HTTP access to newly created projects defaults to in2p3.fr (#5523). We can add domains or remove the filter completely if you prefer.

Create a slave template

Before creating jobs, you need to declare hosts on which they will run.

Don't run jobs on the master server ! This rule will be enforced by automation in the production version.

We won't actually create virtual hosts, but templates of hosts that will be spawned by Jenkins. Now that's the tricky part that we cannot automate on your behalf. Take a deep breath !

  1. Create a new template in Manage Jenkins > Configure System > Cloud Instance Templates > [Add]
    The name must contain only lowercase alphanumeric and dashes '-',
    for ex. ubuntu-1310-server-cloudimg-amd64. config_template.png config_template2.png
  2. Add labels that will be used to link jobs to this host template, for ex. ubuntu 13.10 x86_64
  3. Set the Number of Executors say to 2.
    This will be the maximum number of spawned slave instances, like a pool of slaves.
  4. Choose a hardware Id. regionOne/2 (m1.small) is fine.
    Note that you're limited in resources. You can check your quota in the cloud interface
  5. Choose an image. You can Specify an Image ID, and then the form must be regionOne/IMAGE_ID.
    But as images may be rebuilt, we recommend you Specify Image Name Regex instead,
    for ex: ^official-ubuntu-14\.04-x86_64$. note2 config_template2.png
    You can check the cloud interface (images and snapshots tab) for available images3.
  6. Click [Advanced...] config_template_advanced.png
  7. depending on the VM4, you may also want to fill in:
    • Init Script: platform-/project-dependant tasks that need to be fulfilled as root when the host VM is created. For ex: apt-get install -y git make
    • Admin Username: the name of the superadmin user.
      On Ubuntu this will most likely be ubuntu. On CentOS, cloud-user.
      Leave void if you don't know.
    • Leave Admin Password void in order to use the SSH key pair
  8. Check Allow Sudo
  9. Check Assign Floating IP
  10. In Key Pair Name, enter the name of the SSH key you created earlier
  11. Finally click [Save] at the bottom of the page

config_save.png

Slave/Hosts policy

We recommend that you spawn a fresh new host for each job. This has the following benefits:
  • no assumption on the build environment: stick to what any user would encounter after a fresh install
  • this saves overall resources: you probably don't need to have your hosts run 24/7

You might need to adapt the spawning process for that. For instance, you may want to install specific packages.
This is done in the Init Script section of the template configuration.

If you need to keep long-running slaves, please note that Slave VM's are not backed up !

Troubleshooting

Cannot run program "git"

Make sure git gets installed during the slave spawning, by completing the field Manage Jenkins > Configure System > Cloud Instance Templates > [Advanced] > Init Script with something like apt-get install -y git.

HTTP/1.1 413 Request Entity Too Large, Quota exceeded for

In some situations, Jenkins doesn't manage to release cloud resources (VMs, or floating IPs). If you run into quota issues, you need to delete acquired resources in the cloud interface (instances tab).

Create a job

Here are few things you should pay special attention to when creating a job :

  • in order to link your job with a VM template, you must check Restrict where this project can be run and fill in the field Label Expression with some keywords you entered in the template labels, for ex. ubuntu && "13.10"
  • if your project is source-controlled (it should!), configure the Source Code Management section.
    • in Advanced Project Options, set SCM checkout retry count to 3
    • if you're using git, you will have to install the Jenkins Git plugin and check you filled in the Init Script field (in the template definition) accordingly.
  • configure Build Triggers to automate the job. We recommend you do this in a second step, after having tested manually (Build Now).
  • check (or let checked) JClouds Single-Use Slave
  • [Add build step]
    • for Execute shell, keep in mind your code is checked out in $JOB_NAME
  • [Save]

You're now ready to test your setup by clickin Build Now.
This will launch a dedicated VM (be patient), apply your Init Script directives to it, instantiate a Jenkins slave on it, a finally run your job.
Once the job is run, the single-use slave is marked for removal (be patient).

Further configuration

Plugin updates

After a fresh install, if the list of available plugins is empty, do Manage Plugins > Advanced > Check now.

plugin_updates.png

JDK/Maven

Choose Install automatically.

Log into your slaves

SSH

Bounce through a CC login server. You'll need an account for that.

  • The target VM must have a public IP associated (which should be done automatically by JClouds if you set Assign Floating IP in the template configuration)
  • You must use the SSH Key created earlier
ssh ccage.in2p3.fr
ssh -i ~/.ssh/cif-1 ubuntu@134.158.246.163  # public IP assigned !

Note that, because of network routing, target VMs are not reachable from the internet, even if you setup secgroups properly.

Graphical console

The Cloud web interface provides a graphical console to an instance: select a running instance in the Instances tab. You'll need some browser setup to make it work: https://ccwiki.in2p3.fr/infrastructure:cloud:clis:video_console
like importing the Cloud's CA cert and your user's personal cert.

For the record, Firefox can not import certs in the PEM format. To convert them:

openssl pkcs12 -export -in cert.pem -inkey pk.pem -name "nova cif01" -out cert.p12

Notes and references

1 You can find your credentials in Jenkins > Configure > Cloud > Identity|Credential, where Identity is in the form username:tenant.

2 We haven't been able to make Specify OS Family and Version work yet (see #5557).

3 If none of the images in the catalog suits your needs, you can upload yours through the cloud interface (images and snapshots tab)

4 Here are some specificities we noted so far:

  • Scientific Linux (SL) images (like official-SL*)
    • These images are rebuilt frequently so the imageId will change !
    • Init Script =
      cp -p /etc/ssh/sshd_config /etc/ssh/sshd_config.bak && sed -e "s/^AllowGroups/#AllowGroups/" /etc/ssh/sshd_config.bak > /etc/ssh/sshd_config && service sshd reload
    • Admin Username = root
  • Ubuntu images
    • Admin Username = ubuntu