A Docker Machine driver for the Grid5000 testbed infrastructure.
Go
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

Build Status

docker-machine-driver-g5k

A Docker Machine driver for the Grid5000 testbed infrastructure. It can be used to provision a Docker machine on a node of the Grid5000 infrastructure.

Requirements

You need a Grid5000 account to use this driver. See this page to create an account.

VPN

You need to be connected to the Grid5000 VPN to create and access your Docker node.
Do not forget to configure your DNS or use OpenVPN DNS auto-configuration.
Please follow the instructions from the Grid5000 Wiki.

Installation from GitHub releases

Binary releases for Linux, MacOS and Windows using x86/x86_64 CPU architectures are available in the releases page. You can use the following commands to install or upgrade the driver:

# download the binary for your OS and CPU architecture :
sudo curl -L -o /usr/local/bin/docker-machine-driver-g5k "<link to release>"

# grant execution rigths to the driver for everyone :
sudo chmod +x /usr/local/bin/docker-machine-driver-g5k

Installation from sources

This procedure was tested on Ubuntu 16.04 and MacOS.

To use the Go tools, you need to set your GOPATH variable environment.

To get the code and compile the binary, run:

go get -u github.com/Spirals-Team/docker-machine-driver-g5k

Then, either put the driver in a directory filled in your PATH environment variable, or run:

export PATH=$PATH:$GOPATH/bin

How to use

Driver-specific command line flags

Flags description

  • --g5k-username : Your Grid5000 account username (required)
  • --g5k-password : Your Grid5000 account password (required)
  • --g5k-site : Site where the reservation of the node will be made (required)
  • --g5k-walltime : Duration of the node reservation (format: "hh:mm:ss")
  • --g5k-image : Name of the system image to deploy on the node (Operating system)
  • --g5k-resource-properties : Resource selection with OAR properties (SQL format)
  • --g5k-use-job-reservation : Job ID to use (need to be an already existing job ID)
  • --g5k-host-to-provision : Host to provision (host need to be already deployed)
  • --g5k-skip-vpn-checks : Skip the VPN client connection and DNS configuration checks (don't use this flag)
  • --g5k-reuse-ref-environment : Reuse the Grid'5000 reference environment instead of re-deploying the node
  • --g5k-job-queue : Specify the job queue (default or production only, besteffort is NOT supported)

Flags usage

Option Environment Default value
--g5k-username G5K_USERNAME
--g5k-password G5K_PASSWORD
--g5k-site G5K_SITE
--g5k-walltime G5K_WALLTIME "1:00:00"
--g5k-image G5K_IMAGE "debian9-x64-std"
--g5k-resource-properties G5K_RESOURCE_PROPERTIES
--g5k-use-job-reservation G5K_USE_JOB_RESERVATION
--g5k-host-to-provision G5K_HOST_TO_PROVISION
--g5k-skip-vpn-checks G5K_SKIP_VPN_CHECKS False
--g5k-reuse-ref-environment G5K_REUSE_REF_ENVIRONMENT False
--g5k-job-queue G5K_JOB_QUEUE "default"

Resource properties

You can use OAR properties to only select a node that matches your hardware requirements.
If you give incorrect properties or no resource matches your request, you will get this error:

...
Error with pre-create check: "Error when submitting new job: The server returned an error (code: 400) after sending Job submission: '400 Bad Request'"

More information about usage of OAR properties are available on the Grid5000 Wiki.

Grid'5000 reference environment reuse

You can reuse the Grid'5000 reference environment (debian 9, stretch) instead of redeploying the machine.
Doing so will skip the node deployment phase and will save a lot of time at the machine creation.
If you don't need a tweaked environment or rely on some Grid'5000 services (nfs for example), you should use this option.

Be aware that by default docker-machine use the aufs storage driver for Docker Engine on a Debian 9 environment.
This is incompatible with the Grid'5000 reference environment and the overlay2 storage driver should be used instead.
You will find an appropriate usage example in the following section.

Job queues

You can specify the job queue of your reservation and access the resources of the production queue.
The driver only support default, production and testing queues. The besteffort queue is NOT supported.
If you use an incorrect queue for your site you will get the following error:

...
Error with pre-create check: "Error when submitting new job: The server returned an error (code: 500) after sending Job submission: '500 Internal Server Error'"

See this page for more information about the production queue.

Usage examples

An example of node provisioning reusing the Grid'5000 standard environment:

docker-machine create -d g5k \
--g5k-username "user" \
--g5k-password "********" \
--g5k-site "lille" \
--engine-storage-driver "overlay2" \
--g5k-reuse-ref-environment \
test-node

An example of node provisioning deploying the debian9-x64-min environment on the node:

docker-machine create -d g5k \
--g5k-username "user" \
--g5k-password "********" \
--g5k-site "lille" \
--g5k-image "debian9-x64-min" \
test-node

An example of node provisioning using environment variables:

export G5K_USERNAME="user"
export G5K_PASSWORD="********"
export G5K_SITE="lille"
docker-machine create -d g5k test-node

An example with resource properties (node in cluster chimint with more thant 8GB of RAM and at least 4 CPU cores):

docker-machine create -d g5k \
--g5k-username "user" \
--g5k-password "********" \
--g5k-site "lille" \
--g5k-resource-properties "cluster = 'chimint' and memnode > 8192 and cpucore >= 4" \
test-node

An example using an existing oarsub job ID and a host already deployed with kadeploy3:

docker-machine create -d g5k \
--g5k-username "user" \
--g5k-password "********" \
--g5k-site "lille" \
--g5k-use-job-reservation 1234567 \
--g5k-host-to-provision "chinqchint-xx.lille.grid5000.fr" \
test-node