Skip to content

Commit

Permalink
Replicate pr 3460 from pmm2 docs (#3467)
Browse files Browse the repository at this point in the history 
* replicate Mongo changes from PMM2 - PR3460

* replicate Mongo changes from PMM2 - PR3460

* Update mongodb.md

* Update documentation/docs/install-pmm/install-pmm-client/connect-database/mongodb.md

Co-authored-by: Alex Demidoff <alexander.demidoff@percona.com>

---------

Co-authored-by: Ivan Groenewold <9805809+igroene@users.noreply.github.com>
Co-authored-by: Alex Demidoff <alexander.demidoff@percona.com>
  • Loading branch information
@catalinaadam @igroene @ademidoff
3 people authored Jan 17, 2025
1 parent 698463e commit 47735be
Show file tree
Hide file tree
Showing 2 changed files with 106 additions and 69 deletions.
135 changes: 77 additions & 58 deletions documentation/docs/install-pmm/install-pmm-client/connect-database/mongodb.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,77 +24,90 @@ Run the example codes below in a `mongo` session to:
!!! caution alert alert-warning ""
Values for username (`user`) and password (`pwd`) are examples. Replace them before using these code snippets.

=== "Create roles with privileges for backups and QAN"
=== "Create a role with monitoring and QAN privileges"
This role grants the essential minimum privileges needed for monitoring and QAN.
```{.javascript data-prompt=">"}
db.getSiblingDB("admin").createRole({
role: "explainRole",
privileges: [{
resource: {
db: "",
collection: ""
},
actions: [
"listIndexes",
"listCollections",
"dbStats",
"dbHash",
"collStats",
"find"
]
}],
roles:[]
"role": "explainRole",
"privileges": [
{
"resource": { "db": "", "collection": "" },
"actions": [ "dbHash", "find", "listIndexes", "listCollections" ]
},
{
"resource": { "db": "", "collection": "system.version" },
"actions": [ "find" ]
}
],
"roles": []
})
```

db.getSiblingDB("admin").createRole({ "role": "pbmAnyAction",
=== "Create a role with backup management privileges"
This role provides the necessary privileges for using PMM's backup management features. It is required only if you plan to use this feature.
```{.javascript data-prompt=">"}
db.getSiblingDB("admin").createRole({
"role": "pbmAnyAction",
"privileges": [
{ "resource": { "anyResource": true },
{
"resource": { "anyResource": true },
"actions": [ "anyAction" ]
}
],
"roles": []
});

=== "Create/update user and assign created roles"
db.getSiblingDB("admin").createUser({
user: "pmm",
pwd: "pmm",
roles: [
{ db: "admin", role: "explainRole" },
{ db: "local", role: "read" },
{ db: "admin", role: "readWrite", collection: "" },
{ db: "admin", role: "backup" },
{ db: "admin", role: "clusterMonitor" },
{ db: "admin", role: "restore" },
{ db: "admin", role: "pbmAnyAction" }
]
})
db.getSiblingDB("admin").updateUser("pmm", {
roles: [
{ db: "admin", role: "explainRole" },
{ db: "local", role: "read" },
{ db: "admin", role: "readWrite", collection: "" },
{ db: "admin", role: "backup" },
{ db: "admin", role: "clusterMonitor" },
{ db: "admin", role: "restore" },
{ db: "admin", role: "pbmAnyAction" }
]
})
});
```

### Permissions for advanced metrics

To fetch advanced metrics like usage statistics for collection and indexes, use the following to provide additional privileges to an existing PMM user:
To fetch advanced metrics like usage statistics for collection and indexes, assign the following additional privileges to an existing PMM user:
```{.javascript data-prompt=">"}
db.getSiblingDB("admin").updateRole(
"explainRole",
{
"privileges": [
{
"resource": { "db": "", "collection": "" },
"actions": [ "collStats", "dbStats", "indexStats" ]
},
{
"resource": { "db": "", "collection": "system.profile" },
"actions": [ "dbStats", "collStats", "indexStats" ]
},
]
}
)
```
### Create/update user and assign created roles

Create or update a user with the minimum required privileges for monitoring by assigning the following roles:
```{.javascript data-prompt=">"}
db.getSiblingDB("admin").updateRole(
"explainRole",
{
privileges: [
{
resource: { db: "", collection: "" },
actions: ["collStats", "dbStats", "indexStats"]
}
db.getSiblingDB("admin").createUser({
"user": "pmm",
"pwd": "pmm",
"roles": [
{ "db": "admin", "role": "explainRole" },
{ "db": "local", "role": "read" },
{ "db": "admin". "role": "clusterMonitor" }
]
}
)
})
```

If you intent to use PMM's backup management features, also grant these additional permissions:
```{.javascript data-prompt=">"}
db.getSiblingDB("admin").createUser({
"user": "pmm",
"pwd": "pmm",
"roles": [
{ "db" : "admin", "role": "explainRole" },
{ "db" : "local", "role": "read" },
{ "db" : "admin", "role" : "readWrite", "collection": "" },
{ "db" : "admin", "role" : "backup" },
{ "db" : "admin", "role" : "clusterMonitor" },
{ "db" : "admin", "role" : "restore" },
{ "db" : "admin", "role" : "pbmAnyAction" }
]
})
```

## Profiling
Expand Down Expand Up @@ -189,16 +202,22 @@ Use `pmm-admin` to add the database server as a service using one of these examp
When successful, PMM Client will print `MongoDB Service added` with the service's ID and name. Use the `--environment` and `-custom-labels` options to set tags for the service to help identify them.

!!! hint alert alert-success "Tips"
- When adding nodes of a sharded cluster, add each node separately using the `--cluster mycluster` option for the [MongoDB Cluster Summary](../../details/dashboards/dashboard-mongodb-cluster-summary.md) dashboard to populate correctly. Also use the `--replication-set` option to specify a replication set. Example: `--replication-set config` for your config servers; `--replication-set rs1` for your servers in the first replica set, `--replication-set rs2` for your servers in the second replica set, and so on.
- When adding nodes to a sharded cluster, ensure to add each node separately using the `--cluster mycluster` option. This allows the [MongoDB Cluster Summary](../../details/dashboards/dashboard-mongodb-cluster-summary.md) dashboard to populate correctly.
- You can also use the `--replication-set` option to specify a replication set, altough they are automatically detected. For instance, you can use `--replication-set config` for your config servers; `--replication-set rs1` for your servers in the first replica set, `--replication-set rs2` for your servers in the second replica set, and so on.
- When running mongos routers in containers, specify the `diagnosticDataCollectionDirectoryPath` to ensure that pmm-agent can properly capture mongos metrics. For example: `mongos --setParameter diagnosticDataCollectionDirectoryPath=/var/log/mongo/mongos.diagnostic.data/`

### Examples

Add basic data collection:

```sh
pmm-admin add mongodb \
--username=pmm_mongodb --password=password \
--query-source=profiler --cluster=mycluster
```

Add complete data collection with a custom service name:

```sh
pmm-admin add mongodb \
--username=pmm_mongodb --password=password \
Expand Down
40 changes: 29 additions & 11 deletions documentation/docs/pmm-upgrade/upgrade_client.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,28 +18,46 @@ Run the commands below to install the latest PMM Client version via package mana

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
```
=== "Debian-based"

```sh
percona-release enable pmm-client
apt update
apt install pmm-client
```
=== "Red Hat-based"

```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
```
=== "Red Hat-based"
```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
```

=== "Debian-based"
```sh
apt-cache madison pmm-client
pmm-client | 3.0.1-6.focal | http://repo.percona.com/pmm-client/apt focal/main amd64 Packages
pmm-client | 3.0.0-6.focal | http://repo.percona.com/pmm-client/apt focal/main amd64 Packages
apt install pmm-client=3.0.1-6.focal
```

### 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:
{.power-number}

1. Download `tar.gz` with `pmm-client`.
1. [Download](https://www.percona.com/downloads) `tar.gz` with `pmm-client`.
2. Extract the tarball.
3. Run `./install_tarball` script with the `-u` flag.

Expand Down

0 comments on commit 47735be

Please sign in to comment.