added forgejo runner docs
This commit is contained in:
parent
88d3aee150
commit
fb941c6766
1 changed files with 112 additions and 51 deletions
|
|
@ -22,7 +22,13 @@ description: >
|
|||
|
||||
## Overview
|
||||
|
||||
[Detailed description of the component - what it is, what it does, and why it exists]
|
||||
Action runners are the execution environment for Forgejo Actions workflows. By design, runners execute remote code submitted through CI/CD pipelines, making their architecture highly dependent on the underlying infrastructure and security requirements.
|
||||
|
||||
The primary objective in any runner setup is the separation and isolation of individual runs. Since runners are specifically built to execute arbitrary code from repositories, proper isolation is critical to prevent data and secret leakage between different pipeline executions. Each runner must be thoroughly cleaned or recreated after every job to ensure no residual data persists that could compromise subsequent runs.
|
||||
|
||||
Beyond isolation concerns, action runners represent high-value targets for supply chain attacks. Runners frequently compile, build, and package software binaries that may be distributed to thousands or millions of end users. Compromising a runner could allow attackers to inject malicious code directly into the software supply chain, making runner security a critical consideration in any deployment.
|
||||
|
||||
This document explores different runner architectures, examining their security characteristics, operational trade-offs, and suitability for various infrastructure environments and showing off an example deployment using a Containerized Kubernetes environment.
|
||||
|
||||
## Key Features
|
||||
|
||||
|
|
@ -32,64 +38,114 @@ description: >
|
|||
|
||||
## Purpose in EDP
|
||||
|
||||
[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
|
||||
A actions runner are executing Forgejo actions, which can be used to build, test, package and deploy software. To ensure that EDP customers do not need to provision their own action runners with high efford, we provide globally registered actions runners to pick up jobs.
|
||||
|
||||
## Repository
|
||||
|
||||
**Code**: [Link to source code repository]
|
||||
**Code**:
|
||||
- [Runner on edge connect using GARM](https://edp.buildth.ing/DevFW-CICD/garm-provider-edge-connect/src/branch/main/runner)
|
||||
- [Static runner](https://edp.buildth.ing/DevFW-CICD/stacks/src/branch/main/template/stacks/forgejo/forgejo-runner/dind-docker.yaml)
|
||||
|
||||
**Documentation**: [Link to component-specific documentation]
|
||||
**Documentation**: [Forgejo Runner installation guide](https://forgejo.org/docs/latest/admin/actions/runner-installation/)
|
||||
|
||||
## Runner Setups
|
||||
|
||||
Different runner deployment architectures offer varying levels of isolation, security, and operational complexity. The choice depends on your infrastructure capabilities, security requirements, and operational overhead tolerance.
|
||||
|
||||
### On Bare Metal
|
||||
|
||||
Bare metal runners execute directly on physical hardware without virtualization layers.
|
||||
|
||||
**Advantages:**
|
||||
- Maximum performance with direct hardware access
|
||||
- Complete hardware isolation between different physical machines
|
||||
- No hypervisor overhead or virtualization complexity
|
||||
|
||||
**Disadvantages:**
|
||||
- Difficult to clean after each run, requiring manual intervention or full OS reinstallation
|
||||
- Long provisioning time for individual runners
|
||||
- Complex provisioning processes requiring physical access or remote management tools
|
||||
- Limited scalability due to physical hardware constraints
|
||||
- Higher risk of persistent contamination between runs
|
||||
|
||||
**Use case:** Best suited for specialized workloads requiring specific hardware, performance-critical builds, or environments where virtualization is not available.
|
||||
|
||||
### On Virtual Machines
|
||||
|
||||
VM-based runners operate within virtualized environments managed by a hypervisor.
|
||||
|
||||
**Advantages:**
|
||||
- Strong isolation through hypervisor and hardware memory mapping
|
||||
- Virtual machine images enable faster provisioning compared to bare metal
|
||||
- Easy to snapshot, clone, and restore to clean states
|
||||
- Better resource utilization through multiple VMs per physical host
|
||||
- Automated cleanup by destroying and recreating VMs after each run
|
||||
|
||||
**Disadvantages:**
|
||||
- Requires hypervisor infrastructure and management
|
||||
- Slower provisioning than containers
|
||||
- Higher resource overhead compared to containerized solutions
|
||||
- More complex orchestration for scaling runner fleets
|
||||
|
||||
**Use case:** Ideal for environments requiring strong isolation guarantees, multi-tenant scenarios, or when running untrusted code from external contributors.
|
||||
|
||||
### In Containerized Environment
|
||||
|
||||
Container-based runners execute within isolated containers using OCI-compliant runtimes.
|
||||
|
||||
**Advantages:**
|
||||
- Kernel-level isolation using Linux namespaces and cgroups
|
||||
- Fast provisioning and startup times
|
||||
- Easy deployment through standardized OCI container images
|
||||
- Lightweight resource usage enabling high-density runner deployments
|
||||
- Simple orchestration with Kubernetes or Docker Compose
|
||||
|
||||
**Disadvantages:**
|
||||
- Weaker isolation than VMs since containers share the host kernel
|
||||
- Requires elevated permissions or privileged access for certain workflows (e.g., Docker-in-Docker)
|
||||
- Potential kernel-level vulnerabilities affect all containers on the host
|
||||
- Container escape vulnerabilities pose security risks in multi-tenant environments
|
||||
|
||||
**Use case:** Best for high-volume CI/CD workloads, trusted code repositories, and environments prioritizing speed and efficiency over maximum isolation.
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
* [Prerequisite 1]
|
||||
* [Prerequisite 2]
|
||||
* Forgejo instance
|
||||
* Runner registration token has been generated for a given scope
|
||||
* Global runners in `admin settings > actions > runner > Create new runner`
|
||||
* Organization runners in `organization settings > actions > runner > Create new runner`
|
||||
* Repository runners in `repository settings > actions > runner > Create new runner`
|
||||
* Kubernetes cluster
|
||||
|
||||
### Quick Start
|
||||
|
||||
[Step-by-step guide to get started with this component]
|
||||
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
1. Download [Kubernetes manifest](https://edp.buildth.ing/DevFW-CICD/stacks/src/branch/main/template/stacks/forgejo/forgejo-runner/dind-docker.yaml)
|
||||
2. Replace `${RUNNER_SECRET}` with the runner registration token
|
||||
3. Replace `${RUNNER_NAME}` with the name the runner should have
|
||||
4. Replace `${FORGEJO_INSTANCE_URL}` with the instance url
|
||||
5. (if namespace does not exists) `kubectl create ns gitea`
|
||||
6. Run `kubectl apply -f <file>`
|
||||
|
||||
### Verification
|
||||
|
||||
[How to verify the component is working correctly]
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### [Use Case 1]
|
||||
|
||||
[Example with code/commands showing common use case]
|
||||
|
||||
```bash
|
||||
# Example commands
|
||||
```
|
||||
|
||||
### [Use Case 2]
|
||||
|
||||
[Another common scenario]
|
||||
|
||||
## Integration Points
|
||||
|
||||
* **[Component A]**: [How it integrates]
|
||||
* **[Component B]**: [How it integrates]
|
||||
* **[Component C]**: [How it integrates]
|
||||
|
||||
## Architecture
|
||||
|
||||
[Optional: Add architectural diagrams and descriptions]
|
||||
|
||||
### Component Architecture (C4)
|
||||
|
||||
[Add C4 Container or Component diagrams showing the internal structure]
|
||||
Take a look at the runners page, where you generated the token. There should be 3 runners in idle state now.
|
||||
|
||||
### Sequence Diagrams
|
||||
|
||||
[Add sequence diagrams showing key interaction flows with other components]
|
||||
```mermaid
|
||||
---
|
||||
title: Forgejo Runner executed in daemon mode
|
||||
---
|
||||
sequenceDiagram
|
||||
Runner->>Forgejo: Register runner
|
||||
loop Job Workflow
|
||||
Runner->>Forgejo: Fetch job
|
||||
Runner->>Runner: Work on job
|
||||
Runner->>Forgejo: Send result
|
||||
end
|
||||
```
|
||||
|
||||
### Deployment Architecture
|
||||
|
||||
|
|
@ -97,21 +153,26 @@ description: >
|
|||
|
||||
## Configuration
|
||||
|
||||
[Key configuration options and how to set them]
|
||||
There is a sophisticated [configuration file](https://forgejo.org/docs/latest/admin/actions/runner-installation/#configuration), where finetuning can be done.
|
||||
The most important thing is done by using labels to define the execution environment.
|
||||
|
||||
The label `ubuntu-latest:docker://ghcr.io/catthehacker/ubuntu:act-22.04` (as used in [example runner](https://edp.buildth.ing/DevFW-CICD/stacks/src/branch/main/template/stacks/forgejo/forgejo-runner/dind-docker.yaml)). That a job that uses `ubuntu-latest` label will be executed as docker container inside the `ghcr.io/catthehacker/ubuntu:act-22.04` image.
|
||||
|
||||
Alternatives to `docker` are [`lxc`](https://forgejo.org/docs/latest/admin/actions/security/#job-containers-w-lxc) and [`host`](https://forgejo.org/docs/latest/admin/actions/security/#execution-on-host-host).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### [Common Issue 1]
|
||||
### In containerized environments, i want to build container images
|
||||
|
||||
**Problem**: [Description]
|
||||
**Problem**: In containerized environment, containers usually do not have many privileges. To start or build containers additional privleges, usually root is required inside of the kernel, the container runtime needs to manage linux namespaces and cgroups.
|
||||
|
||||
**Solution**: [How to fix]
|
||||
**Solution**: A partial solution for this is `buildkitd` utilizing `rootlesskit`. This allows containers to be **built** in a non root environment. You can find examples here: [Examples](https://github.com/moby/buildkit/tree/master/examples/kubernetes).
|
||||
|
||||
### [Common Issue 2]
|
||||
***Rootless vs User namespaces:***
|
||||
|
||||
**Problem**: [Description]
|
||||
As of Kubernetes 1.33, uid mapping can be enabled for pods using `pod.spec.hostUsers: false` utilizing user namespaces to map user and group ids between the container ids (0-65535) to high host ids (0-65535 + n * 65536) where n is an arbitrary number of containers. This allows that the container runs with actual root permission in its user namespace without being root on the host system.
|
||||
|
||||
**Solution**: [How to fix]
|
||||
Rootless is considered the more secure version, as the executable is mapped to a privileged entitiy at all.
|
||||
|
||||
## Status
|
||||
|
||||
|
|
@ -119,9 +180,9 @@ description: >
|
|||
|
||||
## Additional Resources
|
||||
|
||||
* [Link to external documentation]
|
||||
* [Link to community resources]
|
||||
* [Link to related components]
|
||||
* [Forgejo Runner installation guide](https://forgejo.org/docs/latest/admin/actions/runner-installation)
|
||||
* [Static Runners on Kubernetes](https://edp.buildth.ing/DevFW-CICD/stacks/src/branch/main/template/stacks/forgejo/forgejo-runner/dind-docker.yaml)
|
||||
* [Runner Orchestartion using GARM on Edge Connect](../runner-orchestration)
|
||||
|
||||
## Documentation Notes
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue