diff --git a/README.md b/README.md index 131aaba..1283bc5 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,7 @@ This project creates [self-hosted][self] (ephemeral) GitHub [runners] based on Kubernetes or Docker containers. MicroVMs boot quickly, providing an experience close to running containers. [krunvm] creates and starts VM based on the OCI [images] created for this project. In theory, these images should be able to be -used in more traditional container-based solutions. And while these images are -based on Fedora, running on top of ubuntu should also be possible. +used in more traditional container-based solutions. [self]: https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners [runners]: https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners @@ -16,25 +15,6 @@ based on Fedora, running on top of ubuntu should also be possible. [solutions]: https://github.com/jonico/awesome-runners [images]: https://github.com/efrecon/gh-runner-krunvm/pkgs/container/runner-krunvm -## Requirements - -This project is coded in pure POSIX shell and has only been tested on Linux. The -images are automatically [built] both for x86_64 and AArch64. However, [krunvm] -also runs on MacOS. No "esoteric" options have been used when using the standard -UNIX binary utilities. PRs are welcome to make the project work on MacOS, if it -does not already. - -Apart from the standard UNIX binary utilities, you will need the following -installed on the host. - -+ `curl` -+ `jq` -+ `buildah` -+ `krunvm` (and its [requirements]) - - [built]: ./.github/workflows/ci.yml - [requirements]: https://github.com/containers/krunvm#installation - ## Example Provided you are at the root directory of this project, the following would @@ -63,6 +43,52 @@ only script that you will be using is the [orchestrator](./orchestrator.sh). [PAT]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens +## Features + ++ Fully isolated GitHub [runners] on your [infrastructure][self], through + microVM. ++ container-like experience: microVMs boot quickly. ++ No special network configuration ++ Ephemeral runners, i.e. will start from a pristine "empty" state at each run. ++ Secrets isolation to avoid leaking to workflows. ++ Run on amd64 and arm64 platforms, probably able to run on MacOS. ++ Standard "medium-sized" base OS installations (node, python, dev tools, etc.) ++ Run on top of any OCI image -- base "OS" separated from runner installation. ++ Support for registration at the repository, organisation and enterprise level. ++ Support for github.com, but also local installations of the forge. ++ Ability to mount local directories to cache local runner-based requirements or + critical software tools. ++ Good compatibility with the regular GitHub [runners]: same user ID, member of + the `docker` group, etc. + +## Requirements + +This project is coded in pure POSIX shell and has only been tested on Linux. The +images are automatically [built] both for x86_64 and AArch64. However, [krunvm] +also runs on MacOS. No "esoteric" options have been used when using the standard +UNIX binary utilities. PRs are welcome to make the project work on MacOS, if it +does not already. + +Apart from the standard UNIX binary utilities, you will need the following +installed on the host. Installation is easiest on Fedora + ++ `curl` ++ `jq` ++ `buildah` ++ `krunvm` (and its [requirements]) + + [built]: ./.github/workflows/ci.yml + [requirements]: https://github.com/containers/krunvm#installation + +## Limitations + ++ Linux host installation easiest on Fedora ++ Runners are (also) based on Fedora. While standard images are based on Fedora, + running on top of ubuntu should also be possible. ++ Docker not supported. Replaced by `podman` in emulation mode. ++ No support for docker network, runs in host networking mode only. This is + alleviated by a docker [shim](./base/docker.sh) + ## Architecture and Design The [orchestrator](./orchestrator.sh) focuses on creating (but not starting) a @@ -101,4 +127,3 @@ runner and then start the actions runner .NET implementation, under the `runner` user. The `runner` user shares the same id as the one at GitHub and is also a member of the `docker` group. Similarily to GitHub runners, the user is capable of `sudo` without a password. -