Migrate on Grafana Labs

Migrate to Alloy

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

Migrate to Alloy

Grafana Alloy is the new name for the Grafana Labs distribution of the OpenTelemetry collector. Grafana Agent Static, Grafana Agent Flow, and Grafana Agent Operator reached End-of-Life (EOL) on November 1, 2025. Grafana Labs has provided tools and migration documentation to assist you in migrating to Grafana Alloy.

Read more about why we recommend migrating to Grafana Alloy.

This section provides links to documentation for how to migrate to Alloy.

Migrate from SSD to distributed

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

Migrate from SSD to distributed

This guide provides instructions for migrating from a simple scalable deployment (SSD) to a distributed microservices deployment of Loki. Before starting the migration, make sure you have read the considerations section.

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. You should plan to migrate from SSD to distributed before Loki 4.0 releases.

Note
In this guide, an AWS deployment is used as an example. However, the migration process is mirrored for other cloud providers. This is due to the fact that no changes are required to the underlying data storage.

Considerations

Migrating from a simple scalable deployment to a distributed deployment with zero downtime is possible but requires careful planning. The following considerations should be taken into account:

Helm Deployment: This guide assumes that you have deploying Loki using Helm. Other migration methods are possible but are not covered in this guide.
Kubernetes Resources: This migration method requires you to spin up distributed Loki pods before shutting down the SSD pods. This means that you need to have enough resources in your Kubernetes cluster to run both the SSD and distributed Loki pods at the same time.
Data: No changes are required to your underlying data storage. Although data loss or corruption is unlikely, it is always recommended to back up your data before starting the migration process. If you are using a cloud provider you can take a snapshot/backup.
Configuration: We do not account for all configuration parameters in this guide. We only cover the parameters that need to be changed. Other parameters can remain the same. However, if pattern_ingesters=true you will need to spin up patternIngesters before shutting down the SSD ingesters. This is primarily needed for the Grafana Logs Drilldown feature.
Zone Aware Ingesters: This guide does not currently account for Zone Aware Ingesters. Our current recommendation is to either disable Zone Aware Ingesters or to consult the Mimir migration guide. Take note, not all parameters are equivalent between Mimir and Loki.

Prerequisites

Before starting the migration process, make sure you have the following prerequisites:

Access to your Kubernetes cluster via kubectl.
Helm installed.

Example SSD deployment

This example will use the following SSD deployment as a reference:

Note
This example is only a reference on the parameters that need to be changed. There will be other parameters within your own config such as limits_config, gateway, compactor, etc. These can remain the same.

---
loki:
  schemaConfig:
    configs:
      - from: "2024-04-01"
        store: tsdb
        object_store: s3
        schema: v13
        index:
          prefix: loki_index_
          period: 24h
  storage_config:
    aws:
      region: eu-central-1
      bucketnames: aws-chunks-bucket
      s3forcepathstyle: false
  ingester:
    chunk_encoding: snappy
  ruler:
    enable_api: true
    storage:
      type: s3
      s3:
        region: eu-central-1
        bucketnames: aws-ruler-bucket
        s3forcepathstyle: false
      alertmanager_url: http://prom:9093
  querier:
    max_concurrent: 4

  storage:
    type: s3
    bucketNames:
      chunks: "aws-chunks-bucket"
      ruler: "aws-ruler-bucket"
    s3:
      region: eu-central-1

deploymentMode: SimpleScalable

# SSD
backend:
  replicas: 2
read:
  replicas: 3
write:
  replicas: 3

# Distributed Loki
ingester:
  replicas: 0
  zoneAwareReplication:
    enabled: false

querier:
  replicas: 0
  maxUnavailable: 0
queryFrontend:
  replicas: 0
  maxUnavailable: 0
queryScheduler:
  replicas: 0
distributor:
  replicas: 0
  maxUnavailable: 0
compactor:
  replicas: 0
indexGateway:
  replicas: 0
  maxUnavailable: 0
ruler:
  replicas: 0
  maxUnavailable: 0

# Single binary Loki
singleBinary:
  replicas: 0

minio:
  enabled: false

Stage 1: Deploying the Loki distributed components

In this stage, we will deploy the distributed Loki components alongside the SSD components. We will also change the deploymentMode to SimpleScalable<->Distributed. The SimpleScalable<->Distributed migration mode allows for a zero-downtime transition between Simple Scalable and fully distributed architectures. During migration, both deployment types run simultaneously, sharing the same object storage backend.

The following table outlines which components take over the responsibilities of the SSD components:

Simple Scalable Components	Distributed Components
write (Deployment)	Distributor + Ingester
read (StatefulSet)	Query Frontend + Querier
backend (StatefulSet)	Compactor + Ruler + Index Gateway

How Loki handles request routing during the migration:

The Gateway (nginx) handles request routing based on endpoint type:

Write Path (loki/api/v1/push):
- Initially routes to Simple Scalable write component
- Gradually shifted to the Distributor
- Both write paths share the same object storage, ensuring data consistency
Read Path (/loki/api/v1/query):
- Routes to either Simple Scalable read or distributed Query Frontend
- Query results are consistent since both architectures read from same storage
Admin/Background Operations:
- Compaction, retention, and rule evaluation handled by either backend or respective distributed components
- Operations are coordinated through object storage locks

To start the migration process:

Create a copy of your existing values.yaml file and name it values-migration.yaml.
Bash
```
cp values.yaml values-migration.yaml
```

Next modify the following parameters; deploymentMode, ingester and components based on the annotations below.

---
loki:
  schemaConfig:
    configs:
      - from: "2024-04-01"
        store: tsdb
        object_store: s3
        schema: v13
        index:
          prefix: loki_index_
          period: 24h
  storage_config:
    aws:
      region: eu-central-1
      bucketnames: aws-chunks-bucket
      s3forcepathstyle: false
  ingester:
    chunk_encoding: snappy
    # Add this to ingester; this will force ingesters to flush before shutting down
    wal:
      flush_on_shutdown: true
  ruler:
    enable_api: true
    storage:
      type: s3
      s3:
        region: eu-central-1
        bucketnames: aws-ruler-bucket
        s3forcepathstyle: false
      alertmanager_url: http://prom:9093
  querier:
    max_concurrent: 4

  storage:
    type: s3
    bucketNames:
      chunks: "aws-chunks-bucket"
      ruler: "aws-ruler-bucket"
    s3:
      region: eu-central-1

# Important: Make sure to change this to SimpleScalable<->Distributed
deploymentMode: SimpleScalable<->Distributed

# SSD
backend:
  replicas: 2
read:
  replicas: 3
write:
  replicas: 3

# Distributed Loki
# Spin up the distributed components
ingester:
  replicas: 3
  zoneAwareReplication:
    enabled: false
querier:
  replicas: 3
  maxUnavailable: 0
queryFrontend:
  replicas: 2
  maxUnavailable: 0
queryScheduler:
  replicas: 2
distributor:
  replicas: 2
  maxUnavailable: 0
compactor:
  replicas: 1
indexGateway:
  replicas: 2
  maxUnavailable: 0
ruler:
  replicas: 1
  maxUnavailable: 0

# Single binary Loki
singleBinary:
  replicas: 0

minio:
  enabled: false

Here is a breakdown of the changes:

ingester.wal.flush_on_shutdown: true: This will force the ingesters to flush before shutting down. This is important to prevent data loss.
deploymentMode: SimpleScalable<->Distributed: This will allow for the SSD and distributed components to run simultaneously.
Spin up all distributed components with the desired replicas.

Deploy the distributed components using the following command:
Bash
```
helm upgrade --values values-migration.yaml loki grafana/loki -n loki 
```
Caution
It is important to allow all components to fully spin up before proceeding to the next stage. You can check the status of the components using the following command:
Bash
kubectl get pods -n loki
Let all components reach the Running state before proceeding to the next stage.

Stage 2: Transitioning to distributed components

The final stage of the migration involves transitioning all traffic to the distributed components. This is done by scaling down the SSD components and swapping the deploymentMode to Distributed. To do this:

Create a copy of values-migration.yaml and name it values-distributed.yaml.
Bash
```
cp values-migration.yaml values-distributed.yaml
```

Next modify the following parameters; deploymentMode and components based on the annotations below.

---
loki:
  schemaConfig:
    configs:
      - from: "2024-04-01"
        store: tsdb
        object_store: s3
        schema: v13
        index:
          prefix: loki_index_
          period: 24h
  storage_config:
    aws:
      region: eu-central-1
      bucketnames: aws-chunks-bucket
      s3forcepathstyle: false
  ingester:
    chunk_encoding: snappy
    wal:
      flush_on_shutdown: true
  ruler:
    enable_api: true
    storage:
      type: s3
      s3:
        region: eu-central-1
        bucketnames: aws-ruler-bucket
        s3forcepathstyle: false
      alertmanager_url: http://prom:9093
  querier:
    max_concurrent: 4

  storage:
    type: s3
    bucketNames:
      chunks: "aws-chunks-bucket"
      ruler: "aws-ruler-bucket"
    s3:
      region: eu-central-1

# Important: Make sure to change this to Distributed
deploymentMode: Distributed

# SSD
# Scale down the SSD components
backend:
  replicas: 0
read:
  replicas: 0
write:
  replicas: 0

# Distributed Loki
ingester:
  replicas: 3
  zoneAwareReplication:
    enabled: false
querier:
  replicas: 3
  maxUnavailable: 0
queryFrontend:
  replicas: 2
  maxUnavailable: 0
queryScheduler:
  replicas: 2
distributor:
  replicas: 2
  maxUnavailable: 0
compactor:
  replicas: 1
indexGateway:
  replicas: 2
  maxUnavailable: 0
ruler:
  replicas: 1
  maxUnavailable: 0

# Single binary Loki
singleBinary:
  replicas: 0

minio:
  enabled: false

Here is a breakdown of the changes:

deploymentMode: Distributed: This will allow for the distributed components to run in isolation.
Scale down all SSD components to 0.

Deploy the final configuration using the following command:

helm upgrade --values values-distributed.yaml loki grafana/loki -n loki

Once the deployment is complete, you can verify that all components are running using the following command:
Bash
```
kubectl get pods -n loki
```

You should see all distributed components running and the SSD compontents have now been removed.

What’s next?

Loki in distributed mode is inherently more complex than SSD mode. It is recommended to meta-monitor your Loki deployment to ensure that everything is running smoothly. You can do this by following the meta-monitoring guide.

Migrate to TSDB

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

Migrate to TSDB

TSDB is the recommended index type for Loki and is where the current development lies. If you are running Loki with boltb-shipper or any of the legacy index types that have been deprecated, we strongly recommend migrating to TSDB.

Configure TSDB index for an upcoming period

To begin the migration, add a new period_config entry in your schema_config. You can read more about schema config here.

Note
You must roll out the new period_config change to all Loki components in order for it to take effect.

This example adds a new period_config which configures Loki to start using the TSDB index for the data ingested starting from 2023-10-20.

schema_config:
  configs:
    - from: 2023-01-01
      store: boltdb-shipper
      object_store: filesystem
      schema: v11
      index:
        prefix: index_
        period: 24h
    - from: 2023-10-20 ①
      store: tsdb ②
      object_store: filesystem ③
      schema: v13 ④
      index:
        prefix: index_
        period: 24h

You must set the new period from to a date in the future.
Update the new period to use TSDB as the index type by setting store: tsdb.
This sample configuration uses filesystem as the storage in both the periods. If you want to use a different storage for the TSDB index and chunks, you can specify a different object_store in the new period.
Update the schema to v13 which is the recommended version at the time of writing. Please refer to the configure page for the current recommended version.

Configure TSDB shipper

It’s also important that you configure the tsdb_shipper block in storage_config. Specifically the following options:

active_index_directory: directory where ingesters would write index files which will then be uploaded by shipper to configured storage.
cache_location: cache location for downloading index files from the storage for use in query path.

storage_config:
  tsdb_shipper:
    active_index_directory: /data/tsdb-index
    cache_location: /data/tsdb-cache

Run compactor

We strongly recommended running the compactor when using TSDB index. It is responsible for running compaction and retention on TSDB index. Not running index compaction will result in sub-optimal query performance.

Please refer to the compactor section for more information and configuration examples.

Migrate from `loki-distributed` Helm chart

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

Migrate from `loki-distributed` Helm chart

This guide will walk you through migrating to the loki Helm Chart, v3.0 or higher, from the loki-distributed Helm Chart (v0.63.2 at time of writing). The process consists of deploying the new loki Helm Chart alongside the existing loki-distributed installation. By joining the new cluster to the existing cluster’s ring, you will create one large cluster. This will allow you to manually bring down the loki-distributed components in a safe way to avoid any data loss.

Before you begin:

We recommend having a Grafana instance available to monitor both the existing and new clusters, to make sure there is no data loss during the migration process. The loki chart ships with self-monitoring features, including dashboards. These are useful for monitoring the health of the new cluster as it spins up.

Start by updating your existing Grafana Agent or Promtail config (whatever is scraping logs from your environment) to exclude the new deployment. The new loki chart ships with its own self-monitoring mechanisms, and we want to make sure it’s not scraped twice, which would produce duplicate logs. The best way to do this is via a relabel config that will drop logs from the new deployment, for example something like:

- source_labels:
    - "__meta_kubernetes_pod_label_app_kubernetes_io_component"
  regex: "(canary|read|write)"
  action: "drop"

This leverages the fact that the new deployment adds a app.kubernetes.io/component label of either read for the Read pods, write for the Write pods, and canary for the Loki Canary pods. These annotations are not present in the loki-distributed deployment, so this should only match logs from the new deployment.

To Migrate from loki-distributed to loki

Deploy new Loki Cluster

Next you will deploy the new loki chart in the same namespace as your existing loki-distributed installation. Make sure to use the same buckets and storage configuration as your existing installation. You will need to set some special migrate values as well:
YAML
```
migrate:
  fromDistributed:
    enabled: true
    memberlistService: loki-loki-distributed-memberlist
```
The value of memberlistService must be the kubernetes service created for the purpose of Memberlist DNS in the loki-distributed deployment. It should match the value of memberlist.join_members in the config of the loki-distributed deployment. This is what will make the new cluster join the existing clusters ring. It is important to join all existing rings, if you are using different memberlist DNS for different rings, you must manually set the value of each applicable join_members configuration for each ring. If using the same memberlist DNS for all rings, as is the default in the loki-distributed chart, setting migrate.memberlistService should be enough.

Once the new cluster is up, add the appropriate data source in Grafana for the new cluster. Check that the following queries return results:
- Confirm new and old logs are in the new deployment. Using the new deployment’s Loki data source in Grafana, look for:
  - Logs with a job that is unique to your existing Promtail or Grafana Agent, the one we adjusted above to exclude logs from the new deployment which is not yet pushing logs to the new deployment. If you can query those via the new deployment in shows we have not lost historical logs.
  - Logs with the label job="loki/loki-read". The read component does not exist in loki-distributed, so this show the new Loki cluster’s self monitoring is working correctly.
- Confirm new logs are in the old deployment. Using the old deployment’s Loki data source in Grafana, look for:
  - Logs with the label job="loki/loki-read". Since you have excluded logs from the new deployment from going to the loki-distributed deployment, if you can query them through the loki-distributed Loki data source that show the ingesters have joined the same ring, and are queryable from the loki-distributed queriers.
Convert all Clients to Push Logs to New loki Deployment

Assuming everything is working as expected, you can now modify the clients section of your Grafana Agent or Promtail configuration to push logs to the new deployment. After this change is made, the loki-distributed cluster will no longer recieve new logs and can be carefully scaled down.

Once this has deployed, query the new loki cluster’s Loki data source for new logs to make sure they’re still being ingested.
Tear Down the Old Loki Canary

If you had previously deployed the canary via the loki-canary Helm Chart, you can now tear it down. The new chart ships the canary by default and is automatically configured to scrape it.
Update Flush Config On loki-distributed Deployment

You are almost ready to start scaling down the old loki-distributed cluster. Before you start, however, it is important to make sure the loki-distributed ingesters are configured to flush on shutdown. Since these ingesters will not be coming back, there will be no opportunity for them to replay their WALs, so they need to flush all in-memory logs before shutting down to prevent data loss.

The easiest way to do this is via the extraArgs argument in the ingester section of the loki-distributed chart. You may also want to set the ingester’s log level to debug to see messages about the flushing process.
YAML
```
ingester:
  replicas: 3
  extraArgs:
    - '-ingester.flush-on-shutdown=true'
    - '-log.level=debug'
    ```

Deploy this change, and make sure all ingesters restart and are running the latest configuration.
```
Scale Down Ingesters One at a Time

It is now time to start scaling down loki-distributed. Scale down the ingester StatefulSet or Deployment (depending on how your loki-distributed chart is deployed) 1 replica at a time. If debug logs were enabled, you can monitor the logs of each ingester as it’s terminating to make sure the flushing process was successful. Once the ingester pod is fully terminated, continue decrementing by another 1 replica. Continue until there are 0 instances of the ingester running.

You can use the following command to edit the ingester StatefulSet in order to change the number of replicas (making sure to replace <NAMESPACE> with the correct namespace):
Bash
```
kubectl -n <NAMESPACE> edit statefulsets.apps loki-distributed-ingester
```
Remove loki-distributed cluster

Double check that logs are still coming in to the new cluster. If something is wrong, it will be much easier to quickly scale back up loki-distributed ingesters before tearing down the whole cluster so you can investigate. If everything looks good, you can tear down loki-distributed using helm uninstall. For example:
Bash
```
helm uninstall -n loki loki-distributed
```
Now edit the new loki cluster to remove the migrate options you added when first installing. Remove all of the following from your values.yaml:
YAML
```
migrate:
  fromDistributed:
    enabled: true
    memberlistService: loki-loki-distributed-memberlist
```
To apply the new configuration (assuming you installed the new chart as loki in the loki namespace):
Bash
```
helm upgrade -n loki loki grafana/loki --values values.yaml
```
The migrate.fromDistributed.memberlistService was added as an additional memberlist join member, so once this new config is pushed, the components should roll without interruption.
Check the Dashboards

Now that the migration is finished, you can check the dashboards included with the new loki chart to make sure everything is working as expected. You can also check the loki canary metrics to make sure nothing was lost during the migration. Assuming everything was in the loki namespace, the following query, if run over a time period that starts before the migration, and ends after it was complete, should clearly illustrate when metrics started coming from the new canary, and if and when there was data detected by either during the process:
logql
```
(
  sum(increase(loki_canary_missing_entries_total{namespace="loki"}[$__range])) by (job)
  /
  sum(increase(loki_canary_entries_total{namespace="loki"}[$__range])) by (job)
)*100
```

Migrate to three scalable targets

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

Migrate to three scalable targets

This guide will walk you through migrating from the old, two target, scalable configuration to the new, three target, scalable configuration. This new configuration introduces a backend component, and reduces the read component to running just a Querier and QueryFrontend, allowing it to be run as a kubernetes Deployment rather than a StatefulSet.

Before you begin:

To Migrate from a “read and write” to a “backend, read and write” deployment

Make sure your deployment is using a new enough version of Loki

This feature landed as an option in the helm chart while still in the main branch of Loki. As a result, depending on when you run this migration, you may neeed to manually override the Loki or GEL image being used to one that has the third, backend target available. For Loki, add the following to your values.yaml.

loki:
  image:
    repository: "grafana/loki"
    tag: "main-f5fbfab-amd64"

For GEL, you’ll need to add:

enterprise:
  image:
    repository: "grafana/enterprise-logs"
    tag: "main-96f32b9f"

Set the legacyReadTarget flag to false

Set the value read.legacyReadTarget to false. In your values.yaml, add:

read:
  legacyReadTarget: false

Upgrade the helm installation

Run helm upgrade on your installation with your updated values.yaml file.

Migrate to Thanos storage clients

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

Migrate to Thanos storage clients

Loki release 3.4 introduces new object storage clients based on the Thanos Object Storage Client Go module.

One of the reasons for making this change is to have a consistent storage configuration across Grafana Loki, Mimir and other telemetry databases from Grafana Labs. If you are already using Grafana Mimir or Pyroscope, you can reuse the storage configuration for setting up Loki.

This is an opt-in feature with the Loki 3.4 release. In a future release, Thanos will become the default way of configuring storage and the existing storage clients will be deprecated.

Note
The new storage configuration deviates from the existing format. The following sections describe the changes in detail for each provider. Refer to the Thanos storage configuration reference to view the complete list of supported storage providers and their configuration options.

Enable the new storage clients

Enable Thanos storage clients by setting use_thanos_objstore to true in the storage_config section or by setting the -use-thanos-objstore flag to true. When enabled, configuration under storage_config.object_store takes effect instead of existing storage configurations.
YAML
```
# Uses the new storage clients for connecting to gcs backend
storage_config:
  use_thanos_objstore: true # enable the new storage clients
  object_store:
    gcs:
      bucket_name: "example-bucket"
```

As an alternative, you can also configure the new clients in the common storage section if you prefer to use the common config section.

storage_config:
   use_thanos_objstore: true # enable the new storage clients
common:
  storage:
    object_store:
      gcs:
        bucket_name: "example-bucket"

Ruler storage should be configured under the ruler_storage section when using the new storage clients.

storage_config:
   use_thanos_objstore: true # enable the new storage clients
ruler_storage:
   backend: gcs
   gcs:
      bucket_name: "example-bucket"

If you are using store.object-prefix flag or the corresponding object_prefix YAML setting, you’ll need to update your configuration to use the new object_store.storage-prefix flag or the corresponding storage_prefix YAML setting.
YAML
```
# Example configuration to prefix all objects with "prefix"
storage_config:
   use_thanos_objstore: true # enable the new storage clients
   object_store:
      storage_prefix: "prefix"
```

GCS Storage Migration

When migrating from the existing Google Cloud Storage (GCS) storage client to the new Thanos-based client, you’ll need to update your configuration parameters as follows:

Existing Parameter	New Parameter	Required Changes
`bucket_name`	`bucket_name`	No changes required
`service_account`	`service_account`	No changes required
`chunk_buffer_size`	`chunk_buffer_size`	No changes required
`enable_retries`	`max_retries`	Replace `enable_retries` (bool) with `max_retries` (int). Set a value > 1 to enable retries, or 1 to disable
`request_timeout`	Removed	Remove parameter
`enable_opencensus`	Removed	Remove parameter
`enable_http2`	Removed	Remove parameter

Example configuration migration (GCS):

Existing configuration:

storage_config:
  gcs:
    bucket_name: example-bucket
    chunk_buffer_size: 10MB
    enable_retries: true

New configuration (Thanos-based):

storage_config:
  use_thanos_objstore: true
  object_store:
    gcs:
      bucket_name: example-bucket
      chunk_buffer_size: 10MB
      max_retries: 5

Amazon S3 Storage Migration

When migrating from the existing Amazon S3 storage client to the new Thanos-based client, update or remove parameters as follows:

Existing Parameter	New Parameter	Required Changes
`bucket_names`	`bucket_name`	Rename this parameter. If you previously used multiple buckets, you must consolidate to a single bucket (Thanos supports only one).
`endpoint`	`endpoint`	No changes required.
`region`	`region`	No changes required.
`access_key_id`	`access_key_id`	No changes required.
`secret_access_key`	`secret_access_key`	No changes required.
`session_token`	`session_token`	No changes required.
`insecure`	`insecure`	No changes required.
`disable_dualstack`	`dualstack_enabled`	Renamed and inverted. If you had `disable_dualstack: false`, set `dualstack_enabled: true`.
`storage_class`	`storage_class`	No changes required.
`s3`	Removed	Remove or replace with `endpoint` if you used the URL-based setup.
`S3ForcePathStyle`	Removed or replaced	If you need path-based addressing, set `bucket_lookup_type: path` in the new config. Otherwise, remove it.
`signature_version`	Removed	Remove parameter. Thanos always uses Signature Version 4 (V4).
`http_config`	`http`	Move subfields (such as timeouts, CA file, etc.) into the `http:` block in the Thanos configuration.
`sse`	`sse`	Migrate any SSE settings (e.g., `type`, `kms_key_id`) into the `sse:` block in the Thanos configuration.
`backoff_config`	`max_retries`	Replace the advanced backoff settings with a single integer (`max_retries`). Set to 1 to disable retries, or a higher value to enable them.

Example configuration migration (S3):

Existing configuration

storage_config:
  aws:
    bucket_names: my-bucket1,my-bucket2   # multiple buckets no longer supported
    endpoint: s3.amazonaws.com
    region: us-west-2
    access_key_id: example-key
    secret_access_key: example-secret
    signature_version: v4
    disable_dualstack: true
    storage_class: STANDARD
    http_config:
      timeout: 1m
      insecure_skip_verify: false
    # ...
    backoff_config:
      max_retries: 5
    sse:
      type: SSE-KMS
      kms_key_id: mySSEKey

New configuration (Thanos-based)

storage_config:
  use_thanos_objstore: true
  object_store:
    s3:
      bucket_name: my-bucket1                       # single bucket
      endpoint: s3.amazonaws.com
      region: us-west-2
      access_key_id: example-key
      secret_access_key: example-secret
      dualstack_enabled: false                        # was disable_dualstack: true
      storage_class: STANDARD
      max_retries: 5
      http:
        insecure_skip_verify: false
      sse:
        type: SSE-KMS
        kms_key_id: mySSEKey

For more advanced configuration options (such as list_objects_version, bucket_lookup_type, etc.), see the Thanos S3 configuration reference.

Azure Storage Migration

When migrating from the existing Azure storage client to the new Thanos-based client, no changes are required if you are using the following parameters:

Existing Parameter	New Parameter	Required Changes
`account_name`	`account_name`	No changes required
`account_key`	`account_key`	No changes required
`container_name`	`container_name`	No changes required
`endpoint_suffix`	`endpoint_suffix`	No changes required
`user_assigned_id`	`user_assigned_id`	No changes required
`connection_string`	`connection_string`	No changes required
`max_retries`	`max_retries`	No changes required
`chunk_delimiter`	`chunk_delimiter`	No changes required

If you are using an authentication method other than storage account key or user-assigned managed identity, you’ll have to pass the neccessary credetials using environment variables. For more details, refer to Azure Identity Client Module for Go.

Filesystem Storage Migration

When migrating from the existing Filesystem storage client to the new Thanos-based client, update or remove parameters as follows:

Existing Parameter	New Parameter	Required Changes
`directory`	`dir`	Rename `directory` to `dir`.

Example configuration migration (Filesystem):

Existing configuration (FSConfig)

storage_config:
  filesystem:
    directory: /var/loki/chunks

New configuration (Thanos-based)

storage_config:
  use_thanos_objstore: true
  object_store:
    filesystem:
      dir: /var/loki/chunks

Note
For providers not listed here, refer to the Thanos storage configuration reference.

Migrate on Grafana Labs

Migrate to Alloy

Migrate to Alloy

Migrate from SSD to distributed

Migrate from SSD to distributed

Considerations

Prerequisites

Example SSD deployment

Stage 1: Deploying the Loki distributed components

Stage 2: Transitioning to distributed components

What’s next?

Migrate to TSDB

Migrate to TSDB

Configure TSDB index for an upcoming period

Configure TSDB shipper

Run compactor

Migrate from `loki-distributed` Helm chart

Migrate from loki-distributed Helm chart

Migrate to three scalable targets

Migrate to three scalable targets

Migrate to Thanos storage clients

Migrate to Thanos storage clients

Enable the new storage clients

GCS Storage Migration

Amazon S3 Storage Migration

Azure Storage Migration

Filesystem Storage Migration

Migrate from `loki-distributed` Helm chart