docs/sources/setup/upgrade/upgrade-to-community/_index.md
The Loki Helm chart has moved from the Loki repository to the Grafana Community Helm Charts repository. Chart version 6.55.0 (appVersion 3.6.7) was the last release from the Loki repository. Chart version 17.2.0 (appVersion 3.7.2) is the current release from the community repository at the time this topic was published.
This guide walks you through upgrading from 6.55.0 to the current community chart version, which spans eleven major chart versions (7 through 17), each with breaking changes.
{{< admonition type="warning" >}}
Grafana Enterprise Logs (GEL) support was removed from the community chart in version 8.0.0. If you are a GEL user, do not migrate to the community chart. The grafana/loki chart remains available for GEL users.
{{< /admonition >}}
{{< admonition type="caution" >}} This upgrade spans several major versions with accumulated breaking changes. Test the upgrade in a non-production environment before applying it to production. {{< /admonition >}}
Before you begin:
Kubernetes 1.25 or later is required (enforced since chart version 7.0.0).
Helm 3.x is required.
Back up your current Helm release values:
helm get values <RELEASE_NAME> -o yaml > backup-values.yaml
Back up any persistent volumes and object store indexes.
The chart is now published to a different Helm repository and Open Container Initiative (OCI) registry. The official Helm documentation now recommends using OCI registries as they implement unified storage, distribution, and improved security.
Old location for 6.x from the Loki repository:
helm repo add grafana https://grafana.github.io/helm-charts
helm upgrade <RELEASE_NAME> grafana/loki -f values.yaml
New location for 7.x and later from the community repository:
helm repo add grafana-community https://grafana-community.github.io/helm-charts
helm repo update
helm upgrade <RELEASE_NAME> grafana-community/loki -f values.yaml --version 17.2.0
Or if you are using OCI for 7.x and later:
helm upgrade <RELEASE_NAME> oci://ghcr.io/grafana-community/helm-charts/loki -f values.yaml --version 17.2.0
The following sections describe every breaking change between chart versions 6.55.0 and 17.x, grouped by the major version that introduced each change. Review each section and update your values file accordingly.
{{< admonition type="caution" >}} Check the Loki Helm Chart README for the latest changes and upgrade information. The Grafana Community is constantly improving the charts. {{< /admonition >}}
Support for deprecated Kubernetes APIs and PodSecurityPolicy has been removed. Kubernetes 1.25 or later is now required.
Remove the following from your values file:
rbac:
pspEnabled: false # remove this key
pspAnnotations: {} # remove this key
The rbac section in 13.x only contains:
rbac:
sccEnabled: false
sccAllowHostDirVolumePlugin: false
namespaced: false
| If you have | using | update them to |
|---|---|---|
| custom Ingress resources | networking.k8s.io/v1beta1 | networking.k8s.io/v1 |
| PodDisruptionBudget resources | policy/v1beta1 | policy/v1 |
Enterprise support is removed in the community Helm chart.
Remove the entire enterprise configuration section from your chart, including any enterprise.* keys:
enterprise:
enabled: false
version: 3.6.5
cluster_name: null
license:
contents: "NOTAVALIDLICENSE"
useExternalLicense: false
externalLicenseName: null
externalConfigName: ""
gelGateway: true
{{< admonition type="note" >}} The Helm Chart in the Loki repository is being maintained for GEL customers only. {{< /admonition >}}
The monitoring.selfMonitoring section and the grafana-agent-operator subchart dependency have been removed.
Remove the monitoring.selfMonitoring section from your values file:
monitoring:
selfMonitoring:
enabled: false
tenant:
name: "self-monitoring"
password: null
secretNamespace: '{{ include "loki.namespace" . }}'
grafanaAgent:
installOperator: false
annotations: {}
labels: {}
enableConfigReadAPI: false
priorityClassName: null
resources: {}
tolerations: []
podLogs:
apiVersion: monitoring.grafana.com/v1alpha1
# ...
logsInstance:
# ...
Also remove monitoring.serviceMonitor.metricsInstance, if present. It referenced a Grafana Agent CRD that no longer exists.
Loki canary tenant authentication has moved from monitoring.selfMonitoring.tenant to the top-level lokiCanary.tenant section. If you were using canary tenant auth, update as follows:
Before (6.x):
monitoring:
selfMonitoring:
tenant:
name: "self-monitoring"
password: "my-password"
After (13.x):
lokiCanary:
tenant:
name: "self-monitoring"
password: "my-password"
{{< admonition type="tip" >}} Grafana Alloy is the successor to Grafana Agent. If you relied on Agent-based self-monitoring, consider using Alloy for log collection. {{< /admonition >}}
The indexGateway.persistence.inMemory field has been replaced with indexGateway.persistence.dataVolumeParameters for more consistent configuration across components.
Before (6.x):
indexGateway:
persistence:
enabled: false
inMemory: false
size: 10Gi
After (13.x):
indexGateway:
persistence:
enabled: false
dataVolumeParameters:
emptyDir: {}
size: 10Gi
If you were using in-memory storage (inMemory: true), the equivalent configuration is:
indexGateway:
persistence:
dataVolumeParameters:
emptyDir:
medium: Memory
sizeLimit: 10Gi
The read.legacyReadTarget option has been removed. Simple scalable deployments now always require a dedicated backend target (read, write, and backend).
Remove from your values file if present:
read:
legacyReadTarget: false # remove this key
If you had legacyReadTarget: true (running the 2-target read/write mode without a backend), you must now run the 3-target mode (read, write, backend) or switch to a different deployment mode.
The default deploymentMode has changed from SimpleScalable to Monolithic, and SingleBinary has been renamed to Monolithic.
Before (6.x default):
deploymentMode: SimpleScalable
After (13.x default):
deploymentMode: Monolithic
Action required based on your current mode:
If you are running SimpleScalable (the 6.x default), explicitly set it in your values file to preserve your current deployment:
deploymentMode: SimpleScalable
{{< admonition type="note" >}}
SimpleScalable is deprecated and will be removed in Loki 4.0. Plan to migrate to Monolithic or Distributed.
{{< /admonition >}}
If you are running SingleBinary, update the value to the new name:
# Before
deploymentMode: SingleBinary
# After
deploymentMode: Monolithic
If you are running Distributed, no change is needed.
The persistence configuration for ephemeral volumes has been flattened across all components. The nested persistence.ephemeralDataVolume structure has been replaced with a persistence.type field.
{{< admonition type="note" >}}
If you are migrating directly from 6.55.0 and have never used the ephemeralDataVolume configuration introduced in the community chart, this change doesn't require action on your existing values. However, be aware of the new persistence.type field when configuring persistence for components like the compactor or bloom-builder.
{{< /admonition >}}
If you adopted the ephemeralDataVolume pattern from any intermediate community chart version, update your values as follows:
Before (12.x):
<component>:
persistence:
ephemeralDataVolume:
enabled: true
accessModes:
- ReadWriteOnce
size: 10Gi
storageClass: null
After (13.x):
<component>:
persistence:
enabled: true
type: ephemeral
accessModes:
- ReadWriteOnce
size: 10Gi
storageClass: null
The type field accepts pvc (default for most components) or ephemeral. Fields that were nested under ephemeralDataVolume (accessModes, size, storageClass, volumeAttributesClassName, selector, annotations, labels) now sit directly under persistence.
The dot-based registry format has been removed. Previously, if the repository value contained a dot (.) in its first path segment, the chart assumed the full registry was already included and silently skipped prepending global.imageRegistry or a component-level image.registry. This caused configured registries to be ignored for references such as mirror.gcr.io/grafana/loki.
The new behavior is that a configured registry is always prepended, unconditionally. global.imageRegistry is the highest-precedence registry setting and overrides all component-level image.registry values.
If you stored a fully-qualified image reference in repository and relied on the old format to prevent double-prefixing, split the value into separate registry and repository fields:
Before (13.x):
loki:
image:
repository: private.registry.com/grafana/loki
After (14.x):
loki:
image:
registry: private.registry.com
repository: grafana/loki
Users who only set repository to a plain path (for example, grafana/loki) or who already use global.imageRegistry / image.registry correctly are unaffected.
Support for Cilium-specific network policies has been removed. The chart now renders Kubernetes NetworkPolicy resources only.
Remove the following from your values file:
networkPolicy:
flavor: cilium # remove this key
egressWorld:
enabled: true # remove this section
egressKubeApiserver:
enabled: true # remove this section
After (15.x):
networkPolicy:
enabled: true
If you relied on Cilium-only behavior such as CiliumNetworkPolicy resources, manage those rules outside the Loki chart using separate manifests or your GitOps workflow.
The loki-canary workload no longer inherits metadata from the shared Loki pod template. Canary-specific metadata that was previously sourced from loki.* keys must now be set explicitly under lokiCanary.*.
Before (15.x):
loki:
annotations:
team: observability
serviceAnnotations:
prometheus.io/scrape: "true"
serviceLabels:
app: loki
After (16.x):
lokiCanary:
annotations:
team: observability
podAnnotations:
team: observability
service:
annotations:
prometheus.io/scrape: "true"
labels:
app: loki-canary
automountServiceAccountToken: false
If you did not set any loki.annotations, loki.serviceAnnotations, or loki.serviceLabels for canary purposes, no action is required.
The built-in MinIO subchart is officially deprecated and will be removed on 2026-10-31. Setting minio.enabled=true now fails chart rendering unless the workaround ignoreMinioDeprecation: true is also set.
If you need to continue using the built-in MinIO subchart temporarily while you plan a migration:
ignoreMinioDeprecation: true # Remove before 2026-10-31
minio:
enabled: true
Grafana recommends migrating to a dedicated external object storage backend. The following steps preserve data continuity using a dual-store transition period.
Before (legacy state using built-in MinIO):
minio:
enabled: true
loki:
schemaConfig:
configs:
- from: "2024-01-01"
store: tsdb
object_store: s3
schema: v13
index:
prefix: index_
period: 24h
Transition release (temporary dual-store period):
Keep old MinIO data readable while writing new data to external storage:
ignoreMinioDeprecation: true
minio:
enabled: true
loki:
structuredConfig:
storage_config:
named_stores:
aws:
minio:
endpoint: '{{ include "loki.minio" $ }}'
bucketnames: chunks
secret_access_key: '{{ $.Values.minio.rootPassword }}'
access_key_id: '{{ $.Values.minio.rootUser }}'
s3forcepathstyle: true
insecure: true
s3-loki-chunks:
endpoint: 's3.example.com'
bucketnames: chunks
access_key_id: '<s3-access-key>'
secret_access_key: '<s3-secret-key>'
s3forcepathstyle: true
insecure: true
schema_config:
configs:
- from: "2024-01-01"
store: tsdb
object_store: minio
schema: v13
index:
prefix: index_
period: 24h
- from: "<date shortly after migration start>"
store: tsdb
object_store: s3-loki-chunks
schema: v13
index:
prefix: index_
period: 24h
Final release (after retention has elapsed):
Once the retention window for data in MinIO has elapsed, remove the MinIO configuration entirely. The chart still requires loki.storage.bucketNames for helper-generated storage sections:
loki:
storage:
bucketNames:
chunks: chunks
ruler: ruler
structuredConfig:
storage_config:
named_stores:
aws:
s3-loki-chunks:
endpoint: 's3.example.com'
bucketnames: chunks
access_key_id: '<s3-access-key>'
secret_access_key: '<s3-secret-key>'
s3forcepathstyle: true
insecure: true
schema_config:
configs:
- from: "<date from transition release>"
store: tsdb
object_store: s3-loki-chunks
schema: v13
index:
prefix: index_
period: 24h
For more information on storage schema configuration, see Storage schema.
Several per-component fields have been deprecated in favor of unified blocks. These deprecated per-component service fields apply to indexGateway, compactor, and others.
These still work but will be removed in a future release. Consider updating them now:
| Deprecated | Use | | ------------------------------- | ------------------------------- -- | | indexGateway.serviceLabels | indexGateway.service.labels | | indexGateway.serviceAnnotations | indexGateway.service.annotations | | indexGateway.serviceType | indexGateway.service.type | | indexGateway.appProtocol | indexGateway.service.type | | indexGateway.maxUnavailable | podDisruptionBudget.maxUnavailable |
The global image registry override has also been renamed:
# Deprecated
global:
image:
registry: null
# Use instead
global:
imageRegistry: null
After updating your values file, run the upgrade:
helm upgrade <RELEASE_NAME> grafana-community/loki \
-f your-updated-values.yaml \
--version 17.2.0
Or using OCI:
helm upgrade <RELEASE_NAME> oci://ghcr.io/grafana-community/helm-charts/loki \
-f your-updated-values.yaml \
--version 17.2.0
# Check all pods are running
kubectl get pods -l app.kubernetes.io/name=loki
# Verify Loki is accepting writes
kubectl logs -l app.kubernetes.io/component=write --tail=50
# Verify Loki canary is healthy (if enabled)
kubectl logs -l app.kubernetes.io/component=loki-canary --tail=20
After a successful upgrade:
Remove the old Helm repository if no longer needed:
helm repo remove grafana
Update any CI/CD pipelines to reference grafana-community/loki or the OCI URL oci://ghcr.io/grafana-community/helm-charts/loki.
Review monitoring dashboards for renamed metrics. Refer to the Loki 3.x upgrade notes for metric namespace changes.
Cause: Leftover rbac.pspEnabled or rbac.pspAnnotations in your values file.
Fix: Remove both keys from your values file and re-run the upgrade.
Cause: Canary tenant configuration was under monitoring.selfMonitoring.tenant in 6.x and has moved to lokiCanary.tenant in 13.x.
Fix: Move tenant.name and tenant.password to the lokiCanary.tenant section.
Cause: The old indexGateway.persistence.inMemory field is no longer recognized.
Fix: Replace inMemory: true with the equivalent dataVolumeParameters configuration as described in 9.x to 10.0.
Cause: The default deploymentMode changed from SimpleScalable to Monolithic. If you relied on the default without explicitly setting it, your deployment mode changed on upgrade.
Fix: Explicitly set deploymentMode: SimpleScalable in your values file (or choose Monolithic or Distributed) and re-run the upgrade.
Cause: The enterprise.* section was removed in 8.0.0. Any leftover keys cause Helm to reject the values.
Fix: Remove the entire enterprise section from your values file.
ephemeralDataVolumeCause: The nested persistence.ephemeralDataVolume structure was flattened in 13.0.0. If you adopted this pattern from an intermediate community chart version, the old keys are no longer recognized.
Fix: Replace persistence.ephemeralDataVolume.enabled: true with persistence.enabled: true and persistence.type: ephemeral, and move all nested fields directly under persistence as described in 12.x to 13.0.
minio.enabled=true fails chart renderingCause: The built-in MinIO subchart was deprecated in 17.0.0. Setting minio.enabled=true without ignoreMinioDeprecation: true causes chart rendering to fail with the error:
The Loki chart builtin MinIO dependency is deprecated and will be removed 2026-10-31.
Fix: Either set ignoreMinioDeprecation: true as a temporary workaround while you plan a migration, or migrate to an external object storage backend. See 16.x to 17.0 for migration steps.
Cause: The dot-based registry format was removed in 14.0.0. If you had a fully-qualified image reference such as private.registry.com/grafana/loki in the repository field, the configured registry is now prepended unconditionally, resulting in a double-prefixed reference.
Fix: Split the fully-qualified reference into separate registry and repository fields as described in 13.x to 14.0.
Cause: The loki-canary workload no longer inherits metadata from the shared loki.* pod template values. Settings such as loki.annotations and loki.serviceAnnotations are no longer applied to the canary.
Fix: Move canary-specific metadata to the lokiCanary.* section as described in 15.x to 16.0.