ContextQMD
Back to Loki

Install the simple scalable Helm chart

docs/sources/setup/install/helm/install-scalable/_index.md

3.7.310.6 KB
Original Source

Install the simple scalable Helm chart

This Helm Chart deploys Grafana Loki in simple scalable mode within a Kubernetes cluster.

{{< admonition type="note" >}} As of March 16, 2026, the Loki Helm Chart is being maintained by Grafana Champions and the Grafana Community in the Grafana-community/helm-charts repository. Please open issues and pull requests for the chart against the Grafana-community repo. Simple Scalable Deployment (SSD) mode is being deprecated. The timeline for the deprecation is to be determined (TBD), but will happen before Loki 4.0 is released. {{< /admonition >}}

{{< admonition type="tip" >}} With the move to the Grafana-community repository, the chart numbering has changed. Major version updates signal breaking changes in the chart. For more information, refer to the README. {{< /admonition >}}

This chart configures Loki to run read, write, and backend targets in a scalable mode. Loki’s simple scalable deployment mode separates execution paths into read, write, and backend targets.

The default Helm chart deploys the following components:

  • Read component (3 replicas)
  • Write component (3 replicas)
  • Backend component (3 replicas)
  • Loki Canary (1 DaemonSet)
  • Gateway (1 NGINX replica)
  • Minio (optional, deprecated — see warning below)
  • Chunks cache (1 replica)
  • Results cache (1 replica)

{{< admonition type="note" >}} We do not recommend running scalable mode with filesystem storage. For the purpose of this guide, we will use the deprecated built-in MinIO subchart to provide a complete self-contained example. Configure a dedicated external object storage backend for production. {{< /admonition >}}

Prerequisites

  • Helm 3 or above. See Installing Helm.
  • A running Kubernetes cluster (must have at least 3 nodes).

Deploying the Helm chart for development and testing

The following steps show how to deploy the Loki Helm chart in simple scalable mode using the included MinIO as the storage backend. Our recommendation is to start here for development and testing purposes. Then configure Loki with an object storage provider when moving to production.

  1. Add the Grafana Community chart repository to Helm:

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

  2. Update the chart repository:

    bash
    helm repo update

  3. Create the configuration file values.yaml. The example below illustrates how to deploy Loki in test mode using MinIO as storage:

    {{< admonition type="warning" >}} The built-in MinIO subchart is deprecated and will be removed on 2026-10-31. The example below requires ignoreMinioDeprecation: true to render with chart v17+. For production, configure a dedicated external object storage backend. {{< /admonition >}}

    yaml
      loki:
    schemaConfig:
      configs:
        - from: "2024-04-01"
          store: tsdb
          object_store: s3
          schema: v13
          index:
            prefix: loki_index_
            period: 24h
    ingester:
      chunk_encoding: snappy
    querier:
      # Default is 4, if you have enough memory and CPU you can increase, reduce if OOMing
      max_concurrent: 4
    pattern_ingester:
      enabled: true
    limits_config:
      allow_structured_metadata: true
      volume_enabled: true

  deploymentMode: SimpleScalable

  backend:
    replicas: 2
  read:
    replicas: 2
  write:
    replicas: 3 # To ensure data durability with replication

  ignoreMinioDeprecation: true  # Temporary workaround – MinIO will be removed 2026-10-31
  # Enable minio for storage
  minio:
    enabled: true

  gateway:
    service:
      type: LoadBalancer

  4. Install or upgrade the Loki deployment.

  • To install:
bash
helm install --values values.yaml loki grafana-community/loki
  • To upgrade:
bash
helm upgrade --values values.yaml loki grafana-community/loki

Object Storage Configuration

After testing Loki with MinIO, we recommend configuring Loki with an object storage provider. The following examples shows how to configure Loki with different object storage providers:

{{< admonition type="caution" >}} When deploying Loki using S3 Storage DO NOT use the default bucket names; chunk, ruler and admin. Choose a unique name for each bucket. For more information see the following security update. This caution does not apply when you are using MinIO. When using MinIO we recommend using the default bucket names. {{< /admonition >}}

{{< collapse title="S3" >}}

