README.markdown

Software-management of the Argo test infrastructure
---------------------------------------------------

This repository contains scripts and configuration files to manage an Argo
testbed. Most of the contents are aimed at the Chameleoncloud infrastructure in
particular.

# Requirements

All the necessary requirements are managed by the python `Pipfile`. You will
need `pipenv` to use it. See `https://github.com/pypa/pipenv` for how to
install it.

# Environment Setup

Enter the pipenv environment:

```
pipenv shell
```

Install required packages

```
pipenv install
```

Create the required secure.yaml file with your Chameleon credentials

```
sed -e 's/USERNAME/myuser/g' -e 's/PASSWORD/mypass/g' secure.yaml.templ > secure.yaml
```

**DO NOT COMMIT THIS FILE** git will ignore it by default, but remember that
this repository is public and these are private credentials to Chameleon.

Note that the default clouds.yaml contains two regions, and they need to be
specified as the `--region` option for all operations in a specific site. If
you don't want to repeat this option everytime, set the `OS_REGION_NAME`
environment variable.

# General Help

The `chi-mngmt.py` script contains a few commands to help you figure out if
your configuration is working properly, or access specific information about a
region.

```
./chi-mngmt.py list-clouds
./chi-mngmt.py list-keys
```

In general the scripts included in this repo are here to simplify access to the
openstack tools. But if you need to do something more complex, you can always
rely on the openstack GUI or CLI directly. The `pipenv` setup will give you
access to the `openstack` command in particular. You can have this tool use the
same `clouds.yaml` configuration by using the `--os-cloud` and `--os-region`
options.

# Lease Management

Chameleon requires that a lease is created before we can boot nodes. You can
create a lease on the Chameleon web interface, or use the `chi-lease.py` script
in this repo.

*Remenber that we have limited node-hours on Chameleon, so try to keep lease
allocations to the minimal amount of hours. You can always extend a lease if
required*

```
./chi-lease.py list
./chi-lease.py create
./chi-lease.py show
./chi-lease.py delete
```

# Appliance Management

Once a lease is active, you can manage an appliance on it.

```
./chi-appliance.py list
./chi-appliance.py create
./chi-appliance.py show
./chi-appliance.py configure
./chi-appliance.py delete
```

Note that `create` requires as a last argument a JSON-formatted dictionary of
additional template parameters. These parameters can be found in the
`chameleon-appliances` directory. The command will fill out `reservation_id`
and `node_count` by itself.

In particular, `configure` will use ansible to reconfigure the appliance nodes.
The playbook used for this configuration is available in the `ansible`
directory.

You can add tasks and make this playbook as complex as you need. Over time, the
common bits used by everyone in the project should be available here. Launching
`configure` again will reconfigure the nodes entirely, you don't have to delete
an appliance to reconfigure it.