Install Loki on Grafana Labs

Install Grafana Loki with Helm

Wed, 11 Feb 2026 23:16:02 +0000

Install Grafana Loki with Helm

The Helm chart lets you configure, install, and upgrade Grafana Loki within a Kubernetes cluster.

This guide references the Loki Helm chart version 3.0 or greater and contains the following sections:

If you are installing Grafana Enterprise Logs, follow the GEL Helm installation.

Deployment Recommendations

Loki is designed to be run in two states:

Monolithic: Recommended when you are running Loki as part of a small meta monitoring stack.
Microservices: For workloads that require high availability and scalability. Loki is deployed in this mode internally at Grafana Labs.

Tip
Loki can also be deployed in Simple Scalable mode. But Simple Scalable Deployment (SSD) mode is being deprecated. For the best possible experience in production, we recommend deploying Loki in microservices mode.

Cloud Deployment Guides

The following guides provide step-by-step instructions for deploying Loki on cloud providers:

Reference

Values reference

Tanka

Wed, 19 Nov 2025 16:24:02 +0000

Tanka

Tanka is a reimplementation of Ksonnet that Grafana Labs created after Ksonnet was deprecated. Tanka is used by Grafana Labs to run Grafana Loki in production.

The Tanka installation runs the Loki cluster in microservices mode.

Note
Grafana Loki does not come with any included authentication layer. You must run an authenticating reverse proxy in front of your services to prevent unauthorized access to Loki (for example, nginx). Refer to Manage authentication for a list of open-source reverse proxies you can use.

Prerequisites

Install the latest version of Tanka (version v0.31.0 or a more recent version) for the tk env commands. Prebuilt binaries for Tanka can be found at the Tanka releases URL.

