Welcome to Telekube, by Gravitational. Telekube allows developers to package and deploy their complex multi-node, multi-tier application clusters into a variety of target infrastructure options, such as their own AWS accounts, 3rd party AWS accounts or even into air-gapped, bare metal server clusters.

Telekube uses Google's Kubernetes as a portable cluster runtime and allows ops teams to remotely manage many instances of a cluster either via SSH or via Kubernetes API, even if they are located behind a firewall.

This overview will walk you through the basic concepts of Telekube and explain how it is used to solve the operational challenges that arise in the use cases below.

If you already have a good understanding of Telekube you can choose to jump right in with our Quick Start guide or dive deeper into Telekube documentation through the table of contents.

Use Cases

There are two primary use cases for Telekube:

  1. Private SaaS: Software vendors (including SaaS applications) often need to deploy their complex software into private datacenters or 3rd party cloud accounts owned by their enterprise customers. Telekube allows them to snapshot, publish and distribute updates to the enterprise customers.

  2. Multi-Region Kubernetes: Ops teams in large companies with many distributed product teams often need to provide Kubernetes-as-a-Service within their organization across multiple hosting regions and multiple hosting providers. Telekube allows them to pre-package supported Kubernetes configurations into "applications" and streamline their management and cross-organizational trust.

In both use cases, an application usually includes the Kubernetes binaries, their dependencies, a private Docker registry for autonomous operation, a monitoring system and an SSH bastion for remotely managing the cluster either via simple SSH or via Kubernetes API.

Application Lifecycle

A Telekube application is a snapshot of a Kubernetes cluster, stored as a compressed .tar file ("Application Bundle" or "Application"). Application Bundles may contain nothing but pre-packaged Kubernetes for centralized management of Kubernetes resources within an organization or may also contain other applications running on Kubernetes. This allows a user to replicate complex cloud native stacks in multiple environments.

The typical application lifecycle using Telekube consists of the following:

  1. Prepare your application to run on Kubernetes. If you do not have Kubernetes expertise, our Implementation Services team can help.
  2. Package the application into a deployable tar tarball ("Application Bundle" or "Bundle").
  3. Publish the Application Bundle for distribution.
  4. Deploy and install the Application Bundle onto Linux based server cluster ("Telekube Cluster" or "Cluster").
  5. Securely connect to any Cluster to monitor health and roll out updates.


Telekube works only with applications running on Kubernetes. This means the following prerequisites apply in order to use Telekube:

  • The application is packaged into containers.
  • You have Kubernetes resource definitions for application services, pods, etc.

To prepare a Kubernetes application for distribution via Telekube, you have to write an Application Manifest. Below is a sample of a simple Application Manifest in YAML format. It follows Kubernetes configuration conventions:

kind: Bundle
  name: telekube
  resourceVersion: "1.0.0"

# Applications can be white-labeled with vendor's look and feel.
logo: ""

# An application can be configured with multiple "flavors", perhaps letting
# the end user of a cluster to customize its shape and size.
    prompt: "Select a flavor"
      - name: "one"
        description: "1 node"
          - profile: node
            count: 1

# An application must define its system requirements, i.e. if an application
# needs certain amounts of RAM/CPU/storage to run, they can be listed here.
  - name: node
    description: "worker node"
        min: 1
        min: "2GB"

The sample above is intentionally simplistic to illustrate the concept. The Applicaion Manifest's purpose is to describe the infrastructure requirements and custom steps required for installing the Bundle and updating the Cluster.

The Application Manifest works in conjunction with Kubernetes jobs and configuration maps. Together, these tools provide a high degree of flexibility for specifying how applications are installed, updated and configured. You can learn more about the Application Manifest in the Packaging & Deployment section of the documentation.

As shown in the diagram below, the build machine (often times a developer's laptop or a CI/CD server) should contain everything needed to build a self-sufficient portable package to distribute the Application Bundle:

Telekube Build Diagram

Telekube's build command creates the Application Bundle tarball:

$ tele build -o app-name.tar app.yaml

This will produce a self-sufficient tarball, app-name.tar, which can be deployed across cloud providers, or onto infrastructure like private data centers or private clouds.


Publishing can be as simple as uploading the Application Bundle to an S3 bucket for others to download and install.

Another option is to publish the Application Bundle into the Telekube "Ops Center", a centralized repository of your Application Bundles and its deployed Clusters. If an Application Bundle is distributed via the Ops Center, the resulting Cluster can optionally "phone home" for automating updates, remote monitoring and trouble shooting.

The Ops Center allows Application Bundle publishers to oversee how many Clusters are running and perform administration and maitenance across all of them in a repeatable, scalable way, even if they are deployed on 3rd party infrastructure.

Deploying and Installing

Once an Application Bundle is deployed and installed it becomes a fully operational, autonomous, self-regulating and self-updating Kubernetes cluster ("Telekube Cluster" or "Cluster"). All Clusters can optionally "phone home" to a centralized control plane ("Ops Center") and be remotely managed.

The Telekube Ops Center supports two methods for deploying Application Bundles:

  • Online Installation: The Ops Center generates a URL to an installer which can be shared with users to install the application into their infrastructure. When using online mode, the Cluster can be remotely managed and updated.

  • Offline Installation: The Application Bundle can be simply copied to the target infrastructure. This infrastructure could even be air-gapped and not connected to the Internet. The end user can then unpack the Application Bundle and launch a self-contained installer.

In either mode, the Telekube installer can run as a command line (CLI) tool or by opening a browser-based graphical installation wizard.

Online Installation

The online installation allows you to generate a URL to a web-based installer. The URL can be distributed to the end users for them to install the Application Bundle.

  • First, the Application Bundle is published into the Ops Center.
  • Then the Application Bundle is deployed into private infrastructure by using the installation URL.
  • Once the Cluster is up and running, an SSH tunnel is established for remote maintenance:

Telekube Online Installer


The end users can close the SSH tunnel and disconnect their Application from the Ops center.

There are two types of online installation URLs:

  • Single-use: Can be used once by a specific end user.

  • Multi-use: Can be used many times by multipe end users.

Offline Installation

The offline installation allows users to install into air-gapped (offline) server clusters. The Application Bundle, app-name.tar, from the example above, contains everything that it needs to be installed and launched.

To install using the graphical installation wizard, a Linux desktop (with a browser) must be connected to the same network as the target servers.

Expanding the tarball will produce the following:

$ tar -xf app-name.tar
$ ls -l
-rwxr--r-- 1 user staff 679  Oct 24 12:01 install
-rw-r--r-- 1 user staff 1.1K Oct 24 12:01 README
-rwxr--r-- 1 user staff 170  Oct 24 12:01 packages
-rwxr--r-- 1 user staff 170  Oct 24 12:01 upload
-rwxr--r-- 1 user staff 170  Oct 24 12:01 upgrade

The installer is launched by typing ./install. This will print an HTTP URL pointing to the installation wizard running on localhost.

The installation wizard will guide the end user through the installation process.

Telekube Offline Installer

Automatic (CLI) Installation

Instead of running a graphical installer, an Application Bundle can be installed through a CLI which is useful for integrations with configuration management scripts or other types of intrastructure automation. Sometimes this method is called "unattended installation".

For this to work the information needed to complete the installation has to be supplied via the command line flags passed to the installer.

Assuming a 3 node installation:

  1. Copy the Application Bundle onto all nodes.
  2. Execute ./gravity install on the first node.
  3. Execute ./gravity join on two other nodes.

Below is a sample ./gravity install command for the first node:

$ sudo ./gravity install --advertise-addr= --token=XXX

This will initiate the process of setting up a new cluster for the application. The install command accepts the following arguments:

Flag Description
--token Secure token which prevents rogue nodes from joining the cluster during installation. Carefully pick a hard-to-guess value.
--advertise-addr IP address this node should be visible as. This setting is needed to correctly configure Kubernetes on every machine.
--cluster (Optional) Name of the cluster. Autogenerated if not set.
--cloud-provider (Optional) Cloud provider integration, generic or aws. Autodetected if not set.
--flavor (Optional) Application flavor. See Application Manifest for details.
--config (Optional) File with Kubernetes resources to create in the cluster during installation.
--pod-network-cidr (Optional) CIDR range Kubernetes will be allocating node subnets and pod IPs from. Must be a minimum of /16 so Kubernetes is able to allocate /24 to each node. Defaults to
--service-cidr (Optional) CIDR range Kubernetes will be allocating service IPs from. Defaults to
--wizard (Optional) Start the installation wizard.
--state-dir (Optional) Directory where all Telekube system data will be kept on this node. Defaults to /var/lib/gravity.

Below is a sample ./gravity join command for the remaining nodes:

$ sudo ./gravity join --advertise-addr= --token=XXX

This tells the other nodes to join a cluster initiated by install on node


--advertise-addr must also be set for every node, and the same value for --token must be used.

The result of running these commands will be a fully functioning and self-sufficient Kubernetes cluster!

You can learn more in the Packaging & Deployment section of the documentation.

Ongoing Management

Telekube uses a component called "Gravity" to manage Clusters. Gravity commands are available through a CLI and can:

  1. Add new nodes to a Cluster.
  2. Remove nodes from a Cluster.
  3. Monitor a Cluster
  4. Perform updates to the Cluster.

Kubernetes tools such as kubectl can also be used to perform Cluster management tasks such as watching logs, seeing stats for pods or volumes, managing configuration and so on.

Kubernetes's job is to manage your application. Gravity's job is to manage Kubernetes.

See more details in Cluster Management section.

For Applications running on remote infrastructure, Ops Center can be used to get remote access to the Application (assuming the end users allow it).

If the Application is offline, the Telekube offline updating mechanism can be used to perform updates.

See more details in Remote Management section.