github.com/grafana/pyroscope@v1.18.0/docs/sources/upgrade-guide/_index.md (about)

     1  ---
     2  title: Upgrade your Grafana Pyroscope installation
     3  menuTitle: Upgrade
     4  description: Upgrade your Pyroscope installation to the latest version.
     5  weight: 350
     6  keywords:
     7    - pyroscope
     8    - phlare
     9    - upgrade
    10    - upgrading
    11  ---
    12  
    13  # Upgrade your Grafana Pyroscope installation
    14  
    15  You can upgrade an existing Pyroscope installation to the next version.
    16  However, any new release has the potential to have breaking changes that should be tested in a non-production environment prior to rolling these changes to production.
    17  
    18  The upgrade process changes for each version, depending upon the changes made for the subsequent release.
    19  
    20  This upgrade guide applies to on-premise installations and not for Grafana Cloud.
    21  
    22  ## Upgrade to Pyroscope 1.0
    23  
    24  Version 1.0 of Pyroscope is a major release that includes breaking changes.
    25  This guide explains how to upgrade to v1.0 from previous versions.
    26  
    27  This document describes in detail the changes that we've made to Pyroscope and how they affect you. For convenience, at the end of this guide we provide short checklists for you to follow.
    28  
    29  ### New architecture
    30  
    31  We're excited to announce the main change to Pyroscope since its acquisition by Grafana Labs: a new horizontally scalable architecture.
    32  Our team took unique learnings that we have gained over the years about profiling data and combined it with a battle-tested Cortex architecture that powers other Grafana Labs databases such as Loki, Mimir, and Tempo.
    33  This means you can now provision Pyroscope as a highly available service backed by cheap object storage, with the ability to scale up and down as needed.
    34  
    35  ### License change
    36  
    37  Pyroscope server is now licensed under the [AGPLv3](https://opensource.org/license/agpl-v3/). All of our client integrations are still licensed under the [Apache 2.0 license](https://opensource.org/license/apache-2-0/).
    38  
    39  Pyroscope was founded in 2020 to build a sustainable business around the open source Pyroscope project, so that revenue from our commercial offerings could be re-invested in the technology and the community.
    40  
    41  We believe that the AGPLv3 license is the best way forward for Pyroscope. It allows us to continue to build a sustainable business around Pyroscope, while also ensuring that the project remains open source and that the community can continue to use and contribute to it.
    42  
    43  ### New Docker repository
    44  
    45  The new Pyroscope Docker repository is located at [grafana/pyroscope](https://hub.docker.com/r/grafana/pyroscope). The old repository at [pyroscope/pyroscope](https://hub.docker.com/r/pyroscope/pyroscope) will no longer be updated.
    46  
    47  ### Breaking changes
    48  
    49  Making big leaps means that we have to break some things. We've tried to minimize the impact of these changes as much as possible, but some of them are unavoidable. We apologize for any inconvenience this may cause. We encourage you to contribute to the community by creating new issues or upvoting existing ones with an `og-feature` label in the [Pyroscope GitHub repository](https://github.com/grafana/pyroscope/labels/og-feature).
    50  
    51  #### Storage format changes
    52  
    53  The new local storage format is entirely new, optimized for object storage. We do not support migrating from the old storage format to the new one. This means that you will lose data when upgrading to v1.0.
    54  
    55  #### Configuration file changes
    56  
    57  The configuration file parameters as well as the default location for the configuration file have changed. The old config file is usually located at `/etc/pyroscope/server.yml` and the new config file is at `/etc/pyroscope/config.yaml`. You can find detailed descriptions of all configuration parameters [here](../configure-server/reference-configuration-parameters/).
    58  
    59  #### Dropping support for certain subcommands
    60  
    61  We stripped the pyroscope CLI of all subcommands that were related to the client side of profiling and only kept the ones that are related to the server side. This means that the following subcommands are no longer supported:
    62  * `pyroscope exec`
    63  * `pyroscope adhoc`
    64  * `pyroscope connect`
    65  * `pyroscope agent`
    66  
    67  This strategic shift has been in the works for some time as we transition away from CLI-based profiling towards embracing native integrations.
    68  Moving forward, we encourage users to take advantage of native integrations tailored to specific programming languages, such as pip packages for Python, .NET packages for .NET applications, Ruby gems for Ruby applications, and so on.
    69  The [eBPF integration](https://grafana.com/docs/pyroscope/<PYROSCOPE_VERSION>/configure-client/grafana-alloy/ebpf/) is also a good way to get profiling data for your whole cluster.
    70  
    71  By adopting native integrations, we aim to provide users with a more streamlined and efficient profiling experience, leveraging language-specific tools and libraries to deliver better performance, ease of use, and seamless integration with their respective applications.
    72  
    73  #### Dropping OAuth support
    74  
    75  OAuth was implemented with SQLite, which made sense when Pyroscope was a single binary, but is no longer feasible with the new distributed architecture. Transitioning to a new distributed architecture means that we had to drop support for OAuth.
    76  
    77  Our recommendation is to use Grafana for visualizing your profiling data. [Grafana 10](/docs/grafana/latest/whatsnew/whats-new-in-v10-0/) comes with native support for Pyroscope and very mature support for OAuth as well as many other authentication methods.
    78  
    79  #### API stability
    80  
    81  Even though this is a major release, the HTTP API is not yet stable and is subject to changes. Going forward we will do our best to keep the APIs backwards compatible and minimize the impact of these changes and provide a migration path.
    82  
    83  ### Community call to action
    84  
    85  Pyroscope v1.0 comes with a huge architectural change and we've tried to minimize the impact of these changes as much as possible, but some of them are unavoidable. Our goal is for our users to have as smooth of a transition as possible. Therefore, we encourage you to contribute to the community by creating new issues or upvoting existing ones with an `og-feature` label in the [Pyroscope GitHub repository](https://github.com/grafana/pyroscope/labels/og-feature). Thank you for your feedback and engagement, which play a crucial role in shaping the future of Pyroscope.
    86  
    87  
    88  ### Upgrade Checklists for v1.0
    89  
    90  We provide the following checklists to help you upgrade to v1.0.
    91  
    92  #### Upgrade Checklist for Docker deployments
    93  
    94  When upgrading to v1.0, we suggest that you follow this checklist:
    95  * Migrate your configuration from the old format to the new format (old config is usually located at `/etc/pyroscope/server.yml` and the new config is at `/etc/pyroscope/config.yaml`). There's a detailed description of all configuration parameters [here](../configure-server/reference-configuration-parameters/).
    96  * Upgrade docker image from `pyroscope/pyroscope` to `grafana/pyroscope`. Link to the new docker image is [here](https://hub.docker.com/r/grafana/pyroscope).
    97  * Delete old data (typically found at `/var/lib/pyroscope`).
    98  
    99  #### Upgrade Checklist for Helm deployments
   100  
   101  When upgrading to v1.0, we suggest that you follow this checklist:
   102  
   103  * Migrate your configuration from the old format to the new format (old config is usually located at `/etc/pyroscope/server.yml` and the new config is at `/etc/pyroscope/config.yaml`). There's a detailed description of all configuration parameters [here](../configure-server/reference-configuration-parameters/).
   104  * Delete the old Helm chart:
   105    ```bash
   106    helm delete pyroscope # replace pyroscope with the name you used when installing the chart
   107    ```
   108  * Install the new Helm chart:
   109    ```bash
   110    kubectl create namespace pyroscope
   111    helm repo add grafana https://grafana.github.io/helm-charts
   112    helm repo update
   113    helm -n pyroscope install pyroscope grafana/pyroscope
   114    ```
   115    For more information on how to install the Helm chart, see our Helm documentation [here](../deploy-kubernetes/).