Documentation Grafana Loki Set up Upgrade Upgrade to Community Helm chart

Upgrade from the Loki Helm chart to the Community Helm chart

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 13.1.2 (appVersion 3.7.1) 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 13.x, which spans seven major chart versions (7 through 13), each with breaking changes.

Prerequisites

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:

  Bash Copy

  helm get values <RELEASE_NAME> -o yaml > backup-values.yaml

• Back up any persistent volumes and object store indexes.

Update your Helm repository

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:

Bash Copy

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:

Bash Copy

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 13.1.2

Or if you are using OCI for 7.x and later:

Bash Copy

helm upgrade <RELEASE_NAME> oci://ghcr.io/grafana-community/helm-charts/loki -f values.yaml --version 13.1.2

Update your values file for breaking changes

The following sections describe every breaking change between chart versions 6.55.0 and 13.x, grouped by the major version that introduced each change. Review each section and update your values file accordingly.

6.x to 7.0: Kubernetes API cleanup

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:

YAML Copy

rbac:
  pspEnabled: false        # remove this key
  pspAnnotations: {}       # remove this key

The rbac section in 13.x only contains:

YAML Copy

rbac:
  sccEnabled: false
  sccAllowHostDirVolumePlugin: false
  namespaced: false

7.x to 8.0: Enterprise support removed

Enterprise support is removed in the community Helm chart.

Remove the entire enterprise configuration section from your chart, including any enterprise.* keys:

YAML Copy

enterprise:
  enabled: false
  version: 3.6.5
  cluster_name: null
  license:
    contents: "NOTAVALIDLICENSE"
  useExternalLicense: false
  externalLicenseName: null
  externalConfigName: ""
  gelGateway: true

8.x to 9.0: Self-monitoring and Grafana Agent Operator removed

The monitoring.selfMonitoring section and the grafana-agent-operator subchart dependency have been removed.

Remove the monitoring.selfMonitoring section from your values file:

YAML Copy

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):

YAML Copy

monitoring:
  selfMonitoring:
    tenant:
      name: "self-monitoring"
      password: "my-password"

After (13.x):

YAML Copy

lokiCanary:
  tenant:
    name: "self-monitoring"
    password: "my-password"

9.x to 10.0: Index gateway persistence restructured

The indexGateway.persistence.inMemory field has been replaced with indexGateway.persistence.dataVolumeParameters for more consistent configuration across components.

Before (6.x):

YAML Copy

indexGateway:
  persistence:
    enabled: false
    inMemory: false
    size: 10Gi

After (13.x):

YAML Copy

indexGateway:
  persistence:
    enabled: false
    dataVolumeParameters:
      emptyDir: {}
    size: 10Gi

If you were using in-memory storage (inMemory: true), the equivalent configuration is:

YAML Copy

indexGateway:
  persistence:
    dataVolumeParameters:
      emptyDir:
        medium: Memory
        sizeLimit: 10Gi

10.x to 11.0: Legacy read target removed

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:

YAML Copy

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.

11.x to 12.0: Deployment mode renamed and default changed

The default deploymentMode has changed from SimpleScalable to Monolithic, and SingleBinary has been renamed to Monolithic.

Before (6.x default):

YAML Copy

deploymentMode: SimpleScalable

After (13.x default):

YAML Copy

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:

YAML Copy

deploymentMode: SimpleScalable

If you are running SingleBinary, update the value to the new name:

YAML Copy

# Before
deploymentMode: SingleBinary

# After
deploymentMode: Monolithic

If you are running Distributed, no change is needed.

12.x to 13.0: Ephemeral volume persistence flattened

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.

If you adopted the ephemeralDataVolume pattern from any intermediate community chart version, update your values as follows:

Before (12.x):

YAML Copy

<component>:
  persistence:
    ephemeralDataVolume:
      enabled: true
      accessModes:
        - ReadWriteOnce
      size: 10Gi
      storageClass: null

After (13.x):

YAML Copy

<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.

Review additional deprecations

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:

YAML Copy

# Deprecated
global:
  image:
    registry: null

# Use instead
global:
  imageRegistry: null

Perform the upgrade

After updating your values file, run the upgrade:

Bash Copy

helm upgrade <RELEASE_NAME> grafana-community/loki \
  -f your-updated-values.yaml \
  --version 13.1.2

Or using OCI:

Bash Copy

helm upgrade <RELEASE_NAME> oci://ghcr.io/grafana-community/helm-charts/loki \
  -f your-updated-values.yaml \
  --version 13.1.2

Verify the upgrade

Bash Copy

# 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

Post-migration cleanup

After a successful upgrade:

• Remove the old Helm repository if no longer needed:

  Bash Copy

  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.

Troubleshoot

Pods fail to start with PodSecurityPolicy errors

Cause: Leftover rbac.pspEnabled or rbac.pspAnnotations in your values file.

Fix: Remove both keys from your values file and re-run the upgrade.

Loki canary fails authentication

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.

Index gateway CrashLoopBackOff

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.

Unexpected deployment mode change

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.

Unknown field errors from enterprise values

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.

Unknown field ephemeralDataVolume

Cause: 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.

Further reading

• Community chart changelog
• Community chart README - Upgrading
• Helm chart 6.x upgrade guide