Before jumping into the setup instructions, you can check why integrating with Thanos is important here.

In this guide, all configurations are based on the source code repository accompanying this tutorial. You can find the actual files referenced below:

Prometheus Helm values: scrape-prometheus/helm/kps-scls-tn.yaml

Thanos object storage config file: scrape-prometheus/storage_config/gcs.yaml

Thanos Helm values: thanos/helm/thanos.yaml

1. Config Storage Configuration (GCS)

Create a file named gcs.yaml with the following contents:

Before configuring the Thanos sidecar, you need to prepare a valid storage configuration file. Below is an example for Google Cloud Storage (GCS). This file will be used by all Thanos components to interact with the object store. The service account should have storage admin role.

The contents of gcs.yaml should look like this:

type: GCS
config:
  bucket: "<your-bucket-name>"
  service_account: "<base64-encoded-service-account-json>"

Replace with your actual GCS bucket and with the base64-encoded contents of your service account credentials file.Or you can see that example file in scrape-prometheus/storage_config/gcs.yaml

You can also create an S3 version of objstore.yaml by following the Thanos documentation: https://thanos.io/tip/thanos/storage.md/

2. Install Thanos Sidecar

To enable Thanos integration with Prometheus, update the Helm configuration for the kube-prometheus-stack. In your repository, this configuration is defined in the file scrape-promethues/helm/kps-scls-thanos.yaml, specifically under the prometheus.prometheusSpec.thanos block:

prometheus:
  prometheusSpec:
    thanos:
      objectStorageConfig:
        existingSecret:
          name: thanos-objstore-config
          key: thanos.yaml

This config ensures that the Prometheus server will launch with an attached Thanos sidecar, configured to upload data to your specified object store.

Create the Kubernetes secret that holds your gcs.yaml file using:

kubectl create secret generic thanos-objstore-config \
  --from-file=thanos.yaml=scrape-promethues/storage_config/gcs.yaml -n monitoring

Then upgrade your Prometheus stack using the Helm values file mentioned above:

helm upgrade prometheus-stack prometheus-community/kube-prometheus-stack \
  -n monitoring \
  -f scrape-promethues/helm/kps-scls-tn.yaml

3. Setup Thanos Query, StoreGateway, Compactor

Once the Thanos sidecar is active, proceed to deploy the rest of the Thanos components using the thanos.yaml file in your source code. These components include:

• thanos-query: Aggregates data from all Prometheus and Store components.
• thanos-storegateway: Allows querying historical metrics from object storage.
• thanos-compactor: Downsamples and enforces retention on long-term metrics. Install them using the Bitnami chart:

helm install thanos bitnami/thanos \
  --namespace monitoring \
  -f thanos.yaml

Ensure PVCs are properly configured for storegateway and compactor if persistence is enabled.

4. Change Grafana Data Source to Thanos

In grafana, go to Settings -> Data Sources Change the existed URL of prometheus to thanos query url.

ex: http://thanos-thanos-query.svc.monitoring.cluster.local:10902

Notes: if you want to setup monitor on gce or ec2. It's here.

End of guide.