Running Grafana Cloud Agent

There are a few ways to run the Grafana Cloud Agent, in order from easiest to hardest:

• Use the Install Script for Kubernetes
• Run the Agent with Docker
• Run the Agent locally
• Use the example Kubernetes configs
• Build the Agent from Source
• Use our production Tanka configs

Install Script for Kubernetes

The Grafana Cloud Agent repository comes with installation scripts to configure components and return a Kubernetes manifest that uses our preferred defaults. To run the script, copy and paste this in your terminal:

NAMESPACE="default" /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/grafana/agent/release/production/kubernetes/install.sh)" | kubectl apply -f -
NAMESPACE="default" /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/grafana/agent/release/production/kubernetes/install-loki.sh)" | kubectl apply -f -
NAMESPACE="default" /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/grafana/agent/release/production/kubernetes/install-tempo.sh)" | kubectl apply -f -

See the Kubernetes README for more information.

Running the Agent with Docker

To run the Agent with Docker, you should have a configuration file on your local machine ready to bind mount into the container. Then modify the following command for your environment. Replace /path/to/config.yaml with the full path to your YAML configuration, and replace /tmp/agent with the directory on your host that you want the agent to store its WAL.

docker run \
  -v /tmp/agent:/etc/agent \
  -v /path/to/config.yaml:/etc/agent-config/agent.yaml \
  --entrypoint "/bin/agent -config.file=/etc/agent-config/agent.yaml -prometheus.wal-directory=/etc/agent/data"
  grafana/agent:v0.12.0

Running the Agent locally

Currently, you must provide your own system configuration files to run the Agent as a long-living process (e.g., write your own systemd unit files).

Use the example Kubernetes configs

The install script replaces variable placeholders in the example Kubernetes manifest in the Kubernetes directory. Feel free to examine that file and modify it for your own needs!

Build the Agent from source

Go 1.14 is currently needed to build the agent from source. Run make agent from the root of this repository, and then the build agent binary will be placed at ./cmd/agent/agent.

Use our production Tanka configs

The Tanka configs we use to deploy the agent ourselves can be found in our production Tanka directory. These configs are also used to generate the Kubernetes configs for the install script. To get started with the tanka configs, do the following:

mkdir tanka-agent
cd tanka-agent
tk init --k8s=false
jb install github.com/grafana/agent/production/tanka/grafana-agent

# substitute your target k8s version for "1.16" in the next few commands
jb install github.com/jsonnet-libs/k8s-alpha/1.16
echo '(import "github.com/jsonnet-libs/k8s-alpha/1.16/main.libsonnet")' > lib/k.libsonnet
echo '+ (import "github.com/jsonnet-libs/k8s-alpha/1.16/extensions/kausal-shim.libsonnet")' >> lib/k.libsonnet

Then put this in environments/default/main.jsonnet:

local agent = import 'grafana-agent/grafana-agent.libsonnet';

agent {
  _config+:: {
    namespace: 'grafana-agent'
  },
}

If all these steps worked, tk eval environments/default should output the default JSON we use to build our Kubernetes manifests.