From fd22811f29f0fbc490c9a9c6e47cc9eb3d4cd653 Mon Sep 17 00:00:00 2001 From: Cortex-DMS <104561178+Cortex-DMS@users.noreply.github.com> Date: Wed, 4 Sep 2024 10:42:55 +0100 Subject: [PATCH] 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 --- .../Guides/upgrade-observability/_index.md | 6 ++ .../upgrade-observability/cloud/_index.md | 6 ++ .../cloud/grafana/_index.md | 6 ++ .../cloud/grafana/prerequisites.md | 44 +++++++++ .../cloud/grafana/try-it-out.md | 48 ++++++++++ .../cloud/grafana/upgrade-promtail.md | 75 +++++++++++++++ .../dashboards/Grafana/_index.md | 6 ++ .../dashboards/Grafana/try-it-out.md | 36 +++++++ .../dashboards/Grafana/upgrade-dashboards.md | 40 ++++++++ .../dashboards/_index.md | 6 ++ .../on-premise/_index.md | 6 ++ .../on-premise/grafana/_index.md | 6 ++ .../on-premise/grafana/prerequisites.md | 60 ++++++++++++ .../on-premise/grafana/try-it-out.md | 54 +++++++++++ .../on-premise/grafana/upgrade-grafana.md | 31 +++++++ .../on-premise/grafana/upgrade-loki.md | 93 +++++++++++++++++++ .../on-premise/grafana/upgrade-promtail.md | 75 +++++++++++++++ data/urls.toml | 32 ++++++- 18 files changed, 627 insertions(+), 3 deletions(-) create mode 100644 content/en/docs/2024.7/Guides/upgrade-observability/_index.md create mode 100644 content/en/docs/2024.7/Guides/upgrade-observability/cloud/_index.md create mode 100644 content/en/docs/2024.7/Guides/upgrade-observability/cloud/grafana/_index.md create mode 100644 content/en/docs/2024.7/Guides/upgrade-observability/cloud/grafana/prerequisites.md create mode 100644 content/en/docs/2024.7/Guides/upgrade-observability/cloud/grafana/try-it-out.md create mode 100644 content/en/docs/2024.7/Guides/upgrade-observability/cloud/grafana/upgrade-promtail.md create mode 100644 content/en/docs/2024.7/Guides/upgrade-observability/dashboards/Grafana/_index.md create mode 100644 content/en/docs/2024.7/Guides/upgrade-observability/dashboards/Grafana/try-it-out.md create mode 100644 content/en/docs/2024.7/Guides/upgrade-observability/dashboards/Grafana/upgrade-dashboards.md create mode 100644 content/en/docs/2024.7/Guides/upgrade-observability/dashboards/_index.md create mode 100644 content/en/docs/2024.7/Guides/upgrade-observability/on-premise/_index.md create mode 100644 content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/_index.md create mode 100644 content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/prerequisites.md create mode 100644 content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/try-it-out.md create mode 100644 content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/upgrade-grafana.md create mode 100644 content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/upgrade-loki.md create mode 100644 content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/upgrade-promtail.md diff --git a/content/en/docs/2024.7/Guides/upgrade-observability/_index.md b/content/en/docs/2024.7/Guides/upgrade-observability/_index.md new file mode 100644 index 000000000..8faaea3a2 --- /dev/null +++ b/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 +--- \ No newline at end of file diff --git a/content/en/docs/2024.7/Guides/upgrade-observability/cloud/_index.md b/content/en/docs/2024.7/Guides/upgrade-observability/cloud/_index.md new file mode 100644 index 000000000..4eaa242d6 --- /dev/null +++ b/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 +--- \ No newline at end of file diff --git a/content/en/docs/2024.7/Guides/upgrade-observability/cloud/grafana/_index.md b/content/en/docs/2024.7/Guides/upgrade-observability/cloud/grafana/_index.md new file mode 100644 index 000000000..1337f8126 --- /dev/null +++ b/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 +--- \ No newline at end of file diff --git a/content/en/docs/2024.7/Guides/upgrade-observability/cloud/grafana/prerequisites.md b/content/en/docs/2024.7/Guides/upgrade-observability/cloud/grafana/prerequisites.md new file mode 100644 index 000000000..d141133bc --- /dev/null +++ b/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" >}} diff --git a/content/en/docs/2024.7/Guides/upgrade-observability/cloud/grafana/try-it-out.md b/content/en/docs/2024.7/Guides/upgrade-observability/cloud/grafana/try-it-out.md new file mode 100644 index 000000000..f6d53e219 --- /dev/null +++ b/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" >}} diff --git a/content/en/docs/2024.7/Guides/upgrade-observability/cloud/grafana/upgrade-promtail.md b/content/en/docs/2024.7/Guides/upgrade-observability/cloud/grafana/upgrade-promtail.md new file mode 100644 index 000000000..91cab8f67 --- /dev/null +++ b/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" >}} diff --git a/content/en/docs/2024.7/Guides/upgrade-observability/dashboards/Grafana/_index.md b/content/en/docs/2024.7/Guides/upgrade-observability/dashboards/Grafana/_index.md new file mode 100644 index 000000000..83fd0b271 --- /dev/null +++ b/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 +--- \ No newline at end of file diff --git a/content/en/docs/2024.7/Guides/upgrade-observability/dashboards/Grafana/try-it-out.md b/content/en/docs/2024.7/Guides/upgrade-observability/dashboards/Grafana/try-it-out.md new file mode 100644 index 000000000..09b163023 --- /dev/null +++ b/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" >}} diff --git a/content/en/docs/2024.7/Guides/upgrade-observability/dashboards/Grafana/upgrade-dashboards.md b/content/en/docs/2024.7/Guides/upgrade-observability/dashboards/Grafana/upgrade-dashboards.md new file mode 100644 index 000000000..6f95386b5 --- /dev/null +++ b/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" >}} diff --git a/content/en/docs/2024.7/Guides/upgrade-observability/dashboards/_index.md b/content/en/docs/2024.7/Guides/upgrade-observability/dashboards/_index.md new file mode 100644 index 000000000..4078c1304 --- /dev/null +++ b/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 +--- \ No newline at end of file diff --git a/content/en/docs/2024.7/Guides/upgrade-observability/on-premise/_index.md b/content/en/docs/2024.7/Guides/upgrade-observability/on-premise/_index.md new file mode 100644 index 000000000..59f2ef8fd --- /dev/null +++ b/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 +--- \ No newline at end of file diff --git a/content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/_index.md b/content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/_index.md new file mode 100644 index 000000000..0b777445d --- /dev/null +++ b/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 +--- \ No newline at end of file diff --git a/content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/prerequisites.md b/content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/prerequisites.md new file mode 100644 index 000000000..1a7dbf3e1 --- /dev/null +++ b/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" >}} diff --git a/content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/try-it-out.md b/content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/try-it-out.md new file mode 100644 index 000000000..3f46dd3c6 --- /dev/null +++ b/content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/try-it-out.md @@ -0,0 +1,54 @@ +--- +title: "Try it out" +linkTitle: "Try it out" +description: "Information about trying out the observability platform after upgrade." +weight: 5 +--- + +# {{% 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 Grafana Upgrade + +1. Navigate to your Grafana website e.g. `https://machinename.domain.com:3000`. +1. Identify the version number under the login prompt. +1. Confirm the version has updated to be 10.4.1. + +## Confirm Dashboards Load + +1. Navigate to your Grafana website e.g. `https://machinename.domain.com:3000` +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.OnPremise.Grafana.UpgradePromtail" >}} +[verifying the old version]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.VerifyOldVersion" >}} diff --git a/content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/upgrade-grafana.md b/content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/upgrade-grafana.md new file mode 100644 index 000000000..c60d9a272 --- /dev/null +++ b/content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/upgrade-grafana.md @@ -0,0 +1,31 @@ +--- +title: "Upgrade Grafana" +linkTitle: "Upgrade Grafana" +description: "The steps to upgrade Grafana." +weight: 2 +--- + +# {{% param title %}} + +This guide describes how to upgrade the Grafana installation. Please ensure that the [Prerequisites] for upgrading Observability have been completed before starting this upgrade. + +## Perform Upgrade + +1. Log in to the server hosting your Grafana website. +1. Open Services.msc from the Start menu. +1. Locate the *Grafana* service and stop it by right-clicking on the service and selecting *Stop*. +1. In File Explorer, navigate to the `grafana-enterprise-10.4.1.windows-amd64` folder created as part of [Make Artefacts Available][]. +1. Open the `grafana-v10.4.1` subfolder. +1. Copy the contents of this folder into the Grafana install location, typically `%SystemDrive%\Program Files\GrafanaLabs\grafana`, and click `Replace the files in the destination` when prompted. +1. Copy the [backed up][] `custom.ini` and `defaults.ini` files into the Grafana install configuration location, typically `%SystemDrive%\Program Files\GrafanaLabs\grafana\conf`, and click `Replace the files in the destination` when prompted. +1. Open Services.msc from the Start menu. +1. Locate the *Grafana* service and start it by right-clicking on the service and selecting *Start*. + +## Next Steps? + +1. [Upgrade Loki][] + +[backed up]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.BackupOldFiles" >}} +[Make Artefacts Available]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.MakeArtefactsAvailable" >}} +[Prerequisites]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.Prerequisites" >}} +[Upgrade Loki]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.UpgradeLoki" >}} diff --git a/content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/upgrade-loki.md b/content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/upgrade-loki.md new file mode 100644 index 000000000..22e2eec7b --- /dev/null +++ b/content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/upgrade-loki.md @@ -0,0 +1,93 @@ +--- +title: "Upgrade Loki" +linkTitle: "Upgrade Loki" +description: "The steps to upgrade Loki." +weight: 3 +--- + +# {{% param title %}} + +This guide describes how to upgrade the Loki installation. Please ensure that the [Grafana Upgrade] has been completed before starting this upgrade. + +## Perform Upgrade + +1. Log in to the server hosting your Loki service. +1. Run Windows PowerShell as Administrator. +1. Change the directory to the folder where Loki is running from, e.g. `cd C:\Loki`. +1. Remove the current Loki installation by executing the following command: + + ``` powershell + .\Remove-Loki.ps1 + ``` + +1. Click *Yes* when prompted for confirmation that you wish to remove the service. +1. Click *OK* when the successful removal of the Loki service is confirmed. +1. Open a File Explorer and navigate to the folder where Loki was running from, e.g. `C:\Loki`. +1. Delete the following files from the directory: + + * Install-Loki.ps1 + * loki-local-config.yaml + * loki-windows-amd64.exe + * nssm.exe + * Remove-Loki.ps1 + * Start-Loki.ps1 + * Stop-Loki.ps1 + +1. In File Explorer, navigate to the extracted `loki-windows-amd64.exe` folder created as part of [Make Artefacts Available][]. +1. Copy the `loki-windows-amd64.exe` file into the folder that Loki was previously running from, e.g. `C:\Loki`. +1. In File Explorer, navigate to the extracted `Grafana.Loki.Install` folder created as part of [Make Artefacts Available][]. +1. Copy the contents of this location into the folder that Loki was previously running from, e.g. `C:\Loki`. +1. Open the new `loki-local-config.yaml` file in a text editor and compare against the [backed up][] version. If there are differences between the two files in the *schema_config* > *configs* section: + + 1. In the new file, change the date next to `- from` to be today's date. + 1. Copy the old config section from the backup and add it immediately under *configs* and before the existing `- from ` line ensuring that formatting (including indentations) remain identical to that which is used in the new file. + + The new *schema_config* should result in something similar to: + + ```yaml + schema_config: + configs: + - from: 2020-10-24 + store: boltdb-shipper + object_store: filesystem + schema: v11 + index: + prefix: index_ + period: 24h + - from: 2024-08-29 + store: tsdb + object_store: filesystem + schema: v13 + index: + prefix: index_ + period: 24h + ``` + + 1. Save the new `loki-local-config.yaml` file. + +1. Run Windows PowerShell as Administrator. +1. Change the directory to the folder where the Loki files have been copied to, e.g. `cd C:\Loki`. +1. Install Loki by executing the following command: + + ``` powershell + .\Install-Loki.ps1 + ``` + +1. Start the Loki service by executing the following command: + + ``` powershell + .\Start-Loki.ps1 + ``` + +1. Check that the Loki service has installed and started correctly: + * Open Services.msc from the Start menu. + * Locate the *Loki* service and confirm that it is *Running*. + +## Next Steps? + +1. [Upgrade Promtail][] + +[backed up]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.BackupOldFiles" >}} +[Grafana Upgrade]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.UpgradeGrafana" >}} +[Make Artefacts Available]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.MakeArtefactsAvailable" >}} +[Upgrade Promtail]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.UpgradePromtail" >}} diff --git a/content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/upgrade-promtail.md b/content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/upgrade-promtail.md new file mode 100644 index 000000000..e317fb110 --- /dev/null +++ b/content/en/docs/2024.7/Guides/upgrade-observability/on-premise/grafana/upgrade-promtail.md @@ -0,0 +1,75 @@ +--- +title: "Upgrade Promtail" +linkTitle: "Upgrade Promtail" +description: "The steps to upgrade Promtail." +weight: 4 +--- + +# {{% param title %}} + +This guide describes how to upgrade the Promtail installation. Please ensure that the [Loki Upgrade][] has 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 the new `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.OnPremise.Grafana.BackupOldFiles" >}} +[Loki Upgrade]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.UpgradeLoki" >}} +[Make Artefacts Available]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.MakeArtefactsAvailable" >}} +[Try it out]: {{< url path="Cortex.Guides.UpgradeObservability.OnPremise.Grafana.TryItOut" >}} diff --git a/data/urls.toml b/data/urls.toml index 2d20fcf31..ca32d90a3 100644 --- a/data/urls.toml +++ b/data/urls.toml @@ -293,8 +293,8 @@ TryItOut= "/docs/getting-started/on-premise/add-innovation-to-72/single-server-without-ha/try-it-out" AntivirusExclusions = "/docs/getting-started/on-premise/add-innovation-to-72/single-server-without-ha/prerequisites#antivirus-exclusions" HardwareRequirements = "/docs/getting-started/on-premise/add-innovation-to-72/single-server-without-ha/prerequisites#hardware-requirements" - [Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation] - MainDoc = "/docs/getting-started/on-premise/add-observability-to-innovation/" + [Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation] + MainDoc = "/docs/getting-started/on-premise/add-observability-to-innovation/" [Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana] MainDoc = "/docs/getting-started/on-premise/add-observability-to-innovation/grafana/" Architecture = "/docs/getting-started/on-premise/add-observability-to-innovation/grafana/architecture" @@ -518,6 +518,32 @@ TryItOut = "/docs/guides/upgrade-cortex/2024.5-to-2024.7/single-server-without-ha/try-it-out" UpgradeApplicationServer = "/docs/guides/upgrade-cortex/2024.5-to-2024.7/single-server-without-ha/upgrade-application-server" UpgradeWebApplicationServer = "/docs/guides/upgrade-cortex/2024.5-to-2024.7/single-server-without-ha/upgrade-web-application-server" + [Cortex.Guides.UpgradeObservability] + MainDoc = "/docs/guides/upgrade-observability/" + [Cortex.Guides.UpgradeObservability.OnPremise] + [Cortex.Guides.UpgradeObservability.OnPremise.Grafana] + BackupOldFiles = "/docs/guides/upgrade-observability/on-premise/grafana/prerequisites/#backup-old-files" + MakeArtefactsAvailable = "/docs/guides/upgrade-observability/on-premise/grafana/prerequisites/#make-artefacts-available" + Prerequisites = "/docs/guides/upgrade-observability/on-premise/grafana/prerequisites" + TryItOut = "/docs/guides/upgrade-observability/on-premise/grafana/try-it-out" + UpgradeGrafana = "/docs/guides/upgrade-observability/on-premise/grafana/upgrade-grafana" + UpgradeLoki = "/docs/guides/upgrade-observability/on-premise/grafana/upgrade-loki" + UpgradePromtail = "/docs/guides/upgrade-observability/on-premise/grafana/upgrade-promtail" + VerifyOldVersion = "/docs/guides/upgrade-observability/on-premise/grafana/prerequisites/#verify-old-version" + [Cortex.Guides.UpgradeObservability.Cloud] + [Cortex.Guides.UpgradeObservability.Cloud.Grafana] + BackupOldFiles = "/docs/guides/upgrade-observability/cloud/grafana/prerequisites/#backup-old-files" + MakeArtefactsAvailable = "/docs/guides/upgrade-observability/cloud/grafana/prerequisites/#make-artefacts-available" + Prerequisites = "/docs/guides/upgrade-observability/cloud/grafana/prerequisites" + TryItOut = "/docs/guides/upgrade-observability/cloud/grafana/try-it-out" + UpgradePromtail = "/docs/guides/upgrade-observability/cloud/grafana/upgrade-promtail" + VerifyOldVersion = "/docs/guides/upgrade-observability/cloud/grafana/prerequisites/#verify-old-version" + [Cortex.Guides.UpgradeObservability.Dashboards] + [Cortex.Guides.UpgradeObservability.Dashboards.Grafana] + Download = "/docs/guides/upgrade-observability/dashboards/grafana/upgrade-dashboards/#download-the-default-dashboards" + UpgradeDashboards = "/docs/guides/upgrade-observability/dashboards/grafana/upgrade-dashboards" + TryItOut = "/docs/guides/upgrade-observability/dashboards/grafana/try-it-out" + [Cortex.Reference] MainDoc = "/docs/reference/" [Cortex.Reference.Apis] @@ -2742,4 +2768,4 @@ CharacterSets = "https://www.w3.org/Style/XSL/TestSuite/results/4/XEP/charsets.pdf" SqlInjection = "https://www.w3schools.com/sql/sql_injection.asp" [Mozilla] - UriSyntax = "https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Identifying_resources_on_the_Web#syntax_of_uniform_resource_identifiers_uris" \ No newline at end of file + UriSyntax = "https://developer.mozilla.org/en-US/docs/Web/URI#syntax_of_uniform_resource_identifiers_uris" \ No newline at end of file