Self-hosted on Kubernetes

Over the past years, Kubernetes has become the defacto standard for orchestrating containers. Instana has been designed to run well on Kubernetes. In fact, we run Instana on Kubernetes ourselves on our SaaS platfrom.

Kubernetes Operator

We've built a Kubernetes operator that manages the whole Instana platform and makes it easy for you to run it on Kubernetes. It automates the deployment of all components and takes care of required database migrations.

The operator is a controller that runs on the cluster. It uses a set of custom resources that describe the Instana setup in a declarative manner. It watches for changes on these resources and reconciles them as necessary.

Custom Resource Definitions

Custom Resource Definitions (CRDs) are extensions of the Kubernetes API. The following two CRDs must be installed on the cluster.

See API Reference for details.

Tip 1:

The API reference is also available via kubectl explain. See kubectl explain --help for details on how to use it.


$ kubectl explain core.spec.serviceProviderConfig
KIND:     Core

RESOURCE: serviceProviderConfig <Object>

     Service provider configuration for SAML or OIDC.

   basePath	<string> -required-
     Base URL (defaults to "/auth").

   maxAuthenticationLifetimeSeconds	<integer> -required-
     The maximum authentication lifetime (defaults to 604.800).

   maxIDPMetadataSizeInBytes	<integer> -required-
     The maximum IDP metadata size (defaults to 200.000).

Tip 2:

A good editor, such as VS Code with the Kubernetes extension provides command completion when the CRDs are installed on the cluster.


VS Code

A Core represents all components shared by an Instana installation. Each Core has a set of associated databases which will be used by the Core itself and all tenants with their respective tenant units created as members of the Core.

Units represent individual data pools in Instana. Internally, Instana has tenants which are merely a logical construct. Each tenant in turn has at least one or multiple tenant units. As far as the configuration is concerned, you always configure tenant units via the Unit CRD. A tenant could stand for a department (e.g. SRE, Dev, QA ...), or any other logical grouping. Within a tenant you would create individual Units as required. Data from one Unit is not visible by any other Unit.


Let's assume for a there are two departments, ecommerce and intranet.

  • ecommerce has 3 environments: dev, preprod, prod.
  • intranet has 2 environments: dev and prod.

In this case, you would create a tenant ecommerce with the tenant units dev, preprod, and prod and a tenant intranet with the tenant units dev and prod. Tenant units are separated and only receive data from agents associated with them.

kubectl Plugin

A kubectl plugin is available that helps install the operator and also enables you to trigger administrative actions that the operator will perform.

Supported Kubernetes Versions

The operator runs on any vanilla Kubernetes distribution. The minimum required version is 1.16.

Support for OpenShift is planned.