feat(actions): add docs for EdgeConnect Actions
Some checks failed
build / build (push) Failing after 54s
ci / build (push) Successful in 55s

This commit is contained in:
Martin McCaffery 2025-12-18 11:51:41 +01:00
parent 41e3306942
commit 48a9eed862
Signed by: martin.mccaffery
GPG key ID: 7C4D0F375BCEE533
6 changed files with 241 additions and 137 deletions

View file

@ -1,35 +1,23 @@
---
title: "EdgeConnect"
linkTitle: "EdgeConnect"
title: EdgeConnect
linkTitle: EdgeConnect Cloud
weight: 20
description: >
Secure connectivity solution for edge devices and environments
---
{{% alert title="Draft" color="warning" %}}
**Editorial Status**: This page is currently being developed.
* **Jira Ticket**: [TICKET-6734](https://jira.telekom-mms.com/browse/IPCEICIS-6734)
* **Assignee**: Waldemar
* **Status**: Draft
* **Last Updated**: 2025-12-16
* **TODO**:
* [x] Add detailed component description
* [ ] Review and finalize content
{{% /alert %}}
## Overview
EdgeConnect is a custom cloud provided by the project as a whole. It has several goals, including retaining sovereign control over cloud compute resources, and supporting sustainability-aware infrastructure choices.
While EdgeConnect is managed outwith our Edge Developer Platform, we have produced a number of tools to facilitate its use and broaden its applicability. These include an [SDK](/docs/components/deployments/edgeconnect/edgeconnect-sdk/), command-line [client](/docs/components/deployments/edgeconnect/edgeconnect-client/), and bespoke [provider](/docs/components/orchestration/infrastructure/provider/) for [Terraform](https://developer.hashicorp.com/terraform).
While EdgeConnect is managed outwith our Edge Developer Platform, we have produced a number of tools to facilitate its use and broaden its applicability. These are an [SDK](/docs/components/deployments/edgeconnect/edgeconnect-sdk/), command-line [client](/docs/components/deployments/edgeconnect/edgeconnect-client/), bespoke [provider](/docs/components/orchestration/infrastructure/provider/) for [Terraform](https://developer.hashicorp.com/terraform), and tailormade [Forgejo Actions](/docs/edgeconnect/edgeconnect-actions/).
## Key Features
* Managed by broader project, not specifically EDP
* Focus on sovereignty and sustainability
* EDP supplies tools such as [CLI](docs/components/deployments/edgeconnect/edgeconnect-client/) and [Terraform provider](/docs/components/orchestration/infrastructure/provider/)
* Primary EDP products such as [Forgejo](/docs/components/forgejo/) are hosted on [OTC](/docs/components/deployments/otc/) rather than EdgeConnect
* Utilities such as [CLI](docs/components/deployments/edgeconnect/edgeconnect-client/) and [Terraform provider](/docs/components/orchestration/infrastructure/provider/) encourage widespread platform use
* [EDP](/docs/edp/) products such as [Forgejo](/docs/components/forgejo/) are hosted on [OTC](/docs/components/deployments/otc/) rather than EdgeConnect
## Purpose in EDP

View file

@ -1,128 +1,286 @@
---
title: Forgejo Actions
linkTitle: Forgejo Actions
weight: 30
weight: 40
description: >
Development environment provisioning and management
CI/CD actions for automated EdgeConnect deployment and deletion
---
{{% 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]
The EdgeConnect Actions are custom composite actions for use in [Forgejo](/docs/edp/forgejo/actions/)/[GitHub Actions](https://forgejo.org/docs/latest/user/actions/github-actions/) that automate EdgeConnect application deployments in CI/CD pipelines. They wrap the [EdgeConnect Client](/docs/edgeconnect/edgeconnect-client/) to provide a simple, declarative way to deploy and delete applications without manual CLI installation or configuration.
Two actions are available:
- **edge-connect-deploy-action**: Deploys applications using declarative YAML configuration
- **edge-connect-delete-action**: Deletes applications and their instances from EdgeConnect
## Key Features
* [Feature 1]
* [Feature 2]
* [Feature 3]
* **Zero installation**: Actions automatically download and use the EdgeConnect Client
* **Declarative workflow**: Deploy applications using YAML configuration files
* **CI/CD optimized**: Designed for automated pipelines with auto-approve and dry-run support
* **Version pinning**: Specify exact EdgeConnect Client version for reproducible builds
* **Secrets management**: Credentials passed securely through workflow secrets
* **Compatible with GitHub and Forgejo Actions**: Works in both ecosystems
## Purpose in EDP
[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
CI/CD automation is essential for modern development workflows. While the [EdgeConnect Client](/docs/edgeconnect/edgeconnect-client/) provides powerful deployment capabilities, integrating it into CI/CD pipelines requires downloading binaries, managing credentials, and configuring authentication for each workflow run.
These actions eliminate that boilerplate by:
- Automatically fetching the correct Client version
- Handling authentication setup
- Providing a clean, reusable action interface
- Reducing pipeline configuration to a few lines
This enables teams to focus on application configuration rather than pipeline plumbing, while maintaining the full power of declarative EdgeConnect deployments.
The actions complement the [Terraform provider](/docs/edgeconnect/terraform-provider/) by offering a simpler option for teams already using Forgejo/GitHub Actions who want deployment automation without adopting Terraform.
## Repository
**Code**: [Link to source code repository]
**Deploy Action**: https://edp.buildth.ing/DevFW-CICD/edge-connect-deploy-action
**Documentation**: [Link to component-specific documentation]
**Delete Action**: https://edp.buildth.ing/DevFW-CICD/edge-connect-delete-action
**Demo Repository**: https://edp.buildth.ing/DevFW-CICD/edgeconnect-action-demo
## Getting Started
### Prerequisites
* [Prerequisite 1]
* [Prerequisite 2]
* Forgejo or GitHub repository with Actions enabled
* EdgeConnect access credentials (username and password)
* `EdgeConnectConfig.yaml` file defining your application (see [YAML Configuration Format](/docs/edgeconnect/edgeconnect-client/#yaml-configuration-format))
* For Kubernetes apps: K8s manifest file referenced in the config
* Repository secrets configured with EdgeConnect credentials
### Quick Start
[Step-by-step guide to get started with this component]
1. [Step 1]
2. [Step 2]
3. [Step 3]
1. Create an `EdgeConnectConfig.yaml` file in your repository defining your application (see [Client documentation](/docs/edgeconnect/edgeconnect-client/#yaml-configuration-format))
2. Add EdgeConnect credentials as repository secrets:
- `EDGEXR_PLATFORM_USERNAME`
- `EDGEXR_PLATFORM_PASSWORD`
3. Create a workflow file (e.g., `.forgejo/workflows/deploy.yaml`) using the action
4. Commit and push to trigger the workflow
### Verification
[How to verify the component is working correctly]
After the workflow runs successfully:
- Check the workflow logs for deployment status
- Verify resources appear in the [EdgeConnect console](https://hub.apps.edge.platform.mg3.mdb.osc.live/)
- Test application endpoints are accessible
## Usage Examples
### [Use Case 1]
### Minimal Deploy Action
[Example with code/commands showing common use case]
```bash
# Example commands
```yaml
- name: Deploy to EdgeConnect
uses: https://edp.buildth.ing/DevFW-CICD/edge-connect-deploy-action@main
with:
configFile: ./EdgeConnectConfig.yaml
baseUrl: https://hub.apps.edge.platform.mg3.mdb.osc.live
username: ${{ secrets.EDGEXR_PLATFORM_USERNAME }}
password: ${{ secrets.EDGEXR_PLATFORM_PASSWORD }}
```
### [Use Case 2]
### Minimal Delete Action
[Another common scenario]
```yaml
- name: Delete from EdgeConnect
uses: https://edp.buildth.ing/DevFW-CICD/edge-connect-delete-action@main
with:
configFile: ./EdgeConnectConfig.yaml
baseUrl: https://hub.apps.edge.platform.mg3.mdb.osc.live
username: ${{ secrets.EDGEXR_PLATFORM_USERNAME }}
password: ${{ secrets.EDGEXR_PLATFORM_PASSWORD }}
```
### Complete Workflow Example
A typical deployment workflow that builds, tags, and deploys:
```yaml
name: deploy
on:
workflow_run:
workflows: [build]
types:
- completed
workflow_dispatch:
jobs:
deploy:
runs-on: ubuntu-22.04
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Update manifest with image tag
run: |
sha="${{ github.sha }}"
shortSha="${sha:0:7}"
echo "Setting image version to: registry.example.com/myapp:${shortSha}"
sed -i "s@###IMAGETAG###@registry.example.com/myapp:${shortSha}@g" ./k8s-deployment.yaml
- name: Deploy to EdgeConnect
uses: https://edp.buildth.ing/DevFW-CICD/edge-connect-deploy-action@main
with:
configFile: ./EdgeConnectConfig.yaml
baseUrl: https://hub.apps.edge.platform.mg3.mdb.osc.live
username: ${{ secrets.EDGEXR_PLATFORM_USERNAME }}
password: ${{ secrets.EDGEXR_PLATFORM_PASSWORD }}
```
### Dry-Run Mode
Preview changes without applying them:
```yaml
- name: Preview deployment
uses: https://edp.buildth.ing/DevFW-CICD/edge-connect-deploy-action@main
with:
configFile: ./EdgeConnectConfig.yaml
dryRun: 'true'
baseUrl: https://hub.apps.edge.platform.mg3.mdb.osc.live
username: ${{ secrets.EDGEXR_PLATFORM_USERNAME }}
password: ${{ secrets.EDGEXR_PLATFORM_PASSWORD }}
```
### Version Pinning
Use a specific EdgeConnect Client version:
```yaml
- name: Deploy with specific version
uses: https://edp.buildth.ing/DevFW-CICD/edge-connect-deploy-action@main
with:
configFile: ./EdgeConnectConfig.yaml
version: 'v2.0.1'
baseUrl: https://hub.apps.edge.platform.mg3.mdb.osc.live
username: ${{ secrets.EDGEXR_PLATFORM_USERNAME }}
password: ${{ secrets.EDGEXR_PLATFORM_PASSWORD }}
```
## 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]
### Sequence Diagrams
[Add sequence diagrams showing key interaction flows with other components]
### Deployment Architecture
[Add infrastructure and deployment diagrams showing how the component is deployed]
* **EdgeConnect Client**: Actions download and execute the Client CLI tool
* **EdgeConnect SDK**: Client uses the SDK for all API interactions
* **Forgejo/GitHub Actions**: Native integration with both action ecosystems
* **EdgeConnect API**: All operations communicate with EdgeConnect platform APIs
* **Container Registries**: Works with any registry for application images
## Configuration
[Key configuration options and how to set them]
### Action Inputs
Both deploy and delete actions accept the same inputs:
| Input | Required | Default | Description |
|-------|----------|---------|-------------|
| `configFile` | Yes | - | Path to EdgeConnectConfig.yaml file |
| `baseUrl` | Yes | - | EdgeConnect API base URL (e.g., https://hub.apps.edge.platform.mg3.mdb.osc.live) |
| `username` | Yes | - | EdgeConnect username for authentication |
| `password` | Yes | - | EdgeConnect password for authentication |
| `dryRun` | No | `false` | Preview changes without applying (set to `'true'` to enable) |
| `version` | No | `v2.0.1` | EdgeConnect Client version to download and use |
### YAML Configuration File
The `configFile` parameter points to an `EdgeConnectConfig.yaml` that defines your application and deployment targets. See the [EdgeConnect Client YAML Configuration Format](/docs/edgeconnect/edgeconnect-client/#yaml-configuration-format) for the complete specification.
Example structure:
```yaml
kind: edgeconnect-deployment
metadata:
name: "my-app"
appVersion: "1.0.0"
organization: "myorg"
spec:
k8sApp:
manifestFile: "./k8s-deployment.yaml"
infraTemplate:
- region: "EU"
cloudletOrg: "TelekomOp"
cloudletName: "Munich"
flavorName: "EU.small"
```
### Secrets Management
Configure repository secrets in Forgejo/GitHub:
1. Navigate to repository Settings → Secrets
2. Add secrets:
- Name: `EDGEXR_PLATFORM_USERNAME`, Value: your EdgeConnect username
- Name: `EDGEXR_PLATFORM_PASSWORD`, Value: your EdgeConnect password
3. Reference in workflows using `${{ secrets.SECRET_NAME }}`
## Troubleshooting
### [Common Issue 1]
### Action Fails with "Failed to download edge-connect-client"
**Problem**: [Description]
**Problem**: Action cannot download the Client binary
**Solution**: [How to fix]
**Solution**:
- Verify the `version` parameter matches an actual release version
- Ensure the release exists at https://edp.buildth.ing/DevFW-CICD/edge-connect-client/releases
- Check network connectivity from the runner
- Try using default version by omitting the `version` parameter
### [Common Issue 2]
### Authentication Errors
**Problem**: [Description]
**Problem**: "authentication failed" or "unauthorized" errors
**Solution**: [How to fix]
**Solution**:
- Verify secrets are correctly configured in repository settings
- Check secret names match exactly (case-sensitive)
- Ensure `baseUrl` is correct for your target environment (Edge vs Orca)
- Confirm credentials work by testing with the [client](../edgeconnect-client/)
### "Configuration validation failed"
**Problem**: YAML configuration file validation errors
**Solution**:
- Verify `configFile` path is correct relative to repository root
- Check YAML syntax is valid (use a YAML validator)
- Ensure all required fields are present (see [Client docs](/docs/edgeconnect/edgeconnect-client/#yaml-configuration-format))
- Verify manifest file paths in the config exist and are correct
### Resources Not Appearing in Console
**Problem**: Action succeeds but resources don't appear in EdgeConnect console
**Solution**:
- Verify you're checking the correct environment (Edge vs Orca)
- Ensure `baseUrl` parameter matches the console you're viewing
- Check organization name in config matches your console access
- Review action logs for any warnings or skipped operations
### Deployment Succeeds but App Doesn't Work
**Problem**: Deployment completes but application is not functioning
**Solution**:
- Check application logs in the EdgeConnect console
- Verify image tags are correct (common issue with placeholder replacement)
- Ensure manifest files reference correct image registry and paths
- Check network configuration allows required outbound connections
- Verify cloudlet has sufficient resources for the specified flavor
## Status
**Maturity**: [Production / Beta / Experimental]
**Maturity**: Production
## Additional Resources
* [Link to external documentation]
* [Link to community resources]
* [Link to related components]
## Documentation Notes
[Instructions for team members filling in this documentation - remove this section once complete]
* [EdgeConnect Client Documentation](/docs/edgeconnect/edgeconnect-client/)
* [EdgeConnect SDK Documentation](/docs/edgeconnect/edgeconnect-sdk/)
* [Terraform Provider Documentation](/docs/edgeconnect/terraform-provider/)
* [EdgeConnect Console](https://hub.apps.edge.platform.mg3.mdb.osc.live/)
* [Demo Repository](https://edp.buildth.ing/DevFW-CICD/edgeconnect-action-demo)
* [Forgejo Actions Documentation](https://forgejo.org/docs/latest/user/actions/)

View file

@ -1,25 +1,11 @@
---
title: "Client"
linkTitle: "Client"
weight: 30
title: EdgeConnect Client
linkTitle: Client
weight: 20
description: >
Client software for establishing EdgeConnect connections
---
{{% alert title="Draft" color="warning" %}}
**Editorial Status**: This page is currently being developed.
* **Jira Ticket**: [TICKET-6734](https://jira.telekom-mms.com/browse/IPCEICIS-6734)
* **Assignee**: Waldemar
* **Status**: Draft
* **Last Updated**: 2025-12-16
* **TODO**:
* [x] Add detailed component description
* [x] Include usage examples and code samples
* [ ] Add architecture diagrams
* [ ] Review and finalize content
{{% /alert %}}
## Overview
The EdgeConnect Client is a command-line tool for managing EdgeConnect applications and instances. It is built using our Golang [SDK](/docs/components/deployments/edgeconnect/edgeconnect-sdk/), and supports functionality to create, destroy, describe and list various resources.

View file

@ -1,25 +1,11 @@
---
title: SDK
title: EdgeConnect SDK
linkTitle: SDK
weight: 10
description: >
Software Development Kit for interacting with EdgeConnect
---
{{% alert title="Draft" color="warning" %}}
**Editorial Status**: This page is currently being developed.
* **Jira Ticket**: [TICKET-6734](https://jira.telekom-mms.com/browse/IPCEICIS-6734)
* **Assignee**: Waldemar
* **Status**: Draft
* **Last Updated**: 2025-12-08
* **TODO**:
* [x] Add detailed component description
* [x] Include usage examples and code samples
* [ ] Add architecture diagrams
* [ ] Review and finalize content
{{% /alert %}}
## Overview
The EdgeConnect SDK is a Go library which provides a simple method for interacting with Edge Connect within programs. It is designed to be used by other tools, such as the [EdgeConnect Client](/docs/components/deployments/edgeconnect/edgeconnect-client/) or [Terraform provider](/docs/components/orchestration/infrastructure/provider/),

View file

@ -1,24 +1,10 @@
---
title: Terraform provider for Edge cloud
linkTitle: Terraform provider
weight: 20
weight: 30
description: Custom Terraform provider for orchestrating Edge deployments
---
{{% alert title="Draft" color="warning" %}}
**Editorial Status**: Mostly ready
* **Jira Ticket**: [TICKET-6732](https://jira.telekom-mms.com/browse/IPCEICIS-6732)
* **Assignee**: Martin
* **Status**: Draft
* **Last Updated**: 2025-12-04
* **TODO**:
* [x] Add detailed component description
* [x] Include usage examples and code samples (NOTE: links to docs, rather than inline refs)
* [x] Add architecture diagrams
* [ ] Review and finalize content
{{% /alert %}}
## Overview
This work-in-progress Terraform provider for Edge cloud allows orchestration of selected resources using flexible, concise [HCL](https://developer.hashicorp.com/terraform/language). This allows deployment to Edge Cloud through a familiar format, abstracting away specific endpoints and authentication elements, and allowing seamless combination of Edge resources with others: on OTC, other clouds, or local utilities.

View file

@ -3,7 +3,7 @@ title: Edge Developer Platform
linkTitle: Edge Developer Platform
weight: 10
description: >
High-level overview of the Edge Developer Platform (EDP), its purpose, and product structure.
A platform to support developers working in the Edge, based around Forgejo
---
{{% alert title="Draft" color="warning" %}}