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

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>

docs/admin/actions.md

@@ -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:

docs/user/actions.md

@@ -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: