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

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

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

1. Download the Edge Connect Client binary from the Forgejo releases page 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

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

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

Additional Resources

• EdgeConnect SDK Documentation
• Edge Cloud: Console | API Docs
• Orca Cloud: Console | API Docs
• Source Code Repository