README.md

jetstream2 administration scripts

Use these scripts to administer the jetstream2 VMs. They provide resources to GitHub Actions to perform expensive build and test options more quickly.

Using the runners in GitHub Actions

Use the runner [self-hosted,jetstream2,CPU] to select these runners for GitHub Actions jobs.

The VMs shutdown automatically after a period of inactivity. Start the runners as part of the workflow with this job:

  start_action_runners:
    name: Start
    uses: glotzerlab/jetstream2-admin/.github/workflows/start.yaml@98f840ba341f72bf412100f2180d38c06e792b84 # v1.3.0
    secrets: inherit

Optionally request only a certain number of runners:

  start_action_runners:
    name: Start
    uses: glotzerlab/jetstream2-admin/.github/workflows/start.yaml@98f840ba341f72bf412100f2180d38c06e792b84 # v1.3.0
    secrets: inherit
    with:
      number: 1

To administer the VMs

• Create and manage VMs at: https://jetstream2.exosphere.app/exosphere/home
• Add VMs to the inventory in hosts.yaml.

Configure GitHub action runners

Use ansible to install GitHub Actions on the VMs::

ansible-playbook configure-runners.yaml -i hosts.yaml

• configure-runners.yaml will ask for a token from GitHub's add runner page.
• update-instances.yaml will update the apt packages.
• View the active runners on GitHub.

Manage action runners

• auto-shutdown.sh automatically shuts down instances when the actions-runner service is idle for some time.
• shelve-action-runners.py shelves actions-runner instances that are powered down.
• start-action-runners.py starts actions-runner instances.

HOOMD's GitHub Actions scripts run start-action-runners.py when needed. This repository runs shelve-action-runners.py periodically in GitHub Actions to shelve the instances when not needed. Both of these scripts may be run locally with the proper authentication token (see https://docs.jetstream-cloud.org/ui/cli/overview/).

Check on action runner usage

Use ansible to download usage data::

ansible-playbook fetch-activity-logs.yaml -i hosts.yaml

Then, run the usage-details.ipynb notebook in Jupyter.

Style

Use pre-commit to check for code style and formatting.

License

The jetstream2 administration scripts are available under the 3-clause BSD license.