diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md new file mode 100644 index 0000000..40a0a94 --- /dev/null +++ b/.claude/CLAUDE.md @@ -0,0 +1,74 @@ +# Technical Documentation Guidelines + +You are an expert technical writer with deep expertise in creating clear, concise, and well-structured documentation. Your goal is to produce documentation that flows naturally while maintaining technical accuracy. + +## Core Principles + +### 1. Conciseness and Clarity +- Use clear, direct language +- Eliminate unnecessary words and redundancy +- Make every sentence count +- Prefer active voice over passive voice +- Use short paragraphs (3-5 sentences maximum) + +### 2. Structure and Organization +- Start with the most important information +- Use logical hierarchies with consistent heading levels +- Group related concepts together +- Provide clear navigation through table of contents when appropriate +- Use lists for sequential steps or related items + +### 3. Flow and Readability +- Ensure smooth transitions between sections +- Connect ideas logically +- Build complexity gradually +- Use examples to illustrate concepts +- Maintain consistent terminology throughout + +### 4. Technical Accuracy +- Be precise with technical terms +- Include relevant code examples that are tested and functional +- Document edge cases and limitations +- Provide accurate command syntax and parameters +- Link to related documentation when appropriate + +## Documentation Structure + +### Standard Document Layout +1. **Title** - Clear, descriptive heading +2. **Overview** - Brief introduction (2-3 sentences) +3. **Prerequisites** - What the reader needs to know or have +4. **Main Content** - Organized in logical sections +5. **Examples** - Practical, real-world use cases +6. **Troubleshooting** - Common issues and solutions (when applicable) +7. **Related Resources** - Links to additional documentation + +### Code Examples +- Provide complete, runnable examples +- Include comments for complex logic +- Show expected output +- Use consistent formatting and syntax highlighting + +### Commands and APIs +- Show full syntax with all parameters +- Indicate required vs optional parameters +- Provide parameter descriptions +- Include return values or output format + +## Writing Style + +- **Be direct**: "Configure the database" not "You should configure the database" +- **Be specific**: "Set timeout to 30 seconds" not "Set an appropriate timeout" +- **Be consistent**: Use the same terms for the same concepts +- **Be complete**: Don't assume implicit knowledge; explain as needed + +## When Uncertain + +**If you don't know something or need clarification:** +- Ask specific questions +- Request examples or use cases +- Clarify technical details or edge cases +- Verify terminology and naming conventions +- Confirm target audience and their expected knowledge level + +Your expertise is in writing excellent documentation. Use your judgment to create documentation that serves the reader's needs effectively. When in doubt, ask rather than guess. diff --git a/content/en/docs/components/forgejo/actions/runner-orchestration.md b/content/en/docs/components/forgejo/actions/runner-orchestration.md index 00fcb0c..1001a6f 100644 --- a/content/en/docs/components/forgejo/actions/runner-orchestration.md +++ b/content/en/docs/components/forgejo/actions/runner-orchestration.md @@ -5,37 +5,29 @@ weight: 30 description: GARM --- -{{% alert title="Draft" color="warning" %}} -**Editorial Status**: This page is currently being developed. - -* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX) -* **Assignee**: [Name or Team] -* **Status**: Draft -* **Last Updated**: YYYY-MM-DD -* **TODO**: - * [ ] Add detailed component description - * [ ] Include usage examples and code samples - * [ ] Add architecture diagrams - * [ ] Review and finalize content -{{% /alert %}} - ## Overview -[Detailed description of the component - what it is, what it does, and why it exists] +GARM provides on-demand runner orchestration for Forgejo Actions through dynamic autoscaling. As Forgejo has similar API structure to Gitea (from which it was forked), GARM's Gitea/GitHub compatibility makes it a natural fit for automated runner provisioning. GARM supports custom providers, enabling runner infrastructure deployment across multiple cloud and infrastructure platforms. + +A custom edge-connect provider was implemented for GARM to enable infrastructure provisioning. Additionally, Forgejo was adapted to align more closely with Gitea's API, ensuring seamless integration with GARM's orchestration capabilities. ## Key Features -* [Feature 1] -* [Feature 2] -* [Feature 3] +* Autoscales Forgejo Actions runners dynamically based on workload demand +* Leverages edge-connect infrastructure for distributed runner provisioning ## Purpose in EDP -[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities] +- Provides CI/CD infrastructure for all software development projects +- Enhances the EDP platform capabilities through improved Forgejo automation +- Enables teams to focus on development by consuming platform-managed runners without capacity planning concerns ## Repository -**Code**: [Link to source code repository] +**Code**: +- [GARM Provider for Edge Connect](https://edp.buildth.ing/DevFW-CICD/garm-provider-edge-connect) +- [GARM deploy script](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/scripts/local-helm.sh) +- [GARM deploy manifests](https://edp.buildth.ing/DevFW/garm-deploy.git) **Documentation**: [Link to component-specific documentation] @@ -43,20 +35,23 @@ description: GARM ### Prerequisites -* [Prerequisite 1] -* [Prerequisite 2] +* Container Runtime installed (e.g. docker) +* Forgejo, Gitea or Github ### Quick Start -[Step-by-step guide to get started with this component] - -1. [Step 1] -2. [Step 2] -3. [Step 3] +1. Clone the [GARM Provider repository](https://edp.buildth.ing/DevFW-CICD/garm-provider-edge-connect/) +2. Build the Docker image: `docker buildx build -t .` +3. Push the image to your container registry +4. Deploy GARM using the [deployment script](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/scripts/local-helm.sh) from the [infra-deploy](https://edp.buildth.ing/DevFW/infra-deploy) repository, targeting your Kubernetes cluster: `./local-helm.sh --garm` ### Verification -[How to verify the component is working correctly] +- Verify the GARM pod is running: `kubectl get pods -n garm` +- Retrieve the GARM domain endpoint: `kubectl get ing -n garm` +- Get the GARM admin password: `kubectl get secret -n garm garm-credentials -o json | jq .data.GARM_ADMIN_PASSWORD -r | base64 -d` +- Configure endpoints, credentials, repositories, and runner pools in GARM as described in [TODO](TODO) + ## Usage Examples @@ -74,9 +69,8 @@ description: GARM ## Integration Points -* **[Component A]**: [How it integrates] -* **[Component B]**: [How it integrates] -* **[Component C]**: [How it integrates] +* **[Forgejo]**: Picks up pending action jobs, listen in Forgejo +* **[Edge Connect]**: Uses this infrastructure to deploy runners that can pick up open jobs in forgejo ## Architecture @@ -95,7 +89,7 @@ sequenceDiagram participant Forgejo participant GARM participant Runner as Ephemeral Runner - + User->>Forgejo: Push Code / Trigger Event Forgejo->>GARM: Webhook Event (Workflow Dispatch) GARM->>Forgejo: Register Runner (via API) @@ -106,10 +100,123 @@ sequenceDiagram Runner->>Forgejo: Report Status GARM->>Runner: Terminate (Ephemeral) ``` +### Sequence Diagrams + +[Add sequence diagrams showing key interaction flows with other components] + +The diagram below shows how a trigger of an action results in deployment of a runner on edge-connect. + +```mermaid +sequenceDiagram + + rect rgb(255,200,200) + Forgejo->>GARM: (Webhook) A new job is pending + GARM->>GARM Provider Edge Connect: Create new runner + GARM Provider Edge Connect->>Edge Connect: Create App + GARM Provider Edge Connect->>Edge Connect: Create AppInstance + Edge Connect->>Runner: Deploys + end + + Runner->>GARM: Retrieve runner registration token + GARM->>Forgejo: Retrieve runner registration token + Forgejo-->>GARM: Token + GARM-->>Runner: Token + Runner->>Forgejo: Register runner + Runner->>Forgejo: Fetch job + Runner->>Runner: Work on job + Runner->>Forgejo: Send result +``` + +### Deployment Architecture + +[Add infrastructure and deployment diagrams showing how the component is deployed] + +TODO c4 + +- Garm Container in OTC Kubernetes +- Garm-Provider in Garm Container +- Garm in Garm container +- EDP in OTC Kubernetes +- Forgejo Runner in Edge Connect +- EDP --notifies with webhook--> Garm +- Garm --calls--> EDP +- Garm --calls--> garm provider +- garm provider --provisions instance--> Forgejo runner +- Forgejo runner --retrieves bootstrap information-->Garm +- Forgejo runner --picks up job--> EDP ## Configuration -[Key configuration options and how to set them] +### Provider Setup + +The config below configures an external provder for garm. Especially important is the `provider.external.config_file` which refers to the configuration of the external provider (example below) and `provider.external.provider_executable` which needs to point to the provider executable. + + +```config.toml +# config.toml +... +[[provider]] +name = "edge-connect" +description = "edge connect provider" +provider_type = "external" + +[provider.external] +config_file = "/etc/garm/edge-connect-provider-config.toml" +provider_executable = "/opt/garm/providers.d/garm-provider-edge-connect" +environment_variables = ["EDP_EDGE_CONNECT_"] +``` + +```edge-connect-provider-config.toml +# edge-connect-provider-config.toml +log_file = "/garm/provider.log" +credentials_file = "/etc/garm-creds/credentials.toml" # to authenticate agains edge_connect.url + +[edge_connect] +organization = "edp-developer-framework" +region = "EU" +url = "https://hub.apps.edge.platform.mg3.mdb.osc.live" +default_flavor = "EU.small" + +[edge_connect.cloudlet] +name = "Munich" +organization = "TelekomOP" +``` + +```credentials.toml +# credentials.toml for edge connect platform +username = "" +password = "" +``` + +### Runner Pool Configuration + +Once the configuration is in place and garm has been deployed. You can connect garm to Forgejo/Gitea/Github, using the commands below. If you have a forgejo instance, you want to create a gitea endpoint. + +```sh +# https://edp.buildth.ing/DevFW/garm-deploy/src/branch/master/helm/garm/templates/init-job.yaml#L39-L56 +garm-cli init --name gitea --password ${GARM_ADMIN_PASSWORD} --username ${GARM_ADMIN_USERNAME} --email ${GARM_ADMIN_EMAIL} --url ${GARM_URL} +if [ $? -ne 0 ]; then + echo "garm maybe already initialized" + exit 0 +fi + +# API_GIT_URL=https://garm-provider-test.t09.de/api/v1 +# GIT_URL=https://garm-provider-test.t09.de +garm-cli gitea endpoint create \ +--api-base-url ${API_GIT_URL} \ +--base-url ${GIT_URL} \ +--description "My first Gitea endpoint" \ +--name local-gitea + +garm-cli gitea credentials add \ +--endpoint local-gitea \ +--auth-type pat \ +--pat-oauth-token $GITEA_TOKEN \ +--name autotoken \ +--description "Gitea token" +``` + +Now, connect to the WebUI, use `GARM_ADMIN_USERNAME` and `GARM_ADMIN_PASSWORD` as credentials to authenticate. Click on repositories and ## Troubleshooting @@ -131,7 +238,7 @@ sequenceDiagram ## Additional Resources -* [Link to external documentation] +* [Using garm](https://github.com/cloudbase/garm/blob/main/doc/using_garm.md) * [Link to community resources] * [Link to related components]