---
title: EdgeConnect Client
linkTitle: Client
weight: 20
description: >
  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](/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

* **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](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**: 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](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

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:

```bash
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:

```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

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

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

```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

### 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](/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)
