diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index f0a34505cc..65454743fb 100644 --- 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: diff --git a/README.md b/README.md index 94da48eac5..0415dd116a 100644 --- 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 ## 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 new file mode 100644 index 0000000000..9a1b1bbc36 Binary files /dev/null and b/docs/Update_page.png differ diff --git a/docs/_images/PMM_Home_Dashboard_Panels_Upgrade.jpg b/docs/_images/PMM_Home_Dashboard_Panels_Upgrade.jpg index e749e7bb0e..539cf47e5a 100644 Binary files a/docs/_images/PMM_Home_Dashboard_Panels_Upgrade.jpg and b/docs/_images/PMM_Home_Dashboard_Panels_Upgrade.jpg differ diff --git a/docs/_images/PMM_Home_Dashboard_Panels_Upgrade2.png b/docs/_images/PMM_Home_Dashboard_Panels_Upgrade2.png new file mode 100644 index 0000000000..5017337d14 Binary files /dev/null and b/docs/_images/PMM_Home_Dashboard_Panels_Upgrade2.png differ diff --git a/docs/alert/index.md b/docs/alert/index.md index 88a1d7d289..bc795e6920 100644 --- 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 index c77433c828..806ab9b3c8 100644 --- 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. @@ -29,13 +30,14 @@ 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**. +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/backup/index.md b/docs/backup/index.md index 3052fd076a..1a29005216 100644 --- 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 index c5f8ed548b..9065749590 100644 --- 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/mongo_prerequisites.md b/docs/backup/mongodb-backup/mongo_prerequisites.md index 5146b9fa0d..d48af7e4f5 100644 --- 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. \ No newline at end of file + PMM 3 and later require PBM 2.0.1 or newer. \ No newline at end of file diff --git a/docs/backup/mongodb-backup/restore_MongoDB_backups.md b/docs/backup/mongodb-backup/restore_MongoDB_backups.md index f3666ee62b..cd4e0dd7d6 100644 --- 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) \ No newline at end of file diff --git a/docs/how-to/integrate-platform.md b/docs/how-to/integrate-platform.md index 601ed582e2..f484393b8b 100644 --- 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. diff --git a/docs/how-to/upgrade.md b/docs/how-to/upgrade.md deleted file mode 100644 index 1b767d270c..0000000000 --- a/docs/how-to/upgrade.md +++ /dev/null @@ -1,64 +0,0 @@ -# Upgrade - -## 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. - -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. - -### 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). - - - 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: - -- the current server version and release date; -- whether the server is up to date; -- the last time a check was made for updates. - -Click the refresh button to manually check for updates. - -If one is available, click the update button to update to the version indicated. - -!!! seealso alert alert-info "See also" - [PMM Server Docker upgrade](../setting-up/server/docker.md#upgrade) - -## Updating a PMM-Agent - -PMM-Agent can be updated from tarball: - - 1. Download `tar.gz` with `pmm2-client`. - 2. Extract it. - 3. Run `./install_tarball` script with the `-u` flag. - -**Hint!** The configuration file will be overwritten if you do not provide the `-u` flag while the `pmm-agent` is updated. - -## Upgrade from PMM 1 - -Because of the significant architectural changes between PMM1 and PMM2, there is no direct upgrade path. The approach to making the switch from PMM version 1 to 2 is a gradual transition, outlined [in this blog post](https://www.percona.com/blog/2019/11/27/running-pmm1-and-pmm2-clients-on-the-same-host/). - -In short, it involves first standing up a new PMM2 server on a new host and connecting clients to it. As new data is reported to the PMM2 server, old metrics will age with the retention period (30 days, by default), at which point you'll be able to shut down your existing PMM1 server. - -Any alerts configured through the Grafana UI will have to be recreated due to the target dashboard id's not matching between PMM1 and PMM2. In this instance we recommend moving to Alertmanager recipes in PMM2 for alerting which, for the time being, requires a separate Alertmanager instance. We are working on integrating this natively into PMM2 Server and expect to support your existing Alertmanager rules. diff --git a/docs/install-pmm/install-pmm-server/baremetal/docker/env_var.md b/docs/install-pmm/install-pmm-server/baremetal/docker/env_var.md index 4f85bc2c4a..3c711239d7 100644 --- a/docs/install-pmm/install-pmm-server/baremetal/docker/env_var.md +++ b/docs/install-pmm/install-pmm-server/baremetal/docker/env_var.md @@ -1,36 +1,165 @@ -# Environment variables - -Use the following Docker container environment variables (with `-e var=value`) to set PMM Server parameters. - -| Variable         | Description -| --------------------------------------------------------------- | ----------------------------------------------------------------------- -| `DISABLE_UPDATES` | Disables a periodic check for new PMM versions as well as ability to apply upgrades using the UI -| `DISABLE_TELEMETRY` | Disable built-in telemetry and disable STT if telemetry is disabled. -| `METRICS_RESOLUTION` | High metrics resolution in seconds. -| `METRICS_RESOLUTION_HR` | High metrics resolution (same as above). -| `METRICS_RESOLUTION_MR` | Medium metrics resolution in seconds. -| `METRICS_RESOLUTION_LR` | Low metrics resolution in seconds. -| `DATA_RETENTION` | The number of days to keep time-series data.
**N.B.** This must be set in a format supported by `time.ParseDuration`
and represent the complete number of days.
The supported units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, and `h`.
The value must be a multiple of 24, e.g., for 90 days 2160h (90 * 24). -| `ENABLE_VM_CACHE` | Enable cache in VM. -| `DISABLE_ALERTING` | Disables built-in Percona Alerting, which is enabled by default. -| `ENABLE_AZUREDISCOVER` | Enable support for discovery of Azure databases. -| `DISABLE_BACKUP_MANAGEMENT` | Disables Backup Management, which is enabled by default. -| `PMM_DEBUG` | Enables a more verbose log level. -| `PMM_TRACE` | Enables a more verbose log level including trace-back information. -| `PMM_PUBLIC_ADDRESS` | External IP address or the DNS name on which PMM server is running. -| `PMM_WATCHTOWER_HOST=${PMM_WATCHTOWER_HOST:-http://watchtower:8080}` | Specifies the connection URL for the WatchTower container, including the schema (http), host (watchtower), and port (8080). -| `PMM_WATCHTOWER_TOKEN=${PMM_WATCHTOWER_TOKEN:-123}` | Defines the authentication token used for secure communication between the PMM Server container and the WatchTower container. Make sure this matches the value of the `WATCHTOWER_HTTP_API_TOKEN` environment variable set in the WatchTower container. - -## Other variables - -The following variables are also supported but values passed are not verified by PMM. If any other variable is found, it will be considered invalid and the server won't start. - -| Variable | Description -| --------------------------------------------------------------- | ------------------------------------------------------ -| `_`, `HOME`, `HOSTNAME`, `LANG`, `PATH`, `PWD`, `SHLVL`, `TERM` | Default environment variables. -| `GF_*` | [Grafana](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/) environment variables. -| `VM_*` | [VictoriaMetrics'](https://docs.victoriametrics.com/Single-server-VictoriaMetrics.html#environment-variables) environment variables. -| `SUPERVISOR_` | `supervisord` environment variables. -| `KUBERNETES_` | Kubernetes environment variables. -| `MONITORING_` | Kubernetes monitoring environment variables. -| `PERCONA_TEST_` | Unknown variable but won't prevent the server starting. \ No newline at end of file +# Environment variables in PMM + +Configure PMM Server by setting Docker container environment variables using the `-e var=value` syntax: + +```bash +docker run -e PMM_DATA_RETENTION=720h -e PMM_DEBUG=true percona/pmm-server:3 +``` + +## Core configuration variables + +### Performance & storage + +| Variable | Default | Description | Example | +|----------|---------|-------------|----------| +| `PMM_DATA_RETENTION` | `30d` | Duration to retain metrics data. Must be in multiples of 24h. | `720h` (30 days) | +| `PMM_METRICS_RESOLUTION` | `1s` | Base metrics collection interval | `5s` | +| `PMM_METRICS_RESOLUTION_HR` | `5s` | High-resolution metrics interval | `10s` | +| `PMM_METRICS_RESOLUTION_MR` | `10s` | Medium-resolution metrics interval | `30s` | +| `PMM_METRICS_RESOLUTION_LR` | `60s` | Low-resolution metrics interval | `300s` | + +### Feature flags + +| Variable | Default | Effect when enabled | +|----------|---------|-------------------| +| `PMM_ENABLE_UPDATES` | `true` | Allows version checks and UI updates | +| `PMM_ENABLE_TELEMETRY` | `true` | Enables usage data collection | +| `PMM_ENABLE_ALERTING` | `true` | Enables Percona Alerting system | +| `PMM_ENABLE_BACKUP_MANAGEMENT` | `true` | Enables backup features | +| `PMM_ENABLE_AZURE_DISCOVER` | `false` | Enables Azure database discovery | + +### Debugging + +| Variable | Default | Purpose | +|----------|---------|---------| +| `PMM_DEBUG` | `false` | Enables verbose logging | +| `PMM_TRACE` | `false` | Enables detailed trace logging | + +## Advanced configuration + +### Networking + +| Variable | Description | +|----------|-------------| +| `PMM_PUBLIC_ADDRESS` | External DNS/IP for PMM server | +| `PMM_INTERFACE_TO_BIND` | Network interface binding | + +### Database connections + +| Variable | Purpose | +|----------|----------| +| `PMM_CLICKHOUSE_*` | ClickHouse connection settings | +| `PMM_POSTGRES_*` | PostgreSQL connection settings | + +### Development & testing + +| Variable | Use case | +|----------|----------| +| `PMM_DEV_*` | Development environment settings | +| `PMM_TEST_*` | Testing environment settings | + +### Supported external variables + +- **Grafana**: All `GF_*` variables +- **VictoriaMetrics**: All `VM_*` variables +- **Kubernetes**: All `KUBERNETES_*` variables +- **System**: Standard variables like `HOME`, `PATH`, etc. + +## Variables for migrating from PMM v2 to PMM v3 + +When migrating from PMM v2 to PMM v3, you'll need to update your environment variables to match the new naming convention. This is because PMM v3 introduces several important changes to improve consistency and clarity: + +- environment variables now use `PMM_` prefix +- some boolean flags reversed (e.g., `DISABLE_` → `ENABLE_`) +- removed deprecated variables + +### Examples + +```bash +# PMM v2 +-e DISABLE_UPDATES=true -e DATA_RETENTION=720h + +# PMM v3 equivalent +-e PMM_ENABLE_UPDATES=false -e PMM_DATA_RETENTION=720h +``` + +### Migration reference table + +??? note "Click to expand migration reference table" + + #### Configuration variables + | PMM 2 | PMM 3 | Comments | + |---------------------------------|------------------------------------|------------------------------| + | `DATA_RETENTION` | `PMM_DATA_RETENTION` | | + | `DISABLE_ALERTING` | `PMM_ENABLE_ALERTING` | | + | `DISABLE_UPDATES` | `PMM_ENABLE_UPDATES` | | + | `DISABLE_TELEMETRY` | `PMM_ENABLE_TELEMETRY` | | + | `DISABLE_BACKUP_MANAGEMENT` | `PMM_ENABLE_BACKUP_MANAGEMENT` | Note the reverted boolean | + | `ENABLE_AZUREDISCOVER` | `PMM_ENABLE_AZURE_DISCOVER` | | + | `ENABLE_RBAC` | `PMM_ENABLE_ACCESS_CONTROL` | | + | `LESS_LOG_NOISE` | | Removed in PMM v3 | + + #### Metrics configuration + | PMM 2 | PMM 3 | + |---------------------------------|------------------------------------| + | `METRICS_RESOLUTION` | `PMM_METRICS_RESOLUTION` | + | `METRICS_RESOLUTION_HR` | `PMM_METRICS_RESOLUTION_HR` | + | `METRICS_RESOLUTION_LR` | `PMM_METRICS_RESOLUTION_LR` | + | `METRICS_RESOLUTION_MR` | `PMM_METRICS_RESOLUTION_MR` | + + #### Authentication & Percona Platform + | PMM 2 | PMM 3 | + |---------------------------------|------------------------------------| + | `OAUTH_PMM_CLIENT_ID` | `PMM_DEV_OAUTH_CLIENT_ID` | + | `OAUTH_PMM_CLIENT_SECRET` | `PMM_DEV_OAUTH_CLIENT_SECRET` | + | `PERCONA_PLATFORM_API_TIMEOUT` | `PMM_DEV_PERCONA_PLATFORM_API_TIMEOUT` | + | `PERCONA_TEST_PLATFORM_ADDRESS` | `PMM_DEV_PERCONA_PLATFORM_ADDRESS` | + | `PERCONA_TEST_PLATFORM_INSECURE`| `PMM_DEV_PERCONA_PLATFORM_INSECURE`| + | `PERCONA_TEST_PLATFORM_PUBLIC_KEY` | `PMM_DEV_PERCONA_PLATFORM_PUBLIC_KEY` | + + #### ClickHouse configuration + | PMM 2 | PMM 3 | Comments | + |-------------------------------------|------------------------------------|--------------------------| + | `PERCONA_TEST_PMM_CLICKHOUSE_ADDR` | `PMM_CLICKHOUSE_ADDR` | | + | `PERCONA_TEST_PMM_CLICKHOUSE_DATABASE` | `PMM_CLICKHOUSE_DATABASE` | | + | `PERCONA_TEST_PMM_CLICKHOUSE_DATASOURCE` | `PMM_CLICKHOUSE_DATASOURCE` | | + | `PERCONA_TEST_PMM_CLICKHOUSE_HOST` | `PMM_CLICKHOUSE_HOST` | | + | `PERCONA_TEST_PMM_CLICKHOUSE_PORT` | `PMM_CLICKHOUSE_PORT` | | + | `PERCONA_TEST_PMM_DISABLE_BUILTIN_CLICKHOUSE` | `PMM_DISABLE_BUILTIN_CLICKHOUSE` | | + | `PERCONA_TEST_PMM_CLICKHOUSE_BLOCK_SIZE` | | Removed in PMM v3, new version| + | `PERCONA_TEST_PMM_CLICKHOUSE_POOL_SIZE` | | Removed in PMM v3, new version| + + #### PostgreSQL configuration + | PMM 2 | PMM 3 | + |-------------------------------------|------------------------------------| + | `PERCONA_TEST_POSTGRES_ADDR` | `PMM_POSTGRES_ADDR` | + | `PERCONA_TEST_POSTGRES_DBNAME` | `PMM_POSTGRES_DBNAME` | + | `PERCONA_TEST_POSTGRES_USERNAME` | `PMM_POSTGRES_USERNAME` | + | `PERCONA_TEST_POSTGRES_DBPASSWORD` | `PMM_POSTGRES_DBPASSWORD` | + | `PERCONA_TEST_POSTGRES_SSL_CA_PATH` | `PMM_POSTGRES_SSL_CA_PATH` | + | `PERCONA_TEST_POSTGRES_SSL_CERT_PATH` | `PMM_POSTGRES_SSL_CERT_PATH` | + | `PERCONA_TEST_POSTGRES_SSL_KEY_PATH` | `PMM_POSTGRES_SSL_KEY_PATH` | + | `PERCONA_TEST_POSTGRES_SSL_MODE` | `PMM_POSTGRES_SSL_MODE` | + | `PERCONA_TEST_PMM_DISABLE_BUILTIN_POSTGRES` | `PMM_DISABLE_BUILTIN_POSTGRES` | + + #### Telemetry & development + | PMM 2 | PMM 3 | + |-------------------------------------|------------------------------------| + | `PMM_TEST_TELEMETRY_DISABLE_SEND` | `PMM_DEV_TELEMETRY_DISABLE_SEND` | + | `PERCONA_TEST_TELEMETRY_DISABLE_START_DELAY` | `PMM_DEV_TELEMETRY_DISABLE_START_DELAY` | + | `PMM_TEST_TELEMETRY_FILE` | `PMM_DEV_TELEMETRY_FILE` | + | `PERCONA_TEST_TELEMETRY_HOST` | `PMM_DEV_TELEMETRY_HOST` | + | `PERCONA_TEST_TELEMETRY_INTERVAL` | `PMM_DEV_TELEMETRY_INTERVAL` | + | `PERCONA_TEST_TELEMETRY_RETRY_BACKOFF` | `PMM_DEV_TELEMETRY_RETRY_BACKOFF` | + | `PERCONA_TEST_VERSION_SERVICE_URL` | `PMM_DEV_VERSION_SERVICE_URL` | + | `PERCONA_TEST_STARLARK_ALLOW_RECURSION` | `PMM_DEV_ADVISOR_STARLARK_ALLOW_RECURSION` | + + #### Removed variables + | PMM 2 | PMM 3 | Comments | + |-------------------------------------|------------------------------------|------------------------------| + | `PERCONA_TEST_AUTH_HOST` | | Removed, use `PMM_DEV_PERCONA_PLATFORM_ADDRESS` | + | `PERCONA_TEST_CHECKS_HOST` | | Removed, use `PMM_DEV_PERCONA_PLATFORM_ADDRESS` | + | `PERCONA_TEST_CHECKS_INTERVAL` | | Removed, not used | + | `PERCONA_TEST_CHECKS_PUBLIC_KEY` | | Removed, use `PMM_DEV_PERCONA_PLATFORM_PUBLIC_KEY` | + | `PERCONA_TEST_NICER_API` | | Removed in PMM v3 | + | `PERCONA_TEST_SAAS_HOST` | | Removed, use `PMM_DEV_PERCONA_PLATFORM_ADDRESS` | \ No newline at end of file diff --git a/docs/install-pmm/install-pmm-server/baremetal/docker/index.md b/docs/install-pmm/install-pmm-server/baremetal/docker/index.md index b0241dfe8d..8adb2d0149 100644 --- a/docs/install-pmm/install-pmm-server/baremetal/docker/index.md +++ b/docs/install-pmm/install-pmm-server/baremetal/docker/index.md @@ -1,21 +1,24 @@ # Install PMM Server with Docker container - This section provides instructions for running PMM Server with Docker based on the [PMM Docker image](https://hub.docker.com/r/percona/pmm-server). ## Running PMM Server with Watchtower -To enable PMM Server upgrades via the **Upgrade Now** button on the PMM Home dashboard, you need to set up Watchtower alongside PMM Server during installation. Watchtower is a container monitoring tool that updates Docker containers to the latest version when triggered. +To enable PMM Server upgrades via the **Upgrade page** and the **Upgrade Now** button on the Home dashboard, you must configure Watchtower during the PMM Server installation. Watchtower is a container monitoring tool that automatically updates Docker containers to their latest version when triggered. + +The [Easy-install script](../easy-install.md) script includes Watchtower commands, allowing for a one-step setup of PMM alongside Watchtower. + +You can also install PMM 3 manually, following the instructions below. -The PMM 3 Beta release will integrate Watchtower commands into the [Easy-install script](../easy-install.md), allowing for a one-step setup of PMM alongside Watchtower. Until then, you can manually test the PMM installation by following the instructions using the instructions provided below. +## Installing PMM Server manually -Before proceeding, review the installation prerequisites and choose a method to run PMM Server with Docker based on your preferred data storage option: +Before starting the installation, review the installation prerequisites below and choose a method to run PMM Server with Docker based on your preferred data storage option: - [Running Docker with Data container](../docker/run_with_data_container.md) - [Running Docker with host directory](../docker/run_with_host_dir.md) - [Running Docker with volume](../docker/run_with_vol.md) -**Prerequisites** +### Manual installation prerequisites - Install [Docker](https://docs.docker.com/get-docker/) version 17.03 or higher. - Ensure your CPU (and any virtualization layer you may be using) supports `x86-64-v2`. diff --git a/docs/install-pmm/install-pmm-server/baremetal/docker/run_with_data_container.md b/docs/install-pmm/install-pmm-server/baremetal/docker/run_with_data_container.md index de80cec896..e0a82b79a3 100644 --- a/docs/install-pmm/install-pmm-server/baremetal/docker/run_with_data_container.md +++ b/docs/install-pmm/install-pmm-server/baremetal/docker/run_with_data_container.md @@ -53,4 +53,4 @@ To run Docker with data container: docker run -v /var/run/docker.sock:/var/run/docker.sock -e WATCHTOWER_HTTP_API_UPDATE=1 -e WATCHTOWER_HTTP_API_TOKEN=your_watchtower_token --hostname=your_watchtower_host --network=pmm_default docker.io/perconalab/watchtower ``` -6. Visit `https://localhost:443` to see the PMM user interface in a web browser. (If you are accessing the docker host remotely, replace `localhost` with the IP or server name of the host.) +6. Visit `https://localhost:443` to see the PMM user interface in a web browser. (If you are accessing the docker host remotely, replace `localhost` with the IP or server name of the host. diff --git a/docs/pmm-upgrade/index.md b/docs/pmm-upgrade/index.md index 208bb4a398..175418de49 100644 --- a/docs/pmm-upgrade/index.md +++ b/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) \ No newline at end of file +* [Upgrade from PMM 2](upgrade_from_pmm_2.md) diff --git a/docs/pmm-upgrade/ui_upgrade.md b/docs/pmm-upgrade/ui_upgrade.md index e048bd6b06..99ece0875b 100644 --- a/docs/pmm-upgrade/ui_upgrade.md +++ b/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) \ No newline at end of file +![PMM Home Dashboard Upgrade Panel](../_images/PMM_Home_Dashboard_Panels_Upgrade.jpg) diff --git a/docs/pmm-upgrade/upgrade_agent.md b/docs/pmm-upgrade/upgrade_agent.md index ebd74f1df3..aa35bd6556 100644 --- a/docs/pmm-upgrade/upgrade_agent.md +++ b/docs/pmm-upgrade/upgrade_agent.md @@ -1,10 +1,44 @@ -# 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 pmm-client + pmm-client-3.0.0-6.el9.x86_64 : Percona Monitoring and Management Client (pmm-agent) + pmm-client-3.0.1-6.el9.x86_64 : Percona Monitoring and Management Client (pmm-agent) + yum update pmm-client-3.0.1-6.el9.x86_64 + ``` + +### 2. 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" diff --git a/docs/pmm-upgrade/upgrade_aws.md b/docs/pmm-upgrade/upgrade_aws.md index d5bf047d75..70b9250515 100644 --- a/docs/pmm-upgrade/upgrade_aws.md +++ b/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} diff --git a/docs/pmm-upgrade/upgrade_docker.md b/docs/pmm-upgrade/upgrade_docker.md index 7a52ac3ac1..6c202fb8b6 100644 --- a/docs/pmm-upgrade/upgrade_docker.md +++ b/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:3 + ``` -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:8443 \ + --volumes-from pmm-data \ + --name pmm-server \ + percona/pmm-server:3 + ``` - ```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. diff --git a/docs/pmm-upgrade/upgrade_from_pmm_1.md b/docs/pmm-upgrade/upgrade_from_pmm_1.md deleted file mode 100644 index c504d07acf..0000000000 --- a/docs/pmm-upgrade/upgrade_from_pmm_1.md +++ /dev/null @@ -1,7 +0,0 @@ -# Upgrade from PMM 1 - -Because of the significant architectural changes between PMM1 and PMM2, there is no direct upgrade path. The approach to making the switch from PMM version 1 to 2 is a gradual transition, outlined in [this blog post](https://www.percona.com/blog/running-pmm1-and-pmm2-clients-on-the-same-host/). - -In short, it involves first standing up a new PMM2 server on a new host and connecting clients to it. As new data is reported to the PMM2 server, old metrics will age with the retention period (30 days, by default), at which point you’ll be able to shut down your existing PMM1 server. - -Any alerts configured through the Grafana UI will have to be recreated due to the target dashboard id’s not matching between PMM1 and PMM2. In this instance we recommend moving to Alertmanager recipes in PMM2 for alerting which, for the time being, requires a separate Alertmanager instance. We are working on integrating this natively into PMM2 Server and expect to support your existing Alertmanager rules. \ No newline at end of file diff --git a/docs/pmm-upgrade/upgrade_from_pmm_2.md b/docs/pmm-upgrade/upgrade_from_pmm_2.md new file mode 100644 index 0000000000..c5fb26ad6e --- /dev/null +++ b/docs/pmm-upgrade/upgrade_from_pmm_2.md @@ -0,0 +1,63 @@ +# Upgrade from PMM 2 to PMM 3 + +PMM 3 introduces significant architectural changes that require gradual transition from PMM 2: + +## Step 1: Update PMM 2 Server to the latest version +{.power-number} + +1. From the **Home** page, scroll to the **PMM Upgrade** panel and click the Refresh button to manually check for updates. +![PMM Home Dashboard Upgrade Panel](../_images/PMM_Home_Dashboard_Panels_Upgrade2.png) +2. If an update is available, click the **Update** button to install the latest PMM 2 version. +3. Verify the update was successful by checking the version number after the update completes. + +## Step 2: Upgrade PMM 2 Server to PMM 3 + +Follow these manual steps to upgrade your PMM 2 Server to PMM 3: +{.power-number} + +1. Pull the new PMM 3 Server Docker image: + + ```sh + docker pull percona/pmm-server:3 + ```1. Stop all services of the PMM 2 server container: + + ```sh + docker exec -t pmm-server supervisorctl stop all + ``` + +2. Transfer ownership of all directories and files in the `/srv` directory to the pmm user: + + ```sh + docker exec -t pmm-server chown -R pmm:pmm /srv + ``` + +3. Stop and remove the PMM 2 server container: + + ```sh + docker stop pmm-server && docker rm pmm-server + ``` + +4. Run a new container based on the PMM 3 image, ensuring you pass the same pmm-data volume: + + ```sh + docker run -d -p 80:8080 -p 443:8443 -v pmm-data:/srv --name pmm-server --restart always percona/pmm-server:3 + ``` + +5. Verify that the new PMM 3 Server container is running and accessible through the UI. + +## Step 3: Upgrade PMM 2 Clients to PMM 3 + +!!! caution alert alert-warning "Important" + Support of PMM 2 Clients by PMM 3 Server will be limited to metrics and Query Analytics (QAN) only. This limited support will be dropped in PMM 3.3. + +Depending on your initial installation method, update PMM Clients using your operating system's package manager or by updating from a tarball. +For detailed instructions, see the [Upgrade PMM Client topic](../pmm-upgrade/upgrade_agent.md). + +### Post-upgrade steps + +After you finish migrating: +{.power-number} + +1. Verify that all clients are up to date by checking **PMM Configuration > Updates**. +2. Confirm all previously monitored services are reporting correctly to the new PMM 3 Server by reviewing **Configuration > PMM Inventory > Services**. +3. Check the dashboards to make sure you're receiving the metrics information, QAN data. diff --git a/docs/pmm-upgrade/upgrade_helm.md b/docs/pmm-upgrade/upgrade_helm.md index e9d579a28f..fc6f627905 100644 --- a/docs/pmm-upgrade/upgrade_helm.md +++ b/docs/pmm-upgrade/upgrade_helm.md @@ -1,21 +1,50 @@ # Upgrade PMM Server using Helm -Percona will release a new chart updating its containers if a new version of the main container is available, there are any significant changes, or critical vulnerabilities exist. +Percona releases new chart versions to update containers when: -By default UI update feature is disabled and should not be enabled. Do not modify that parameter or add it while modifying the custom `values.yaml` file: +- A new version of the main container is available +- Significant changes are made +- Critical vulnerabilities are addressed -```yaml -pmmEnv: - DISABLE_UPDATES: "1" -``` +!!! caution alert alert-warning "UI Update feature disabled by default" + The UI update feature is disabled by default and should remain so. Do not modify or add the following parameter in your custom `values.yaml` file: + > ```yaml + > pmmEnv: + > DISABLE_UPDATES: "1" + > ``` -Before updating the helm chart, it is recommended to pre-pull the image on the node where PMM is running, as the PMM images could be large and could take time to download. +## Before you begin +{.power-number} -Update PMM as follows: +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. -```sh -helm repo update percona -helm upgrade pmm -f values.yaml percona/pmm -``` +2. Pre-pull the image: To reduce downtime, pre-pull the new image on the node where PMM is running: -This will check updates in the repo and upgrade deployment if the updates are available. \ No newline at end of file + ```sh + # Replace with the latest PMM version + docker pull percona/pmm-server: + ``` + +## Upgrade steps +{.power-number} + +1. Update Helm repository: + ```sh + helm repo update percona + ``` + +2. Upgrade PMM : + + ```sh + helm upgrade pmm -f values.yaml percona/pmm + ``` +3. After the upgrade, verify that PMM Server is running correctly: + + ```sh + kubectl get pods | grep pmm-server + ``` +4. Check the logs for any errors: + + ```sh + kubectl logs deployment/pmm-server + ``` \ No newline at end of file diff --git a/docs/pmm-upgrade/upgrade_podman.md b/docs/pmm-upgrade/upgrade_podman.md index cfbc9d1145..61e5e90887 100644 --- a/docs/pmm-upgrade/upgrade_podman.md +++ b/docs/pmm-upgrade/upgrade_podman.md @@ -1,63 +1,48 @@ -# Upgrade PMM Server using podman +# Upgrade PMM Server using Podman -??? info "Summary" +## Before you begin - !!! summary alert alert-info "" - - Perform a backup. - - Update PMM tag. - - Pre-pull image. - - Run it. +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. - --- - -!!! caution alert alert-warning "Important" - You cannot downgrade. To go to a previous version, you must create a backup before upgrading. - -!!! hint alert alert-success "Tip" - To see the current release running on your system, 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 podman exec -it pmm-server \ curl -ku admin:admin https://localhost/v1/version ``` -(If you are accessing the podman host remotely, replace `localhost` with the IP or server name of the host.) -{.power-number} +## Upgrade steps -1. Perform a [backup](../install-pmm/install-pmm-server/baremetal/podman/backup_container_podman.md). +{.power-number} +1. [Back up your data](../install-pmm/install-pmm-server/baremetal/podman/backup_container_podman.md). +2. Update PMM tag by editing `~/.config/pmm-server/env` file and running the following command to set the latest release version: -2. Update PMM tag. + ```sh + sed -i "s/PMM_TAG=.*/PMM_TAG=3.0.0/g" ~/.config/pmm-server/env + ``` - Edit `~/.config/pmm-server/env` and create/update with a new tag from [latest release](https://per.co.na/pmm/latest): +3. Pre-pull the new image to ensure a faster restart: ```sh - sed -i "s/PMM_TAG=.*/PMM_TAG=2.33.0/g" ~/.config/pmm-server/env - ``` + source ~/.config/pmm-server/env + podman pull ${PMM_IMAGE}:${PMM_TAG} + ``` -3. Pre-pull image for faster restart. +4. Restart PMM Server: - + systemctl --user restart pmm-server + ``` + +5. After the upgrade, verify that PMM Server is running correctly: ```sh - source ~/.config/pmm-server/env - podman pull ${PMM_IMAGE}:${PMM_TAG} + podman ps | grep pmm-server ``` -4. Run PMM. +6. Check the logs for any errors: ```sh - systemctl --user restart pmm-server + podman logs pmm-server ``` - - diff --git a/docs/reference/faq.md b/docs/reference/faq.md index 8d890ba815..9720751809 100644 --- a/docs/reference/faq.md +++ b/docs/reference/faq.md @@ -18,17 +18,9 @@ - [Setting up PMM Server](setting-up/server/index.md) - [Setting up PMM Client](setting-up/client/index.md) -## How can I upgrade from version 1? +## How can I upgrade from version 2? -There is no direct software upgrade path. - -You must [set up](setting-up/index.md) PMM 2 and connect your existing clients to it. - -When all data is registered in PMM2 and expired in PMM1, decommission your PMM1 instance. - -!!! seealso alert alert-info "See also" - - [Upgrade from PMM1](how-to/upgrade.md#upgrade-from-pmm-1) - - [Percona blog: Running PMM1 and PMM2 Clients on the Same Host](https://www.percona.com/blog/2019/11/27/running-pmm1-and-pmm2-clients-on-the-same-host/) +A direct software upgrade path is not available. For detailed instructions, see [Upgrade from PMM2](../pmm-upgrade/upgrade_from_pmm_2.md) ## How to control data retention? {: #retention } @@ -121,7 +113,7 @@ The `prometheus.yml` file can be regenerated by restarting the PMM Server contai - [API](details/api.md) - [Percona blog: Extending PMM’s Prometheus Configuration](https://www.percona.com/blog/2020/03/23/extending-pmm-prometheus-configuration/) -## How to troubleshoot an Update? +## How to troubleshoot an update? See [Troubleshoot update](how-to/troubleshoot.md#update). diff --git a/docs/reference/why_pmm.md b/docs/reference/why_pmm.md index b40656c1dc..c0a3dfabf0 100644 --- a/docs/reference/why_pmm.md +++ b/docs/reference/why_pmm.md @@ -19,17 +19,10 @@ - [Setting up PMM Server](setting-up/server/index.md) - [Setting up PMM Client](setting-up/client/index.md) -## How can I upgrade from version 1? +## How can I upgrade from version 2? -There is no direct software upgrade path. +There is no direct software upgrade path. For infomation, see [Upgrade from PMM2](../pmm-upgrade/upgrade_from_pmm_2.md). -You must [set up](setting-up/index.md) PMM 2 and connect your existing clients to it. - -When all data is registered in PMM2 and expired in PMM1, decommission your PMM1 instance. - -!!! seealso alert alert-info "See also" - - [Upgrade from PMM1](how-to/upgrade.md#upgrade-from-pmm-1) - - [Percona blog: Running PMM1 and PMM2 Clients on the Same Host](https://www.percona.com/blog/2019/11/27/running-pmm1-and-pmm2-clients-on-the-same-host/) ## How to control data retention? {: #retention } diff --git a/docs/release-notes/3.0.0_Beta.md b/docs/release-notes/3.0.0_Beta.md index 86f05b8629..4a358b348e 100644 --- a/docs/release-notes/3.0.0_Beta.md +++ b/docs/release-notes/3.0.0_Beta.md @@ -10,6 +10,24 @@ It enables you to observe the health of your database systems, explore new patte ## Release highlights +### Streamlined update process + +We've enhanced PMM's update system with a new **Update** page, accessible via **PMM Configuration > Updates**. This new intuitive interface replaces the previous RPM-based update method, allowing you to easily track versions, configurations, and the health status of your PMM Server and Clients. + +This change comes with proactive notifications, alerting you immediately when new versions are released, and providing detailed change summaries so you can make informed decisions before upgrading. + +![Update page](../Update_page.png) + +#### New upgrade environment variables + +When migrating from PMM v2 to PMM v3, you’ll need to update your environment variables to match the new naming convention. This is because PMM v3 introduces several important changes to improve consistency and clarity: + +- environment variables now use PMM_ prefix +- some boolean flags reversed (e.g., `DISABLE_` → `ENABLE_`) +- removed deprecated variables + +To check the Migration reference table, see [Environment variables in PMM](../install-pmm/install-pmm-server/baremetal/docker/env_var.md##variables-for-migrating-from-pmm-v2-to-pmm-v3). + ### Encryption of sensitive data To strengthen the security of your monitoring setup, all sensitive information stored in the PMM Server database, including usernames, passwords, AWS keys, Azure credentials, and TLS/SSL certificates, is now encrypted. diff --git a/docs/troubleshoot/upgrade_issues.md b/docs/troubleshoot/upgrade_issues.md index 7c3dc3e12d..58062d0356 100644 --- a/docs/troubleshoot/upgrade_issues.md +++ b/docs/troubleshoot/upgrade_issues.md @@ -1,71 +1,15 @@ -# Upgrade issues +# Troubleshoot upgrade issues ## PMM Server not updating correctly - -If the PMM Server wasn't updated correctly, or if you have concerns about the release, you can force the update process in 2 ways: -{.power-number} - -1. From the UI - Home panel: click the Alt key on the reload icon in the Update panel to make the Update Button visible even if you are on the same version as available for update. Pressing this button will force the system to rerun the update so that any broken or not installed components can be installed. In this case, you'll go through the usual update process with update logs and successful messages at the end. - -2. By API call (if UI not available): You can call the Update API directly with: - - ```sh - curl --user admin:admin --request POST 'http://PMM_SERVER/v1/Updates/Start' - ``` - - Replace `admin:admin` with your username/password, and replace `PMM_SERVER` with your server address. - - !!! note alert alert-primary "Note" - You will not see the logs using this method. - - Refresh The Home page in 2-5 minutes, and you should see that PMM was updated. - -3. Upgrade PMM Server using [Docker](../pmm-upgrade/upgrade_docker.md). - - -## PMM Server not showing latest versions available with the instances created from AWS - -For PMM versions prior to 2.33.0, in specific environments, including AWS, some EPEL repository mirrors did not respond within the time limit defined by `pmm-update` (currently set to 30 seconds). It was causing supervisord to kill pmm-update-checker, which determines if a newer PMM Server is available for upgrade. - -**Solution** - -Log in to the PMM Server and run the following command as a root user: - -```sh - $ yum-config-manager --setopt=epel.timeout=1 --save -``` - -## PMM Server fails while upgrading - -A bug in PMM Server ansible scripts caused PMM to upgrade Nginx's dependencies without updating Nginx itself. Due to this, PMM throws an error while upgrading and cannot upgrade to a newer version. - -!!! caution alert alert-warning "Important" - This issue has been resolved for PMM version 2.33.0. However, the issue persists on all the versions prior to 2.33.0. - - -**Solution** - -While PMM is being upgraded, log in to the PMM Server and run the following command: - -```sh - sed -i 's/- nginx/- nginx*/' /usr/share/pmm-update/ansible/playbook/tasks/update.yml -``` - - -## Admin user cannot access PMM after upgrading - -After upgrading PMM from version 2.39.0 to 2.40.0 (not el7) using Docker, the `admin` user cannot access the PMM UI. - -**Solution**: To fix the problem and gain back admin access to the PMM interface execute the following: - -```sh -# psql -U grafana -grafana=> update "user" set id='1' where login='admin'; -UPDATE 1 -grafana=> \q - -# grafana cli --homepath=/usr/share/grafana --config=/etc/grafana/grafana.ini admin reset-admin-password -``` - - +If the automatic update process isn't working, you can force an update using the API: + +1. Open your terminal. +2. Run the update command, replacing : with your credentials and with your PMM server addressЖ + + ```curl -X POST \ + --user : \ + 'http:///v1/server/updates:start' \ + -H 'Content-Type: application/json' + ``` +3. Wait 2-5 minutes and refresh the PMM Home page to verify the update. \ No newline at end of file diff --git a/mkdocs-base.yml b/mkdocs-base.yml index ad47fd7574..25a040e2b7 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -227,10 +227,10 @@ nav: - Manual upgrade: - pmm-upgrade/upgrade_docker.md - pmm-upgrade/upgrade_podman.md - - Upgrade PM server in K8s: + - Upgrade PMM Server in K8s: - pmm-upgrade/upgrade_helm.md - pmm-upgrade/upgrade_agent.md - - pmm-upgrade/upgrade_from_pmm_1.md + - pmm-upgrade/upgrade_from_pmm_2.md - pmm-upgrade/upgrade_aws.md - Uninstall: - Uninstall PMM Client: