Skip to main content

Onboarding

This guide walks you through getting started as an application team on the Control Plane. Before you can expose APIs, subscribe to services, or publish events, your team needs to be onboarded to the platform.

Prerequisites​

Before you begin, make sure a platform administrator has:

  • Created an Environment for you to work in (for example, dev)
  • Created a Group and Team for your team within that environment

If you are unsure whether your team has been set up, contact your platform administrator.

What Happens When Your Team Is Created​

When a platform administrator creates your team, the Control Plane automatically provisions the following resources for you:

  • A dedicated namespace in the Kubernetes cluster, following the pattern {environment}--{group}--{team}
  • An Identity Client — your team's service account for authenticating with the platform
  • A Gateway Consumer — grants your team access to APIs through the gateway
  • A Notification Channel — so you receive platform notifications (approvals, token rotations, etc.)

You will receive an onboarding notification with your team credentials once this provisioning is complete.

Setting Up Rover-CTL​

Rover-CTL is the command-line tool for interacting with the Control Plane. It lets you apply Rover files, manage API configurations, and check the status of your resources.

tip

For a complete list of all available commands and options, see the Rover-CTL CLI Reference.

Installation​

Download the latest release of Rover-CTL from the project repository and add it to your PATH:

curl -LO https://github.com/telekom/controlplane/releases/latest/download/roverctl_Linux_x86_64.tar.gz
tar -xzf roverctl_Linux_x86_64.tar.gz
sudo mv roverctl /usr/local/bin/
note

The command above is for Linux (x86_64). For Windows, download roverctl_Windows_x86_64.zip from the releases page instead.

Authentication​

Rover-CTL authenticates using a Team Token — a base64-encoded JSON structure containing your environment, group, team, and client credentials. Set it as an environment variable:

export ROVER_TOKEN="<your-base64-encoded-team-token>"

Additional configuration options:

VariableDescription
ROVER_TOKENYour team's authentication token
RESOURCE_PATHOptional base directory for relative --file/-f paths. May be relative to the current directory or absolute. Absolute --file paths are not affected. If both RESOURCE_PATH and ROVER_RESOURCE_PATH are unset or empty, paths are resolved relative to the current directory. If ROVER_RESOURCE_PATH is set and nonempty, it takes priority over RESOURCE_PATH.

For example, if ROVER_RESOURCE_PATH is not set, the following applies ./resources/api.yaml:

RESOURCE_PATH=./resources roverctl apply -f api.yaml

Verify Your Setup​

To confirm that Rover-CTL is correctly configured and can reach the platform:

roverctl get-info

This should return a list of your team's existing Rover resources (which will be empty if you are starting fresh).

Troubleshooting Token Errors​

If Rover-CTL reports that ROVER_TOKEN is invalid or incomplete, check that you copied the entire team token and that you are using the token for the correct environment. If the problem persists, obtain a new team token.

For troubleshooting, run the command again with --debug. For token errors, the error log then also shows which part of the token could not be decoded or validated, for example a missing field or an invalid URL. These token diagnostics do not include the token contents, credentials or URL values.

Request failures are reported by HTTP method, resource type, a failure category (such as authentication, timeout or connection) and the HTTP status code. Rover-CTL does not add request payloads or credentials to these error messages, and messages for connection-level failures do not include request URLs. With --debug, request URLs may be logged.

If the server returns a structured error (problem details), its fields, including type, title, detail, instance and field errors, are shown as returned, for example ApiCategory "Test" not found. These fields may contain request-specific information. Other server responses, such as HTML or plain-text bodies, are omitted.

Review any output before sharing it: other parts of the output, such as the result of roverctl get-secret, intentionally contain credentials.

Next Steps​