CLIs

Control Plane CLI Tools

Command-line tools for interacting with and managing the Control Plane

CLI Overview

Command-line tools

The Control Plane provides several command-line tools that help users interact with the platform, test configurations, and manage resources.

These tools are designed to simplify common tasks and provide efficient interfaces for developers and operators working with the Control Plane.

Available CLI Tools

Rover-CTL

The primary CLI tool for managing and interacting with the Rover control plane. It provides a user-friendly way to perform operations such as applying configurations, retrieving information, and managing resources within the Rover ecosystem.

Key capabilities:

• Apply configurations
• Manage resources
• Retrieve information

Route-Tester

A utility tool for testing if a Route is correctly configured. It functions as an automated version of `curl`, making it easy to verify API routes.

Key capabilities:

• Test route configurations
• Validate API endpoints
• Automated API testing

Snapshotter

A tool designed to create snapshots of the current state of the system, primarily for the gateway-domain. Useful for tracking changes and comparing configurations over time.

Key capabilities:

• Create state snapshots
• Compare configurations
• Track system changes

Rover-CTL

Primary Control Plane CLI

Rover-CTL is the primary command-line interface for the Control Plane, providing comprehensive management capabilities.

About Rover-CTL

Rover Control CLI (roverctl) is a command-line tool for managing rover resources via the REST API. It handles configuration files and maps them to the appropriate resource handlers.

Installation

From Source

To build and install roverctl from source, follow these steps:

1. Clone the repository:

   git clone github.com/telekom/controlplane.git
   cd controlplane/rover-ctl

2. Build the binary:

   make build

3. Install the binary:

   make install

Configuration

Rover-ctl can be configured using environment variables. The tool uses Viper for configuration management with the following options:

Environment Variables

All environment variables are prefixed with ROVER_ and use underscores instead of dots for nested keys. For example, server.url becomes ROVER_SERVER_URL.

Environment Variable	Description	Default
ROVER_SERVER_URL	URL of the Rover server	-
ROVER_TOKEN_URL	URL for token authentication	-
ROVER_TOKEN	Authentication token	-
ROVER_LOG_LEVEL	Log level (debug, info, warn, error)	info
ROVER_LOG_FORMAT	Log format (json or console)	console
ROVER_OUTPUT_FORMAT	Output format (yaml or json)	yaml

Authentication

The CLI uses token-based authentication to interact with the Rover server. The token is a base64-encoded JSON object with the following structure:

{
  "environment": "required",
  "group": "required",
  "team": "required",
  "client_id": "required",
  "client_secret": "required",
  "token_url": "required URL",
  "server_url": "required URL",
  "generated_at": 1692345678000
}

The token can be set using the ROVER_TOKEN environment variable or through a configuration file.

Route-Tester

API testing utility

Route-Tester provides a simple way to verify that your routes are correctly configured.

About Route-Tester

The Route-Testing tool can be used to test if a Route is correctly configured. It's essentially an automated version of curl that simplifies API endpoint testing.

Installation

go build -o bin/rt main.go
install -m 0755 bin/rt /usr/local/bin/rt

Usage

Run the tool with:

rt --app rover-sample-consumer --basepath /eni/foo/v2 --team sample-team --env poc | jq 

Snapshotter

System state management

Snapshotter helps track and compare system configurations over time.

About Snapshotter

The Snapshotting Tool is intended to create snapshots of the current state of the system, mainly for the gateway-domain. It helps track changes and ensure consistency across deployments.

Installation

go build -o bin/snapshotter main.go
install -m 0755 bin/snapshotter /usr/local/bin/snapshotter

Configuration

This tool can either be configured via environment variables or flags.

Using a .env file:

GATEWAY_ENV="poc"
GATEWAY_ZONE="dataplane1"
GATEWAY_ROUTE="poc--my-route-v1"
GATEWAY_ADMIN_URL="https://<host>/admin-api>"
GATEWAY_ADMIN_CLIENT_ID="<client-id>"
GATEWAY_ADMIN_CLIENT_SECRET="<client-secret>"
GATEWAY_ADMIN_ISSUER="<issuer-url>"

Usage

Run with environment configuration:

snapshotter --from-env

Or using automatic setup via flags:

snapshotter --env poc --zone dataplane1 --route poc--my-route-v1

Features

1. By default, this tool outputs a snapshot in YAML format to ./snapshots/. You can change the output directory using the --output-dir flag.

2. If the snapshot file doesn't exist, it will be created with no further action.

3. If the snapshot file already exists, it compares the current state with the snapshot and outputs the differences to the console.

Related Pages

• Components: Learn about the core components of the Control Plane
• Architecture: See how CLIs fit into the overall system design
• Installation: Get started with installing the Control Plane