Menu
Documentationbreadcrumb arrowGrafana Lokibreadcrumb arrowSend databreadcrumb arrowPromtailbreadcrumb arrowInstall Promtail
Open source

Install Promtail

Caution

Promtail has been deprecated and is in Long-Term Support (LTS) through February 28, 2026. Promtail will reach an End-of-Life (EOL) on March 2, 2026. You can find migration resourceshere.

Promtail is distributed as a binary, in a Docker container,or there is a Helm chart to install it in a Kubernetes cluster.

Install the binary

Every Grafana Loki release includes binaries for Promtail which can be found on theReleases page as part of the release assets.

Install using APT or RPM package manager

See the instructionshere.

Install using Docker

  1. Make sure to modify the tag to the most recent version.

    Bash
    docker pull grafana/promtail:3.2.1

  2. Create your Promtail configuration file in a file calledpromtail-config.yaml. Refer to thePromtail configuration reference for more details.

  3. Note that you will need to replace<local-path> in the commands with your local path.

    Bash
    docker run -v <local-path>:/mnt/config -v /var/log:/var/log --link loki grafana/promtail:3.2.1 --config.file=/mnt/config/promtail-config.yaml

Install on MacOS with Homebrew

  1. If necessary, installHomebrew.

    Bash
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  2. Update Homebrew.

    Bash
    brew update

  3. Navigate to thehomebrew page for Promtail.

  4. To install Promtail, run the following command:

    Bash
    brew install promtail

  5. Check that installation was successful.

    1. Check that promtail exists in its install directory.

      Bash
      which promtail

    2. Run promtail

      Bash
      promtail

Install using Helm

  1. Make sure that Helm is installed. SeeInstalling Helm.

  2. Then you can add Grafana’s chart repository to Helm:

    Bash
    helm repo add grafana https://grafana.github.io/helm-charts

  3. Update the chart repository:

    Bash
    helm repo update

  4. Create the configuration filevalues.yaml. The example below illustrates a connection to the locally deployed loki server:

    YAML
    config:# publish data to loki  clients:    - url: http://loki-gateway/loki/api/v1/push      tenant_id: 1

  5. Finally, Promtail can be deployed with:

    Bash
    # The default helm configuration deploys promtail as a daemonSet (recommended)helm upgrade --values values.yaml --install promtail grafana/promtail

ADaemonSet will deploy Promtail on every node within a Kubernetes cluster.

The DaemonSet deployment works well at collecting the logs of all containers within acluster. It’s the best solution for a single-tenant model. Replace{YOUR_LOKI_ENDPOINT} with your Loki endpoint.

YAML
--- # Daemonset.yamlapiVersion: apps/v1kind: DaemonSetmetadata:  name: promtail-daemonsetspec:  selector:    matchLabels:      name: promtail  template:    metadata:      labels:        name: promtail    spec:      serviceAccount: promtail-serviceaccount      containers:      - name: promtail-container        image: grafana/promtail        args:        - -config.file=/etc/promtail/promtail.yaml        env:         - name: 'HOSTNAME' # needed when using kubernetes_sd_configs          valueFrom:            fieldRef:              fieldPath: 'spec.nodeName'        volumeMounts:        - name: logs          mountPath: /var/log        - name: promtail-config          mountPath: /etc/promtail        - mountPath: /var/lib/docker/containers          name: varlibdockercontainers          readOnly: true      volumes:      - name: logs        hostPath:          path: /var/log      - name: varlibdockercontainers        hostPath:          path: /var/lib/docker/containers      - name: promtail-config        configMap:          name: promtail-config--- # configmap.yamlapiVersion: v1kind: ConfigMapmetadata:  name: promtail-configdata:  promtail.yaml: |    server:      http_listen_port: 9080      grpc_listen_port: 0    clients:    - url: https://{YOUR_LOKI_ENDPOINT}/loki/api/v1/push    positions:      filename: /tmp/positions.yaml    target_config:      sync_period: 10s    scrape_configs:    - job_name: pod-logs      kubernetes_sd_configs:        - role: pod      pipeline_stages:        - docker: {}      relabel_configs:        - source_labels:            - __meta_kubernetes_pod_node_name          target_label: __host__        - action: labelmap          regex: __meta_kubernetes_pod_label_(.+)        - action: replace          replacement: $1          separator: /          source_labels:            - __meta_kubernetes_namespace            - __meta_kubernetes_pod_name          target_label: job        - action: replace          source_labels:            - __meta_kubernetes_namespace          target_label: namespace        - action: replace          source_labels:            - __meta_kubernetes_pod_name          target_label: pod        - action: replace          source_labels:            - __meta_kubernetes_pod_container_name          target_label: container        - replacement: /var/log/pods/*$1/*.log          separator: /          source_labels:            - __meta_kubernetes_pod_uid            - __meta_kubernetes_pod_container_name          target_label: __path__--- # Clusterrole.yamlapiVersion: rbac.authorization.k8s.io/v1kind: ClusterRolemetadata:  name: promtail-clusterrolerules:  - apiGroups: [""]    resources:    - nodes    - services    - pods    verbs:    - get    - watch    - list--- # ServiceAccount.yamlapiVersion: v1kind: ServiceAccountmetadata:  name: promtail-serviceaccount--- # Rolebinding.yamlapiVersion: rbac.authorization.k8s.io/v1kind: ClusterRoleBindingmetadata:  name: promtail-clusterrolebindingsubjects:    - kind: ServiceAccount      name: promtail-serviceaccount      namespace: defaultroleRef:    kind: ClusterRole    name: promtail-clusterrole    apiGroup: rbac.authorization.k8s.io

Is this page helpful?

On this page
Scroll for more