From ac62015231a4e8c855d37cf1eaedeaf249873399 Mon Sep 17 00:00:00 2001 From: s3lph Date: Mon, 4 Dec 2023 17:42:08 +0000 Subject: [PATCH] {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 Co-authored-by: s3lph Co-committed-by: s3lph --- docs/admin/actions.md | 78 +++++++++++++++++++++++++++++++++++++++++++ docs/user/actions.md | 2 ++ 2 files changed, 80 insertions(+) diff --git a/docs/admin/actions.md b/docs/admin/actions.md index 5f42dc35..b97b2a88 100644 --- a/docs/admin/actions.md +++ b/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: diff --git a/docs/user/actions.md b/docs/user/actions.md index 427b4692..f1122db4 100644 --- a/docs/user/actions.md +++ b/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: