Project: Opstrace (Observability and Analysis / Observability)
File: configuration.md

description: Parameter reference When creating a new Opstrace instance, one has to provide a corresponding configuration document in YAML format. A minimal variant might look like this: ```yaml tenants: prod ci ``` To add tenants after installation, see our . 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 :-)) The set of initial tenants \(their names\) to create. At least one name is required. Value type: list of strings Example: ```yaml tenants: prod staging ci ``` The number of underlying nodes (VMs/machines) to use. Value type: number \(integer\) Example: ```yaml node_count: 3 ``` Note: we develop with three nodes, andfor nowwe rarely test with less or more. Allows for setting configuration specific to Amazon Web Services (AWS). Value type: object Example: ```yaml aws: instance_type: t3.xlarge region: us-west-2 zone_suffix: a eksadminroles: AWSReservedSSOAdministratorAccess133333abc3333337 ``` Use the `eksadminroles` 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 . 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 Example: ```yaml gcp: 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 Example: ```yaml 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\). Notes: When set to `false` \(default\), the Opstrace CLI creates one long-lived API token per tenant during the `create` operation. Naming: might be renamed in the future (to `tenantapi...`) Use this to specify the range of source IP addresses allowed to reach the data API through the Internet. Default: one item: `0.0.0.0/0` Value type: list of strings Example: ```yaml dataapiauthorizedipranges: 54.190.201.152/32 ``` Locking this down makes sense when setting `dataapiauthentication_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 `customauth0client_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 Example: ```yaml customdnsname: myopstrace.powerteam.com ``` The parameter value needs to be a 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://<customdnsname>/`. 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 . 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 . 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` Example: ```yaml cert_issuer: letsencrypt-prod ``` Notes: `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: . 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 `customdnsname` (see above). <!-- TODO --> Default: undefined Value type: string Example: ```yaml customauth0client_id: 1333337 customauth0domain: 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). Example: ```yaml 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 :-). Defines data retention in terms of the number of desired days (for each data type). Default: 7 days. Value type: number \(integer\) ```yaml logretentiondays: 90 metricretentiondays: 365 ``` Notes: 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.