In your config repo, if you don’t have a Tanka application, create a folder and call tk init inside of it. Then create an environment for Loki and provide the URL for the Kubernetes API server to deploy to (e.g., https://localhost:6443):

mkdir <application name>
cd <application name>
tk init
tk env add environments/loki --namespace=loki --server=<Kubernetes API server>

Install jsonnet-bundler (jb), find instructions for your platform in Tanka’s installation docs.

Deploying

Download and install the Loki and Promtail module using jb (version v0.6.0 or a more recent version):

jb init  # not required if you already ran `tk init`
jb install github.com/grafana/loki/production/ksonnet/loki@main
jb install github.com/grafana/loki/production/ksonnet/promtail@main

Revise the YAML contents of environments/loki/main.jsonnet, updating these variables:

Update the username, password, and the relevant htpasswd variable values.
Update the S3 or GCS variable values, depending on your object storage type. See storage_config for more configuration details.
Remove from the configuration the S3 or GCS object storage variables that are not part of your setup.
Update the Promtail configuration container_root_path variable’s value to reflect your root path for the Docker daemon. Run docker info | grep "Root Dir" to acquire your root path.
Update the from value in the Loki schema_config section to no more than 14 days prior to the current date. The from date represents the first day for which the schema_config section is valid. For example, if today is 2021-01-15, set from to 2021-01-01. This recommendation is based on the Loki default acceptance of log lines up to 14 days in the past. The reject_old_samples_max_age configuration variable controls the acceptance range.

local gateway = import 'loki/gateway.libsonnet';
local loki = import 'loki/loki.libsonnet';
local promtail = import 'promtail/promtail.libsonnet';

loki + promtail + gateway {
  _config+:: {
    namespace: 'loki',
    htpasswd_contents: 'loki:$apr1$H4yGiGNg$ssl5/NymaGFRUvxIV1Nyr.',

    // S3 variables -- Remove if not using s3
    storage_backend: 's3,dynamodb',
    s3_access_key: 'key',
    s3_secret_access_key: 'secret access key',
    s3_address: 'url',
    s3_bucket_name: 'loki-test',
    dynamodb_region: 'region',

    // GCS variables -- Remove if not using gcs
    storage_backend: 'bigtable,gcs',
    bigtable_instance: 'instance',
    bigtable_project: 'project',
    gcs_bucket_name: 'bucket',

    //Update the object_store and from fields
    loki+: {
      schema_config: {
        configs: [{
          from: 'YYYY-MM-DD',
          store: 'boltdb-shipper',
          object_store: 'my-object-storage-backend-type',
          schema: 'v11',
          index: {
            prefix: '%s_index_' % $._config.table_prefix,
            period: '%dh' % $._config.index_period_hours,
          },
        }],
      },
    },

    //Update the container_root_path if necessary
    promtail_config+: {
      clients: [{
        scheme:: 'http',
        hostname:: 'gateway.%(namespace)s.svc' % $._config,
        username:: 'loki',
        password:: 'password',
        container_root_path:: '/var/lib/docker',
      }],
    },

    replication_factor: 3,
    consul_replicas: 1,
  },
}

Run tk show environments/loki to see the manifests that will be deployed to the cluster. Run tk apply environments/loki to deploy the manifests. To delete the environment from cluster, run tk delete environments/loki.

Install Loki with Docker or Docker Compose

Mon, 12 Jan 2026 18:30:10 +0000

Install Loki with Docker or Docker Compose

You can install Loki and Promtail with Docker or Docker Compose if you are evaluating, testing, or developing Loki. For production, Grafana recommends installing with Helm or Tanka.

The configuration files associated with these installation instructions run Loki as a single binary.

Prerequisites

Docker
Docker Compose (optional, only needed for the Docker Compose install method)

Install with Docker on Linux

Create a directory called loki. Make loki your current working directory:
Bash
```
mkdir loki
cd loki
```

Copy and paste the following commands into your command line to download loki-local-config.yaml and promtail-docker-config.yaml to your loki directory.

wget https://raw.githubusercontent.com/grafana/loki/v3.6.0/cmd/loki/loki-local-config.yaml -O loki-config.yaml
wget https://raw.githubusercontent.com/grafana/loki/v3.6.0/clients/cmd/promtail/promtail-docker-config.yaml -O promtail-config.yaml

Copy and paste the following commands into your command line to start the Docker containers using the configuration files you downloaded in the previous step.
Bash
```
docker run --name loki -d -v $(pwd):/mnt/config -p 3100:3100 grafana/loki:3.6.0 -config.file=/mnt/config/loki-config.yaml
docker run --name promtail -d -v $(pwd):/mnt/config -v /var/log:/var/log --link loki grafana/promtail:3.6.0 -config.file=/mnt/config/promtail-config.yaml
```
Note
The image is configured to run by default as user loki with UID 10001 and GID 10001. You can use a different user, specially if you are using bind mounts, by specifying the UID with a docker run command and using --user=UID with a numeric UID suited to your needs.

Verify that your containers are running:

docker container ls

You should see something similar to the following:


CONTAINER ID   IMAGE                    COMMAND                  CREATED              STATUS              PORTS                                       NAMES
9485de9ad351   grafana/promtail:3.6.0   "/usr/bin/promtail -…"   About a minute ago   Up About a minute                                               promtail
cece1df84519   grafana/loki:3.6.0       "/usr/bin/loki -conf…"   About a minute ago   Up About a minute   0.0.0.0:3100->3100/tcp, :::3100->3100/tcp   loki

Verify that Loki is up and running.
- To view readiness, navigate to http://localhost:3100/ready.
- To view metrics, navigate to http://localhost:3100/metrics.

Install with Docker on Windows

Copy and paste the following commands into your command line to download loki-local-config.yaml and promtail-docker-config.yaml to your loki directory. Note that you will need to replace the <local-path> in the commands with your local path.

cd "<local-path>"
wget https://raw.githubusercontent.com/grafana/loki/v3.6.0/cmd/loki/loki-local-config.yaml -O loki-config.yaml
wget https://raw.githubusercontent.com/grafana/loki/v3.6.0/clients/cmd/promtail/promtail-docker-config.yaml -O promtail-config.yaml

Copy and paste the following commands into your command line to start the Docker containers using the configuration files you downloaded in the previous step. Note that you will need to replace the <local-path> in the commands with your local path.

docker run --name loki -v <local-path>:/mnt/config -p 3100:3100 grafana/loki:3.6.0 --config.file=/mnt/config/loki-config.yaml
docker run -v <local-path>:/mnt/config -v /var/log:/var/log --link loki grafana/promtail:3.6.0 --config.file=/mnt/config/promtail-config.yaml

Verify that Loki is up and running.
- To view readiness, navigate to http://localhost:3100/ready.
- To view metrics, navigate to http://localhost:3100/metrics.

Install with Docker Compose

Run the following commands in your command line. They work for Windows or Linux systems.

Create a directory called loki. Make loki your current working directory:
Bash
```
mkdir loki
cd loki
```

Copy and paste the following command into your command line to download the docker-compose file.

wget https://raw.githubusercontent.com/grafana/loki/v3.6.0/examples/getting-started/docker-compose.yaml -O docker-compose.yaml
wget https://raw.githubusercontent.com/grafana/loki/v3.6.0/examples/getting-started/alloy-local-config.yaml -O alloy-local-config.yaml
wget https://raw.githubusercontent.com/grafana/loki/v3.6.0/examples/getting-started/loki-config.yaml -O loki-config.yaml

With loki as the current working directory, run the following ‘docker-compose` command:

docker-compose -f docker-compose.yaml up

You should see something similar to the following:

✔ Container loki-loki-1      Started              0.0s
✔ Container loki-grafana-1   Started              0.0s
✔ Container loki-promtail-1  Started              0.0s

Verify that Loki is up and running.
- To view readiness, navigate to http://localhost:3100/ready.
- To view metrics, navigate to http://localhost:3100/metrics.

Install Grafana Loki locally

Mon, 12 Jan 2026 18:30:10 +0000

Install Grafana Loki locally

To log events with Grafana Loki, download and install both Promtail and Loki.

Loki is the logging engine.
Promtail sends logs to Loki.

The configuration runs Loki as a single binary.

Note
Grafana Loki does not come with any included authentication layer. You must run an authenticating reverse proxy in front of your services to prevent unauthorized access to Loki (for example, nginx). Refer to Manage authentication for a list of open-source reverse proxies you can use.

Install using APT or RPM package manager

Add the Grafana Advanced Package Tool (APT) or RPM Package Manager (RPM) package repository following the linked instructions.

Install Loki and Promtail

Using dnf
Bash
```
dnf update
dnf install loki promtail
```

Using apt-get

apt-get update
apt-get install loki promtail

Install manually

Browse to the release page.
Find the Assets section for the version that you want to install.
Download the Loki and Promtail archive files that correspond to your system.

Don’t download LogCLI or Loki Canary at this time. LogCLI allows you to run Loki queries in a command line interface. Loki Canary is a tool to audit Loki performance.
Extract the package contents into the same directory. This is where the two programs will run.
In the command line, change directory (cd on most systems) to the directory with Loki and Promtail.

Copy and paste the following commands into your command line to download generic configuration files.

Use the Git references that match your downloaded Loki version to get the correct configuration file. For example, if you are using Loki version 3.6.0, you need to use the https://raw.githubusercontent.com/grafana/loki/v3.6.0/cmd/loki/loki-local-config.yaml URL to download the configuration file.
Bash
```
wget https://raw.githubusercontent.com/grafana/loki/main/cmd/loki/loki-local-config.yaml
wget https://raw.githubusercontent.com/grafana/loki/main/clients/cmd/promtail/promtail-local-config.yaml
```

Run the following command to start Loki:

Windows

.\loki-windows-amd64.exe --config.file=loki-local-config.yaml

Linux

./loki-linux-amd64 -config.file=loki-local-config.yaml

Loki runs and displays Loki logs in your command line and on http://localhost:3100/metrics.

The next step is running an agent to send logs to Loki. To do so with Promtail, refer to the Promtail configuration.

Release binaries - openSUSE Linux only

Every release includes binaries for Loki. You can find them on the Releases page.

Community openSUSE Linux packages

The community provides packages of Loki for openSUSE Linux. To install them:

Add the repository https://download.opensuse.org/repositories/security:/logging/ to your system. For example, if you are using Leap 15.1, run:
Bash
```
sudo zypper ar https://download.opensuse.org/repositories/security:/logging/openSUSE_Leap_15.1/security:logging.repo
sudo zypper ref
```
Install the Loki package:
Bash
```
zypper in loki
```

Start and enable the Loki and Promtail services:

systemd start loki
systemd enable loki
systemd start promtail
systemd enable promtail

Modify the /etc/loki/promtail.yaml and /etc/loki/loki.yaml configuration files as needed.

Install on Istio

Wed, 19 Nov 2025 16:24:02 +0000

Install on Istio

When installing Loki on Istio service mesh you must complete some additional steps. Without these steps, the ingester, querier, etc. might start, but you will see logs like the following:

loki level=debug ts=2021-11-24T11:33:37.352544925Z caller=broadcast.go:48 msg="Invalidating forwarded broadcast" key=collectors/distributor version=123 oldVersion=122 content=[loki-distributor-59c4896444-t9t6g[] oldContent=[loki-distributor-59c4896444-t9t6g[]

This means that the pod is failing to join the ring.

If you try to add loki to Grafana data sources, you will see logs like (empty ring):

loki level=warn ts=2021-11-24T08:02:42.08262122Z caller=logging.go:72 traceID=3fc821042d8ada1a orgID=fake msg="GET /loki/api/v1/labels?end=1637740962079859431&start=1637740361925000000 (500) 97.4µs Response: \"empty ring\\n\" ws: false; X-Scope-Orgid: fake; uber-trace-id: 3fc821042d8ada1a:1feed8872deea75c:1180f95a8235bb6c:0; "

When you enable istio-injection on the namespace where Loki is running, you need to also modify the configuration for the Loki services. Given that Istio will not allow a pod to resolve another pod using an IP address, you must also modify the memberlist service.

Required changes

Query frontend service

Make the following modifications to the file for the Loki Query Frontend service.

Change the name of grpc port to grpclb. This is used by the grpc load balancing strategy which relies on SRV records. Otherwise the querier will not be able to reach the query-frontend. See https://github.com/grafana/loki/blob/0116aa61c86fa983ddcbbd5e30a2141d2e89081a/production/ksonnet/loki/common.libsonnet#L19 and https://grpc.github.io/grpc/core/md_doc_load-balancing.html
Set the appProtocol of grpclb to tcp
Set publishNotReadyAddresses to true

apiVersion: v1
kind: Service
metadata:
  labels:
    app: loki-query-frontend
    app.kubernetes.io/instance: observability
    app.kubernetes.io/name: loki-query-frontend
spec:
  ports:
  - appProtocol: http
    name: http
    port: 3100
    protocol: TCP
    targetPort: http
  - appProtocol: tcp
    name: grpclb
    port: 9095
    protocol: TCP
    targetPort: grpc
  publishNotReadyAddresses: true
  selector:
    app: loki-query-frontend
    app.kubernetes.io/instance: observability
    app.kubernetes.io/name: loki-query-frontend
  type: ClusterIP

Querier service

Make the following modifications to the file for the Loki Querier service.

Set the appProtocol of the grpc service to tcp

apiVersion: v1
kind: Service
metadata:
  labels:
    app: loki-querier
    app.kubernetes.io/instance: observability
    app.kubernetes.io/name: loki-querier
  name: loki-querier
  namespace: observability
spec:
  ports:
  - appProtocol: http
    name: http
    port: 3100
    protocol: TCP
    targetPort: http
  - appProtocol: tcp
    name: grpc
    port: 9095
    protocol: TCP
    targetPort: grpc
  selector:
    app: loki-querier
    app.kubernetes.io/instance: observability
    app.kubernetes.io/name: loki-querier
  type: ClusterIP

Ingester service and Ingester headless service

Make the following modifications to the file for the Loki Query Ingester and Ingester Headless service.

Set the appProtocol of the grpc port to tcp.

apiVersion: v1
kind: Service
metadata:
  labels:
    app: loki-ingester-(headless)
    app.kubernetes.io/instance: observability
    app.kubernetes.io/name: loki-ingester
  name: loki-ingester-headless
spec:  
  clusterIP: None (if headless)
  ports:
  - name: http
    port: 3100
    protocol: TCP
    targetPort: http
  - appProtocol: tcp
    name: grpc
    port: 9095
    protocol: TCP
    targetPort: grpc
  selector:
    app: loki-ingester
    app.kubernetes.io/instance: observability
    app.kubernetes.io/name: loki-ingester
  type: ClusterIP

Distributor service

Make the following modifications to the file for the Loki Distributor service.

Set the appProtocol of the grpc port to tcp.

apiVersion: v1
kind: Service
metadata:
  labels:
    app: loki-distributor
    app.kubernetes.io/instance: observability
    app.kubernetes.io/name: loki-distributor
spec:
  ports:
  - name: http
    port: 3100
    protocol: TCP
    targetPort: http
  - name: grpc
    port: 9095
    protocol: TCP
    targetPort: grpc
    appProtocol: tcp
  selector:
    app: loki-distributor
    app.kubernetes.io/instance: observability
    app.kubernetes.io/name: loki-distributor
  sessionAffinity: None
  type: ClusterIP

Memberlist service

Make the following modifications to the file for the Memberlist service.

Set the appProtocol of the http port to tcp.

apiVersion: v1
kind: Service
metadata:
  labels:
    app.kubernetes.io/instance: observability
  name: loki-memberlist
  namespace: observability
spec:
  clusterIP: None
  ports:
    - name: http
      port: 7946
      protocol: TCP
      targetPort: 7946
      appProtocol: tcp
  selector:
    app.kubernetes.io/instance: observability
    app.kubernetes.io/part-of: memberlist

Build from source

Wed, 19 Nov 2025 16:24:02 +0000

Build from source

Clone the Grafana Loki repository and use the provided Makefile to build Loki from source.

Note
Grafana Loki does not come with any included authentication layer. You must run an authenticating reverse proxy in front of your services to prevent unauthorized access to Loki (for example, nginx). Refer to Manage authentication for a list of open-source reverse proxies you can use.

Prerequisites

Go, version 1.23 or later; set your $GOPATH environment variable
make
Docker (for updating protobuf and yacc files)

Build locally

Clone Loki to $GOPATH/src/github.com/grafana/loki:

git clone https://github.com/grafana/loki $GOPATH/src/github.com/grafana/loki

With a current working directory of $GOPATH/src/github.com/grafana/loki:
Bash
```
make loki
```

The built executable will be in $GOPATH/src/github.com/grafana/loki/cmd/loki/loki.