oblachno-oss/grm
1
0
Fork 0
Code Issues Pull Requests Actions 14 Packages Projects Releases Wiki Activity

GRM-16: test: add molecule lifecycle scenarios, integration tests, and docs

Browse Source 
- Add multi-instance molecule scenario verifying isolated data/config dirs
- Add lifecycle molecule scenario testing stop/disable/enable/start sequence
- Update default and binary verify playbooks for template unit assertions
- Add integration tests for full CLI lifecycle and multi-instance support
- Add pytest integration marker and --no-cov Makefile target
- Update README with lifecycle commands, multi-instance examples, and architecture
- Update Makefile with start/stop/enable/disable/status/remove targets
- Update .env.example with GRM_LANG documentation
This commit is contained in:
Emil Simeonov
2026-06-18 23:14:02 +02:00
parent adb758f5f5
commit a575a89026
15 changed files with 557 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+105 -29
View File
@@ -12,6 +12,9 @@ By default, runners are deployed as **Docker containers** using the official `gi
- **Secure** — no hardcoded secrets, uses scoped tokens.
- **Idempotent** — can be run multiple times safely.
- **Flexible** — accepts a plain IP address or hostname, and allows specifying the SSH user and private key.
- **Lifecycle management** — start, stop, enable, disable, status, and remove runners via CLI.
- **Multi-instance** — run multiple isolated runners on the same host, each with its own data directory and systemd service.
- **Systemd-managed** — both Docker and binary modes run under systemd template units (`gitea-runner@<name>.service`).
## Supported Operating Systems
@@ -22,7 +25,7 @@ By default, runners are deployed as **Docker containers** using the official `gi
## Prerequisites
- **SSH key authentication** — The remote host must be reachable via SSH using the user specified with `--user` and the private key specified with `--key`. GRM uses Ansible under the hood, which connects to the target host over SSH to execute all installation and configuration tasks. Without valid SSH credentials, Ansible cannot establish a connection and the deployment will fail.
- **Sudo privileges** — The specified user must have passwordless or password-prompted (`--ask-become-pass`) sudo access on the remote host. Runner installation requires root privileges for tasks such as installing packages, creating systemd services, and managing Docker.
- **Sudo access** — GRM requires root privileges on the remote host to install packages, create systemd services, and manage Docker. You will be prompted interactively for the sudo password. For automation or uninterrupted workflows, configure passwordless sudo on the remote host.
## Quick Start
@@ -58,33 +61,66 @@ API checks, if enabled, are purely informational and do not affect pass/fail.
### Install a Runner
Using the CLI:
Using the CLI (you will be prompted for the sudo password interactively):
```bash
# Docker mode (default) — deploys gitea_runner as a container
grm install 192.168.1.10 --user ubuntu --key ~/.ssh/id_ed25519 --name prod-runner
grm install 192.168.1.10 --user ubuntu --key ~/.ssh/id_ed25519 --name prod-runner --ask-become-pass
# Binary mode — downloads and installs the gitea_runner binary with systemd
grm install 192.168.1.10 --user ubuntu --key ~/.ssh/id_ed25519 --name prod-runner --mode binary
grm install 192.168.1.10 --user ubuntu --key ~/.ssh/id_ed25519 --name prod-runner --mode binary --ask-become-pass
```
If the remote user requires a sudo password:
```bash
grm install 192.168.1.10 --user ubuntu --ask-become-pass
```
> **Automation tip:** Configure passwordless sudo on the remote host to skip the password prompt. This is recommended for CI/CD pipelines.
Using Make:
```bash
# Docker mode (default)
make install HOST=192.168.1.10 USER=ubuntu KEY=~/.ssh/id_ed25519 NAME=prod-runner
make install HOST=192.168.1.10 USER=ubuntu KEY=~/.ssh/id_ed25519 NAME=prod-runner ASK_BECOME_PASS=1
# Binary mode
make install HOST=192.168.1.10 USER=ubuntu KEY=~/.ssh/id_ed25519 NAME=prod-runner MODE=binary
make install HOST=192.168.1.10 USER=ubuntu KEY=~/.ssh/id_ed25519 NAME=prod-runner MODE=binary ASK_BECOME_PASS=1
```
# With sudo password prompt:
make install HOST=192.168.1.10 USER=ubuntu ASK_BECOME_PASS=1
### Manage Runner Lifecycle
GRM provides commands to manage runners after installation. All commands below prompt for the sudo password interactively:
```bash
# Start a runner (registers if .runner file is missing)
grm start 192.168.1.10 --user ubuntu --name prod-runner --ask-become-pass
# Stop a runner (graceful stop, no deregistration)
grm stop 192.168.1.10 --user ubuntu --name prod-runner --ask-become-pass
# Enable a runner to start on boot
grm enable 192.168.1.10 --user ubuntu --name prod-runner --ask-become-pass
# Disable a runner (stops, deregisters from Gitea, and disables systemd)
grm disable 192.168.1.10 --user ubuntu --name prod-runner --token <token> --ask-become-pass
# Check runner status
grm status 192.168.1.10 --user ubuntu --name prod-runner --ask-become-pass
# Remove a runner completely (stops, disables, deregisters, removes files)
grm remove 192.168.1.10 --user ubuntu --name prod-runner --token <token> --ask-become-pass
```
> **Automation tip:** If the remote host has passwordless sudo configured, omit `--ask-become-pass`.
### Multiple Instances on the Same Host
Each runner instance is fully isolated with its own data directory and systemd service:
```bash
# Install two runners on the same host
grm install 192.168.1.10 --user ubuntu --name workflow-runner --ask-become-pass
grm install 192.168.1.10 --user ubuntu --name build-runner --mode binary --ask-become-pass
# Manage them independently
grm stop 192.168.1.10 --user ubuntu --name workflow-runner --ask-become-pass
grm status 192.168.1.10 --user ubuntu --name build-runner --ask-become-pass
```
### Verify Runner
@@ -101,8 +137,8 @@ Optional: If `GITEA_ADMIN_TOKEN` is set, the installer will also query the Gitea
### View Logs
```bash
# Binary mode logs
sudo journalctl -u gitea-runner-<name> -f
# Binary mode logs (via systemd template unit)
sudo journalctl -u gitea-runner@<name> -f
# Docker mode logs
docker logs gitea-runner-<name> -f
@@ -112,8 +148,8 @@ docker logs gitea-runner-<name> -f
GRM consists of two layers:
1. **Python CLI** (`src/gitea_runner_manager/`) — built with Click, handles argument parsing, environment loading, and delegates to Ansible via the `ansible-playbook` subprocess.
2. **Ansible Role** (`ansible/roles/gitea-runner/`) — idempotent role that installs Docker, configures the runner (binary or container), creates systemd services, and registers the runner with Gitea.
1. **Python CLI** (`src/gitea_runner_manager/`) — built with Click, handles argument parsing, environment loading, i18n translations, and delegates to Ansible via the `ansible-playbook` subprocess.
2. **Ansible Role** (`ansible/roles/gitea-runner/`) — idempotent role that installs Docker, configures the runner (binary or container), creates systemd template units, and registers the runner with Gitea.
```
grm install <host>
@@ -123,10 +159,18 @@ grm install <host>
├── docker.yml (Docker installation)
├── docker_mode.yml (container deployment)
├── binary_mode.yml (binary + systemd deployment)
├── service.yml (systemd template unit)
├── deregister.yml (deregistration from Gitea)
├── prune.yml (Docker prune timer)
└── integration_test.yml (validate online status)
```
Both Docker and binary modes run under a single systemd template unit (`gitea-runner@.service`), instantiated per runner name (e.g., `gitea-runner@prod-runner.service`). Each instance has fully isolated directories:
- **Data**: `/var/lib/gitea-runner/<name>/`
- **Config**: `/etc/gitea-runner/<name>/` (binary mode)
- **Service**: `gitea-runner@<name>.service`
## Configuration
All tunable values are exposed as Ansible variables in `ansible/roles/gitea-runner/defaults/main.yml`:
@@ -138,8 +182,10 @@ All tunable values are exposed as Ansible variables in `ansible/roles/gitea-runn
| `gitea_runner_docker_image` | `gitea/runner` | Docker image name |
| `runner_labels` | `ubuntu-latest:docker://runner-images:ubuntu-22.04` | Runner labels |
| `skip_runner_registration` | `false` | Skip API registration (useful for tests) |
| `gitea_runner_data_dir` | `/var/lib/gitea-runner` | Runtime data directory |
| `gitea_runner_config_dir` | `/etc/gitea-runner` | Config directory (binary mode) |
| `gitea_runner_base_data_dir` | `/var/lib/gitea-runner` | Base data directory (instance-scoped) |
| `gitea_runner_base_config_dir` | `/etc/gitea-runner` | Base config directory (instance-scoped) |
| `gitea_runner_data_dir` | `{{ base }}/{{ runner_name }}` | Runtime data directory per instance |
| `gitea_runner_config_dir` | `{{ base }}/{{ runner_name }}` | Config directory per instance |
| `gitea_runner_binary_path` | `/usr/local/bin/gitea_runner` | Binary install path |
| `gitea_runner_prune_until` | `24h` | Prune resources older than this |
| `gitea_runner_prune_schedule` | `daily` | systemd timer schedule |
@@ -149,6 +195,7 @@ All tunable values are exposed as Ansible variables in `ansible/roles/gitea-runn
| `gitea_runner_log_level` | `info` | Runner log level |
| `gitea_runner_container_label` | `gitea-runner=true` | Container label |
| `docker_gpg_key_path` | `/etc/apt/keyrings/docker.asc` | Docker GPG key path |
| `GRM_LANG` | `en` | CLI language: `en`, `bg`, `de`, `ru`, `zh` |
Override any variable by passing it to the CLI with `--extra-vars` or by setting it in your Ansible inventory.
@@ -161,6 +208,8 @@ Override any variable by passing it to the CLI with `--extra-vars` or by setting
├── src/gitea_runner_manager/ # Python CLI source
│ ├── cli.py # Click commands
│ ├── runner_manager.py # Ansible orchestration
│ ├── executor.py # Ansible subprocess execution
│ ├── i18n.py # Translations (en, bg, de, ru, zh)
│ └── exceptions.py # Custom exceptions
├── ansible/
│ ├── roles/gitea-runner/ # Main Ansible role
@@ -169,8 +218,16 @@ Override any variable by passing it to the CLI with `--extra-vars` or by setting
│ │ ├── templates/ # Jinja2 templates
│ │ └── molecule/ # Test scenarios
│ ├── install-runner.yml # Install playbook
│ └── update-runner.yml # Update playbook
├── tests/ # Unit tests
│ ├── update-runner.yml # Update playbook
│ ├── start-runner.yml # Start playbook
│ ├── stop-runner.yml # Stop playbook
│ ├── enable-runner.yml # Enable playbook
│ ├── disable-runner.yml # Disable playbook
│ ├── status-runner.yml # Status playbook
│ └── remove-runner.yml # Remove playbook
├── tests/
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
├── Makefile # Build & test automation
└── pyproject.toml # Python project metadata
```
@@ -206,12 +263,22 @@ Runs pytest with 100% coverage requirement.
make molecule
```
Runs two scenarios:
Runs four scenarios:
- **default** — Docker mode installation in an Ubuntu 22.04 container
- **binary** — Binary mode installation in an Ubuntu 22.04 container
- **multi-instance** — Two isolated runner instances on the same host
- **lifecycle** — Stop, disable, re-enable, and start sequence
Both scenarios test idempotence (second run produces zero changes).
All scenarios test idempotence (second run produces zero changes).
### Integration Tests
```bash
make test-integration
```
Tests the full CLI lifecycle commands end-to-end ( mocked executor boundary).
### Full Test Suite
@@ -228,7 +295,7 @@ This is a harmless cleanup traceback from Molecule's Docker driver when the test
### Runner appears offline after installation
- Check that the `GITEA_URL` and `GITEA_REGISTRATION_TOKEN` environment variables are correct.
- Verify the runner container or service is running: `docker ps` or `systemctl status gitea-runner-<name>`.
- Verify the runner container or service is running: `docker ps` or `systemctl status gitea-runner@<name>`.
- Check logs for registration errors.
### Integration test fails
@@ -238,33 +305,42 @@ The test checks two things:
1. **`.runner` file missing or invalid** — Registration failed. Check:
- `GITEA_URL` and `GITEA_REGISTRATION_TOKEN` are correct
- Runner logs for registration errors
- The `.runner` file should exist at `/var/lib/gitea-runner/.runner` (Docker) or `/etc/gitea-runner/.runner` (binary)
- The `.runner` file should exist at `/var/lib/gitea-runner/<name>/.runner`
2. **Container/service not running** — Daemon failed to start. Check:
- `docker ps` or `systemctl status gitea-runner-<name>`
- `docker ps` or `systemctl status gitea-runner@<name>`
- Logs for connection errors
### Docker mode: container won't start
- Ensure Docker is installed and running on the host.
- Verify the Docker socket is accessible: `docker version`.
- Check systemd status: `systemctl status gitea-runner@<name>`.
### Binary mode: systemd service fails
- Check the service status: `systemctl status gitea-runner-<name>`.
- Check the service status: `systemctl status gitea-runner@<name>`.
- Verify the binary exists at `gitea_runner_binary_path`.
- Ensure the service user is in the `docker` group.
- Check logs: `journalctl -u gitea-runner@<name> -f`.
## Makefile Targets
| Target | Description |
|--------|-------------|
| `setup` | Full environment setup |
| `install` | Installs a runner on a host (`MODE=docker` or `binary`) |
| `update` | Updates a runner on a host (`MODE=docker` or `binary`) |
| `install` | Installs a runner on a host |
| `update` | Updates a runner on a host |
| `start` | Starts a runner instance |
| `stop` | Stops a runner instance |
| `enable` | Enables a runner to start on boot |
| `disable` | Disables and deregisters a runner |
| `status` | Checks runner status |
| `remove` | Removes a runner completely |
| `lint` | Runs Python linters |
| `ansible-lint` | Runs `ansible-lint` |
| `test-unit` | Runs unit tests with coverage |
| `test-integration` | Runs integration tests |
| `molecule` | Runs Ansible Molecule tests |
| `test-all` | Runs all tests |