Universal Worker

Note

This feature is a Beta release, if you wish to use Universal Workers please contact support and we’ll get you set up.

Universal Workers allow you to run a simple software agent that connects to Solano CI and and enables you to run Solano CI workloads on your own machines.

Some potential uses for Universal Workers:
  • custom hardware (ARM & x86 supported)
  • testing licensed software
  • testing with full control over execution environment
  • test source code that can’t leave an internal network

Contents of this guide:

Execution Environment

Solano Universal Workers will clone your repository using the ssh key that is assigned to your account (you can find the public key in your organization page under “Worker SSH Identity”). The repository will be cloned to /usr/local/repos. Universal Workers run inside a containerized environment on a layer on top of the base filesystem; any changes made to the filesystem during the build will be cleared after each run.

Universal Worker solano.yml

Solano CI uses a solano.yml file that allows users to control various aspects of their execution environment. As Universal Workers gives a user total control over their environment, the solano.yml file used with Universal Workers doesn’t need to support all of the features that the normal solano.yml does.

The Universal Worker solano.yml supports the following keys:

  • script - A script to run as your tests.
  • environment - a list of key: value pairs that will be exported as Environment variables when your build runs
  • timeout - How long your build will run (in seconds) before timing out (default is 1200s)
  • profile & plan - Build Profiles and Plans.

Here is an example configuration file that will execute the run_tests.sh script that is located in the repo that is being cloned.

plan:
 - default
profiles:
  default:
    script: "/usr/local/repos/run_tests.sh"
    environment:
      'FOOBARVAR': 'foobarval'
      'PATH': '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin'
    timeout: 9000

The uw-docker-example repository demonstrates running Docker builds on Solano CI Universal workers.

Setup on Amazon EC2

AWS EC2 users can easily get set up with Universal Workers by using the Solano CI Universal Worker AMI.

The current AMI is: ami-9c17938b

Note

If you want to use your own base AMI and install the universal worker software into it, see Setup in any hosting environment.

Start a new EC2 instance using this AMI. The AMI comes preconfigured with the proper EBS volumes attached. Ensure that the new instance is in a security group that authorizes incoming traffic on ports 443 and 80. Contact support for assistance with more restrictive network configurations.

Once the instance is started, ssh to it and continue with the rest of the instructions on Connecting a Universal Worker and Running Builds.

Setup on Azure

Azure users can easily get set up with Universal Workers by using the Solano CI VM image listed in the Azure marketplace. Azure docs

Search for “Solano CI Private Beta” in the Azure Virtual Machine Store.

../../_images/uw-azure_store.png

Configure the VM settings and make sure to attach a Network Security Group that has port 443, and port 80 open. For more information on setting up Network Security Groups in Azure, see the Azure docs.

../../_images/uw-net_sec_group.png

Go through the rest of the settings and buy the virtual machine. Continue with the rest of the instructions on Connecting a Universal Worker and Running Builds.

Setup in any hosting environment

  1. Starting from a standard Ubuntu 14.04 server or VM:

    1. Ensure that the server or VM has a second data disk in addition to the root volume that has at least 20GB of space. This device will be used as the scratch space for build containers. The second disk can be configured to use ephemeral storage (deleted on VM termination) as your hosting environment supports, e.g. EC2 Ephemeral Volumes or GCP local-scratch disks.
    2. Ensure that the server or VM is reachable on port 443 or 80. Contact support for assistance with more restrictive network configurations.
  2. On the new server, install the linked ovf-env.xml into /var/lib/waagent/ovf-env.xml. This is a temporary workaround for a known bug in the current released software, and it will be removed as a requirement in the next release.

  3. Install the universal-worker software:

    wget https://s3.amazonaws.com/solano-labs/universal-worker/solano-agent-20160603.2.tgz
    tar zxvf solano-agent-20160603.2.tgz
    cd solano-agent
    sudo ./install.sh
    
  4. Continue by following the rest of the instructions on Connecting a Universal Worker and Running Builds.

Connecting a Universal Worker and Running Builds

Visit your Universal Worker organization settings page by clicking the organization name on the top right of your Solano CI Dashboard.

../../_images/uw-find_org_page.png

Select the ‘Universal Workers’ settings page in the right sidebar. This is the place where you will manage your Universal Workers. Notice the worker registration command at the top of the page. You will need to run this command as root on each of your Universal Workers in order to register it with Solano CI and make it available for running workloads. Open a shell on the Universal Worker and run the command you see on this page as root.

../../_images/uw-org_settings.png

After running the command, check to make sure your worker is successfully registered on the Universal Worker settings page.

../../_images/uw-recently_started.png

Note

You can use the same command to register multiple workers. This means you can run the command as part of your configuration management process or machine bootstrap to easily scale up and down your universal worker fleet.

It will take a few minutes for Solano CI and the Universal Worker to sync up and update packages. Your worker will be ready when it is listed as ‘available’

../../_images/uw-available.png

Now that you have a Universal Worker available, all that is left to do is start running builds! You can add a new repo using the UI by clicking the “Add New Repo” button at the top right of your Dashboard, or by using the Solano CLI Use Solano CI from the CLI. Make sure that you add your repo to your Universal Worker organization. Your repo should also use the solano.yml syntax outlined above.

Once you have a repo set up, all you need to do is initiate a build. Solano CI will find an available Universal Worker, and assign your build to it. Your worker will be marked as “assigned” and you will be able to see the session it was assigned to in the Universal Worker settings page:

../../_images/uw-assigned.png

Troubleshooting

If your Universal Worker loses its connection to Solano CI, try rerunning the registration command.

If you run into any other issues or have any suggestions, please contact support@solanolabs.com.