github.com/grafana/pyroscope@v1.18.0/docs/sources/deploy-kubernetes/helm.md (about) 1 --- 2 description: Learn how to get started with Pyroscope using the Helm chart. 3 menuTitle: Deploy with Helm 4 title: Deploy Pyroscope using the Helm chart 5 weight: 50 6 --- 7 8 # Deploy Pyroscope using the Helm chart 9 10 The [Helm](https://helm.sh/) chart allows you to configure, install, and upgrade Pyroscope within a Kubernetes cluster. 11 12 ## Before you begin 13 14 These instructions are common across any flavor of Kubernetes and assume that you know how to install, configure, and operate a Kubernetes cluster as well as use `kubectl`. 15 16 Hardware requirements: 17 18 - A single Kubernetes node with a minimum of 4 cores and 16GiB RAM 19 20 Software requirements: 21 22 - Kubernetes 1.20 or higher 23 - The `kubectl` command for your version of Kubernetes 24 - Helm 3 or higher 25 26 Verify that you have: 27 28 - Access to the Kubernetes cluster 29 - Persistent storage is enabled in the Kubernetes cluster, which has a default storage class set up. You can [change the default StorageClass](https://kubernetes.io/docs/tasks/administer-cluster/change-default-storage-class/). 30 - DNS service works in the Kubernetes cluster 31 32 ## Install the Helm chart in a custom namespace 33 34 Use a custom namespace so that you don't have to overwrite the default namespace later in the procedure. 35 36 1. Create a unique Kubernetes namespace, for example `pyroscope-test`: 37 38 ```console 39 kubectl create namespace pyroscope-test 40 ``` 41 42 For more details, see the Kubernetes documentation about [Creating a new namespace](https://kubernetes.io/docs/tasks/administer-cluster/namespaces/#creating-a-new-namespace). 43 44 1. Set up a Helm repository using the following commands: 45 46 ```console 47 helm repo add grafana https://grafana.github.io/helm-charts 48 helm repo update 49 ``` 50 51 {{% admonition type="note" %}} 52 The Helm chart at [https://grafana.github.io/helm-charts](https://grafana.github.io/helm-charts) is a publication of the source code at [**grafana/pyroscope**](https://github.com/grafana/pyroscope/tree/main/operations/pyroscope/helm/pyroscope). 53 {{% /admonition %}} 54 55 1. Install Pyroscope using the Helm chart using one of the following options: 56 57 - Option A: Install Pyroscope as single binary. Use this mode _only when you need one Pyroscope instance_. Multiple instances won't share information with each other. 58 59 ```bash 60 helm -n pyroscope-test install pyroscope grafana/pyroscope 61 ``` 62 63 {{% admonition type="note" %}} 64 The output of the command contains the query URLs necessary for the following steps, so for a single-binary setup, it will look like this: 65 66 ``` 67 [...] 68 The in-cluster query URL is: 69 http://pyroscope.pyroscope-test.svc.cluster.local.:4040/ 70 [...] 71 ``` 72 {{% /admonition %}} 73 74 - Option B: Install Pyroscope as multiple microservices. In this mode, as you scale out the number of instances, they will share a singular backend for storage and querying. 75 76 ```bash 77 # Gather the default config for micro-services 78 curl -Lo values-micro-services.yaml https://raw.githubusercontent.com/grafana/pyroscope/main/operations/pyroscope/helm/pyroscope/values-micro-services.yaml 79 helm -n pyroscope-test install pyroscope grafana/pyroscope --values values-micro-services.yaml 80 ``` 81 82 {{% admonition type="note" %}} 83 The output of the command contains the query URLs necessary for the following steps, so for a microservice setup, it will look like this: 84 85 ``` 86 [...] 87 The in-cluster query URL is: 88 http://pyroscope-querier.pyroscope-test.svc.cluster.local.:4040 89 [...] 90 ``` 91 {{% /admonition %}} 92 93 1. Check the statuses of the Pyroscope pods: 94 95 ```bash 96 kubectl -n pyroscope-test get pods 97 ``` 98 99 The results look similar to this when you are in microservices mode: 100 101 ```bash 102 kubectl -n pyroscope-test get pods 103 NAME READY STATUS RESTARTS AGE 104 pyroscope-agent-7d75b4f9dc-xwpsw 1/1 Running 0 3m23s 105 pyroscope-distributor-7c474947c-2p5cc 1/1 Running 0 3m23s 106 pyroscope-distributor-7c474947c-xbszv 1/1 Running 0 3m23s 107 pyroscope-ingester-0 1/1 Running 0 5s 108 pyroscope-ingester-1 1/1 Running 0 37s 109 pyroscope-ingester-2 1/1 Running 0 69s 110 pyroscope-minio-0 1/1 Running 0 3m23s 111 pyroscope-querier-66bf58dfcc-89gb8 1/1 Running 0 3m23s 112 pyroscope-querier-66bf58dfcc-p7lnc 1/1 Running 0 3m23s 113 pyroscope-querier-66bf58dfcc-zbggm 1/1 Running 0 3m23s 114 ``` 115 116 1. Wait until all the pods have a status of `Running` or `Completed`, which might take a few minutes. 117 118 ## Query profiles in Grafana 119 120 1. Install Grafana in the same Kubernetes cluster where you installed Pyroscope. 121 122 ``` 123 helm upgrade -n pyroscope-test --install grafana grafana/grafana \ 124 --set image.repository=grafana/grafana \ 125 --set image.tag=main \ 126 --set env.GF_PLUGINS_PREINSTALL_SYNC=grafana-pyroscope-app \ 127 --set env.GF_AUTH_ANONYMOUS_ENABLED=true \ 128 --set env.GF_AUTH_ANONYMOUS_ORG_ROLE=Admin \ 129 --set env.GF_DIAGNOSTICS_PROFILING_ENABLED=true \ 130 --set env.GF_DIAGNOSTICS_PROFILING_ADDR=0.0.0.0 \ 131 --set env.GF_DIAGNOSTICS_PROFILING_PORT=9094 \ 132 --set-string 'podAnnotations.profiles\.grafana\.com/cpu\.scrape=true' \ 133 --set-string 'podAnnotations.profiles\.grafana\.com/cpu\.port=9094' \ 134 --set-string 'podAnnotations.profiles\.grafana\.com/memory\.scrape=true' \ 135 --set-string 'podAnnotations.profiles\.grafana\.com/memory\.port=9094' \ 136 --set-string 'podAnnotations.profiles\.grafana\.com/goroutine\.scrape=true' \ 137 --set-string 'podAnnotations.profiles\.grafana\.com/goroutine\.port=9094' 138 ``` 139 140 For details, see [Deploy Grafana on Kubernetes](/docs/grafana/latest/setup-grafana/installation/kubernetes/). 141 142 1. Port-forward Grafana to `localhost`, by using the `kubectl` command: 143 144 ```bash 145 kubectl port-forward -n pyroscope-test service/grafana 3000:80 146 ``` 147 148 1. In a browser, go to the Grafana server at [http://localhost:3000](http://localhost:3000). 149 1. On the left side, go to **Configuration** > **Data sources**. 150 1. Configure a Pyroscope data source to query the Pyroscope server, by using the following settings: 151 152 | Field | Value | 153 | ----- | ------------------------------------------------------------ | 154 | Name | Pyroscope | 155 | URL | `http://pyroscope-querier.pyroscope-test.svc.cluster.local.:4040/` | 156 157 To add a data source, refer to [Add a data source](/docs/grafana/latest/datasources/add-a-data-source/). 158 159 1. Verify success: 160 161 You should be able to query profiles in [Grafana Explore](/docs/grafana/latest/explore/), 162 as well as create dashboard panels by using your newly configured Pyroscope data source. 163 164 ## Optional: Persistently add data source 165 166 The deployment of Grafana has no persistent database, so it will not retain settings like the data source configuration across restarts. 167 168 To ensure the data source gets provisioned at start-up, create the following `datasources.yaml` file: 169 170 ```yaml 171 datasources: 172 pyroscope.yaml: 173 apiVersion: 1 174 datasources: 175 - name: Pyroscope 176 type: grafana-pyroscope-datasource 177 uid: pyroscope-test 178 url: http://pyroscope-querier.pyroscope-test.svc.cluster.local.:4040/ 179 ``` 180 181 Modify the Helm deployment by running: 182 183 ```bash 184 helm upgrade -n pyroscope-test --reuse-values grafana grafana/grafana \ 185 --values datasources.yaml 186 ``` 187 188 ## Optional: Scrape your own workload's profiles 189 190 The Pyroscope chart uses a default configuration that causes its agent to scrape Pods, provided they have the correct annotations. 191 This functionality uses [relabel_config](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#relabel_config) and [kubernetes_sd_config](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) you might be familiar with the Prometheus or Grafana Alloy configuration. 192 193 To get Pyroscope to scrape pods, you must add the following annotations to the Pods: 194 195 ```yaml 196 metadata: 197 annotations: 198 profiles.grafana.com/memory.scrape: "true" 199 profiles.grafana.com/memory.port: "8080" 200 profiles.grafana.com/cpu.scrape: "true" 201 profiles.grafana.com/cpu.port: "8080" 202 profiles.grafana.com/goroutine.scrape: "true" 203 profiles.grafana.com/goroutine.port: "8080" 204 ``` 205 206 The above example will scrape the `memory`, `cpu` and `goroutine` profiles from the `8080` port of the Pod. 207 208 Each profile type has a set of corresponding annotations which allows customization of scraping per profile type. 209 210 ```yaml 211 metadata: 212 annotations: 213 profiles.grafana.com/<profile-type>.scrape: "true" 214 profiles.grafana.com/<profile-type>.port: "<port>" 215 profiles.grafana.com/<profile-type>.port_name: "<port-name>" 216 profiles.grafana.com/<profile-type>.scheme: "<scheme>" 217 profiles.grafana.com/<profile-type>.path: "<profile_path>" 218 ``` 219 220 The full list of profile types supported by annotations is `cpu`, `memory`, `goroutine`, `block` and `mutex`. 221 222 The following table describes the annotations: 223 224 | Annotation | Description | Default | 225 | ---------- | ----------- | ------- | 226 | `profiles.grafana.com/<profile-type>.scrape` | Whether to scrape the profile type. | `false` | 227 | `profiles.grafana.com/<profile-type>.port` | The port to scrape the profile type from. | `` | 228 | `profiles.grafana.com/<profile-type>.port_name` | The port name to scrape the profile type from. | `` | 229 | `profiles.grafana.com/<profile-type>.scheme` | The scheme to scrape the profile type from. | `http` | 230 | `profiles.grafana.com/<profile-type>.path` | The path to scrape the profile type from. | default golang path | 231 232 By default, the port is discovered using named port `http2` or ending with `-metrics` or `-profiles`. 233 If you don't have a named port, the scraping target is dropped. 234 235 If you don't want to use the port name, then you can use the `profiles.grafana.com/<profile-type>.port` annotation to statically specify the port number.