From 927fc778d55a06cc1f00033f6172559040ca4d9a Mon Sep 17 00:00:00 2001 From: Martin McCaffery Date: Tue, 16 Dec 2025 16:37:19 +0100 Subject: [PATCH] feat(edgeconnect): Add docs for SDK and EdgeConnect client --- content/en/docs/components/TEMPLATE.md | 141 ---------- .../deployments/edgeconnect/_index.md | 118 ++------- .../edgeconnect/edgeconnect-client.md | 246 ++++++++++++++---- .../edgeconnect/edgeconnect-sdk.md | 8 +- 4 files changed, 213 insertions(+), 300 deletions(-) delete mode 100644 content/en/docs/components/TEMPLATE.md diff --git a/content/en/docs/components/TEMPLATE.md b/content/en/docs/components/TEMPLATE.md deleted file mode 100644 index 77eee23..0000000 --- a/content/en/docs/components/TEMPLATE.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: "[Component Name]" -linkTitle: "[Short Name]" -weight: 1 -description: > - [Brief one-line description of the component] ---- - -{{% 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] - -## Key Features - -* [Feature 1] -* [Feature 2] -* [Feature 3] - -## Purpose in EDP - -[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities] - -## Repository - -**Code**: [Link to source code repository] - -**Documentation**: [Link to component-specific documentation] - -## Getting Started - -### Prerequisites - -* [Prerequisite 1] -* [Prerequisite 2] - -### Quick Start - -[Step-by-step guide to get started with this component] - -1. [Step 1] -2. [Step 2] -3. [Step 3] - -### 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] - -### C4 charts - -Embed C4 charts this way: - -1. add a likec4-view with the name of the view -{{< likec4-view view="components-template-documentation" project="architecture" title="Example Documentation Diagram" >}} - -2. create the LikeC4 view somewhere in ```./resources/edp-likec4/views```, the example above is in ```./resources/edp-likec4/views/documentation/components-template-documentation.c4``` - -3. run ```task likec4:generate``` to create the webcomponent - -4. if you are in ```task:serve``` hot-reload mode the view will show up directly - -### 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] - -## Configuration - -[Key configuration options and how to set them] - -## Troubleshooting - -### [Common Issue 1] - -**Problem**: [Description] - -**Solution**: [How to fix] - -### [Common Issue 2] - -**Problem**: [Description] - -**Solution**: [How to fix] - -## Status - -**Maturity**: [Production / Beta / Experimental] - -## 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] diff --git a/content/en/docs/components/deployments/edgeconnect/_index.md b/content/en/docs/components/deployments/edgeconnect/_index.md index d31bd74..5080786 100644 --- a/content/en/docs/components/deployments/edgeconnect/_index.md +++ b/content/en/docs/components/deployments/edgeconnect/_index.md @@ -12,117 +12,41 @@ description: > * **Jira Ticket**: [TICKET-6734](https://jira.telekom-mms.com/browse/IPCEICIS-6734) * **Assignee**: Waldemar * **Status**: Draft -* **Last Updated**: YYYY-MM-DD +* **Last Updated**: 2025-12-16 * **TODO**: - * [ ] Add detailed component description - * [ ] Include usage examples and code samples - * [ ] Add architecture diagrams + * [x] Add detailed component description * [ ] Review and finalize content {{% /alert %}} ## Overview -[Detailed description of the component - what it is, what it does, and why it exists] +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). ## Key Features -* [Feature 1] -* [Feature 2] -* [Feature 3] +* 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 + + +SYSTEM IS NOT ACTUALLY DEPLOYED HERE +JUST RUNNERS, CODER, individual components ## Purpose in EDP -[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities] +Working with EdgeConnect allows us to ensure our work supports that of our colleagues, ultimately leading to a platform that is as broadly and deeply usable as possible. By working in a sovereign system we are encouraging European development, while sustainability features are offered by very few other clouds. It also gives us possibilities to work closely with other teams, ensuring both teams' work is better than would be possible otherwise. -## Repository +### Access -**Code**: [Link to source code repository] +* [Gardener console access](https://gardener.apps.mg3.mdb.osc.live/namespace/garden-platform/shoots) + - Choose `Log in with mg3` then `platform` before entering credentials set up by the Platform Team. +* [Edge cluster](https://hub.apps.edge.platform.mg3.mdb.osc.live/) +* [Orca cluster](https://hub.apps.orca.platform.mg3.mdb.osc.live/) -**Documentation**: [Link to component-specific documentation] -## Getting Started +### Notes -### Prerequisites - -* [Prerequisite 1] -* [Prerequisite 2] - -### Quick Start - -[Step-by-step guide to get started with this component] - -1. [Step 1] -2. [Step 2] -3. [Step 3] - -### 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] - -### 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] - -## Configuration - -[Key configuration options and how to set them] - -## Troubleshooting - -### [Common Issue 1] - -**Problem**: [Description] - -**Solution**: [How to fix] - -### [Common Issue 2] - -**Problem**: [Description] - -**Solution**: [How to fix] - -## Status - -**Maturity**: [Production / Beta / Experimental] - -## 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] +Documentation for Edge Connect is provided using other systems, including Confluence. \ No newline at end of file diff --git a/content/en/docs/components/deployments/edgeconnect/edgeconnect-client.md b/content/en/docs/components/deployments/edgeconnect/edgeconnect-client.md index 7c08aca..dec365e 100644 --- a/content/en/docs/components/deployments/edgeconnect/edgeconnect-client.md +++ b/content/en/docs/components/deployments/edgeconnect/edgeconnect-client.md @@ -12,117 +12,249 @@ description: > * **Jira Ticket**: [TICKET-6734](https://jira.telekom-mms.com/browse/IPCEICIS-6734) * **Assignee**: Waldemar * **Status**: Draft -* **Last Updated**: YYYY-MM-DD +* **Last Updated**: 2025-12-16 * **TODO**: - * [ ] Add detailed component description - * [ ] Include usage examples and code samples + * [x] Add detailed component description + * [x] 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 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. + +The tool provides both imperative commands (for direct resource management) and declarative workflows (using YAML configuration files) to deploy applications across multiple edge cloudlets. It supports different EdgeConnect deployment environments through an API version selector. ## Key Features -* [Feature 1] -* [Feature 2] -* [Feature 3] +* **Dual workflow support**: Imperative commands for direct operations, declarative YAML for infrastructure-as-code +* **Multi-cloudlet deployment**: Deploy applications to multiple edge locations from a single configuration +* **Deployment planning**: Preview and approve changes before applying them (dry-run mode) +* **Environment compatibility**: Works with different EdgeConnect deployment environments (configured via `api-version`) +* **CI/CD ready**: Designed for automated deployments with auto-approve and exit codes ## Purpose in EDP -[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities] +No system can be considered useful unless it is actually, in practice, used. While the Edge Connect [console](https://hub.apps.edge.platform.mg3.mdb.osc.live/) and [API](https://swagger.edge.platform.mg3.mdb.osc.live/) are essential tools to allow the platform to be used by developers, there are numerous use cases for interaction that is automated but simpler to use than an API. + +The EdgeConnect Client bridges the gap between manual console operations and direct API integration, enabling automated deployments in CI/CD pipelines, infrastructure-as-code workflows, and scripted operations while maintaining simplicity and usability. ## Repository -**Code**: [Link to source code repository] +**Code**: https://edp.buildth.ing/DevFW-CICD/edge-connect-client -**Documentation**: [Link to component-specific documentation] +**Releases**: https://edp.buildth.ing/DevFW-CICD/edge-connect-client/releases ## Getting Started ### Prerequisites -* [Prerequisite 1] -* [Prerequisite 2] +* Access credentials for the EdgeConnect platform (username and password) +* Knowledge of your target deployment environment (determines `api-version` setting) +* For Kubernetes deployments: K8s manifest files +* For Docker deployments: Docker image reference ### Quick Start -[Step-by-step guide to get started with this component] - -1. [Step 1] -2. [Step 2] -3. [Step 3] +1. Download the Edge Connect Client binary from the Forgejo [releases page](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/releases) for your platform (Linux, macOS, or Windows) +2. Extract and move to your PATH: `tar -xzf edge-connect-client_*.tar.gz && sudo mv edge-connect /usr/local/bin/` +3. Configure authentication using environment variables or a config file (see Configuration section) +4. Verify installation: `edge-connect --help` ### Verification -[How to verify the component is working correctly] +Run `edge-connect app list --org --region ` to verify you can authenticate and communicate with the EdgeConnect API. ## Usage Examples -### [Use Case 1] +### Declarative Deployment (Recommended) -[Example with code/commands showing common use case] +Create an `EdgeConnectConfig.yaml` file defining your application and deployment targets, then apply it: ```bash -# Example commands +edge-connect apply -f EdgeConnectConfig.yaml ``` -### [Use Case 2] +Use `--dry-run` to preview changes without applying them, and `--auto-approve` for automated CI/CD workflows. -[Another common scenario] +### Imperative Commands + +Direct resource management using CLI commands: + +```bash +# Create an application +edge-connect app create --org myorg --name myapp --version 1.0.0 --region EU + +# Create an instance on a specific cloudlet +edge-connect instance create --org myorg --name myinstance \ + --app myapp --version 1.0.0 --region EU \ + --cloudlet Munich --cloudlet-org TelekomOp --flavor EU.small + +# List resources +edge-connect app list --org myorg --region EU +edge-connect instance list --org myorg --region EU + +# Delete resources +edge-connect instance delete --org myorg --name myinstance --region EU \ + --cloudlet Munich --cloudlet-org TelekomOp +edge-connect app delete --org myorg --name myapp --version 1.0.0 --region EU +``` ## 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 API**: Communicates with EdgeConnect platform APIs for all resource operations +* **EdgeConnect SDK**: Built on top of the Golang SDK, sharing authentication and client implementation +* **CI/CD Pipelines**: Designed for integration with GitLab CI, GitHub Actions, and other automation tools +* **Infrastructure-as-Code**: YAML configuration files enable GitOps workflows ## Configuration -[Key configuration options and how to set them] +### Global Settings + +The client can be configured via config file, environment variables, or command-line flags (in order of precedence: flags > env vars > config file). + +**Config File** (`~/.edge-connect.yaml` or use `--config` flag): + +```yaml +base_url: "https://hub.apps.edge.platform.mg3.mdb.osc.live" +username: "your-username@example.com" +password: "your-password" +api_version: "v2" # v1 or v2 - identifies deployment environment +``` + +**Environment Variables**: + +- `EDGE_CONNECT_BASE_URL`: API base URL +- `EDGE_CONNECT_USERNAME`: Authentication username +- `EDGE_CONNECT_PASSWORD`: Authentication password +- `EDGE_CONNECT_API_VERSION`: API version selector (v1 or v2, default: v2) + +**Global Flags** (available on all commands): + +- `--base-url`: API base URL +- `--username`: Authentication username +- `--password`: Authentication password +- `--api-version`: API version selector (v1 or v2) - specifies which deployment environment to target +- `--config`: Path to config file +- `--debug`: Enable debug logging + +**Note on API Versions**: The `api-version` setting (v1 or v2) is an internal label used to distinguish between different EdgeConnect deployment environments, not an official API version designation from the platform. + +### Commands + +**App Management** (`edge-connect app `): + +CLI command `app` corresponds to **App** in the platform console. + +- `create`: Create app (flags: `--org`, `--name`, `--version`, `--region`) +- `show`: Show app details (flags: same as create) +- `list`: List apps (flags: `--org`, `--region`, optional: `--name`, `--version`) +- `delete`: Delete app (flags: `--org`, `--name`, `--version`, `--region`) + +**App Instance Management** (`edge-connect instance `): + +CLI command `instance` corresponds to **App Instance** in the platform console. + +- `create`: Create app instance (flags: `--org`, `--name`, `--app`, `--version`, `--region`, `--cloudlet`, `--cloudlet-org`, `--flavor`) +- `show`: Show app instance details (flags: `--org`, `--name`, `--cloudlet`, `--cloudlet-org`, `--region`, `--app-id`) +- `list`: List app instances (flags: same as show, all optional) +- `delete`: Delete app instance (flags: `--org`, `--name`, `--cloudlet`, `--cloudlet-org`, `--region`) + +**Declarative Operations**: + +- `apply`: Deploy from YAML (flags: `-f `, `--dry-run`, `--auto-approve`) +- `delete`: Delete from YAML (flags: `-f `, `--dry-run`, `--auto-approve`) + +### YAML Configuration Format + +The `EdgeConnectConfig.yaml` file defines apps and their deployment targets: + +```yaml +kind: edgeconnect-deployment +metadata: + name: "my-app" # App name (required) + appVersion: "1.0.0" # App version (required) + organization: "myorg" # Organization (required) + +spec: + # Choose ONE: k8sApp OR dockerApp + k8sApp: + manifestFile: "./k8s-deployment.yaml" # Path to K8s manifest + + # OR dockerApp: + # image: "registry.example.com/myimage:tag" + # manifestFile: "./docker-compose.yaml" # Optional + + # Deployment targets (at least one required) + infraTemplate: + - region: "EU" # Region (required) + cloudletOrg: "TelekomOp" # Cloudlet provider (required) + cloudletName: "Munich" # Cloudlet name (required) + flavorName: "EU.small" # Instance size (required) + - region: "US" + cloudletOrg: "TelekomOp" + cloudletName: "gardener-shepherd-test" + flavorName: "default" + + # Optional network configuration + network: + outboundConnections: + - protocol: "tcp" # tcp, udp, or icmp + portRangeMin: 80 + portRangeMax: 80 + remoteCIDR: "0.0.0.0/0" + - protocol: "tcp" + portRangeMin: 443 + portRangeMax: 443 + remoteCIDR: "0.0.0.0/0" + + # Optional deployment strategy (default: recreate) + deploymentStrategy: "recreate" # recreate, blue-green, or rolling +``` + +**Key Points**: +- Manifest file paths are relative to the config file location +- Multiple `infraTemplate` entries deploy to multiple cloudlets simultaneously +- Network configuration is optional; outbound connections default to platform settings +- Deployment strategy currently only supports "recreate" (others planned) ## Troubleshooting -### [Common Issue 1] +### Authentication Failures -**Problem**: [Description] +**Problem**: Errors like "authentication failed" or "unauthorized" -**Solution**: [How to fix] +**Solution**: +- Verify credentials are correct in config file or environment variables +- Ensure `base_url` includes the scheme (https://) and has no trailing path +- Check that you're connecting to the correct cloud instance (Edge or Orca) +- Ensure the correct `api-version` is set for your deployment environment -### [Common Issue 2] +### "Configuration validation failed" Errors -**Problem**: [Description] +**Problem**: YAML configuration file validation errors -**Solution**: [How to fix] +**Solution**: +- Check that all required fields are present (name, appVersion, organization) +- Ensure you have exactly one of `k8sApp` or `dockerApp` (not both, not neither) +- Verify manifest file paths exist relative to the config file location +- Check for leading/trailing whitespace in string values +- Ensure at least one `infraTemplate` entry is defined + +### Wrong API Version or Cloud Instance + +**Problem**: Commands work but resources don't appear in the console, or vice versa + +**Solution**: Verify both the `base_url` and `api-version` match your target environment. There are two cloud instances (Edge and Orca) with different URLs and API versions. Check with your platform administrator for the correct configuration. ## 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 SDK Documentation](/docs/components/deployments/edgeconnect/edgeconnect-sdk/) +* **Edge Cloud**: [Console](https://hub.apps.edge.platform.mg3.mdb.osc.live/) | [API Docs](https://swagger.edge.platform.mg3.mdb.osc.live/) +* **Orca Cloud**: [Console](https://hub.apps.orca.platform.mg3.mdb.osc.live/) | [API Docs](https://swagger.orca.platform.mg3.mdb.osc.live/) +* [Source Code Repository](https://edp.buildth.ing/DevFW-CICD/edge-connect-client) diff --git a/content/en/docs/components/deployments/edgeconnect/edgeconnect-sdk.md b/content/en/docs/components/deployments/edgeconnect/edgeconnect-sdk.md index 1b215b1..cf91227 100644 --- a/content/en/docs/components/deployments/edgeconnect/edgeconnect-sdk.md +++ b/content/en/docs/components/deployments/edgeconnect/edgeconnect-sdk.md @@ -14,8 +14,8 @@ description: > * **Status**: Draft * **Last Updated**: 2025-12-08 * **TODO**: - * [ ] Add detailed component description - * [ ] Include usage examples and code samples + * [x] Add detailed component description + * [x] Include usage examples and code samples * [ ] Add architecture diagrams * [ ] Review and finalize content {{% /alert %}} @@ -38,8 +38,6 @@ While each such tool could simply independently wrap existing endpoints, this is To avoid this, the Edge Connect SDK aims to provide a common library for interacting with EdgeConnect, allowing the abstraction of HTTP requests and authentication procedures while nonetheless allowing access directly to the endpoints available. -[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities] - ## Repository **Code**: https://edp.buildth.ing/DevFW-CICD/edge-connect-client @@ -73,7 +71,7 @@ See [README](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/m ### Varying code versions -**Problem**: While the Edge Connect API does not (at time of writing) have different semantic versions, it does have different iterations which function differently. The SDK provides two different libraries, labelled [v1](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/sdk/edgeconnect) and [v2](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/sdk/edgeconnect/v2). +**Problem**: While the Edge Connect API does not (at time of writing) have different semantic versions, it does have different iterations which function differently. The SDK provides two different libraries, labelled [v1](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/sdk/edgeconnect) and [v2](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/sdk/edgeconnect/v2) and referring to API definitions similarly stored as [v1](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/api/swagger_v1.json) and [v2](https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/api/swagger_v2.json). **Solution**: If you receive errors when using the SDK, consider changing the version you import: ```go