This is a getting started guide that will provide you with a step by step guide to setting up a Metrics Enterprise cluster. This guide is centered around our recommended practices for setting up an initial cluster:
- Single-binary deployments limit the complexity of the system while still allowing for horizontal scaling.
- Memberlist gossip to synchronize responsibility between processes in your cluster. Gossip performs better at scale for managing the state of the system and removes the need to deploy Consul or etcd to manage state.
- Blocks based storage using an object storage backend for persistence.
Get a license
Currently users are unable to create and provision their own license. In order to get a license, ask a Grafana Labs representative to provision one for you. Provide them with the
cluster name you want associated with that license.
- A cluster name must be between 3 and 63 characters long.
- A cluster name can only consist of lowercase letters, numbers, underscores (_), and hyphens (-).
- A cluster name must begin and end with a letter or number.
- Object Storage (S3/GCS/Azure Blob Storage or S3-compatible)
- Grafana Labs License File (
license.jwt) with an associated
- Provisioned compute capacity. For capacity planning, see the Cortex Capacity Planning Guide.
Prepare configuration file
This guide will focus on using an unauthenticated S3 bucket. See the admin storage documentation for how to configure storage with different backends and authentication options.
The general configuration format is compatible with Cortex’s configuration file format and its documentation provides a more detailed explanation of all the configuration options.
When you start your Grafana Metrics Enterprise cluster, ensure that the license file (
license.jwt) is present on the local filesystem and the path to the license file is specified in the GME config YAML file.
Take the following config and store it locally under metrics-enterprise.yaml:
auth: type: enterprise target: all # TODO: Ensure the cluster name is set to match your Grafana Labs License File cluster_name: <my-cluster> license: path: /etc/metrics-enterprise/license.jwt # Update this path to match the location where you stored the license file. admin_client: storage: # TODO: Configure the admin bucket according to your environment type: s3 s3: endpoint: minio:9000 bucket_name: metrics-enterprise-admin access_key_id: metrics-enterprise secret_access_key: supersecret insecure: true distributor: shard_by_all_labels: true pool: health_check_ingesters: true ingester_client: grpc_client_config: grpc_compression: gzip frontend_worker: match_max_concurrent: true memberlist: abort_if_cluster_join_fails: false bind_port: 7946 ingester: lifecycler: num_tokens: 512 ring: kvstore: store: memberlist # replication_factor configures the number of ingesters each sample will be stored # on. We recommend that you use a replication factor of 3. However, # if you plan on deploying GME on less than three nodes, lower this # value to 1. replication_factor: 3 blocks_storage: tsdb: dir: /tmp/cortex/tsdb bucket_store: sync_dir: /tmp/cortex/tsdb-sync # TODO: Configure the tsdb bucket according to your environment. backend: s3 s3: endpoint: minio:9000 # set a valid s3 hostname bucket_name: metrics-enterprise-tsdb # set a value for an existing bucket at the provided s3 address. access_key_id: metrics-enterprise # set an access key id for the provided s3 bucket. secret_access_key: supersecret # set an access key secret for the provided s3 bucket. insecure: true # avoid validating TLS certificates of the s3 backend, this is useful for setting up an initial testing environment. storage: engine: blocks
cluster_nameconfiguration option to match the one used when requesting the Grafana Labs License File.
Update the bucket configuration options with the appropriate options for your object store. Two different buckets that are used in the above config:
- Admin bucket stores the configuration and the license information of your Metrics Enterprise cluster.
- TSDB bucket is where all time series data is persisted. Prometheus' TSDB format is used.
Bootstrap and deploy cluster
In order to use Metrics Enterprise, you will need to bootstrap your cluster first. This process will…
- … parse and validate your license file and persist the license into your object storage backend. Any
metrics-enterpriseprocess with access to this backend will be able to utilize this license during startup.
- … create a cluster config object in the provided object storage backend to store metadata about your cluster and to allow for instances to be provisioned on the cluster.
- … create an initial
adminscoped API token for accessing and configuring the cluster through the Admin API or the Metrics Enterprise Grafana plugin.
The generated token will be important to use the cluster later, so make sure to note this admin token down.
Following that you can start deploying your cluster’s replicas.
Both the bootstrap and the deployment require slightly different actions depending on your deployment target. Continue with the specific guides for your environment: