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]>

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

@@ -0,0 +1,6 @@
+---
+title: "Upgrade Observability"
+linkTitle: "Upgrade Observability"
+description: "Information about upgrading your observability platform for {{% ctx %}}."
+weight: 1000
+---

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

@@ -0,0 +1,6 @@
+---
+title: "Cloud"
+linkTitle: "Cloud"
+description: "Information about upgrading a cloud-hosted observability platform for {{% ctx %}}."
+weight: 500
+---

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

@@ -0,0 +1,6 @@
+---
+title: "Grafana"
+linkTitle: "Grafana"
+description: "Information about upgrading a cloud-hosted Grafana platform for {{% ctx %}}."
+weight: 1000
+---

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

@@ -0,0 +1,44 @@
+---
+title: "Prerequisites"
+linkTitle: "Prerequisites"
+description: "The prerequisites required before performing the observability upgrade."
+weight: 1
+---
+
+# {{% param title %}}
+
+## Verify Old Version
+
+1. Navigate to your Grafana website e.g. `https://{Team URL}.grafana.net`
+1. Login to Grafana.
+1. Open the *Dashboards* page via the menu on the left sidebar.
+1. Select the folder that hosts the Cortex Dashboards, e.g. *Cortex*
+1. Click the *Flow Execution Requests* dashboard to open it.
+1. Change the time period to be *Last 90 days* and confirm data is present.
+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.
+
+## Make Artefacts Available
+
+1. Download the required artefacts to a folder on your machine:
+
+    * [Promtail 3.0.0][] archive.
+    * [Promtail Install][] archive.
+
+1. Extract the downloaded `promtail-windows-amd64.exe` archive to a folder with the same name.
+1. Extract the downloaded `Promtail.Install` archive to a folder with the same name.
+
+## Backup Old Files
+
+On each Application Server that Promtail is installed on:
+
+1. Create a folder called `Observability Backups` in a known location.
+1. Open File Explorer and navigate to the location where Promtail is running from, e.g. `C:\Promtail`.
+1. Copy the `promtail-local-config.yaml` file and save it to the `Observability Backups` folder created at step 1.
+
+## Next Steps?
+
+1. [Upgrade Promtail][]
+
+[Promtail 3.0.0]:  {{< url path="Grafana.SelfManaged.Downloads.Promtail.3.0.0.PromtailInstallZip" >}}
+[Promtail Install]: {{< url path="GitHub.Cortex.Observability.3.0.0.PromtailInstallZip" >}}
+[Upgrade Promtail]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.UpgradePromtail" >}}

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

