PMM-14993 Add one-step PMM client installer script and UI integration by theTibi · Pull Request #5250 · percona/pmm

theTibi · 2026-04-14T13:22:01Z

Introduced a new script install-pmm-client.sh for streamlined installation of the PMM client.
Updated Ansible tasks to copy the installer script to the appropriate directory.
Enhanced documentation with a new section for one-step installation from the UI.
Added a new Install Client page in the UI for generating installation commands.
Integrated navigation for the new Install Client page within the application.

This update simplifies the PMM client installation process and improves user experience through the UI.

Link to the Feature Build:
Percona-Lab/pmm-submodules#4330

If this PR adds, removes or alters one or more API endpoints, please review and update the relevant API documentation as well:

API Docs updated

If this PR is related to other PRs, contributions, or ongoing work in this or other repositories, please reference them here:

Links to related work items (optional).

- Introduced a new script `install-pmm-client.sh` for streamlined installation of the PMM client. - Updated Ansible tasks to copy the installer script to the appropriate directory. - Enhanced documentation with a new section for one-step installation from the UI. - Added a new Install Client page in the UI for generating installation commands. - Integrated navigation for the new Install Client page within the application. This update simplifies the PMM client installation process and improves user experience through the UI.

codecov · 2026-04-14T13:23:32Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 43.19%. Comparing base (7fccd1e) to head (e71a1e4).
⚠️ Report is 4 commits behind head on v3.

Additional details and impacted files

@@            Coverage Diff             @@
##               v3    #5250      +/-   ##
==========================================
- Coverage   43.22%   43.19%   -0.04%     
==========================================
  Files         413      413              
  Lines       42279    42279              
==========================================
- Hits        18277    18263      -14     
- Misses      22134    22149      +15     
+ Partials     1868     1867       -1