yaml
loki:
  schemaConfig:
    configs:
      - from: "2024-04-01"
        store: tsdb
        object_store: s3
        schema: v13
        index:
          prefix: loki_index_
          period: 24h
  storage_config:
    aws:
      region: <AWS region your bucket is in, for example, `eu-west-2`>
      bucketnames: <Your AWS bucket for chunk, for example, `aws-loki-dev-chunk`>
      s3forcepathstyle: false
  pattern_ingester:
    enabled: true
  limits_config:
    allow_structured_metadata: true
    volume_enabled: true
    retention_period: 672h # 28 days retention
  querier:
    max_concurrent: 4

  storage:
    type: s3
    bucketNames:
      chunks: <Your AWS bucket for chunk, for example, `aws-loki-dev-chunk`>
      ruler: <Your AWS bucket for ruler, for example,  `aws-loki-dev-ruler`>
      admin: <Your AWS bucket for admin, for example,  `aws-loki-dev-admin`>
    s3:
      # s3 URL can be used to specify the endpoint, access key, secret key, and bucket name this works well for S3 compatible storages or if you are hosting Loki on-premises and want to use S3 as the storage backend. Either use the s3 URL or the individual fields below (AWS endpoint, region, secret).
      s3: s3://access_key:secret_access_key@custom_endpoint/bucket_name
      # AWS endpoint URL
      endpoint: <YOUR_ENDPOINT>
      # AWS region where the S3 bucket is located
      region: <YOUR_REGION>
      # AWS secret access key
      secretAccessKey: <YOUR_SECRET_ACCESS_KEY>
      # AWS access key ID
      accessKeyId: <YOUR_ACCESS_KEY_ID>
      # AWS signature version (e.g., v2 or v4)
      signatureVersion: <YOUR_SIGNATURE_VERSION>
      # Forces the path style for S3 (true/false)
      s3ForcePathStyle: false
      # Allows insecure (HTTP) connections (true/false)
      insecure: false
      # HTTP configuration settings
      http_config: {}

deploymentMode: SimpleScalable

backend:
  replicas: 3
read:
  replicas: 3
write:
  replicas: 3

# Disable minio storage
minio:
  enabled: false

{{< /collapse >}}

{{< collapse title="Azure" >}}

yaml

loki:
  schemaConfig:
    configs:
      - from: "2024-04-01"
        store: tsdb
        object_store: azure
        schema: v13
        index:
          prefix: loki_index_
          period: 24h
  ingester:
    chunk_encoding: snappy
  tracing:
    enabled: true
  querier:
    max_concurrent: 4

  storage:
    type: azure
    azure:
      # Name of the Azure Blob Storage account
      accountName: <YOUR_ACCOUNT_NAME>
      # Key associated with the Azure Blob Storage account
      accountKey: <YOUR_ACCOUNT_KEY>
      # Comprehensive connection string for Azure Blob Storage account (Can be used to replace endpoint, accountName, and accountKey)
      connectionString: <YOUR_CONNECTION_STRING>
      # Flag indicating whether to use Azure Managed Identity for authentication
      useManagedIdentity: false
      # Flag indicating whether to use a federated token for authentication
      useFederatedToken: false
      # Client ID of the user-assigned managed identity (if applicable)
      userAssignedId: <YOUR_USER_ASSIGNED_ID>
      # Timeout duration for requests made to the Azure Blob Storage account (in seconds)
      requestTimeout: <YOUR_REQUEST_TIMEOUT>
      # Domain suffix of the Azure Blob Storage service endpoint (e.g., core.windows.net)
      endpointSuffix: <YOUR_ENDPOINT_SUFFIX>
    bucketNames:
      chunks: "chunks"
      ruler: "ruler"
      admin: "admin"

deploymentMode: SimpleScalable

backend:
  replicas: 3
read:
  replicas: 3
write:
  replicas: 3

# Disable minio storage
minio:
  enabled: false

{{< /collapse >}}

To configure other storage providers, refer to the Helm Chart Reference.

Gateway API

As an alternative to traditional Kubernetes Ingress, the Loki Helm chart supports Gateway API routes. There are two independent options depending on whether you want to keep the nginx gateway or bypass it entirely.

Option 1: Expose the nginx gateway via Gateway API

Use gateway.route to replace gateway.ingress with a Gateway API route that points to the nginx gateway. This keeps nginx as the proxy but exposes it through a Gateway API resource instead of a traditional Ingress.

yaml
gateway:
  ingress:
    enabled: false  # disable traditional Ingress
  route:
    main:
      enabled: true
      kind: HTTPRoute
      parentRefs:
        - name: my-gateway
          namespace: gateway-namespace
      hostnames:
        - loki.example.com

Option 2: Bypass nginx and route directly to Loki services

Use the top-level route: key (mutually exclusive with the top-level ingress:) to route Gateway API traffic directly to Loki services, bypassing nginx. The chart auto-generates path-based rules that route write traffic to the write component and read traffic to the read component.

yaml
route:
  main:
    enabled: true
    kind: HTTPRoute
    parentRefs:
      - name: my-gateway
        namespace: gateway-namespace
    hostnames:
      - loki.example.com

For both options, if apiVersion is not set, the chart auto-detects the latest available Gateway API version installed in the cluster. Supported route kinds include HTTPRoute, GRPCRoute, TCPRoute, TLSRoute, and UDPRoute.

Next Steps