Upgrade Loki on Grafana Labs

Upgrade the Helm chart to 3.0

Thu, 09 Apr 2026 02:28:18 +0000

Upgrading from v2.x

v3.x represents a major milestone for this chart, showing a commitment by the Loki team to provide a better supported, scalable helm chart. In addition to moving the source code for this helm chart into the Loki repo itself, it also combines what were previously two separate charts, grafana/loki and grafana/loki-simple-scalable into one chart. This chart will automatically assume the “Single Binary” mode previously deployed by the grafana/loki chart if you are using a filesystem backend, and will assume the “Scalable” mode previously deployed by the grafana/loki-simple-scalable chart if you are using an object storage backend.

As a result of this major change, upgrades from the charts this replaces might be difficult. We are attempting to support the 3 most common upgrade paths.

Upgrade from grafana/loki using local filesystem storage
Upgrade from grafana/loki-simple-scalable using a cloud based object storage such as S3 or GCS, or an api compatible equivalent like MinIO.

Upgrading from `grafana/loki`

The default installation of grafana/loki is a single instance backed by filesystem storage that is not highly available. As a result, this upgrade method will involve downtime. The upgrade will involve deleting the previously deployed loki stateful set, the running the helm upgrade which will create the new one with the same name, which should attach to the existing PVC or ephemeral storage, thus preserving you data. We still highly recommend backing up all data before conducting the upgrade.

To upgrade, you will need at least the following in your values.yaml:

loki:
  commonConfig:
    replication_factor: 1
  storage:
    type: 'filesystem'

You will need to 1. Update the grafana helm repo, 2. delete the existing stateful set, and 3. upgrade making sure to have the values above included in your values.yaml. If you installed grafana/loki as loki in namespace loki, the commands would be:

helm repo update grafana
kubectl -n loki delete statefulsets.apps loki
helm upgrade loki grafana/loki \
  --values values.yaml \
  --namespace loki

You will need to manually delete the existing stateful set for the above command to work.

Notable changes

The grafana/loki chart used Secret as storage for configuration. You can set .loki.existingSecretForConfig to continue using Secret or migrate your configuration to a ConfigMap. Specifying the Loki config in values.yaml is still available. In the old chart it was under .config, the new chart allows specifying either .loki.config or .loki.structuredConfig which takes precedence.

Similarly when using extraVolumes, the configuration is now nested under .singleBinary.extraVolumes or .read.extraVolumes + .write.extraVolumes if you decide to migrate to the Loki scalable deployment mode.

Dependencies

The grafana/loki chart was only used to install Loki. New charts since v3.x also bundle two dependencies - minio and grafana-agent-operator. If you have already installed either of these independently and wish to continue managing them separately, you can explicitly disable these dependencies in your values.yaml as shown in the following examples:

minio:
  enabled: false

monitoring:
  selfMonitoring:
    enabled: false
    grafanaAgent:
      installOperator: false

Upgrading from `grafana/loki-simple-scalable`

As this chart is largely based off the grafana/loki-simple-scalable chart, you should be able to use your existing values.yaml file and just upgrade to the new chart name. For example, if you installed the grafana/loki-simple-scalable chart as loki in the namespace loki, your upgrade would be:

helm repo update grafana
helm upgrade loki grafana/loki \
  --values values.yaml \
  --namespace loki

Upgrade the Helm chart to 6.0

Thu, 09 Apr 2026 02:28:18 +0000

Upgrading to v6.x

v6.x of this chart introduces distributed mode but also introduces breaking changes from v5x.

Caution
If you have not yet migrated to TSDB, perform that migration before you upgrade your Loki Helm chart to v6.x.

Note
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. When you upgrade to Loki 3.x, you should choose either monolithic (single-binary) or microservices (distributed) as your deployment mode.

Tip
With the move to the Grafana-community/helm-charts repository, the chart numbering has changed. Major version updates signal breaking changes in the chart. For more information, refer to the README.

Changes

BREAKING: `deploymentMode` setting

This only breaks you if you are running the chart in Single Binary mode, you will need to set

deploymentMode: SingleBinary

BREAKING: `lokiCanary` section was moved

This section was moved from within the monitoring section to the root level of the values file.

BREAKING: `topologySpreadConstraints` and `podAffinity` converted to objects

Previously they were strings which were passed through tpl now they are normal objects which will be added to deployments.

Also we removed the soft constraint on zone.

BREAKING: `externalConfigSecretName` was removed and replaced

Instead you can now provide configObjectName which is used by Loki components for loading the config.

generatedConfigObjectName also can be used to control the name of the config object created by the chart.

This gives greater flexibility in using the chart to still generate a config object but allowing for another process to load and mutate this config into a new object which can be loaded by Loki and configObjectName