@@ -0,0 +1,48 @@
+---
+title: "Try it out"
+linkTitle: "Try it out"
+description: "Information about trying out the observability platform after upgrade."
+weight: 3
+---
+
+# {{% param title %}}
+
+This guide describes how to verify that the upgrade has been successful. Please ensure that [Upgrade Promtail][] has been completed before taking these steps.
+
+## Confirm Dashboards Load
+
+1. Navigate to your Grafana website e.g. `https://{Team URL}.grafana.net`
+1. Login to Grafana.
+1. Open the *Dashboards* page via the menu on the left sidebar.
+1. Select the folder that hosts the Cortex Dashboards, e.g. *Cortex*
+1. Click the *Flow Execution Requests* dashboard to open it.
+1. Change the time period to be *Last 90 days* and confirm data is present.
+1. Confirm the data from the previous step is similar to the data captured when [verifying the old version][].
+
+## Confirm New Data is Processed
+
+{{% alert title="Note" %}}
+Any flow can be used that exists on the system and can be executed.
+{{% / alert %}}
+
+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.
+1. Open a flow that you are able to execute on an ad hoc basis.
+1. Start the flow.
+1. Once the request has completed, in your web browser, navigate to and log in to your configured Grafana.
+1. Open the *Dashboards* page via the menu on the left sidebar.
+1. Click the folder name that the dashboards were imported to.
+1. Click the *Flow Execution Requests* dashboard to open it.
+1. The request made at step 1 should be visible on the dashboard.
+{{% alert title="Note" %}}
+If other requests have been made then there may be more than one request visible on the dashboard.
+{{% / alert %}}
+1. Open the *Dashboards* page via the menu on the left sidebar.
+1. Click the folder name that the dashboards were imported to.
+1. Click the *Platform Health* dashboard to open it.
+1. The request made at step 1 should be visible on the dashboard.
+{{% alert title="Note" %}}
+If other requests have been made then there may be more than one request visible on the dashboard.
+{{% / alert %}}
+
+[Upgrade Promtail]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.UpgradePromtail" >}}
+[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

@@ -0,0 +1,75 @@
+---
+title: "Upgrade Promtail"
+linkTitle: "Upgrade Promtail"
+description: "The steps to upgrade Promtail."
+weight: 2
+---
+
+# {{% param title %}}
+
+This guide describes how to upgrade the Promtail installation. Please ensure that the [Prerequisites] for upgrading Observability have been completed before starting this upgrade.
+
+## Perform Upgrade
+
+{{% alert title="Note" %}}
+These steps will need to be performed on all application servers that host a Promtail service.
+{{% / alert %}}
+
+1. Log in to the application server.
+1. Run Windows PowerShell as Administrator.
+1. Change the directory to the folder where Promtail is running from, e.g. `cd C:\Promtail`.
+1. Remove the current Promtail installation by executing the following command:
+
+    ``` powershell
+        .\Remove-Promtail.ps1
+    ```
+
+1. Click *Yes* when prompted for confirmation that you wish to remove the service.
+1. Click *OK* when the successful removal of the Promtail service is confirmed.
+1. Open a File Explorer and navigate to the folder where Promtail was running from, e.g. `C:\Promtail`
+1. Delete the following files from the directory:
+
+    * Install-Promtail.ps1
+    * nssm.exe
+    * Promtail-local-config.yaml
+    * Promtail-windows-amd64.exe
+    * Remove-Promtail.ps1
+    * Start-Promtail.ps1
+    * Stop-Promtail.ps1
+
+1. In File Explorer, navigate to the extracted `promtail-windows-amd64.exe` folder created as part of [Make Artefacts Available][].
+1. Copy the `promtail-windows-amd64.exe` file into the folder that Promtail was previously running from, e.g. `C:\Promtail`.
+1. In File Explorer, navigate to the extracted `Promtail.Install` folder created as part of [Make Artefacts Available][].
+1. Copy the contents of this location into the folder that Promtail was previously running from, e.g. `C:\Promtail`.
+1. Open `promtail-local-config.yaml` in a text editor:
+
+    * Update the *filename* property under *positions* to be the value found in the [backed up][] version.
+    * Update the *url* property under *clients* to be the value found in the [backed up][] version.
+    * Save the new `promtail-local-config.yaml` file.
+
+1. Run Windows PowerShell as Administrator.
+1. Change the directory to the folder where the Promtail files have been copied to, e.g. `cd C:\Promtail`.
+1. Install Promtail by executing the following command:
+
+    ``` powershell
+        .\Install-Promtail.ps1
+    ```
+
+1. Start the Promtail service by executing the following command:
+
+    ``` powershell
+        .\Start-Promtail.ps1
+    ```
+
+1. Check that the Promtail service has installed and started correctly:
+    * Open Services.msc from the Start menu.
+    * Locate the *Promtail* service and confirm that it is *Running*.
+
+## Next Steps?
+
+1. [Try it out][]
+
+[backed up]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.BackupOldFiles" >}}
+[Make Artefacts Available]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.MakeArtefactsAvailable" >}}
+[Prerequisites]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.Prerequisites" >}}
+[Try it out]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.TryItOut" >}}

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

@@ -0,0 +1,6 @@
+---
+title: "Grafana"
+linkTitle: "Grafana"
+description: "Information about upgrading the default Grafana dashboards for your observability platform."
+weight: 1000
+---

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

@@ -0,0 +1,36 @@
+---
+title: "Try it out"
+linkTitle: "Try it out"
+description: "Information about trying out the observability platform after upgrading the dashboards."
+weight: 3
+---
+
+# {{% param title %}}
+
+## Confirm New Dashboards Display Data
+
+{{% alert title="Note" %}}
+Any flow can be used that exists on the system and can be executed.
+{{% / alert %}}
+
+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.
+1. Open a flow that you are able to execute on an ad hoc basis.
+1. Start the flow.
+1. Once the request has completed, in your web browser, navigate to and log in to your configured Grafana.
+1. Open the *Dashboards* page via the menu on the left sidebar.
+1. Click the folder name that the dashboards were imported to.
+1. Click the *Flow Execution Requests* dashboard to open it.
+1. The request made at step 1 should be visible on the dashboard.
+{{% alert title="Note" %}}
+If other requests have been made then there may be more than one request visible on the dashboard.
+{{% / alert %}}
+1. Open the *Dashboards* page via the menu on the left sidebar.
+1. Click the folder name that the dashboards were imported to.
+1. Click the *Platform Health* dashboard to open it.
+1. The request made at step 1 should be visible on the dashboard.
+{{% alert title="Note" %}}
+If other requests have been made then there may be more than one request visible on the dashboard.
+{{% / alert %}}
+
+[Upgrade Promtail]: {{< url path="Cortex.Guides.UpgradeObservability.Cloud.Grafana.UpgradePromtail" >}}
+[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

@@ -0,0 +1,40 @@
+---
+title: "Upgrade Dashboards"
+linkTitle: "Upgrade Dashboards"
+description: "Information about upgrading your Grafana dashboards."
+weight: 1
+---
+
+# {{% param title %}}
+
+This guide describes how to upgrade the default dashboards that are provided for your observability platform.
+
+## Download the Default Dashboards
+
+1. Download [Grafana.Dashboards.zip][] archive containing the {{% ctx %}} Innovation default dashboards.
+1. Extract the content of the downloaded archive to a suitable location.
+
+## Import New Dashboards
+
+1. Log in to your configured Grafana with a user that has the *Admin* role.
+1. Go to *Dashboards* via the menu on the left sidebar.
+1. Click the *New* button and select *Import* from the drop-down menu.
+1. Click the *Upload JSON file* button.
+1. Locate the `Flow Execution Requests.json` file [extracted][] from the downloaded `Grafana.Dashboards.zip`.
+1. Select the file and click *Open*.
+{{% alert title="Note" %}}
+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.
+{{% / alert %}}
+
+1. Select the folder in Grafana you wish the dashboard to be saved in, e.g. *Cortex*.
+1. Select your configured Loki data source from the dropdown menu.
+1. Click *Import (Overwrite)*.
+1. Repeat steps 2 - 9 for the `Platform Health.json` file.
+
+## Next Steps?
+
+1. [Try it out][]
+
+[extracted]: {{< url path="Cortex.Guides.UpgradeObservability.Dashboards.Grafana.Download" >}}
+[Grafana.Dashboards.zip]: {{< url path="GitHub.Cortex.Observability.3.0.0.GrafanaDashboardsZip" >}}
+[Try it out]: {{< url path="Cortex.Guides.UpgradeObservability.Dashboards.Grafana.TryItOut" >}}

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

@@ -0,0 +1,6 @@
+---
+title: "Dashboards"
+linkTitle: "Dashboards"
+description: "Information about upgrading the default dashboards provided for your observability platform."
+weight: 1000
+---

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

@@ -0,0 +1,6 @@
+---
+title: "On-Premise"
+linkTitle: "On-Premise"
+description: "Information about upgrading an on-premise observability platform for {{% ctx %}}."
+weight: 1
+---

content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/_index.md

@@ -0,0 +1,6 @@
+---
+title: "Grafana"
+linkTitle: "Grafana"
+description: "Information about upgrading an on-premise Grafana platform for {{% ctx %}}."
+weight: 1
+---

content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/prerequisites.md

@@ -0,0 +1,60 @@
+---
+title: "Prerequisites"
+linkTitle: "Prerequisites"
+description: "The prerequisites required before performing the observability upgrade."
+weight: 1
+---
+
+# {{% param title %}}
+
+## Verify Old Version
+
+1. Navigate to your Grafana website e.g. `https://machinename.domain.com:3000`
+1. Make a note of the version number under the login prompt.
+1. Login to Grafana.
+1. Open the *Dashboards* page via the menu on the left sidebar.
+1. Select the folder that hosts the Cortex Dashboards, e.g. *Cortex*
+1. Click the *Flow Execution Requests* dashboard to open it.
+1. Change the time period to be *Last 90 days* and confirm data is present.
+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.
+
+## Make Artefacts Available
+
+1. Download the required artefacts to a folder on your machine:
+
+    * [Grafana 10.4.1][] Standalone Windows Binaries archive.
+    * [Grafana Loki 3.0.0][] archive.
+    * [Grafana Loki Install][] archive.
+    * [Promtail 3.0.0][] archive.
+    * [Promtail Install][] archive.
+
+1. Extract the downloaded `grafana-enterprise-10.4.1.windows-amd64` archive to a folder with the same name.
+1. Extract the downloaded `loki-windows-amd64.exe` archive to a folder with the same name.
+1. Extract the downloaded `Grafana.Loki.Install` archive to a folder with the same name.
+1. Extract the downloaded `promtail-windows-amd64.exe` archive to a folder with the same name.
+1. Extract the downloaded `Promtail.Install` archive to a folder with the same name.
+
+## Backup Old Files
+
+1. On the server that Grafana and Loki is installed on, create a folder called `Observability Backups` in a known location.
+1. Open File Explorer and navigate to the location that Grafana was previously installed to, typically `%SystemDrive%\Program Files\GrafanaLabs\grafana\conf`.
+1. Copy the `custom.ini` file and save it to the `Observability Backups` folder created at step 1.
+1. Copy the `defaults.ini` file and save it to the `Observability Backups` folder created at step 1.
+1. In File Explorer, navigate to the location that Loki is running from, e.g. `C:\Loki\`.
+1. Copy the `loki-local-config.yaml` file and save it to the `Observability Backups` folder created at step 1.
+1. On each Application Server that Promtail is installed on:
+
+    1. Create a folder called `Observability Backups` in a known location.
+    1. Open File Explorer and navigate to the location that Promtail is running from, e.g. `C:\Promtail`.
+    1. Copy the `promtail-local-config.yaml` file and save it to the `Observability Backups` folder created at step 7.1.
+
+## Next Steps?
+
+1. [Upgrade Grafana][]
+
+[Grafana 10.4.1]: {{< url path="Grafana.SelfManaged.Downloads.GrafanaWebApp.10.4.1.Windows" >}}
+[Grafana Loki 3.0.0]: {{< url path="Grafana.SelfManaged.Downloads.GrafanaLoki.3.0.0.GrafanaLokiInstallZip" >}}
+[Grafana Loki Install]: {{< url path="GitHub.Cortex.Observability.3.0.0.GrafanaLokiInstallZip" >}}
+[Promtail 3.0.0]:  {{< url path="Grafana.SelfManaged.Downloads.Promtail.3.0.0.PromtailInstallZip" >}}
+[Promtail Install]: {{< url path="GitHub.Cortex.Observability.3.0.0.PromtailInstallZip" >}}
+[Upgrade Grafana]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.UpgradeGrafana" >}}