Hey! We've joined GitLab! ๐ŸŽ‰ Read more


When creating a new Opstrace instance, one has to provide a corresponding configuration document in YAML format. A minimal variant might look like this:

- prod
- ci

To add tenants after installation, see our Managing Tenants Guide.

The following sections list individual configuration parameters and aim to provide a detailed specification for their purpose and meaning.

At a high level, there are two different types of parameters:

  • required ones
  • optional ones (but please do not assume sane defaults yet :-))

Required parameters


The set of initial tenants (their names) to create. At least one name is required.

Value type: list of strings


- prod
- staging
- ci

Optional parameters


The number of underlying nodes (VMs/machines) to use.

Value type: number (integer)


node_count: 3

Note: we develop with three nodes, andโ€”for nowโ€”we rarely test with less or more.


Allows for setting configuration specific to Amazon Web Services (AWS).

Value type: object


instance_type: t3.xlarge
region: us-west-2
zone_suffix: a
- AWSReservedSSO_AdministratorAccess_133333abc3333337

Use the eks_admin_roles parameter (an enumeration of strings) to define individual AWS IAM roles that should have administrator access to the underlying EKS cluster, via e.g. the EKS console.

Note: we develop and test mainly with region set to us-west-2. To date, we test other regions only manually and rarely.


Allows for setting infrastructure-related configuration specific to Google Cloud Platform (GCP).

Value type: flat object


machine_type: n1-standard-4
region: us-west2
zone_suffix: a

The example above shows the defaults.

Note: we develop and test mainly with region set to us-west2. To date, we test other regions only manually and rarely.


Specifies a label that is subsequently attached to most of the underlying cloud resources.

Default: not set, not applied

Value type: string


env_label: ci

The label name will be env, and the value will be what you provide here.


Default: false (the tenant API requires authentication proof).

Value type: boolean

By default, authentication proof is required when accessing the HTTP API for pushing or querying data. This flag can be used to disable said authentication mechanism, allowing for unauthenticated clients to write or read data.

When required, any HTTP request arriving at the tenant HTTP API is expected to show an API token in an Authorization header (using the Bearer scheme).


  • When set to false (default), the Opstrace CLI creates one long-lived API token per tenant during the create operation.


  • might be renamed in the future (to tenant_api_...)


Use this to specify the range of source IP addresses allowed to reach the data API through the Internet.

Default: one item:

Value type: list of strings



Locking this down makes sense when setting data_api_authentication_disabled to true.


Use this when your goal is to reach the Opstrace instance under a custom DNS name, using DNS infrastructure managed entirely by you.

Requires setting custom_auth0_client_id (see below).

Setting this parameter disables the default mechanism via which the Opstrace instance is made available under <instance_name>.opstrace.io (using Opstrace's DNS infrastructure). As a side effect, this removes the need for the Opstrace CLI to communicate with the Opstrace DNS configuration service and therefore removes the need to log in to that service during opstrace create ... and opstrace destroy ....

Default: undefined

Value type: string


custom_dns_name: myopstrace.powerteam.com

Further specification

  • The parameter value needs to be a fully qualified domain name without the trailing dot. It can be a top-level domain, but does not need to be.
  • This DNS name will point to the specific Opstrace instance you are planning to create. For example, the UI will then be served under https://<custom_dns_name>/.


  • A Google Cloud DNS or AWS Route53 DNS zone created a priori in your cloud account (during creation, the Opstrace instance will need to interact with the AWS/GCP API and reconfigure that DNS zone to add records for more fine-grained DNS names):
    • If you install the Opstrace instance in a GCP account, this DNS name must correspond to a so-called managed zone in Google Cloud DNS which you must set up prior to installing Opstrace. A guide can be found here.
    • If you install the Opstrace instance in an AWS account, this DNS name must correspond to a so-called hosted zone in AWS Route53 which you must set up prior to installing Opstrace. A guide can be found here.
  • A custom Auth0 application which you have to set up in advance. It needs to be configured specifically for the custom DNS name you are planning to use. A guide can be found here TODO. Take note of the so-called "client ID" of this Auth0 application and refer to it via custom_auth0_client_id. This is necessary for a secure single sign-on (SSO) experience; we cannot provide an out-of-the-box SSO experience that works against arbitrary DNS names.


Defines the issuer to use for all TLS-terminating certificates, such as for the externally available data API endpoints.

Default: letsencrypt-prod

Value type: string, one of letsencrypt-prod and letsencrypt-staging


cert_issuer: letsencrypt-prod


  • letsencrypt-staging should be used for test setups and playgrounds. This results in certificates that are not automatically trusted by browsers, i.e. users are likely to see security warnings.
  • letsencrypt-prod results in browser-trusted certificates, but is subject to quota/limits: https://letsencrypt.org/docs/rate-limits/.

custom_auth0_client_id and custom_auth0_domain

Use these two parameters when you want to log in to the web UI of your Opstrace instance via your custom Auth0 'application'.

This makes sense especially when you would like to connect to a special identity provider, and is obligatory when using a custom_dns_name (see above).

Default: undefined

Value type: string


custom_auth0_client_id: 1333337
custom_auth0_domain: barfoo.us.auth0.com

These two parameters must be provided together.


Defines the Docker image to run the controller from.

Default: controller image corresponding to the CLI build in use.

Value type: string -- Docker image reference, including the Docker hub user/org, the repository name, and the image tag (cf. example).


controller_image: opstrace/controller:297005c9-ci

This defines the Docker container image based on which the Opstrace installer deploys the Opstrace controller.

Note that the controller does not get deployed when initiating create with the --hold-controller command line argument. In that case, controller_image must still be set but is ignored.

Change this (compared to the default value) only when you know what you're doing :-).

log_retention_days and metric_retention_days

Defines data retention in terms of the number of desired days (for each data type).

Default: 7 days.

Value type: number (integer)

log_retention_days: 90
metric_retention_days: 365


  • These options currently cannot be specified on a per-tenant basis.
  • These options (as with the other options in the configuration file) currently cannot be changed after initial cluster creation.