Monitoring

After some consideration of how this chart works with other charts provided by Grafana, we decided to deprecate the monitoring sections of this chart and take a new approach entirely to monitoring Loki, Mimir and Tempo with the Meta Monitoring Chart.

Reasons:

There were conflicts with this chart and the Mimir chart both installing the Agent Operator.
The Agent Operator is deprecated.
The dependency on the Prometheus operator is not one we are able to support well.

The Meta Monitoring Chart is an improvement over the previous approach because it allows for installing a clustered Grafana Agent which can send metrics, logs, and traces to Grafana Cloud, or letting you install a monitoring-only local installation of Loki, Mimir, Tempo, and Grafana.

The monitoring sections of this chart still exist but are disabled by default.

If you wish to continue using the self monitoring features you should use the following configuration, but please do note a future version of this chart will remove this capability completely:

monitoring:
  enabled: true
  selfMonitoring:
    enabled: true
    grafanaAgent:
      installOperator: true

Memcached is included and enabled by default

Caching is crucial to the proper operation of Loki and Memcached is now included in this chart and enabled by default for the chunksCache and resultsCache.

If you are already running Memcached separately you can remove your existing installation and use the Memcached deployments built into this chart.

Single Binary

Memcached also deploys for the Single Binary, but this may not be desired in resource constrained environments.

You can disable it with the following configuration:

chunksCache:
  enabled: false
resultsCache:
  enabled: false

With these caches disabled, Loki will return to defaults which enables an in-memory results and chunks cache, so you will still get some caching.

BREAKING: Zone-aware ingester StatefulSet serviceName fix (6.34.0+)

Affected users: Only deployments using zone-aware ingester replication (ingester.zoneAwareReplication.enabled: true)

In Helm chart version 6.34.0, PR #18558 fixed the serviceName field in zone-aware ingester StatefulSets to correctly reference headless services. However, since serviceName is an immutable field in Kubernetes StatefulSets, upgrading to 6.34.0 requires manual intervention.

Required action before upgrading to 6.34.0:

Check if you’re affected:
Bash
```
helm get values <RELEASE_NAME> | grep -A5 zoneAwareReplication
```
If enabled: true appears, you need to follow these steps.

Delete the StatefulSets (data will be preserved):

kubectl delete statefulset \
  <RELEASE_NAME>-ingester-zone-a \
  <RELEASE_NAME>-ingester-zone-b \
  <RELEASE_NAME>-ingester-zone-c \
  --cascade=orphan

Proceed with the Helm upgrade:

helm upgrade <RELEASE_NAME> grafana/loki --version 6.34.0

What happens:

PersistentVolumeClaims and data are preserved
New StatefulSets will be created with correct service references
Pods will restart and reattach to existing storage

Why this change was necessary: The previous configuration caused ingester scaling operations to fail because the rollout-operator couldn’t find the correct headless services for the /ingester/prepare-downscale endpoint.

BREAKING: Make access modes for persistence on all PVCs and StatefulSets editable (6.38.0+)

Version 6.38.0 of the Helm charts introduced the ability to edit the access modes for persistence on all PVCs and StatefulSets. This is a breaking change because it requires users to manually orphan StatefulSets before upgrading.

Required action before upgrading to 6.38.0:

Delete the StatefulSets (delete only the ones that exist in your deployment):

# Core components (SimpleScalable mode)
kubectl delete statefulset <RELEASE_NAME>-write --cascade=orphan
kubectl delete statefulset <RELEASE_NAME>-backend --cascade=orphan

# Single binary mode
kubectl delete statefulset <RELEASE_NAME> --cascade=orphan

# Distributed mode components
kubectl delete statefulset <RELEASE_NAME>-ingester --cascade=orphan

# Zone-aware ingester (if zoneAwareReplication.enabled is true)
kubectl delete statefulset <RELEASE_NAME>-ingester-zone-a --cascade=orphan
kubectl delete statefulset <RELEASE_NAME>-ingester-zone-b --cascade=orphan
kubectl delete statefulset <RELEASE_NAME>-ingester-zone-c --cascade=orphan

kubectl delete statefulset <RELEASE_NAME>-index-gateway --cascade=orphan
kubectl delete statefulset <RELEASE_NAME>-compactor --cascade=orphan
kubectl delete statefulset <RELEASE_NAME>-ruler --cascade=orphan
kubectl delete statefulset <RELEASE_NAME>-pattern-ingester --cascade=orphan
kubectl delete statefulset <RELEASE_NAME>-bloom-planner --cascade=orphan
kubectl delete statefulset <RELEASE_NAME>-bloom-gateway --cascade=orphan