foster/forgejo-docs
0
0
Fork 0
mirror of https://codeberg.org/forgejo/docs.git synced 2024-12-22 22:17:10 -05:00
Code Issues Activity

{user,admin}: actions: IPv6-capable Forgejo Runner

Browse source 
Preview

* Admin https://forgejo.codeberg.page/@docs_pull_243/docs/v1.21/admin/actions/
* User https://forgejo.codeberg.page/@docs_pull_243/docs/v1.21/user/actions/#execution-of-the-workflows

---

Forgejo runner receives IPv6 support in https://code.forgejo.org/forgejo/runner/pulls/120. I was requested in https://code.forgejo.org/forgejo/runner/issues/119#issuecomment-3289 to provide documentation for this feature.

Reviewed-on: https://codeberg.org/forgejo/docs/pulls/243
Reviewed-by: Earl Warren <earl-warren@noreply.codeberg.org>
Co-authored-by: s3lph <codeberg@s3lph.me>
Co-committed-by: s3lph <codeberg@s3lph.me>
This commit is contained in:
s3lph 2023-12-04 17:42:08 +00:00 committed by Earl Warren
parent 34791eb810
commit ac62015231
2 changed files with 80 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

78
docs/admin/actions.md
View file

@ -306,6 +306,9 @@ container:
# Could be host, bridge or the name of a custom network.
# If it's empty, create a network automatically.
network: ""
# Whether to create networks with IPv6 enabled. Requires the Docker daemon to be set up accordingly.
# Only takes effect if "network" is set to "".
enable_ipv6: false
# Whether to use privileged mode or not when launching task containers (privileged mode is required for Docker-in-Docker).
privileged: false
# And other options to be used when the container is started (eg, --add-host=my.forgejo.url:host-gateway).
@ -394,6 +397,81 @@ It will also show a similar output in the `Actions` tab of the repository.
If no `Forgejo runner` is available, `Forgejo` will wait for one to connect and submit the job as soon as it is available.
### Enable IPv6 in Docker & Podman Networks
When a `Forgejo runner` creates its own Docker or Podman networks, IPv6 is not enabled by default, and must be enabled explicitly in the `Forgejo runner` configuration.
**Docker only**: The Docker daemon requires additional configuration to enable IPv6. To make use of IPv6 with Docker, you need to provide an `/etc/docker/daemon.json` configuration file with at least the following keys:
```json
{
"ipv6": true,
"experimental": true,
"ip6tables": true,
"fixed-cidr-v6": "fd00:d0ca:1::/64",
"default-address-pools": [
{ "base": "172.17.0.0/16", "size": 24 },
{ "base": "fd00:d0ca:2::/104", "size": 112 }
]
}
```
Afterwards restart the Docker daemon with `systemctl restart docker.service`.
> **NOTE**: These are example values. While this setup should work out of the box, it may not meet your requirements. Please refer to the Docker documentation regarding [enabling IPv6](https://docs.docker.com/config/daemon/ipv6/#use-ipv6-for-the-default-bridge-network) and [allocating IPv6 addresses to subnets dynamically](https://docs.docker.com/config/daemon/ipv6/#dynamic-ipv6-subnet-allocation).
**Docker & Podman**:
To test IPv6 connectivity in `Forgejo runner`-created networks, create a small workflow such as the following:
```yaml
---
on: push
jobs:
ipv6:
runs-on: docker
steps:
- run: |
apt update; apt install --yes curl
curl -s -o /dev/null http://ipv6.google.com
```
If you run this action with `forgejo-runner exec`, you should expect this job fail:
```shell-session
$ forgejo-runner exec
...
| curl: (7) Couldn't connect to server
[ipv6.yml/ipv6] ❌ Failure - apt update; apt install --yes curl
curl -s -o /dev/null http://ipv6.google.com
[ipv6.yml/ipv6] exitcode '7': failure
[ipv6.yml/ipv6] Cleaning up services for job ipv6
[ipv6.yml/ipv6] Cleaning up container for job ipv6
[ipv6.yml/ipv6] Cleaning up network for job ipv6, and network name is: FORGEJO-ACTIONS-TASK-push_WORKFLOW-ipv6-yml_JOB-ipv6-network
[ipv6.yml/ipv6] 🏁 Job failed
```
To actually enable IPv6 with `forgejo-runner exec`, the flag `--enable-ipv6` must be provided. If you run this again with `forgejo-runner exec --enable-ipv6`, the job should succeed:
```shell-session
$ forgejo-runner exec --enable-ipv6
...
[ipv6.yml/ipv6] ✅ Success - Main apt update; apt install --yes curl
curl -s -o /dev/null http://ipv6.google.com
[ipv6.yml/ipv6] Cleaning up services for job ipv6
[ipv6.yml/ipv6] Cleaning up container for job ipv6
[ipv6.yml/ipv6] Cleaning up network for job ipv6, and network name is: FORGEJO-ACTIONS-TASK-push_WORKFLOW-ipv6-yml_JOB-ipv6-network
[ipv6.yml/ipv6] 🏁 Job succeeded
```
Finally, if this test was successful, enable IPv6 in the `config.yml` file of the `Forgejo runner` daemon and restart the daemon:
```yaml
container:
enable_ipv6: true
```
Now, `Forgejo runner` will create networks with IPv6 enabled, and workflow containers will be assigned addresses from the pools defined in the Docker daemon configuration.
## Labels and `runs-on`
The workflows / tasks defined in the files found in `.forgejo/workflows` must specify the environment they need to run with `runs-on`. Each `Forgejo runner` declares, when they connect to the `Forgejo` instance the list of labels they support so `Forgejo` sends them tasks accordingly. For instance if a job within a workflow has:

2
docs/user/actions.md
View file

@ -585,6 +585,8 @@ INFO[0000] Start server on http://192.168.1.20:34567
[checks/check and test] 🏁 Job succeeded
```
> **NOTE:** When Docker or Podman is used and IPv6 support is required, the `--enable-ipv6` flag must be provided, and IPv6 must be enabled in the `Forgejo runner`'s Docker daemon configuration. See the [Forgejo Actions administrator guide](../../admin/actions/) for more information.
## Examples
Each example is part of the [setup-forgejo](https://code.forgejo.org/forgejo/end-to-end/) action [test suite](https://code.forgejo.org/forgejo/end-to-end/src/branch/main/actions). They can be run locally with something similar to: