Migration guides on Grafana Labs

Migrate from Cortex to Grafana Mimir

Mon, 29 Jun 2026 07:50:30 +0000

Migrate from Cortex to Grafana Mimir

As an operator, you can migrate a Helm deployment of Cortex to Grafana Mimir. The overview includes the steps required for any environment. To migrate deployment environments with Helm, see Migrate to Grafana Mimir using Helm.

Note: This document was tested with Cortex versions 1.10 and 1.11. It might work with more recent versions of Cortex, but that is not guaranteed.

To migrate a Jsonnet deployment of Cortex refer to [Migrate from Cortex].

Grafana Mimir includes significant changes that simplify the deployment and continued operation of a horizontally scalable, multi-tenant time series database with long-term storage.

The changes make Grafana Mimir easier to run out of the box:

Removed configuration parameters that don’t require tuning
Renamed some parameters so that they’re more easily understood
Updated the default values of some existing parameters

The mimirtool automates configuration conversion. It provides a simple migration by generating Mimir configuration from Cortex configuration.

Before you begin:

Ensure that you are running either Cortex 1.10.X or Cortex 1.11.X.

If you are running an older version of Cortex, upgrade to Cortex 1.11.1 before proceeding with the migration.
Ensure you have installed Cortex alerting and recording rules as well as Cortex dashboards.

Using the monitoring mixin, you need to install both alerting and recording rules in either Prometheus or Cortex. You also need to install dashboards in Grafana. To download a prebuilt ZIP file that contains the alerting and recording rules, refer to Release Cortex-jsonnet 1.11.0.

To upload rules to the ruler using mimirtool, refer to [mimirtool rules]. To import the dashboards into Grafana, refer to Import dashboard .

Notable changes

Note: For the full list of changes, refer to Mimir’s CHANGELOG.

The Grafana Mimir HTTP server defaults to listening on port 8080; Cortex defaults to listening on port 80. To maintain port 80 as the listening port, set -server.http-listen-port=80.
Grafana Mimir uses anonymous as the default tenant ID when -auth.multitenancy=false. Cortex uses fake as the default tenant ID when -auth.enabled=false. Use -auth.no-auth-tenant=fake when -auth.multitenancy=false to match the Cortex default tenant ID.

Grafana Mimir removes the legacy HTTP prefixes deprecated in Cortex.

Query endpoints

Legacy	Current
`/<legacy-http-prefix>/api/v1/query`	`<prometheus-http-prefix>/api/v1/query`
`/<legacy-http-prefix>/api/v1/query_range`	`<prometheus-http-prefix>/api/v1/query_range`
`/<legacy-http-prefix>/api/v1/query_exemplars`	`<prometheus-http-prefix>/api/v1/query_exemplars`
`/<legacy-http-prefix>/api/v1/series`	`<prometheus-http-prefix>/api/v1/series`
`/<legacy-http-prefix>/api/v1/labels`	`<prometheus-http-prefix>/api/v1/labels`
`/<legacy-http-prefix>/api/v1/label/{name}/values`	`<prometheus-http-prefix>/api/v1/label/{name}/values`
`/<legacy-http-prefix>/api/v1/metadata`	`<prometheus-http-prefix>/api/v1/metadata`
`/<legacy-http-prefix>/api/v1/read`	`<prometheus-http-prefix>/api/v1/read`
`/<legacy-http-prefix>/api/v1/cardinality/label_names`	`<prometheus-http-prefix>/api/v1/cardinality/label_names`
`/<legacy-http-prefix>/api/v1/cardinality/label_values`	`<prometheus-http-prefix>/api/v1/cardinality/label_values`
`/api/prom/user_stats`	`/api/v1/user_stats`

Distributor endpoints

Legacy endpoint	Current
`/<legacy-http-prefix>/push`	`/api/v1/push`
`/all_user_stats`	`/distributor/all_user_stats`
`/ha-tracker`	`/distributor/ha_tracker`

Ingester endpoints

Legacy	Current
`/ring`	`/ingester/ring`
`/shutdown`	`/ingester/shutdown`
`/flush`	`/ingester/flush`
`/push`	`/ingester/push`

Ruler endpoints

Legacy	Current
`/<legacy-http-prefix>/api/v1/rules`	`<prometheus-http-prefix>/api/v1/rules`
`/<legacy-http-prefix>/api/v1/alerts`	`<prometheus-http-prefix>/api/v1/alerts`
`/<legacy-http-prefix>/rules`	`<prometheus-http-prefix>/config/v1/rules`
`/<legacy-http-prefix>/rules/{namespace}`	`<prometheus-http-prefix>/config/v1/rules/{namespace}`
`/<legacy-http-prefix>/rules/{namespace}/{groupName}`	`<prometheus-http-prefix>/config/v1/rules/{namespace}/{groupName}`
`/<legacy-http-prefix>/rules/{namespace}`	`<prometheus-http-prefix>/config/v1/rules/{namespace}`
`/<legacy-http-prefix>/rules/{namespace}/{groupName}`	`<prometheus-http-prefix>/config/v1/rules/{namespace}/{groupName}`
`/<legacy-http-prefix>/rules/{namespace}`	`<prometheus-http-prefix>/config/v1/rules/{namespace}`
`/ruler_ring`	`/ruler/ring`

Alertmanager endpoints

Legacy	Current
`/<legacy-http-prefix>`	`/alertmanager`
`/status`	`/multitenant_alertmanager/status`

Generate the configuration for Grafana Mimir

The [mimirtool config convert] command converts Cortex configuration to Mimir configuration. You can use it to update both flags and configuration files.

Install mimirtool

To install Mimirtool, download the appropriate binary from the latest release for your operating system and architecture and make it executable.

Alternatively, use a command line tool such as curl to download mimirtool. For example, for Linux with the AMD64 architecture, use the following command:

curl -fLo mimirtool https://github.com/grafana/mimir/releases/latest/download/mimirtool-linux-amd64
chmod +x mimirtool

Use mimirtool

The mimirtool config convert command converts Cortex 1.11 configuration files to Grafana Mimir configuration files. It removes any configuration parameters that are no longer available in Grafana Mimir, and it renames configuration parameters that have a new name. If you have explicitly set configuration parameters to a value matching the Cortex default, by default, mimirtool config convert doesn’t update the value. To have mimirtool config convert update explicitly set values from the Cortex defaults to the new Grafana Mimir defaults, provide the --update-defaults flag. Refer to [convert] for more information on using mimirtool for configuration conversion.

Migrate to Grafana Mimir using Helm

You can migrate to the Grafana Mimir Helm chart (grafana/mimir-distributed v3.1.0) from the Cortex Helm chart (cortex-helm/cortex v1.7.0).

Before you begin

Ensure that you are running the v1.7.0 release of the Cortex Helm chart.
Ensure that you are running ingesters using a Kubernetes StatefulSet.
Install yq v4.

In the values.yaml file:
```
ingester:
  statefulSet:
    enabled: true
```
The ingester needs storage capacity for write-ahead-logging (WAL) and to create blocks for uploading. The WAL was optional in Cortex with chunks, but not optional in Mimir. A StatefulSet is the most convenient way to make sure that each Pod gets a dedicated storage volume.

To migrate to the Grafana Mimir Helm chart:

Install the updated monitoring mixin.

a. Add the dashboards to Grafana. The dashboards replace your Cortex dashboards and continue to work for monitoring Cortex deployments.

Note: Resource dashboards are now enabled by default and require additional metrics sources. To understand the required metrics sources, refer to [Additional resources metrics].

b. Install the recording and alerting rules into the ruler or a Prometheus server.
Run the following command to add the Grafana Helm chart repository:
Bash
```
helm repo add grafana https://grafana.github.io/helm-charts
```
Convert the Cortex configuration in your values.yaml file.

a. Extract the Cortex configuration and write the output to the cortex.yaml file.
Bash
```
yq '.config' <VALUES YAML FILE> > cortex.yaml
```
b. Use mimirtool to update the configuration.
Bash
```
mimirtool config convert --yaml-file cortex.yaml --yaml-out mimir.yaml
```
c. Clean up the generated YAML configuration.

You have to remove some fields that are generated by mimirtool config convert or are coming from old configuration, because the mimir-distributed Helm chart has already set the default value for them. Use the following script to clean up those fields:
Bash
```
yq -i 'del(.activity_tracker.filepath,.alertmanager.data_dir,.compactor.data_dir,.frontend_worker.frontend_address,.ingester.ring.tokens_file_path,.ruler.alertmanager_url,.ruler.rule_path,.runtime_config.file)' mimir.yaml
```
d. At the top level of your custom Helm values file, put the updated configuration under the mimir.structuredConfig key.

Note: The mimir.structuredConfig field, which is added in v3.0.0, allows you to override a specific configuration without needing to rewrite the whole block string literal, such as in mimir.config.

In your Helm values file:
YAML
```
mimir:
  structuredConfig: <CONFIGURATION FILE CONTENTS>
```
Example:
YAML
```
mimir:
  structuredConfig:
    ingester:
      ring:
        num_tokens: 512
```
e. Set the ingester podManagementPolicy to "OrderedReady". The Grafana Mimir chart prefers "Parallel" for faster scale up, but this field is immutable on an existing StatefulSet.

In your values.yaml file:
YAML
```
ingester:
  podManagementPolicy: "OrderedReady"
```
f. Set the nameOverride parameter to cortex. This configuration parameter ensures that resources have the same names as those created by the Cortex Helm chart and ensures Kubernetes performs a rolling upgrade of existing resources instead of creating new resources.

In your values.yaml file:
YAML
```
nameOverride: "cortex"
```
g. Disable MinIO. The Grafana Mimir Helm chart enables MinIO by default for convenience during first time install. If you are migrating from Cortex and have your existing object storage you must disable MinIO in Grafana Mimir Helm chart custom values.yaml.

In your values.yaml file:
YAML
```
minio:
  enabled: false
```
Run the Helm upgrade with the Grafana Mimir chart.

Note: The name of the release must match your Cortex Helm chart release.
Bash
```
helm upgrade <RELEASE> grafana/mimir-distributed [-n <NAMESPACE>]
```

To verify that the cluster is operating correctly, use the [monitoring mixin dashboards].

Migrate from single zone to zone-aware replication in Mimir Helm chart version 4.0

Mon, 29 Jun 2026 07:50:30 +0000

Migrate from single zone to zone-aware replication in Mimir Helm chart version 4.0

The mimir-distributed Helm chart version 4.0 enables zone-aware replication by default. This is a breaking change for existing installations and requires a migration.

This document explains how to migrate stateful components from single zone to zone-aware replication with Helm. The three components in question are the alertmanager, the store-gateway and the ingester.

The migration path of Alertmanager and store-gateway is straight forward, however migrating ingesters is more complicated.

Prerequisite

Depending on what version of the mimir-distributed Helm chart is installed currently, make sure to meet the following requirements.

If the current version of the mimir-distributed Helm chart is less than 4.0.0 (version < 4.0.0).
1. Follow the upgrade instructions for 4.0.0 in the CHANGELOG.md. In particular make sure to disable zone awareness before upgrading the chart:
  YAML
```
ingester:
  zoneAwareReplication:
    enabled: false
store_gateway:
  zoneAwareReplication:
    enabled: false
rollout_operator:
  enabled: false
```
  Note
```
  A direct upgrade from non-zone aware ingesters to zone-aware ingesters will cause data loss.
```
2. If you have modified the mimir.config value, either make sure to merge in the latest version from the chart, or consider using mimir.structuredConfig instead.
  
  For more information, see Manage the configuration of Grafana Mimir with Helm.
If the current version of the mimir-distributed Helm chart is greater than 4.0.0 (version >= 4.0.0).
1. Make sure that zone-aware replication is turned off for the component in question.
  
  For example, the store-gateway:
  YAML
```
store_gateway:
  zoneAwareReplication:
    enabled: false
```
2. If you have modified the mimir.config value, either make sure to merge in the latest version from the chart, or consider using mimir.structuredConfig instead.
  
  For more information, see Manage the configuration of Grafana Mimir with Helm.

Migrate alertmanager to zone-aware replication

Using zone-aware replication for alertmanager is optional and is only available if alertmanager is deployed as a StatefulSet.

Configure zone-aware replication for Alertmanagers

This section is about planning and configuring the availability zones defined under the alertmanager.zoneAwareReplication Helm value.

There are two use cases in general:

Speeding up rollout of alertmanagers in case there are more than 3 replicas. In this case use the default value in the small.yaml, large.yaml, capped-small.yaml or capped-large.yaml. The default value defines 3 “virtual” zones and sets affinity rules so that alertmanagers from different zones do not mix, but it allows multiple alertmanagers of the same zone on the same node:
YAML
```
alertmanager:
  zoneAwareReplication:
    topologyKey: "kubernetes.io/hostname" # Triggers creating anti-affinity rules
```

Geographical redundancy. In this case you need to set a suitable nodeSelector value to choose where the pods of each zone are to be placed. Setting topologyKey will instruct the Helm chart to create anti-affinity rules so that alertmanagers from different zones do not mix, but it allows multiple alertmanagers of the same zone on the same node. For example:

alertmanager:
  zoneAwareReplication:
    topologyKey: "kubernetes.io/hostname" # Triggers creating anti-affinity rules
    zones:
      - name: zone-a
        nodeSelector:
          topology.kubernetes.io/zone: us-central1-a
      - name: zone-b
        nodeSelector:
          topology.kubernetes.io/zone: us-central1-b
      - name: zone-c
        nodeSelector:
          topology.kubernetes.io/zone: us-central1-c

Note: as the zones value is an array, you must copy and modify it to make changes to it, there is no way to overwrite just parts of the array!

Set the chosen configuration in your custom values (e.g. custom.yaml).

Note: The number of alertmanager Pods that will be started is derived from alertmanager.replicas. Each zone will start alertmanager.replicas / number of zones pods, rounded up to the nearest integer value. For example if you have 3 zones, then alertmanager.replicas=3 will yield 1 alertmanager per zone, but alertmanager.replicas=4 will yield 2 per zone, 6 in total.

Migrate Alertmanager

Before starting this procedure, set up your zones according to Configure zone-aware replication for alertmanagers.

Create a new empty YAML file called migrate.yaml.

Start the migration.

Copy the following into the migrate.yaml file:

alertmanager:
  zoneAwareReplication:
    enabled: true
    migration:
      enabled: true

rollout_operator:
  enabled: true

Upgrade the installation with the helm command and make sure to provide the flag -f migrate.yaml as the last flag.

In this step zone-awareness is enabled with the default zone and new StatefulSets are created for zone-aware alertmanagers, but no new pods are started.
Wait until all alertmanagers are restarted and are ready.

Scale up zone-aware alertmanagers.

Replace the contents of the migrate.yaml file with:

alertmanager:
  zoneAwareReplication:
    enabled: true
    migration:
      enabled: true
      writePath: true

rollout_operator:
  enabled: true

Upgrade the installation with the helm command and make sure to provide the flag -f migrate.yaml as the last flag.
Wait until all new zone-aware alertmanagers are started and are ready.
Set the final configuration.

Merge the following values into your custom Helm values file:
YAML
```
alertmanager:
  zoneAwareReplication:
    enabled: true

rollout_operator:
  enabled: true
```
Upgrade the installation with the helm command using your regular command line flags.
Ensure that the Service and StatefulSet resources of the non zone-aware alertmanagers have been deleted. The previous step also removes the Service and StatefulSet manifests of the old non zone-aware alertmanagers. In some cases, such as when using Helm from Tanka, these resources will not be automatically deleted from your Kubernetes cluster even if the Helm chart no longer renders them. If the old resources still exist, delete them manually. If not deleted, some of the pods may be scraped multiple times when using the Prometheus operator for metamonitoring.
Wait until old non zone-aware alertmanagers are terminated.

Migrate store-gateways to zone-aware replication

Configure zone-aware replication for store-gateways

This section is about planning and configuring the availability zones defined under the store_gateway.zoneAwareReplication Helm value.

There are two use cases in general:

Speeding up rollout of store-gateways in case there are more than 3 replicas. In this case use the default value in the small.yaml, large.yaml, capped-small.yaml or capped-large.yaml. The default value defines 3 “virtual” zones and sets affinity rules so that store-gateways from different zones do not mix, but it allows multiple store-gateways of the same zone on the same node:
YAML
```
store_gateway:
  zoneAwareReplication:
    enabled: false # Do not turn on zone-awareness without migration because of potential query errors
    topologyKey: "kubernetes.io/hostname" # Triggers creating anti-affinity rules
```

Geographical redundancy. In this case you need to set a suitable nodeSelector value to choose where the pods of each zone are to be placed. Setting topologyKey will instruct the Helm chart to create anti-affinity rules so that store-gateways from different zones do not mix, but it allows multiple store-gateways of the same zone on the same node. For example:

store_gateway:
  zoneAwareReplication:
    enabled: false # Do not turn on zone-awareness without migration because of potential query errors
    topologyKey: "kubernetes.io/hostname" # Triggers creating anti-affinity rules
    zones:
      - name: zone-a
        nodeSelector:
          topology.kubernetes.io/zone: us-central1-a
      - name: zone-b
        nodeSelector:
          topology.kubernetes.io/zone: us-central1-b
      - name: zone-c
        nodeSelector:
          topology.kubernetes.io/zone: us-central1-c

Note: as zones value is an array, you must copy and modify it to make changes to it, there is no way to overwrite just parts of the array!

Set the chosen configuration in your custom values (e.g. custom.yaml).

Note: The number of store-gateway pods that will be started is derived from store_gateway.replicas. Each zone will start store_gateway.replicas / number of zones pods, rounded up to the nearest integer value. For example if you have 3 zones, then store_gateway.replicas=3 will yield 1 store-gateway per zone, but store_gateway.replicas=4 will yield 2 per zone, 6 in total.

Decide which migration path to take for store-gateways

There are two ways to do the migration:

With downtime. In this procedure old non zone-aware store-gateways are stopped, which will cause queries that look back more than 12 hours (or whatever querier.query_store_after Mimir parameter is set to) to fail. Ingestion is not impacted. This is the quicker and simpler way.
Without downtime. This is a multi step procedure which requires additional hardware resources as the old and new store-gateways run in parallel for some time.

Migrate store-gateways with downtime

Before starting this procedure, set up your zones according to Configure zone-aware replication for store-gateways.

Create a new empty YAML file called migrate.yaml.
Scale the current store-gateways to 0.

Copy the following into the migrate.yaml file:
YAML
```
store_gateway:
  replicas: 0
  zoneAwareReplication:
    enabled: false
```
Upgrade the installation with the helm command and make sure to provide the flag -f migrate.yaml as the last flag.
Wait until all store-gateways have terminated.
Set the final configuration.

Merge the following values into your custom Helm values file:
YAML
```
store_gateway:
  zoneAwareReplication:
    enabled: true

rollout_operator:
  enabled: true
```
These values are actually the default, which means that removing the values store_gateway.zoneAwareReplication.enabled and rollout_operator.enabled is also a valid step.
Upgrade the installation with the helm command using your regular command line flags.
Ensure that the Service and StatefulSet resources of the non zone-aware store-gateways have been deleted. The previous step also removes the Service and StatefulSet manifests of the old non zone-aware store-gateways. In some cases, such as when using Helm from Tanka, these resources will not be automatically deleted from your Kubernetes cluster even if the Helm chart no longer renders them. If the old resources still exist, delete them manually. If not deleted, some of the pods may be scraped multiple times when using the Prometheus operator for metamonitoring.
Wait until all store-gateways are running and ready.

Migrate store-gateways without downtime

Before starting this procedure, set up your zones according to Configure zone-aware replication for store-gateways.

Create a new empty YAML file called migrate.yaml.

Create the new zone-aware store-gateways

Copy the following into the migrate.yaml file:

store_gateway:
  zoneAwareReplication:
    enabled: true
    migration:
      enabled: true

rollout_operator:
  enabled: true

Upgrade the installation with the helm command and make sure to provide the flag -f migrate.yaml as the last flag.
Wait for all new store-gateways to start up and be ready.

Make the read path use the new zone-aware store-gateways.

Replace the contents of the migrate.yaml file with:

store_gateway:
  zoneAwareReplication:
    enabled: true
    migration:
      enabled: true
      readPath: true

rollout_operator:
  enabled: true

Upgrade the installation with the helm command and make sure to provide the flag -f migrate.yaml as the last flag.
Wait for all queriers and rulers to restart and become ready.
Set the final configuration.

Merge the following values into your custom Helm values file:
YAML
```
store_gateway:
  zoneAwareReplication:
    enabled: true

rollout_operator:
  enabled: true
```
These values are actually the default, which means that removing the values store_gateway.zoneAwareReplication.enabled and rollout_operator.enabled is also a valid step.
Upgrade the installation with the helm command using your regular command line flags.
Ensure that the Service and StatefulSet resources of the non zone-aware store-gateways have been deleted. The previous step also removes the Service and StatefulSet manifests of the old non zone-aware store-gateways. In some cases, such as when using Helm from Tanka, these resources will not be automatically deleted from your Kubernetes cluster even if the Helm chart no longer renders them. If the old resources still exist, delete them manually. If not deleted, some of the pods may be scraped multiple times when using the Prometheus operator for metamonitoring.
Wait for non zone-aware store-gateways to terminate.

Migrate ingesters to zone-aware replication

Configure zone-aware replication for ingesters

This section is about planning and configuring the availability zones defined under the ingester.zoneAwareReplication Helm value.

There are two use cases in general:

Speeding up rollout of ingesters in case there are more than 3 replicas. In this case use the default value in the small.yaml, large.yaml, capped-small.yaml or capped-large.yaml. The default value defines 3 “virtual” zones and sets affinity rules so that ingesters from different zones do not mix, but it allows multiple ingesters of the same zone on the same node:
YAML
```
ingester:
  zoneAwareReplication:
    enabled: false # Do not turn on zone-awareness without migration because of potential data loss
    topologyKey: "kubernetes.io/hostname" # Triggers creating anti-affinity rules
```

Geographical redundancy. In this case you need to set a suitable nodeSelector value to choose where the pods of each zone are to be placed. Setting topologyKey will instruct the Helm chart to create anti-affinity rules so that ingesters from different zones do not mix, but it allows multiple ingesters of the same zone on the same node. For example:

ingester:
  zoneAwareReplication:
    enabled: false # Do not turn on zone-awareness without migration because of potential data loss
    topologyKey: "kubernetes.io/hostname" # Triggers creating anti-affinity rules
    zones:
      - name: zone-a
        nodeSelector:
          topology.kubernetes.io/zone: us-central1-a
      - name: zone-b
        nodeSelector:
          topology.kubernetes.io/zone: us-central1-b
      - name: zone-c
        nodeSelector:
          topology.kubernetes.io/zone: us-central1-c

Note: as zones value is an array, you must copy and modify it to make changes to it, there is no way to overwrite just parts of the array!

Set the chosen configuration in your custom values (e.g. custom.yaml).

Note: The number of ingester pods that will be started is derived from ingester.replicas. Each zone will start ingester.replicas / number of zones pods, rounded up to the nearest integer value. For example if you have 3 zones, then ingester.replicas=3 will yield 1 ingester per zone, but ingester.replicas=4 will yield 2 per zone, 6 in total.

Decide which migration path to take for ingesters

There are two ways to do the migration:

With downtime. In this procedure ingress is stopped to the cluster while ingesters are migrated. This is the quicker and simpler way. The time it takes to execute this migration depends on how fast ingesters restart and upload their data to object storage, but in general should be finished in an hour.
Without downtime. This is a multi step procedure which requires additional hardware resources as the old and new ingesters run in parallel for some time. This is a complex migration that can take days and requires monitoring for increased resource utilization. The minimum time it takes to do this migration can be calculated as (querier.query_store_after) + (2h TSDB blocks range period + blocks_storage.tsdb.head_compaction_idle_timeout) * (1 + number_of_ingesters / 21). With the default values this means 12h + 3h * (1 + number of ingesters / 21) = 15h + 3h * (number_of_ingesters / 21). Add an extra 12 hours if shuffle sharding is enabled.

Migrate ingesters with downtime

Before starting this procedure, set up your zones according to Configure zone-aware replication for ingesters.

Create a new empty YAML file called migrate.yaml.

Enable flushing data from ingesters to storage on shutdown.

Copy the following into the migrate.yaml file:

mimir:
  structuredConfig:
    blocks_storage:
      tsdb:
        flush_blocks_on_shutdown: true
    ingester:
      ring:
        unregister_on_shutdown: true

ingester:
  zoneAwareReplication:
    enabled: false

Upgrade the installation with the helm command and make sure to provide the flag -f migrate.yaml as the last flag.
Wait for all ingesters to restart and be ready.

Turn off traffic to the installation.

Replace the contents of the migrate.yaml file with:

mimir:
  structuredConfig:
    blocks_storage:
      tsdb:
        flush_blocks_on_shutdown: true
    ingester:
      ring:
        unregister_on_shutdown: true

ingester:
  zoneAwareReplication:
    enabled: false

nginx:
  replicas: 0
gateway:
  replicas: 0

Upgrade the installation with the helm command and make sure to provide the flag -f migrate.yaml as the last flag.
Wait until there is no nginx or gateway running.

Scale the current ingesters to 0.

Replace the contents of the migrate.yaml file with:

mimir:
  structuredConfig:
    blocks_storage:
      tsdb:
        flush_blocks_on_shutdown: true
    ingester:
      ring:
        unregister_on_shutdown: true

ingester:
  replicas: 0
  zoneAwareReplication:
    enabled: false

nginx:
  replicas: 0
gateway:
  replicas: 0

Upgrade the installation with the helm command and make sure to provide the flag -f migrate.yaml as the last flag.
Wait until no ingesters are running.

Start the new zone-aware ingesters.

Replace the contents of the migrate.yaml file with:

ingester:
  zoneAwareReplication:
    enabled: true

nginx:
  replicas: 0
gateway:
  replicas: 0

rollout_operator:
  enabled: true

Upgrade the installation with the helm command and make sure to provide the flag -f migrate.yaml as the last flag.
Wait until all requested ingesters are running and are ready.
Enable traffic to the installation.

Merge the following values into your custom Helm values file:
YAML
```
ingester:
  zoneAwareReplication:
    enabled: true

rollout_operator:
  enabled: true
```
These values are actually the default, which means that removing the values ingester.zoneAwareReplication.enabled and rollout_operator.enabled is also a valid step.
Ensure that the Service and StatefulSet resources of the non zone-aware ingesters have been deleted. The previous step also removes the Service and StatefulSet manifests of the old non zone-aware ingesters. In some cases, such as when using Helm from Tanka, these resources will not be automatically deleted from your Kubernetes cluster even if the Helm chart no longer renders them. If the old resources still exist, delete them manually. If not deleted, some of the pods may be scraped multiple times when using the Prometheus operator for metamonitoring.
Upgrade the installation with the helm command using your regular command line flags.

Migrate ingesters without downtime

Before starting this procedure, set up your zones according to Configure zone-aware replication for ingesters

Double the series limits for tenants and the ingesters.

Explanation: while new ingesters are being added, some series will start to be written to new ingesters, however the series will also exist on old ingesters, thus the series will count twice towards limits. Not updating the limits might lead to writes to be refused due to limits violation.

The limits.max_global_series_per_user Mimir configuration parameter has a non-zero default value of 150000. Double the default or your value by setting:
YAML
```
mimir:
  structuredConfig:
    limits:
      max_global_series_per_user: 300000 # <-- or your value doubled
```
If you have set the Mimir configuration parameter ingester.instance_limits.max_series via mimir.config or mimir.structuredConfig or via runtime overrides, double it for the duration of the migration.

If you have set per tenant limits in the Mimir configuration parameters limits.max_global_series_per_user, limits.max_global_series_per_metric via mimir.config or mimir.structuredConfig or via runtime overrides, double the set limits. For example:
YAML
```
runtimeConfig:
  ingester_limits:
    max_series: X # <-- double it
  overrides:
    tenantA:
      max_global_series_per_metric: Y # <-- double it
      max_global_series_per_user: Z # <-- double it
```
Create a new empty YAML file called migrate.yaml.

Start the migration.

Copy the following into the migrate.yaml file:

ingester:
  zoneAwareReplication:
    enabled: true
    migration:
      enabled: true
      replicas: 0

rollout_operator:
  enabled: true

Upgrade the installation with the helm command and make sure to provide the flag -f migrate.yaml as the last flag.

In this step new zone-aware StatefulSets are created - but no new pods are started yet. The parameter ingester.ring.zone_awareness_enabled: true is set in the Mimir configuration via the mimir.config value. The flag -ingester.ring.zone-awareness-enabled=false is set on distributors, rulers and queriers. The flags -blocks-storage.tsdb.flush-blocks-on-shutdown and -ingester.ring.unregister-on-shutdown are set to true for the ingesters.
Wait for all Mimir components to restart and be ready.
Add zone-aware ingester replicas, maximum 21 at a time.

Explanation: while new ingesters are being added, some series will start to be written to new ingesters, however the series will also exist on old ingesters, thus the series will count twice towards limits. Adding only 21 replicas at a time reduces the number of series affected and thus the likelihood of breaching maximum series limits.
1. Replace the contents of the migrate.yaml file with:
  YAML
```
ingester:
  zoneAwareReplication:
    enabled: true
    migration:
      enabled: true
      replicas: <N>

rollout_operator:
  enabled: true
```
  Note: replace <N> with the number of replicas in each step until <N> reaches the same number as in ingester.replicas, do not increase <N> with more than 21 in each step.
2. Upgrade the installation with the helm command and make sure to provide the flag -f migrate.yaml as the last flag.
3. Once the new ingesters are started and are ready, wait at least 3 hours.
  
  The 3 hours is calculated from 2h TSDB block range period + blocks_storage.tsdb.head_compaction_idle_timeout Grafana Mimir parameters to give enough time for ingesters to remove stale series from memory. Stale series will be there due to series being moved between ingesters.
4. If the current <N> above in ingester.zoneAwareReplication.migration.replicas is less than ingester.replicas, go back and increase <N> with at most 21 and repeat these four steps.
If you are using shuffle sharding, it must be turned off on the read path at this point.
1. Update your configuration with these values and keep them until otherwise instructed.
  YAML
```
querier:
  extraArgs:
    "querier.shuffle-sharding-ingesters-enabled": "false"
ruler:
  extraArgs:
    "querier.shuffle-sharding-ingesters-enabled": "false"
```
2. Upgrade the installation with the helm command and make sure to provide the flag -f migrate.yaml as the last flag.
3. Wait until queriers and rulers have restarted and are ready.
4. Monitor resource utilization of queriers and rulers and scale up if necessary. Turning off shuffle sharding may increase resource utilization.

Enable zone-awareness on the write path.

Replace the contents of the migrate.yaml file with:

ingester:
  zoneAwareReplication:
    enabled: true
    migration:
      enabled: true
      writePath: true

rollout_operator:
  enabled: true

Upgrade the installation with the helm command and make sure to provide the flag -f migrate.yaml as the last flag.

In this step the flag -ingester.ring.zone-awareness-enabled=false is removed from distributors and rulers.
Once all distributors and rulers have restarted and are ready, wait 12 hours.

The 12 hours is calculated from the querier.query_store_after Grafana Mimir parameter.

Enable zone-awareness on the read path.

Replace the contents of the migrate.yaml file with:

ingester:
  zoneAwareReplication:
    enabled: true
    migration:
      enabled: true
      writePath: true
      readPath: true

rollout_operator:
  enabled: true

Upgrade the installation with the helm command and make sure to provide the flag -f migrate.yaml as the last flag.

In this step the flag -ingester.ring.zone-awareness-enabled=false is removed from queriers.
Wait until all queriers have restarted and are ready.

Exclude non zone-aware ingesters from the write path.

Replace the contents of the migrate.yaml file with:

ingester:
  zoneAwareReplication:
    enabled: true
    migration:
      enabled: true
      writePath: true
      readPath: true
      excludeDefaultZone: true

rollout_operator:
  enabled: true

Upgrade the installation with the helm command and make sure to provide the flag -f migrate.yaml as the last flag.

In this step the flag -ingester.ring.excluded-zones=zone-default is added to distributors and rulers.
Wait until all distributors and rulers have restarted and are ready.

Scale down non zone-aware ingesters to 0.

Replace the contents of the migrate.yaml file with:

ingester:
  zoneAwareReplication:
    enabled: true
    migration:
      enabled: true
      writePath: true
      readPath: true
      excludeDefaultZone: true
      scaleDownDefaultZone: true

rollout_operator:
  enabled: true

Upgrade the installation with the helm command and make sure to provide the flag -f migrate.yaml as the last flag.
Wait until all non zone-aware ingesters are terminated.
Delete the default zone.

Merge the following values into your custom Helm values file:
YAML
```
ingester:
  zoneAwareReplication:
    enabled: true

rollout_operator:
  enabled: true
```
These values are actually the default, which means that removing the values ingester.zoneAwareReplication.enabled and rollout_operator.enabled from your custom.yaml is also a valid step.
Upgrade the installation with the helm command using your regular command line flags.
Ensure that the Service and StatefulSet resources of the non zone-aware ingesters have been deleted. The previous step also removes the Service and StatefulSet manifests of the old non zone-aware ingesters. In some cases, such as when using Helm from Tanka, these resources will not be automatically deleted from your Kubernetes cluster even if the Helm chart no longer renders them. If the old resources still exist, delete them manually. If not deleted, some of the pods may be scraped multiple times when using the Prometheus operator for metamonitoring.
Wait at least 3 hours.

The 3 hours is calculated from 2h TSDB block range period + blocks_storage.tsdb.head_compaction_idle_timeout Grafana Mimir parameters to give enough time for ingesters to remove stale series from memory. Stale series will be there due to series being moved between ingesters.
If you are using shuffle sharding:
1. Wait an extra 12 hours.
  
  The 12 hours is calculated from the querier.query_store_after Grafana Mimir parameter. After this time, no series are stored outside their dedicated shard, meaning that shuffle sharding on the read path can be safely enabled.
2. Remove these values from your configuration:
  YAML
```
querier:
  extraArgs:
    "querier.shuffle-sharding-ingesters-enabled": "false"
ruler:
  extraArgs:
    "querier.shuffle-sharding-ingesters-enabled": "false"
```
3. Upgrade the installation with the helm command using your regular command line flags.
4. Wait until queriers and rulers have restarted and are ready.
5. The resource utilization of queriers and rulers should return to pre-migration levels and you can scale them down to previous numbers.
Undo the doubling of series limits done in the first step.
Upgrade the installation with the helm command using your regular command line flags.

Migrate to Kubernetes version 1.25

Mon, 29 Jun 2026 07:50:30 +0000

Migrate to Kubernetes version 1.25

This procedure describes how to prepare a mimir-distributed Helm chart release for an upgrade to Kubernetes 1.25.

Background

Kubernetes version 1.25 removes the support for the deprecated PodSecurityPolicy object. You can learn more about this topic by visiting PodSecurityPolicy Deprecation: Past, Present, and Future.

Due to how Helm works, PodSecurityPolicy objects must already be removed from the release prior to upgrading to Kubernetes version 1.25. If you are using PodSecurityPolicy on Kubernetes 1.24, this is a breaking change. mimir-distributed Helm chart versions before 5.0 used PodSecurityPolicy by default in Kubernetes version 1.24.

Prerequisite

You have Kubernetes version 1.22, 1.23 or 1.24.
This procedure is only applicable if rbac.create is true and rbac.type is psp in your current Helm values. This was the case by default before Helm chart version 5.0.

Procedure

If rbac.create is false or rbac.type is scc, then there is nothing to do, skip the whole procedure.
Optionally follow the Kubernetes Migrate from PodSecurityPolicy to the Built-In PodSecurity Admission Controller guide to replace PodSecurityPolicy.
Set the rbac.create value to false.
Upgrade the deployment. The chart will not install PodSecurityPolicy objects anymore.

Note
Grafana Mimir does not require any special permissions on the hosts that it runs on. Because of this, you can deploy it in environments that enforce the Kubernetes Restricted security policy.

Troubleshoot

If you have upgraded to Kubernetes 1.25 and see the following error containing PodSecurityPolicy during a Helm release upgrade:

resource mapping not found for name: "mimir" namespace: "" from "":
no matches for kind "PodSecurityPolicy" in version "policy/v1beta1" ensure CRDs are installed first

This happens because Helm stores the current release in a Secret in the namespace. If the current release contains removed resources the helm command fails to determine the current state of the release.

To remove the PodSecurityPolicy from the Helm release history follow this procedure:

Optionally follow the Kubernetes Migrate from PodSecurityPolicy to the Built-In PodSecurity Admission Controller guide to replace PodSecurityPolicy.
Set the rbac.create value to false.
Remove PodSecurityPolicy from the Helm release history following the Updating API Versions of a Release Manifest Helm documentation in order to proceed with the upgrade.
Upgrade the release. The upgrade should succeed now.

Migrate the Mimir Helm chart from version 2.x to 3.0

Mon, 29 Jun 2026 07:50:30 +0000

Migrate the Mimir Helm chart from version 2.x to 3.0

There are breaking changes between the Grafana Mimir Helm chart versions 2.x and 3.0. Several parameters that were available in versions 2.x of the mimir-distributed Helm chart have changed.

To migrate from Helm chart 2.x to 3.0:

Understand the improvements that we made to the Mimir configuration in the Helm chart:
- The Mimir configuration is now stored in a Kubernetes ConfigMap by default, instead of a Kubernetes Secret.
- You can override individual properties without copying the entire mimir.config block. Specify properties you want to override under the mimir.structuredConfig.
- You can move secrets outside the Mimir configuration via external secrets and environment variables. Environment variables can be used to externalize secrets from the configuration file.
Decide whether or not you need to update the Mimir configuration:
- If you are using external configuration (useExternalConfig: true), then you must set configStorageType: Secret.
  
  Note: It is now possible to use a ConfigMap to manage your external configuration instead. If your external configuration contains secrets, then you can externalize them and use a ConfigMap. See Externalize secrets.
- If you are not using external configuration (useExternalConfig: false), and your Mimir configuration contains secrets, chose one of two options:
  - Keep the previous location as-is by setting configStorageType: Secret.
  - Externalize secrets:
    1. Move secrets from the Mimir configuration to a Kubernetes Secret.
    2. Mount the Kubernetes Secret via global.extraEnvFrom:
      YAML
      
      global: extraEnvFrom: - secretRef: name: mysecret
      For more information, see Secrets - Use case: As container environment variables.
    3. Replace the values in the Mimir configuration with environment variables.
      
      For example:
      YAML
      
      mimir: structuredConfig: blocks_storage: s3: secret_access_key: ${AWS_SECRET_ACCESS_KEY}
- If you are not using an external configuration (useExternalConfig: false), and your Mimir configuration does not contain secrets, then the storage location is automatically changed by Helm and you do not need to do anything.
See Example migrated values file.
Update your memcached configuration via your customized Helm chart values, if needed:

The mimir-distributed Helm chart supports multiple cache types. If you have not enabled any memcached caches, and you are not overriding the values of memcached, memcached-queries, memcached-metadata, or memcached-results sections, then you do not need to update the memcached configuration.

Otherwise, check to see if you need to change any of the following configuration parameters:
- The memcached section was repurposed, and chunks-cache was added.
- The contents of the memcached section now contain the following common values that are shared across all memcached instances: image, podSecurityContext, and containerSecurityContext.
- The following sections were renamed:
  - memcached-queries is now index-cache
  - memcached-metadata is now metadata-cache
  - memcached-results is now results-cache
- The memcached*.replicaCount values were renamed:
  - memcached.replicaCount is now chunks-cache.replicas
  - memcached-queries.replicaCount is now index-cache.replicas
  - memcached-metadata.replicaCount is now metadata-cache.replicas
  - memcached-results.replicaCount is now results-cache.replicas
- The memcached*.architecture values were removed.
- The memcached*.arguments values were removed.
- The default arguments are now encoded in the Helm chart templates; the values *-cache.allocatedMemory, *-cache.maxItemMemory and *-cache.port control the arguments -m, -I and -u. To provide additional arguments, use *-cache.extraArgs.
- The memcached*.metrics values were consolidated under memcachedExporter.
See also an example of migration of customized memcached values between versions 2.x and 3.0.
Update your memcached-related Mimir configuration via your customized Helm chart value that is named mimir.config, if needed:

The configuration parameters for memcached addresses and max_item_size have changed in the default mimir.config value. If you previously copied the value of mimir.config into your values file, then take the latest version of the memcached configuration in the mimir.config from the values.yaml file in the Helm chart.
(Conditional) If you have enabled serviceMonitor, or you are overriding the value of anything under the serviceMonitor section, or both, then move the serviceMonitor section under metaMonitoring.
Update the rbac section, based on the following changes:
- If you are not overriding the value of anything under the rbac section, then skip this step.
- The rbac.pspEnabled value was removed.
- To continue using Pod Security Policy (PSP), set rbac.create to true and rbac.type to psp.
- To start using Security Context Constraints (SCC) instead of PSP, set rbac.create to true and rbac.type to scc.
Update the mimir.config value, based on the following information:
- Compare your overridden value of mimir.config with the one in the values.yaml file in the chart. If you are not overriding the value of mimir.config, then skip this step.
Decide whether or not to update the nginx configuration:
- Unless you have overridden the value of nginx.nginxConfig.file, and you are using the default mimir.config, then skip this step.
- Otherwise, compare the overridden nginx.nginxConfig.file value to the one in the values.yaml file in the Helm chart, and incorporate the differences. Pay attention to the sections that contain x_scope_orgid. The value in the values.yaml file contains Nginx configuration that adds the X-Scope-OrgId header to incoming requests that do not already set it.
  
  Note: This change allows Mimir clients to keep sending requests without needing to specify a tenant ID, even though multi-tenancy is now enabled by default.

Example of migrated values

The example values file is compatible with any 2.x version of the mimir-distributed Helm chart, and demonstrates a few things:

All memcached caches are enabled.
The default pod security policy is disabled.
ServiceMonitors are enabled.
Object storage credentials for block storage are specified directly in the mimir.config value.
Note
The unmodified parts of the default mimir.config are omitted for brevity, even though in a valid 2.x values file they need to be included.

rbac:
  pspEnabled: false

memcached:
  enabled: true
  replicaCount: 1

memcached-queries:
  enabled: true
  replicaCount: 1

memcached-metadata:
  enabled: true
  replicaCount: 1

memcached-results:
  enabled: true
  replicaCount: 1

serviceMonitor:
  enabled: true

mimir:
  config: |-
    #######
    # default contents omitted for brevity
    #######

    blocks_storage:
      backend: s3
      s3:
        endpoint: s3.amazonaws.com
        bucket_name: my-blocks-bucket
        access_key_id: FAKEACCESSKEY
        secret_access_key: FAKESECRETKEY

    #######
    # default contents omitted for brevity
    #######

After applying the migration steps listed in this guide, you now have a Kubernetes Secret that contains the S3 credentials, and a values file for version 3.0. The values file is does not have any omissions. The parts that were omitted in the 2.x version are automatically included by the Helm chart in version 3.0.

Kubernetes Secret:

apiVersion: v1
kind: Secret
metadata:
  name: mimir-bucket-secret
data:
  AWS_ACCESS_KEY_ID: FAKEACCESSKEY
  AWS_SECRET_ACCESS_KEY: FAKESECRETKEY

Values file:

rbac:
  create: false

chunks-cache:
  enabled: true
  replicas: 1

index-cache:
  enabled: true
  replicas: 1

metadata-cache:
  enabled: true
  replicas: 1

results-cache:
  enabled: true
  replicas: 1

metaMonitoring:
  serviceMonitor:
    enabled: true

mimir:
  structuredConfig:
    blocks_storage:
      backend: s3
      s3:
        access_key_id: ${AWS_ACCESS_KEY_ID}
        bucket_name: my-blocks-bucket
        endpoint: s3.amazonaws.com
        secret_access_key: ${AWS_SECRET_ACCESS_KEY}

global:
  extraEnvFrom:
    - secretRef:
        name: mimir-bucket-secret

Example of migration of customized memcached values between versions 2.x and 3.0

Version 2.1:

memcached:
  replicaCount: 12
  arguments:
    - -m 2048
    - -I 128m
    - -u 12345
  image:
    repository: memcached
    tag: 1.6.9-alpine

memcached-queries:
  replicaCount: 3
  architecture: modern
  image:
    repository: memcached
    tag: 1.6.9-alpine

Version 3.0:

memcached:
  image:
    repository: memcached
    tag: 1.6.9-alpine

chunks-cache:
  allocatedMemory: 2048
  maxItemMemory: 128
  port: 12345
  replicas: 12

index-cache:
  replicas: 3

Configure a unique Grafana Mimir's Memberlist cluster label in the mimir-distributed Helm chart installation

Mon, 29 Jun 2026 07:50:30 +0000

Configure a unique Grafana Mimir’s Memberlist cluster label in the mimir-distributed Helm chart installation

This document shows the steps to configure cluster label verification in a Grafana Mimir installed by Helm. Multiple Memberlist gossip ring clusters are at risk of merging into one without enabling cluster label verification. For example, if a Mimir, Tempo or Loki are running in the same Kubernetes cluster, they might communicate with each other without this configuration update. Once cluster label verification is enabled, before Mimir components communicate with other components, they will verify whether the other components have the same cluster label. The process to update the configuration will take three rollouts of the whole cluster.

Before you begin

You have a Grafana Mimir installed by mimir-distributed helm chart with its Memberlist cluster label still set to default value.
You have kubectl and helm command line configured to connect to the Kubernetes cluster where your Grafana Mimir is running.

Configuration update steps

There are three steps of the configuration update:

Disable Memberlist cluster label verification
Set cluster label on all Mimir components
Enable Memberlist cluster label verification again

1. Disable Memberlist cluster label verification

Cluster label verification flag is enabled by default with cluster label set to an empty string. Using the default value of cluster label can make different systems that use Memberlist communicate with each other if they also have not updated the default cluster label. Setting a new cluster label directly to a non-empty string value without first disabling cluster label verification will cause Memberlist to form partition in the Grafana Mimir cluster. The partition makes some Mimir components have different cluster label values which can prevent the component from communicating. To disable cluster label verification flag, set the following structured config in mimir-distributed values.yaml configuration.

mimir:
  structuredConfig:
    memberlist:
      cluster_label_verification_disabled: true

Rollout the installation to apply the configuration changes by running helm upgrade <my-mimir-release> mimir-distributed -f values.yaml. Replace <my-mimir-release> with the actual Mimir release name. Wait until all Pods are ready before going to the next step.

2. Set cluster label on all Mimir components

Set cluster label on all Mimir components by setting the following configuration. The configuration will set cluster_label to the Helm release name and the namespace where the helm release is installed. Updating a new cluster label after disabling cluster label verification will prevent Memberlist from forming a partition.

mimir:
  structuredConfig:
    memberlist:
      cluster_label_verification_disabled: true
      cluster_label: "{{.Release.Name}}-{{.Release.Namespace}}"

Apply the configuration changes again by running helm upgrade <my-mimir-release> mimir-distributed -f values.yaml. Replace <my-mimir-release> with the actual Mimir release name. Wait until all Pods are ready before going to the next step.

3. Enable Memberlist cluster label verification

Remove mimir.structuredConfig.memberlist.cluster_label_verification_disabled from the values.yaml file to re-enable Memberlist cluster label verification.

mimir:
  structuredConfig:
    memberlist:
      cluster_label: "{{.Release.Name}}-{{.Release.Namespace}}"

Apply the configuration changes by running helm upgrade <my-mimir-release> mimir-distributed -f values.yaml. Replace <my-mimir-release> with the actual Mimir release name. Wait until all Pods are ready before verifying that the configuration is applied correctly.

Verifying the configuration changes

Once the rollout is completed, verify the change by looking at the /memberlist endpoint in some of Grafana Mimir pods. Run the following port-forward command on several different Grafana Mimir components.

   kubectl port-forward pod/<mimir-pod-1> --kube-context=<my-k8s-context> --namespace=<my-mimir-namespace> 8080:8080
   kubectl port-forward pod/<mimir-pod-2> --kube-context=<my-k8s-context> --namespace=<my-mimir-namespace> 8081:8080

Replace <mimir-pod-1> and <mimir-pod-2> with several actual pods from different Mimir components. Ensure the host port 8080 and 8081 are available, otherwise use different available ports.

Open the port-forwarded URL in browser to see the Memberlist status http://localhost:8080/memberlist, http://localhost:8081/memberlist and also few others Grafana Mimir components. The Memberlist page from different pods must show same view of all of their members.

Migrate the Helm chart from version 4.x to 5.0

Mon, 29 Jun 2026 07:50:30 +0000

Migrate the Helm chart from version 4.x to 5.0

The mimir-distributed Helm chart version 5.0 and later does not install PodSecurityPolicy objects on Kubernetes version 1.24 by default to prepare for upgrade to Kubernetes version 1.25.

Prerequisite

This procedure is only applicable if rbac.create is true and rbac.type is psp in your current Helm values. This was the case by default before Helm chart version 5.0.

Procedure

If rbac.create is false or rbac.type is scc, then there is nothing to do, skip the whole procedure.
Choose between the following options:
1. If you are on Kubernetes version 1.22 or later and already have Pod Security Admission set up, you don’t need to do anything and can upgrade to Helm chart version 5.0.
2. If you are on Kubernetes version 1.22 or later but don’t have Pod Security Admission set up and want to upgrade to Kubernetes version 1.25 after this procedure, then follow the Migrate to Kubernetes version 1.25 guide.
3. If you are on Kubernetes version 1.24 and want to keep using PodSecurityPolicy, then merge the following setting into your custom values file:
  YAML
```
rbac:
  forcePSPOnKubernetes124: true
```

Warning
Using rbac.forcePSPOnKubernetes124 equal true value prevents you from upgrading to Kubernetes version 1.25.

Migrate the Helm chart from version 5.x to 6.0

Mon, 29 Jun 2026 07:50:30 +0000

Migrate the Helm chart from version 5.x to 6.0

The mimir-distributed Helm chart version 6.0 introduces several breaking changes:

Ingest storage and Kafka are enabled by default. The bundled Kafka deployment is for demonstration and testing purposes only and is not suitable for production use.
Rollout-operator webhooks are enabled by default, which requires installing CRDs before upgrading.
The top-level nginx values section is removed. You must migrate to the unified gateway deployment before upgrading to version 6.0.

Before you begin

You are running mimir-distributed Helm chart version 5.x.
If you’re using the rollout-operator, you have cluster permissions to install CRDs.
If you’re using the top-level nginx values, you have already migrated to the unified gateway deployment.

Procedure

Migrate to unified gateway deployment (if needed)

If your values file contains a top-level nginx section, you must migrate to the unified gateway deployment before upgrading to version 6.0.

Follow the Migrate to unified proxy deployment guide to complete this migration.

Account for the rollout-operator

If your deployment uses the rollout-operator, you must ensure that the required CustomResourceDefinitions (CRDs) are installed. If you don’t use the rollout-operator, you must explicitly disable it in your values file to avoid unnecessary components and issues with subsequent rollouts.

Install CRDs if using the rollout-operator

If you’re using the rollout-operator, install the CRDs from the rollout-operator chart:

kubectl apply -f https://raw.githubusercontent.com/grafana/helm-charts/main/charts/rollout-operator/crds/replica-templates-custom-resource-definition.yaml
kubectl apply -f https://raw.githubusercontent.com/grafana/helm-charts/main/charts/rollout-operator/crds/zone-aware-pod-disruption-budget-custom-resource-definition.yaml

Disable the rollout-operator if not in use

If you don’t use the rollout-operator, disable it in your values file to prevent the installation of related webhooks which will interfere with subsequent rollouts:

rollout_operator:
  enabled: false

Choose your ingest storage strategy

Choose one of the following options:

Migrate to ingest storage

If you want to migrate your existing installation to use ingest storage, follow the Migrate from classic to ingest storage architecture guide.

Note
The Kafka deployment included in the Helm chart is for demonstration and testing purposes only. For production deployments, set up your own Kafka-compatible backend and configure Mimir to connect to it.

To use your own Kafka cluster:

Set up a production-grade Kafka-compatible backend (such as Apache Kafka, Amazon MSK, or Confluent Cloud).
Disable the bundled Kafka deployment in your values file:
YAML
```
kafka:
  enabled: false
```
Configure Mimir to connect to your Kafka cluster. Refer to the Configure the Kafka backend documentation for configuration details.

Continue using classic architecture (disable ingest storage)

Classic architecture is supported in Mimir version 3.0. If you want to continue using the classic architecture without ingest storage, add the following to your values file:

mimir:
  structuredConfig:
    ingest_storage:
      enabled: false
    ingester:
      push_grpc_method_enabled: true
kafka:
  enabled: false

After adding these values, upgrade to version 6.0.

Upgrade to version 6.0

After completing the prerequisites and choosing your ingest storage strategy, upgrade the Helm release:

helm upgrade <RELEASE_NAME> grafana/mimir-distributed --version 6.0.2 -f <VALUES_FILE>

Troubleshooting

Follow this guidance to recover from common issues with the rollout operator during migration.

Rollout operator misconfiguration

If you don’t install the rollout operator CustomResourceDefinitions (CRDs) and don’t disable the rollout operator, your deployment enters an error state.

If you intend to use the rollout-operator, install the CRDs as described above.

If you intend to disable the rollout-operator, follow these steps:

Disable the rollout-operator in your values file.
YAML
```
rollout-operator:
  enabled: false
```

Delete the rollout-operator validating and mutating webhook configurations.

kubectl delete validatingwebhookconfiguration no-downscale-<NAMESPACE>
kubectl delete validatingwebhookconfiguration pod-eviction-<NAMESPACE>
kubectl delete mutatingwebhookconfigurations prepare-downscale-<NAMESPACE>

Re-apply the updated configuration

helm upgrade <RELEASE_NAME> grafana/mimir-distributed --version 6.0.2 -f <VALUES_FILE> --reset-values