PMM-13025 - Upgrade changes

.github/workflows/build.yml

@@ -1,4 +1,4 @@
-name: Build PMM Docs 2.x
+name: Build PMM Docs 3.x
 
 on:
   push:

README.md

@@ -22,7 +22,9 @@ The documentation source files are in the `docs` directory. (Other files in this
 
 The two major PMM versions are kept in separate branches:
 
-- `main` is for PMM 2.x (latest)
+- `PMM3-branch` is for PMM 3.x (latest)
+
+- `main` is for PMM 2.x 
 
 - `1.x` is for PMM 1.x
 
@@ -159,7 +161,7 @@ View the site at <http://0.0.0.0:8000>
 
 ## Version switching
 
-We use [mike] to build different versions of the documentation. Currently, only two are built, the latest PMM 1 and PMM 2 versions.
+We use [mike] to build different versions of the documentation. Currently, only two are built, the latest PMM 2 and PMM 3 versions.
 
 A [GitHub actions] workflow runs `mike` which in turn runs `mkdocs`. The HTML is committed and pushed to the `publish` branch. The whole branch is then copied (by an internal Percona Jenkins job) to our web server.
 

docs/alert/index.md

@@ -1,13 +1,7 @@
 # About Percona Alerting
-
-!!! alert alert-info "Important"
-    Percona Alerting is the new Alerting feature introduced in PMM 2.31. This replaces the Integrated Alerting feature available in previous versions.  
 
 Alerting notifies of important or unusual activity in your database environments so that you can identify and resolve problems quickly. When something needs your attention, Percona Alerting can be configured to automatically send you a notification through your specified contact points.
 
-
-PMM 2.31 introduced Percona Alerting which replaces Integrated Alerting in previous PMM versions. In addition to full feature parity, Percona Alerting includes additional benefits like Grafana-based alert rules and a unified, easy-to-use alerting command center on the **Alerting** page.
-
 Percona Alerting is enabled by default in the PMM Settings. This feature adds the **Alert rule templates** option on the main menu and alert template options on the **Alerting** page.
 
 These options enable you to create alerts based on a set of Percona-supplied templates with common events and expressions for alerting. 

docs/alert/silence_alerts.md

@@ -29,9 +29,9 @@ For more information on working with silences, see [About alerting silences](htt
 
 ### Template compatibility with previous PMM versions
 
-If you have used Integrated Alerting in previous PMM versions, your custom alert rule templates will be automatically migrated to the new PMM version. After upgrading to the new version, you will find all your alert templates under **Alerting > Alert rule templates**.
+If you have used Integrated Alerting in previous PMM 2.31 and earlier, your custom alert rule templates will be automatically migrated to the new PMM version. After upgrading to the new version, you will find all your alert templates under **Alerting > Alert rule templates**.
 
-If you have any templates available in the  ``/srv/ia/templates`` folder, make sure to transfer them to ``/srv/alerting/templates`` as PMM 2.31 and later will look for custom templates in this location.
+If you have any templates available in the  ``/srv/ia/templates`` folder, make sure to transfer them to ``/srv/alerting/templates`` as PMM 3   will look for custom templates in this location.
 
 ### Template compatibility with other alerting tools
 

docs/backup/index.md

@@ -20,7 +20,7 @@ For MySQL databases, you can create and restore on-demand and scheduled physical
 
 ### Sharded MongoDB cluster configurations
 
-PMM 2.38 added support for creating backups of sharded MongoDB clusters. However, the restoring process is not handled end-to-end, and requires you to manually restore the artifacts using the CLI in Percona Backup for MongoDB.
+PMM 3 supports creating backups of sharded MongoDB clusters. However, the restoring process is not handled end-to-end, and requires you to manually restore the artifacts using the CLI in Percona Backup for MongoDB.
 
 
 ## Start here

docs/backup/mongodb-backup/backup_mongo.md

@@ -12,7 +12,7 @@ PMM supports the following actions for MongoDB backups:
 
 ## Sharded clusters
 
-Backups of sharded clusters is supported starting with PMM 2.38. However, restoring for sharded cluster configurations is only supported from the CLI, and is handled via [Percona Backup for MongoDB](https://docs.percona.com/percona-backup-mongodb/usage/restore.html).
+PMM 3 supports backing up sharded clusters. However, restoring for sharded cluster configurations is only supported from the CLI, and is handled via [Percona Backup for MongoDB](https://docs.percona.com/percona-backup-mongodb/usage/restore.html).
 
   - Storing backups on Amazon S3-compatible object storage, and on mounted filesystem
   - Creating Logical snapshot backups

docs/backup/mongodb-backup/mongo_prerequisites.md

@@ -22,4 +22,4 @@ Services that do not specify a cluster name should be removed and re-added using
 
       Use `pbm` in manual mode only for restoring sharded cluster backups or other operations that can only be completed via the PBM CLI! Since PMM takes care of the PBM configuration, any unnecessary manual intervention can break the state.
 
-       PMM 2.32 and later require PBM 2.0.1 or newer.
+       PMM 3 and later require PBM 2.0.1 or newer.

docs/backup/mongodb-backup/restore_MongoDB_backups.md

@@ -130,6 +130,6 @@ To restore to a new cluster manually:
 
 ### Restoring from a sharded cluster
 
-Sharded cluster backups are supported starting with PMM 2.38 and PMM handles the backup process end-to-end. However, restoring such artifacts is currently possible only via the CLI, using Percona Backup for MongoDB.
+Sharded cluster backups are supported and PMM handles the backup process end-to-end. However, restoring such artifacts is currently possible only via the CLI, using Percona Backup for MongoDB.
 
 For information on restoring sharded backups, check the [PBM documentation](https://docs.percona.com/percona-backup-mongodb/usage/restore.html)

docs/how-to/integrate-platform.md

@@ -11,16 +11,8 @@ We recommend that you connect with a Percona Account, as this gives you access t
 #### Prerequisites
 To ensure that PMM can establish a connection to Percona Platform:
 
-### Upgrade to PMM 2.27.0 or later
- Before connecting your PMM Server to Percona Platform, make sure you are using PMM version 2.27 or newer. Otherwise, upgrade your PMM installation beforehand.
-
- This is required because, starting with PMM 2.27, Percona Platform has replaced username/password authentication with access token authentication. Access-token authentication increases security and enables federated identity.
-
-  This change did not affect existing connections to PMM Platform, which were not automatically terminated.
-
- For more information, see [Install and set up PMM](../setting-up/index.md).
-
 ### Check that you are a member of an existing Platform organization
+
 1. Log in to [Percona Platform](https://portal.percona.com) using your Percona Account. If you are connecting via GitHub, make sure you set your email address as **public** in your GitHub account. If your email address is private instead, Percona Platform cannot access it to authenticate you.
 
 2. On the **Getting Started** page, check that the **Create organization** step shows an option to view your organization.

docs/how-to/upgrade.md

@@ -1,36 +1,43 @@
 # Upgrade
 
+Client and Server components are installed and updated separately.
+
+
 ## Plan the upgrade order
 
 ### Upgrade PMM Server first
 
-Make sure to upgrade the PMM Server before you upgrade the PMM Client.
-
-Ensure that the PMM Server version is higher than or equal to the PMM Client version. Otherwise, there might be configuration issues, thus leading to failure in the client-server communication as PMM Server might not be able to identify all the parameters in the configuration.
+Always upgrade the PMM Server before you upgrade the PMM Client.
+Ensure that the PMM Server version is equal to or higher than the PMM Client version. Otherwise, configuration issues may arise, potentially causing failures in Client-Server communication, as the PMM Server may not recognize all the configuration parameters.
+
+### Migrating from PMM 2
+
+When upgrading PMM from PMM v2, follow the following staged approach: 
 
-For example, for a PMM Server version 2.25.0, the PMM Client version should be 2.25.0 or 2.24.0. If the PMM Client version is 2.26.0, PMM might not work as expected.
+1. upgrade to the latest PMM v2 version
+2. Proceed to upgrading to PMM 3. 
+
+Make sure you have access to the machine where PMM Server: 
+
+1. run docker exec -t <pmm-server> supervisorctl stop all to stop all services of pmm-server container
+2. run docker exec -t <pmm-server> chown -R pmm:pmm /srv to transfer ownership of all directories and files located in /srv directory to pmm user
+3. stop and remove pmm-server container (docker stop pmm-server && docker rm pmm-server )
+4. pull a new docker image for PMM Server v3 (once it goes GA, it will be docker pull percona/pmm-server:3 )
+5. run a new container based on v3 image ( see above) while remembering to pass the same pmm-data volume to it (docker run -d -v pmm-data:/srv ... percona/pmm-server:3 )
 
-### Staged upgrade approach
 
-When upgrading PMM from older versions (2.30.0 and below), we recommend following a staged approach: first, upgrade to version 2.33.0, and then proceed to the latest version. 
 
 This sequential upgrading process ensures that PMM's internal components are migrated and updated correctly.
 
 ## Update the Server
 
-!!! caution alert alert-warning "Known issues for older versions"
-    - Upgrading to PMM 2.32.0 from older versions fails. We recommend upgrading directly to2.33 or latest version. For more information, see the [troubleshooting topic](../how-to/troubleshoot.md#pmm-server-fails-while-upgrading).
-
+!!! caution alert alert-warning "Known issue for older versions"
     - PMM versions prior to 2.33.0 may not show the latest versions available with instances created from the AWS marketplace in specific environments, including AWS. For solution, see the [troubleshooting](../how-to/troubleshoot.md#pmm-server-not-showing-latest-versions-available-with-the-instances-created-from-aws) section.
 
 
-Client and server components are installed and updated separately.
-
 PMM Server can run natively, as a Docker image, a virtual appliance, or an AWS cloud instance. Each has its own installation and update steps.
 
-The preferred and simplest way to update PMM Server is with the *PMM Upgrade* panel on the Home page.
 
-![!image](../_images/PMM_Home_Dashboard_Panels_Upgrade.jpg)
 
 The panel shows:
 

docs/pmm-upgrade/index.md

@@ -1,17 +1,15 @@
 # About PMM Server upgrade
 
-!!! caution alert alert-warning "Important"
-    Upgrade the PMM Server before you upgrade the PMM Client.
-    Ensure that the PMM Server version is higher than or equal to the PMM Client version. Otherwise, there might be configuration issues, thus leading to failure in the client-server communication as PMM Server might not be able to identify all the parameters in the configuration.
-
-    For example, for a PMM Server version 2.25.0, the PMM Client version should be 2.25.0 or 2.24.0. If the PMM Client version is 2.26.0, PMM might not work as expected.
+!!! caution alert alert-warning "Upgrade PMM Server before Clients"
+    - When upgrading PMM, always upgrade the PMM Server before upgrading any PMM Clients.
+    - Make sure that the PMM Server version is higher than or equal to the PMM Client version. Mismatched versions can lead to configuration issues and failures in Client-Server communication, as the PMM Server may not recognize all parameters in the client configuration.
 
 Find the detailed information on how to upgrade PMM in the following sections:
 
-* [Upgrade PMM Server using the UI](ui_upgrade.md)
+* [Upgrade PMM Server from the UI](ui_upgrade.md)
 
-* [Upgrade PMM agent](upgrade_agent.md)
+* [Upgrade PMM Client](upgrade_agent.md)
 
 * [Upgrade PMM Server using Docker](upgrade_docker.md)
 
-* [Upgrade from PMM 1](upgrade_from_pmm_1.md)
+* [Upgrade from PMM 2](upgrade_from_ppm_2.md)

docs/pmm-upgrade/ui_upgrade.md

@@ -1,26 +1,22 @@
-# Upgrade PMM Server using the UI
+# Upgrade PMM v3 Server from the UI
 
-!!! caution alert alert-warning "Caution"
-    - While upgrading PMM to version 2.32.0, it fails. This issue has been resolved for PMM version 2.33.0. However, the issue persists on all the versions prior to 2.33.0. For solution, see the [troubleshooting](../troubleshoot/upgrade_issues.md) section.
-    - PMM versions prior to 2.33.0 may not show the latest versions available with instances created from the AWS marketplace in specific environments, including AWS. For solution, see the [troubleshooting](../troubleshoot/upgrade_issues.md#pmm-server-not-showing-latest-versions-available-with-the-instances-created-from-aws) section.
+PMM Server and Client components are installed and updated separately.
 
-Client and server components are installed and updated separately.
+PMM v3 Server can run natively, as a Docker image, a virtual appliance, or an AWS cloud instance. While each environment has its own specific installation and update steps, the UI-based upgrade method is universal and recommended for most users.
 
-PMM Server can run natively, as a Docker image, a virtual appliance, or an AWS cloud instance. Each has its own installation and update steps.
+## Upgrade process
 
-The preferred and simplest way to update PMM Server is with the *PMM Upgrade* panel on the Home page.
+The preferred and simplest way to update PMM v3 Server is via the **Updates** page:
+{.power-number}
 
-![!image](../_images/PMM_Home_Dashboard_Panels_Upgrade.jpg)
+1. Go to **PMM Configuration > Updates** in your PMM web interface. Here you can check the current PMM Server version, the timestamp of the last update check and whether your instance is up-to-date.  
 
-The panel shows:
+2. If an update is available, click the **Update now** button to install the latest version.
 
-- the current server version and release date;
-- whether the server is up to date;
-- the last time a check was made for updates.
+![Update page](../Update_page.png)
 
-Click the refresh button to manually check for updates.
+## Quick upgrade check
 
-If one is available, click the update button to update to the version indicated.
+For a quick overview of your PMM v3 Server's update status, you can also check to the **Upgrade** panel on the **Home** page.
 
-!!! seealso alert alert-info "See also"
-    [PMM Server Docker upgrade](upgrade_docker.md) and [Upgrade PMM agent](upgrade_agent.md)
+![PMM Home Dashboard Upgrade Panel](../_images/PMM_Home_Dashboard_Panels_Upgrade.jpg)

docs/pmm-upgrade/upgrade_agent.md

@@ -1,10 +1,50 @@
-# Upgrade PMM agent
+# Upgrade PMM Client
 
-PMM-Agent can be updated from tarball:
-{.power-number}
+There are two primary methods to update PMM Clients, depending on your initial installation method:
 
- 1. Download `tar.gz` with `pmm2-client`.
- 2. Extract it.
+1. Using your operating system's package manager.
+2. Updating from a tarball.
+
+### 1. Package Manager method
+
+The package manager method is generally more convenient and efficient. Percona provides the [percona-release](https://docs.percona.com/percona-software-repositories/installing.html) package, which helps you install Percona software, including the PMM Client. The PMM Client is available from the `pmm-client` repository.
+
+To deploy a new version of the Client via package manager, simply replace the currently installed package with the latest version of the PMM Client or with a specific version.
+
+#### Install the latest PMM Client version
+
+Run the commands below to install the latest PMM Client version via package manager and keep your existing Client configuration during the update process.
+
+For example, to install the latest version of the PMM Client on Red Hat or its derivatives:
+
+ ```sh
+ percona-release enable pmm-client
+ yum update pmm-client
+ ```
+
+#### Deploy a specific version
+
+To deploy a specific version of the PMM Client via package manager, check the available versions and then provide the full name of the package. For example:
+
+ ```sh
+ yum --showduplicates search pmm2-client
+ pmm2-client-2.39.0-6.el9.x86_64 : Percona Monitoring and Management Client (pmm-agent)
+ pmm2-client-2.40.0-6.el9.x86_64 : Percona Monitoring and Management Client (pmm-agent)
+ pmm2-client-2.40.1-6.el9.x86_64 : Percona Monitoring and Management Client (pmm-agent)
+ pmm2-client-2.41.0-6.el9.x86_64 : Percona Monitoring and Management Client (pmm-agent)
+ pmm2-client-2.41.1-6.el9.x86_64 : Percona Monitoring and Management Client (pmm-agent)
+ pmm2-client-2.41.2-6.el9.x86_64 : Percona Monitoring and Management Client (pmm-agent)
+ pmm2-client-2.42.0-6.el9.x86_64 : Percona Monitoring and Management Client (pmm-agent)
+
+ yum update pmm2-client-2.41.2-6.el9.x86_64
+ ```
+
+### Tarball method
+
+If you initially installed the PMM Client from a tarball, you can update it by replacing the currently installed package with the latest version:
+
+ 1. Download `tar.gz` with `pmm-client`.
+ 2. Extract the tarball.
  3. Run `./install_tarball` script with the `-u` flag.
 
 !!! caution alert alert-warning "Important"

docs/pmm-upgrade/upgrade_aws.md

@@ -1,6 +1,6 @@
 # Upgrade PMM Server on AWS
 
-## Change Public IP address
+## Change public IP address
 
 To assign a public IP address for an Amazon EC2 instance, follow these steps:
 {.power-number}

docs/pmm-upgrade/upgrade_docker.md

@@ -1,62 +1,49 @@
 # Upgrade PMM Server using Docker
 
-??? info "Summary"
-
-    !!! summary alert alert-info ""
-        - Stop the running container.
-        - Backup (rename) the container and copy data.
-        - Pull the latest Docker image.
-        - Run it.
-
-    ---
+## Before you begin
+{.power-number}
 
-!!! caution alert alert-warning "Important"
-    Downgrades are not possible. To go back to using a previous version you must have created a backup of it before upgrading.
+1. Create a backup before upgrading, as downgrades are not possible. Therefore, reverting to a previous version requires an backup made prior to the upgrade.
 
-!!! hint alert alert-success "Tip"
-    To see what release you are running, use the *PMM Upgrade* panel on the *Home Dashboard*, or run:
+2. Verify your current PMM version: Check your current PMM version by navigating to **PMM Configuration > Updates** or by running the following command. If accessing remotely, replace `localhost` with the appropriate IP address or server name:
 
     ```sh
-    docker exec -it pmm-server \
-    curl -ku admin:admin https://localhost/v1/version
+   docker exec -it pmm-server curl -ku admin:admin https://localhost/v1/version
     ```
 
-    (If you are accessing the docker host remotely, replace `localhost` with the IP or server name of the host.)
-
-To upgrade PMM Server using Docker:
+## Upgrade steps
 {.power-number}
 
+1. Stop the current container:
 
-1. Stop the container.
-
-    ```sh
-    docker stop pmm-server
-    ```
-
-2. Perform a [backup](#backup).
+   ```sh
+   docker stop pmm-server
+   ```
 
+2. [Back up your data](../install-pmm/install-pmm-server/baremetal/docker/backup_container.md).
 
-3. Pull the latest image.
+3. Pull the latest image:
 
-    ```sh
-    docker pull percona/pmm-server:2
-    ```
+   ```sh
+   docker pull percona/pmm-server:2
+   ```
 
-4. Rename the original container
+4. Rename the original container:
 
-    ```sh
-    docker rename pmm-server pmm-server-old
-    ```
+   ```sh
+   docker rename pmm-server pmm-server-old
+   ```
 
+5. Run the new container:
 
-5. Run it.
+   ```sh
+   docker run \
+   --detach \
+   --restart always \
+   --publish 443:443 \
+   --volumes-from pmm-data \
+   --name pmm-server \
+   percona/pmm-server:2
+   ```
 
-    ```sh
-    docker run \
-    --detach \
-    --restart always \
-    --publish 443:443 \
-    --volumes-from pmm-data \
-    --name pmm-server \
-    percona/pmm-server:2
-    ```
+6. After upgrading, verify that PMM Server is running correctly and all your data is accessible.