website-and-documentation/content/en/docs/edgeconnect/edgeconnect-client.md at 41e33069423fa8f4007d2b6987a22a354410ee24

Patrick.Sy/website-and-documentation

Fork 0

forked from DevFW-CICD/website-and-documentation

Martin McCaffery 41e3306942

feat(docs): Restructure entire documentation

2025-12-18 10:25:07 +01:00

11 KiB

Raw Blame History

title	linkTitle	weight	description
Client	Client	30	Client software for establishing EdgeConnect connections

{{% alert title="Draft" color="warning" %}} Editorial Status: This page is currently being developed.

Jira Ticket: TICKET-6734
Assignee: Waldemar
Status: Draft
Last Updated: 2025-12-16
TODO:
- Add detailed component description
- 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, 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

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

No system can be considered useful unless it is actually, in practice, used. While the Edge Connect console and API 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: https://edp.buildth.ing/DevFW-CICD/edge-connect-client

Releases: https://edp.buildth.ing/DevFW-CICD/edge-connect-client/releases

Getting Started

Prerequisites

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

Download the Edge Connect Client binary from the Forgejo releases page for your platform (Linux, macOS, or Windows)
Extract and move to your PATH: tar -xzf edge-connect-client_*.tar.gz && sudo mv edge-connect /usr/local/bin/
Configure authentication using environment variables or a config file (see Configuration section)
Verify installation: edge-connect --help

Verification

Run edge-connect app list --org <your-org> --region <region> to verify you can authenticate and communicate with the EdgeConnect API.

Usage Examples

Declarative Deployment (Recommended)

Create an EdgeConnectConfig.yaml file defining your application and deployment targets, then apply it:

edge-connect apply -f EdgeConnectConfig.yaml

Use --dry-run to preview changes without applying them, and --auto-approve for automated CI/CD workflows.

Imperative Commands

Direct resource management using CLI commands:

# 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

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

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):

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 <command>):

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 <command>):

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 <file>, --dry-run, --auto-approve)
delete: Delete from YAML (flags: -f <file>, --dry-run, --auto-approve)

YAML Configuration Format

The EdgeConnectConfig.yaml file defines apps and their deployment targets:

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

Authentication Failures

Problem: Errors like "authentication failed" or "unauthorized"

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

"Configuration validation failed" Errors

Problem: YAML configuration file validation errors