Deploy on Linux

This guide provides a step by step process for installing Grafana Enterprise Traces (GET) on a Linux machine. It assumes you have access to a Linux machine and the permissions required to deploy a service with network and filesystem access. At the end of this guide you will have deployed a single GET instance on a single node.

Prerequisites

You will need:

• A valid Grafana Labs license with an associated GET cluster name.
• An s3 compatible object store

Setup an object storage bucket

GET uses object storage as the backend for its trace storage. It also uses object storage for storing various administrative credentials and data related to the state of the system. (GET and Tempo support using the local filesystem as the backend for trace storage as well, but as this is not recommended for production deployments and is not supported for storing admin credentials, this guide will focus on setup with an object storage.)

This guide assumes that you are using Amazon S3 on the AWS us-east-1 region as your object store. If you plan on using a different region or object storage service, update the storage fields in the configuration file below. Currently, the supported object storage backends are AWS S3, other S3-compliant object stores, and Google Cloud’s GCS.

After you have provisioned an object storage backend, create two buckets: grafana-traces-admin and grafana-traces-data. Those buckets will be referenced in the configuration file of this guide.

Install GET

Run the following commands on your machine as the root user:

# Add dedicated user and group
groupadd --system enterprise-traces
useradd --system --home-dir /var/lib/enterprise-traces -g enterprise-traces enterprise-traces

# Create directories
mkdir -p /etc/enterprise-traces /var/lib/enterprise-traces /var/lib/enterprise-traces/rules-temp
chown root:enterprise-traces /etc/enterprise-traces
chown enterprise-traces:enterprise-traces /var/lib/enterprise-traces /var/lib/enterprise-traces/rules-temp
chmod 0750 /etc/enterprise-traces /var/lib/enterprise-traces

# Download enterprise-traces binary
curl -Lo /usr/local/bin/enterprise-traces \
  https://dl.grafana.com/GET/releases/enterprise-traces-v1.0.0-linux-amd64
# ** TODO: update the sha once released ***
echo d123d211d40ebbf41af9d7e6c87030bacdc6b62e8490b872aef970a22bb44b04 \
  /usr/local/bin/enterprise-traces | sha256sum -c
chmod 0755 /usr/local/bin/enterprise-traces
setcap 'cap_net_bind_service=+ep' /usr/local/bin/enterprise-traces

# # Set up systemd unit and enable startup on boot
cat > /etc/systemd/system/enterprise-traces.service <<EOF
[Unit]
After=network.target

[Service]
User=enterprise-traces
Group=enterprise-traces
WorkingDirectory=/var/lib/enterprise-traces
ExecStart=/usr/local/bin/enterprise-traces \
   -config.file=/etc/enterprise-traces/enterprise-traces.yaml \
   -log.level=warn \

[Install]
WantedBy=default.target
EOF

systemctl daemon-reload
systemctl enable enterprise-traces.service

Create a GET configuration file

Copy the following YAML config to a file called enterprise-traces.yaml. Update the cluster_name field with the name of the cluster your license was issued for and paste in your s3 credentials for the admin_client.

multitenancy_enabled: true
auth:
  type: enterprise

license:
  path: /etc/enterprise-traces/license.jwt

http_api_prefix: /tempo

ingester:
    lifecycler:
        ring:
            replication_factor: 3

server:
    http_listen_port: 3200

storage:
    trace:
        backend: s3
        s3:
            endpoint: s3.us-east-1.amazonaws.com
            bucket: grafana-traces-data
            forcepathstyle: true
            #set to true if endpoint is https
            insecure: true
            access_key: # TODO: insert your key id
            secret_key: # TODO: insert your secret key
        wal:
            path: /var/lib/enterprise-traces/wal

admin_client:
  storage:
    s3:
      endpoint: s3.us-east-1.amazonaws.com
      bucket_name: grafana-traces-admin
      access_key_id: # TODO: insert your key id
      secret_access_key: # TODO: insert your secret key
    type: s3

Move the configuration file and license to the proper directory

Copy the configuration and the license files to all nodes in the GET cluster:

• enterprise-traces.yaml should be copied to /etc/enterprise-traces/enterprise-traces.yaml
• license.jwt should be copied to /etc/enterprise-traces/license.jwt

Generate an admin token

Generate an admin token by running the following on a single node in the cluster:

su enterprise-traces -c "/usr/local/bin/enterprise-traces \
   --config.file=/etc/enterprise-traces/enterprise-traces.yaml \
   --bootstrap.license.path=/etc/enterprise-traces/license.jwt \
   --log.level=warn \
   --target=tokengen"
# Token created:  YWRtaW4tcG9saWN5LWJvb3RzdHJhcC10b2tlbjo8Ujc1IzQyfXBfMjd7fDIwMDRdYVxgeXw=

Start the enterprise-traces service

systemctl start enterprise-traces.service

Verify your cluster is working

To verify your cluster is working, you can run the following command using the token you generated in the previous step.

curl -u :$API_TOKEN localhost:3100/ready

After running the above command, you should see the following output:

ready

This indicates the ingester component is ready to receive trace data.

Next steps

To integrate your GET cluster with Grafana and a UI to interact with the Admin API, refer to Set up the GET plugin for Grafana.