Merge ~ubuntu-docker-images/ubuntu-docker-images/+git/cortex:1.7-21.04-update into ~ubuntu-docker-images/ubuntu-docker-images/+git/cortex:edge

[Sergio Durigan Junior]

This is the update of the cortex OCI image for hirsute.

Because we keep the whole upstream source in the same git repo, this MP will likely be very polluted with a bunch of upstream changes.

Feel free to focus only on changes inside the oci/ directory.

[Lucas Kanashiro (lucaskanashiro)]

LGTM, +1.

I tested the build, checked the manifest file, ran unit tests, and spotted nothing to be fixed.

review: Approve

[Bryce Harrington (bryce)]

Looks good to me too. I only reviewed the Dockerfile, data/, and README.md changes.

(I see this corrects the mixing of && and ; too, so I guess the thing I worried about wasn't quite so theoretical. These changes look like the proper fixes for that.)

review: Approve

diff --git a/.circleci/config.yml b/.circleci/config.yml
deleted file mode 100644
index ab6cc93..0000000
--- a/.circleci/config.yml
+++ /dev/null
@@ -1,249 +0,0 @@
-version: 2.1
-
-# https://circleci.com/blog/circleci-hacks-reuse-yaml-in-your-circleci-config-with-yaml/
-defaults: &defaults
-  docker:
-    # IMPORTANT: whenever you change the build-image version tag, remember to replace it
-    #            across the entire file (there are multiple references).
-    - image: quay.io/cortexproject/build-image:update-golang-1.14.9-eb0c8d4d2
-  working_directory: /go/src/github.com/cortexproject/cortex
-
-filters: &filters
-  filters:
-    tags:
-      only: /^v[0-9]+(\.[0-9]+){2}(-.+|[^-.]*)$/
-
-workflows:
-  version: 2
-  test-build-deploy:
-    # You must specify a tag filter for each job that deploy depends on.
-    jobs:
-    - lint:
-        <<: *filters
-    - test:
-        <<: *filters
-    - integration:
-        requires:
-        - build
-        <<: *filters
-    - integration-configs-db:
-        requires:
-        - build
-        <<: *filters
-    - build:
-        <<: *filters
-    - deploy_website:
-        requires:
-        - test
-        - build
-        filters:
-          branches:
-            only: master
-    - deploy:
-        requires:
-        - build
-        - test
-        - lint
-        - integration
-        - integration-configs-db
-        filters:
-          branches:
-            only: master
-          tags:
-            only: /^v[0-9]+(\.[0-9]+){2}(-.+|[^-.]*)$/
-
-commands:
-  install-docker:
-    steps:
-    - run:
-        name: Install Docker client
-        command: |
-          set -x
-          VER="17.03.0-ce"
-          curl -L -o /tmp/docker-$VER.tgz https://download.docker.com/linux/static/stable/x86_64/docker-$VER.tgz
-          tar -xz -C /tmp -f /tmp/docker-$VER.tgz
-          mv /tmp/docker/* /usr/bin
-
-jobs:
-  lint:
-    <<: *defaults
-    steps:
-    - checkout
-    - run:
-        name: Lint
-        command: make BUILD_IN_CONTAINER=false lint
-    - run:
-        name: Check vendor directory is consistent.
-        command: make BUILD_IN_CONTAINER=false mod-check
-    - run:
-        name: Check protos are consistent.
-        command: make BUILD_IN_CONTAINER=false check-protos
-    - run:
-        name: Check generated documentation is consistent.
-        command: make BUILD_IN_CONTAINER=false check-doc
-    - run:
-        name: Check white noise.
-        command: make BUILD_IN_CONTAINER=false check-white-noise
-
-  test:
-    docker:
-      - image: quay.io/cortexproject/build-image:update-golang-1.14.9-eb0c8d4d2
-      - image: cassandra:3.11
-        environment:
-          JVM_OPTS: "-Xms1024M -Xmx1024M"
-    working_directory: /go/src/github.com/cortexproject/cortex
-    steps:
-    - checkout
-    - run:
-        name: Test
-        command: CASSANDRA_TEST_ADDRESSES=localhost:9042 make BUILD_IN_CONTAINER=false test
-
-  integration-configs-db:
-    machine:
-      image: ubuntu-1604:201903-01
-
-    working_directory: ~/src/github.com/cortexproject/cortex
-    steps:
-    - checkout
-    - restore_cache:
-        key: v1-cortex-{{ .Branch }}-{{ .Revision }}
-    - run:
-        name: Integration Test
-        command: |
-          touch build-image/.uptodate
-          MIGRATIONS_DIR=$(pwd)/cmd/cortex/migrations make BUILD_IMAGE=quay.io/cortexproject/build-image:update-golang-1.14.9-eb0c8d4d2 configs-integration-test
-
-  integration:
-    machine:
-      image: ubuntu-1604:201903-01
-
-    # Make sure the working directory is within the GOPATH, otherwise
-    # "go test" will not download module dependencies.
-    working_directory: ~/.go_workspace/src/github.com/cortexproject/cortex
-    steps:
-    - run:
-        name: Upgrade golang
-        command: |
-          cd /tmp && \
-          wget https://dl.google.com/go/go1.14.9.linux-amd64.tar.gz && \
-          tar -zxvf go1.14.9.linux-amd64.tar.gz && \
-          sudo rm -fr /usr/local/go && \
-          sudo mv /tmp/go /usr/local/go && \
-          cd -
-    - checkout
-    - restore_cache:
-        key: v1-cortex-{{ .Branch }}-{{ .Revision }}
-    - run:
-        name: Load Images
-        command: ln -s /tmp/images ./docker-images; make BUILD_IN_CONTAINER=false load-images
-    - run:
-        name: Preload Docker Images
-        # We download docker images used by integration tests so that all images are available
-        # locally and the download time doesn't account in the test execution time, which is subject
-        # to a timeout.
-        command: |
-          docker pull minio/minio:RELEASE.2019-12-30T05-45-39Z
-          docker pull amazon/dynamodb-local:1.11.477
-          docker pull consul:0.9
-          docker pull gcr.io/etcd-development/etcd:v3.4.7
-          docker pull quay.io/cortexproject/cortex:v0.6.0
-          docker pull quay.io/cortexproject/cortex:v0.7.0
-          docker pull quay.io/cortexproject/cortex:v1.0.0
-          docker pull quay.io/cortexproject/cortex:v1.1.0
-          docker pull shopify/bigtable-emulator:0.1.0
-          docker pull rinscy/cassandra:3.11.0
-          docker pull memcached:1.6.1
-          docker pull bouncestorage/swift-aio:55ba4331
-    - run:
-        name: Integration Tests
-        command: |
-          export CORTEX_IMAGE_PREFIX="${IMAGE_PREFIX:-quay.io/cortexproject/}"
-          export CORTEX_IMAGE="${CORTEX_IMAGE_PREFIX}cortex:${CIRCLE_TAG:-$(./tools/image-tag)}"
-          export CORTEX_CHECKOUT_DIR="/home/circleci/.go_workspace/src/github.com/cortexproject/cortex"
-          echo "Running integration tests with image: $CORTEX_IMAGE"
-          go test -tags=requires_docker -timeout 1200s -v -count=1 ./integration/...
-        no_output_timeout: 20m
-
-  build:
-    <<: *defaults
-    steps:
-    - checkout
-    - setup_remote_docker
-    - install-docker
-
-    - run:
-        name: Build
-        command: |
-          touch build-image/.uptodate
-          make BUILD_IN_CONTAINER=false
-    - run:
-        name: Build Website
-        command: |
-          touch build-image/.uptodate
-          make BUILD_IN_CONTAINER=false web-build
-
-    - persist_to_workspace:
-        root: .
-        paths:
-          - website/public/
-
-    - store_artifacts:
-        path: pkg/querier/frontend/frontend.pb.go
-    - store_artifacts:
-        path: pkg/chunk/storage/caching_index_client.pb.go
-    - store_artifacts:
-        path: pkg/ring/ring.pb.go
-    - store_artifacts:
-        path: pkg/ingester/client/cortex.pb.go
-    - store_artifacts:
-        path: pkg/ruler/rules/rules.pb.go
-
-    - run:
-        name: Save Images
-        command: |
-          mkdir /tmp/images
-          ln -s /tmp/images ./docker-images
-          make BUILD_IN_CONTAINER=false save-images
-
-    - save_cache:
-        key: v1-cortex-{{ .Branch }}-{{ .Revision }}
-        paths:
-        - /tmp/images/
-
-  deploy_website:
-    <<: *defaults
-    steps:
-    - add_ssh_keys:
-        fingerprints:
-        - "72:f2:e3:39:18:1f:95:17:90:b3:37:5e:49:ed:7e:a3"
-    - checkout
-    - attach_workspace:
-        at: .
-    - run:
-        name: deploy-website
-        command: make BUILD_IN_CONTAINER=false web-deploy
-
-  deploy:
-    <<: *defaults
-    steps:
-    - checkout
-    - setup_remote_docker
-    - install-docker
-
-    - restore_cache:
-        key: v1-cortex-{{ .Branch }}-{{ .Revision }}
-
-    - run:
-        name: Load Images
-        command: ln -s /tmp/images ./docker-images; make BUILD_IN_CONTAINER=false load-images
-
-    - run:
-        name: Deploy
-        command: |
-          if [ -n "$DOCKER_REGISTRY_PASSWORD" ]; then
-            docker login -u "$DOCKER_REGISTRY_USER" -p "$DOCKER_REGISTRY_PASSWORD"
-          fi
-          if [ -n "$QUAY_PASSWORD" ]; then
-            docker login -u "$QUAY_USER" -p "$QUAY_PASSWORD" quay.io;
-          fi
-          IMAGE_TAG=$CIRCLE_TAG ./push-images $NOQUAY
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 0000000..0e1b477
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,30 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Start Cortex (SHA or version)
+2. Perform Operations(Read/Write/Others)
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Environment:**
+ - Infrastructure: [e.g., Kubernetes, bare-metal, laptop]
+ - Deployment tool: [e.g., helm, jsonnet]
+
+**Storage Engine**
+- [ ] Blocks
+- [ ] Chunks
+
+**Additional Context**
+<!--  Additional relevant info which can help us debug this issue easily like Logs, Configuration etc. -->
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 0000000..bbcbbe7
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.
diff --git a/.github/stale.yml b/.github/stale.yml
index fc5f2b2..a6c9689 100644
--- a/.github/stale.yml
+++ b/.github/stale.yml
@@ -1,5 +1,5 @@
 # Days without any activity until an issue is labeled as stale
-daysUntilStale: 60
+daysUntilStale: 90
 
 # Days after having the stale label that the issue will be closed
 daysUntilClose: 15
diff --git a/.github/workflows-doc.md b/.github/workflows-doc.md
new file mode 100644
index 0000000..d38fa97
--- /dev/null
+++ b/.github/workflows-doc.md
@@ -0,0 +1,82 @@
+# GitHub Actions CI/CD
+
+The purpose of this workflow is to run all continuous integration (CI) and continuous deployment (CD) jobs when needed while respecting their internal dependencies. The continuous integration jobs serve to ensure new code passes linting, unit tests and integration tests before reaching the master branch. The continuous deployment jobs serve to deploy the latest version of the code to cortex and the website when merged with master.
+
+## Contributing
+
+If you wish to add a new CI or CD job, add it to the existing current test-build-deploy workflow and make sure it does not prevent any of the other jobs from passing. If you wish to change any of the build or testing images, update it in all sections are containers are often reused. If you wish to add an entirely new workflow, create a new yml file with separate triggers and filters. In all cases, clearly document any changes made to the workflows, images and dependencies below.
+
+## Test, Build and Deploy
+
+test-build-deploy.yml specifies a workflow that runs all Cortex continuous integration and continuous deployment jobs. The workflow is triggered on every pull request and commit to master, however the CD jobs only run when changes are merged onto master . The workflow combines both CI and CD jobs, because the CD jobs are dependent on artifacts produced the CI jobs.
+
+
+## Specific Jobs
+
+| Job                    | Description                                                                                                                   | Type |
+|------------------------|-------------------------------------------------------------------------------------------------------------------------------|------|
+| lint                   | Runs linting and ensures vendor directory, protos and generated documentation are consistent.                                 | CI   |
+| test                   | Runs units tests on Cassandra testing framework.                                                                              | CI   |
+| integration-configs-db | Integration tests for database configurations.                                                                                | CI   |
+| integration            | Runs integration tests after upgrading golang, pulling necessary docker images and downloading necessary module dependencies. | CI   |
+| build                  | Builds and saves an up-to-date Cortex image and website.                                                                      | CI   |
+| deploy_website         | Deploys the latest version of Cortex website to gh-pages branch. Triggered within workflow.                                   | CD   |
+| deploy                 | Deploys the latest Cortex image.                                                                                              | CD   |
+
+## Job Dependency Graph
+
+Internal dependencies between jobs illustrated below. Jobs run concurrently where possible but do not start until all jobs they depend on have completed successfully.
+
+
+![cortex_test-build-deploy](https://user-images.githubusercontent.com/20804975/95492784-9b7feb80-0969-11eb-9934-f44a4b1da498.png)
+
+### Key Details
+
+**Naming Convention**
+
+Each step in a job has a clear name that encapsulates the purpose of the command. The convention we are using is each word in the name should be capitalized except articles and prepositions. This creates consistent labeling when looking at the progress of the current workflow on GitHub.
+
+```yaml
+- name: Checkout Repo
+# commands
+- name: Get Dependencies
+# commands
+```
+
+**Symbolic Link to Expected Workspace**
+
+A significant number of commands in the Makefile are hardcoded with an assumed file structure of the CI container. To ensure paths specified in previous commands don’t break, a symlink was created from the hardcoded “expected” working directory `/go/src/github.com/cortexproject/cortex` to the actual working directory `$GITHUB_WORKSPACE`.
+
+```yaml
+- name: Sym link expected path to github workspace
+  run: |
+    mkdir -p /go/src/github.com/cortexproject/cortex
+    ln -s $GITHUB_WORKSPACE/* /go/src/github.com/cortexproject/cortex
+```
+
+**Sharing Artifacts Between Jobs**
+
+As of October 2020, GitHub Actions do not persist between different jobs in the same workflow. Each job is run on a fresh virtual environment (https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/introduction-to-github-actions#runners). As such, we need to upload and download artifacts to share data between jobs.
+
+| Artifact                      | Stored In | Used By                                     | Purpose of Storing Artifact |
+|-------------------------------|-----------|---------------------------------------------|-----------------------------|
+| website public                | build     | deploy_website                              | share data between jobs     |
+| Docker Images                 | build     | deploy, integration, integrations-config-db | share data between jobs     |
+
+*Note:* Docker Images are zipped before uploading as a workaround. The images contain characters that are illegal in the upload-artifact action.
+```yaml
+- name: Compressing Images
+        run: tar -zcvf images.tar.gz /tmp/images
+      - name: Cache Images
+        uses: actions/upload-artifact@v2
+        with:
+          name: Docker Images
+          path: ./images.tar.gz
+```
+**Tags**
+
+As of Oct 2020, GitHub [does not support](https://github.community/t/using-regex-for-filtering/16427/2) regex for tag filtering. The regex /^v[0-9]+(\.[0-9]+){2}(-.+|[^-.]*)$/ was approximated using the available GitHub [filter patterns](https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet)
+```yaml
+tags:
+  - v[0-9]+.[0-9]+.[0-9]+**
+```
\ No newline at end of file
diff --git a/.github/workflows/scripts/install-docker.sh b/.github/workflows/scripts/install-docker.sh
new file mode 100755
index 0000000..fa1bf70
--- /dev/null
+++ b/.github/workflows/scripts/install-docker.sh
@@ -0,0 +1,7 @@
+#!/bin/bash
+
+set -x
+VER="18.06.3-ce"
+curl -L -o /tmp/docker-$VER.tgz https://download.docker.com/linux/static/stable/x86_64/docker-$VER.tgz
+tar -xz -C /tmp -f /tmp/docker-$VER.tgz
+mv /tmp/docker/* /usr/bin
diff --git a/.github/workflows/test-build-deploy.yml b/.github/workflows/test-build-deploy.yml
new file mode 100644
index 0000000..b9e395a
--- /dev/null
+++ b/.github/workflows/test-build-deploy.yml
@@ -0,0 +1,253 @@
+name: ci
+on:
+  push:
+    branches: [master]
+    tags:
+      - v[0-9]+.[0-9]+.[0-9]+** # Tag filters not as strict due to different regex system on Github Actions
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    container:
+      image: quay.io/cortexproject/build-image:upgrade-build-image-debian-491e60715-WIP
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v2
+        # Commands in the Makefile are hardcoded with an assumed file structure of the CI container
+        # Symlink ensures paths specified in previous commands don’t break
+      - name: Sym Link Expected Path to Workspace
+        run: |
+          mkdir -p /go/src/github.com/cortexproject/cortex
+          ln -s $GITHUB_WORKSPACE/* /go/src/github.com/cortexproject/cortex
+      - name: Lint
+        run: make BUILD_IN_CONTAINER=false lint
+      - name: Check Vendor Directory
+        run: make BUILD_IN_CONTAINER=false mod-check
+      - name: Check Protos
+        run: make BUILD_IN_CONTAINER=false check-protos
+      - name: Check Generated Documentation
+        run: make BUILD_IN_CONTAINER=false check-doc
+      - name: Check White Noise.
+        run: make BUILD_IN_CONTAINER=false check-white-noise
+
+  test:
+    runs-on: ubuntu-latest
+    container:
+      image: quay.io/cortexproject/build-image:upgrade-build-image-debian-491e60715-WIP
+    services:
+      cassandra:
+        image: cassandra:3.11
+        env:
+          JVM_OPTS: "-Xms1024M -Xmx1024M"
+        ports:
+        - 9042:9042
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v2
+      - name: Sym Link Expected Path to Workspace
+        run: |
+          mkdir -p /go/src/github.com/cortexproject/cortex
+          ln -s $GITHUB_WORKSPACE/* /go/src/github.com/cortexproject/cortex
+      - name: Run Tests
+        run: CASSANDRA_TEST_ADDRESSES=cassandra:9042 make BUILD_IN_CONTAINER=false test
+
+  build:
+    runs-on: ubuntu-latest
+    container:
+      image: quay.io/cortexproject/build-image:upgrade-build-image-debian-491e60715-WIP
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v2
+      - name: Install Docker Client
+        run: ./.github/workflows/scripts/install-docker.sh
+      - name: Sym Link Expected Path to Workspace
+        run: |
+          mkdir -p /go/src/github.com/cortexproject/cortex
+          ln -s $GITHUB_WORKSPACE/* /go/src/github.com/cortexproject/cortex
+      - name: Build Image
+        run: |
+          touch build-image/.uptodate
+          make BUILD_IN_CONTAINER=false
+      - name: Build Website
+        run: |
+          touch build-image/.uptodate
+          make BUILD_IN_CONTAINER=false web-build
+      - name: Upload Website Artifact
+        uses: actions/upload-artifact@v2
+        with:
+          name: website public
+          path: website/public/
+      - name: Save Images
+        run: |
+          mkdir /tmp/images
+          ln -s /tmp/images ./docker-images
+          make BUILD_IN_CONTAINER=false save-images
+      - name: Create Docker Images Archive
+        run: tar -cvf images.tar /tmp/images
+      - name: Upload Docker Images Artifact
+        uses: actions/upload-artifact@v2
+        with:
+          name: Docker Images
+          path: ./images.tar
+
+  integration:
+    needs: build
+    runs-on: ubuntu-16.04
+    steps:
+      - name: Upgrade golang
+        run: |
+          cd /tmp
+          wget https://dl.google.com/go/go1.14.9.linux-amd64.tar.gz
+          tar -zxvf go1.14.9.linux-amd64.tar.gz
+          sudo rm -fr /usr/local/go
+          sudo mv /tmp/go /usr/local/go
+          cd -
+      - name: Checkout Repo
+        uses: actions/checkout@v2
+      - name: Install Docker Client
+        run: sudo ./.github/workflows/scripts/install-docker.sh
+      - name: Sym Link Expected Path to Workspace
+        run: |
+          sudo mkdir -p /go/src/github.com/cortexproject/cortex
+          sudo ln -s $GITHUB_WORKSPACE/* /go/src/github.com/cortexproject/cortex
+      - name: Download Docker Images Artifacts
+        uses: actions/download-artifact@v2
+        with:
+          name: Docker Images
+      - name: Extract Docker Images Archive
+        run: tar -xvf images.tar -C /
+      - name: Load Docker Images
+        run: |
+          ln -s /tmp/images ./docker-images
+          make BUILD_IN_CONTAINER=false load-images
+      - name: Preload Images
+        # We download docker images used by integration tests so that all images are available
+        # locally and the download time doesn't account in the test execution time, which is subject
+        # to a timeout
+        run: |
+          docker pull minio/minio:RELEASE.2019-12-30T05-45-39Z
+          docker pull amazon/dynamodb-local:1.11.477
+          docker pull consul:1.8.4
+          docker pull gcr.io/etcd-development/etcd:v3.4.7
+          docker pull quay.io/cortexproject/cortex:v1.0.0
+          docker pull quay.io/cortexproject/cortex:v1.1.0
+          docker pull quay.io/cortexproject/cortex:v1.2.0
+          docker pull quay.io/cortexproject/cortex:v1.3.0
+          docker pull quay.io/cortexproject/cortex:v1.4.0
+          docker pull quay.io/cortexproject/cortex:v1.5.0
+          docker pull quay.io/cortexproject/cortex:v1.6.0
+          docker pull shopify/bigtable-emulator:0.1.0
+          docker pull rinscy/cassandra:3.11.0
+          docker pull memcached:1.6.1
+          docker pull bouncestorage/swift-aio:55ba4331
+      - name: Integration Tests
+        run: |
+          export CORTEX_IMAGE_PREFIX="${IMAGE_PREFIX:-quay.io/cortexproject/}"
+          export IMAGE_TAG=$(make image-tag)
+          export CORTEX_IMAGE="${CORTEX_IMAGE_PREFIX}cortex:$IMAGE_TAG"
+          export CORTEX_CHECKOUT_DIR="/go/src/github.com/cortexproject/cortex"
+          echo "Running integration tests with image: $CORTEX_IMAGE"
+          go test -tags=requires_docker -timeout 2400s -v -count=1 ./integration/...
+        env:
+          IMAGE_PREFIX: ${{ secrets.IMAGE_PREFIX }}
+
+  integration-configs-db:
+    needs: build
+    runs-on: ubuntu-16.04
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v2
+      - name: Install Docker Client
+        run: sudo ./.github/workflows/scripts/install-docker.sh
+      - name: Download Docker Images Artifact
+        uses: actions/download-artifact@v2
+        with:
+          name: Docker Images
+      - name: Extract Docker Images Archive
+        run: tar -xvf images.tar -C /
+      - name: Run Integration Configs Tests
+        # Github Actions does not support TTY in their default runners yet
+        run: |
+          touch build-image/.uptodate
+          MIGRATIONS_DIR=$(pwd)/cmd/cortex/migrations
+          make BUILD_IMAGE=quay.io/cortexproject/build-image:upgrade-build-image-debian-491e60715-WIP TTY='' configs-integration-test
+
+  deploy_website:
+    needs: [build, test]
+    if: (github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/')) && github.repository == 'cortexproject/cortex'
+    runs-on: ubuntu-latest
+    container:
+      image: quay.io/cortexproject/build-image:upgrade-build-image-debian-491e60715-WIP
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v2
+        with:
+          # web-deploy script expects repo to be cloned with ssh for some commands to work
+          ssh-key: ${{ secrets.WEBSITE_DEPLOY_SSH_PRIVATE_KEY }}
+      - name: Sym Link Expected Path to Workspace
+        run: |
+          mkdir -p /go/src/github.com/cortexproject/cortex
+          ln -s $GITHUB_WORKSPACE/* /go/src/github.com/cortexproject/cortex
+      - name: Download Website Artifact
+        uses: actions/download-artifact@v2
+        with:
+          name: website public
+          path: website/public
+      - name: Setup SSH Keys and known_hosts for Github Authentication to Deploy Website
+        run: |
+          mkdir -p ~/.ssh
+          ssh-keyscan github.com >> ~/.ssh/known_hosts
+          ssh-agent -a $SSH_AUTH_SOCK > /dev/null
+          ssh-add - <<< "${{ secrets.WEBSITE_DEPLOY_SSH_PRIVATE_KEY }}"
+        env:
+          SSH_AUTH_SOCK: /tmp/ssh_agent.sock
+        shell: bash
+      - name: Deploy Website
+        # SSH is used to authentricate with Github because web-deploy script uses git to checkout and push to gh-pages
+        run: make BUILD_IN_CONTAINER=false web-deploy
+        env:
+          SSH_AUTH_SOCK: /tmp/ssh_agent.sock
+          GIT_SSH_COMMAND: "ssh -o StrictHostKeyChecking=no"
+
+  deploy:
+    needs: [build, test, lint, integration, integration-configs-db]
+    if: (github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/')) && github.repository == 'cortexproject/cortex'
+    runs-on: ubuntu-latest
+    container:
+      image: quay.io/cortexproject/build-image:upgrade-build-image-debian-491e60715-WIP
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v2
+      - name: Install Docker Client
+        run: ./.github/workflows/scripts/install-docker.sh
+      - name: Sym link Expected Path to Workspace
+        run: |
+          mkdir -p /go/src/github.com/cortexproject/cortex
+          ln -s $GITHUB_WORKSPACE/* /go/src/github.com/cortexproject/cortex
+      - name: Download Docker Images Artifact
+        uses: actions/download-artifact@v2
+        with:
+          name: Docker Images
+      - name: Extract Docker Images Archive
+        run: tar -xvf images.tar -C /
+      - name: Load Images
+        run: |
+          ln -s /tmp/images ./docker-images
+          make BUILD_IN_CONTAINER=false load-images
+      - name: Deploy
+        run: |
+          if [ -n "$DOCKER_REGISTRY_PASSWORD" ]; then
+            docker login -u "$DOCKER_REGISTRY_USER" -p "$DOCKER_REGISTRY_PASSWORD"
+          fi
+          if [ -n "$QUAY_REGISTRY_PASSWORD" ]; then
+            docker login -u "$QUAY_REGISTRY_USER" -p "$QUAY_REGISTRY_PASSWORD" quay.io;
+          fi
+          export IMAGE_TAG=$(make image-tag)
+          ./push-images $NOQUAY
+        env:
+          DOCKER_REGISTRY_USER: ${{secrets.DOCKER_REGISTRY_USER}}
+          DOCKER_REGISTRY_PASSWORD: ${{ secrets.DOCKER_REGISTRY_PASSWORD }}
+          QUAY_REGISTRY_USER: ${{secrets.QUAY_REGISTRY_USER}}
+          QUAY_REGISTRY_PASSWORD: ${{secrets.QUAY_REGISTRY_PASSWORD}}
+          NOQUAY: ${{secrets.NOQUAY}}
diff --git a/.gitignore b/.gitignore
index edbb044..90c3541 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,3 +12,16 @@ website/content/en/docs
 e2e_integration_test*
 active-query-tracker
 dist/
+
+# Binaries built from ./cmd
+/blocksconvert
+/cortex
+/query-tee
+/test-exporter
+
+# This is custom Makefile modification, if it exists.
+Makefile.local
+
+.idea
+compose
+compose-simple
\ No newline at end of file
diff --git a/ADOPTERS.md b/ADOPTERS.md
index 002ca35..6b6c951 100644
--- a/ADOPTERS.md
+++ b/ADOPTERS.md
@@ -2,12 +2,17 @@
 
 This is the list of organisations that are using Cortex in **production environments** to power their metrics and monitoring systems. Please send PRs to add or remove organisations.
 
+* [Amazon Web Services (AWS)](https://aws.amazon.com/prometheus)
 * [Aspen Mesh](https://aspenmesh.io/)
+* [Buoyant](https://buoyant.io/)
 * [DigitalOcean](https://www.digitalocean.com/)
 * [Electronic Arts](https://www.ea.com/)
+* [Etsy](https://www.etsy.com/)
+* [EverQuote](https://everquote.com/)
 * [GoJek](https://www.gojek.io/)
 * [GrafanaLabs](https://grafana.com/)
 * [MayaData](https://mayadata.io/)
+* [Opstrace](https://opstrace.com/)
 * [Platform9](https://platform9.com/)
 * [REWE Digital](https://rewe-digital.com/)
 * [SysEleven](https://www.syseleven.de/)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6b8a1c3..fc8dc25 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,10 +2,282 @@
 
 ## master / unreleased
 
+## 1.7.0
+
+Note the blocks storage compactor runs a migration task at startup in this version, which can take many minutes and use a lot of RAM.
+[Turn this off after first run](https://cortexmetrics.io/docs/blocks-storage/production-tips/#ensure-deletion-marks-migration-is-disabled-after-first-run).
+
+* [CHANGE] FramedSnappy encoding support has been removed from Push and Remote Read APIs. This means Prometheus 1.6 support has been removed and the oldest Prometheus version supported in the remote write is 1.7. #3682
+* [CHANGE] Ruler: removed the flag `-ruler.evaluation-delay-duration-deprecated` which was deprecated in 1.4.0. Please use the `ruler_evaluation_delay_duration` per-tenant limit instead. #3694
+* [CHANGE] Removed the flags `-<prefix>.grpc-use-gzip-compression` which were deprecated in 1.3.0: #3694
+  * `-query-scheduler.grpc-client-config.grpc-use-gzip-compression`: use `-query-scheduler.grpc-client-config.grpc-compression` instead
+  * `-frontend.grpc-client-config.grpc-use-gzip-compression`: use `-frontend.grpc-client-config.grpc-compression` instead
+  * `-ruler.client.grpc-use-gzip-compression`: use `-ruler.client.grpc-compression` instead
+  * `-bigtable.grpc-use-gzip-compression`: use `-bigtable.grpc-compression` instead
+  * `-ingester.client.grpc-use-gzip-compression`: use `-ingester.client.grpc-compression` instead
+  * `-querier.frontend-client.grpc-use-gzip-compression`: use `-querier.frontend-client.grpc-compression` instead
+* [CHANGE] Querier: it's not required to set `-frontend.query-stats-enabled=true` in the querier anymore to enable query statistics logging in the query-frontend. The flag is now required to be configured only in the query-frontend and it will be propagated to the queriers. #3595 #3695
+* [CHANGE] Blocks storage: compactor is now required when running a Cortex cluster with the blocks storage, because it also keeps the bucket index updated. #3583
+* [CHANGE] Blocks storage: block deletion marks are now stored in a per-tenant global markers/ location too, other than within the block location. The compactor, at startup, will copy deletion marks from the block location to the global location. This migration is required only once, so you can safely disable it via `-compactor.block-deletion-marks-migration-enabled=false` once new compactor has successfully started once in your cluster. #3583
+* [CHANGE] OpenStack Swift: the default value for the `-ruler.storage.swift.container-name` and `-swift.container-name` config options has changed from `cortex` to empty string. If you were relying on the default value, you should set it back to `cortex`. #3660
+* [CHANGE] HA Tracker: configured replica label is now verified against label value length limit (`-validation.max-length-label-value`). #3668
+* [CHANGE] Distributor: `extend_writes` field in YAML configuration has moved from `lifecycler` (inside `ingester_config`) to `distributor_config`. This doesn't affect command line option `-distributor.extend-writes`, which stays the same. #3719
+* [CHANGE] Alertmanager: Deprecated `-cluster.` CLI flags in favor of their `-alertmanager.cluster.` equivalent. The deprecated flags (and their respective YAML config options) are: #3677
+  * `-cluster.listen-address` in favor of `-alertmanager.cluster.listen-address`
+  * `-cluster.advertise-address` in favor of `-alertmanager.cluster.advertise-address`
+  * `-cluster.peer` in favor of `-alertmanager.cluster.peers`
+  * `-cluster.peer-timeout` in favor of `-alertmanager.cluster.peer-timeout`
+* [CHANGE] Blocks storage: the default value of `-blocks-storage.bucket-store.sync-interval` has been changed from `5m` to `15m`. #3724
+* [FEATURE] Querier: Queries can be federated across multiple tenants. The tenants IDs involved need to be specified separated by a `|` character in the `X-Scope-OrgID` request header. This is an experimental feature, which can be enabled by setting `-tenant-federation.enabled=true` on all Cortex services. #3250
+* [FEATURE] Alertmanager: introduced the experimental option `-alertmanager.sharding-enabled` to shard tenants across multiple Alertmanager instances. This feature is still under heavy development and its usage is discouraged. The following new metrics are exported by the Alertmanager: #3664
+  * `cortex_alertmanager_ring_check_errors_total`
+  * `cortex_alertmanager_sync_configs_total`
+  * `cortex_alertmanager_sync_configs_failed_total`
+  * `cortex_alertmanager_tenants_discovered`
+  * `cortex_alertmanager_tenants_owned`
+* [ENHANCEMENT] Allow specifying JAEGER_ENDPOINT instead of sampling server or local agent port. #3682
+* [ENHANCEMENT] Blocks storage: introduced a per-tenant bucket index, periodically updated by the compactor, used to avoid full bucket scanning done by queriers, store-gateways and rulers. The bucket index is updated by the compactor during blocks cleanup, on every `-compactor.cleanup-interval`. #3553 #3555 #3561 #3583 #3625 #3711 #3715
+* [ENHANCEMENT] Blocks storage: introduced an option `-blocks-storage.bucket-store.bucket-index.enabled` to enable the usage of the bucket index in the querier, store-gateway and ruler. When enabled, the querier, store-gateway and ruler will use the bucket index to find a tenant's blocks instead of running the periodic bucket scan. The following new metrics are exported by the querier and ruler: #3614 #3625
+  * `cortex_bucket_index_loads_total`
+  * `cortex_bucket_index_load_failures_total`
+  * `cortex_bucket_index_load_duration_seconds`
+  * `cortex_bucket_index_loaded`
+* [ENHANCEMENT] Compactor: exported the following metrics. #3583 #3625
+  * `cortex_bucket_blocks_count`: Total number of blocks per tenant in the bucket. Includes blocks marked for deletion, but not partial blocks.
+  * `cortex_bucket_blocks_marked_for_deletion_count`: Total number of blocks per tenant marked for deletion in the bucket.
+  * `cortex_bucket_blocks_partials_count`: Total number of partial blocks.
+  * `cortex_bucket_index_last_successful_update_timestamp_seconds`: Timestamp of the last successful update of a tenant's bucket index.
+* [ENHANCEMENT] Ruler: Add `cortex_prometheus_last_evaluation_samples` to expose the number of samples generated by a rule group per tenant. #3582
+* [ENHANCEMENT] Memberlist: add status page (/memberlist) with available details about memberlist-based KV store and memberlist cluster. It's also possible to view KV values in Go struct or JSON format, or download for inspection. #3575
+* [ENHANCEMENT] Memberlist: client can now keep a size-bounded buffer with sent and received messages and display them in the admin UI (/memberlist) for troubleshooting. #3581 #3602
+* [ENHANCEMENT] Blocks storage: added block index attributes caching support to metadata cache. The TTL can be configured via `-blocks-storage.bucket-store.metadata-cache.block-index-attributes-ttl`. #3629
+* [ENHANCEMENT] Alertmanager: Add support for Azure blob storage. #3634
+* [ENHANCEMENT] Compactor: tenants marked for deletion will now be fully cleaned up after some delay since deletion of last block. Cleanup includes removal of remaining marker files (including tenant deletion mark file) and files under `debug/metas`. #3613
+* [ENHANCEMENT] Compactor: retry compaction of a single tenant on failure instead of re-running compaction for all tenants. #3627
+* [ENHANCEMENT] Querier: Implement result caching for tenant query federation. #3640
+* [ENHANCEMENT] API: Add a `mode` query parameter for the config endpoint: #3645
+  * `/config?mode=diff`: Shows the YAML configuration with all values that differ from the defaults.
+  * `/config?mode=defaults`: Shows the YAML configuration with all the default values.
+* [ENHANCEMENT] OpenStack Swift: added the following config options to OpenStack Swift backend client: #3660
+  - Chunks storage: `-swift.auth-version`, `-swift.max-retries`, `-swift.connect-timeout`, `-swift.request-timeout`.
+  - Blocks storage: ` -blocks-storage.swift.auth-version`, ` -blocks-storage.swift.max-retries`, ` -blocks-storage.swift.connect-timeout`, ` -blocks-storage.swift.request-timeout`.
+  - Ruler: `-ruler.storage.swift.auth-version`, `-ruler.storage.swift.max-retries`, `-ruler.storage.swift.connect-timeout`, `-ruler.storage.swift.request-timeout`.
+* [ENHANCEMENT] Disabled in-memory shuffle-sharding subring cache in the store-gateway, ruler and compactor. This should reduce the memory utilisation in these services when shuffle-sharding is enabled, without introducing a significantly increase CPU utilisation. #3601
+* [ENHANCEMENT] Shuffle sharding: optimised subring generation used by shuffle sharding. #3601
+* [ENHANCEMENT] New /runtime_config endpoint that returns the defined runtime configuration in YAML format. The returned configuration includes overrides. #3639
+* [ENHANCEMENT] Query-frontend: included the parameter name failed to validate in HTTP 400 message. #3703
+* [ENHANCEMENT] Fail to startup Cortex if provided runtime config is invalid. #3707
+* [ENHANCEMENT] Alertmanager: Add flags to customize the cluster configuration: #3667
+  * `-alertmanager.cluster.gossip-interval`: The interval between sending gossip messages. By lowering this value (more frequent) gossip messages are propagated across cluster more quickly at the expense of increased bandwidth usage.
+  * `-alertmanager.cluster.push-pull-interval`: The interval between gossip state syncs. Setting this interval lower (more frequent) will increase convergence speeds across larger clusters at the expense of increased bandwidth usage.
+* [ENHANCEMENT] Distributor: change the error message returned when a received series has too many label values. The new message format has the series at the end and this plays better with Prometheus logs truncation. #3718
+  - From: `sample for '<series>' has <value> label names; limit <value>`
+  - To: `series has too many labels (actual: <value>, limit: <value>) series: '<series>'`
+* [ENHANCEMENT] Improve bucket index loader to handle edge case where new tenant has not had blocks uploaded to storage yet. #3717
+* [BUGFIX] Allow `-querier.max-query-lookback` use `y|w|d` suffix like deprecated `-store.max-look-back-period`. #3598
+* [BUGFIX] Memberlist: Entry in the ring should now not appear again after using "Forget" feature (unless it's still heartbeating). #3603
+* [BUGFIX] Ingester: do not close idle TSDBs while blocks shipping is in progress. #3630 #3632
+* [BUGFIX] Ingester: correctly update `cortex_ingester_memory_users` and `cortex_ingester_active_series` when a tenant's idle TSDB is closed, when running Cortex with the blocks storage. #3646
+* [BUGFIX] Querier: fix default value incorrectly overriding `-querier.frontend-address` in single-binary mode. #3650
+* [BUGFIX] Compactor: delete `deletion-mark.json` at last when deleting a block in order to not leave partial blocks without deletion mark in the bucket if the compactor is interrupted while deleting a block. #3660
+* [BUGFIX] Blocks storage: do not cleanup a partially uploaded block when `meta.json` upload fails. Despite failure to upload `meta.json`, this file may in some cases still appear in the bucket later. By skipping early cleanup, we avoid having corrupted blocks in the storage. #3660
+* [BUGFIX] Alertmanager: disable access to `/alertmanager/metrics` (which exposes all Cortex metrics), `/alertmanager/-/reload` and `/alertmanager/debug/*`, which were available to any authenticated user with enabled AlertManager. #3678
+* [BUGFIX] Query-Frontend: avoid creating many small sub-queries by discarding cache extents under 5 minutes #3653
+* [BUGFIX] Ruler: Ensure the stale markers generated for evaluated rules respect the configured `-ruler.evaluation-delay-duration`. This will avoid issues with samples with NaN be persisted with timestamps set ahead of the next rule evaluation. #3687
+* [BUGFIX] Alertmanager: don't serve HTTP requests until Alertmanager has fully started. Serving HTTP requests earlier may result in loss of configuration for the user. #3679
+* [BUGFIX] Do not log "failed to load config" if runtime config file is empty. #3706
+* [BUGFIX] Do not allow to use a runtime config file containing multiple YAML documents. #3706
+* [BUGFIX] HA Tracker: don't track as error in the `cortex_kv_request_duration_seconds` metric a CAS operation intentionally aborted. #3745
+
+## 1.6.0
+
+* [CHANGE] Query Frontend: deprecate `-querier.compress-http-responses` in favour of `-api.response-compression-enabled`. #3544
+* [CHANGE] Querier: deprecated `-store.max-look-back-period`. You should use `-querier.max-query-lookback` instead. #3452
+* [CHANGE] Blocks storage: increased `-blocks-storage.bucket-store.chunks-cache.attributes-ttl` default from `24h` to `168h` (1 week). #3528
+* [CHANGE] Blocks storage: the config option `-blocks-storage.bucket-store.index-cache.postings-compression-enabled` has been deprecated and postings compression is always enabled. #3538
+* [CHANGE] Ruler: gRPC message size default limits on the Ruler-client side have changed: #3523
+  - limit for outgoing gRPC messages has changed from 2147483647 to 16777216 bytes
+  - limit for incoming gRPC messages has changed from 4194304 to 104857600 bytes
+* [FEATURE] Distributor/Ingester: Provide ability to not overflow writes in the presence of a leaving or unhealthy ingester. This allows for more efficient ingester rolling restarts. #3305
+* [FEATURE] Query-frontend: introduced query statistics logged in the query-frontend when enabled via `-frontend.query-stats-enabled=true`. When enabled, the metric `cortex_query_seconds_total` is tracked, counting the sum of the wall time spent across all queriers while running queries (on a per-tenant basis). The metrics `cortex_request_duration_seconds` and `cortex_query_seconds_total` are different: the first one tracks the request duration (eg. HTTP request from the client), while the latter tracks the sum of the wall time on all queriers involved executing the query. #3539
+* [ENHANCEMENT] API: Add GZIP HTTP compression to the API responses. Compression can be enabled via `-api.response-compression-enabled`. #3536
+* [ENHANCEMENT] Added zone-awareness support on queries. When zone-awareness is enabled, queries will still succeed if all ingesters in a single zone will fail. #3414
+* [ENHANCEMENT] Blocks storage ingester: exported more TSDB-related metrics. #3412
+  - `cortex_ingester_tsdb_wal_corruptions_total`
+  - `cortex_ingester_tsdb_head_truncations_failed_total`
+  - `cortex_ingester_tsdb_head_truncations_total`
+  - `cortex_ingester_tsdb_head_gc_duration_seconds`
+* [ENHANCEMENT] Enforced keepalive on all gRPC clients used for inter-service communication. #3431
+* [ENHANCEMENT] Added `cortex_alertmanager_config_hash` metric to expose hash of Alertmanager Config loaded per user. #3388
+* [ENHANCEMENT] Query-Frontend / Query-Scheduler: New component called "Query-Scheduler" has been introduced. Query-Scheduler is simply a queue of requests, moved outside of Query-Frontend. This allows Query-Frontend to be scaled separately from number of queues. To make Query-Frontend and Querier use Query-Scheduler, they need to be started with `-frontend.scheduler-address` and `-querier.scheduler-address` options respectively. #3374 #3471
+* [ENHANCEMENT] Query-frontend / Querier / Ruler: added `-querier.max-query-lookback` to limit how long back data (series and metadata) can be queried. This setting can be overridden on a per-tenant basis and is enforced in the query-frontend, querier and ruler. #3452 #3458
+* [ENHANCEMENT] Querier: added `-querier.query-store-for-labels-enabled` to query store for label names, label values and series APIs. Only works with blocks storage engine. #3461 #3520
+* [ENHANCEMENT] Ingester: exposed `-blocks-storage.tsdb.wal-segment-size-bytes` config option to customise the TSDB WAL segment max size. #3476
+* [ENHANCEMENT] Compactor: concurrently run blocks cleaner for multiple tenants. Concurrency can be configured via `-compactor.cleanup-concurrency`. #3483
+* [ENHANCEMENT] Compactor: shuffle tenants before running compaction. #3483
+* [ENHANCEMENT] Compactor: wait for a stable ring at startup, when sharding is enabled. #3484
+* [ENHANCEMENT] Store-gateway: added `-blocks-storage.bucket-store.index-header-lazy-loading-enabled` to enable index-header lazy loading (experimental). When enabled, index-headers will be mmap-ed only once required by a query and will be automatically released after `-blocks-storage.bucket-store.index-header-lazy-loading-idle-timeout` time of inactivity. #3498
+* [ENHANCEMENT] Alertmanager: added metrics `cortex_alertmanager_notification_requests_total` and `cortex_alertmanager_notification_requests_failed_total`. #3518
+* [ENHANCEMENT] Ingester: added `-blocks-storage.tsdb.head-chunks-write-buffer-size-bytes` to fine-tune the TSDB head chunks write buffer size when running Cortex blocks storage. #3518
+* [ENHANCEMENT] /metrics now supports OpenMetrics output. HTTP and gRPC servers metrics can now include exemplars. #3524
+* [ENHANCEMENT] Expose gRPC keepalive policy options by gRPC server. #3524
+* [ENHANCEMENT] Blocks storage: enabled caching of `meta.json` attributes, configurable via `-blocks-storage.bucket-store.metadata-cache.metafile-attributes-ttl`. #3528
+* [ENHANCEMENT] Compactor: added a config validation check to fail fast if the compactor has been configured invalid block range periods (each period is expected to be a multiple of the previous one). #3534
+* [ENHANCEMENT] Blocks storage: concurrently fetch deletion marks from object storage. #3538
+* [ENHANCEMENT] Blocks storage ingester: ingester can now close idle TSDB and delete local data. #3491 #3552
+* [ENHANCEMENT] Blocks storage: add option to use V2 signatures for S3 authentication. #3540
+* [ENHANCEMENT] Exported process metrics to monitor the number of memory map areas allocated. #3537
+  * - `process_memory_map_areas`
+  * - `process_memory_map_areas_limit`
+* [ENHANCEMENT] Ruler: Expose gRPC client options. #3523
+* [ENHANCEMENT] Compactor: added metrics to track on-going compaction. #3535
+  * `cortex_compactor_tenants_discovered`
+  * `cortex_compactor_tenants_skipped`
+  * `cortex_compactor_tenants_processing_succeeded`
+  * `cortex_compactor_tenants_processing_failed`
+* [ENHANCEMENT] Added new experimental API endpoints: `POST /purger/delete_tenant` and `GET /purger/delete_tenant_status` for deleting all tenant data. Only works with blocks storage. Compactor removes blocks that belong to user marked for deletion. #3549 #3558
+* [ENHANCEMENT] Chunks storage: add option to use V2 signatures for S3 authentication. #3560
+* [ENHANCEMENT] HA Tracker: Added new limit `ha_max_clusters` to set the max number of clusters tracked for single user. This limit is disabled by default. #3668
+* [BUGFIX] Query-Frontend: `cortex_query_seconds_total` now return seconds not nanoseconds. #3589
+* [BUGFIX] Blocks storage ingester: fixed some cases leading to a TSDB WAL corruption after a partial write to disk. #3423
+* [BUGFIX] Blocks storage: Fix the race between ingestion and `/flush` call resulting in overlapping blocks. #3422
+* [BUGFIX] Querier: fixed `-querier.max-query-into-future` which wasn't correctly enforced on range queries. #3452
+* [BUGFIX] Fixed float64 precision stability when aggregating metrics before exposing them. This could have lead to false counters resets when querying some metrics exposed by Cortex. #3506
+* [BUGFIX] Querier: the meta.json sync concurrency done when running Cortex with the blocks storage is now controlled by `-blocks-storage.bucket-store.meta-sync-concurrency` instead of the incorrect `-blocks-storage.bucket-store.block-sync-concurrency` (default values are the same). #3531
+* [BUGFIX] Querier: fixed initialization order of querier module when using blocks storage. It now (again) waits until blocks have been synchronized. #3551
+
+## Blocksconvert
+
+* [ENHANCEMENT] Scheduler: ability to ignore users based on regexp, using `-scheduler.ignore-users-regex` flag. #3477
+* [ENHANCEMENT] Builder: Parallelize reading chunks in the final stage of building block. #3470
+* [ENHANCEMENT] Builder: remove duplicate label names from chunk. #3547
+
+## 1.5.0 / 2020-11-09
+
+### Cortex
+
+* [CHANGE] Blocks storage: update the default HTTP configuration values for the S3 client to the upstream Thanos default values. #3244
+  - `-blocks-storage.s3.http.idle-conn-timeout` is set 90 seconds.
+  - `-blocks-storage.s3.http.response-header-timeout` is set to 2 minutes.
+* [CHANGE] Improved shuffle sharding support in the write path. This work introduced some config changes: #3090
+  * Introduced `-distributor.sharding-strategy` CLI flag (and its respective `sharding_strategy` YAML config option) to explicitly specify which sharding strategy should be used in the write path
+  * `-experimental.distributor.user-subring-size` flag renamed to `-distributor.ingestion-tenant-shard-size`
+  * `user_subring_size` limit YAML config option renamed to `ingestion_tenant_shard_size`
+* [CHANGE] Dropped "blank Alertmanager configuration; using fallback" message from Info to Debug level. #3205
+* [CHANGE] Zone-awareness replication for time-series now should be explicitly enabled in the distributor via the `-distributor.zone-awareness-enabled` CLI flag (or its respective YAML config option). Before, zone-aware replication was implicitly enabled if a zone was set on ingesters. #3200
+* [CHANGE] Removed the deprecated CLI flag `-config-yaml`. You should use `-schema-config-file` instead. #3225
+* [CHANGE] Enforced the HTTP method required by some API endpoints which did (incorrectly) allow any method before that. #3228
+  - `GET /`
+  - `GET /config`
+  - `GET /debug/fgprof`
+  - `GET /distributor/all_user_stats`
+  - `GET /distributor/ha_tracker`
+  - `GET /all_user_stats`
+  - `GET /ha-tracker`
+  - `GET /api/v1/user_stats`
+  - `GET /api/v1/chunks`
+  - `GET <legacy-http-prefix>/user_stats`
+  - `GET <legacy-http-prefix>/chunks`
+  - `GET /services`
+  - `GET /multitenant_alertmanager/status`
+  - `GET /status` (alertmanager microservice)
+  - `GET|POST /ingester/ring`
+  - `GET|POST /ring`
+  - `GET|POST /store-gateway/ring`
+  - `GET|POST /compactor/ring`
+  - `GET|POST /ingester/flush`
+  - `GET|POST /ingester/shutdown`
+  - `GET|POST /flush`
+  - `GET|POST /shutdown`
+  - `GET|POST /ruler/ring`
+  - `POST /api/v1/push`
+  - `POST <legacy-http-prefix>/push`
+  - `POST /push`
+  - `POST /ingester/push`
+* [CHANGE] Renamed CLI flags to configure the network interface names from which automatically detect the instance IP. #3295
+  - `-compactor.ring.instance-interface` renamed to `-compactor.ring.instance-interface-names`
+  - `-store-gateway.sharding-ring.instance-interface` renamed to `-store-gateway.sharding-ring.instance-interface-names`
+  - `-distributor.ring.instance-interface` renamed to `-distributor.ring.instance-interface-names`
+  - `-ruler.ring.instance-interface` renamed to `-ruler.ring.instance-interface-names`
+* [CHANGE] Renamed `-<prefix>.redis.enable-tls` CLI flag to `-<prefix>.redis.tls-enabled`, and its respective YAML config option from `enable_tls` to `tls_enabled`. #3298
+* [CHANGE] Increased default `-<prefix>.redis.timeout` from `100ms` to `500ms`. #3301
+* [CHANGE] `cortex_alertmanager_config_invalid` has been removed in favor of `cortex_alertmanager_config_last_reload_successful`. #3289
+* [CHANGE] Query-frontend: POST requests whose body size exceeds 10MiB will be rejected. The max body size can be customised via `-frontend.max-body-size`. #3276
+* [FEATURE] Shuffle sharding: added support for shuffle-sharding queriers in the query-frontend. When configured (`-frontend.max-queriers-per-tenant` globally, or using per-tenant limit `max_queriers_per_tenant`), each tenants's requests will be handled by different set of queriers. #3113 #3257
+* [FEATURE] Shuffle sharding: added support for shuffle-sharding ingesters on the read path. When ingesters shuffle-sharding is enabled and `-querier.shuffle-sharding-ingesters-lookback-period` is set, queriers will fetch in-memory series from the minimum set of required ingesters, selecting only ingesters which may have received series since 'now - lookback period'. #3252
+* [FEATURE] Query-frontend: added `compression` config to support results cache with compression. #3217
+* [FEATURE] Add OpenStack Swift support to blocks storage. #3303
+* [FEATURE] Added support for applying Prometheus relabel configs on series received by the distributor. A `metric_relabel_configs` field has been added to the per-tenant limits configuration. #3329
+* [FEATURE] Support for Cassandra client SSL certificates. #3384
+* [ENHANCEMENT] Ruler: Introduces two new limits `-ruler.max-rules-per-rule-group` and `-ruler.max-rule-groups-per-tenant` to control the number of rules per rule group and the total number of rule groups for a given user. They are disabled by default. #3366
+* [ENHANCEMENT] Allow to specify multiple comma-separated Cortex services to `-target` CLI option (or its respective YAML config option). For example, `-target=all,compactor` can be used to start Cortex single-binary with compactor as well. #3275
+* [ENHANCEMENT] Expose additional HTTP configs for the S3 backend client. New flag are listed below: #3244
+  - `-blocks-storage.s3.http.idle-conn-timeout`
+  - `-blocks-storage.s3.http.response-header-timeout`
+  - `-blocks-storage.s3.http.insecure-skip-verify`
+* [ENHANCEMENT] Added `cortex_query_frontend_connected_clients` metric to show the number of workers currently connected to the frontend. #3207
+* [ENHANCEMENT] Shuffle sharding: improved shuffle sharding in the write path. Shuffle sharding now should be explicitly enabled via `-distributor.sharding-strategy` CLI flag (or its respective YAML config option) and guarantees stability, consistency, shuffling and balanced zone-awareness properties. #3090 #3214
+* [ENHANCEMENT] Ingester: added new metric `cortex_ingester_active_series` to track active series more accurately. Also added options to control whether active series tracking is enabled (`-ingester.active-series-metrics-enabled`, defaults to false), and how often this metric is updated (`-ingester.active-series-metrics-update-period`) and max idle time for series to be considered inactive (`-ingester.active-series-metrics-idle-timeout`). #3153
+* [ENHANCEMENT] Store-gateway: added zone-aware replication support to blocks replication in the store-gateway. #3200
+* [ENHANCEMENT] Store-gateway: exported new metrics. #3231
+  - `cortex_bucket_store_cached_series_fetch_duration_seconds`
+  - `cortex_bucket_store_cached_postings_fetch_duration_seconds`
+  - `cortex_bucket_stores_gate_queries_max`
+* [ENHANCEMENT] Added `-version` flag to Cortex. #3233
+* [ENHANCEMENT] Hash ring: added instance registered timestamp to the ring. #3248
+* [ENHANCEMENT] Reduce tail latency by smoothing out spikes in rate of chunk flush operations. #3191
+* [ENHANCEMENT] User Cortex as User Agent in http requests issued by Configs DB client. #3264
+* [ENHANCEMENT] Experimental Ruler API: Fetch rule groups from object storage in parallel. #3218
+* [ENHANCEMENT] Chunks GCS object storage client uses the `fields` selector to limit the payload size when listing objects in the bucket. #3218 #3292
+* [ENHANCEMENT] Added shuffle sharding support to ruler. Added new metric `cortex_ruler_sync_rules_total`. #3235
+* [ENHANCEMENT] Return an explicit error when the store-gateway is explicitly requested without a blocks storage engine. #3287
+* [ENHANCEMENT] Ruler: only load rules that belong to the ruler. Improves rules synching performances when ruler sharding is enabled. #3269
+* [ENHANCEMENT] Added `-<prefix>.redis.tls-insecure-skip-verify` flag. #3298
+* [ENHANCEMENT] Added `cortex_alertmanager_config_last_reload_successful_seconds` metric to show timestamp of last successful AM config reload. #3289
+* [ENHANCEMENT] Blocks storage: reduced number of bucket listing operations to list block content (applies to newly created blocks only). #3363
+* [ENHANCEMENT] Ruler: Include the tenant ID on the notifier logs. #3372
+* [ENHANCEMENT] Blocks storage Compactor: Added `-compactor.enabled-tenants` and `-compactor.disabled-tenants` to explicitly enable or disable compaction of specific tenants. #3385
+* [ENHANCEMENT] Blocks storage ingester: Creating checkpoint only once even when there are multiple Head compactions in a single `Compact()` call. #3373
+* [BUGFIX] Blocks storage ingester: Read repair memory-mapped chunks file which can end up being empty on abrupt shutdowns combined with faulty disks. #3373
+* [BUGFIX] Blocks storage ingester: Close TSDB resources on failed startup preventing ingester OOMing. #3373
+* [BUGFIX] No-longer-needed ingester operations for queries triggered by queriers and rulers are now canceled. #3178
+* [BUGFIX] Ruler: directories in the configured `rules-path` will be removed on startup and shutdown in order to ensure they don't persist between runs. #3195
+* [BUGFIX] Handle hash-collisions in the query path. #3192
+* [BUGFIX] Check for postgres rows errors. #3197
+* [BUGFIX] Ruler Experimental API: Don't allow rule groups without names or empty rule groups. #3210
+* [BUGFIX] Experimental Alertmanager API: Do not allow empty Alertmanager configurations or bad template filenames to be submitted through the configuration API. #3185
+* [BUGFIX] Reduce failures to update heartbeat when using Consul. #3259
+* [BUGFIX] When using ruler sharding, moving all user rule groups from ruler to a different one and then back could end up with some user groups not being evaluated at all. #3235
+* [BUGFIX] Fixed shuffle sharding consistency when zone-awareness is enabled and the shard size is increased or instances in a new zone are added. #3299
+* [BUGFIX] Use a valid grpc header when logging IP addresses. #3307
+* [BUGFIX] Fixed the metric `cortex_prometheus_rule_group_duration_seconds` in the Ruler, it wouldn't report any values. #3310
+* [BUGFIX] Fixed gRPC connections leaking in rulers when rulers sharding is enabled and APIs called. #3314
+* [BUGFIX] Fixed shuffle sharding consistency when zone-awareness is enabled and the shard size is increased or instances in a new zone are added. #3299
+* [BUGFIX] Fixed Gossip memberlist members joining when addresses are configured using DNS-based service discovery. #3360
+* [BUGFIX] Ingester: fail to start an ingester running the blocks storage, if unable to load any existing TSDB at startup. #3354
+* [BUGFIX] Blocks storage: Avoid deletion of blocks in the ingester which are not shipped to the storage yet. #3346
+* [BUGFIX] Fix common prefixes returned by List method of S3 client. #3358
+* [BUGFIX] Honor configured timeout in Azure and GCS object clients. #3285
+* [BUGFIX] Blocks storage: Avoid creating blocks larger than configured block range period on forced compaction and when TSDB is idle. #3344
+* [BUGFIX] Shuffle sharding: fixed max global series per user/metric limit when shuffle sharding and `-distributor.shard-by-all-labels=true` are both enabled in distributor. When using these global limits you should now set `-distributor.sharding-strategy` and `-distributor.zone-awareness-enabled` to ingesters too. #3369
+* [BUGFIX] Slow query logging: when using downstream server request parameters were not logged. #3276
+* [BUGFIX] Fixed tenant detection in the ruler and alertmanager API when running without auth. #3343
+
+### Blocksconvert
+
+* [ENHANCEMENT] Blocksconvert – Builder: download plan file locally before processing it. #3209
+* [ENHANCEMENT] Blocksconvert – Cleaner: added new tool for deleting chunks data. #3283
+* [ENHANCEMENT] Blocksconvert – Scanner: support for scanning specific date-range only. #3222
+* [ENHANCEMENT] Blocksconvert – Scanner: metrics for tracking progress. #3222
+* [ENHANCEMENT] Blocksconvert – Builder: retry block upload before giving up. #3245
+* [ENHANCEMENT] Blocksconvert – Scanner: upload plans concurrently. #3340
+* [BUGFIX] Blocksconvert: fix chunks ordering in the block. Chunks in different order than series work just fine in TSDB blocks at the moment, but it's not consistent with what Prometheus does and future Prometheus and Cortex optimizations may rely on this ordering. #3371
+
 ## 1.4.0 / 2020-10-02
 
+* [CHANGE] TLS configuration for gRPC, HTTP and etcd clients is now marked as experimental. These features are not yet fully baked, and we expect possible small breaking changes in Cortex 1.5. #3198
 * [CHANGE] Cassandra backend support is now GA (stable). #3180
-* [CHANGE] Blocks storage is now GA (stable). The `-experimental` prefix has been removed from all CLI flags related to the blocks storage (no YAML config changes). #3180
+* [CHANGE] Blocks storage is now GA (stable). The `-experimental` prefix has been removed from all CLI flags related to the blocks storage (no YAML config changes). #3180 #3201
   - `-experimental.blocks-storage.*` flags renamed to `-blocks-storage.*`
   - `-experimental.store-gateway.*` flags renamed to `-store-gateway.*`
   - `-experimental.querier.store-gateway-client.*` flags renamed to `-querier.store-gateway-client.*`
@@ -46,6 +318,7 @@
   * `cortex_bucket_stores_tenants_discovered`
   * `cortex_bucket_stores_tenants_synced`
 * [FEATURE] Experimental blocksconvert: introduce an experimental tool `blocksconvert` to migrate long-term storage chunks to blocks. #3092 #3122 #3127 #3162
+* [ENHANCEMENT] Improve the Alertmanager logging when serving requests from its API / UI. #3397
 * [ENHANCEMENT] Add support for azure storage in China, German and US Government environments. #2988
 * [ENHANCEMENT] Query-tee: added a small tolerance to floating point sample values comparison. #2994
 * [ENHANCEMENT] Query-tee: add support for doing a passthrough of requests to preferred backend for unregistered routes #3018
diff --git a/MAINTAINERS b/MAINTAINERS
index dd22681..af224c7 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1,5 +1,5 @@
 Bryan Boreham, Weaveworks <[e-mail]> (@bboreham)
-Chris Marchbanks, Splunk <[e-mail]> (@csmarchbanks)
+Chris Marchbanks, Grafana Labs <[e-mail]> (@csmarchbanks)
 Goutham Veeramachaneni, Grafana Labs <[e-mail]> (@gouthamve)
 Jacob Lisi, Grafana Labs <[e-mail]> (@jtlisi)
 Ken Haines, Microsoft <[e-mail]> (@khaines)
diff --git a/Makefile b/Makefile
index 36183b2..f872e19 100644
--- a/Makefile
+++ b/Makefile
@@ -1,3 +1,7 @@
+# Local settings (optional). See Makefile.local.example for an example.
+# WARNING: do not commit to a repository!
+-include Makefile.local
+
 .PHONY: all test clean images protos exes dist doc clean-doc check-doc
 .DEFAULT_GOAL := all
 
@@ -8,12 +12,22 @@ GOPROXY_VALUE=$(shell go env GOPROXY)
 # Boiler plate for building Docker containers.
 # All this must go at top of file I'm afraid.
 IMAGE_PREFIX ?= quay.io/cortexproject/
-# Use CIRCLE_TAG if present for releases.
-IMAGE_TAG ?= $(if $(CIRCLE_TAG),$(CIRCLE_TAG),$(shell ./tools/image-tag))
+
+# For a tag push GITHUB_REF will look like refs/tags/<tag_name>,
+# If finding refs/tags/ does not equal emptystring then use
+# the tag we are at as the image tag.
+ifneq (,$(findstring refs/tags/, $(GITHUB_REF)))
+	GIT_TAG := $(shell git tag --points-at HEAD)
+endif
+IMAGE_TAG ?= $(if $(GIT_TAG),$(GIT_TAG),$(shell ./tools/image-tag))
 GIT_REVISION := $(shell git rev-parse --short HEAD)
 GIT_BRANCH := $(shell git rev-parse --abbrev-ref HEAD)
 UPTODATE := .uptodate
 
+.PHONY: image-tag
+image-tag:
+	@echo $(IMAGE_TAG)
+
 # Support gsed on OSX (installed via brew), falling back to sed. On Linux
 # systems gsed won't be installed, so will use sed as expected.
 SED ?= $(shell which gsed 2>/dev/null || which sed)
@@ -60,13 +74,17 @@ $(foreach exe, $(EXES), $(eval $(call dep_exe, $(exe))))
 pkg/ingester/client/cortex.pb.go: pkg/ingester/client/cortex.proto
 pkg/ingester/wal.pb.go: pkg/ingester/wal.proto
 pkg/ring/ring.pb.go: pkg/ring/ring.proto
-pkg/querier/frontend/frontend.pb.go: pkg/querier/frontend/frontend.proto
+pkg/frontend/v1/frontendv1pb/frontend.pb.go: pkg/frontend/v1/frontendv1pb/frontend.proto
+pkg/frontend/v2/frontendv2pb/frontend.pb.go: pkg/frontend/v2/frontendv2pb/frontend.proto
 pkg/querier/queryrange/queryrange.pb.go: pkg/querier/queryrange/queryrange.proto
+pkg/querier/stats/stats.pb.go: pkg/querier/stats/stats.proto
 pkg/chunk/storage/caching_index_client.pb.go: pkg/chunk/storage/caching_index_client.proto
 pkg/distributor/ha_tracker.pb.go: pkg/distributor/ha_tracker.proto
 pkg/ruler/rules/rules.pb.go: pkg/ruler/rules/rules.proto
 pkg/ruler/ruler.pb.go: pkg/ruler/rules/rules.proto
 pkg/ring/kv/memberlist/kv.pb.go: pkg/ring/kv/memberlist/kv.proto
+pkg/scheduler/schedulerpb/scheduler.pb.go: pkg/scheduler/schedulerpb/scheduler.proto
+pkg/storegateway/storegatewaypb/gateway.pb.go: pkg/storegateway/storegatewaypb/gateway.proto
 pkg/chunk/grpc/grpc.pb.go: pkg/chunk/grpc/grpc.proto
 tools/blocksconvert/scheduler.pb.go: tools/blocksconvert/scheduler.proto
 
@@ -81,10 +99,6 @@ build-image/$(UPTODATE): build-image/*
 SUDO := $(shell docker info >/dev/null 2>&1 || echo "sudo -E")
 BUILD_IN_CONTAINER := true
 BUILD_IMAGE ?= $(IMAGE_PREFIX)build-image
-# RM is parameterized to allow CircleCI to run builds, as it
-# currently disallows `docker run --rm`. This value is overridden
-# in circle.yml
-RM := --rm
 # TTY is parameterized to allow Google Cloud Builder to run builds,
 # as it currently disallows TTY devices. This value needs to be overridden
 # in any custom cloudbuild.yaml files
@@ -93,16 +107,16 @@ GO_FLAGS := -ldflags "-X main.Branch=$(GIT_BRANCH) -X main.Revision=$(GIT_REVISI
 
 ifeq ($(BUILD_IN_CONTAINER),true)
 
-GOVOLUMES=	-v $(shell pwd)/.cache:/go/cache:delegated \
-			-v $(shell pwd)/.pkg:/go/pkg:delegated \
-			-v $(shell pwd):/go/src/github.com/cortexproject/cortex:delegated
+GOVOLUMES=	-v $(shell pwd)/.cache:/go/cache:delegated,z \
+			-v $(shell pwd)/.pkg:/go/pkg:delegated,z \
+			-v $(shell pwd):/go/src/github.com/cortexproject/cortex:delegated,z
 
 exes $(EXES) protos $(PROTO_GOS) lint test shell mod-check check-protos web-build web-pre web-deploy doc: build-image/$(UPTODATE)
 	@mkdir -p $(shell pwd)/.pkg
 	@mkdir -p $(shell pwd)/.cache
 	@echo
 	@echo ">>>> Entering build container: $@"
-	@$(SUDO) time docker run $(RM) $(TTY) -i $(GOVOLUMES) $(BUILD_IMAGE) $@;
+	@$(SUDO) time docker run --rm $(TTY) -i $(GOVOLUMES) $(BUILD_IMAGE) $@;
 
 configs-integration-test: build-image/$(UPTODATE)
 	@mkdir -p $(shell pwd)/.pkg
@@ -110,14 +124,14 @@ configs-integration-test: build-image/$(UPTODATE)
 	@DB_CONTAINER="$$(docker run -d -e 'POSTGRES_DB=configs_test' postgres:9.6.16)"; \
 	echo ; \
 	echo ">>>> Entering build container: $@"; \
-	$(SUDO) docker run $(RM) $(TTY) -i $(GOVOLUMES) \
-		-v $(shell pwd)/cmd/cortex/migrations:/migrations \
+	$(SUDO) docker run --rm $(TTY) -i $(GOVOLUMES) \
+		-v $(shell pwd)/cmd/cortex/migrations:/migrations:z \
 		--workdir /go/src/github.com/cortexproject/cortex \
 		--link "$$DB_CONTAINER":configs-db.cortex.local \
 		-e DB_ADDR=configs-db.cortex.local \
 		$(BUILD_IMAGE) $@; \
 	status=$$?; \
-	test -n "$(CIRCLECI)" || docker rm -f "$$DB_CONTAINER"; \
+	docker rm -f "$$DB_CONTAINER"; \
 	exit $$status
 
 else
@@ -141,12 +155,34 @@ lint:
 	golangci-lint run
 
 	# Ensure no blacklisted package is imported.
-	faillint -paths "github.com/bmizerany/assert=github.com/stretchr/testify/assert,\
+	GOFLAGS="-tags=requires_docker" faillint -paths "github.com/bmizerany/assert=github.com/stretchr/testify/assert,\
 		golang.org/x/net/context=context,\
-		sync/atomic=go.uber.org/atomic" ./pkg/... ./cmd/... ./tools/... ./integration/...
+		sync/atomic=go.uber.org/atomic,\
+		github.com/prometheus/client_golang/prometheus.{MultiError}=github.com/prometheus/prometheus/tsdb/errors.{NewMulti},\
+		github.com/weaveworks/common/user.{ExtractOrgID}=github.com/cortexproject/cortex/pkg/tenant.{TenantID,TenantIDs},\
+		github.com/weaveworks/common/user.{ExtractOrgIDFromHTTPRequest}=github.com/cortexproject/cortex/pkg/tenant.{ExtractTenantIDFromHTTPRequest}" ./pkg/... ./cmd/... ./tools/... ./integration/...
+
+	# Ensure clean pkg structure.
+	faillint -paths "\
+		github.com/cortexproject/cortex/pkg/scheduler,\
+		github.com/cortexproject/cortex/pkg/frontend,\
+		github.com/cortexproject/cortex/pkg/frontend/transport,\
+		github.com/cortexproject/cortex/pkg/frontend/v1,\
+		github.com/cortexproject/cortex/pkg/frontend/v2" \
+		./pkg/querier/...
+	faillint -paths "github.com/cortexproject/cortex/pkg/querier/..." ./pkg/scheduler/...
+	faillint -paths "github.com/cortexproject/cortex/pkg/storage/tsdb/..." ./pkg/storage/bucket/...
+
+	# Ensure the query path is supporting multiple tenants
+	faillint -paths "\
+		github.com/cortexproject/cortex/pkg/tenant.{TenantID}=github.com/cortexproject/cortex/pkg/tenant.{TenantIDs}" \
+		./pkg/scheduler/... \
+		./pkg/frontend/... \
+		./pkg/querier/tenantfederation/... \
+		./pkg/querier/queryrange/...
 
 	# Validate Kubernetes spec files. Requires:
-	# https://kubeval.instrumenta.dev
+	# https://kubeval.instrumenta.dev
 	kubeval ./k8s/*
 
 test:
@@ -230,7 +266,7 @@ check-white-noise: clean-white-noise
 	@git diff --exit-code --quiet -- '*.md' || (echo "Please remove trailing whitespaces running 'make clean-white-noise'" && false)
 
 web-serve:
-	cd website && hugo --config config.toml -v server
+	cd website && hugo --config config.toml --minify -v server
 
 # Generate binaries for a Cortex release
 dist dist/cortex-linux-amd64 dist/cortex-darwin-amd64 dist/query-tee-linux-amd64 dist/query-tee-darwin-amd64 dist/cortex-linux-amd64-sha-256 dist/cortex-darwin-amd64-sha-256 dist/query-tee-linux-amd64-sha-256 dist/query-tee-darwin-amd64-sha-256:
@@ -263,8 +299,8 @@ packages: dist/cortex-linux-amd64 packaging/fpm/$(UPTODATE)
 	@mkdir -p $(shell pwd)/.pkg
 	@mkdir -p $(shell pwd)/.cache
 	@echo ">>>> Entering build container: $@"
-	@$(SUDO) time docker run $(RM) $(TTY) \
-		-v  $(shell pwd):/src/github.com/cortexproject/cortex:delegated \
+	@$(SUDO) time docker run --rm $(TTY) \
+		-v  $(shell pwd):/src/github.com/cortexproject/cortex:delegated,z \
 		-i $(PACKAGE_IMAGE) $@;
 
 else
diff --git a/Makefile.local.example b/Makefile.local.example
new file mode 100644
index 0000000..7faa0bb
--- /dev/null
+++ b/Makefile.local.example
@@ -0,0 +1,10 @@
+# Example of extending Makefile with Makefile.local.
+
+BUILD_IMAGE ?= quay.io/cortexproject/build-image
+IMAGE_PREFIX ?= custom-prefix/
+
+blocksconvert-push: cmd/blocksconvert/.uptodate
+	docker push $(IMAGE_PREFIX)blocksconvert:$(IMAGE_TAG)
+
+cortex-push: cmd/cortex/.uptodate
+	docker push $(IMAGE_PREFIX)cortex:$(IMAGE_TAG)
diff --git a/README.md b/README.md
index 8c2a360..e6f1db1 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,9 @@
 <p align="center"><img src="images/logo.png" alt="Cortex Logo"></p>
 
-[![Circle CI](https://circleci.com/gh/cortexproject/cortex/tree/master.svg?style=shield)](https://circleci.com/gh/cortexproject/cortex/tree/master)
+[![CI](https://github.com/cortexproject/cortex/workflows/ci/badge.svg)](https://github.com/cortexproject/cortex/actions)
 [![GoDoc](https://godoc.org/github.com/cortexproject/cortex?status.svg)](https://godoc.org/github.com/cortexproject/cortex)
 <a href="https://goreportcard.com/report/github.com/cortexproject/cortex"><img src="https://goreportcard.com/badge/github.com/cortexproject/cortex" alt="Go Report Card" /></a>
 <a href="https://cloud-native.slack.com/messages/cortex/"><img src="https://img.shields.io/badge/join%20slack-%23cortex-brightgreen.svg" alt="Slack" /></a>
-[![TODOs](https://badgen.net/https/api.tickgit.com/badgen/github.com/cortexproject/cortex)](https://www.tickgit.com/browse?repo=github.com/cortexproject/cortex)
 
 # Cortex: horizontally scalable, highly available, multi-tenant, long term storage for Prometheus.
 
@@ -26,17 +25,34 @@ Read the [getting started guide](https://cortexmetrics.io/docs/getting-started) 
 project. Before deploying Cortex with a permanent storage backend you
 should read:
 1. [An overview of Cortex's architecture](https://cortexmetrics.io/docs/architecture/)
-1. [A guide to running Cortex](https://cortexmetrics.io/docs/production/)
+1. [A guide to running Cortex](https://cortexmetrics.io/docs/guides/running-chunks-storage-in-production/)
 1. [Information regarding configuring Cortex](https://cortexmetrics.io/docs/configuration/arguments/)
-1. [Steps to run Cortex with Cassandra](https://cortexmetrics.io/docs/production/cassandra)
+1. [Steps to run Cortex with Cassandra](https://cortexmetrics.io/docs/guides/running-chunks-storage-with-cassandra/)
 
 For a guide to contributing to Cortex, see the [contributor guidelines](https://cortexmetrics.io/docs/contributing/).
 
 ## Further reading
 
-To learn more about Cortex, consult the following documents & talks:
+To learn more about Cortex, consult the following talks and articles.
+
+### Recent talks and articles
+
+- Dec 2020 blog post "[How AWS and Grafana Labs are scaling Cortex for the cloud](https://aws.amazon.com/blogs/opensource/how-aws-and-grafana-labs-are-scaling-cortex-for-the-cloud/)
+- Oct 2020 blog post "[How to switch Cortex from chunks to blocks storage (and why you won’t look back)](https://grafana.com/blog/2020/10/19/how-to-switch-cortex-from-chunks-to-blocks-storage-and-why-you-wont-look-back/)"
+- Oct 2020 blog post "[Now GA: Cortex blocks storage for running Prometheus at scale with reduced operational complexity](https://grafana.com/blog/2020/10/06/now-ga-cortex-blocks-storage-for-running-prometheus-at-scale-with-reduced-operational-complexity/)"
+- Sep 2020 blog post "[A Tale of Tail Latencies](https://www.weave.works/blog/a-tale-of-tail-latencies)"
+- Sep 2020 KubeCon talk "Scaling Prometheus: How We Got Some Thanos Into Cortex" ([video](https://www.youtube.com/watch?v=Z5OJzRogAS4), [slides](https://static.sched.com/hosted_files/kccnceu20/ec/2020-08%20-%20KubeCon%20EU%20-%20Cortex%20blocks%20storage.pdf))
+- Aug 2020 blog post "[Scaling Prometheus: How we’re pushing Cortex blocks storage to its limit and beyond](https://grafana.com/blog/2020/08/12/scaling-prometheus-how-were-pushing-cortex-blocks-storage-to-its-limit-and-beyond/)"
+- Jul 2020 blog post "[How blocks storage in Cortex reduces operational complexity for running Prometheus at massive scale](https://grafana.com/blog/2020/07/29/how-blocks-storage-in-cortex-reduces-operational-complexity-for-running-prometheus-at-massive-scale/)"
+- Jul 2020 PromCon talk "Sharing is Caring: Leveraging Open Source to Improve Cortex & Thanos" ([video](https://www.youtube.com/watch?v=2oTLouUvsac), [slides](https://docs.google.com/presentation/d/1OuKYD7-k9Grb7unppYycdmVGWN0Bo0UwdJRySOoPdpg/edit))
+- Mar 2020 blog post "[Cortex: Zone Aware Replication](https://kenhaines.net/cortex-zone-aware-replication/)"
+- Mar 2020 blog post "[How we're using gossip to improve Cortex and Loki availability](https://grafana.com/blog/2020/03/25/how-were-using-gossip-to-improve-cortex-and-loki-availability/)"
+- Jan 2020 blog post "[The Future of Cortex: Into the Next Decade][future-of-cortex-blog]"
+
+[future-of-cortex-blog]: https://grafana.com/blog/2020/01/21/the-future-of-cortex-into-the-next-decade/
+
+### Previous talks and articles
 
-- Jan 2020 Blog Post "[The Future of Cortex: Into the Next Decade][future-of-cortex-blog]"
 - Nov 2019 KubeCon talks "[Cortex 101: Horizontally Scalable Long Term Storage for Prometheus][kubecon-cortex-101]" ([video][kubecon-cortex-101-video], [slides][kubecon-cortex-101-slides]), "[Configuring Cortex for Max
 Performance][kubecon-cortex-201]" ([video][kubecon-cortex-201-video], [slides][kubecon-cortex-201-slides], [write up][kubecon-cortex-201-writeup]) and "[Blazin’ Fast PromQL][kubecon-blazin]" ([slides][kubecon-blazin-slides], [video][kubecon-blazin-video], [write up][kubecon-blazin-writeup])
 - Nov 2019 PromCon talk "[Two Households, Both Alike in Dignity: Cortex and Thanos][promcon-two-households]" ([video][promcon-two-households-video], [slides][promcon-two-households-slides], [write up][promcon-two-households-writeup])
@@ -56,7 +72,6 @@ Performance][kubecon-cortex-201]" ([video][kubecon-cortex-201-video], [slides][k
 - Aug 2016 PromCon talk; "Project Frankenstein: Multitenant, Scale-Out Prometheus": ([video][promcon-2016-video], [slides][promcon-2016-slides])
 - Jun 2016 design document; "[Project Frankenstein: A Multi Tenant, Scale Out Prometheus](http://goo.gl/prdUYV)"
 
-[future-of-cortex-blog]: https://grafana.com/blog/2020/01/21/the-future-of-cortex-into-the-next-decade/
 [kubecon-cortex-101]: https://kccncna19.sched.com/event/UaiH/cortex-101-horizontally-scalable-long-term-storage-for-prometheus-chris-marchbanks-splunk
 [kubecon-cortex-101-video]: https://www.youtube.com/watch?v=f8GmbH0U_kI
 [kubecon-cortex-101-slides]: https://static.sched.com/hosted_files/kccncna19/92/cortex_101.pdf
@@ -142,3 +157,7 @@ in the [Weave Cloud documentation](https://www.weave.works/docs/cloud/latest/ove
 To use Cortex as part of Grafana Cloud, sign up for [Grafana Cloud](https://grafana.com/cloud)
 by clicking "Log In" in the top right and then "Sign Up Now".  Cortex is included
 as part of the Starter and Basic Hosted Grafana plans.
+
+### Amazon Managed Service for Prometheus (AMP)
+
+[Amazon Managed Service for Prometheus (AMP)](https://aws.amazon.com/prometheus/) is a Prometheus-compatible monitoring service that makes it easy to monitor containerized applications at scale. It is a highly available, secure, and managed monitoring for your containers. Get started [here](https://console.aws.amazon.com/prometheus/home). To learn more about the AMP, reference our [documentation](https://docs.aws.amazon.com/prometheus/latest/userguide/what-is-Amazon-Managed-Service-Prometheus.html) and [Getting Started with AMP blog](https://aws.amazon.com/blogs/mt/getting-started-amazon-managed-service-for-prometheus/).
diff --git a/RELEASE.md b/RELEASE.md
index 07da8cb..a5767c3 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -20,7 +20,11 @@ Our goal is to provide a new minor release every 6 weeks. This is a new process 
 | v1.2.0         | 2020-06-24                                 | Bryan Boreham                               |
 | v1.3.0         | 2020-08-03                                 | Marco Pracucci (@pracucci)                  |
 | v1.4.0         | 2020-09-14                                 | Marco Pracucci (@pracucci)                  |
-| v1.5.0         | 2020-10-26                                 |                                             |
+| v1.5.0         | 2020-10-26                                 | Chris Marchbanks (@csmarchbanks)            |
+| v1.6.0         | 2020-12-07                                 | Jacob Lisi (@jtlisi)                        |
+| v1.7.0         | 2021-01-18                                 | Ken Haines (@khaines)                       |
+| v1.8.0         | 2021-03-01                                 | Peter Štibraný (@pstibrany)                 |
+| v1.9.0         | 2021-04-12                                 | Goutham Veeramachaneni (@gouthamve)         |
 
 ## Release shepherd responsibilities
 
@@ -83,7 +87,7 @@ To publish a release candidate:
 1. Do not change the release branch directly; make a PR to the release-X.Y branch with VERSION and any CHANGELOG changes.
 1. Ensure the `VERSION` file has the `-rc.X` suffix (`X` starting from `0`)
 1. `git tag` the new release (see [How to tag a release](#how-to-tag-a-release))
-1. Wait until CI pipeline succeeded (once a tag is created, the release process through CircleCI will be triggered for this tag)
+1. Wait until CI pipeline succeeded (once a tag is created, the release process through GitHub actions will be triggered for this tag)
 1. Create a pre-release in GitHub
    - Write the release notes (including a copy-paste of the changelog)
    - Build binaries with `make dist` and attach them to the release
@@ -99,7 +103,7 @@ To publish a stable release:
    - Kubernetes manifests located at `k8s/`
    - Documentation located at `docs/`
 1. `git tag` the new release (see [How to tag a release](#how-to-tag-a-release))
-1. Wait until CI pipeline succeeded (once a tag is created, the release process through CircleCI will be triggered for this tag)
+1. Wait until CI pipeline succeeded (once a tag is created, the release process through GitHub actions will be triggered for this tag)
 1. Create a release in GitHub
    - Write the release notes (including a copy-paste of the changelog)
    - Build binaries with `make dist` and attach them to the release
diff --git a/SECURITY.md b/SECURITY.md
index a856e43..6f7b3ac 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -5,3 +5,82 @@ As with any complex system, it is certain that bugs will be found, some of them 
 ## Public Disclosure Timing
 
 The public disclosure date is agreed between the Cortex Team and the bug submitter. We prefer to fully disclose the bug as soon as possible, but only after a mitigation or fix is available. We will ask for delay if the bug or the fix is not yet fully understood or the solution is not tested to our standards yet. While there is no fixed timeframe for fix & disclosure, we will try our best to be quick and do not expect to need the usual 90 days most companies ask or. For a vulnerability with a straightforward mitigation, we expect report date to disclosure date to be on the order of 7 days.
+
+---------------------------
+
+## Private Vendors List
+
+We also have a list for vendors who provide Cortex to their users.
+This list is not intended for individuals to find out about security issues.
+
+### Embargo Policy
+
+The information members receive on [e-mail]
+must not be made public, shared, nor even hinted at anywhere
+beyond the need-to-know within your specific team except with the list's
+explicit approval. This holds true until the public disclosure date/time that was
+agreed upon by the list. Members of the list and others may not use the information
+ for anything other than getting the issue fixed for your respective vendor’s users.
+
+Before any information from the list is shared with respective members of your
+team required to fix said issue, they must agree to the same terms and only
+find out information on a need-to-know basis.
+
+In the unfortunate event you share the information beyond what is allowed by
+this policy, you _must_ urgently inform the [e-mail]
+mailing list of exactly what information
+leaked and to whom. A retrospective will take place after the leak so
+we can assess how to not make the same mistake in the future.
+
+If you continue to leak information and break the policy outlined here, you
+will be removed from the list.
+
+### Contributing Back
+
+This is a team effort. As a member of the list you must carry some water. This
+could be in the form of the following:
+
+**Technical**
+
+- Review and/or test the proposed patches and point out potential issues with
+  them (such as incomplete fixes for the originally reported issues, additional
+  issues you might notice, and newly introduced bugs), and inform the list of the
+  work done even if no issues were encountered.
+
+**Administrative**
+
+- Help draft emails to the public disclosure mailing list.
+- Help with release notes.
+
+### Membership
+
+Group membership is managed by the Cortex maintainers using Google Groups.
+
+### Membership Criteria
+
+To be eligible for the [e-mail] mailing list, your
+company should:
+
+0. Have an actively monitored security email alias for our project.
+1. Have a public hosted version/distribution of Cortex.
+2. Have a user base not limited to your own organization.
+3. Not be a downstream or rebuild of another vendor.
+4. Be a participant and active contributor in the community.
+5. Accept the [Embargo Policy](#embargo-policy) that is outlined above.
+6. Be willing to [contribute back](#contributing-back) as outlined above.
+
+**Removal**: If your vendor stops meeting one or more of these criteria
+after joining the list then you will be unsubscribed.
+
+### Request to Join
+
+Please open an issue to the repo with the details to prove that you're eligible based on
+the above criteria. The team will review the application and will reach out to you in case
+of any clarifications. Once the application is accepted you'll be added to the mailing-list
+and also to the list below.
+
+### Members of the list
+
+Members of the list are listed below:
+- Cortex Maintainers
+- AWS Security Announce (email private)
diff --git a/VERSION b/VERSION
index 88c5fb8..bd8bf88 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-1.4.0
+1.7.0
diff --git a/build-image/Dockerfile b/build-image/Dockerfile
index fcd001d..054d080 100644
--- a/build-image/Dockerfile
+++ b/build-image/Dockerfile
@@ -1,10 +1,10 @@
-FROM golang:1.14.9-stretch
+FROM golang:1.14.9-buster
 ARG goproxyValue
 ENV GOPROXY=${goproxyValue}
 RUN apt-get update && apt-get install -y curl python-requests python-yaml file jq unzip protobuf-compiler libprotobuf-dev && \
 	rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
 RUN curl -sL https://deb.nodesource.com/setup_14.x | bash -
-RUN apt-get install -y nodejs npm && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
+RUN apt-get install -y nodejs && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
 
 # Install website builder dependencies. Whenever you change these version, please also change website/package.json
 # and viceversa.
diff --git a/cmd/blocksconvert/main.go b/cmd/blocksconvert/main.go
index 500f6e8..0bbb8e0 100644
--- a/cmd/blocksconvert/main.go
+++ b/cmd/blocksconvert/main.go
@@ -17,6 +17,7 @@ import (
 	"github.com/cortexproject/cortex/pkg/util/services"
 	"github.com/cortexproject/cortex/tools/blocksconvert"
 	"github.com/cortexproject/cortex/tools/blocksconvert/builder"
+	"github.com/cortexproject/cortex/tools/blocksconvert/cleaner"
 	"github.com/cortexproject/cortex/tools/blocksconvert/scanner"
 	"github.com/cortexproject/cortex/tools/blocksconvert/scheduler"
 )
@@ -29,6 +30,7 @@ type Config struct {
 	ScannerConfig   scanner.Config
 	BuilderConfig   builder.Config
 	SchedulerConfig scheduler.Config
+	CleanerConfig   cleaner.Config
 }
 
 func main() {
@@ -38,6 +40,7 @@ func main() {
 	cfg.ScannerConfig.RegisterFlags(flag.CommandLine)
 	cfg.BuilderConfig.RegisterFlags(flag.CommandLine)
 	cfg.SchedulerConfig.RegisterFlags(flag.CommandLine)
+	cfg.CleanerConfig.RegisterFlags(flag.CommandLine)
 	cfg.ServerConfig.RegisterFlags(flag.CommandLine)
 	flag.Parse()
 
@@ -62,6 +65,8 @@ func main() {
 		targetService, err = builder.NewBuilder(cfg.BuilderConfig, cfg.SharedConfig, util.Logger, registry)
 	case "scheduler":
 		targetService, err = scheduler.NewScheduler(cfg.SchedulerConfig, cfg.SharedConfig, util.Logger, registry, serv.HTTP, serv.GRPC)
+	case "cleaner":
+		targetService, err = cleaner.NewCleaner(cfg.CleanerConfig, cfg.SharedConfig, util.Logger, registry)
 	default:
 		err = fmt.Errorf("unknown target")
 	}
diff --git a/cmd/cortex/main.go b/cmd/cortex/main.go
index 8340e83..8955696 100644
--- a/cmd/cortex/main.go
+++ b/cmd/cortex/main.go
@@ -61,6 +61,8 @@ func main() {
 		eventSampleRate      int
 		ballastBytes         int
 		mutexProfileFraction int
+		printVersion         bool
+		printModules         bool
 	)
 
 	configFile, expandENV := parseConfigFileParameter(os.Args[1:])
@@ -86,6 +88,8 @@ func main() {
 	flag.IntVar(&eventSampleRate, "event.sample-rate", 0, "How often to sample observability events (0 = never).")
 	flag.IntVar(&ballastBytes, "mem-ballast-size-bytes", 0, "Size of memory ballast to allocate.")
 	flag.IntVar(&mutexProfileFraction, "debug.mutex-profile-fraction", 0, "Fraction at which mutex profile vents will be reported, 0 to disable")
+	flag.BoolVar(&printVersion, "version", false, "Print Cortex version and exit.")
+	flag.BoolVar(&printModules, "modules", false, "List available values that can be used as target.")
 
 	usage := flag.CommandLine.Usage
 	flag.CommandLine.Usage = func() { /* don't do anything by default, we will print usage ourselves, but only when requested. */ }
