introduced runner orchestration doc
This commit is contained in:
parent
5b4fbcbb54
commit
88d3aee150
2 changed files with 215 additions and 34 deletions
74
.claude/CLAUDE.md
Normal file
74
.claude/CLAUDE.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -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 <your-image-tag> .`
|
||||
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]
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue