--- title: "Install the microservice Helm chart | Grafana Loki documentation" description: "Installing Loki in microservice mode using the Helm chart." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Install the microservice Helm chart This Helm Chart deploys Grafana Loki on Kubernetes. > 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](https://github.com/grafana-community/helm-charts). Please open issues and pull requests for the chart against the Grafana-community repo. > 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](https://github.com/grafana-community/helm-charts/blob/main/charts/loki/README.md#upgrading). This Helm chart deploys Loki to run Loki in [microservice mode](/docs/loki/next/get-started/deployment-modes/#microservices-mode) within a Kubernetes cluster. The microservices deployment is also referred to as a Distributed deployment. The microservices deployment mode runs components of Loki as distinct processes. The default Helm chart deploys the following components: - **Compactor component** (1 replica): Compacts and processes stored data. - **Distributor component** (3 replicas, maxUnavailable: 2): Distributes incoming requests. Up to 2 replicas can be unavailable during updates. - **IndexGateway component** (2 replicas, maxUnavailable: 1): Handles indexing. Up to 1 replica can be unavailable during updates. - **Ingester component** (3 replicas per zone): Handles ingestion of data. By default, zone-aware replication is enabled, creating three StatefulSets (zone-a, zone-b, zone-c) with one replica each. - **Querier component** (3 replicas, maxUnavailable: 2): Processes queries. Up to 2 replicas can be unavailable during updates. - **QueryFrontend component** (2 replicas, maxUnavailable: 1): Manages frontend queries. Up to 1 replica can be unavailable during updates. - **QueryScheduler component** (2 replicas): Schedules queries. - **Gateway** (1 NGINX replica): Exposes the Loki API and proxies requests to the correct Loki components. - **Loki Canary** (1 DaemonSet): Verifies the Loki deployment is in a healthy state. - **Chunks cache** (1 replica): Caches chunks data using memcached. - **Results cache** (1 replica): Caches query results using memcached. > Note > > Zone-aware replication is enabled by default for ingesters. This creates three ingester StatefulSets (one per zone) and requires the `rollout-operator` subchart. To disable zone-aware replication (for example, in development), set `ingester.zoneAwareReplication.enabled: false` in your `values.yaml`. > Note > > We do not recommend running in microservices mode with `filesystem` storage. For the purpose of this guide, we will use MinIO as the object storage to provide a complete example. ## Prerequisites - Helm 3 or above. See [Installing Helm](https://helm.sh/docs/intro/install/). - A running Kubernetes cluster (must have at least 3 nodes). ## Deploying the Helm chart for development and testing > Note > > If this is the first time you have deployed the Loki Helm chart since the move to the Community managed Helm chart, note that the URL for the chart has changed. For more information see the [Upgrade documentation](/docs/loki/next/setup/upgrade/upgrade-to-6x/). 1. Add the [Grafana Community chart repository](https://github.com/grafana-community/helm-charts) to Helm: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash helm repo add grafana-community https://grafana-community.github.io/helm-charts ``` 2. Update the chart repository: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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: YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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: Distributed ingester: replicas: 3 # To ensure data durability with replication zoneAwareReplication: enabled: false querier: replicas: 3 # Improve query performance via parallelism maxUnavailable: 2 queryFrontend: replicas: 2 maxUnavailable: 1 queryScheduler: replicas: 2 distributor: replicas: 3 maxUnavailable: 2 compactor: replicas: 1 indexGateway: replicas: 2 maxUnavailable: 1 bloomPlanner: replicas: 0 bloomBuilder: replicas: 0 bloomGateway: replicas: 0 backend: replicas: 0 read: replicas: 0 write: replicas: 0 singleBinary: replicas: 0 # This exposes the Loki gateway so it can be written to and queried externaly gateway: service: type: LoadBalancer # Enable minio for storage minio: enabled: true ``` 4. Install or upgrade the Loki deployment. - To install: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash helm install --values values.yaml loki grafana-community/loki ``` - To upgrade: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash helm upgrade --values values.yaml loki grafana-community/loki ``` 5. Verify that Loki is running: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash kubectl get pods -n loki ``` The output should an output similar to the following: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash loki-canary-8thrx 1/1 Running 0 167m loki-canary-h965l 1/1 Running 0 167m loki-canary-th8kb 1/1 Running 0 167m loki-chunks-cache-0 2/2 Running 0 167m loki-compactor-0 1/1 Running 0 167m loki-compactor-1 1/1 Running 0 167m loki-distributor-7c9bb8f4dd-bcwc5 1/1 Running 0 167m loki-distributor-7c9bb8f4dd-jh9h8 1/1 Running 0 167m loki-distributor-7c9bb8f4dd-np5dw 1/1 Running 0 167m loki-gateway-77bc447887-qgc56 1/1 Running 0 167m loki-index-gateway-0 1/1 Running 0 167m loki-index-gateway-1 1/1 Running 0 166m loki-ingester-zone-a-0 1/1 Running 0 167m loki-ingester-zone-b-0 1/1 Running 0 167m loki-ingester-zone-c-0 1/1 Running 0 167m loki-minio-0 1/1 Running 0 167m loki-querier-bb8695c6d-bv9x2 1/1 Running 0 167m loki-querier-bb8695c6d-bz2rw 1/1 Running 0 167m loki-querier-bb8695c6d-z9qf8 1/1 Running 0 167m loki-query-frontend-6659566b49-528j5 1/1 Running 0 167m loki-query-frontend-6659566b49-84jtx 1/1 Running 0 167m loki-query-frontend-6659566b49-9wfr7 1/1 Running 0 167m loki-query-scheduler-f6dc4b949-fknfk 1/1 Running 0 167m loki-query-scheduler-f6dc4b949-h4nwh 1/1 Running 0 167m loki-query-scheduler-f6dc4b949-scfwp 1/1 Running 0 167m loki-results-cache-0 2/2 Running 0 167m ``` ## Object Storage Configuration After testing Loki with [MinIO](https://min.io/docs/minio/kubernetes/upstream/index.html), we recommend configuring Loki with an object storage provider. The following examples shows how to configure Loki with different object storage providers: > 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](/blog/2024/06/27/grafana-security-update-grafana-loki-and-unintended-data-write-attempts-to-amazon-s3-buckets/). This caution does not apply when you are using MinIO. When using MinIO we recommend using the default bucket names. S3 YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml # Example configuration for Loki with S3 storage loki: schemaConfig: configs: - from: 2024-04-01 store: tsdb object_store: s3 schema: v13 index: prefix: loki_index_ period: 24h storage_config: aws: region: bucketnames: s3forcepathstyle: false ingester: chunk_encoding: snappy 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: ruler: admin: s3: # s3 URL can be used to specify the endpoint, access key, secret key, and bucket name this works well for S3 compatible storage 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: # AWS region where the S3 bucket is located region: # AWS secret access key secretAccessKey: # AWS access key ID accessKeyId: # AWS signature version (e.g., v2 or v4) signatureVersion: # Forces the path style for S3 (true/false) s3ForcePathStyle: false # Allows insecure (HTTP) connections (true/false) insecure: false # HTTP configuration settings http_config: {} deploymentMode: Distributed # Disable minio storage minio: enabled: false ingester: replicas: 3 zoneAwareReplication: enabled: false querier: replicas: 3 maxUnavailable: 2 queryFrontend: replicas: 2 maxUnavailable: 1 queryScheduler: replicas: 2 distributor: replicas: 3 maxUnavailable: 2 compactor: replicas: 1 indexGateway: replicas: 2 maxUnavailable: 1 bloomPlanner: replicas: 0 bloomBuilder: replicas: 0 bloomGateway: replicas: 0 backend: replicas: 0 read: replicas: 0 write: replicas: 0 singleBinary: replicas: 0 ``` Azure YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml # Example configuration for Loki with Azure Blob Storage 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: # Key associated with the Azure Blob Storage account accountKey: # Comprehensive connection string for Azure Blob Storage account (Can be used to replace endpoint, accountName, and accountKey) connectionString: # 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: # Timeout duration for requests made to the Azure Blob Storage account (in seconds) requestTimeout: # Domain suffix of the Azure Blob Storage service endpoint (e.g., core.windows.net) endpointSuffix: bucketNames: chunks: "chunks" ruler: "ruler" admin: "admin" deploymentMode: Distributed ingester: replicas: 3 zoneAwareReplication: enabled: false querier: replicas: 3 maxUnavailable: 2 queryFrontend: replicas: 2 maxUnavailable: 1 queryScheduler: replicas: 2 distributor: replicas: 3 maxUnavailable: 2 compactor: replicas: 1 indexGateway: replicas: 2 maxUnavailable: 1 bloomPlanner: replicas: 0 bloomBuilder: replicas: 0 bloomGateway: replicas: 0 backend: replicas: 0 read: replicas: 0 write: replicas: 0 singleBinary: replicas: 0 ``` To configure other storage providers, refer to the [Helm Chart Reference](../reference/). ## Gateway API As an alternative to traditional Kubernetes Ingress, the Loki Helm chart supports [Gateway API](https://gateway-api.sigs.k8s.io/) 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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 requests to the correct microservice components (distributor, query-frontend, ruler, compactor) when `deploymentMode: Distributed` is set. YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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`. ## Deploying the Loki Helm chart to a Production Environment > Note > > We are actively working on providing more guides for deploying Loki in production. We recommend running Loki at scale within a cloud environment like AWS, Azure, or GCP. The below guides will show you how to deploy a minimally viable production environment. - [Deploy Loki on AWS](/docs/loki/next/setup/install/helm/deployment-guides/aws/) - [Deploy Loki on Azure](/docs/loki/next/setup/install/helm/deployment-guides/azure/) ## Next Steps - Configure an agent to [send log data to Loki](/docs/loki/next/send-data/). - Monitor the Loki deployment using the [Meta Monitoring Helm chart](/docs/loki/next/setup/install/helm/monitor-and-alert/)