Skip to content

Commit fd22811

Browse files
Cortex-DMSDonna-Marie Smith
Cortex-DMS
and
Donna-Marie Smith
authored
Feature/22059 observability upgrade instructions (#157)
* instructions to perform the observability platform upgrade as well as instructions on how to upgrade the dashboards --------- Co-authored-by: Donna-Marie Smith <[email protected]>
1 parent b95cf4d commit fd22811

File tree

18 files changed

+627
-3
lines changed

18 files changed

+627
-3
lines changed

‎content/en/docs/2024.7/Guides/upgrade-observability/_index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: "Upgrade Observability"
3+
linkTitle: "Upgrade Observability"
4+
description: "Information about upgrading your observability platform for {{% ctx %}}."
5+
weight: 1000
6+
---

‎content/en/docs/2024.7/Guides/upgrade-observability/cloud/_index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: "Cloud"
3+
linkTitle: "Cloud"
4+
description: "Information about upgrading a cloud-hosted observability platform for {{% ctx %}}."
5+
weight: 500
6+
---

‎content/en/docs/2024.7/Guides/upgrade-observability/cloud/grafana/_index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: "Grafana"
3+
linkTitle: "Grafana"
4+
description: "Information about upgrading a cloud-hosted Grafana platform for {{% ctx %}}."
5+
weight: 1000
6+
---

‎content/en/docs/2024.7/Guides/upgrade-observability/cloud/grafana/prerequisites.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: "Prerequisites"
3+
linkTitle: "Prerequisites"
4+
description: "The prerequisites required before performing the observability upgrade."
5+
weight: 1
6+
---
7+
8+
# {{% param title %}}
9+
10+
## Verify Old Version
11+
12+
1. Navigate to your Grafana website e.g. `https://{Team URL}.grafana.net`
13+
1. Login to Grafana.
14+
1. Open the *Dashboards* page via the menu on the left sidebar.
15+
1. Select the folder that hosts the Cortex Dashboards, e.g. *Cortex*
16+
1. Click the *Flow Execution Requests* dashboard to open it.
17+
1. Change the time period to be *Last 90 days* and confirm data is present.
18+
1. Make a note of values returned in the Overview tiles, or alternatively take a screenshot of the dashboard, to use later to verify the upgrade.
19+
20+
## Make Artefacts Available
21+
22+
1. Download the required artefacts to a folder on your machine:
23+
24+
* [Promtail 3.0.0][] archive.
25+
* [Promtail Install][] archive.
26+
27+
1. Extract the downloaded `promtail-windows-amd64.exe` archive to a folder with the same name.
28+
1. Extract the downloaded `Promtail.Install` archive to a folder with the same name.
29+
30+
## Backup Old Files
31+
32+
On each Application Server that Promtail is installed on:
33+
34+
1. Create a folder called `Observability Backups` in a known location.
35+
1. Open File Explorer and navigate to the location where Promtail is running from, e.g. `C:\Promtail`.
36+
1. Copy the `promtail-local-config.yaml` file and save it to the `Observability Backups` folder created at step 1.
37+
38+
## Next Steps?
39+
40+
1. [Upgrade Promtail][]
41+
42+
[Promtail 3.0.0]: {{< url path="Grafana.SelfManaged.Downloads.Promtail.3.0.0.PromtailInstallZip" >}}
43+
[Promtail Install]: {{< url path="GitHub.Cortex.Observability.3.0.0.PromtailInstallZip" >}}
44+
[Upgrade Promtail]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.UpgradePromtail" >}}

‎content/en/docs/2024.7/Guides/upgrade-observability/cloud/grafana/try-it-out.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
title: "Try it out"
3+
linkTitle: "Try it out"
4+
description: "Information about trying out the observability platform after upgrade."
5+
weight: 3
6+
---
7+
8+
# {{% param title %}}
9+
10+
This guide describes how to verify that the upgrade has been successful. Please ensure that [Upgrade Promtail][] has been completed before taking these steps.
11+
12+
## Confirm Dashboards Load
13+
14+
1. Navigate to your Grafana website e.g. `https://{Team URL}.grafana.net`
15+
1. Login to Grafana.
16+
1. Open the *Dashboards* page via the menu on the left sidebar.
17+
1. Select the folder that hosts the Cortex Dashboards, e.g. *Cortex*
18+
1. Click the *Flow Execution Requests* dashboard to open it.
19+
1. Change the time period to be *Last 90 days* and confirm data is present.
20+
1. Confirm the data from the previous step is similar to the data captured when [verifying the old version][].
21+
22+
## Confirm New Data is Processed
23+
24+
{{% alert title="Note" %}}
25+
Any flow can be used that exists on the system and can be executed.
26+
{{% / alert %}}
27+
28+
1. Open a web browser and navigate to your installed {{% ctx %}} Gateway URL, e.g. `https://server.domain.com/gateway`, and log in when prompted.
29+
1. Open a flow that you are able to execute on an ad hoc basis.
30+
1. Start the flow.
31+
1. Once the request has completed, in your web browser, navigate to and log in to your configured Grafana.
32+
1. Open the *Dashboards* page via the menu on the left sidebar.
33+
1. Click the folder name that the dashboards were imported to.
34+
1. Click the *Flow Execution Requests* dashboard to open it.
35+
1. The request made at step 1 should be visible on the dashboard.
36+
{{% alert title="Note" %}}
37+
If other requests have been made then there may be more than one request visible on the dashboard.
38+
{{% / alert %}}
39+
1. Open the *Dashboards* page via the menu on the left sidebar.
40+
1. Click the folder name that the dashboards were imported to.
41+
1. Click the *Platform Health* dashboard to open it.
42+
1. The request made at step 1 should be visible on the dashboard.
43+
{{% alert title="Note" %}}
44+
If other requests have been made then there may be more than one request visible on the dashboard.
45+
{{% / alert %}}
46+
47+
[Upgrade Promtail]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.UpgradePromtail" >}}
48+
[verifying the old version]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.VerifyOldVersion" >}}

‎content/en/docs/2024.7/Guides/upgrade-observability/cloud/grafana/upgrade-promtail.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
title: "Upgrade Promtail"
3+
linkTitle: "Upgrade Promtail"
4+
description: "The steps to upgrade Promtail."
5+
weight: 2
6+
---
7+
8+
# {{% param title %}}
9+
10+
This guide describes how to upgrade the Promtail installation. Please ensure that the [Prerequisites] for upgrading Observability have been completed before starting this upgrade.
11+
12+
## Perform Upgrade
13+
14+
{{% alert title="Note" %}}
15+
These steps will need to be performed on all application servers that host a Promtail service.
16+
{{% / alert %}}
17+
18+
1. Log in to the application server.
19+
1. Run Windows PowerShell as Administrator.
20+
1. Change the directory to the folder where Promtail is running from, e.g. `cd C:\Promtail`.
21+
1. Remove the current Promtail installation by executing the following command:
22+
23+
``` powershell
24+
.\Remove-Promtail.ps1
25+
```
26+
27+
1. Click *Yes* when prompted for confirmation that you wish to remove the service.
28+
1. Click *OK* when the successful removal of the Promtail service is confirmed.
29+
1. Open a File Explorer and navigate to the folder where Promtail was running from, e.g. `C:\Promtail`
30+
1. Delete the following files from the directory:
31+
32+
* Install-Promtail.ps1
33+
* nssm.exe
34+
* Promtail-local-config.yaml
35+
* Promtail-windows-amd64.exe
36+
* Remove-Promtail.ps1
37+
* Start-Promtail.ps1
38+
* Stop-Promtail.ps1
39+
40+
1. In File Explorer, navigate to the extracted `promtail-windows-amd64.exe` folder created as part of [Make Artefacts Available][].
41+
1. Copy the `promtail-windows-amd64.exe` file into the folder that Promtail was previously running from, e.g. `C:\Promtail`.
42+
1. In File Explorer, navigate to the extracted `Promtail.Install` folder created as part of [Make Artefacts Available][].
43+
1. Copy the contents of this location into the folder that Promtail was previously running from, e.g. `C:\Promtail`.
44+
1. Open `promtail-local-config.yaml` in a text editor:
45+
46+
* Update the *filename* property under *positions* to be the value found in the [backed up][] version.
47+
* Update the *url* property under *clients* to be the value found in the [backed up][] version.
48+
* Save the new `promtail-local-config.yaml` file.
49+
50+
1. Run Windows PowerShell as Administrator.
51+
1. Change the directory to the folder where the Promtail files have been copied to, e.g. `cd C:\Promtail`.
52+
1. Install Promtail by executing the following command:
53+
54+
``` powershell
55+
.\Install-Promtail.ps1
56+
```
57+
58+
1. Start the Promtail service by executing the following command:
59+
60+
``` powershell
61+
.\Start-Promtail.ps1
62+
```
63+
64+
1. Check that the Promtail service has installed and started correctly:
65+
* Open Services.msc from the Start menu.
66+
* Locate the *Promtail* service and confirm that it is *Running*.
67+
68+
## Next Steps?
69+
70+
1. [Try it out][]
71+
72+
[backed up]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.BackupOldFiles" >}}
73+
[Make Artefacts Available]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.MakeArtefactsAvailable" >}}
74+
[Prerequisites]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.Prerequisites" >}}
75+
[Try it out]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.TryItOut" >}}

‎content/en/docs/2024.7/Guides/upgrade-observability/dashboards/Grafana/_index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: "Grafana"
3+
linkTitle: "Grafana"
4+
description: "Information about upgrading the default Grafana dashboards for your observability platform."
5+
weight: 1000
6+
---

‎content/en/docs/2024.7/Guides/upgrade-observability/dashboards/Grafana/try-it-out.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: "Try it out"
3+
linkTitle: "Try it out"
4+
description: "Information about trying out the observability platform after upgrading the dashboards."
5+
weight: 3
6+
---
7+
8+
# {{% param title %}}
9+
10+
## Confirm New Dashboards Display Data
11+
12+
{{% alert title="Note" %}}
13+
Any flow can be used that exists on the system and can be executed.
14+
{{% / alert %}}
15+
16+
1. Open a web browser and navigate to your installed {{% ctx %}} Gateway URL, e.g. `https://server.domain.com/gateway`, and log in when prompted.
17+
1. Open a flow that you are able to execute on an ad hoc basis.
18+
1. Start the flow.
19+
1. Once the request has completed, in your web browser, navigate to and log in to your configured Grafana.
20+
1. Open the *Dashboards* page via the menu on the left sidebar.
21+
1. Click the folder name that the dashboards were imported to.
22+
1. Click the *Flow Execution Requests* dashboard to open it.
23+
1. The request made at step 1 should be visible on the dashboard.
24+
{{% alert title="Note" %}}
25+
If other requests have been made then there may be more than one request visible on the dashboard.
26+
{{% / alert %}}
27+
1. Open the *Dashboards* page via the menu on the left sidebar.
28+
1. Click the folder name that the dashboards were imported to.
29+
1. Click the *Platform Health* dashboard to open it.
30+
1. The request made at step 1 should be visible on the dashboard.
31+
{{% alert title="Note" %}}
32+
If other requests have been made then there may be more than one request visible on the dashboard.
33+
{{% / alert %}}
34+
35+
[Upgrade Promtail]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.UpgradePromtail" >}}
36+
[verifying the old version]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.VerifyOldVersion" >}}

‎content/en/docs/2024.7/Guides/upgrade-observability/dashboards/Grafana/upgrade-dashboards.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: "Upgrade Dashboards"
3+
linkTitle: "Upgrade Dashboards"
4+
description: "Information about upgrading your Grafana dashboards."
5+
weight: 1
6+
---
7+
8+
# {{% param title %}}
9+
10+
This guide describes how to upgrade the default dashboards that are provided for your observability platform.
11+
12+
## Download the Default Dashboards
13+
14+
1. Download [Grafana.Dashboards.zip][] archive containing the {{% ctx %}} Innovation default dashboards.
15+
1. Extract the content of the downloaded archive to a suitable location.
16+
17+
## Import New Dashboards
18+
19+
1. Log in to your configured Grafana with a user that has the *Admin* role.
20+
1. Go to *Dashboards* via the menu on the left sidebar.
21+
1. Click the *New* button and select *Import* from the drop-down menu.
22+
1. Click the *Upload JSON file* button.
23+
1. Locate the `Flow Execution Requests.json` file [extracted][] from the downloaded `Grafana.Dashboards.zip`.
24+
1. Select the file and click *Open*.
25+
{{% alert title="Note" %}}
26+
You will receive warnings that *A dashboard or folder with the same name already exists* and *Dashboard named 'Flow Execution Requests' in folder 'Cortex' has the same UID*. These can be ignored.
27+
{{% / alert %}}
28+
29+
1. Select the folder in Grafana you wish the dashboard to be saved in, e.g. *Cortex*.
30+
1. Select your configured Loki data source from the dropdown menu.
31+
1. Click *Import (Overwrite)*.
32+
1. Repeat steps 2 - 9 for the `Platform Health.json` file.
33+
34+
## Next Steps?
35+
36+
1. [Try it out][]
37+
38+
[extracted]: {{< url path="Cortex.Guides.UpgradeObservability.Dashboards.Grafana.Download" >}}
39+
[Grafana.Dashboards.zip]: {{< url path="GitHub.Cortex.Observability.3.0.0.GrafanaDashboardsZip" >}}
40+
[Try it out]: {{< url path="Cortex.Guides.UpgradeObservability.Dashboards.Grafana.TryItOut" >}}

‎content/en/docs/2024.7/Guides/upgrade-observability/dashboards/_index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: "Dashboards"
3+
linkTitle: "Dashboards"
4+
description: "Information about upgrading the default dashboards provided for your observability platform."
5+
weight: 1000
6+
---

0 commit comments

Comments
 (0)