@@ -106,6 +110,11 @@ func main() {
 		}
 	}
 
+	if printVersion {
+		fmt.Fprintln(os.Stdout, version.Print("Cortex"))
+		return
+	}
+
 	// Validate the config once both the config file has been loaded
 	// and CLI flags parsed.
 	err = cfg.Validate(util.Logger)
@@ -118,7 +127,7 @@ func main() {
 
 	// Continue on if -modules flag is given. Code handling the
 	// -modules flag will not start cortex.
-	if testMode && !cfg.ListModules {
+	if testMode && !printModules {
 		DumpYaml(&cfg)
 		return
 	}
@@ -137,8 +146,13 @@ func main() {
 	// In testing mode skip JAEGER setup to avoid panic due to
 	// "duplicate metrics collector registration attempted"
 	if !testMode {
+		name := "cortex"
+		if len(cfg.Target) == 1 {
+			name += "-" + cfg.Target[0]
+		}
+
 		// Setting the environment variable JAEGER_AGENT_HOST enables tracing.
-		if trace, err := tracing.NewFromEnv("cortex-" + cfg.Target); err != nil {
+		if trace, err := tracing.NewFromEnv(name); err != nil {
 			level.Error(util.Logger).Log("msg", "Failed to setup tracing", "err", err.Error())
 		} else {
 			defer trace.Close()
@@ -151,7 +165,7 @@ func main() {
 	t, err := cortex.New(cfg)
 	util.CheckFatal("initializing cortex", err)
 
-	if t.Cfg.ListModules {
+	if printModules {
 		allDeps := t.ModuleManager.DependenciesForModule(cortex.All)
 
 		for _, m := range t.ModuleManager.UserVisibleModuleNames() {
@@ -167,12 +181,7 @@ func main() {
 
 		fmt.Fprintln(os.Stdout)
 		fmt.Fprintln(os.Stdout, "Modules marked with * are included in target All.")
-
-		// in test mode we cannot call os.Exit, it will stop to whole test process.
-		if testMode {
-			return
-		}
-		os.Exit(2)
+		return
 	}
 
 	level.Info(util.Logger).Log("msg", "Starting Cortex", "version", version.Info())
diff --git a/cmd/cortex/main_test.go b/cmd/cortex/main_test.go
index e053f83..d5c5a14 100644
--- a/cmd/cortex/main_test.go
+++ b/cmd/cortex/main_test.go
@@ -80,6 +80,11 @@ func TestFlagParsing(t *testing.T) {
 			stderrMessage: "the Querier configuration in YAML has been specified as an empty YAML node",
 		},
 
+		"version": {
+			arguments:     []string{"-version"},
+			stdoutMessage: "Cortex, version",
+		},
+
 		// we cannot test the happy path, as cortex would then fully start
 	} {
 		t.Run(name, func(t *testing.T) {
diff --git a/development/tsdb-blocks-storage-s3-gossip/.data-ingester-1/.gitignore b/development/tsdb-blocks-storage-s3-gossip/.data-ingester-1/.gitignore
new file mode 100644
index 0000000..d6b7ef3
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3-gossip/.data-ingester-1/.gitignore
@@ -0,0 +1,2 @@
+*
+!.gitignore
diff --git a/development/tsdb-blocks-storage-s3-gossip/.data-ingester-2/.gitignore b/development/tsdb-blocks-storage-s3-gossip/.data-ingester-2/.gitignore
new file mode 100644
index 0000000..d6b7ef3
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3-gossip/.data-ingester-2/.gitignore
@@ -0,0 +1,2 @@
+*
+!.gitignore
diff --git a/development/tsdb-blocks-storage-s3-gossip/.data-minio/.gitignore b/development/tsdb-blocks-storage-s3-gossip/.data-minio/.gitignore
new file mode 100644
index 0000000..521c201
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3-gossip/.data-minio/.gitignore
@@ -0,0 +1,5 @@
+*
+!.gitignore
+!cortex-tsdb
+!cortex-alertmanager
+!cortex-ruler
diff --git a/development/tsdb-blocks-storage-s3-gossip/.data-minio/cortex-alertmanager/.gitignore b/development/tsdb-blocks-storage-s3-gossip/.data-minio/cortex-alertmanager/.gitignore
new file mode 100644
index 0000000..d6b7ef3
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3-gossip/.data-minio/cortex-alertmanager/.gitignore
@@ -0,0 +1,2 @@
+*
+!.gitignore
diff --git a/development/tsdb-blocks-storage-s3-gossip/.data-minio/cortex-ruler/.gitignore b/development/tsdb-blocks-storage-s3-gossip/.data-minio/cortex-ruler/.gitignore
new file mode 100644
index 0000000..d6b7ef3
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3-gossip/.data-minio/cortex-ruler/.gitignore
@@ -0,0 +1,2 @@
+*
+!.gitignore
diff --git a/development/tsdb-blocks-storage-s3-gossip/.data-minio/cortex-tsdb/.gitignore b/development/tsdb-blocks-storage-s3-gossip/.data-minio/cortex-tsdb/.gitignore
new file mode 100644
index 0000000..d6b7ef3
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3-gossip/.data-minio/cortex-tsdb/.gitignore
@@ -0,0 +1,2 @@
+*
+!.gitignore
diff --git a/development/tsdb-blocks-storage-s3-gossip/.dockerignore b/development/tsdb-blocks-storage-s3-gossip/.dockerignore
new file mode 100644
index 0000000..085f68e
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3-gossip/.dockerignore
@@ -0,0 +1,4 @@
+.data-configstore
+.data-ingester-1
+.data-ingester-2
+.data-minio
diff --git a/development/tsdb-blocks-storage-s3-gossip/.gitignore b/development/tsdb-blocks-storage-s3-gossip/.gitignore
new file mode 100644
index 0000000..ec09251
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3-gossip/.gitignore
@@ -0,0 +1 @@
+cortex
\ No newline at end of file
diff --git a/development/tsdb-blocks-storage-s3-gossip/compose-down.sh b/development/tsdb-blocks-storage-s3-gossip/compose-down.sh
new file mode 100755
index 0000000..39f3730
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3-gossip/compose-down.sh
@@ -0,0 +1,5 @@
+#!/bin/bash
+
+SCRIPT_DIR=$(cd `dirname $0` && pwd)
+
+docker-compose -f ${SCRIPT_DIR}/docker-compose.yml down
diff --git a/development/tsdb-blocks-storage-s3-gossip/compose-up.sh b/development/tsdb-blocks-storage-s3-gossip/compose-up.sh
new file mode 100755
index 0000000..7baee60
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3-gossip/compose-up.sh
@@ -0,0 +1,10 @@
+#!/bin/bash
+
+set -e
+
+SCRIPT_DIR=$(cd `dirname $0` && pwd)
+
+# -gcflags "all=-N -l" disables optimizations that allow for better run with combination with Delve debugger.
+CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -mod=vendor -gcflags "all=-N -l" -o ${SCRIPT_DIR}/cortex ${SCRIPT_DIR}/../../cmd/cortex
+docker-compose -f ${SCRIPT_DIR}/docker-compose.yml build distributor
+docker-compose -f ${SCRIPT_DIR}/docker-compose.yml up $@
diff --git a/development/tsdb-blocks-storage-s3-gossip/config/cortex.yaml b/development/tsdb-blocks-storage-s3-gossip/config/cortex.yaml
new file mode 100644
index 0000000..157082a
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3-gossip/config/cortex.yaml
@@ -0,0 +1,143 @@
+auth_enabled: false
+
+distributor:
+  shard_by_all_labels: true
+  pool:
+    health_check_ingesters: true
+
+ingester_client:
+  grpc_client_config:
+    # Configure the client to allow messages up to 100MB.
+    max_recv_msg_size: 104857600
+    max_send_msg_size: 104857600
+    grpc_compression: gzip
+
+ingester:
+  lifecycler:
+    # We want to start immediately.
+    join_after: 0
+    final_sleep: 0s
+    num_tokens: 512
+
+    ring:
+      kvstore:
+        store: memberlist
+      replication_factor: 1
+
+memberlist:
+  message_history_buffer_bytes: 1048576
+  join_members:
+    - distributor:10001
+    - ingester-1:10002
+    - ingester-2:10003
+    - querier:10004
+    - compactor:10006
+    - store-gateway-1:10008
+    - store-gateway-2:10009
+    - ruler-1:10021
+    - ruler-2:10022
+    - querier-with-scheduler:10013
+  abort_if_cluster_join_fails: false
+
+querier:
+  query_ingesters_within: 3h
+
+  # Used when the blocks sharding is disabled.
+  store_gateway_addresses: store-gateway-1:9008,store-gateway-2:9009
+
+blocks_storage:
+  backend: s3
+
+  tsdb:
+    dir: /tmp/cortex-tsdb-ingester
+    ship_interval: 1m
+    block_ranges_period: [ 2h ]
+    retention_period: 3h
+
+  bucket_store:
+    sync_dir: /tmp/cortex-tsdb-querier
+    consistency_delay: 5s
+
+    index_cache:
+      backend: memcached
+      memcached:
+        addresses: dns+memcached:11211
+
+    chunks_cache:
+      backend: memcached
+      memcached:
+        addresses: dns+memcached:11211
+
+    metadata_cache:
+      backend: memcached
+      memcached:
+        addresses: dns+memcached:11211
+
+  s3:
+    endpoint:          minio:9000
+    bucket_name:       cortex-tsdb
+    access_key_id:     cortex
+    secret_access_key: supersecret
+    insecure:          true
+
+ruler:
+  enable_api: true
+  storage:
+    type: s3
+    s3:
+      bucketnames: cortex-ruler
+      s3forcepathstyle: true
+      s3: http://cortex:supersecret@minio.:9000
+  enable_sharding: true
+  ring:
+    heartbeat_period:   5s
+    heartbeat_timeout:  15s
+    kvstore:
+      store: memberlist
+
+alertmanager:
+  enable_api: true
+  storage:
+    type: s3
+    s3:
+      bucketnames: cortex-alertmanager
+      s3forcepathstyle: true
+      s3: http://cortex:supersecret@minio.:9000
+
+storage:
+  engine: blocks
+
+compactor:
+  compaction_interval: 30s
+  data_dir:            /tmp/cortex-compactor
+  consistency_delay:   1m
+  sharding_enabled:    true
+  sharding_ring:
+    kvstore:
+      store: memberlist
+
+store_gateway:
+  sharding_enabled: true
+  sharding_ring:
+    replication_factor: 1
+    heartbeat_period:   5s
+    heartbeat_timeout:  15s
+    kvstore:
+      store: memberlist
+
+frontend_worker:
+  frontend_address: "query-frontend:9007"
+  match_max_concurrent: true
+
+  # By setting scheduler_address, querier worker would use scheduler instead of frontend.
+  # scheduler_address: "query-scheduler:9012"
+
+query_range:
+  split_queries_by_interval: 24h
+
+limits:
+  # Limit max query time range to 31d
+  max_query_length: 744h
+
+runtime_config:
+  file: ./config/runtime.yaml
diff --git a/development/tsdb-blocks-storage-s3-gossip/config/grafana-agent.yaml b/development/tsdb-blocks-storage-s3-gossip/config/grafana-agent.yaml
new file mode 100644
index 0000000..164b409
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3-gossip/config/grafana-agent.yaml
@@ -0,0 +1,64 @@
+server:
+  log_level: debug
+  http_listen_port: 9091
+
+prometheus:
+  global:
+    scrape_interval: 5s
+    external_labels:
+      scraped_by: grafana-agent
+  configs:
+    - name: local
+      host_filter: false
+      scrape_configs:
+        - job_name: tsdb-blocks-storage-s3/distributor
+          static_configs:
+            - targets: ['distributor:8001']
+              labels:
+                cluster: 'docker-compose'
+                namespace: 'tsdb-blocks-storage-s3'
+        - job_name: tsdb-blocks-storage-s3/ingester
+          static_configs:
+            - targets: ['ingester-1:8002', 'ingester-2:8003']
+              labels:
+                cluster: 'docker-compose'
+                namespace: 'tsdb-blocks-storage-s3'
+        - job_name: tsdb-blocks-storage-s3/querier
+          static_configs:
+            - targets: ['querier:8004', 'querier-with-scheduler:8013']
+              labels:
+                cluster: 'docker-compose'
+                namespace: 'tsdb-blocks-storage-s3'
+        - job_name: tsdb-blocks-storage-s3/ruler
+          static_configs:
+            - targets: ['ruler-1:8021', 'ruler-2:8022']
+              labels:
+                cluster: 'docker-compose'
+                namespace: 'tsdb-blocks-storage-s3'
+        - job_name: tsdb-blocks-storage-s3/compactor
+          static_configs:
+            - targets: ['compactor:8006']
+              labels:
+                cluster: 'docker-compose'
+                namespace: 'tsdb-blocks-storage-s3'
+        - job_name: tsdb-blocks-storage-s3/query-frontend
+          static_configs:
+            - targets: ['query-frontend:8007', 'query-frontend-with-scheduler:8012']
+              labels:
+                cluster: 'docker-compose'
+                namespace: 'tsdb-blocks-storage-s3'
+        - job_name: tsdb-blocks-storage-s3/store-gateway
+          static_configs:
+            - targets: ['store-gateway-1:8008', 'store-gateway-2:8009']
+              labels:
+                cluster: 'docker-compose'
+                namespace: 'tsdb-blocks-storage-s3'
+        - job_name: tsdb-blocks-storage-s3/query-scheduler
+          static_configs:
+            - targets: ['query-scheduler:8011']
+              labels:
+                cluster: 'docker-compose'
+                namespace: 'tsdb-blocks-storage-s3'
+
+      remote_write:
+        - url: http://distributor:8001/api/prom/push
diff --git a/development/tsdb-blocks-storage-s3-gossip/config/prometheus.yaml b/development/tsdb-blocks-storage-s3-gossip/config/prometheus.yaml
new file mode 100644
index 0000000..be12319
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3-gossip/config/prometheus.yaml
@@ -0,0 +1,57 @@
+global:
+  scrape_interval: 5s
+  external_labels:
+    scraped_by: prometheus
+
+scrape_configs:
+  - job_name: tsdb-blocks-storage-s3/distributor
+    static_configs:
+      - targets: ['distributor:8001']
+        labels:
+          cluster: 'docker-compose'
+          namespace: 'tsdb-blocks-storage-s3'
+  - job_name: tsdb-blocks-storage-s3/ingester
+    static_configs:
+      - targets: ['ingester-1:8002', 'ingester-2:8003']
+        labels:
+          cluster: 'docker-compose'
+          namespace: 'tsdb-blocks-storage-s3'
+  - job_name: tsdb-blocks-storage-s3/querier
+    static_configs:
+      - targets: ['querier:8004', 'query-frontend-with-scheduler:8013']
+        labels:
+          cluster: 'docker-compose'
+          namespace: 'tsdb-blocks-storage-s3'
+  - job_name: tsdb-blocks-storage-s3/ruler
+    static_configs:
+      - targets: ['ruler-1:8021', 'ruler-2:8022']
+        labels:
+          cluster: 'docker-compose'
+          namespace: 'tsdb-blocks-storage-s3'
+  - job_name: tsdb-blocks-storage-s3/compactor
+    static_configs:
+      - targets: ['compactor:8006']
+        labels:
+          cluster: 'docker-compose'
+          namespace: 'tsdb-blocks-storage-s3'
+  - job_name: tsdb-blocks-storage-s3/query-frontend
+    static_configs:
+      - targets: ['query-frontend:8007', 'query-frontend-with-scheduler:8012']
+        labels:
+          cluster: 'docker-compose'
+          namespace: 'tsdb-blocks-storage-s3'
+  - job_name: tsdb-blocks-storage-s3/store-gateway
+    static_configs:
+      - targets: ['store-gateway-1:8008', 'store-gateway-2:8009']
+        labels:
+          cluster: 'docker-compose'
+          namespace: 'tsdb-blocks-storage-s3'
+  - job_name: tsdb-blocks-storage-s3/query-scheduler
+    static_configs:
+      - targets: ['query-scheduler:8011']
+        labels:
+          cluster: 'docker-compose'
+          namespace: 'tsdb-blocks-storage-s3'
+
+remote_write:
+  - url: http://distributor:8001/api/prom/push
diff --git a/development/tsdb-blocks-storage-s3-gossip/config/runtime.yaml b/development/tsdb-blocks-storage-s3-gossip/config/runtime.yaml
new file mode 100644
index 0000000..475c274
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3-gossip/config/runtime.yaml
@@ -0,0 +1 @@
+# This file is left empty. It can be configured with overrides or other runtime config.
diff --git a/development/tsdb-blocks-storage-s3-gossip/dev.dockerfile b/development/tsdb-blocks-storage-s3-gossip/dev.dockerfile
new file mode 100644
index 0000000..ddeebf6
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3-gossip/dev.dockerfile
@@ -0,0 +1,10 @@
+FROM golang:1.14
+ENV CGO_ENABLED=0 GOOS=linux GOARCH=amd64
+RUN go get github.com/go-delve/delve/cmd/dlv
+
+FROM alpine:3.12
+
+RUN     mkdir /cortex
+WORKDIR /cortex
+ADD     ./cortex ./
+COPY --from=0 /go/bin/dlv ./
diff --git a/development/tsdb-blocks-storage-s3-gossip/docker-compose.yml b/development/tsdb-blocks-storage-s3-gossip/docker-compose.yml
new file mode 100644
index 0000000..73b5dfd
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3-gossip/docker-compose.yml
@@ -0,0 +1,338 @@
+version: '3.4'
+services:
+
+  consul:
+    image: consul
+    command: [ "agent", "-dev" ,"-client=0.0.0.0", "-log-level=info" ]
+    ports:
+      - 8500:8500
+
+  minio:
+    image: minio/minio
+    command: [ "server", "/data" ]
+    environment:
+      - MINIO_ACCESS_KEY=cortex
+      - MINIO_SECRET_KEY=supersecret
+    ports:
+      - 9000:9000
+    volumes:
+      - .data-minio:/data:delegated
+
+  memcached:
+    image: memcached:1.6
+
+  prometheus:
+    image: prom/prometheus:v2.16.0
+    command: ["--config.file=/etc/prometheus/prometheus.yaml"]
+    volumes:
+      - ./config:/etc/prometheus
+    ports:
+      - 9090:9090
+
+  jaeger:
+    image: jaegertracing/all-in-one
+    ports:
+      - 16686:16686
+      - "14268"
+
+  # Scrape the metrics also with the Grafana agent (useful to test metadata ingestion
+  # until metadata remote write is not supported by Prometheus).
+  grafana-agent:
+    image: grafana/agent:v0.2.0
+    command: ["-config.file=/etc/agent-config/grafana-agent.yaml", "-prometheus.wal-directory=/tmp"]
+    volumes:
+      - ./config:/etc/agent-config
+    ports:
+      - 9091:9091
+
+  distributor:
+    build:
+      context:    .
+      dockerfile: dev.dockerfile
+    image: cortex
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18001 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=distributor -server.http-listen-port=8001 -server.grpc-listen-port=9001 -memberlist.nodename=distributor -memberlist.bind-port=10001 -log.level=debug"]
+    depends_on:
+      - consul
+      - minio
+    environment:
+      - JAEGER_AGENT_HOST=jaeger
+      - JAEGER_AGENT_PORT=6831
+      - JAEGER_TAGS=app=distributor
+      - JAEGER_SAMPLER_TYPE=const
+      - JAEGER_SAMPLER_PARAM=1
+    ports:
+      - 8001:8001
+      - 18001:18001
+    volumes:
+      - ./config:/cortex/config
+
+  ingester-1:
+    build:
+      context:    .
+      dockerfile: dev.dockerfile
+    image: cortex
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18002 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=ingester -server.http-listen-port=8002 -server.grpc-listen-port=9002 -memberlist.nodename=ingester-1 -memberlist.bind-port=10002"]
+    depends_on:
+      - consul
+      - minio
+    environment:
+      - JAEGER_AGENT_HOST=jaeger
+      - JAEGER_AGENT_PORT=6831
+      - JAEGER_TAGS=app=ingester-1
+      - JAEGER_SAMPLER_TYPE=const
+      - JAEGER_SAMPLER_PARAM=1
+    ports:
+      - 8002:8002
+      - 18002:18002
+    volumes:
+      - ./config:/cortex/config
+      - .data-ingester-1:/tmp/cortex-tsdb-ingester:delegated
+
+  ingester-2:
+    build:
+      context:    .
+      dockerfile: dev.dockerfile
+    image: cortex
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18003 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=ingester -server.http-listen-port=8003 -server.grpc-listen-port=9003 -memberlist.nodename=ingester-2 -memberlist.bind-port=10003"]
+    depends_on:
+      - consul
+      - minio
+    environment:
+      - JAEGER_AGENT_HOST=jaeger
+      - JAEGER_AGENT_PORT=6831
+      - JAEGER_TAGS=app=ingester-2
+      - JAEGER_SAMPLER_TYPE=const
+      - JAEGER_SAMPLER_PARAM=1
+    ports:
+      - 8003:8003
+      - 18003:18003
+    volumes:
+      - ./config:/cortex/config
+      - .data-ingester-2:/tmp/cortex-tsdb-ingester:delegated
+    
+  querier:
+    build:
+      context:    .
+      dockerfile: dev.dockerfile
+    image: cortex
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18004 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=querier -server.http-listen-port=8004 -server.grpc-listen-port=9004 -memberlist.nodename=querier -memberlist.bind-port=10004"]
+    depends_on:
+      - consul
+      - minio
+    environment:
+      - JAEGER_AGENT_HOST=jaeger
+      - JAEGER_AGENT_PORT=6831
+      - JAEGER_TAGS=app=querier
+      - JAEGER_SAMPLER_TYPE=const
+      - JAEGER_SAMPLER_PARAM=1
+    ports:
+      - 8004:8004
+      - 18004:18004
+    volumes:
+      - ./config:/cortex/config
+
+  store-gateway-1:
+    build:
+      context:    .
+      dockerfile: dev.dockerfile
+    image: cortex
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18008 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=store-gateway -server.http-listen-port=8008 -server.grpc-listen-port=9008 -memberlist.nodename=store-gateway-1 -memberlist.bind-port=10008"]
+    depends_on:
+      - consul
+      - minio
+    environment:
+      - JAEGER_AGENT_HOST=jaeger
+      - JAEGER_AGENT_PORT=6831
+      - JAEGER_TAGS=app=store-gateway-1
+      - JAEGER_SAMPLER_TYPE=const
+      - JAEGER_SAMPLER_PARAM=1
+    ports:
+      - 8008:8008
+      - 18008:18008
+    volumes:
+      - ./config:/cortex/config
+
+  store-gateway-2:
+    build:
+      context:    .
+      dockerfile: dev.dockerfile
+    image: cortex
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18009 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=store-gateway -server.http-listen-port=8009 -server.grpc-listen-port=9009 -memberlist.nodename=store-gateway-2 -memberlist.bind-port=10009"]
+    depends_on:
+      - consul
+      - minio
+    environment:
+      - JAEGER_AGENT_HOST=jaeger
+      - JAEGER_AGENT_PORT=6831
+      - JAEGER_TAGS=app=store-gateway-2
+      - JAEGER_SAMPLER_TYPE=const
+      - JAEGER_SAMPLER_PARAM=1
+    ports:
+      - 8009:8009
+      - 18009:18009
+    volumes:
+      - ./config:/cortex/config
+
+  compactor:
+    build:
+      context:    .
+      dockerfile: dev.dockerfile
+    image: cortex
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18006 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=compactor -server.http-listen-port=8006 -server.grpc-listen-port=9006  -memberlist.nodename=compactor -memberlist.bind-port=10006"]
+    depends_on:
+      - consul
+      - minio
+    environment:
+      - JAEGER_AGENT_HOST=jaeger
+      - JAEGER_AGENT_PORT=6831
+      - JAEGER_TAGS=app=compactor
+      - JAEGER_SAMPLER_TYPE=const
+      - JAEGER_SAMPLER_PARAM=1
+    ports:
+      - 8006:8006
+      - 18006:18006
+    volumes:
+      - ./config:/cortex/config
+
+  query-frontend:
+    build:
+      context:    .
+      dockerfile: dev.dockerfile
+    image: cortex
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18007 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=query-frontend -server.http-listen-port=8007 -server.grpc-listen-port=9007 -store.max-query-length=8760h"]
+    depends_on:
+      - consul
+      - minio
+    environment:
+      - JAEGER_AGENT_HOST=jaeger
+      - JAEGER_AGENT_PORT=6831
+      - JAEGER_TAGS=app=query-frontend
+      - JAEGER_SAMPLER_TYPE=const
+      - JAEGER_SAMPLER_PARAM=1
+    ports:
+      - 8007:8007
+      - 18007:18007
+    volumes:
+      - ./config:/cortex/config
+
+  alertmanager:
+    build:
+      context:    .
+      dockerfile: dev.dockerfile
+    image: cortex
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18010 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=alertmanager -server.http-listen-port=8010 -server.grpc-listen-port=9010  -alertmanager.web.external-url=localhost:8010"]
+    depends_on:
+      - consul
+      - minio
+    ports:
+      - 8010:8010
+      - 18010:18010
+    volumes:
+      - ./config:/cortex/config
+
+  ruler-1:
+    build:
+      context:    .
+      dockerfile: dev.dockerfile
+    image: cortex
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18021 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=ruler -server.http-listen-port=8021 -server.grpc-listen-port=9021 -memberlist.nodename=ruler-1 -memberlist.bind-port=10021"]
+    depends_on:
+      - consul
+      - minio
+    environment:
+      - JAEGER_AGENT_HOST=jaeger
+      - JAEGER_AGENT_PORT=6831
+      - JAEGER_TAGS=app=ruler-1
+      - JAEGER_SAMPLER_TYPE=const
+      - JAEGER_SAMPLER_PARAM=1
+    ports:
+      - 8021:8021
+      - 18021:18021
+    volumes:
+      - ./config:/cortex/config
+
+  ruler-2:
+    build:
+      context:    .
+      dockerfile: dev.dockerfile
+    image: cortex
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18022 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=ruler -server.http-listen-port=8022 -server.grpc-listen-port=9022 -memberlist.nodename=ruler-2 -memberlist.bind-port=10022"]
+    depends_on:
+      - consul
+      - minio
+    environment:
+      - JAEGER_AGENT_HOST=jaeger
+      - JAEGER_AGENT_PORT=6831
+      - JAEGER_TAGS=app=ruler-2
+      - JAEGER_SAMPLER_TYPE=const
+      - JAEGER_SAMPLER_PARAM=1
+    ports:
+      - 8022:8022
+      - 18022:18022
+    volumes:
+      - ./config:/cortex/config
+
+  query-scheduler:
+    build:
+      context:    .
+      dockerfile: dev.dockerfile
+    image: cortex
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18011 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=query-scheduler -server.http-listen-port=8011 -server.grpc-listen-port=9011 -store.max-query-length=8760h -log.level=debug"]
+    depends_on:
+      - consul
+      - minio
+    environment:
+      - JAEGER_AGENT_HOST=jaeger
+      - JAEGER_AGENT_PORT=6831
+      - JAEGER_TAGS=app=query-scheduler
+      - JAEGER_SAMPLER_TYPE=const
+      - JAEGER_SAMPLER_PARAM=1
+    ports:
+      - 8011:8011
+      - 18011:18011
+    volumes:
+      - ./config:/cortex/config
+
+  # This frontend uses query-scheduler, activated by `-frontend.scheduler-address` option.
+  query-frontend-with-scheduler:
+    build:
+      context:    .
+      dockerfile: dev.dockerfile
+    image: cortex
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18012 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=query-frontend -server.http-listen-port=8012 -server.grpc-listen-port=9012 -store.max-query-length=8760h -frontend.scheduler-address=query-scheduler:9011 -log.level=debug"]
+    depends_on:
+      - consul
+      - minio
+    environment:
+      - JAEGER_AGENT_HOST=jaeger
+      - JAEGER_AGENT_PORT=6831
+      - JAEGER_TAGS=app=query-frontend2
+      - JAEGER_SAMPLER_TYPE=const
+      - JAEGER_SAMPLER_PARAM=1
+    ports:
+      - 8012:8012
+      - 18012:18012
+    volumes:
+      - ./config:/cortex/config
+
+  # This querier is connecting to query-scheduler, instead of query-frontend. This is achieved by setting -querier.scheduler-address="..."
+  querier-with-scheduler:
+    build:
+      context:    .
+      dockerfile: dev.dockerfile
+    image: cortex
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18013 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=querier -server.http-listen-port=8013 -server.grpc-listen-port=9013 -querier.scheduler-address=query-scheduler:9011 -querier.frontend-address= -log.level=debug -memberlist.nodename=querier-with-scheduler -memberlist.bind-port=10013"]
+    depends_on:
+      - consul
+      - minio
+    environment:
+      - JAEGER_AGENT_HOST=jaeger
+      - JAEGER_AGENT_PORT=6831
+      - JAEGER_TAGS=app=querier-scheduler
+      - JAEGER_SAMPLER_TYPE=const
+      - JAEGER_SAMPLER_PARAM=1
+    ports:
+      - 8013:8013
+      - 18013:18013
+    volumes:
+      - ./config:/cortex/config
diff --git a/development/tsdb-blocks-storage-s3-single-binary/config/cortex.yaml b/development/tsdb-blocks-storage-s3-single-binary/config/cortex.yaml
index a9e1970..bbe4cc4 100644
--- a/development/tsdb-blocks-storage-s3-single-binary/config/cortex.yaml
+++ b/development/tsdb-blocks-storage-s3-single-binary/config/cortex.yaml
@@ -75,3 +75,6 @@ ruler:
       store: consul
       consul:
         host: consul:8500
+
+runtime_config:
+  file: ./config/runtime.yaml
diff --git a/development/tsdb-blocks-storage-s3-single-binary/config/runtime.yaml b/development/tsdb-blocks-storage-s3-single-binary/config/runtime.yaml
new file mode 100644
index 0000000..475c274
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3-single-binary/config/runtime.yaml
@@ -0,0 +1 @@
+# This file is left empty. It can be configured with overrides or other runtime config.
diff --git a/development/tsdb-blocks-storage-s3/.data-configstore/api/prom/configs/rules b/development/tsdb-blocks-storage-s3/.data-configstore/api/prom/configs/rules
deleted file mode 100644
index fa6bcd3..0000000
--- a/development/tsdb-blocks-storage-s3/.data-configstore/api/prom/configs/rules
+++ /dev/null
@@ -1,14 +0,0 @@
-{
-    "since": 2,
-    "configs": {
-        "fake": {
-            "id": 1,
-            "config": {
-                "rule_format_version": "2",
-                "rules_files": {
-                    "test": "groups:\n    - name: group-1\n      rules:\n      - record: avalanche_metric_mmmmm_0_0:count\n        expr: count(avalanche_metric_mmmmm_0_0)\n    - name: group-2\n      rules:\n      - record: avalanche_metric_mmmmm_0:count\n        expr: |\n          count(avalanche_metric_mmmmm_0_0) +\n          count(avalanche_metric_mmmmm_0_1)\n      - alert: alert-1\n        expr: |\n          count(avalanche_metric_mmmmm_0_0) > 1000\n      - alert: alert-2\n        expr:  count(avalanche_metric_mmmmm_0_0) > 100\n        for:   5m\n        labels:\n          label1: value1\n          label2: value2\n        annotations:\n          annotation1: value1\n          annotation2: value2\n"
-                }
-            }
-        }
-    }
-}
diff --git a/development/tsdb-blocks-storage-s3/.data-configstore/api/prom/configs/rules.yaml b/development/tsdb-blocks-storage-s3/.data-configstore/api/prom/configs/rules.yaml
deleted file mode 100644
index 3fd54ff..0000000
--- a/development/tsdb-blocks-storage-s3/.data-configstore/api/prom/configs/rules.yaml
+++ /dev/null
@@ -1,23 +0,0 @@
-groups:
-    - name: group-1
-      rules:
-      - record: avalanche_metric_mmmmm_0_0:count
-        expr: count(avalanche_metric_mmmmm_0_0)
-    - name: group-2
-      rules:
-      - record: avalanche_metric_mmmmm_0:count
-        expr: |
-          count(avalanche_metric_mmmmm_0_0) +
-          count(avalanche_metric_mmmmm_0_1)
-      - alert: alert-1
-        expr: |
-          count(avalanche_metric_mmmmm_0_0) > 1000
-      - alert: alert-2
-        expr:  count(avalanche_metric_mmmmm_0_0) > 100
-        for:   5m
-        labels:
-          label1: value1
-          label2: value2
-        annotations:
-          annotation1: value1
-          annotation2: value2
diff --git a/development/tsdb-blocks-storage-s3/.data-minio/.gitignore b/development/tsdb-blocks-storage-s3/.data-minio/.gitignore
index f8872cf..521c201 100644
--- a/development/tsdb-blocks-storage-s3/.data-minio/.gitignore
+++ b/development/tsdb-blocks-storage-s3/.data-minio/.gitignore
@@ -2,3 +2,4 @@
 !.gitignore
 !cortex-tsdb
 !cortex-alertmanager
+!cortex-ruler
diff --git a/development/tsdb-blocks-storage-s3/.data-minio/cortex-ruler/.gitignore b/development/tsdb-blocks-storage-s3/.data-minio/cortex-ruler/.gitignore
new file mode 100644
index 0000000..d6b7ef3
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3/.data-minio/cortex-ruler/.gitignore
@@ -0,0 +1,2 @@
+*
+!.gitignore
diff --git a/development/tsdb-blocks-storage-s3/config/cortex.yaml b/development/tsdb-blocks-storage-s3/config/cortex.yaml
index 3a57de2..bf5e147 100644
--- a/development/tsdb-blocks-storage-s3/config/cortex.yaml
+++ b/development/tsdb-blocks-storage-s3/config/cortex.yaml
@@ -70,9 +70,19 @@ blocks_storage:
 ruler:
   enable_api: true
   storage:
-    type: configdb
-    configdb:
-      configs_api_url: http://configstore:80/
+    type: s3
+    s3:
+      bucketnames: cortex-ruler
+      s3forcepathstyle: true
+      s3: http://cortex:supersecret@minio.:9000
+  enable_sharding: true
+  ring:
+    heartbeat_period:   5s
+    heartbeat_timeout:  15s
+    kvstore:
+      store: consul
+      consul:
+        host: consul:8500
 
 alertmanager:
   enable_api: true
@@ -91,6 +101,8 @@ compactor:
   data_dir:            /tmp/cortex-compactor
   consistency_delay:   1m
   sharding_enabled:    true
+  cleanup_interval:    1m
+  tenant_cleanup_delay: 1m
   sharding_ring:
     kvstore:
       store: consul
@@ -108,8 +120,15 @@ store_gateway:
       consul:
         host: consul:8500
 
+frontend:
+  query_stats_enabled: true
+
 frontend_worker:
   frontend_address: "query-frontend:9007"
+  match_max_concurrent: true
+
+  # By setting scheduler_address, querier worker would use scheduler instead of frontend.
+  # scheduler_address: "query-scheduler:9012"
 
 query_range:
   split_queries_by_interval: 24h
@@ -117,3 +136,6 @@ query_range:
 limits:
   # Limit max query time range to 31d
   max_query_length: 744h
+
+runtime_config:
+  file: ./config/runtime.yaml
diff --git a/development/tsdb-blocks-storage-s3/config/grafana-agent.yaml b/development/tsdb-blocks-storage-s3/config/grafana-agent.yaml
index 9b62fdf..164b409 100644
--- a/development/tsdb-blocks-storage-s3/config/grafana-agent.yaml
+++ b/development/tsdb-blocks-storage-s3/config/grafana-agent.yaml
@@ -25,13 +25,13 @@ prometheus:
                 namespace: 'tsdb-blocks-storage-s3'
         - job_name: tsdb-blocks-storage-s3/querier
           static_configs:
-            - targets: ['querier:8004']
+            - targets: ['querier:8004', 'querier-with-scheduler:8013']
               labels:
                 cluster: 'docker-compose'
                 namespace: 'tsdb-blocks-storage-s3'
         - job_name: tsdb-blocks-storage-s3/ruler
           static_configs:
-            - targets: ['ruler:8005']
+            - targets: ['ruler-1:8021', 'ruler-2:8022']
               labels:
                 cluster: 'docker-compose'
                 namespace: 'tsdb-blocks-storage-s3'
@@ -43,7 +43,7 @@ prometheus:
                 namespace: 'tsdb-blocks-storage-s3'
         - job_name: tsdb-blocks-storage-s3/query-frontend
           static_configs:
-            - targets: ['query-frontend:8007']
+            - targets: ['query-frontend:8007', 'query-frontend-with-scheduler:8012']
               labels:
                 cluster: 'docker-compose'
                 namespace: 'tsdb-blocks-storage-s3'
@@ -53,6 +53,12 @@ prometheus:
               labels:
                 cluster: 'docker-compose'
                 namespace: 'tsdb-blocks-storage-s3'
+        - job_name: tsdb-blocks-storage-s3/query-scheduler
+          static_configs:
+            - targets: ['query-scheduler:8011']
+              labels:
+                cluster: 'docker-compose'
+                namespace: 'tsdb-blocks-storage-s3'
 
       remote_write:
         - url: http://distributor:8001/api/prom/push
diff --git a/development/tsdb-blocks-storage-s3/config/prometheus.yaml b/development/tsdb-blocks-storage-s3/config/prometheus.yaml
index ffd1c68..be12319 100644
--- a/development/tsdb-blocks-storage-s3/config/prometheus.yaml
+++ b/development/tsdb-blocks-storage-s3/config/prometheus.yaml
@@ -18,13 +18,13 @@ scrape_configs:
           namespace: 'tsdb-blocks-storage-s3'
   - job_name: tsdb-blocks-storage-s3/querier
     static_configs:
-      - targets: ['querier:8004']
+      - targets: ['querier:8004', 'query-frontend-with-scheduler:8013']
         labels:
           cluster: 'docker-compose'
           namespace: 'tsdb-blocks-storage-s3'
   - job_name: tsdb-blocks-storage-s3/ruler
     static_configs:
-      - targets: ['ruler:8005']
+      - targets: ['ruler-1:8021', 'ruler-2:8022']
         labels:
           cluster: 'docker-compose'
           namespace: 'tsdb-blocks-storage-s3'
@@ -36,7 +36,7 @@ scrape_configs:
           namespace: 'tsdb-blocks-storage-s3'
   - job_name: tsdb-blocks-storage-s3/query-frontend
     static_configs:
-      - targets: ['query-frontend:8007']
+      - targets: ['query-frontend:8007', 'query-frontend-with-scheduler:8012']
         labels:
           cluster: 'docker-compose'
           namespace: 'tsdb-blocks-storage-s3'
@@ -46,6 +46,12 @@ scrape_configs:
         labels:
           cluster: 'docker-compose'
           namespace: 'tsdb-blocks-storage-s3'
+  - job_name: tsdb-blocks-storage-s3/query-scheduler
+    static_configs:
+      - targets: ['query-scheduler:8011']
+        labels:
+          cluster: 'docker-compose'
+          namespace: 'tsdb-blocks-storage-s3'
 
 remote_write:
   - url: http://distributor:8001/api/prom/push
diff --git a/development/tsdb-blocks-storage-s3/config/runtime.yaml b/development/tsdb-blocks-storage-s3/config/runtime.yaml
new file mode 100644
index 0000000..475c274
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3/config/runtime.yaml
@@ -0,0 +1 @@
+# This file is left empty. It can be configured with overrides or other runtime config.
diff --git a/development/tsdb-blocks-storage-s3/docker-compose.yml b/development/tsdb-blocks-storage-s3/docker-compose.yml
index 9575fc4..87a4924 100644
--- a/development/tsdb-blocks-storage-s3/docker-compose.yml
+++ b/development/tsdb-blocks-storage-s3/docker-compose.yml
@@ -21,11 +21,6 @@ services:
   memcached:
     image: memcached:1.6
 
-  configstore:
-    image: nginx
-    volumes:
-      - .data-configstore:/usr/share/nginx/html/private:ro
-
   prometheus:
     image: prom/prometheus:v2.16.0
     command: ["--config.file=/etc/prometheus/prometheus.yaml"]
@@ -178,80 +173,187 @@ services:
     volumes:
       - ./config:/cortex/config
 
-  ruler:
+  compactor:
     build:
       context:    .
       dockerfile: dev.dockerfile
     image: cortex
-    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18005 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=ruler -server.http-listen-port=8005 -server.grpc-listen-port=9005"]
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18006 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=compactor -server.http-listen-port=8006 -server.grpc-listen-port=9006"]
     depends_on:
       - consul
       - minio
     environment:
       - JAEGER_AGENT_HOST=jaeger
       - JAEGER_AGENT_PORT=6831
-      - JAEGER_TAGS=app=ruler
+      - JAEGER_TAGS=app=compactor
       - JAEGER_SAMPLER_TYPE=const
       - JAEGER_SAMPLER_PARAM=1
     ports:
-      - 8005:8005
-      - 18005:18005
+      - 8006:8006
+      - 18006:18006
     volumes:
       - ./config:/cortex/config
 
-  compactor:
+  query-frontend:
     build:
       context:    .
       dockerfile: dev.dockerfile
     image: cortex
-    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18006 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=compactor -server.http-listen-port=8006 -server.grpc-listen-port=9006"]
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18007 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=query-frontend -server.http-listen-port=8007 -server.grpc-listen-port=9007 -store.max-query-length=8760h"]
     depends_on:
       - consul
       - minio
     environment:
       - JAEGER_AGENT_HOST=jaeger
       - JAEGER_AGENT_PORT=6831
-      - JAEGER_TAGS=app=compactor
+      - JAEGER_TAGS=app=query-frontend
       - JAEGER_SAMPLER_TYPE=const
       - JAEGER_SAMPLER_PARAM=1
     ports:
-      - 8006:8006
-      - 18006:18006
+      - 8007:8007
+      - 18007:18007
     volumes:
       - ./config:/cortex/config
 
-  query-frontend:
+  alertmanager:
     build:
       context:    .
       dockerfile: dev.dockerfile
     image: cortex
-    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18007 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=query-frontend -server.http-listen-port=8007 -server.grpc-listen-port=9007 -store.max-query-length=8760h"]
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18010 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=alertmanager -server.http-listen-port=8010 -server.grpc-listen-port=9010 -alertmanager.web.external-url=localhost:8010"]
+    depends_on:
+      - consul
+      - minio
+    ports:
+      - 8010:8010
+      - 18010:18010
+    volumes:
+      - ./config:/cortex/config
+
+  ruler-1:
+    build:
+      context:    .
+      dockerfile: dev.dockerfile
+    image: cortex
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18021 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=ruler -server.http-listen-port=8021 -server.grpc-listen-port=9021"]
     depends_on:
       - consul
       - minio
     environment:
       - JAEGER_AGENT_HOST=jaeger
       - JAEGER_AGENT_PORT=6831
-      - JAEGER_TAGS=app=query-frontend
+      - JAEGER_TAGS=app=ruler-1
       - JAEGER_SAMPLER_TYPE=const
       - JAEGER_SAMPLER_PARAM=1
     ports:
-      - 8007:8007
-      - 18007:18007
+      - 8021:8021
+      - 18021:18021
     volumes:
       - ./config:/cortex/config
 
-  alertmanager:
+  ruler-2:
     build:
       context:    .
       dockerfile: dev.dockerfile
     image: cortex
-    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18010 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=alertmanager -server.http-listen-port=8010 -server.grpc-listen-port=9010"]
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18022 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=ruler -server.http-listen-port=8022 -server.grpc-listen-port=9022"]
     depends_on:
       - consul
       - minio
+    environment:
+      - JAEGER_AGENT_HOST=jaeger
+      - JAEGER_AGENT_PORT=6831
+      - JAEGER_TAGS=app=ruler-2
+      - JAEGER_SAMPLER_TYPE=const
+      - JAEGER_SAMPLER_PARAM=1
     ports:
-      - 8010:8010
-      - 18010:18010
+      - 8022:8022
+      - 18022:18022
+    volumes:
+      - ./config:/cortex/config
+
+  query-scheduler:
+    build:
+      context:    .
+      dockerfile: dev.dockerfile
+    image: cortex
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18011 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=query-scheduler -server.http-listen-port=8011 -server.grpc-listen-port=9011 -store.max-query-length=8760h"]
+    depends_on:
+      - consul
+      - minio
+    environment:
+      - JAEGER_AGENT_HOST=jaeger
+      - JAEGER_AGENT_PORT=6831
+      - JAEGER_TAGS=app=query-scheduler
+      - JAEGER_SAMPLER_TYPE=const
+      - JAEGER_SAMPLER_PARAM=1
+    ports:
+      - 8011:8011
+      - 18011:18011
+    volumes:
+      - ./config:/cortex/config
+
+  # This frontend uses query-scheduler, activated by `-frontend.scheduler-address` option.
+  query-frontend-with-scheduler:
+    build:
+      context:    .
+      dockerfile: dev.dockerfile
+    image: cortex
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18012 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=query-frontend -server.http-listen-port=8012 -server.grpc-listen-port=9012 -store.max-query-length=8760h -frontend.scheduler-address=query-scheduler:9011"]
+    depends_on:
+      - consul
+      - minio
+    environment:
+      - JAEGER_AGENT_HOST=jaeger
+      - JAEGER_AGENT_PORT=6831
+      - JAEGER_TAGS=app=query-frontend2
+      - JAEGER_SAMPLER_TYPE=const
+      - JAEGER_SAMPLER_PARAM=1
+    ports:
+      - 8012:8012
+      - 18012:18012
+    volumes:
+      - ./config:/cortex/config
+
+  # This querier is connecting to query-scheduler, instead of query-frontend. This is achieved by setting -querier.scheduler-address="..."
+  querier-with-scheduler:
+    build:
+      context:    .
+      dockerfile: dev.dockerfile
+    image: cortex
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18013 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=querier -server.http-listen-port=8013 -server.grpc-listen-port=9013 -querier.scheduler-address=query-scheduler:9011 -querier.frontend-address="]
+    depends_on:
+      - consul
+      - minio
+    environment:
+      - JAEGER_AGENT_HOST=jaeger
+      - JAEGER_AGENT_PORT=6831
+      - JAEGER_TAGS=app=querier-scheduler
+      - JAEGER_SAMPLER_TYPE=const
+      - JAEGER_SAMPLER_PARAM=1
+    ports:
+      - 8013:8013
+      - 18013:18013
+    volumes:
+      - ./config:/cortex/config
+
+  purger:
+    build:
+      context:    .
+      dockerfile: dev.dockerfile
+    image: cortex
+    command: ["sh", "-c", "sleep 3 && exec ./dlv exec ./cortex --listen=:18014 --headless=true --api-version=2 --accept-multiclient --continue -- -config.file=./config/cortex.yaml -target=purger -server.http-listen-port=8014 -server.grpc-listen-port=9014"]
+    depends_on:
+      - consul
+      - minio
+    environment:
+      - JAEGER_AGENT_HOST=jaeger
+      - JAEGER_AGENT_PORT=6831
+      - JAEGER_TAGS=app=querier-scheduler
+      - JAEGER_SAMPLER_TYPE=const
+      - JAEGER_SAMPLER_PARAM=1
+    ports:
+      - 8014:8014
+      - 18014:18014
     volumes:
       - ./config:/cortex/config
diff --git a/development/tsdb-blocks-storage-s3/goland/TSDB Query-frontend (using scheduler).run.xml b/development/tsdb-blocks-storage-s3/goland/TSDB Query-frontend (using scheduler).run.xml
new file mode 100644
index 0000000..c74d201
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3/goland/TSDB Query-frontend (using scheduler).run.xml
@@ -0,0 +1,6 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="TSDB Query-frontend (using scheduler)" type="GoRemoteDebugConfigurationType" factoryName="Go Remote" port="18012">
+    <option name="disconnectOption" value="ASK" />
+    <method v="2" />
+  </configuration>
+</component>
\ No newline at end of file
diff --git a/development/tsdb-blocks-storage-s3/goland/TSDB Query-scheduler.run.xml b/development/tsdb-blocks-storage-s3/goland/TSDB Query-scheduler.run.xml
new file mode 100644
index 0000000..932cce6
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3/goland/TSDB Query-scheduler.run.xml
@@ -0,0 +1,6 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="TSDB Query-scheduler" type="GoRemoteDebugConfigurationType" factoryName="Go Remote" port="18011">
+    <option name="disconnectOption" value="ASK" />
+    <method v="2" />
+  </configuration>
+</component>
\ No newline at end of file
diff --git a/development/tsdb-blocks-storage-s3/goland/ruler-1.run.xml b/development/tsdb-blocks-storage-s3/goland/ruler-1.run.xml
new file mode 100644
index 0000000..d5ed8e7
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3/goland/ruler-1.run.xml
@@ -0,0 +1,5 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="TSDB Ruler-1" type="GoRemoteDebugConfigurationType" factoryName="Go Remote" port="18021">
+    <method v="2" />
+  </configuration>
+</component>
\ No newline at end of file
diff --git a/development/tsdb-blocks-storage-s3/goland/ruler-2.run.xml b/development/tsdb-blocks-storage-s3/goland/ruler-2.run.xml
new file mode 100644
index 0000000..44f79aa
--- /dev/null
+++ b/development/tsdb-blocks-storage-s3/goland/ruler-2.run.xml
@@ -0,0 +1,5 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="TSDB Ruler-2" type="GoRemoteDebugConfigurationType" factoryName="Go Remote" port="18022">
+    <method v="2" />
+  </configuration>
+</component>
\ No newline at end of file
diff --git a/development/tsdb-blocks-storage-swift-single-binary/.data-cortex-1/.gitignore b/development/tsdb-blocks-storage-swift-single-binary/.data-cortex-1/.gitignore
new file mode 100644
index 0000000..d6b7ef3
--- /dev/null
+++ b/development/tsdb-blocks-storage-swift-single-binary/.data-cortex-1/.gitignore
@@ -0,0 +1,2 @@
+*
+!.gitignore
diff --git a/development/tsdb-blocks-storage-swift-single-binary/.data-cortex-2/.gitignore b/development/tsdb-blocks-storage-swift-single-binary/.data-cortex-2/.gitignore
new file mode 100644
index 0000000..d6b7ef3
--- /dev/null
+++ b/development/tsdb-blocks-storage-swift-single-binary/.data-cortex-2/.gitignore
@@ -0,0 +1,2 @@
+*
+!.gitignore
diff --git a/development/tsdb-blocks-storage-swift-single-binary/.dockerignore b/development/tsdb-blocks-storage-swift-single-binary/.dockerignore
new file mode 100644
index 0000000..18e736f
--- /dev/null
+++ b/development/tsdb-blocks-storage-swift-single-binary/.dockerignore
@@ -0,0 +1,4 @@
+.data-cortex-1
+.data-cortex-2
+.data-swift
+active-query-tracker
\ No newline at end of file
diff --git a/development/tsdb-blocks-storage-swift-single-binary/.gitignore b/development/tsdb-blocks-storage-swift-single-binary/.gitignore
new file mode 100644
index 0000000..06787dd
--- /dev/null
+++ b/development/tsdb-blocks-storage-swift-single-binary/.gitignore
@@ -0,0 +1,2 @@
+cortex
+.data-swift
\ No newline at end of file
diff --git a/development/tsdb-blocks-storage-swift-single-binary/compose-down.sh b/development/tsdb-blocks-storage-swift-single-binary/compose-down.sh
new file mode 100755
index 0000000..39f3730
--- /dev/null
+++ b/development/tsdb-blocks-storage-swift-single-binary/compose-down.sh
@@ -0,0 +1,5 @@
+#!/bin/bash
+
+SCRIPT_DIR=$(cd `dirname $0` && pwd)
+
+docker-compose -f ${SCRIPT_DIR}/docker-compose.yml down
diff --git a/development/tsdb-blocks-storage-swift-single-binary/compose-up.sh b/development/tsdb-blocks-storage-swift-single-binary/compose-up.sh
new file mode 100755
index 0000000..d42350b
--- /dev/null
+++ b/development/tsdb-blocks-storage-swift-single-binary/compose-up.sh
@@ -0,0 +1,7 @@
+#!/bin/bash
+
+SCRIPT_DIR=$(cd `dirname $0` && pwd)
+
+CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o ${SCRIPT_DIR}/cortex ${SCRIPT_DIR}/../../cmd/cortex && \
+docker-compose -f ${SCRIPT_DIR}/docker-compose.yml build cortex-1 && \
+docker-compose -f ${SCRIPT_DIR}/docker-compose.yml up $@
diff --git a/development/tsdb-blocks-storage-swift-single-binary/config/cortex.yaml b/development/tsdb-blocks-storage-swift-single-binary/config/cortex.yaml
new file mode 100644
index 0000000..e1d52fc
--- /dev/null
+++ b/development/tsdb-blocks-storage-swift-single-binary/config/cortex.yaml
@@ -0,0 +1,84 @@
+auth_enabled: false
+
+distributor:
+  shard_by_all_labels: true
+  pool:
+    health_check_ingesters: true
+
+ingester_client:
+  grpc_client_config:
+    # Configure the client to allow messages up to 100MB.
+    max_recv_msg_size: 104857600
+    max_send_msg_size: 104857600
+    grpc_compression: gzip
+
+ingester:
+  lifecycler:
+    # We want to start immediately.
+    join_after: 0
+    final_sleep: 0s
+    num_tokens: 512
+
+    ring:
+      kvstore:
+        store: consul
+        consul:
+          host: localhost:8500
+      replication_factor: 1
+
+querier:
+  query_ingesters_within: 3h
+
+store_gateway:
+  sharding_enabled: true
+  sharding_ring:
+    replication_factor: 1
+    kvstore:
+      store: consul
+      consul:
+        host: localhost:8500
+
+blocks_storage:
+  backend: swift
+
+  tsdb:
+    dir: /data/cortex-tsdb-ingester
+    ship_interval: 1m
+    block_ranges_period: [ 2h ]
+    retention_period: 3h
+
+  bucket_store:
+    sync_dir: /data/cortex-tsdb-querier
+
+  swift:
+    auth_url:          http://localhost:5000/v2.0
+    username:          admin
+    password:          s3cr3t
+    project_name:      admin
+    region_name:       RegionOne
+    container_name:    cortex-tsdb
+
+storage:
+  engine: blocks
+
+ruler:
+  enable_api: true
+  enable_sharding: true
+  poll_interval: 2s
+  storage:
+    type: swift
+    swift:
+      auth_url:          http://localhost:5000/v2.0
+      username:          admin
+      password:          s3cr3t
+      project_name:      admin
+      region_name:       RegionOne
+      container_name: cortex-rules
+  ring:
+    kvstore:
+      store: consul
+      consul:
+        host: localhost:8500
+
+runtime_config:
+  file: ./config/runtime.yaml
diff --git a/development/tsdb-blocks-storage-swift-single-binary/config/grafana-agent.yaml b/development/tsdb-blocks-storage-swift-single-binary/config/grafana-agent.yaml
new file mode 100644
index 0000000..9ae002a
--- /dev/null
+++ b/development/tsdb-blocks-storage-swift-single-binary/config/grafana-agent.yaml
@@ -0,0 +1,26 @@
+server:
+  log_level: debug
+  http_listen_port: 9091
+
+prometheus:
+  global:
+    scrape_interval: 5s
+    external_labels:
+      scraped_by: grafana-agent
+  configs:
+    - name: local
+      host_filter: false
+      scrape_configs:
+        - job_name: cortex-1
+          static_configs:
+            - targets: ['localhost:8001']
+              labels:
+                container: 'cortex-1'
+        - job_name: cortex-2
+          static_configs:
+            - targets: ['localhost:8002']
+              labels:
+                container: 'cortex-2'
+
+      remote_write:
+        - url: http://localhost:8001/api/prom/push
diff --git a/development/tsdb-blocks-storage-swift-single-binary/config/prometheus.yaml b/development/tsdb-blocks-storage-swift-single-binary/config/prometheus.yaml
new file mode 100644
index 0000000..f650c3a
--- /dev/null
+++ b/development/tsdb-blocks-storage-swift-single-binary/config/prometheus.yaml
@@ -0,0 +1,19 @@
+global:
+  scrape_interval: 5s
+  external_labels:
+    scraped_by: prometheus
+
+scrape_configs:
+  - job_name: cortex-1
+    static_configs:
+      - targets: ['localhost:8001']
+        labels:
+          container: 'cortex-1'
+  - job_name: cortex-2
+    static_configs:
+      - targets: ['localhost:8002']
+        labels:
+          container: 'cortex-2'
+
+remote_write:
+  - url: http://localhost:8001/api/prom/push
diff --git a/development/tsdb-blocks-storage-swift-single-binary/config/runtime.yaml b/development/tsdb-blocks-storage-swift-single-binary/config/runtime.yaml
new file mode 100644
index 0000000..475c274
--- /dev/null
+++ b/development/tsdb-blocks-storage-swift-single-binary/config/runtime.yaml
@@ -0,0 +1 @@
+# This file is left empty. It can be configured with overrides or other runtime config.
diff --git a/development/tsdb-blocks-storage-swift-single-binary/dev.dockerfile b/development/tsdb-blocks-storage-swift-single-binary/dev.dockerfile
new file mode 100644
index 0000000..8947594
--- /dev/null
+++ b/development/tsdb-blocks-storage-swift-single-binary/dev.dockerfile
@@ -0,0 +1,5 @@
+FROM alpine:3.12
+
+RUN     mkdir /cortex
+WORKDIR /cortex
+ADD     ./cortex ./
diff --git a/development/tsdb-blocks-storage-swift-single-binary/docker-compose.yml b/development/tsdb-blocks-storage-swift-single-binary/docker-compose.yml
new file mode 100644
index 0000000..ef28014
--- /dev/null
+++ b/development/tsdb-blocks-storage-swift-single-binary/docker-compose.yml
@@ -0,0 +1,100 @@
+version: '3.4'
+services:
+
+  consul:
+    image: consul
+    command: [ "agent", "-dev" ,"-client=0.0.0.0", "-log-level=info" ]
+    ports:
+      - 8500:8500
+
+  swift:
+    image: beaukode/docker-swift-onlyone-authv2-keystone
+    volumes:
+      - .data-swift:/srv:delegated
+    ports:
+      - 5000:5000
+      - 5001:5001
+      - 8080:8080
+      - 35357:35357
+
+  swift-create-container:
+    network_mode: host
+    image: theflockers/swiftclient
+    environment:
+      - OS_USERNAME=admin
+      - OS_PASSWORD=s3cr3t
+      - OS_TENANT_NAME=admin
+      - OS_AUTH_URL=http://localhost:5000/v2.0
+      - OS_REGION_NAME=RegionOne
+    command: ["sh", "-c", "sleep 30 && swift post cortex-rules && \
+                            swift post cortex-tsdb && swift list"]
+
+  prometheus:
+    network_mode: host
+    image: prom/prometheus:v2.16.0
+    command: ["--config.file=/etc/prometheus/prometheus.yaml"]
+    volumes:
+      - ./config:/etc/prometheus
+    ports:
+      - 9090:9090
+
+  # Scrape the metrics also with the Grafana agent (useful to test metadata ingestion
+  # until metadata remote write is not supported by Prometheus).
+  grafana-agent:
+    network_mode: host
+    image: grafana/agent:v0.2.0
+    command: ["-config.file=/etc/agent-config/grafana-agent.yaml", "-prometheus.wal-directory=/tmp"]
+    volumes:
+      - ./config:/etc/agent-config
+    ports:
+      - 9091:9091
+
+  jaeger:
+    image: jaegertracing/all-in-one
+    ports:
+      - 16686:16686
+      - "14268"
+
+  cortex-1:
+    network_mode: host
+    build:
+      context:    .
+      dockerfile: dev.dockerfile
+    image: cortex
+    command: ["sh", "-c", "sleep 40 && exec ./cortex -config.file=./config/cortex.yaml -target=all -server.http-listen-port=8001 -server.grpc-listen-port=9001"]
+    depends_on:
+      - consul
+      - swift
+    environment:
+      - JAEGER_AGENT_HOST=jaeger
+      - JAEGER_AGENT_PORT=6831
+      - JAEGER_TAGS=app=cortex-1
+      - JAEGER_SAMPLER_TYPE=const
+      - JAEGER_SAMPLER_PARAM=1
+    ports:
+      - 8001:8001
+    volumes:
+      - ./config:/cortex/config
+      - .data-cortex-1:/data:delegated
+
+  cortex-2:
+    network_mode: host
+    build:
+      context:    .
+      dockerfile: dev.dockerfile
+    image: cortex
+    command: ["sh", "-c", "sleep 40 && exec ./cortex -config.file=./config/cortex.yaml -target=all -server.http-listen-port=8002 -server.grpc-listen-port=9002"]
+    depends_on:
+      - consul
+      - swift
+    environment:
+      - JAEGER_AGENT_HOST=jaeger
+      - JAEGER_AGENT_PORT=6831
+      - JAEGER_TAGS=app=cortex-2
+      - JAEGER_SAMPLER_TYPE=const
+      - JAEGER_SAMPLER_PARAM=1
+    ports:
+      - 8002:8002
+    volumes:
+      - ./config:/cortex/config
+      - .data-cortex-2:/data:delegated
diff --git a/docs/_index.md b/docs/_index.md
index 3cf5c5d..28de70d 100644
--- a/docs/_index.md
+++ b/docs/_index.md
@@ -8,7 +8,7 @@ menu:
 ---
 <p align="center"><img width="200px" src="https://cncf-branding.netlify.com/img/projects/cortex/stacked/color/cortex-stacked-color.png" alt="Cortex Logo"></p>
 
-[![Circle CI](https://circleci.com/gh/cortexproject/cortex/tree/master.svg?style=shield)](https://circleci.com/gh/cortexproject/cortex/tree/master)
+[![CI](https://github.com/cortexproject/cortex/workflows/ci/badge.svg)](https://github.com/cortexproject/cortex/actions)
 [![GoDoc](https://godoc.org/github.com/cortexproject/cortex?status.svg)](https://godoc.org/github.com/cortexproject/cortex)
 <a href="https://goreportcard.com/report/github.com/cortexproject/cortex"><img src="https://goreportcard.com/badge/github.com/cortexproject/cortex" alt="Go Report Card" /></a>
 <a href="https://cloud-native.slack.com/messages/cortex/"><img src="https://img.shields.io/badge/join%20slack-%23cortex-brightgreen.svg" alt="Slack" /></a>
@@ -28,20 +28,41 @@ Cortex is primarily used as a [remote write](https://prometheus.io/docs/operatin
 
 ## Documentation
 
-Read the [getting started guide](getting-started/) if you're new to the
+Read the [getting started guide](getting-started/_index.md) if you're new to the
 project. Before deploying Cortex with a permanent storage backend you
 should read:
 
 1. [An overview of Cortex's architecture](architecture.md)
-1. [A guide to running Cortex](production/running.md)
-1. [Information regarding configuring Cortex](configuration/arguments.md)
+1. [A guide to running Cortex chunks storage](guides/running-chunks-storage-in-production.md)
+1. [Information regarding configuring Cortex](configuration/_index.md)
 
 For a guide to contributing to Cortex, see the [contributor guidelines](contributing/).
 
 ## Further reading
 
-To learn more about Cortex, consult the following documents & talks:
+To learn more about Cortex, consult the following talks and articles.
 
+### Recent talks and articles
+
+- Dec 2020 blog post "[How AWS and Grafana Labs are scaling Cortex for the cloud](https://aws.amazon.com/blogs/opensource/how-aws-and-grafana-labs-are-scaling-cortex-for-the-cloud/)
+- Oct 2020 blog post "[How to switch Cortex from chunks to blocks storage (and why you won’t look back)](https://grafana.com/blog/2020/10/19/how-to-switch-cortex-from-chunks-to-blocks-storage-and-why-you-wont-look-back/)"
+- Oct 2020 blog post "[Now GA: Cortex blocks storage for running Prometheus at scale with reduced operational complexity](https://grafana.com/blog/2020/10/06/now-ga-cortex-blocks-storage-for-running-prometheus-at-scale-with-reduced-operational-complexity/)"
+- Sep 2020 blog post "[A Tale of Tail Latencies](https://www.weave.works/blog/a-tale-of-tail-latencies)"
+- Sep 2020 KubeCon talk "Scaling Prometheus: How We Got Some Thanos Into Cortex" ([video](https://www.youtube.com/watch?v=Z5OJzRogAS4), [slides](https://static.sched.com/hosted_files/kccnceu20/ec/2020-08%20-%20KubeCon%20EU%20-%20Cortex%20blocks%20storage.pdf))
+- Aug 2020 blog post "[Scaling Prometheus: How we’re pushing Cortex blocks storage to its limit and beyond](https://grafana.com/blog/2020/08/12/scaling-prometheus-how-were-pushing-cortex-blocks-storage-to-its-limit-and-beyond/)"
+- Jul 2020 blog post "[How blocks storage in Cortex reduces operational complexity for running Prometheus at massive scale](https://grafana.com/blog/2020/07/29/how-blocks-storage-in-cortex-reduces-operational-complexity-for-running-prometheus-at-massive-scale/)"
+- Jul 2020 PromCon talk "Sharing is Caring: Leveraging Open Source to Improve Cortex & Thanos" ([video](https://www.youtube.com/watch?v=2oTLouUvsac), [slides](https://docs.google.com/presentation/d/1OuKYD7-k9Grb7unppYycdmVGWN0Bo0UwdJRySOoPdpg/edit))
+- Mar 2020 blog post "[Cortex: Zone Aware Replication](https://kenhaines.net/cortex-zone-aware-replication/)"
+- Mar 2020 blog post "[How we're using gossip to improve Cortex and Loki availability](https://grafana.com/blog/2020/03/25/how-were-using-gossip-to-improve-cortex-and-loki-availability/)"
+- Jan 2020 blog post "[The Future of Cortex: Into the Next Decade][future-of-cortex-blog]"
+
+[future-of-cortex-blog]: https://grafana.com/blog/2020/01/21/the-future-of-cortex-into-the-next-decade/
+
+### Previous talks and articles
+
+- Nov 2019 KubeCon talks "[Cortex 101: Horizontally Scalable Long Term Storage for Prometheus][kubecon-cortex-101]" ([video][kubecon-cortex-101-video], [slides][kubecon-cortex-101-slides]), "[Configuring Cortex for Max
+Performance][kubecon-cortex-201]" ([video][kubecon-cortex-201-video], [slides][kubecon-cortex-201-slides], [write up][kubecon-cortex-201-writeup]) and "[Blazin’ Fast PromQL][kubecon-blazin]" ([slides][kubecon-blazin-slides], [video][kubecon-blazin-video], [write up][kubecon-blazin-writeup])
+- Nov 2019 PromCon talk "[Two Households, Both Alike in Dignity: Cortex and Thanos][promcon-two-households]" ([video][promcon-two-households-video], [slides][promcon-two-households-slides], [write up][promcon-two-households-writeup])
 - May 2019 KubeCon talks; "[Cortex: Intro][kubecon-cortex-intro]" ([video][kubecon-cortex-intro-video], [slides][kubecon-cortex-intro-slides], [blog post][kubecon-cortex-intro-blog]) and "[Cortex: Deep Dive][kubecon-cortex-deepdive]" ([video][kubecon-cortex-deepdive-video], [slides][kubecon-cortex-deepdive-slides])
 - Feb 2019 blog post & podcast; "[Prometheus Scalability with Bryan Boreham][prometheus-scalability]" ([podcast][prometheus-scalability-podcast])
 - Feb 2019 blog post; "[How Aspen Mesh Runs Cortex in Production][aspen-mesh-2019]"
@@ -58,6 +79,21 @@ To learn more about Cortex, consult the following documents & talks:
 - Aug 2016 PromCon talk; "Project Frankenstein: Multitenant, Scale-Out Prometheus": ([video][promcon-2016-video], [slides][promcon-2016-slides])
 - Jun 2016 design document; "[Project Frankenstein: A Multi Tenant, Scale Out Prometheus](http://goo.gl/prdUYV)"
 
+[kubecon-cortex-101]: https://kccncna19.sched.com/event/UaiH/cortex-101-horizontally-scalable-long-term-storage-for-prometheus-chris-marchbanks-splunk
+[kubecon-cortex-101-video]: https://www.youtube.com/watch?v=f8GmbH0U_kI
+[kubecon-cortex-101-slides]: https://static.sched.com/hosted_files/kccncna19/92/cortex_101.pdf
+[kubecon-cortex-201]: https://kccncna19.sched.com/event/UagC/performance-tuning-and-day-2-operations-goutham-veeramachaneni-grafana-labs
+[kubecon-cortex-201-slides]: https://static.sched.com/hosted_files/kccncna19/87/Taming%20Cortex_%20Configuring%20for%20maximum%20performance%281%29.pdf
+[kubecon-cortex-201-video]: https://www.youtube.com/watch?v=VuE5aDHDexU
+[kubecon-cortex-201-writeup]: https://grafana.com/blog/2019/12/02/kubecon-recap-configuring-cortex-for-maximum-performance-at-scale/
+[kubecon-blazin]: https://kccncna19.sched.com/event/UaWT/blazin-fast-promql-tom-wilkie-grafana-labs
+[kubecon-blazin-slides]: https://static.sched.com/hosted_files/kccncna19/0b/2019-11%20Blazin%27%20Fast%20PromQL.pdf
+[kubecon-blazin-video]: https://www.youtube.com/watch?v=yYgdZyeBOck
+[kubecon-blazin-writeup]: https://grafana.com/blog/2019/09/19/how-to-get-blazin-fast-promql/
+[promcon-two-households]: https://promcon.io/2019-munich/talks/two-households-both-alike-in-dignity-cortex-and-thanos/
+[promcon-two-households-video]: https://www.youtube.com/watch?v=KmJnmd3K3Ws&feature=youtu.be
+[promcon-two-households-slides]: https://promcon.io/2019-munich/slides/two-households-both-alike-in-dignity-cortex-and-thanos.pdf
+[promcon-two-households-writeup]: https://grafana.com/blog/2019/11/21/promcon-recap-two-households-both-alike-in-dignity-cortex-and-thanos/
 [kubecon-cortex-intro]: https://kccnceu19.sched.com/event/MPhX/intro-cortex-tom-wilkie-grafana-labs-bryan-boreham-weaveworks
 [kubecon-cortex-intro-video]: https://www.youtube.com/watch?v=_7Wnta-3-W0
 [kubecon-cortex-intro-slides]: https://static.sched.com/hosted_files/kccnceu19/af/Cortex%20Intro%20KubeCon%20EU%202019.pdf
@@ -120,3 +156,8 @@ in the [Weave Cloud documentation](https://www.weave.works/docs/cloud/latest/ove
 To use Cortex as part of Grafana Cloud, sign up for [Grafana Cloud](https://grafana.com/cloud)
 by clicking "Log In" in the top right and then "Sign Up Now".  Cortex is included
 as part of the Starter and Basic Hosted Grafana plans.
+
+### Amazon Managed Service for Prometheus (AMP)
+[Amazon Managed Service for Prometheus (AMP)](https://aws.amazon.com/prometheus/) is a Prometheus-compatible monitoring service that makes it easy to monitor containerized applications at scale. It is a highly available, secure, and managed monitoring for your containers. Get started [here](https://console.aws.amazon.com/prometheus/home). To learn more about the AMP, reference our [documentation](https://docs.aws.amazon.com/prometheus/latest/userguide/what-is-Amazon-Managed-Service-Prometheus.html) and [Getting Started with AMP blog](https://aws.amazon.com/blogs/mt/getting-started-amazon-managed-service-for-prometheus/).
+
+
diff --git a/docs/api/_index.md b/docs/api/_index.md
index 6d8783d..1cc8673 100644
--- a/docs/api/_index.md
+++ b/docs/api/_index.md
@@ -1,7 +1,7 @@
 ---
 title: "HTTP API"
 linkTitle: "HTTP API"
-weight: 5
+weight: 7
 slug: api
 menu:
 no_section_index_title: true
@@ -19,9 +19,12 @@ For the sake of clarity, in this document we have grouped API endpoints by servi
 | --- | ------- | -------- |
 | [Index page](#index-page) | _All services_ | `GET /` |
 | [Configuration](#configuration) | _All services_ | `GET /config` |
+| [Runtime Configuration](#runtime-configuration) | _All services_ | `GET /runtime_config` |
 | [Services status](#services-status) | _All services_ | `GET /services` |
 | [Readiness probe](#readiness-probe) | _All services_ | `GET /ready` |
 | [Metrics](#metrics) | _All services_ | `GET /metrics` |
+| [Pprof](#pprof) | _All services_ | `GET /debug/pprof` |
+| [Fgprof](#fgprof) | _All services_ | `GET /debug/fgprof` |
 | [Remote write](#remote-write) | Distributor | `POST /api/v1/push` |
 | [Tenants stats](#tenants-stats) | Distributor | `GET /distributor/all_user_stats` |
 | [HA tracker status](#ha-tracker-status) | Distributor | `GET /distributor/ha_tracker` |
@@ -47,6 +50,7 @@ For the sake of clarity, in this document we have grouped API endpoints by servi
 | [Delete rule group](#delete-rule-group) | Ruler | `DELETE /api/v1/rules/{namespace}/{groupName}` |
 | [Delete namespace](#delete-namespace) | Ruler | `DELETE /api/v1/rules/{namespace}` |
 | [Alertmanager status](#alertmanager-status) | Alertmanager | `GET /multitenant_alertmanager/status` |
+| [Alertmanager ring status](#alertmanager-ring-status) | Alertmanager | `GET /multitenant_alertmanager/ring` |
 | [Alertmanager UI](#alertmanager-ui) | Alertmanager | `GET /<alertmanager-http-prefix>` |
 | [Get Alertmanager configuration](#get-alertmanager-configuration) | Alertmanager | `GET /api/v1/alerts` |
 | [Set Alertmanager configuration](#set-alertmanager-configuration) | Alertmanager | `POST /api/v1/alerts` |
@@ -54,6 +58,8 @@ For the sake of clarity, in this document we have grouped API endpoints by servi
 | [Delete series](#delete-series) | Purger | `PUT,POST <prometheus-http-prefix>/api/v1/admin/tsdb/delete_series` |
 | [List delete requests](#list-delete-requests) | Purger | `GET <prometheus-http-prefix>/api/v1/admin/tsdb/delete_series` |
 | [Cancel delete request](#cancel-delete-request) | Purger | `PUT,POST <prometheus-http-prefix>/api/v1/admin/tsdb/cancel_delete_request` |
+| [Tenant delete request](#tenant-delete-request) | Purger | `POST /purger/delete_tenant` |
+| [Tenant delete status](#tenant-delete-status) | Purger | `GET /purger/delete_tenant_status` |
 | [Store-gateway ring status](#store-gateway-ring-status) | Store-gateway | `GET /store-gateway/ring` |
 | [Compactor ring status](#compactor-ring-status) | Compactor | `GET /compactor/ring` |
 | [Get rule files](#get-rule-files) | Configs API (deprecated) | `GET /api/prom/configs/rules` |
@@ -83,7 +89,7 @@ When multi-tenancy is enabled, endpoints requiring authentication are expected t
 
 Multi-tenancy can be enabled/disabled via the CLI flag `-auth.enabled` or its respective YAML config option.
 
-_For more information, please refer to the dedicated [Authentication and Authorisation](../production/auth.md) guide._
+_For more information, please refer to the dedicated [Authentication and Authorisation](../guides/authentication-and-authorisation.md) guide._
 
 ## All services
 
@@ -105,6 +111,28 @@ GET /config
 
 Displays the configuration currently applied to Cortex (in YAML format), including default values and settings via CLI flags. Sensitive data is masked. Please be aware that the exported configuration **doesn't include the per-tenant overrides**.
 
+#### Different modes
+
+```
+GET /config?mode=diff
+```
+
+Displays the configuration currently applied to Cortex (in YAML format) as before, but containing only the values that differ from the  default values.
+
+```
+GET /config?mode=defaults
+```
+
+Displays the configuration using only the default values.
+
+### Runtime Configuration
+
+```
+GET /runtime_config
+```
+
+Displays the runtime configuration currently applied to Cortex (in YAML format), including default values. Please be aware that the endpoint will be only available if Cortex is configured with the `-runtime-config.file` option.
+
 ### Services status
 
 ```
@@ -129,6 +157,31 @@ GET /metrics
 
 Returns the metrics for the running Cortex service in the Prometheus exposition format.
 
+### Pprof
+
+```
+GET /debug/pprof/heap
+GET /debug/pprof/block
+GET /debug/pprof/profile
+GET /debug/pprof/trace
+GET /debug/pprof/goroutine
+GET /debug/pprof/mutex
+```
+
+Returns the runtime profiling data in the format expected by the pprof visualization tool. There are many things which can be profiled using this including heap, trace, goroutine, etc.
+
+_For more information, please check out the official documentation of [pprof](https://golang.org/pkg/net/http/pprof/)._
+
+### Fgprof
+
+```
+GET /debug/fgprof
+```
+
+Returns the sampling Go profiling data which allows you to analyze On-CPU as well as Off-CPU (e.g. I/O) time together.
+
+_For more information, please check out the official documentation of [fgprof](https://github.com/felixge/fgprof)._
+
 ## Distributor
 
 ### Remote write
@@ -170,6 +223,7 @@ GET /ha-tracker
 
 Displays a web page with the current status of the HA tracker, including the elected replica for each Prometheus HA cluster.
 
+
 ## Ingester
 
 ### Flush chunks / blocks
@@ -192,7 +246,7 @@ GET,POST /ingester/shutdown
 GET,POST /shutdown
 ```
 
-Flushes in-memory time series data from ingester to the long-term storage, and shuts down the ingester service. Notice that the other Cortex services are still running, and the operator (or any automation) is expected to terminate the process with a `SIGINT` / `SIGTERM` signal after the shutdown endpoint returns. In the meantime, `/ready` will not return 200.
+Flushes in-memory time series data from ingester to the long-term storage, and shuts down the ingester service. Notice that the other Cortex services are still running, and the operator (or any automation) is expected to terminate the process with a `SIGINT` / `SIGTERM` signal after the shutdown endpoint returns. In the meantime, `/ready` will not return 200. This endpoint will unregister the ingester from the ring even if `-ingester.unregister-on-shutdown` is disabled.
 
 _This API endpoint is usually used by scale down automations._
 
@@ -251,7 +305,7 @@ GET,POST <prometheus-http-prefix>/api/v1/series
 GET,POST <legacy-http-prefix>/api/v1/series
 ```
 
-Find series by label matchers. Differently than Prometheus and due to scalability and performances reasons, Cortex currently ignores the `start` and `end` request parameters and always fetches the series from in-memory data stored in the ingesters.
+Find series by label matchers. Differently than Prometheus and due to scalability and performances reasons, Cortex currently ignores the `start` and `end` request parameters and always fetches the series from in-memory data stored in the ingesters. There is experimental support to query the long-term store with the *blocks* storage engine when `-querier.query-store-for-labels-enabled` is set.
 
 _For more information, please check out the Prometheus [series endpoint](https://prometheus.io/docs/prometheus/latest/querying/api/#finding-series-by-label-matchers) documentation._
 
@@ -266,7 +320,7 @@ GET,POST <prometheus-http-prefix>/api/v1/labels
 GET,POST <legacy-http-prefix>/api/v1/labels
 ```
 
-Get label names of ingested series. Differently than Prometheus and due to scalability and performances reasons, Cortex currently ignores the `start` and `end` request parameters and always fetches the label names from in-memory data stored in the ingesters.
+Get label names of ingested series. Differently than Prometheus and due to scalability and performances reasons, Cortex currently ignores the `start` and `end` request parameters and always fetches the label names from in-memory data stored in the ingesters. There is experimental support to query the long-term store with the *blocks* storage engine when `-querier.query-store-for-labels-enabled` is set.
 
 _For more information, please check out the Prometheus [get label names](https://prometheus.io/docs/prometheus/latest/querying/api/#getting-label-names) documentation._
 
@@ -281,7 +335,7 @@ GET <prometheus-http-prefix>/api/v1/label/{name}/values
 GET <legacy-http-prefix>/api/v1/label/{name}/values
 ```
 
-Get label values for a given label name. Differently than Prometheus and due to scalability and performances reasons, Cortex currently ignores the `start` and `end` request parameters and always fetches the label values from in-memory data stored in the ingesters.
+Get label values for a given label name. Differently than Prometheus and due to scalability and performances reasons, Cortex currently ignores the `start` and `end` request parameters and always fetches the label values from in-memory data stored in the ingesters. There is experimental support to query the long-term store with the *blocks* storage engine when `-querier.query-store-for-labels-enabled` is set.
 
 _For more information, please check out the Prometheus [get label values](https://prometheus.io/docs/prometheus/latest/querying/api/#querying-label-values) documentation._
 
@@ -587,6 +641,14 @@ GET /status
 
 Displays a web page with the current status of the Alertmanager, including the Alertmanager cluster members.
 
+### Alertmanager ring status
+
+```
+GET /multitenant_alertmanager/ring
+```
+
+Displays a web page with the Alertmanager hash ring status, including the state, healthy and last heartbeat time of each Alertmanager instance.
+
 ### Alertmanager UI
 
 ```
@@ -639,6 +701,8 @@ alertmanager_config: |
   global:
     smtp_smarthost: 'localhost:25'
     smtp_from: '[e-mail]'
+  templates:
+    - 'default_template'
   route:
     receiver: example-email
   receivers:
@@ -710,6 +774,26 @@ Cancel a delete request while the request is still in the grace period (before t
 
 _Requires [authentication](#authentication)._
 
+### Tenant Delete Request
+
+```
+POST /purger/delete_tenant
+```
+
+Request deletion of ALL tenant data. Only works with blocks storage. Experimental.
+
+_Requires [authentication](#authentication)._
+
+### Tenant Delete Status
+
+```
+GET /purger/delete_tenant_status
+```
+
+Returns status of tenant deletion. Output format to be defined. Experimental.
+
+_Requires [authentication](#authentication)._
+
 ## Store-gateway
 
 ### Store-gateway ring status
@@ -764,7 +848,16 @@ The following schema is used both when retrieving the current configs from the A
 - **`config.rules_files`**<br />
   The contents of a rules file should be as described [here](http://prometheus.io/docs/prometheus/latest/configuration/recording_rules/), encoded as a single string to fit within the overall JSON payload.
 - **`config.template_files`**<br />
-  The contents of a template file should be as described [here](https://prometheus.io/docs/alerting/notification_examples/#defining-reusable-templates), encoded as a single string to fit within the overall JSON payload.
+  The contents of a template file should be as described [here](https://prometheus.io/docs/alerting/notification_examples/#defining-reusable-templates), encoded as a single string to fit within the overall JSON payload. These entries should match the `templates` entries in `alertmanager_config`. Example:
+  ```yaml
+  template_files:
+    myorg.tmpl: |
+      {{ define "__alertmanager" }}AlertManager{{ end }}
+      {{ define "__alertmanagerURL" }}{{ .ExternalURL }}/#/alerts?receiver={{ .Receiver | urlquery }}{{ end }}
+  alertmanager_config: |
+    templates:
+      - 'myorg.tmpl'
+  ```
 
 ### Get rule files
 
diff --git a/docs/architecture.md b/docs/architecture.md
index dcbe65d..c4cd232 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -44,11 +44,7 @@ For this reason, the chunks storage consists of:
   * [Google Cloud Storage](https://cloud.google.com/storage/)
   * [Microsoft Azure Storage](https://azure.microsoft.com/en-us/services/storage/)
 
-Internally, the access to the chunks storage relies on a unified interface called "chunks store". Unlike other Cortex components, the chunk store is not a separate service, but rather a library embedded in the services that need to access the long-term storage: [ingester](#ingester), [querier](#querier) and [ruler](#ruler).
-
-The chunk and index format are versioned, this allows Cortex operators to upgrade the cluster to take advantage of new features and improvements. This strategy enables changes in the storage format without requiring any downtime or complex procedures to rewrite the stored data. A set of schemas are used to map the version while reading and writing time series belonging to a specific period of time.
-
-The current schema recommendation is the **v9 schema** for most use cases and **v10 schema** if you expect to have very high cardinality metrics (v11 is still experimental). For more information about the schema, please check out the [Schema](configuration/schema-config-reference.md) documentation.
+For more information, please check out the [Chunks storage](./chunks-storage/_index.md) documentation.
 
 ### Blocks storage
 
@@ -61,10 +57,10 @@ The blocks storage doesn't require a dedicated storage backend for the index. Th
 * [Amazon S3](https://aws.amazon.com/s3)
 * [Google Cloud Storage](https://cloud.google.com/storage/)
 * [Microsoft Azure Storage](https://azure.microsoft.com/en-us/services/storage/)
-* [Local Filesystem](https://thanos.io/storage.md/#filesystem) (single node only)
 * [OpenStack Swift](https://wiki.openstack.org/wiki/Swift) (experimental)
+* [Local Filesystem](https://thanos.io/storage.md/#filesystem) (single node only)
 
-For more information, please check out the [Blocks storage](./blocks-storage/) documentation.
+For more information, please check out the [Blocks storage](./blocks-storage/_index.md) documentation.
 
 ## Services
 
@@ -110,7 +106,7 @@ The supported KV stores for the HA tracker are:
 
 Note: Memberlist is not supported. Memberlist-based KV store propagates updates using gossip, which is very slow for HA purposes: result is that different distributors may see different Prometheus server as elected HA replica, which is definitely not desirable.
 
-For more information, please refer to [config for sending HA pairs data to Cortex](production/ha-pair-handling.md) in the documentation.
+For more information, please refer to [config for sending HA pairs data to Cortex](guides/ha-pair-handling.md) in the documentation.
 
 #### Hashing
 
@@ -207,6 +203,13 @@ The query frontend internally performs some query adjustments and holds queries 
 
 Query frontends are **stateless**. However, due to how the internal queue works, it's recommended to run a few query frontend replicas to reap the benefit of fair scheduling. Two replicas should suffice in most cases.
 
+Flow of the query in the system when using query-frontend:
+
+1) Query is received by query frontend, which can optionally split it or serve from the cache.
+2) Query frontend stores the query into in-memory queue, where it waits for some querier to pick it up.
+3) Querier picks up the query, and executes it.
+4) Querier sends result back to query-frontend, which then forwards it to the client.
+
 #### Queueing
 
 The query frontend queuing mechanism is used to:
@@ -223,6 +226,24 @@ The query frontend splits multi-day queries into multiple single-day queries, ex
 
 The query frontend supports caching query results and reuses them on subsequent queries. If the cached results are incomplete, the query frontend calculates the required subqueries and executes them in parallel on downstream queriers. The query frontend can optionally align queries with their step parameter to improve the cacheability of the query results. The result cache is compatible with any cortex caching backend (currently memcached, redis, and an in-memory cache).
 
+### Query Scheduler
+
+Query Scheduler is an **optional** service that moves the internal queue from query frontend into separate component.
+This enables independent scaling of query frontends and number of queues (query scheduler).
+
+In order to use query scheduler, both query frontend and queriers must be configured with query scheduler address
+(using `-frontend.scheduler-address` and `-querier.scheduler-address` options respectively).
+
+Flow of the query in the system changes when using query scheduler:
+
+1) Query is received by query frontend, which can optionally split it or serve from the cache.
+2) Query frontend forwards the query to random query scheduler process.
+3) Query scheduler stores the query into in-memory queue, where it waits for some querier to pick it up.
+3) Querier picks up the query, and executes it.
+4) Querier sends result back to query-frontend, which then forwards it to the client.
+
+Query schedulers are **stateless**. It is recommended to run two replicas to make sure queries can still be serviced while one replica is restarting.
+
 ### Ruler
 
 The **ruler** is an **optional service** executing PromQL queries for recording rules and alerts. The ruler requires a database storing the recording rules and alerts for each tenant.
diff --git a/docs/blocks-storage/_index.md b/docs/blocks-storage/_index.md
index 124c887..e0541f4 100644
--- a/docs/blocks-storage/_index.md
+++ b/docs/blocks-storage/_index.md
@@ -1,7 +1,7 @@
 ---
 title: "Blocks Storage"
 linkTitle: "Blocks Storage"
-weight: 8
+weight: 3
 menu:
 ---
 
@@ -12,9 +12,10 @@ The supported backends for the blocks storage are:
 * [Amazon S3](https://aws.amazon.com/s3)
 * [Google Cloud Storage](https://cloud.google.com/storage/)
 * [Microsoft Azure Storage](https://azure.microsoft.com/en-us/services/storage/)
+* [OpenStack Swift](https://wiki.openstack.org/wiki/Swift) (experimental)
 * [Local Filesystem](https://thanos.io/storage.md/#filesystem) (single node only)
 
-_Internally, this storage engine is based on [Thanos](https://thanos.io), but no Thanos knowledge is required in order to run it._
+_Internally, some components are based on [Thanos](https://thanos.io), but no Thanos knowledge is required in order to run it._
 
 ## Architecture
 
@@ -28,9 +29,9 @@ When running the Cortex blocks storage, the Cortex architecture doesn't signific
 
 The **[store-gateway](./store-gateway.md)** is responsible to query blocks and is used by the [querier](./querier.md) at query time. The store-gateway is required when running the blocks storage.
 
-The **[compactor](./compactor.md)** is responsible to merge and deduplicate smaller blocks into larger ones, in order to reduce the number of blocks stored in the long-term storage for a given tenant and query them more efficiently. The compactor is optional but highly recommended.
+The **[compactor](./compactor.md)** is responsible to merge and deduplicate smaller blocks into larger ones, in order to reduce the number of blocks stored in the long-term storage for a given tenant and query them more efficiently. It also keeps the [bucket index](./bucket-index.md) updated and, for this reason, it's a required component.
 
-Finally, the **table-manager** is not used by the blocks storage.
+Finally, the [**table-manager**](../chunks-storage/table-manager.md) and the [**schema config**](../chunks-storage/schema-config.md) are **not used** by the blocks storage.
 
 ### The write path
 
@@ -44,7 +45,7 @@ In order to effectively use the **WAL** and being able to recover the in-memory 
 
 The series sharding and replication done by the distributor doesn't change based on the storage engine.
 
-It's important to note that - differently than the [chunks storage](../architecture.md#chunks-storage-default) - due to the replication factor N (typically 3), each time series is stored by N ingesters. Since each ingester writes its own block to the long-term storage, this leads a storage utilization N times more than the chunks storage. [Compactor](./compactor.md) solves this problem by merging blocks from multiple ingesters into a single block, and removing duplicated samples.
+It's important to note that - differently than the [chunks storage](../chunks-storage/_index.md) - due to the replication factor N (typically 3), each time series is stored by N ingesters. Since each ingester writes its own block to the long-term storage, this leads a storage utilization N times more than the chunks storage. [Compactor](./compactor.md) solves this problem by merging blocks from multiple ingesters into a single block, and removing duplicated samples. After blocks compaction, the storage utilization is significantly smaller compared to the chunks storage for the same exact series and samples.
 
 For more information, please refer to the following dedicated sections:
 
diff --git a/docs/blocks-storage/bucket-index.md b/docs/blocks-storage/bucket-index.md
new file mode 100644
index 0000000..67947d0
--- /dev/null
+++ b/docs/blocks-storage/bucket-index.md
@@ -0,0 +1,61 @@
+---
+title: "Bucket Index"
+linkTitle: "Bucket Index"
+weight: 5
+slug: bucket-index
+---
+
+The bucket index is a **per-tenant file containing the list of blocks and block deletion marks** in the storage. The bucket index itself is stored in the backend object storage, is periodically updated by the compactor, and used by queriers, store-gateways and rulers to discover blocks in the storage.
+
+The bucket index usage is **optional** and can be enabled via `-blocks-storage.bucket-store.bucket-index.enabled=true` (or its respective YAML config option).
+
+## Benefits
+
+The [querier](./querier.md), [store-gateway](./store-gateway.md) and ruler need to have an almost up-to-date view over the entire storage bucket, in order to find the right blocks to lookup at query time (querier) and load block's [index-header](./binary-index-header.md) (store-gateway). Because of this, they need to periodically scan the bucket to look for new blocks uploaded by ingester or compactor, and blocks deleted (or marked for deletion) by compactor.
+
+When the bucket index is enabled, the querier, store-gateway and ruler periodically look up the per-tenant bucket index instead of scanning the bucket via "list objects" operations. This brings few benefits:
+
+1. Reduced number of API calls to the object storage by querier and store-gateway
+2. No "list objects" storage API calls done by querier and store-gateway
+3. The [querier](./querier.md) is up and running immediately after the startup (no need to run an initial bucket scan)
+
+## Structure of the index
+
+The `bucket-index.json.gz` contains:
+
+- **`blocks`**<br />
+  List of complete blocks of a tenant, including blocks marked for deletion (partial blocks are excluded from the index).
+- **`block_deletion_marks`**<br />
+  List of block deletion marks.
+- **`updated_at`**<br />
+  Unix timestamp (seconds precision) of when the index has been updated (written in the storage) the last time.
+
+## How it gets updated
+
+The [compactor](./compactor.md) periodically scans the bucket and uploads an updated bucket index to the storage. The frequency at which the bucket index is updated can be configured via `-compactor.cleanup-interval`.
+
+Despite using the bucket index is optional, the index itself is built and updated by the compactor even if `-blocks-storage.bucket-store.bucket-index.enabled` has **not** been enabled. This is intentional, so that once a Cortex cluster operator decides to enable the bucket index in a live cluster, the bucket index for any tenant is already existing and query results consistency is guaranteed. The overhead introduced by keeping the bucket index updated is expected to be non significative.
+
+## How it's used by the querier
+
+At query time the [querier](./querier.md) and ruler check whether the bucket index for the tenant has already been loaded in memory. If not, the querier and ruler download it from the storage and cache it in memory.
+
+_Given it's a small file, lazy downloading it doesn't significantly impact on first query performances, but allows to get a querier up and running without pre-downloading every tenant's bucket index. Moreover, if the [metadata cache](./querier.md#metadata-cache) is enabled, the bucket index will be cached for a short time in a shared cache, reducing the actual latency and number of API calls to the object storage in case multiple queriers and rulers will fetch the same tenant's bucket index in a short time._
+
+![Querier - Bucket index](/images/blocks-storage/bucket-index-querier-workflow.png)
+<!-- Diagram source at https://docs.google.com/presentation/d/1bHp8_zcoWCYoNU2AhO2lSagQyuIrghkCncViSqn14cU/edit -->
+
+While in-memory, a background process will keep it **updated at periodic intervals**, so that subsequent queries from the same tenant to the same querier instance will use the cached (and periodically updated) bucket index. There are two config options involved:
+
+- `-blocks-storage.bucket-store.sync-interval`<br />
+  This option configures how frequently a cached bucket index should be refreshed.
+- `-blocks-storage.bucket-store.bucket-index.update-on-error-interval`<br />
+  If downloading a bucket index fails, the failure is cached for a short time in order to avoid hammering the backend storage. This option configures how frequently a bucket index, which previously failed to load, should be tried to load again.
+
+If a bucket index is unused for a long time (configurable via `-blocks-storage.bucket-store.bucket-index.idle-timeout`), e.g. because that querier instance is not receiving any query from the tenant, the querier will offload it, stopping to keep it updated at regular intervals. This is particularly for tenants which are resharded to different queriers when [shuffle sharding](../guides/shuffle-sharding.md) is enabled.
+
+Finally, at query time the querier and ruler check how old a bucket index is (based on its `updated_at`) and fail a query if its age is older than `-blocks-storage.bucket-store.bucket-index.max-stale-period`. This circuit breaker is used to ensure queriers and rulers will not return any partial query results due to a stale view over the long-term storage.
+
+## How it's used by the store-gateway
+
+The [store-gateway](./store-gateway.md), at startup and periodically, fetches the bucket index for each tenant belonging to their shard and uses it as the source of truth for the blocks (and deletion marks) in the storage. This removes the need to periodically scan the bucket to discover blocks belonging to their shard.
diff --git a/docs/blocks-storage/compactor.md b/docs/blocks-storage/compactor.md
index f4721b0..bcea40d 100644
--- a/docs/blocks-storage/compactor.md
+++ b/docs/blocks-storage/compactor.md
@@ -7,13 +7,16 @@ slug: compactor
 
 <!-- DO NOT EDIT THIS FILE - This file has been automatically generated from its .template -->
 
-The **compactor** is an optional service which compacts multiple blocks of a given tenant into a single optimized larger block. Running compactor is **highly recommended** to reduce storage costs (deduplication, index size reduction), and increase query speed (querying fewer blocks is faster).
+The **compactor** is an service which is responsible to:
+
+- Compact multiple blocks of a given tenant into a single optimized larger block. This helps to reduce storage costs (deduplication, index size reduction), and increase query speed (querying fewer blocks is faster).
+- Keep the per-tenant bucket index updated. The [bucket index](./bucket-index.md) is used by [queriers](./querier.md), [store-gateways](./store-gateway.md) and rulers to discover new blocks in the storage.
 
 The compactor is **stateless**.
 
-## How it works
+## How compaction works
 
-The compactor has two main benefits:
+The blocks compaction has two main benefits:
 
 1. Vertically compact blocks uploaded by all ingesters for the same time range
 2. Horizontally compact blocks with small time ranges into a single larger block
@@ -38,6 +41,14 @@ The compactor sharding is based on the Cortex [hash ring](../architecture.md#the
 
 This feature can be enabled via `-compactor.sharding-enabled=true` and requires the backend [hash ring](../architecture.md#the-hash-ring) to be configured via `-compactor.ring.*` flags (or their respective YAML config options).
 
+### Waiting for stable ring at startup
+
+In the event of a cluster cold start or scale up of 2+ compactor instances at the same time we may end up in a situation where each new compactor instance starts at a slightly different time and thus each one runs the first compaction based on a different state of the ring. This is not a critical condition, but may be inefficient, because multiple compactor replicas may start compacting the same tenant nearly at the same time.
+
+To reduce the likelihood this could happen, the compactor waits for a stable ring at startup. A ring is considered stable if no instance is added/removed to the ring for at least `-compactor.ring.wait-stability-min-duration`. If the ring keep getting changed after `-compactor.ring.wait-stability-max-duration`, the compactor will stop waiting for a stable ring and will proceed starting up normally.
+
+To disable this waiting logic, you can start the compactor with `-compactor.ring.wait-stability-min-duration=0`.
+
 ## Soft and hard blocks deletion
 
 When the compactor successfully compacts some source blocks into a larger block, source blocks are deleted from the storage. Blocks deletion is not immediate, but follows a two steps process:
@@ -105,8 +116,7 @@ compactor:
   # CLI flag: -compactor.compaction-interval
   [compaction_interval: <duration> | default = 1h]
 
-  # How many times to retry a failed compaction during a single compaction
-  # interval
+  # How many times to retry a failed compaction within a single compaction run.
   # CLI flag: -compactor.compaction-retries
   [compaction_retries: <int> | default = 3]
 
@@ -114,16 +124,48 @@ compactor:
   # CLI flag: -compactor.compaction-concurrency
   [compaction_concurrency: <int> | default = 1]
 
+  # How frequently compactor should run blocks cleanup and maintenance, as well
+  # as update the bucket index.
+  # CLI flag: -compactor.cleanup-interval
+  [cleanup_interval: <duration> | default = 15m]
+
+  # Max number of tenants for which blocks cleanup and maintenance should run
+  # concurrently.
+  # CLI flag: -compactor.cleanup-concurrency
+  [cleanup_concurrency: <int> | default = 20]
+
   # Time before a block marked for deletion is deleted from bucket. If not 0,
-  # blocks will be marked for deletion and compactor component will delete
-  # blocks marked for deletion from the bucket. If delete-delay is 0, blocks
-  # will be deleted straight away. Note that deleting blocks immediately can
-  # cause query failures, if store gateway still has the block loaded, or
-  # compactor is ignoring the deletion because it's compacting the block at the
-  # same time.
+  # blocks will be marked for deletion and compactor component will permanently
+  # delete blocks marked for deletion from the bucket. If 0, blocks will be
+  # deleted straight away. Note that deleting blocks immediately can cause query
+  # failures.
   # CLI flag: -compactor.deletion-delay
   [deletion_delay: <duration> | default = 12h]
 
+  # For tenants marked for deletion, this is time between deleting of last
+  # block, and doing final cleanup (marker files, debug files) of the tenant.
+  # CLI flag: -compactor.tenant-cleanup-delay
+  [tenant_cleanup_delay: <duration> | default = 6h]
+
+  # When enabled, at compactor startup the bucket will be scanned and all found
+  # deletion marks inside the block location will be copied to the markers
+  # global location too. This option can (and should) be safely disabled as soon
+  # as the compactor has successfully run at least once.
+  # CLI flag: -compactor.block-deletion-marks-migration-enabled
+  [block_deletion_marks_migration_enabled: <boolean> | default = true]
+
+  # Comma separated list of tenants that can be compacted. If specified, only
+  # these tenants will be compacted by compactor, otherwise all tenants can be
+  # compacted. Subject to sharding.
+  # CLI flag: -compactor.enabled-tenants
+  [enabled_tenants: <string> | default = ""]
+
+  # Comma separated list of tenants that cannot be compacted by this compactor.
+  # If specified, and compactor would normally pick given tenant for compaction
+  # (via -compactor.enabled-tenants or sharding), it will be ignored instead.
+  # CLI flag: -compactor.disabled-tenants
+  [disabled_tenants: <string> | default = ""]
+
   # Shard tenants across multiple compactor instances. Sharding is required if
   # you run multiple compactor instances, in order to coordinate compactions and
   # avoid race conditions leading to the same tenant blocks simultaneously
@@ -175,4 +217,17 @@ compactor:
     # within the ring.
     # CLI flag: -compactor.ring.heartbeat-timeout
     [heartbeat_timeout: <duration> | default = 1m]
+
+    # Minimum time to wait for ring stability at startup. 0 to disable.
+    # CLI flag: -compactor.ring.wait-stability-min-duration
+    [wait_stability_min_duration: <duration> | default = 1m]
+
+    # Maximum time to wait for ring stability at startup. If the compactor ring
+    # keep changing after this period of time, the compactor will start anyway.
+    # CLI flag: -compactor.ring.wait-stability-max-duration
+    [wait_stability_max_duration: <duration> | default = 5m]
+
+    # Name of network interface to read address from.
+    # CLI flag: -compactor.ring.instance-interface-names
+    [instance_interface_names: <list of string> | default = [eth0 en0]]
 ```
diff --git a/docs/blocks-storage/compactor.template b/docs/blocks-storage/compactor.template
index 102bb0a..5de4e9c 100644
--- a/docs/blocks-storage/compactor.template
+++ b/docs/blocks-storage/compactor.template
@@ -7,13 +7,16 @@ slug: compactor
 
 {{ .GeneratedFileWarning }}
 
-The **compactor** is an optional service which compacts multiple blocks of a given tenant into a single optimized larger block. Running compactor is **highly recommended** to reduce storage costs (deduplication, index size reduction), and increase query speed (querying fewer blocks is faster).
+The **compactor** is an service which is responsible to:
+
+- Compact multiple blocks of a given tenant into a single optimized larger block. This helps to reduce storage costs (deduplication, index size reduction), and increase query speed (querying fewer blocks is faster).
+- Keep the per-tenant bucket index updated. The [bucket index](./bucket-index.md) is used by [queriers](./querier.md), [store-gateways](./store-gateway.md) and rulers to discover new blocks in the storage.
 
 The compactor is **stateless**.
 
-## How it works
+## How compaction works
 
-The compactor has two main benefits:
+The blocks compaction has two main benefits:
 
 1. Vertically compact blocks uploaded by all ingesters for the same time range
 2. Horizontally compact blocks with small time ranges into a single larger block
@@ -38,6 +41,14 @@ The compactor sharding is based on the Cortex [hash ring](../architecture.md#the
 
 This feature can be enabled via `-compactor.sharding-enabled=true` and requires the backend [hash ring](../architecture.md#the-hash-ring) to be configured via `-compactor.ring.*` flags (or their respective YAML config options).
 
+### Waiting for stable ring at startup
+
+In the event of a cluster cold start or scale up of 2+ compactor instances at the same time we may end up in a situation where each new compactor instance starts at a slightly different time and thus each one runs the first compaction based on a different state of the ring. This is not a critical condition, but may be inefficient, because multiple compactor replicas may start compacting the same tenant nearly at the same time.
+
+To reduce the likelihood this could happen, the compactor waits for a stable ring at startup. A ring is considered stable if no instance is added/removed to the ring for at least `-compactor.ring.wait-stability-min-duration`. If the ring keep getting changed after `-compactor.ring.wait-stability-max-duration`, the compactor will stop waiting for a stable ring and will proceed starting up normally.
+
+To disable this waiting logic, you can start the compactor with `-compactor.ring.wait-stability-min-duration=0`.
+
 ## Soft and hard blocks deletion
 
 When the compactor successfully compacts some source blocks into a larger block, source blocks are deleted from the storage. Blocks deletion is not immediate, but follows a two steps process:
diff --git a/docs/blocks-storage/convert-stored-chunks-to-blocks.md b/docs/blocks-storage/convert-stored-chunks-to-blocks.md
index 88ab405..4afd765 100644
--- a/docs/blocks-storage/convert-stored-chunks-to-blocks.md
+++ b/docs/blocks-storage/convert-stored-chunks-to-blocks.md
@@ -23,6 +23,8 @@ Tools are:
   Looks for plan files, and distributes them to builders. Scheduler has global view of overall conversion progress.
 - [**Builder**](#builder)<br />
   Asks scheduler for next plan file to work on, fetches chunks, puts them into TSDB block, and uploads the block to the object store. It repeats this process until there are no more plans.
+- [**Cleaner**](#cleaner)<br />
+  Cleaner asks scheduler for next plan file to work on, but instead of building the block, it actually **REMOVES CHUNKS** and **INDEX ENTRIES** from the Index database.
 
 All tools start HTTP server (see `-server.http*` options) exposing the `/metrics` endpoint.
 All tools also start gRPC server (`-server.grpc*` options), but only Scheduler exposes services on it.
@@ -38,6 +40,7 @@ Scanner is started by running `blocksconvert -target=scanner`. Scanner requires 
 - `-scanner.allowed-users` – comma-separated list of Cortex tenants that should have plans generated. If empty, plans for all found users are generated.
 - `-scanner.ignore-users-regex` - If plans for all users are generated (`-scanner.allowed-users` is not set), then users matching this non-empty regular expression will be skipped.
 - `-scanner.tables-limit` – How many tables should be scanned? By default all tables are scanned, but when testing scanner it may be useful to start with small number of tables first.
+- `-scanner.tables` – Comma-separated list of tables to be scanned. Can be used to scan specific tables only. Note that schema is still used to find all tables first, and then this list is consulted to select only specified tables.
 
 Scanner will read the Cortex schema file to discover Index tables, and then it will start scanning them from most-recent table first, going back.
 For each table, it will fully read the table and generate a plan for each user and day stored in the table.
@@ -83,9 +86,28 @@ Builders are CPU intensive (decoding and merging chunks), and require fast disk 
 
 Builders's metrics have `cortex_blocksconvert_builder` prefix, and include total number of fetched chunks and their size, read position of the current plan and plan size, total number of written series and samples, number of chunks that couldn't be downloaded.
 
+### Cleaner
+
+Cleaner is similar to builder in that it asks scheduler for next plan to work on, but instead of building blocks, it actually **REMOVES CHUNKS and INDEX ENTRIES**. Use with caution.
+
+Cleaner is started by using `blocksconvert -target=cleaner`. Like Builder, it needs Scheduler endpoint, Cortex schema file, index and chunk-store specific options. Note that Cleaner works with any index store supported by Cortex, not just BigTable.
+
+- `-cleaner.scheduler-endpoint` – where to find scheduler
+- `-blocks-storage.*` – blocks storage configuration, used for downloading plan files
+- `-cleaner.plans-dir` – local directory to store plan file while it is being processed by Cleaner.
+- `-schema-config-file` – Cortex schema file.
+
+Cleaner doesn't **scan** for index entries, but uses existing plan files to find chunks and index entries. For each series, Cleaner needs to download at least one chunk. This is because plan file doesn't contain label names and values, but chunks do. Cleaner will then delete all index entries associated with the series, and also all chunks.
+
+**WARNING:** If both Builder and Cleaner run at the same time and use use the same Scheduler, **some plans will be handled by builder, and some by cleaner!** This will result in a loss of data!
+
+Cleaner should only be deployed if no other Builder is running. Running multiple Cleaners at once is not supported, and will result in leftover chunks and index entries. Reason for this is that chunks can span multiple days, and chunk is fully deleted only when processing plan (day) when chunk started. Since cleaner also needs to download some chunks to be able to clean up all index entries, when using multiple cleaners, it can happen that cleaner processing older plans will delete chunks required to properly clean up data in newer plans. When using single cleaner only, this is not a problem, since scheduler sends plans to cleaner in time-reversed order.
+
+**Note:** Cleaner is designed for use in very special cases, eg. when deleting chunks and index entries for a specific customer. If `blocksconvert` was used to convert ALL chunks to blocks, it is simpler to just drop the index and chunks database afterwards. In such case, Cleaner is not needed.
+
 ### Limitations
 
 The `blocksconvert` toolset currently has the following limitations:
 
-- Supports only BigTable for chunks index backend
+- Scanner supports only BigTable for chunks index backend, and cannot currently scan other databases.
 - Supports only chunks schema versions v9, v10 and v11
diff --git a/docs/blocks-storage/learn-more.md b/docs/blocks-storage/learn-more.md
new file mode 100644
index 0000000..5dd7d65
--- /dev/null
+++ b/docs/blocks-storage/learn-more.md
@@ -0,0 +1,21 @@
+---
+title: "Learn more"
+linkTitle: "Learn more"
+weight: 100
+slug: learn-more
+---
+
+In this page we're listing some external resources to learn more about the Cortex blocks storage.
+
+## Talks
+
+### Scaling Prometheus: How We Got Some Thanos Into Cortex
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/Z5OJzRogAS4" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+
+## Articles
+
+- [How to switch Cortex from chunks to blocks storage (and why you won’t look back)](https://grafana.com/blog/2020/10/19/how-to-switch-cortex-from-chunks-to-blocks-storage-and-why-you-wont-look-back/) (Oct 2020)
+- [Now GA: Cortex blocks storage for running Prometheus at scale with reduced operational complexity](https://grafana.com/blog/2020/10/06/now-ga-cortex-blocks-storage-for-running-prometheus-at-scale-with-reduced-operational-complexity/) (Oct 2020)
+- [Scaling Prometheus: How we’re pushing Cortex blocks storage to its limit and beyond](https://grafana.com/blog/2020/08/12/scaling-prometheus-how-were-pushing-cortex-blocks-storage-to-its-limit-and-beyond/) (Aug 2020)
+- [How blocks storage in Cortex reduces operational complexity for running Prometheus at massive scale](https://grafana.com/blog/2020/07/29/how-blocks-storage-in-cortex-reduces-operational-complexity-for-running-prometheus-at-massive-scale/) (Jul 2020)
diff --git a/docs/blocks-storage/production-tips.md b/docs/blocks-storage/production-tips.md
index 0f12e04..50238f0 100644
--- a/docs/blocks-storage/production-tips.md
+++ b/docs/blocks-storage/production-tips.md
@@ -7,6 +7,16 @@ slug: production-tips
 
 This page shares some tips and things to take in consideration when setting up a production Cortex cluster based on the blocks storage.
 
+## Ingester
+
+### Ensure a high number of max open file descriptors
+
+The ingester stores received series into per-tenant TSDB blocks. Both TSDB WAL, head and compacted blocks are composed by a relatively large number of files which gets loaded via mmap. This means that the ingester keeps file descriptors open for TSDB WAL segments, chunk files and compacted blocks which haven't reached the retention period yet.
+
+If your Cortex cluster has many tenants or ingester is running with a long `-blocks-storage.tsdb.retention-period`, the ingester may hit the **`file-max` ulimit** (maximum number of open file descriptions by a process); in such case, we recommend increasing the limit on your system or enabling [shuffle sharding](../guides/shuffle-sharding.md).
+
+The rule of thumb is that a production system shouldn't have the `file-max` ulimit below `65536`, but higher values are recommended (eg. `1048576`).
+
 ## Querier
 
 ### Ensure caching is enabled
@@ -53,6 +63,8 @@ The store-gateway heavily relies on caching both to speed up the queries and to 
 
 The store-gateway stores each block’s index-header on the local disk and loads it via mmap. This means that the store-gateway keeps a file descriptor open for each loaded block. If your Cortex cluster has many blocks in the bucket, the store-gateway may hit the **`file-max` ulimit** (maximum number of open file descriptions by a process); in such case, we recommend increasing the limit on your system or running more store-gateway instances with blocks sharding enabled.
 
+The rule of thumb is that a production system shouldn't have the `file-max` ulimit below `65536`, but higher values are recommended (eg. `1048576`).
+
 ## Compactor
 
 ### Ensure the compactor has enough disk space
diff --git a/docs/blocks-storage/querier.md b/docs/blocks-storage/querier.md
index 6a03b97..5e6351b 100644
--- a/docs/blocks-storage/querier.md
+++ b/docs/blocks-storage/querier.md
@@ -13,12 +13,28 @@ The querier is **stateless**.
 
 ## How it works
 
-At startup **queriers** iterate over the entire storage bucket to discover all tenants blocks and download the `meta.json` for each block. During this initial bucket scanning phase, a querier is not ready to handle incoming queries yet and its `/ready` readiness probe endpoint will fail.
+The querier needs to have an almost up-to-date view over the entire storage bucket, in order to find the right blocks to lookup at query time. The querier can keep the bucket view updated in to two different ways:
+
+1. Periodically scanning the bucket (default)
+2. Periodically downloading the [bucket index](./bucket-index.md)
+
+### Bucket index disabled (default)
+
+At startup, **queriers** iterate over the entire storage bucket to discover all tenants blocks and download the `meta.json` for each block. During this initial bucket scanning phase, a querier is not ready to handle incoming queries yet and its `/ready` readiness probe endpoint will fail.
 
 While running, queriers periodically iterate over the storage bucket to discover new tenants and recently uploaded blocks. Queriers do **not** download any content from blocks except a small `meta.json` file containing the block's metadata (including the minimum and maximum timestamp of samples within the block).
 
 Queriers use the metadata to compute the list of blocks that need to be queried at query time and fetch matching series from the [store-gateway](./store-gateway.md) instances holding the required blocks.
 
+### Bucket index enabled
+
+When [bucket index](./bucket-index.md) is enabled, queriers lazily download the bucket index upon the first query received for a given tenant, cache it in memory and periodically keep it update. The bucket index contains the list of blocks and block deletion marks of a tenant, which is later used during the query execution to find the set of blocks that need to be queried for the given query.
+
+Given the bucket index removes the need to scan the bucket, it brings few benefits:
+
+1. The querier is expected to be ready shortly after startup.
+2. Lower volume of API calls to object storage.
+
 ### Anatomy of a query request
 
 When a querier receives a query range request, it contains the following parameters:
@@ -60,6 +76,7 @@ Caching is optional, but **highly recommended** in a production environment. Ple
 - List of blocks per tenant
 - Block's `meta.json` content
 - Block's `deletion-mark.json` existence and content
+- Tenant's `bucket-index.json.gz` content
 
 Using the metadata cache can significantly reduce the number of API calls to object storage and protects from linearly scale the number of these API calls with the number of querier and store-gateway instances (because the bucket is periodically scanned and synched by each querier and store-gateway).
 
@@ -110,11 +127,16 @@ querier:
   # CLI flag: -querier.query-ingesters-within
   [query_ingesters_within: <duration> | default = 0s]
 
-  # The time after which a metric should only be queried from storage and not
-  # just ingesters. 0 means all queries are sent to store. When running the
-  # blocks storage, if this option is enabled, the time range of the query sent
-  # to the store will be manipulated to ensure the query end is not more recent
-  # than 'now - query-store-after'.
+  # Query long-term store for series, label values and label names APIs. Works
+  # only with blocks engine.
+  # CLI flag: -querier.query-store-for-labels-enabled
+  [query_store_for_labels_enabled: <boolean> | default = false]
+
+  # The time after which a metric should be queried from storage and not just
+  # ingesters. 0 means all queries are sent to store. When running the blocks
+  # storage, if this option is enabled, the time range of the query sent to the
+  # store will be manipulated to ensure the query end is not more recent than
+  # 'now - query-store-after'.
   # CLI flag: -querier.query-store-after
   [query_store_after: <duration> | default = 0s]
 
@@ -173,6 +195,15 @@ querier:
   # Default value 0 means secondary store is always queried.
   # CLI flag: -querier.use-second-store-before-time
   [use_second_store_before_time: <time> | default = 0]
+
+  # When distributor's sharding strategy is shuffle-sharding and this setting is
+  # > 0, queriers fetch in-memory series from the minimum set of required
+  # ingesters, selecting only ingesters which may have received series since
+  # 'now - lookback period'. The lookback period should be greater or equal than
+  # the configured 'query store after'. If this setting is 0, queriers always
+  # query all ingesters (ingesters shuffle sharding on read path is disabled).
+  # CLI flag: -querier.shuffle-sharding-ingesters-lookback-period
+  [shuffle_sharding_ingesters_lookback_period: <duration> | default = 0s]
 ```
 
 ### `blocks_storage_config`
@@ -181,7 +212,8 @@ The `blocks_storage_config` configures the blocks storage.
 
 ```yaml
 blocks_storage:
-  # Backend storage to use. Supported backends are: s3, gcs, azure, filesystem.
+  # Backend storage to use. Supported backends are: s3, gcs, azure, swift,
+  # filesystem.
   # CLI flag: -blocks-storage.backend
   [backend: <string> | default = "s3"]
 
@@ -210,6 +242,25 @@ blocks_storage:
     # CLI flag: -blocks-storage.s3.insecure
     [insecure: <boolean> | default = false]
 
+    # The signature version to use for authenticating against S3. Supported
+    # values are: v4, v2.
+    # CLI flag: -blocks-storage.s3.signature-version
+    [signature_version: <string> | default = "v4"]
+
+    http:
+      # The time an idle connection will remain idle before closing.
+      # CLI flag: -blocks-storage.s3.http.idle-conn-timeout
+      [idle_conn_timeout: <duration> | default = 1m30s]
+
+      # The amount of time the client will wait for a servers response headers.
+      # CLI flag: -blocks-storage.s3.http.response-header-timeout
+      [response_header_timeout: <duration> | default = 2m]
+
+      # If the client connects to S3 via HTTPS and this option is enabled, the
+      # client will accept any certificate and hostname.
+      # CLI flag: -blocks-storage.s3.http.insecure-skip-verify
+      [insecure_skip_verify: <boolean> | default = false]
+
   gcs:
     # GCS bucket name
     # CLI flag: -blocks-storage.gcs.bucket-name
@@ -243,22 +294,100 @@ blocks_storage:
     # CLI flag: -blocks-storage.azure.max-retries
     [max_retries: <int> | default = 20]
 
+  swift:
+    # OpenStack Swift authentication API version. 0 to autodetect.
+    # CLI flag: -blocks-storage.swift.auth-version
+    [auth_version: <int> | default = 0]
+
+    # OpenStack Swift authentication URL
+    # CLI flag: -blocks-storage.swift.auth-url
+    [auth_url: <string> | default = ""]
+
+    # OpenStack Swift username.
+    # CLI flag: -blocks-storage.swift.username
+    [username: <string> | default = ""]
+
+    # OpenStack Swift user's domain name.
+    # CLI flag: -blocks-storage.swift.user-domain-name
+    [user_domain_name: <string> | default = ""]
+
+    # OpenStack Swift user's domain ID.
+    # CLI flag: -blocks-storage.swift.user-domain-id
+    [user_domain_id: <string> | default = ""]
+
+    # OpenStack Swift user ID.
+    # CLI flag: -blocks-storage.swift.user-id
+    [user_id: <string> | default = ""]
+
+    # OpenStack Swift API key.
+    # CLI flag: -blocks-storage.swift.password
+    [password: <string> | default = ""]
+
+    # OpenStack Swift user's domain ID.
+    # CLI flag: -blocks-storage.swift.domain-id
+    [domain_id: <string> | default = ""]
+
+    # OpenStack Swift user's domain name.
+    # CLI flag: -blocks-storage.swift.domain-name
+    [domain_name: <string> | default = ""]
+
+    # OpenStack Swift project ID (v2,v3 auth only).
+    # CLI flag: -blocks-storage.swift.project-id
+    [project_id: <string> | default = ""]
+
+    # OpenStack Swift project name (v2,v3 auth only).
+    # CLI flag: -blocks-storage.swift.project-name
+    [project_name: <string> | default = ""]
+
+    # ID of the OpenStack Swift project's domain (v3 auth only), only needed if
+    # it differs the from user domain.
+    # CLI flag: -blocks-storage.swift.project-domain-id
+    [project_domain_id: <string> | default = ""]
+
+    # Name of the OpenStack Swift project's domain (v3 auth only), only needed
+    # if it differs from the user domain.
+    # CLI flag: -blocks-storage.swift.project-domain-name
+    [project_domain_name: <string> | default = ""]
+
+    # OpenStack Swift Region to use (v2,v3 auth only).
+    # CLI flag: -blocks-storage.swift.region-name
+    [region_name: <string> | default = ""]
+
+    # Name of the OpenStack Swift container to put chunks in.
+    # CLI flag: -blocks-storage.swift.container-name
+    [container_name: <string> | default = ""]
+
+    # Max retries on requests error.
+    # CLI flag: -blocks-storage.swift.max-retries
+    [max_retries: <int> | default = 3]
+
+    # Time after which a connection attempt is aborted.
+    # CLI flag: -blocks-storage.swift.connect-timeout
+    [connect_timeout: <duration> | default = 10s]
+
+    # Time after which an idle request is aborted. The timeout watchdog is reset
+    # each time some data is received, so the timeout triggers after X time no
+    # data is received on a request.
+    # CLI flag: -blocks-storage.swift.request-timeout
+    [request_timeout: <duration> | default = 5s]
+
   filesystem:
     # Local filesystem storage directory.
     # CLI flag: -blocks-storage.filesystem.dir
     [dir: <string> | default = ""]
 
-  # This configures how the store-gateway synchronizes blocks stored in the
-  # bucket.
+  # This configures how the querier and store-gateway discover and synchronize
+  # blocks stored in the bucket.
   bucket_store:
     # Directory to store synchronized TSDB index headers.
     # CLI flag: -blocks-storage.bucket-store.sync-dir
     [sync_dir: <string> | default = "tsdb-sync"]
 
-    # How frequently scan the bucket to look for changes (new blocks shipped by
-    # ingesters and blocks removed by retention or compaction). 0 disables it.
+    # How frequently to scan the bucket, or to refresh the bucket index (if
+    # enabled), in order to look for changes (new blocks shipped by ingesters
+    # and blocks deleted by retention or compaction).
     # CLI flag: -blocks-storage.bucket-store.sync-interval
-    [sync_interval: <duration> | default = 5m]
+    [sync_interval: <duration> | default = 15m]
 
     # Max size - in bytes - of a per-tenant chunk pool, used to reduce memory
     # allocations.
@@ -331,7 +460,7 @@ blocks_storage:
         [max_get_multi_concurrency: <int> | default = 100]
 
         # The maximum number of keys a single underlying get operation should
-        # run. If more keys are specified, internally keys are splitted into
+        # run. If more keys are specified, internally keys are split into
         # multiple batches and fetched concurrently, honoring the max
         # concurrency. If set to 0, the max batch size is unlimited.
         # CLI flag: -blocks-storage.bucket-store.index-cache.memcached.max-get-multi-batch-size
@@ -342,7 +471,8 @@ blocks_storage:
         # CLI flag: -blocks-storage.bucket-store.index-cache.memcached.max-item-size
         [max_item_size: <int> | default = 1048576]
 
-      # Compress postings before storing them to postings cache.
+      # Deprecated: compress postings before storing them to postings cache.
+      # This option is unused and postings compression is always enabled.
       # CLI flag: -blocks-storage.bucket-store.index-cache.postings-compression-enabled
       [postings_compression_enabled: <boolean> | default = false]
 
@@ -382,7 +512,7 @@ blocks_storage:
         [max_get_multi_concurrency: <int> | default = 100]
 
         # The maximum number of keys a single underlying get operation should
-        # run. If more keys are specified, internally keys are splitted into
+        # run. If more keys are specified, internally keys are split into
         # multiple batches and fetched concurrently, honoring the max
         # concurrency. If set to 0, the max batch size is unlimited.
         # CLI flag: -blocks-storage.bucket-store.chunks-cache.memcached.max-get-multi-batch-size
@@ -406,7 +536,7 @@ blocks_storage:
 
       # TTL for caching object attributes for chunks.
       # CLI flag: -blocks-storage.bucket-store.chunks-cache.attributes-ttl
-      [attributes_ttl: <duration> | default = 24h]
+      [attributes_ttl: <duration> | default = 168h]
 
       # TTL for caching individual chunks subranges.
       # CLI flag: -blocks-storage.bucket-store.chunks-cache.subrange-ttl
@@ -448,7 +578,7 @@ blocks_storage:
         [max_get_multi_concurrency: <int> | default = 100]
 
         # The maximum number of keys a single underlying get operation should
-        # run. If more keys are specified, internally keys are splitted into
+        # run. If more keys are specified, internally keys are split into
         # multiple batches and fetched concurrently, honoring the max
         # concurrency. If set to 0, the max batch size is unlimited.
         # CLI flag: -blocks-storage.bucket-store.metadata-cache.memcached.max-get-multi-batch-size
@@ -471,11 +601,13 @@ blocks_storage:
       # CLI flag: -blocks-storage.bucket-store.metadata-cache.chunks-list-ttl
       [chunks_list_ttl: <duration> | default = 24h]
 
-      # How long to cache information that block metafile exists.
+      # How long to cache information that block metafile exists. Also used for
+      # user deletion mark file.
       # CLI flag: -blocks-storage.bucket-store.metadata-cache.metafile-exists-ttl
       [metafile_exists_ttl: <duration> | default = 2h]
 
-      # How long to cache information that block metafile doesn't exist.
+      # How long to cache information that block metafile doesn't exist. Also
+      # used for user deletion mark file.
       # CLI flag: -blocks-storage.bucket-store.metadata-cache.metafile-doesnt-exist-ttl
       [metafile_doesnt_exist_ttl: <duration> | default = 5m]
 
@@ -483,10 +615,34 @@ blocks_storage:
       # CLI flag: -blocks-storage.bucket-store.metadata-cache.metafile-content-ttl
       [metafile_content_ttl: <duration> | default = 24h]
 
-      # Maximum size of metafile content to cache in bytes.
+      # Maximum size of metafile content to cache in bytes. Caching will be
+      # skipped if the content exceeds this size. This is useful to avoid
+      # network round trip for large content if the configured caching backend
+      # has an hard limit on cached items size (in this case, you should set
+      # this limit to the same limit in the caching backend).
       # CLI flag: -blocks-storage.bucket-store.metadata-cache.metafile-max-size-bytes
       [metafile_max_size_bytes: <int> | default = 1048576]
 
+      # How long to cache attributes of the block metafile.
+      # CLI flag: -blocks-storage.bucket-store.metadata-cache.metafile-attributes-ttl
+      [metafile_attributes_ttl: <duration> | default = 168h]
+
+      # How long to cache attributes of the block index.
+      # CLI flag: -blocks-storage.bucket-store.metadata-cache.block-index-attributes-ttl
+      [block_index_attributes_ttl: <duration> | default = 168h]
+
+      # How long to cache content of the bucket index.
+      # CLI flag: -blocks-storage.bucket-store.metadata-cache.bucket-index-content-ttl
+      [bucket_index_content_ttl: <duration> | default = 5m]
+
+      # Maximum size of bucket index content to cache in bytes. Caching will be
+      # skipped if the content exceeds this size. This is useful to avoid
+      # network round trip for large content if the configured caching backend
+      # has an hard limit on cached items size (in this case, you should set
+      # this limit to the same limit in the caching backend).
+      # CLI flag: -blocks-storage.bucket-store.metadata-cache.bucket-index-max-size-bytes
+      [bucket_index_max_size_bytes: <int> | default = 1048576]
+
     # Duration after which the blocks marked for deletion will be filtered out
     # while fetching blocks. The idea of ignore-deletion-marks-delay is to
     # ignore blocks that are marked for deletion with some delay. This ensures
@@ -496,6 +652,30 @@ blocks_storage:
     # CLI flag: -blocks-storage.bucket-store.ignore-deletion-marks-delay
     [ignore_deletion_mark_delay: <duration> | default = 6h]
 
+    bucket_index:
+      # True to enable querier and store-gateway to discover blocks in the
+      # storage via bucket index instead of bucket scanning.
+      # CLI flag: -blocks-storage.bucket-store.bucket-index.enabled
+      [enabled: <boolean> | default = false]
+
+      # How frequently a bucket index, which previously failed to load, should
+      # be tried to load again. This option is used only by querier.
+      # CLI flag: -blocks-storage.bucket-store.bucket-index.update-on-error-interval
+      [update_on_error_interval: <duration> | default = 1m]
+
+      # How long a unused bucket index should be cached. Once this timeout
+      # expires, the unused bucket index is removed from the in-memory cache.
+      # This option is used only by querier.
+      # CLI flag: -blocks-storage.bucket-store.bucket-index.idle-timeout
+      [idle_timeout: <duration> | default = 1h]
+
+      # The maximum allowed age of a bucket index (last updated) before queries
+      # start failing because the bucket index is too old. The bucket index is
+      # periodically updated by the compactor, while this check is enforced in
+      # the querier (at query time).
+      # CLI flag: -blocks-storage.bucket-store.bucket-index.max-stale-period
+      [max_stale_period: <duration> | default = 1h]
+
   tsdb:
     # Local directory to store TSDBs in the ingesters.
     # CLI flag: -blocks-storage.tsdb.dir
@@ -535,6 +715,12 @@ blocks_storage:
     # CLI flag: -blocks-storage.tsdb.head-compaction-idle-timeout
     [head_compaction_idle_timeout: <duration> | default = 1h]
 
+    # The write buffer size used by the head chunks mapper. Lower values reduce
+    # memory utilisation on clusters with a large number of tenants at the cost
+    # of increased disk I/O operations.
+    # CLI flag: -blocks-storage.tsdb.head-chunks-write-buffer-size-bytes
+    [head_chunks_write_buffer_size_bytes: <int> | default = 4194304]
+
     # The number of shards of series to use in TSDB (must be a power of 2).
     # Reducing this will decrease memory footprint, but can negatively impact
     # performance.
@@ -545,11 +731,24 @@ blocks_storage:
     # CLI flag: -blocks-storage.tsdb.wal-compression-enabled
     [wal_compression_enabled: <boolean> | default = false]
 
+    # TSDB WAL segments files max size (bytes).
+    # CLI flag: -blocks-storage.tsdb.wal-segment-size-bytes
+    [wal_segment_size_bytes: <int> | default = 134217728]
+
     # True to flush blocks to storage on shutdown. If false, incomplete blocks
     # will be reused after restart.
     # CLI flag: -blocks-storage.tsdb.flush-blocks-on-shutdown
     [flush_blocks_on_shutdown: <boolean> | default = false]
 
+    # If TSDB has not received any data for this duration, and all blocks from
+    # TSDB have been shipped, TSDB is closed and deleted from local disk. If set
+    # to positive value, this value should be equal or higher than
+    # -querier.query-ingesters-within flag to make sure that TSDB is not closed
+    # prematurely, which could cause partial query results. 0 or negative value
+    # disables closing of idle TSDB.
+    # CLI flag: -blocks-storage.tsdb.close-idle-tsdb-timeout
+    [close_idle_tsdb_timeout: <duration> | default = 0s]
+
     # limit the number of concurrently opening TSDB's on startup
     # CLI flag: -blocks-storage.tsdb.max-tsdb-opening-concurrency-on-startup
     [max_tsdb_opening_concurrency_on_startup: <int> | default = 10]
diff --git a/docs/blocks-storage/querier.template b/docs/blocks-storage/querier.template
index 97d59a2..ee944d3 100644
--- a/docs/blocks-storage/querier.template
+++ b/docs/blocks-storage/querier.template
@@ -13,12 +13,28 @@ The querier is **stateless**.
 
 ## How it works
 
-At startup **queriers** iterate over the entire storage bucket to discover all tenants blocks and download the `meta.json` for each block. During this initial bucket scanning phase, a querier is not ready to handle incoming queries yet and its `/ready` readiness probe endpoint will fail.
+The querier needs to have an almost up-to-date view over the entire storage bucket, in order to find the right blocks to lookup at query time. The querier can keep the bucket view updated in to two different ways:
+
+1. Periodically scanning the bucket (default)
+2. Periodically downloading the [bucket index](./bucket-index.md)
+
+### Bucket index disabled (default)
+
+At startup, **queriers** iterate over the entire storage bucket to discover all tenants blocks and download the `meta.json` for each block. During this initial bucket scanning phase, a querier is not ready to handle incoming queries yet and its `/ready` readiness probe endpoint will fail.
 
 While running, queriers periodically iterate over the storage bucket to discover new tenants and recently uploaded blocks. Queriers do **not** download any content from blocks except a small `meta.json` file containing the block's metadata (including the minimum and maximum timestamp of samples within the block).
 
 Queriers use the metadata to compute the list of blocks that need to be queried at query time and fetch matching series from the [store-gateway](./store-gateway.md) instances holding the required blocks.
 
+### Bucket index enabled
+
+When [bucket index](./bucket-index.md) is enabled, queriers lazily download the bucket index upon the first query received for a given tenant, cache it in memory and periodically keep it update. The bucket index contains the list of blocks and block deletion marks of a tenant, which is later used during the query execution to find the set of blocks that need to be queried for the given query.
+
+Given the bucket index removes the need to scan the bucket, it brings few benefits:
+
+1. The querier is expected to be ready shortly after startup.
+2. Lower volume of API calls to object storage.
+
 ### Anatomy of a query request
 
 When a querier receives a query range request, it contains the following parameters:
@@ -60,6 +76,7 @@ Caching is optional, but **highly recommended** in a production environment. Ple
 - List of blocks per tenant
 - Block's `meta.json` content
 - Block's `deletion-mark.json` existence and content
+- Tenant's `bucket-index.json.gz` content
 
 Using the metadata cache can significantly reduce the number of API calls to object storage and protects from linearly scale the number of these API calls with the number of querier and store-gateway instances (because the bucket is periodically scanned and synched by each querier and store-gateway).
 
diff --git a/docs/blocks-storage/store-gateway.md b/docs/blocks-storage/store-gateway.md
index c145c01..32961dd 100644
--- a/docs/blocks-storage/store-gateway.md
+++ b/docs/blocks-storage/store-gateway.md
@@ -13,6 +13,13 @@ The store-gateway is **semi-stateful**.
 
 ## How it works
 
+The store-gateway needs to have an almost up-to-date view over the storage bucket, in order to discover blocks belonging to their shard. The store-gateway can keep the bucket view updated in to two different ways:
+
+1. Periodically scanning the bucket (default)
+2. Periodically downloading the [bucket index](./bucket-index.md)
+
+### Bucket index disabled (default)
+
 At startup **store-gateways** iterate over the entire storage bucket to discover blocks for all tenants and download the `meta.json` and index-header for each block. During this initial bucket synchronization phase, the store-gateway `/ready` readiness probe endpoint will fail.
 
 While running, store-gateways periodically rescan the storage bucket to discover new blocks (uploaded by the ingesters and [compactor](./compactor.md)) and blocks marked for deletion or fully deleted since the last scan (as a result of compaction). The frequency at which this occurs is configured via `-blocks-storage.bucket-store.sync-interval`.
@@ -21,6 +28,12 @@ The blocks chunks and the entire index are never fully downloaded by the store-g
 
 _For more information about the index-header, please refer to [Binary index-header documentation](./binary-index-header.md)._
 
+### Bucket index enabled
+
+When bucket index is enabled, the overall workflow is the same but, instead of iterating over the bucket objects, the store-gateway fetch the [bucket index](./bucket-index.md) for each tenant belonging to their shard in order to discover each tenant's blocks and block deletion marks.
+
+_For more information about the bucket index, please refer to [bucket index documentation](./bucket-index.md)._
+
 ## Blocks sharding and replication
 
 The store-gateway optionally supports blocks sharding. Sharding can be used to horizontally scale blocks in a large cluster without hitting any vertical scalability limit.
@@ -48,6 +61,8 @@ The **`shuffle-sharding`** strategy spreads the blocks of a tenant across a subs
 
 The shuffle sharding strategy can be enabled via `-store-gateway.sharding-strategy=shuffle-sharding` and requires the `-store-gateway.tenant-shard-size` flag (or their respective YAML config options) to be set to the default shard size, which is the default number of store-gateway instances each tenant should be sharded to. The shard size can then be overridden on a per-tenant basis setting the `store_gateway_tenant_shard_size` in the limits overrides.
 
+_Please check out the [shuffle sharding documentation](../guides/shuffle-sharding.md) for more information about how it works._
+
 ### Auto-forget
 
 When a store-gateway instance cleanly shutdowns, it automatically unregisters itself from the ring. However, in the event of a crash or node failure, the instance will not be unregistered from the ring, potentially leaving a spurious entry in the ring forever.
@@ -56,6 +71,16 @@ To protect from this, when an healthy store-gateway instance finds another insta
 
 This feature is called **auto-forget** and is built into the store-gateway.
 
+### Zone-awareness
+
+The store-gateway replication optionally supports [zone-awareness](../guides/zone-replication.md). When zone-aware replication is enabled and the blocks replication factor is > 1, each block is guaranteed to be replicated across store-gateway instances running in different availability zones.
+
+**To enable** the zone-aware replication for the store-gateways you should:
+
+1. Configure the availability zone for each store-gateway via the `-store-gateway.sharding-ring.instance-availability-zone` CLI flag (or its respective YAML config option)
+2. Enable blocks zone-aware replication via the `-store-gateway.sharding-ring.zone-awareness-enabled` CLI flag (or its respective YAML config option). Please be aware this configuration option should be set to store-gateways, queriers and rulers.
+3. Rollout store-gateways, queriers and rulers to apply the new configuration
+
 ## Caching
 
 The store-gateway supports the following caches:
@@ -113,6 +138,7 @@ Store-gateway and [querier](./querier.md) can use memcached for caching bucket m
 - List of blocks per tenant
 - Block's `meta.json` content
 - Block's `deletion-mark.json` existence and content
+- Tenant's `bucket-index.json.gz` content
 
 Using the metadata cache can significantly reduce the number of API calls to object storage and protects from linearly scale the number of these API calls with the number of querier and store-gateway instances (because the bucket is periodically scanned and synched by each querier and store-gateway).
 
@@ -207,6 +233,20 @@ store_gateway:
     # CLI flag: -store-gateway.sharding-ring.tokens-file-path
     [tokens_file_path: <string> | default = ""]
 
+    # True to enable zone-awareness and replicate blocks across different
+    # availability zones.
+    # CLI flag: -store-gateway.sharding-ring.zone-awareness-enabled
+    [zone_awareness_enabled: <boolean> | default = false]
+
+    # Name of network interface to read address from.
+    # CLI flag: -store-gateway.sharding-ring.instance-interface-names
+    [instance_interface_names: <list of string> | default = [eth0 en0]]
+
+    # The availability zone where this instance is running. Required if
+    # zone-awareness is enabled.
+    # CLI flag: -store-gateway.sharding-ring.instance-availability-zone
+    [instance_availability_zone: <string> | default = ""]
+
   # The sharding strategy to use. Supported values are: default,
   # shuffle-sharding.
   # CLI flag: -store-gateway.sharding-strategy
@@ -219,7 +259,8 @@ The `blocks_storage_config` configures the blocks storage.
 
 ```yaml
 blocks_storage:
-  # Backend storage to use. Supported backends are: s3, gcs, azure, filesystem.
+  # Backend storage to use. Supported backends are: s3, gcs, azure, swift,
+  # filesystem.
   # CLI flag: -blocks-storage.backend
   [backend: <string> | default = "s3"]
 
@@ -248,6 +289,25 @@ blocks_storage:
     # CLI flag: -blocks-storage.s3.insecure
     [insecure: <boolean> | default = false]
 
+    # The signature version to use for authenticating against S3. Supported
+    # values are: v4, v2.
+    # CLI flag: -blocks-storage.s3.signature-version
+    [signature_version: <string> | default = "v4"]
+
+    http:
+      # The time an idle connection will remain idle before closing.
+      # CLI flag: -blocks-storage.s3.http.idle-conn-timeout
+      [idle_conn_timeout: <duration> | default = 1m30s]
+
+      # The amount of time the client will wait for a servers response headers.
+      # CLI flag: -blocks-storage.s3.http.response-header-timeout
+      [response_header_timeout: <duration> | default = 2m]
+
+      # If the client connects to S3 via HTTPS and this option is enabled, the
+      # client will accept any certificate and hostname.
+      # CLI flag: -blocks-storage.s3.http.insecure-skip-verify
+      [insecure_skip_verify: <boolean> | default = false]
+
   gcs:
     # GCS bucket name
     # CLI flag: -blocks-storage.gcs.bucket-name
@@ -281,22 +341,100 @@ blocks_storage:
     # CLI flag: -blocks-storage.azure.max-retries
     [max_retries: <int> | default = 20]
 
+  swift:
+    # OpenStack Swift authentication API version. 0 to autodetect.
+    # CLI flag: -blocks-storage.swift.auth-version
+    [auth_version: <int> | default = 0]
+
+    # OpenStack Swift authentication URL
+    # CLI flag: -blocks-storage.swift.auth-url
+    [auth_url: <string> | default = ""]
+
+    # OpenStack Swift username.
+    # CLI flag: -blocks-storage.swift.username
+    [username: <string> | default = ""]
+
+    # OpenStack Swift user's domain name.
+    # CLI flag: -blocks-storage.swift.user-domain-name
+    [user_domain_name: <string> | default = ""]
+
+    # OpenStack Swift user's domain ID.
+    # CLI flag: -blocks-storage.swift.user-domain-id
+    [user_domain_id: <string> | default = ""]
+
+    # OpenStack Swift user ID.
+    # CLI flag: -blocks-storage.swift.user-id
+    [user_id: <string> | default = ""]
+
+    # OpenStack Swift API key.
+    # CLI flag: -blocks-storage.swift.password
+    [password: <string> | default = ""]
+
+    # OpenStack Swift user's domain ID.
+    # CLI flag: -blocks-storage.swift.domain-id
+    [domain_id: <string> | default = ""]
+
+    # OpenStack Swift user's domain name.
+    # CLI flag: -blocks-storage.swift.domain-name
+    [domain_name: <string> | default = ""]
+
+    # OpenStack Swift project ID (v2,v3 auth only).
+    # CLI flag: -blocks-storage.swift.project-id
+    [project_id: <string> | default = ""]
+
+    # OpenStack Swift project name (v2,v3 auth only).
+    # CLI flag: -blocks-storage.swift.project-name
+    [project_name: <string> | default = ""]
+
+    # ID of the OpenStack Swift project's domain (v3 auth only), only needed if
+    # it differs the from user domain.
+    # CLI flag: -blocks-storage.swift.project-domain-id
+    [project_domain_id: <string> | default = ""]
+
+    # Name of the OpenStack Swift project's domain (v3 auth only), only needed
+    # if it differs from the user domain.
+    # CLI flag: -blocks-storage.swift.project-domain-name
+    [project_domain_name: <string> | default = ""]
+
+    # OpenStack Swift Region to use (v2,v3 auth only).
+    # CLI flag: -blocks-storage.swift.region-name
+    [region_name: <string> | default = ""]
+
+    # Name of the OpenStack Swift container to put chunks in.
+    # CLI flag: -blocks-storage.swift.container-name
+    [container_name: <string> | default = ""]
+
+    # Max retries on requests error.
+    # CLI flag: -blocks-storage.swift.max-retries
+    [max_retries: <int> | default = 3]
+
+    # Time after which a connection attempt is aborted.
+    # CLI flag: -blocks-storage.swift.connect-timeout
+    [connect_timeout: <duration> | default = 10s]
+
+    # Time after which an idle request is aborted. The timeout watchdog is reset
+    # each time some data is received, so the timeout triggers after X time no
+    # data is received on a request.
+    # CLI flag: -blocks-storage.swift.request-timeout
+    [request_timeout: <duration> | default = 5s]
+
   filesystem:
     # Local filesystem storage directory.
     # CLI flag: -blocks-storage.filesystem.dir
     [dir: <string> | default = ""]
 
-  # This configures how the store-gateway synchronizes blocks stored in the
-  # bucket.
+  # This configures how the querier and store-gateway discover and synchronize
+  # blocks stored in the bucket.
   bucket_store:
     # Directory to store synchronized TSDB index headers.
     # CLI flag: -blocks-storage.bucket-store.sync-dir
     [sync_dir: <string> | default = "tsdb-sync"]
 
-    # How frequently scan the bucket to look for changes (new blocks shipped by
-    # ingesters and blocks removed by retention or compaction). 0 disables it.
+    # How frequently to scan the bucket, or to refresh the bucket index (if
+    # enabled), in order to look for changes (new blocks shipped by ingesters
+    # and blocks deleted by retention or compaction).
     # CLI flag: -blocks-storage.bucket-store.sync-interval
-    [sync_interval: <duration> | default = 5m]
+    [sync_interval: <duration> | default = 15m]
 
     # Max size - in bytes - of a per-tenant chunk pool, used to reduce memory
     # allocations.
@@ -369,7 +507,7 @@ blocks_storage:
         [max_get_multi_concurrency: <int> | default = 100]
 
         # The maximum number of keys a single underlying get operation should
-        # run. If more keys are specified, internally keys are splitted into
+        # run. If more keys are specified, internally keys are split into
         # multiple batches and fetched concurrently, honoring the max
         # concurrency. If set to 0, the max batch size is unlimited.
         # CLI flag: -blocks-storage.bucket-store.index-cache.memcached.max-get-multi-batch-size
@@ -380,7 +518,8 @@ blocks_storage:
         # CLI flag: -blocks-storage.bucket-store.index-cache.memcached.max-item-size
         [max_item_size: <int> | default = 1048576]
 
-      # Compress postings before storing them to postings cache.
+      # Deprecated: compress postings before storing them to postings cache.
+      # This option is unused and postings compression is always enabled.
       # CLI flag: -blocks-storage.bucket-store.index-cache.postings-compression-enabled
       [postings_compression_enabled: <boolean> | default = false]
 
@@ -420,7 +559,7 @@ blocks_storage:
         [max_get_multi_concurrency: <int> | default = 100]
 
         # The maximum number of keys a single underlying get operation should
-        # run. If more keys are specified, internally keys are splitted into
+        # run. If more keys are specified, internally keys are split into
         # multiple batches and fetched concurrently, honoring the max
         # concurrency. If set to 0, the max batch size is unlimited.
         # CLI flag: -blocks-storage.bucket-store.chunks-cache.memcached.max-get-multi-batch-size
@@ -444,7 +583,7 @@ blocks_storage:
 
       # TTL for caching object attributes for chunks.
       # CLI flag: -blocks-storage.bucket-store.chunks-cache.attributes-ttl
-      [attributes_ttl: <duration> | default = 24h]
+      [attributes_ttl: <duration> | default = 168h]
 
       # TTL for caching individual chunks subranges.
       # CLI flag: -blocks-storage.bucket-store.chunks-cache.subrange-ttl
@@ -486,7 +625,7 @@ blocks_storage:
         [max_get_multi_concurrency: <int> | default = 100]
 
         # The maximum number of keys a single underlying get operation should
-        # run. If more keys are specified, internally keys are splitted into
+        # run. If more keys are specified, internally keys are split into
         # multiple batches and fetched concurrently, honoring the max
         # concurrency. If set to 0, the max batch size is unlimited.
         # CLI flag: -blocks-storage.bucket-store.metadata-cache.memcached.max-get-multi-batch-size
@@ -509,11 +648,13 @@ blocks_storage:
       # CLI flag: -blocks-storage.bucket-store.metadata-cache.chunks-list-ttl
       [chunks_list_ttl: <duration> | default = 24h]
 
-      # How long to cache information that block metafile exists.
+      # How long to cache information that block metafile exists. Also used for
+      # user deletion mark file.
       # CLI flag: -blocks-storage.bucket-store.metadata-cache.metafile-exists-ttl
       [metafile_exists_ttl: <duration> | default = 2h]
 
-      # How long to cache information that block metafile doesn't exist.
+      # How long to cache information that block metafile doesn't exist. Also
+      # used for user deletion mark file.
       # CLI flag: -blocks-storage.bucket-store.metadata-cache.metafile-doesnt-exist-ttl
       [metafile_doesnt_exist_ttl: <duration> | default = 5m]
 
@@ -521,10 +662,34 @@ blocks_storage:
       # CLI flag: -blocks-storage.bucket-store.metadata-cache.metafile-content-ttl
       [metafile_content_ttl: <duration> | default = 24h]
 
-      # Maximum size of metafile content to cache in bytes.
+      # Maximum size of metafile content to cache in bytes. Caching will be
+      # skipped if the content exceeds this size. This is useful to avoid
+      # network round trip for large content if the configured caching backend
+      # has an hard limit on cached items size (in this case, you should set
+      # this limit to the same limit in the caching backend).
       # CLI flag: -blocks-storage.bucket-store.metadata-cache.metafile-max-size-bytes
       [metafile_max_size_bytes: <int> | default = 1048576]
 
+      # How long to cache attributes of the block metafile.
+      # CLI flag: -blocks-storage.bucket-store.metadata-cache.metafile-attributes-ttl
+      [metafile_attributes_ttl: <duration> | default = 168h]
+
+      # How long to cache attributes of the block index.
+      # CLI flag: -blocks-storage.bucket-store.metadata-cache.block-index-attributes-ttl
+      [block_index_attributes_ttl: <duration> | default = 168h]
+
+      # How long to cache content of the bucket index.
+      # CLI flag: -blocks-storage.bucket-store.metadata-cache.bucket-index-content-ttl
+      [bucket_index_content_ttl: <duration> | default = 5m]
+
+      # Maximum size of bucket index content to cache in bytes. Caching will be
+      # skipped if the content exceeds this size. This is useful to avoid
+      # network round trip for large content if the configured caching backend
+      # has an hard limit on cached items size (in this case, you should set
+      # this limit to the same limit in the caching backend).
+      # CLI flag: -blocks-storage.bucket-store.metadata-cache.bucket-index-max-size-bytes
+      [bucket_index_max_size_bytes: <int> | default = 1048576]
+
     # Duration after which the blocks marked for deletion will be filtered out
     # while fetching blocks. The idea of ignore-deletion-marks-delay is to
     # ignore blocks that are marked for deletion with some delay. This ensures
@@ -534,6 +699,30 @@ blocks_storage:
     # CLI flag: -blocks-storage.bucket-store.ignore-deletion-marks-delay
     [ignore_deletion_mark_delay: <duration> | default = 6h]
 
+    bucket_index:
+      # True to enable querier and store-gateway to discover blocks in the
+      # storage via bucket index instead of bucket scanning.
+      # CLI flag: -blocks-storage.bucket-store.bucket-index.enabled
+      [enabled: <boolean> | default = false]
+
+      # How frequently a bucket index, which previously failed to load, should
+      # be tried to load again. This option is used only by querier.
+      # CLI flag: -blocks-storage.bucket-store.bucket-index.update-on-error-interval
+      [update_on_error_interval: <duration> | default = 1m]
+
+      # How long a unused bucket index should be cached. Once this timeout
+      # expires, the unused bucket index is removed from the in-memory cache.
+      # This option is used only by querier.
+      # CLI flag: -blocks-storage.bucket-store.bucket-index.idle-timeout
+      [idle_timeout: <duration> | default = 1h]
+
+      # The maximum allowed age of a bucket index (last updated) before queries
+      # start failing because the bucket index is too old. The bucket index is
+      # periodically updated by the compactor, while this check is enforced in
+      # the querier (at query time).
+      # CLI flag: -blocks-storage.bucket-store.bucket-index.max-stale-period
+      [max_stale_period: <duration> | default = 1h]
+
   tsdb:
     # Local directory to store TSDBs in the ingesters.
     # CLI flag: -blocks-storage.tsdb.dir
@@ -573,6 +762,12 @@ blocks_storage:
     # CLI flag: -blocks-storage.tsdb.head-compaction-idle-timeout
     [head_compaction_idle_timeout: <duration> | default = 1h]
 
+    # The write buffer size used by the head chunks mapper. Lower values reduce
+    # memory utilisation on clusters with a large number of tenants at the cost
+    # of increased disk I/O operations.
+    # CLI flag: -blocks-storage.tsdb.head-chunks-write-buffer-size-bytes
+    [head_chunks_write_buffer_size_bytes: <int> | default = 4194304]
+
     # The number of shards of series to use in TSDB (must be a power of 2).
     # Reducing this will decrease memory footprint, but can negatively impact
     # performance.
@@ -583,11 +778,24 @@ blocks_storage:
     # CLI flag: -blocks-storage.tsdb.wal-compression-enabled
     [wal_compression_enabled: <boolean> | default = false]
 
+    # TSDB WAL segments files max size (bytes).
+    # CLI flag: -blocks-storage.tsdb.wal-segment-size-bytes
+    [wal_segment_size_bytes: <int> | default = 134217728]
+
     # True to flush blocks to storage on shutdown. If false, incomplete blocks
     # will be reused after restart.
     # CLI flag: -blocks-storage.tsdb.flush-blocks-on-shutdown
     [flush_blocks_on_shutdown: <boolean> | default = false]
 
+    # If TSDB has not received any data for this duration, and all blocks from
+    # TSDB have been shipped, TSDB is closed and deleted from local disk. If set
+    # to positive value, this value should be equal or higher than
+    # -querier.query-ingesters-within flag to make sure that TSDB is not closed
+    # prematurely, which could cause partial query results. 0 or negative value
+    # disables closing of idle TSDB.
+    # CLI flag: -blocks-storage.tsdb.close-idle-tsdb-timeout
+    [close_idle_tsdb_timeout: <duration> | default = 0s]
+
     # limit the number of concurrently opening TSDB's on startup
     # CLI flag: -blocks-storage.tsdb.max-tsdb-opening-concurrency-on-startup
     [max_tsdb_opening_concurrency_on_startup: <int> | default = 10]
diff --git a/docs/blocks-storage/store-gateway.template b/docs/blocks-storage/store-gateway.template
index 8c95335..5f43448 100644
--- a/docs/blocks-storage/store-gateway.template
+++ b/docs/blocks-storage/store-gateway.template
@@ -13,6 +13,13 @@ The store-gateway is **semi-stateful**.
 
 ## How it works
 
+The store-gateway needs to have an almost up-to-date view over the storage bucket, in order to discover blocks belonging to their shard. The store-gateway can keep the bucket view updated in to two different ways:
+
+1. Periodically scanning the bucket (default)
+2. Periodically downloading the [bucket index](./bucket-index.md)
+
+### Bucket index disabled (default)
+
 At startup **store-gateways** iterate over the entire storage bucket to discover blocks for all tenants and download the `meta.json` and index-header for each block. During this initial bucket synchronization phase, the store-gateway `/ready` readiness probe endpoint will fail.
 
 While running, store-gateways periodically rescan the storage bucket to discover new blocks (uploaded by the ingesters and [compactor](./compactor.md)) and blocks marked for deletion or fully deleted since the last scan (as a result of compaction). The frequency at which this occurs is configured via `-blocks-storage.bucket-store.sync-interval`.
@@ -21,6 +28,12 @@ The blocks chunks and the entire index are never fully downloaded by the store-g
 
 _For more information about the index-header, please refer to [Binary index-header documentation](./binary-index-header.md)._
 
+### Bucket index enabled
+
+When bucket index is enabled, the overall workflow is the same but, instead of iterating over the bucket objects, the store-gateway fetch the [bucket index](./bucket-index.md) for each tenant belonging to their shard in order to discover each tenant's blocks and block deletion marks.
+
+_For more information about the bucket index, please refer to [bucket index documentation](./bucket-index.md)._
+
 ## Blocks sharding and replication
 
 The store-gateway optionally supports blocks sharding. Sharding can be used to horizontally scale blocks in a large cluster without hitting any vertical scalability limit.
@@ -48,6 +61,8 @@ The **`shuffle-sharding`** strategy spreads the blocks of a tenant across a subs
 
 The shuffle sharding strategy can be enabled via `-store-gateway.sharding-strategy=shuffle-sharding` and requires the `-store-gateway.tenant-shard-size` flag (or their respective YAML config options) to be set to the default shard size, which is the default number of store-gateway instances each tenant should be sharded to. The shard size can then be overridden on a per-tenant basis setting the `store_gateway_tenant_shard_size` in the limits overrides.
 
+_Please check out the [shuffle sharding documentation](../guides/shuffle-sharding.md) for more information about how it works._
+
 ### Auto-forget
 
 When a store-gateway instance cleanly shutdowns, it automatically unregisters itself from the ring. However, in the event of a crash or node failure, the instance will not be unregistered from the ring, potentially leaving a spurious entry in the ring forever.
@@ -56,6 +71,16 @@ To protect from this, when an healthy store-gateway instance finds another insta
 
 This feature is called **auto-forget** and is built into the store-gateway.
 
+### Zone-awareness
+
+The store-gateway replication optionally supports [zone-awareness](../guides/zone-replication.md). When zone-aware replication is enabled and the blocks replication factor is > 1, each block is guaranteed to be replicated across store-gateway instances running in different availability zones.
+
+**To enable** the zone-aware replication for the store-gateways you should:
+
+1. Configure the availability zone for each store-gateway via the `-store-gateway.sharding-ring.instance-availability-zone` CLI flag (or its respective YAML config option)
+2. Enable blocks zone-aware replication via the `-store-gateway.sharding-ring.zone-awareness-enabled` CLI flag (or its respective YAML config option). Please be aware this configuration option should be set to store-gateways, queriers and rulers.
+3. Rollout store-gateways, queriers and rulers to apply the new configuration
+
 ## Caching
 
 The store-gateway supports the following caches:
@@ -113,6 +138,7 @@ Store-gateway and [querier](./querier.md) can use memcached for caching bucket m
 - List of blocks per tenant
 - Block's `meta.json` content
 - Block's `deletion-mark.json` existence and content
+- Tenant's `bucket-index.json.gz` content
 
 Using the metadata cache can significantly reduce the number of API calls to object storage and protects from linearly scale the number of these API calls with the number of querier and store-gateway instances (because the bucket is periodically scanned and synched by each querier and store-gateway).
 
diff --git a/docs/case-studies/_index.md b/docs/case-studies/_index.md
index ba12af6..12201c5 100644
--- a/docs/case-studies/_index.md
+++ b/docs/case-studies/_index.md
@@ -3,6 +3,6 @@ title: "Case Studies"
 linkTitle: "Case Studies"
 slug: case-studies
 no_section_index_title: true
-weight: 11
+weight: 9
 menu:
 ---
diff --git a/docs/case-studies/buoyant-cloud.md b/docs/case-studies/buoyant-cloud.md
new file mode 100644
index 0000000..f4ac0cf
--- /dev/null
+++ b/docs/case-studies/buoyant-cloud.md
@@ -0,0 +1,83 @@
+---
+title: "Buoyant Cloud and Cortex: Standing on the shoulders of Linkerd and Prometheus"
+linkTitle: "Buoyant Cloud"
+weight: 3
+slug: buoyant-cloud
+---
+
+[Buoyant](https://buoyant.io), the creator of [Linkerd](https://linkerd.io), has had a close relationship with Prometheus and related technologies for years. As of today, that relationship now includes [Cortex](https://cortexmetrics.io/).
+
+Linkerd is an open source service mesh for Kubernetes, and part of the CNCF, along with Prometheus and Cortex. Linkerd provides three key classes of features: observability, reliability, and security—all without requiring any changes to your code. That first pillar, observability, has motivated deep Prometheus integration, and is the focus of this case study.
+
+## Linkerd x Prometheus
+
+In 2016, Linkerd 1.0 shipped with a [visualization module](https://linkerd.io/2016/10/04/a-service-mesh-for-kubernetes-part-i-top-line-service-metrics/#step-3-install-linkerd-viz) built with Prometheus and Grafana. With the release of [Linkerd 2.0 in 2018](https://linkerd.io/2018/09/18/announcing-linkerd-2-0/), Prometheus and Grafana were promoted to first-class components. That evolution was documented in a blog post entitled [Prometheus the Right Way](https://linkerd.io/2018/05/17/prometheus-the-right-way-lessons-learned-evolving-conduits-prometheus-integration/), and a KubeCon North America 2018 talk entitled [Linkerd 2.0, Now with Extra Prometheus](https://www.youtube.com/watch?v=bnDWApsH36Y), both co-authored by [Frederic Branczyk](https://twitter.com/fredbrancz) of Polar Signals and [Andrew Seigner](https://twitter.com/siggy) of Buoyant.
+
+This deep integration in Linkerd 2.0 provided out-of-the-box golden metrics, that is, success rate, request rate, and latency, across all your Kubernetes workloads.
+
+![Linkerd Grafana](/images/case-studies/bcloud-linkerd-grafana.png)
+_Linkerd 2.0 with integrated Prometheus and Grafana, out-of-the-box golden metrics_
+
+## Buoyant x Cortex
+
+Building on the success of Linkerd, Buoyant has created [Buoyant Cloud](https://buoyant.cloud/), a global platform health dashboard for Kubernetes. Leveraging Linkerd's integration with Prometheus, Buoyant Cloud rolls up Linkerd metrics across all Kubernetes clusters to provide global platform-wide observability, including advanced features such as cross-cluster Service Level Objectives for success rate and latency.
+
+![Buoyant Cloud Screenshot](/images/case-studies/bcloud-screenshot.jpg)
+_Service Level Objectives in Buoyant Cloud_
+
+### Buoyant Cloud Prototyping with Prometheus
+
+To enable observability in Buoyant Cloud, customers install an agent into their Kubernetes clusters. That agent gathers metrics from Linkerd and sends them up to Buoyant Cloud. Early prototypes of Buoyant Cloud received these metrics, wrote them to [pushgateway](https://github.com/prometheus/pushgateway), and then our own larger Prometheus would scrape metrics from there. While this had the nice property that Linkerd metrics looked the same in Buoyant Cloud as they did in individual Linkerd clusters, gathering metrics across all customers into a single Prometheus instance created an inherent scaling limitation, and a single-point-of-failure.
+
+### Observability Requirements
+
+Thinking beyond our early prototypes, we came up with four core requirements for our observability system:
+
+1. Scalable - To support all Kubernetes clusters across our growing customer base, we needed a system that could scale as-needed. Bonus points if we could scale our reads and writes independently.
+2. Reliable - Users of Linkerd expect nothing less.
+3. Multi-tenant - To provide an extra layer of security and performance isolation between customers.
+4. Prometheus-compatible - To give our customers a familiar API, and to allow a drop-in replacement for our prototype Prometheus instance.
+
+Those first two requirements in particular are not compatible with a single instance of anything. Even Prometheus, which does exceptionally well as a single instance, is intentionally not designed as a distributed, scalable system.
+
+Take a look at those requirements again, then go to the [Cortex website](https://cortexmetrics.io/):
+
+![Cortex Homepage](/images/case-studies/bcloud-cortex-homepage.png)
+_[https://cortexmetrics.io/](https://cortexmetrics.io/)_
+
+This was not intentional, but it was a fortuitous coincidence. Cortex's one-line description of itself literally satisfied all four of our requirements for Buoyant Cloud.
+
+### Buoyant Cloud Production-Ready with Cortex
+
+We set about building a proof of concept to validate whether Cortex could be a viable replacement for Buoyant Cloud's prototype Prometheus-based observability.
+
+#### Development environment
+
+The very first attempt at Cortex integration in our development environment was surprisingly smooth, thanks largely to Cortex's [single instance, single process](https://cortexmetrics.io/docs/getting-started/getting-started-blocks-storage/#single-instance-single-process) mode. This enabled our developers to operate all of Cortex's services as a single process in our docker-compose development environment, with no dependencies.
+
+#### (Almost) a drop-in replacement
+
+Cortex provides a Prometheus-compatible API. To enable multi-tenancy, you must set a [X-Scope-OrgID](https://cortexmetrics.io/docs/guides/auth/) header on every request with a unique identifier for the tenant. We already had a unique public identifier for each Buoyant Cloud customer, so that was a natural fit for this header. Modifying all reads and writes to Prometheus to set this header was a relatively straightforward code change, considering we were about to completely swap out a back-end storage system.
+
+#### Blocks Storage
+
+Being the creators of Linkerd, we care a lot about operational complexity. Thus, it was no surprise that we wanted to minimize operational complexity and cost for ourselves in maintaining Buoyant Cloud. Cortex's [Chunk Storage](https://cortexmetrics.io/docs/getting-started/getting-started-chunks-storage/) was a concern here. Operating our own Cassandra cluster would incur developer time, and paying for DynamoDB, BigTable, or Azure Cosmos DB would incur cost. Cortex's [Blocks Storage](https://cortexmetrics.io/docs/blocks-storage/) removed this complexity and cost by relying on a simple and cheap object store, such as S3, GCS, or Azure Storage. At the time, Blocks Storage was still marked experimental. That's when we hopped into a Q&A at a KubeCon EU 2020 talk, [Scaling Prometheus: How We Got Some Thanos Into Cortex](https://www.youtube.com/watch?v=Z5OJzRogAS4) by [Thor Hansen](https://twitter.com/thor4hansen) of HashiCorp and [Marco Pracucci](https://twitter.com/pracucci) of Grafana Labs. We asked the Cortex maintainers how close to General Availability they felt Blocks Storage was. While wisely not guaranteeing a date, they hinted it may be ready by the next Cortex release (and that hint turned out to be true, Blocks Storage was marked stable in [Cortex 1.4.0](https://github.com/cortexproject/cortex/releases/tag/v1.4.0)!). This gave us enough confidence to build our proof of concept around Blocks Storage.
+
+#### Recording Rules
+
+Buoyant Cloud uses recording rules for important success rate and latency metrics. One unexpected challenge was that Cortex's multi-tenancy applies to recording rules. This meant that for every customer, we needed to push an identical set of recording rules to the [Cortex Ruler API](https://cortexmetrics.io/docs/api/#ruler). We ended up writing a small background process that continually checks our database for new customers, and pushes recording rules when they appear.
+
+#### Cortex in Prod: Writes, then reads
+
+Once all the pieces were in place, we enabled production writes to our new Cortex cluster. We continued writing to and reading from our existing Prometheus. Writing to Cortex and Prometheus simultaneously enabled validation of three things. We could 1) Evaluate Cortex's read performance under full production write load, 2) ensure Cortex query results matched Prometheus, and 3) gather enough historical metrics in Cortex to minimize data loss for our customers.
+
+When we were satisfied with all three of these validation steps, we switched all reads to Cortex. This was the smallest code change in the entire migration. We simply swapped out a few command-line flags pointing to `prometheus:9009` with `query-frontend.cortex.svc.cluster.local:9009/api/prom`. Boom! It all worked!
+
+![Cortex Launch](/images/case-studies/bcloud-cortex-launch.png)
+_The moment we turned on Cortex reads in production (numbers do not reflect full production load)._
+
+## Looking Ahead
+
+Our mission with Buoyant Cloud is to enable our customers to build observable, scalable, and secure Kubernetes platforms, without the complexity of stitching together lots of components.
+
+Users of Linkerd expect their observability to "just work", and expect it to be something they are already familiar with and have tools to integrate with. For Linkerd running on a single Kubernetes cluster, Prometheus fits the bill perfectly. For Buoyant Cloud, we believe Cortex can deliver that same familiarity and integration story for all Kubernetes clusters across all customers.
diff --git a/docs/chunks-storage/_index.md b/docs/chunks-storage/_index.md
new file mode 100644
index 0000000..7f38eec
--- /dev/null
+++ b/docs/chunks-storage/_index.md
@@ -0,0 +1,36 @@
+---
+title: "Chunks Storage"
+linkTitle: "Chunks Storage"
+weight: 4
+menu:
+---
+
+The chunks storage is a Cortex storage engine which stores each single time series into a separate object called _chunk_. Each chunk contains the samples for a given period (defaults to 12 hours). Chunks are then indexed by time range and labels, in order to provide a fast lookup across many (over millions) chunks. For this reason, the Cortex chunks storage requires two backend storages: a key-value store for the index and an object store for the chunks.
+
+The supported backends for the **index store** are:
+
+* [Amazon DynamoDB](https://aws.amazon.com/dynamodb)
+* [Google Bigtable](https://cloud.google.com/bigtable)
+* [Apache Cassandra](https://cassandra.apache.org)
+
+The supported backends for the **chunks store** are:
+
+* [Amazon DynamoDB](https://aws.amazon.com/dynamodb)
+* [Google Bigtable](https://cloud.google.com/bigtable)
+* [Apache Cassandra](https://cassandra.apache.org)
+* [Amazon S3](https://aws.amazon.com/s3)
+* [Google Cloud Storage](https://cloud.google.com/storage/)
+* [Microsoft Azure Storage](https://azure.microsoft.com/en-us/services/storage/)
+
+## Storage versioning
+
+The chunks storage is based on a custom data format. The **chunks and index format are versioned**: this allows Cortex operators to upgrade the cluster to take advantage of new features and improvements. This strategy enables changes in the storage format without requiring any downtime or complex procedures to rewrite the stored data. A set of schemas are used to map the version while reading and writing time series belonging to a specific period of time.
+
+The current schema recommendation is the **v9 schema** for most use cases and **v10 schema** if you expect to have very high cardinality metrics (v11 is still experimental). For more information about the schema, please check out the [schema configuration](schema-config.md).
+
+## Guides
+
+The following step-by-step guides can help you setting up Cortex running with the chunks storage:
+
+- [Running Cortex chunks storage in Production](../guides/running-chunks-storage-in-production.md)
+- [Running Cortex chunks storage with Cassandra](../guides/running-chunks-storage-with-cassandra.md)
diff --git a/docs/production/storage-aws.md b/docs/chunks-storage/aws-tips.md
similarity index 87%
rename from docs/production/storage-aws.md
rename to docs/chunks-storage/aws-tips.md
index cd1707a..cef7034 100644
--- a/docs/production/storage-aws.md
+++ b/docs/chunks-storage/aws-tips.md
@@ -1,15 +1,13 @@
 ---
-title: "Running Cortex with AWS Services"
-linkTitle: "Running Cortex with AWS Services"
-weight: 2
-slug: aws
+title: "AWS tips"
+linkTitle: "AWS tips"
+weight: 10
+slug: aws-tips
 ---
 
-[this is a work in progress]
+This page shares some tips and things to take in consideration when running Cortex chunks storage on AWS.
 
-See also the [Running in Production](running.md) document.
-
-## Credentials
+## AWS Credentials
 
 You can supply credentials to Cortex by setting environment variables
 `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` (and `AWS_SESSION_TOKEN`
@@ -20,7 +18,7 @@ if you use MFA), or use a short-term token solution such as
 
 Note that the choices for the chunks storage backend are: "chunks" of
 timeseries data in S3 and index in DynamoDB, or everything in DynamoDB.
-Using just S3 is not an option, unless you use the [blocks storage](../../blocks-storage/) engine.
+Using just S3 is not an option, unless you use the [blocks storage](../blocks-storage/_index.md) engine.