Flag	Coverage Δ
admin	`34.94% <ø> (ø)`
agent	`49.04% <ø> (-0.12%)`	⬇️
managed	`42.33% <ø> (-0.01%)`	⬇️
vmproxy	`72.41% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

- Cleaned up import statements in `accesscontrol_grpc.pb.go` and `actions_grpc.pb.go` by removing unnecessary blank lines. - Updated `accesscontrol.pb.go` and `actions.pb.go` to reorder import statements for consistency. - Added validation checks in `accesscontrol.pb.validate.go` and `advisors.pb.validate.go` to ensure proper handling of optional fields. - Introduced new Swagger JSON files for `accesscontrol` and `actions` APIs to enhance API documentation. - Improved formatting and organization of code across multiple files for better readability and maintainability. These changes enhance the overall structure and documentation of the API, making it easier for developers to understand and use.

- Simplified the implementation of the createNodeInstallToken function by directly returning the response data from the API call. - Removed unnecessary parameters in the API post method for cleaner code. These changes enhance code readability and maintainability.

- Modified `install-pmm-client.sh` to enhance command options for node registration and configuration, including clearer error messages and improved handling of non-interactive installations. - Updated the UI to set `insecureTLS` to true by default and adjusted related tests to reflect this change. - Refactored command building logic in `InstallClientPage.utils.ts` to streamline the installation command generation, ensuring proper handling of flags and environment variables. These changes improve the installation process and user experience for the PMM client.

- Simplified the OS detection logic by removing unnecessary cases for various Linux distributions. - Updated the error message to clearly specify the supported 64-bit Linux distributions: Debian, Ubuntu (DEB) and RHEL, Oracle Linux, Amazon Linux (RPM). These changes enhance the clarity and maintainability of the installation script.

- Updated the default credentials mode to 'env' for improved security during installation. - Enhanced user guidance in the UI regarding the use of environment variables and flags for database credentials. - Added new helper text to clarify the limitations of using curl with the installation script. - Modified the command generation logic to include database environment variables when applicable, improving the handling of optional database fields in both prompt and env modes. - Updated tests to ensure correct behavior when optional database fields are provided. These changes improve the user experience and security of the PMM client installation process.

- Introduced environment variables for PMM agent configuration, allowing customization of the config file path, listen host, listen port, log file, and start timeout. - Implemented functions to ensure the PMM agent is running, handling both systemd and nohup startup methods. - Added checks to create the PMM agent config file if it does not exist, improving the robustness of the installation script. These changes enhance the installation process by ensuring the PMM agent is properly configured and running, especially in environments without systemd. Signed-off-by: theTibi <tkorocz@gmail.com>

- Updated the default lifetime of install tokens to 15 minutes for improved security, reflecting the short-lived nature of tokens used during the initial configuration. - Modified the `InstallClientPage` to include a countdown timer for token expiration, enhancing user awareness of token validity. - Added helper text to clarify the implications of token expiration and the need for regeneration. - Introduced a new utility function `formatExpiresIn` to format the remaining time of the token, improving the display of expiration information. - Updated tests to ensure correct functionality of the new token management features. These changes improve the security and usability of the PMM client installation process. Signed-off-by: theTibi <tkorocz@gmail.com>

- Added a new function `detect_node_hostname` to resolve the local node's hostname without relying on the `hostname` command, improving compatibility with minimal RHEL/UBI/Alpine images. - Updated service name assignments for MySQL, PostgreSQL, MongoDB, and Valkey to use the new hostname detection function, ensuring accurate service naming. These changes enhance the robustness of the PMM client installation script in diverse environments. Signed-off-by: theTibi <tkorocz@gmail.com>

- Refactored the `CreateNodeInstallToken` function to accept a technology parameter instead of a unique suffix, improving clarity and usability. - Implemented validation for technology input, ensuring it is not empty and normalizing casing and whitespace. - Updated tests to cover new validation logic and ensure correct behavior for various technology inputs, including error handling for invalid and empty cases. - Enhanced the `install_token.go` file to maintain consistency with the updated function signature and logic. These changes improve the robustness and reliability of the node installation token management process. Signed-off-by: theTibi <tkorocz@gmail.com>

- Clarified that the service token for PMM Client installation is generated with Grafana Admin role, enhancing security awareness. - Updated documentation to reflect the correct role and expiration details for generated tokens. - Modified the `CreateNodeInstallToken` function to ensure service accounts are created with Admin role, aligning with the updated security model. - Adjusted UI components to communicate the Admin role of generated tokens, reinforcing the importance of treating the token URL as a password. These changes improve the clarity and security of the PMM Client installation process. Signed-off-by: theTibi <tkorocz@gmail.com>

- Updated the `install-pmm-client.sh` script to clarify the behavior of the prompt mode, ensuring it correctly handles database credentials by prompting users when the script is run interactively. - Modified the UI components to reflect the new two-step command for the prompt mode, improving user guidance on how to execute the installation script. - Enhanced documentation to explain the differences between installation modes, particularly emphasizing the security benefits of using prompt mode for sensitive credentials. - Updated tests to validate the new command generation logic for prompt mode, ensuring that no sensitive information is exposed in the command output. These changes improve the security and usability of the PMM client installation process. Signed-off-by: theTibi <tkorocz@gmail.com>

…odes - Adjusted the default credentials mode in the UI from 'env' to 'prompt', aligning with the updated documentation that emphasizes the security benefits of prompting for database credentials. - Enhanced the installation documentation to clarify the differences between the credentials modes, particularly focusing on the two-step command for prompt mode. - Updated UI components to reflect the new default and provide clearer guidance on the available options for credential handling. These changes improve the usability and security of the PMM client installation process. Signed-off-by: theTibi <tkorocz@gmail.com>

mattiasimonato

After reviewing the frontend implementation, I have one small architectural note: the hook is colocated within the page/component, while the PMM codebase usually extracts hooks into separate modules. This is low priority and can be deferred, it does not need to block the dev preview

Copilot

Pull request overview

This PR adds a new “one-step” PMM Client installation flow by shipping an installer script from PMM Server, exposing a new UI page that generates install commands (with multiple credential-handling modes), and documenting the UI-driven workflow.

Changes:

Added a new static installer script (/pmm-static/install-pmm-client.sh) and Ansible packaging to ship it with PMM Server.
Added an “Install PMM Client” UI page + routing/navigation to generate install commands and mint short-lived install tokens via Grafana service accounts.
Added documentation for the new UI-based one-step installation flow.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
ui/apps/pmm/src/router.tsx	Adds a new route for the Install Client page.
ui/apps/pmm/src/pages/install-client/InstallClientPage.utils.ts	Builds server URL + install command strings for different credential modes.
ui/apps/pmm/src/pages/install-client/InstallClientPage.utils.test.ts	Adds unit tests for install command generation and token expiry formatting.
ui/apps/pmm/src/pages/install-client/InstallClientPage.tsx	New UI page to generate commands and mint short-lived tokens.
ui/apps/pmm/src/pages/install-client/index.ts	Barrel export for the new page.
ui/apps/pmm/src/contexts/navigation/navigation.constants.ts	Adds navigation entry under Inventory for Install PMM Client.
ui/apps/pmm/src/api/installToken.ts	New API helper to mint short-lived Grafana service-account tokens.
documentation/mkdocs-base.yml	Adds the new doc page to the MkDocs nav.
documentation/docs/install-pmm/install-pmm-client/one-step-ui-install.md	Documents the UI-driven one-step install flow and security notes.
build/ansible/roles/nginx/tasks/main.yml	Installs the installer script into the static content directory.
build/ansible/roles/nginx/files/install-pmm-client.sh	New installer script that installs pmm-client, configures the node, and adds a service.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

fabio-silva · 2026-05-19T09:42:25Z

@copilot adress my comments and fix them.
Also, we have frequent re-renders (due to setInterval) and lots of inline callbacks. Please refactor those into useCallback.
Fix each one in different commits.

Agent-Logs-Url: https://github.com/percona/pmm/sessions/171cec47-2b58-4382-a820-bbc69140fc34 Co-authored-by: fabio-silva <4190654+fabio-silva@users.noreply.github.com>

Copilot · 2026-05-19T09:55:35Z

@copilot adress my comments and fix them.
Also, we have frequent re-renders (due to setInterval) and lots of inline callbacks. Please refactor those into useCallback.
Fix each one in different com...

Addressed in separate commits as requested: cf24b9e (clipboard availability: disable copy + tooltip), 20008d5 (remove local error handling in favor of global interceptor), and baa6584 (refactor inline handlers to useCallback and keep interval ticking only while token is live to avoid frequent re-renders after expiry). Screenshot: https://github.com/user-attachments/assets/c1b1052d-e22e-426b-9d75-63e0e4e8acc7

fabio-silva · 2026-05-19T10:06:56Z

@copilot just realized something:

addApiErrorInterceptor -> only applies to our own API. We need to apply it to grafanaApi as well, please refactor accordingly;
actually we need to re-add the genError from the catch block (no need to check for Axios errors as those are caught already by the interceptor. Just to do it generically).

Agent-Logs-Url: https://github.com/percona/pmm/sessions/583021bb-df4e-4016-8da7-3ddf0b35aa33 Co-authored-by: fabio-silva <4190654+fabio-silva@users.noreply.github.com>

Copilot · 2026-05-19T10:13:19Z

@copilot just realized something:

addApiErrorInterceptor -> only applies to our own API. We need to apply it to grafanaApi as well, please refactor accordingly;

actually we need to re-add th...

Implemented in 67b39c1: addApiErrorInterceptor now also attaches to grafanaApi, and genError was re-added with a generic catch fallback (Error.message or Failed to create token) so the page still shows inline feedback. Screenshot: https://github.com/user-attachments/assets/bdd16e71-6d18-42d6-8fdb-02b4e7158fac

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

fabio-silva · 2026-05-19T10:32:10Z

@copilot isExpired used before assignment, move it to the top.

Agent-Logs-Url: https://github.com/percona/pmm/sessions/8a4da2e1-973b-4cc4-b28f-2293caa68d81 Co-authored-by: fabio-silva <4190654+fabio-silva@users.noreply.github.com>

Copilot · 2026-05-19T10:37:55Z

@copilot isExpired used before assignment, move it to the top.

Fixed in cfb9b89: isExpired is now computed before the effect that references it, so TypeScript build no longer fails with used-before-assignment. Screenshot: https://github.com/user-attachments/assets/99781d4b-55b0-4a90-a499-02c90c507e31

static directory

- Updated `install-pmm-client.sh` to include detailed descriptions for the `--force` and `--db-service-name` options, and added support for `--db-query-source`. - Improved documentation for the one-step installation process, clarifying the use of environment variables and advanced options. - Enhanced the Install Client UI to support MySQL query source selection and added a learn more section for better user guidance. - Updated utility functions to handle MySQL query sources and suggested service names based on user input. This update aims to streamline the installation process and improve user experience when configuring PMM clients. Signed-off-by: theTibi <tkorocz@gmail.com>

- Replaced the Alert component with a Box component for better styling control. - Updated typography colors for improved readability and consistency. - Enhanced the layout of the "Force re-register node" description for clarity. This change aims to improve the user interface and experience during the PMM client installation process. Signed-off-by: theTibi <tkorocz@gmail.com>

github-actions Bot added the documentation Documentation changes label Apr 14, 2026

ademidoff deployed to one_step_install - pmm-doc-3 PR #5250 April 14, 2026 13:22 — with Render View deployment

theTibi added 5 commits April 14, 2026 23:03

matejkubinec changed the title ~~Add one-step PMM client installer script and UI integration~~ PMM-14993 Add one-step PMM client installer script and UI integration Apr 28, 2026

ademidoff deployed to one_step_install - pmm-doc-2 PR #5250 April 29, 2026 08:00 — with Render View deployment

theTibi added 3 commits April 29, 2026 11:14

ademidoff deployed to one_step_install - pmm-doc-2 PR #5250 April 29, 2026 10:58 — with Render View deployment

ademidoff deployed to one_step_install - pmm-doc-3 PR #5250 April 29, 2026 10:58 — with Render View deployment

ademidoff deployed to one_step_install - pmm-doc-3 PR #5250 April 29, 2026 12:47 — with Render View deployment

ademidoff deployed to one_step_install - pmm-doc-2 PR #5250 April 29, 2026 12:47 — with Render View deployment

ademidoff deployed to one_step_install - pmm-doc-2 PR #5250 May 4, 2026 08:42 — with Render View deployment

ademidoff deployed to one_step_install - pmm-doc-3 PR #5250 May 4, 2026 08:42 — with Render View deployment

ademidoff deployed to one_step_install - pmm-doc-3 PR #5250 May 4, 2026 09:53 — with Render View deployment

ademidoff deployed to one_step_install - pmm-doc-2 PR #5250 May 4, 2026 09:53 — with Render View deployment

feat: add 'Preview' badge on navigation

1cd8fc7

mattiasimonato self-requested a review May 6, 2026 11:56

mattiasimonato approved these changes May 6, 2026

View reviewed changes

Copilot AI reviewed May 19, 2026

View reviewed changes

Comment thread ui/apps/pmm/src/pages/install-client/InstallClientPage.tsx Outdated

Comment thread build/ansible/roles/nginx/files/install-pmm-client.sh Outdated

Comment thread build/ansible/roles/nginx/files/install-pmm-client.sh Outdated

Fix: infinite ticking

f43069c

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot started work on behalf of fabio-silva May 19, 2026 09:42 View session

Copilot AI and others added 3 commits May 19, 2026 09:48

ui: disable copy when clipboard API is unavailable

cf24b9e

Agent-Logs-Url: https://github.com/percona/pmm/sessions/171cec47-2b58-4382-a820-bbc69140fc34 Co-authored-by: fabio-silva <4190654+fabio-silva@users.noreply.github.com>

ui: rely on global interceptor for token generation errors

20008d5

Agent-Logs-Url: https://github.com/percona/pmm/sessions/171cec47-2b58-4382-a820-bbc69140fc34 Co-authored-by: fabio-silva <4190654+fabio-silva@users.noreply.github.com>

ui: memoize install page handlers with useCallback

baa6584

Agent-Logs-Url: https://github.com/percona/pmm/sessions/171cec47-2b58-4382-a820-bbc69140fc34 Co-authored-by: fabio-silva <4190654+fabio-silva@users.noreply.github.com>

Copilot finished work on behalf of fabio-silva May 19, 2026 09:57

Copilot AI requested a review from fabio-silva May 19, 2026 09:57

Copilot started work on behalf of fabio-silva May 19, 2026 10:07 View session

ui: apply error interceptor to grafana api and restore genError

67b39c1

Agent-Logs-Url: https://github.com/percona/pmm/sessions/583021bb-df4e-4016-8da7-3ddf0b35aa33 Co-authored-by: fabio-silva <4190654+fabio-silva@users.noreply.github.com>

Copilot finished work on behalf of fabio-silva May 19, 2026 10:13

fabio-silva and others added 2 commits May 19, 2026 11:21

chore: improve script for presence check

4bda5ca

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

fix: permissions

f894332

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot started work on behalf of fabio-silva May 19, 2026 10:32 View session

ui: compute isExpired before interval effect usage

cfb9b89

Agent-Logs-Url: https://github.com/percona/pmm/sessions/8a4da2e1-973b-4cc4-b28f-2293caa68d81 Co-authored-by: fabio-silva <4190654+fabio-silva@users.noreply.github.com>

Copilot finished work on behalf of fabio-silva May 19, 2026 10:39

Merge branch 'v3' into one_step_install

a375e96

fabio-silva approved these changes May 19, 2026

View reviewed changes

ademidoff and others added 6 commits May 19, 2026 15:04

Merge branch 'v3' into one_step_install

52088df

fix: the removal of the

877b995

static directory

Merge branch 'v3' into one_step_install

db6e8de

Merge branch 'v3' into one_step_install

e71a1e4

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

PMM-14993 Add one-step PMM client installer script and UI integration#5250

PMM-14993 Add one-step PMM client installer script and UI integration#5250
theTibi wants to merge 46 commits into
v3from
one_step_install

theTibi commented Apr 14, 2026 •

edited by mattiasimonato

Loading

Uh oh!

codecov Bot commented Apr 14, 2026 •

edited

Loading

Uh oh!

mattiasimonato left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fabio-silva commented May 19, 2026

Uh oh!

Copilot AI commented May 19, 2026

Uh oh!

fabio-silva commented May 19, 2026

Uh oh!

Copilot AI commented May 19, 2026

Uh oh!

fabio-silva commented May 19, 2026

Uh oh!

Copilot AI commented May 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

Conversation

theTibi commented Apr 14, 2026 • edited by mattiasimonato Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

mattiasimonato left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fabio-silva commented May 19, 2026

Uh oh!

Copilot AI commented May 19, 2026

Uh oh!

fabio-silva commented May 19, 2026

Uh oh!

Copilot AI commented May 19, 2026

Uh oh!

fabio-silva commented May 19, 2026

Uh oh!

Copilot AI commented May 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

theTibi commented Apr 14, 2026 •

edited by mattiasimonato

Loading

codecov Bot commented Apr 14, 2026 •

edited

Loading