Tirsvad
fce3cf8c6b
actions/connect-wireguard brings a WireGuard tunnel up for a deployment job and takes it down again, with a guide and offline tests. The runs on a real runner (MIL-012 task 3) are still to do. Refs #184 Task: MIL-012#3
106 lines
4.2 KiB
Markdown
106 lines
4.2 KiB
Markdown
# Reaching a private network with WireGuard
|
|
|
|
The composite action `actions/connect-wireguard` brings a WireGuard tunnel up on
|
|
a Gitea Actions runner, so the next steps of the same job (a deployment over
|
|
SSH, a database migration) can reach hosts that are not on the internet. It is
|
|
the WireGuard counterpart of the Tailscale action. It is **experimental**: it
|
|
lives on a branch until a trial shows it is wanted.
|
|
|
|
A tunnel belongs to one job: every job that deploys brings its own tunnel up
|
|
and takes it down. It cannot be a reusable workflow, because a called workflow
|
|
runs as a separate job.
|
|
|
|
## Use it
|
|
|
|
```yaml
|
|
jobs:
|
|
deploy:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v4.2.2
|
|
|
|
- name: Connect the VPN
|
|
uses: TirSystem/github-action/actions/connect-wireguard@v2
|
|
with:
|
|
config: ${{ secrets.WG_CONFIG }}
|
|
health-check-host: 10.8.0.1
|
|
|
|
- name: Deploy
|
|
run: ssh deploy@10.8.0.10 ./deploy.sh
|
|
|
|
- name: Disconnect the VPN
|
|
if: always()
|
|
uses: TirSystem/github-action/actions/connect-wireguard@v2
|
|
with:
|
|
action: down
|
|
```
|
|
|
|
If the short form does not resolve on your instance (Gitea looks for the action
|
|
on the host set in `DEFAULT_ACTIONS_URL`), use the full address:
|
|
`https://git.tirsystem.com/TirSystem/github-action/actions/connect-wireguard@v2`.
|
|
|
|
To try the branch before it is released, replace `@v2` with
|
|
`@wireguard-vpn-action`.
|
|
|
|
## Inputs
|
|
|
|
| Input | Default | Meaning |
|
|
| --- | --- | --- |
|
|
| `action` | `up` | `up` or `down` |
|
|
| `config` | | A complete wg-quick file, as a secret. When set, the fields below are ignored |
|
|
| `private-key`, `address`, `peer-public-key`, `endpoint`, `allowed-ips` | | The fields of a configuration, all five needed without `config` |
|
|
| `preshared-key`, `dns` | | Optional |
|
|
| `persistent-keepalive` | `25` | Seconds |
|
|
| `interface` | `wg0` | Interface name |
|
|
| `health-check-host` | | A host behind the tunnel; the step fails when it does not answer a ping |
|
|
|
|
## Set it up
|
|
|
|
1. On the WireGuard server add one peer for CI, with its own key pair and an
|
|
address inside the tunnel (`10.8.0.2/32`). Let it reach only the hosts the
|
|
deployment needs.
|
|
2. Store the configuration (or the private key) as a secret of the
|
|
organization, never in the repository. Give the secret a name that does not
|
|
start with `GITEA_` or `GITHUB_`.
|
|
3. Set `allowed-ips` to the private network only. `0.0.0.0/0` sends all of the
|
|
job's traffic, including the checkout, through the tunnel.
|
|
4. Rotate the key when a person with access to the secret leaves.
|
|
|
|
## The runner must allow it
|
|
|
|
A tunnel needs a network interface, so the runner needs more than a plain job
|
|
container:
|
|
|
|
- the job runs as root or can use `sudo` (the action installs
|
|
`wireguard-tools` with `apt` when it is missing, so a Debian or Ubuntu image);
|
|
- the container has the capability `NET_ADMIN` and the device `/dev/net/tun`.
|
|
In the `act_runner` configuration set under `container:`
|
|
`options: "--cap-add=NET_ADMIN --device=/dev/net/tun"`;
|
|
- without the kernel module the action uses `wireguard-go` (user space), which
|
|
needs the same capability and device.
|
|
|
|
Use a dedicated runner with a label of its own (for example `vpn`) and put
|
|
`runs-on: vpn` on the jobs that need it, so the other jobs do not get the extra
|
|
privilege.
|
|
|
|
## What the action does
|
|
|
|
- masks the keys in the log before anything else;
|
|
- writes `/etc/wireguard/<interface>.conf` with mode 600 and brings it up with
|
|
`wg-quick`;
|
|
- prints errors as `::error::[category] message`, with the categories
|
|
`configuration`, `environment` and `connection`;
|
|
- on `down` takes the interface down and deletes the file.
|
|
|
|
It never prints a key. Do not turn on shell tracing (`set -x`) in the steps
|
|
that follow.
|
|
|
|
## Troubleshooting
|
|
|
|
| Message | Cause |
|
|
| --- | --- |
|
|
| `[configuration] ... is empty` | Neither `config` nor all five fields were given |
|
|
| `[environment] ... NET_ADMIN and /dev/net/tun` | The runner container lacks the capability or the device |
|
|
| `[connection] wg-quick could not bring wg0 up` | A wrong key, endpoint or a firewall; run `wg show` on the server |
|
|
| `[connection] health-check-host ... does not answer` | The tunnel is up but the host is not in `allowed-ips`, or is blocked |
|