From 48a9eed862cb8178c71a2166f53fd1f6af677c58 Mon Sep 17 00:00:00 2001 From: Martin McCaffery Date: Thu, 18 Dec 2025 11:51:41 +0100 Subject: [PATCH] feat(actions): add docs for EdgeConnect Actions --- content/en/docs/edgeconnect/_index.md | 22 +- .../docs/edgeconnect/edgeconnect-actions.md | 302 +++++++++++++----- .../en/docs/edgeconnect/edgeconnect-client.md | 20 +- .../en/docs/edgeconnect/edgeconnect-sdk.md | 16 +- .../en/docs/edgeconnect/terraform-provider.md | 16 +- content/en/docs/edp/_index.md | 2 +- 6 files changed, 241 insertions(+), 137 deletions(-) diff --git a/content/en/docs/edgeconnect/_index.md b/content/en/docs/edgeconnect/_index.md index 3a067c3..54ad6b1 100644 --- a/content/en/docs/edgeconnect/_index.md +++ b/content/en/docs/edgeconnect/_index.md @@ -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 diff --git a/content/en/docs/edgeconnect/edgeconnect-actions.md b/content/en/docs/edgeconnect/edgeconnect-actions.md index e5c0f60..31712f5 100644 --- a/content/en/docs/edgeconnect/edgeconnect-actions.md +++ b/content/en/docs/edgeconnect/edgeconnect-actions.md @@ -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/) diff --git a/content/en/docs/edgeconnect/edgeconnect-client.md b/content/en/docs/edgeconnect/edgeconnect-client.md index 02ab2ab..1e254ea 100644 --- a/content/en/docs/edgeconnect/edgeconnect-client.md +++ b/content/en/docs/edgeconnect/edgeconnect-client.md @@ -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. diff --git a/content/en/docs/edgeconnect/edgeconnect-sdk.md b/content/en/docs/edgeconnect/edgeconnect-sdk.md index df3c71a..013eec1 100644 --- a/content/en/docs/edgeconnect/edgeconnect-sdk.md +++ b/content/en/docs/edgeconnect/edgeconnect-sdk.md @@ -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/), diff --git a/content/en/docs/edgeconnect/terraform-provider.md b/content/en/docs/edgeconnect/terraform-provider.md index f7efe13..b6bc371 100644 --- a/content/en/docs/edgeconnect/terraform-provider.md +++ b/content/en/docs/edgeconnect/terraform-provider.md @@ -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. diff --git a/content/en/docs/edp/_index.md b/content/en/docs/edp/_index.md index b2c2aac..be9635e 100644 --- a/content/en/docs/edp/_index.md +++ b/content/en/docs/edp/_index.md @@ -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" %}}