Merge branch 'PMM3_Beta' into Monitor_from_Different-Nodes

percona · Nov 12, 2024 · bf45651 · bf45651
2 parents d0b7eb4 + 1a6117f
commit bf45651
Show file tree

Hide file tree

Showing 85 changed files with 909 additions and 960 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -1,4 +1,4 @@
-name: Build PMM Docs 2.x
+name: Build PMM Docs 3.x
 
 on:
   push:
@@ -43,6 +43,6 @@ jobs:
       # Builds Material-themed static web site in 'preview' branch
       - name: Build a themed site (2.x)
         run: |
-          PATH=$PATH:_resources/bin mike deploy 2.x -b preview
-          mike set-default 2.x -b preview
-          mike retitle 2.x "PMM 2.x (LATEST)" -b preview
+          PATH=$PATH:_resources/bin mike deploy 3.x -b preview
+          mike set-default 3.x -b preview
+          mike retitle 3.x "PMM 3.x (LATEST)" -b preview
diff --git a/README.md b/README.md
@@ -20,9 +20,11 @@ We use [MkDocs] to convert [Markdown] files into a static HTML website (or [PDF]
 
 The documentation source files are in the `docs` directory. (Other files in this repo are explained in [Directories and files](#directories-and-files).)
 
-The two major PMM versions are kept in separate branches:
+The three 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.
 

diff --git a/docs/Update_page.png b/docs/Update_page.png
diff --git a/docs/_images/PMM_Home_Dashboard_Panels_Upgrade.jpg b/docs/_images/PMM_Home_Dashboard_Panels_Upgrade.jpg
diff --git a/docs/_images/PMM_Home_Dashboard_Panels_Upgrade2.png b/docs/_images/PMM_Home_Dashboard_Panels_Upgrade2.png
diff --git a/docs/_images/PMM_Inventory_Item_Selection.png b/docs/_images/PMM_Inventory_Item_Selection.png
diff --git a/docs/_images/PMM_Inventory_Node_Agent_Properties.png b/docs/_images/PMM_Inventory_Node_Agent_Properties.png
diff --git a/docs/_images/PMM_Inventory_Node_Selection.png b/docs/_images/PMM_Inventory_Node_Selection.png
diff --git a/docs/_images/PMM_Inventory_Service_Selection.jpg b/docs/_images/PMM_Inventory_Service_Selection.jpg
diff --git a/docs/_images/PMM_Inventory_Service_Selection.png b/docs/_images/PMM_Inventory_Service_Selection.png
diff --git a/docs/_images/PMM_Inventory_cluster_view.png b/docs/_images/PMM_Inventory_cluster_view.png
diff --git a/docs/_images/PMM_Inventory_cluster_view_details.png b/docs/_images/PMM_Inventory_cluster_view_details.png
diff --git a/docs/_images/PMM_Inventory_cluster_view_filter.png b/docs/_images/PMM_Inventory_cluster_view_filter.png
diff --git a/docs/_images/PMM_Settings_Metrics_Resolution.jpg b/docs/_images/PMM_Settings_Metrics_Resolution.jpg
diff --git a/docs/_images/PMM_Settings_SSH_Key.jpg b/docs/_images/PMM_Settings_SSH_Key.jpg
diff --git a/docs/_images/PMM_access_edit_labels.png b/docs/_images/PMM_access_edit_labels.png
diff --git a/docs/_images/scrape_targets_03.png b/docs/_images/scrape_targets_03.png
diff --git a/docs/alert/index.md b/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. 
diff --git a/docs/alert/silence_alerts.md b/docs/alert/silence_alerts.md
@@ -1,7 +1,7 @@
 # Silence alerts
 
 Create a silence when you want to suppress/stop alerts and their associated notifications for a very specific amount of time. 
-Silences default to today’s current date and have a default duration of two hours. 
+Silences default to today’s current date and have a default duration of two hours.
 
 You can also schedule a silence for a future date and time. This is referred to as a `Pending` silence, which can be observed on the Silences page.
 
@@ -14,6 +14,7 @@ Silenced alerts are still recorded under **Alerting > Fired Alerts** so that you
 You can silence an alert by creating a silence from the **Silences** page.  Here you define labels that match the alert that you want to silence.
 
 To create a new silence:
+{.power-number}
 
 1. Click the **Create silence** button.
 2. Select the start and end date to indicate when the silence should go into effect and expire.
@@ -27,15 +28,16 @@ For more information on working with silences, see [About alerting silences](htt
 
 ## Alerting compatibility
 
-### Template compatibility with previous PMM versions
+### Template compatibility with PMM 2
 
-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**.
+After upgrading from the latest PMM 2 version to PMM 3, 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
 
 If you have existing YAML alert templates that you want to leverage in Percona Alerting:
+{.power-number}
 
 1. Go to **Alerting > Alert rule templates** tab and click **Add template** at the top right-hand side of the table.
 2. Upload a local .yaml file that contains the definition of one or more alert templates then click **Add**. Alert templates added in bulk will be displayed individually on **Alert rule templates** page.

diff --git a/docs/annotate/index.md b/docs/annotate/index.md
@@ -1,6 +1,3 @@
 # PMM annotation
-
-!!! alert alert-info ""
-    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, PMM automatically sends you an alert through your specified contact points.
+
+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, PMM automatically sends you an alert through your specified contact points. 
diff --git a/docs/api/authentication.md b/docs/api/authentication.md
@@ -21,6 +21,13 @@ Creating multiple tokens for the same service account is beneficial in the follo
 - when a token becomes compromised and needs to be replaced. Instead of revoking the entire service account, you can rotate or replace the affected token without disrupting other applications using the same service account.
 - when you want to implement token lifecycle management. You can set expiration dates for individual tokens, ensuring that they are regularly rotated and reducing the risk of unauthorized access.
 
+## Service Account name management
+
+To prevent node registration failures, PMM automatically manages service account names that exceed 200 characters using a `{prefix}_{hash}` pattern. For example, a very long service account name will be automatically shortened while maintaining uniqueness:
+
+- **original**: `very_long_mysql_database_server_in_production_environment_with_specific_location_details...`
+- **shortened**: `very_long_mysql_database_server_in_prod_4a7b3f9d`
+
 ## Generate a service account and token
 
 PMM uses Grafana service account tokens for authentication. These tokens are randomly generated strings that serve as alternatives to API keys or basic authentication passwords.

diff --git a/docs/backup/index.md b/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

diff --git a/docs/backup/mongodb-backup/backup_mongo.md b/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

diff --git a/docs/backup/mongodb-backup/create_PITR_mongo.md b/docs/backup/mongodb-backup/create_PITR_mongo.md
@@ -8,7 +8,7 @@ Point-in-Time Recovery helps you prevent data loss during a disaster such as cra
 PMM introduced the option to create PITR Backups for MongoDB in version 2.23, as part of the larger Backup Management feature. This implementation in PMM uses Percona Backup for MongoDB (pbm) behind the scenes.
 
 Percona Backup for MongoDB is a distributed, low-impact solution for achieving consistent backups of MongoDB sharded clusters and replica sets.
-Starting with PMM 2.32, restoring PITR backups is available for backups based on pbm ≤ 2.0.1. To restore PITR backups, make sure you have pbm ≥ 2.0.1 installed.
+Restoring PITR backups is available for backups based on pbm ≤ 2.0.1. To restore PITR backups, make sure you have pbm ≥ 2.0.1 installed.
 
  Percona Backup for MongoDB supports [Percona Server for MongoDB](https://www.percona.com/software/mongodb/percona-server-for-mongodb) and MongoDB Community ≤ 3.6, with [MongoDB Replication](https://docs.mongodb.com/manual/replication/) enabled. For more information, see the [Percona Backup for MongoDB documentation](https://docs.percona.com/percona-backup-mongodb/installation.html).
 

diff --git a/docs/backup/mongodb-backup/mongo_prerequisites.md b/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.
diff --git a/docs/backup/mongodb-backup/mongodb_limitations.md b/docs/backup/mongodb-backup/mongodb_limitations.md
@@ -4,7 +4,7 @@ Creating and restoring MongoDB backups in PMM currently has the following limita
 
 - Physical backups and restores are supported only for **Percona Server for MongoDB**.
 - Physical restores are not supported for deployments with arbiter nodes. For more information, see the [Percona Backup for MongoDB documentation](https://docs.percona.com/percona-backup-mongodb/usage/restore.html#physical-restore-known-limitations).
-- Creating backups for sharded clusters was included in PMM 2.38 and is available straight from the UI. However, restoring these backup artifacts is only possible 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).
+- Creating backups for sharded clusters is available straight from the UI. However, restoring these backup artifacts is only possible 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).
 - Retention policy is supported only for snapshot types of scheduled backups and for the S3-compatible storage type.
 - Before restoring, make sure to prevent clients from accessing the database.
 

diff --git a/docs/backup/mongodb-backup/restore_MongoDB_backups.md b/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)
diff --git a/docs/configure-pmm/ssh.md b/docs/configure-pmm/ssh.md
@@ -1,6 +1,6 @@
 # SSH Key
 
-This section lets you upload your public SSH key to access the PMM Server via SSH (for example, when accessing PMM Server as a [virtual appliance](../install-pmm/install-pmm-server/baremetal/virtual/index.md).
+This section enables you to upload your public SSH key for SSH access to the PMM Server, such as when accessing it as a [virtual appliance](../install-pmm/install-pmm-server/baremetal/virtual/index.md).
 
 ![!](../_images/PMM_Settings_SSH_Key.jpg)
 

diff --git a/docs/how-to/extend-metrics.md b/docs/how-to/extend-metrics.md
@@ -9,9 +9,9 @@ The collector is enabled by default. The following folders are used for differen
 
 | Resolution | Folder                                                                    |
 |------------|---------------------------------------------------------------------------|
-|  High      | `/usr/local/percona/pmm2/collectors/textfile-collector/high-resolution`   |
-|  Medium    | `/usr/local/percona/pmm2/collectors/textfile-collector/medium-resolution` |
-|  Low       | `/usr/local/percona/pmm2/collectors/textfile-collector/low-resolution`    |
+|  High      | `/usr/local/percona/pmm/collectors/textfile-collector/high-resolution`   |
+|  Medium    | `/usr/local/percona/pmm/collectors/textfile-collector/medium-resolution` |
+|  Low       | `/usr/local/percona/pmm/collectors/textfile-collector/low-resolution`    |
 
 ![!image](../_images/node-exporter.textfile-collector.1.png)
 
@@ -23,14 +23,14 @@ Metrics are stored on the PMM Server-side with additional labels related to this
 To statically set roles for a machine using labels:
 
 ```sh
-echo 'node_role{role="my_monitored_server_1"} 1' > /usr/local/percona/pmm2/collectors/textfile-collector/low-resolution/node_role.prom
+echo 'node_role{role="my_monitored_server_1"} 1' > /usr/local/percona/pmm/collectors/textfile-collector/low-resolution/node_role.prom
 ```
 
 Here's an example of a `cron` job that automatically pushes logged-in users:
 
 ```sh
 $ cat /etc/cron.d/loggedin_users
-*/1 * * * *     root    /usr/bin/who | /usr/bin/wc -l | sed -ne 's/^/node_loggedin_users /p' > /usr/local/percona/pmm2/collectors/textfile-collector/high-resolution/node_users.prom
+*/1 * * * *     root    /usr/bin/who | /usr/bin/wc -l | sed -ne 's/^/node_loggedin_users /p' > /usr/local/percona/pmm/collectors/textfile-collector/high-resolution/node_users.prom
 ```
 
 ![!image](../_images/node-exporter.textfile-collector.2.png)

diff --git a/docs/how-to/integrate-platform.md b/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.
@@ -59,20 +51,16 @@ To disconnect a PMM Server, go to > <i class="uil uil-cog"></i> **Configuration
 
 In situations where you are not able to disconnect servers yourself, ask your PMM Admin to disconnect the server for you. For example, you may not be able to disconnect servers when PMM is moved to a network segment without outbound connections to public networks.
 
-
-!!! note alert alert-primary "Availability"
-    This feature is available starting with PMM 2.29.0.
-
 If you cannot disconnect servers yourself, ask your PMM Admin to disconnect the server for you. For example, you may not be able to disconnect servers when PMM is moved to a network segment without outbound connections to public networks.
 
 If you are a PMM Admin, you can terminate any connections to Percona Platform, even if you are not logged into PMM with a Percona Account. However, we recommend logging in with a Percona Account before disconnecting servers, as this will automatically remove the disconnected servers from Percona Platform as well. 
 
-If you do disconnect servers without being connected with a Percona Account, you'll have to manually remove the unavailable servers from Percona Platform. This ensures that your list of connected PMM instances stays up-to-date in Percona Platform. 
+If you do disconnect servers without being connected with a Percona Account, you'll have to manually remove the unavailable servers from Percona Platform. This ensures that your list of connected PMM instances stays up-to-date in Percona Platform.
 
 To do this, go to [PMM instances](https://portal.percona.com/login), and remove any servers that you have already disconnected from PMM.
 
-
 ## Sign into PMM with your Percona Account
+
 Once you've successfully connected your PMM instance to the Percona Platform, you can also sign into PMM using your Percona Account:
 
 1. Log out of your existing PMM session.

diff --git a/docs/how-to/share-dashboard 2.md b/docs/how-to/share-dashboard 2.md
@@ -18,41 +18,32 @@ When you need to share a dashboard with your team members, you can either send t
 Rendering images requires the Image Renderer plug-in. If your PMM Admin has not installed this for your PMM instance, you will see the following error message under **Share Panel > Link**.
 ![!image](../_images/No_Image_Render_Plugin.png)
 
-To install the dependencies:
+To enable image rendering:
 
-1. Connect to your PMM Server Docker container.
+1. Deploy the Grafana Image Renderer container alongside PMM Server:
 
-    ```sh
-    docker exec -it pmm-server bash
-    ```
+   ```sh
+   docker run -d --name renderer --network=pmm-network grafana/grafana-image-renderer:latest
+   ```
 
-2. Install Grafana plug-ins.
+2. Stop your existing PMM Server container:
 
-    ```sh
-    grafana-cli plugins install grafana-image-renderer
-    ```
+   ```sh 
+   docker stop pmm-server
+   docker rm pmm-server
+   ```
 
-3. Restart Grafana.
+3. Start a new PMM Server container with the required environment variables:
 
-    ```sh
-    supervisorctl restart grafana
-    ```
-
-4. Install libraries.
-
-    ```sh
-    yum install -y libXcomposite libXdamage libXtst cups libXScrnSaver pango \
-    atk adwaita-cursor-theme adwaita-icon-theme at at-spi2-atk at-spi2-core \
-    cairo-gobject colord-libs dconf desktop-file-utils ed emacs-filesystem \
-    gdk-pixbuf2 glib-networking gnutls gsettings-desktop-schemas \
-    gtk-update-icon-cache gtk3 hicolor-icon-theme jasper-libs json-glib \
-    libappindicator-gtk3 libdbusmenu libdbusmenu-gtk3 libepoxy \
-    liberation-fonts liberation-narrow-fonts liberation-sans-fonts \
-    liberation-serif-fonts libgusb libindicator-gtk3 libmodman libproxy \
-    libsoup libwayland-cursor libwayland-egl libxkbcommon m4 mailx nettle \
-    patch psmisc redhat-lsb-core redhat-lsb-submod-security rest spax time \
-    trousers xdg-utils xkeyboard-config alsa-lib
-    ```
+   ```sh
+   docker run -d \
+   --name pmm-server \
+   --network=pmm-network \
+   -p 8443:443 \
+   -e GF_RENDERING_SERVER_URL=http://renderer:8081/render \
+   -e GF_RENDERING_CALLBACK_URL=https://pmm-server:8443/graph/ \
+   percona/pmm-server:latest
+   ```
 
 ## Render Dashboard image