diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml index 851406bcef..95b4c948f8 100644 --- a/.github/workflows/doc.yml +++ b/.github/workflows/doc.yml @@ -6,6 +6,7 @@ on: paths: - "api/**" - "docs/api/**" + workflow_dispatch: inputs: version: diff --git a/docs/api/access-control.md b/docs/api/access-control/access-control.md similarity index 67% rename from docs/api/access-control.md rename to docs/api/access-control/access-control.md index 61b1da4ad2..91b05dbe42 100644 --- a/docs/api/access-control.md +++ b/docs/api/access-control/access-control.md @@ -1,11 +1,13 @@ --- -slug: 'access-control' +title: Access Control +slug: access-control +category: 64e49e26498dc6002b62ebf4 --- ## Overview Access Control in PMM can be used to restrict access to individual metrics. -Access Control is in tech preview and needs to be enabled manually from the PMM settings before it can be used. +Access Control is in **tech preview** and needs to be enabled manually from PMM settings before it can be used. Once enabled, restricting access to metrics can be performed by: @@ -14,12 +16,12 @@ Once enabled, restricting access to metrics can be performed by: ### Create a Percona role -```bash -curl -X POST "http://localhost/v1/management/Role/Create" \ +```shell +curl -X POST "http://localhost/v1/management/Role/Create" \ -H "Authorization: Basic xxx" \ - -H "Content-Type: application/json" \ + -H "Content-Type: application/json" \ -d '{ - "title": "My custom role role", + "title": "My custom role", "filter": "{environment=\"staging\"}" }' ``` @@ -32,10 +34,10 @@ Full access can be provided by specifying an empty `filter` field. Users can be assigned roles by using the `/v1/management/Role/Assign` API. The endpoint assigns new roles to a user. Other roles, that may have been assigned to the user previously, stay intact. -```bash -curl -X POST "http://localhost/v1/management/Role/Assign" \ +```shell +curl -X POST "http://localhost/v1/management/Role/Assign" \ -H "Authorization: Basic xxx" \ - -H "Content-Type: application/json" \ + -H "Content-Type: application/json" \ -d '{ "user_id": 1, "role_ids": [2, 3, 4] diff --git a/docs/api/adhoc-backup.md b/docs/api/adhoc-backup.md deleted file mode 100644 index fcd94af324..0000000000 --- a/docs/api/adhoc-backup.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -slug: 'adhoc-backup' ---- - -## Ad hoc Backup - -PMM can backup the monitored servers. - -This section describes making ad hoc backups from a service. - -### Creating a Backup - -Here is an example of a Curl API call to create a backup: - -```bash -curl --insecure -X POST -H 'Authorization: Bearer XXXXX' \ - --request POST \ - --url https://127.0.0.1/v1/management/backup/Backups/Start \ - --header 'Accept: application/json' \ - --header 'Content-Type: application/json' \ - --data ' -{ - "service_id": "/service_id/XXXXX", - "location_id": "/location_id/XXXXX", - "name": "Test Backup", - "description": "Test Backup", - "retry_interval": "60s", - "retries": 1 -} -' -``` - -You require an authentication token, which is described [here](ref:authentication). - -Also, you require the [service_id](ref:listservices) and [location_id](ref:listlocations). - -You can choose a `name` and `description` for the backup. You can also configure `retry_interval` and `retries` if required. diff --git a/docs/api/advisor-api/advisors-and-advisor-checks.md b/docs/api/advisor-api/advisors-and-advisor-checks.md new file mode 100644 index 0000000000..7a50116fde --- /dev/null +++ b/docs/api/advisor-api/advisors-and-advisor-checks.md @@ -0,0 +1,7 @@ +--- +title: Percona Advisors and Advisors checks +slug: advisors-and-advisor-checks +category: 6291050b9400a1001ae1877d +order: 2 +hidden: 0 +--- diff --git a/docs/api/advisor-api/changing-advisor-checks.md b/docs/api/advisor-api/changing-advisor-checks.md new file mode 100644 index 0000000000..36265f0c63 --- /dev/null +++ b/docs/api/advisor-api/changing-advisor-checks.md @@ -0,0 +1,7 @@ +--- +title: Changing Advisors and Advisor checks +slug: changing-advisor-checks +category: 6291050b9400a1001ae1877d +order: 3 +hidden: 0 +--- diff --git a/docs/api/advisor-api/failed-checks.md b/docs/api/advisor-api/failed-checks.md new file mode 100644 index 0000000000..b240596293 --- /dev/null +++ b/docs/api/advisor-api/failed-checks.md @@ -0,0 +1,7 @@ +--- +title: List of problems detected by Advisors +slug: failed-checks +category: 6291050b9400a1001ae1877d +order: 1 +hidden: 0 +--- diff --git a/docs/api/advisor-api/overview.md b/docs/api/advisor-api/overview.md new file mode 100644 index 0000000000..f791f36668 --- /dev/null +++ b/docs/api/advisor-api/overview.md @@ -0,0 +1,15 @@ +--- +title: Overview +slug: percona-advisors +category: 6291050b9400a1001ae1877d +order: 0 +--- + + +This section is about API for managing Percona [Advisors](https://docs.percona.com/percona-monitoring-and-management/get-started/advisors.html), and [Advisors Checks](https://docs.percona.com/percona-monitoring-and-management/details/develop-checks/index.html). + +This section has three main subsections. + +- In [List of problems detected by Advisors](reference/failed-checks) you can find API to get information about potential problems with your Infrastructure detected by Advisors. +- [Percona Advisors and Advisors checks](reference/advisors-and-advisor-checks) lists all Advisors and Advisor Checks available in your PMM. +- [Changing Advisors and Advisor checks](reference/changing-advisor-checks) will help you automate Advisor checks modification if needed. diff --git a/docs/api/backups/list-locations.md b/docs/api/backups/list-locations.md new file mode 100644 index 0000000000..bb64df8151 --- /dev/null +++ b/docs/api/backups/list-locations.md @@ -0,0 +1,20 @@ +--- +title: List Locations +slug: listlocations +excerpt: ListLocations returns a list of all backup locations. +category: 626badcabbc59c02acc1a540 +--- + +The following API call will list all the available backup locations: + +```shell +curl --insecure -X POST \ + -H 'Authorization: Basic YWRtaW46YWRtaW4=' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --url https://127.0.0.1/v1/management/backup/Locations/List \ +``` + +Please note that locations are good for storing any type of backup disregarding the technology or the database vendor. However, for a better organization of your file system storage, you'll probably want to create different locations based on a certain criteria. For example, it can be a department, a region, etc. + +You will need the [authetication token](ref:authentication). diff --git a/docs/api/backups/restore-backup.md b/docs/api/backups/restore-backup.md new file mode 100644 index 0000000000..50f212d5e4 --- /dev/null +++ b/docs/api/backups/restore-backup.md @@ -0,0 +1,44 @@ +--- +title: Restore from a backup +slug: restorebackup +excerpt: This endpoint allows to restore a database from a previously made backup. +category: 626badcabbc59c02acc1a540 +order: 1 +--- + +PMM can backup the monitored services. + +This section describes making ad-hoc backups from a service. + +### Restoring From a Backup + +Here is an example of an API call to restore from a backup: + +```shell +curl --insecure -X POST -H 'Authorization: Bearer XXXXX' \ + --request POST \ + --url https://127.0.0.1/v1/management/backup/Backups/Restore \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' \ + --data ' +{ + "service_id": "/service_id/XXXXX", + "artifact_id": "/location_id/XXXXX", + "pitr_timestamp": "2023-09-09T10:02:25.998" +} +' +``` + +You require an authentication token, which is described [here](ref:authentication). + +Also, you require the [service_id](ref:listservices) and [location_id](ref:listlocations). + +You can defined a `name` and a `description` for each backup. You can also configure `retry_interval` and `retries` if required. + +### Error messages + +The API call could return an error message in the details, containing a specific ErrorCode indicating the failure reason: +- ERROR_CODE_XTRABACKUP_NOT_INSTALLED - xtrabackup is not installed on the service +- ERROR_CODE_INVALID_XTRABACKUP - different versions of xtrabackup and xbcloud +- ERROR_CODE_INCOMPATIBLE_XTRABACKUP - xtrabackup is not compatible with MySQL for making a backup +- ERROR_CODE_INCOMPATIBLE_TARGET_MYSQL - target MySQL version is not compatible with the artifact to perform a restore of the backup diff --git a/docs/api/backups/start-backup.md b/docs/api/backups/start-backup.md new file mode 100644 index 0000000000..918508c0c4 --- /dev/null +++ b/docs/api/backups/start-backup.md @@ -0,0 +1,46 @@ +--- +title: Make a backup +slug: startbackup +excerpt: This endpoint allows to make an unscheduled, or ad-hoc, backup of a given service. +category: 626badcabbc59c02acc1a540 +order: 0 +--- + +PMM can backup the monitored services. + +This section describes how to make an ad-hoc backup of a service. + +### Creating a Backup + +Here is an example of an API call to create a backup: + +```shell +curl --insecure -X POST -H 'Authorization: Bearer XXXXX' \ + --request POST \ + --url https://127.0.0.1/v1/management/backup/Backups/Start \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' \ + --data ' +{ + "service_id": "/service_id/XXXXX", + "location_id": "/location_id/XXXXX", + "name": "Test Backup", + "description": "Test Backup", + "retry_interval": "60s", + "retries": 1 +} +' +``` + +You require an authentication token, which is described [here](ref:authentication). + +Also, you require the [service_id](ref:listservices) and [location_id](ref:listlocations). + +You can defined a `name` and a `description` for each backup. You can also configure `retry_interval` and `retries` if required. + +### Error messages + +The API call could return an error message in the details, containing a specific ErrorCode indicating the failure reason: +- ERROR_CODE_XTRABACKUP_NOT_INSTALLED - xtrabackup is not installed on the service +- ERROR_CODE_INVALID_XTRABACKUP - different versions of xtrabackup and xbcloud +- ERROR_CODE_INCOMPATIBLE_XTRABACKUP - xtrabackup is not compatible with MySQL to make a backup diff --git a/docs/api/createpsmdbcluster.md b/docs/api/dbaas/create-psmdb-cluster.md similarity index 91% rename from docs/api/createpsmdbcluster.md rename to docs/api/dbaas/create-psmdb-cluster.md index 6a096a3d76..e2acb6a4ae 100644 --- a/docs/api/createpsmdbcluster.md +++ b/docs/api/dbaas/create-psmdb-cluster.md @@ -1,6 +1,12 @@ -### Create a PSMDB Cluster +--- +title: Create a PSMDB Cluster +slug: create-psmdb-cluster +category: 651c00ce1679590036133c8c +order: 2 +hidden: 0 +--- -The PSMDB Create endpoint receives this structure: +The PSMDB Create endpoint receives this structure of: ```json { @@ -21,7 +27,7 @@ The PSMDB Create endpoint receives this structure: } ``` -#### Fields description +## Fields description | Field | Description | Notes | | ----------------------------------------- | ------------------------------------- | ------------------------------------------------------------ | @@ -37,7 +43,7 @@ The PSMDB Create endpoint receives this structure: Since the endpoint can set defaults, you can create a PSMDB cluster with a minimum request like this: -```bash +```shell curl -X POST "http://localhost/v1/management/DBaaS/PSMDBCluster/Create" \ -H "accept: application/json" \ -H "authorization: Basic YWRtaW46YWRtaW4=" \ diff --git a/docs/api/createpxccluster.md b/docs/api/dbaas/create-pxc-cluster.md similarity index 91% rename from docs/api/createpxccluster.md rename to docs/api/dbaas/create-pxc-cluster.md index 9994b47c1d..e45779d647 100644 --- a/docs/api/createpxccluster.md +++ b/docs/api/dbaas/create-pxc-cluster.md @@ -1,8 +1,14 @@ -### Create PXC Cluster +--- +title: Create a PXC Cluster +slug: create-pxc-cluster +category: 651c00ce1679590036133c8c +order: 1 +hidden: 0 +--- -Once you register the Kubernetes cluster, you can use its name to create database clusters. Here is an example for the PXC cluster. Percona recommends the following the values for the parameters: +Once you register a Kubernetes cluster, you can use its name to create database clusters. Here is an example for the PXC cluster. Percona recommends the following the values for the parameters: -```bash +```shell curl -X POST "http://localhost/v1/management/DBaaS/PXCCluster/Create" \ -H "accept: application/json" \ -H "authorization: Basic YWRtaW46YWRtaW4=" \ @@ -10,7 +16,7 @@ curl -X POST "http://localhost/v1/management/DBaaS/PXCCluster/Create" \ -d "{ \"kubernetes_cluster_name\": \"my_cluster\", \"name\": \"my-cluster-1\", \"expose\": true, \"params\": { \"cluster_size\": 3, \"pxc\": { \"compute_resources\": { \"cpu_m\": 1000, \"memory_bytes\": 2000000000 }, \"disk_size\": 25000000000, \"image\": \"percona/percona-xtradb-cluster:8.0.25-15.1\" }, \"haproxy\": { \"compute_resources\": { \"cpu_m\": 1000, \"memory_bytes\": 2000000000 } } } }" ``` -### Request parameters +## Request parameters ``` { @@ -46,7 +52,7 @@ curl -X POST "http://localhost/v1/management/DBaaS/PXCCluster/Create" \ } ``` -#### Fields description +### Fields description |Parameter |Description |Notes | |---------------------------------------|------------------------------------------------|---------------------------------------------------------------------| @@ -69,13 +75,13 @@ curl -X POST "http://localhost/v1/management/DBaaS/PXCCluster/Create" \ **Note:** Either ProxySQL or HAProxy should be specified in the request. -#### Minimum request example +### Minimum request example Since the API has the defaults mentioned above, the HTTP request can have the Kubernetes cluster name as the only parameter. Example: -```bash +```shell curl -X POST "http://localhost/v1/management/DBaaS/PXCCluster/Create" \ -H "accept: application/json" \ -H "authorization: Basic YWRtaW46YWRtaW4=" \ diff --git a/docs/api/dbaas.md b/docs/api/dbaas/dbaas.md similarity index 99% rename from docs/api/dbaas.md rename to docs/api/dbaas/dbaas.md index 08eda78960..44c3e63d93 100644 --- a/docs/api/dbaas.md +++ b/docs/api/dbaas/dbaas.md @@ -1,5 +1,9 @@ --- -slug: 'dbaas' +title: Private DBaaS +slug: dbaas-overview +category: 651c00ce1679590036133c8c +order: 0 +hidden: 0 --- ## Private DBaaS @@ -45,13 +49,13 @@ It is highly recommended to **use DNS name** instead of IP address but in exampl #### Get Docker container IP and set it as public address First of all we should get IP address of PMM (or DNS name should be used and that is recommended). If you are running in local minikube environment you can use following command to get IP address: -```bash +```shell IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' pmm-server) ``` If your kubernetes cluster is located outside of your local system you can get public address by calling `ifconfig`. Then to enable DBaaS send request to `Settings/Change` endpoint like below where `IP` is public IP address or DNS name of PMM Server instance. -```bash +```shell curl -X POST "http://localhost/v1/Settings/Change" \ -H "accept: application/json" \ -H "authorization: Basic YWRtaW46YWRtaW4=" \ @@ -64,7 +68,7 @@ API endpoint used in this step: [Change settings](ref:changesettings). ### Registering new Kubernetes cluster Once kubernetes cluster is created it should be registered in PMM where `my_cluster` is a name of kubernetes cluster which will be used later. `sed` command is used to remove newlines, otherwise this script doesn’t work. -```bash +```shell KUBECONFIG=$(kubectl config view --flatten --minify | sed -e ':a' -e 'N' -e '$!ba' -e 's/\n/\\n/g') curl -X POST "http://localhost/v1/management/DBaaS/Kubernetes/Register" \ @@ -81,7 +85,7 @@ API endpoint used in this step: [RegisterKubernetesCluster](ref:registerkubernet To create a PXC cluster, we need to provide the image name for the database instance. Percona maintains a list of available versions for each component. For example, to retrieve the list of the available PXC components we can call the `Components/GetPXC` API method: -```bash +```shell curl -X POST "http://localhost/v1/management/DBaaS/Components/GetPXC" \ -H "accept: application/json" \ -H "authorization: Basic YWRtaW46YWRtaW4=" \ @@ -244,7 +248,7 @@ API endpoint used in this step: [ChangePXCComponents](ref:changepxccomponents). Once we registered kubernetes cluster we can use it’s name to create DB Clusters. Here is an example for PXC Cluster, the values for parameters are recomended by Percona: -```bash +```shell curl -X POST "http://localhost/v1/management/DBaaS/PXCCluster/Create" \ -H "accept: application/json" \ -H "authorization: Basic YWRtaW46YWRtaW4=" \ @@ -317,7 +321,7 @@ Since the API has the defaults mentioned above, the HTTP request can have the Ku Example: -```bash +```shell curl -X POST "http://localhost/v1/management/DBaaS/PXCCluster/Create" \ -H "accept: application/json" \ -H "authorization: Basic YWRtaW46YWRtaW4=" \ @@ -330,7 +334,7 @@ API endpoint used in this step: [CreatePXCCluster](ref:createpxccluster). ### List Kubernetes clusters Once you created PXC cluster you can check the status of the cluster by calling the `List` endpoint. -```bash +```shell curl -X POST "http://localhost/v1/management/DBaaS/DBClusters/List" \ -H "accept: application/json" \ -H "authorization: Basic YWRtaW46YWRtaW4=" \ @@ -378,7 +382,7 @@ API endpoint used in this step: [ListDBClusters](ref:listdbclusters) Once PXC Cluster is ready we can request credentials to connect to DB. -```bash +```shell curl -X POST "http://localhost/v1/management/DBaaS/PXCClusters/GetCredentials" \ -H "accept: application/json" \ -H "authorization: Basic YWRtaW46YWRtaW4=" \ @@ -403,7 +407,7 @@ API endpoint used in this step: [GetPXCClusterCredentials](ref:getpxcclustercred The PSMDB `Create` endpoint can also set defaults, so creating a PSMDB cluster can be made with a request like this: -```bash +```shell curl -X POST "http://localhost/v1/management/DBaaS/PSMDBCluster/Create" \ -H "accept: application/json" \ -H "authorization: Basic YWRtaW46YWRtaW4=" \ @@ -446,7 +450,7 @@ curl -X POST "http://localhost/v1/management/DBaaS/PSMDBCluster/Create" \ ### Delete DB Cluster If you don’t need the database cluster you can delete it using the request below. -```bash +```shell curl -X POST "http://localhost/v1/management/DBaaS/DBClusters/Delete" \ -H "accept: application/json" \ -H "authorization: Basic YWRtaW46YWRtaW4=" \ @@ -462,7 +466,7 @@ After we played with DBaaS we can unregister kubernetes cluster. Unregister a kubernetes cluster doesn’t delete anything, it just removes the cluster from the list of registered clusters and all database clusters will remain active and will send metrics to PMM. -```bash +```shell curl -X POST "http://localhost/v1/management/DBaaS/Kubernetes/Unregister" \ -H "accept: application/json" \ -H "authorization: Basic YWRtaW46YWRtaW4=" \ diff --git a/docs/api/addnode.md b/docs/api/inventory/add-node.md similarity index 94% rename from docs/api/addnode.md rename to docs/api/inventory/add-node.md index 2b177c72bf..79b725c3ac 100644 --- a/docs/api/addnode.md +++ b/docs/api/inventory/add-node.md @@ -1,5 +1,7 @@ --- -slug: 'addnode' +title: Add a Node +slug: addnode +category: 626de009b977e3003179f7dd --- ## Add a Node @@ -12,9 +14,9 @@ Let's see how to add a Node of type `GENERIC_NODE` using the old and new API cal Old API call: -````bash: +````shell: -```bash +```shell curl --insecure -X POST \ -H 'Authorization: Basic YWRtaW46YWRtaW4=' \ -H 'Accept: application/json' \ @@ -36,7 +38,7 @@ curl --insecure -X POST \ New API call: -```bash +```shell curl --insecure -X POST \ -H 'Authorization: Basic YWRtaW46YWRtaW4=' \ -H 'Accept: application/json' \ diff --git a/docs/api/listnodes.md b/docs/api/inventory/list-nodes.md similarity index 87% rename from docs/api/listnodes.md rename to docs/api/inventory/list-nodes.md index ba5740e3e5..2ba49557dd 100644 --- a/docs/api/listnodes.md +++ b/docs/api/inventory/list-nodes.md @@ -1,5 +1,7 @@ --- -slug: 'listnodes' +title: List Nodes +slug: listnodes +category: 626de009b977e3003179f7dd --- ## List Nodes @@ -8,7 +10,7 @@ This section describes how to list PMM Inventory Nodes. Example: -```bash +```shell curl --insecure -X POST \ -H 'Authorization: Basic YWRtaW46YWRtaW4=' \ -H 'Accept: application/json' \ diff --git a/docs/api/listservices.md b/docs/api/inventory/list-services.md similarity index 91% rename from docs/api/listservices.md rename to docs/api/inventory/list-services.md index 51d79dcb19..b8528723b8 100644 --- a/docs/api/listservices.md +++ b/docs/api/inventory/list-services.md @@ -1,12 +1,14 @@ --- -slug: 'listservices' +title: List Services +slug: listservices +category: 626de009b977e3003179f7dd --- ## List Services The following API call lists the available services on a Node: -```bash +```shell curl --insecure -X POST \ -H 'Authorization: Basic YWRtaW46YWRtaW4=' \ -H 'Accept: application/json' \ diff --git a/docs/api/listlocations.md b/docs/api/listlocations.md deleted file mode 100644 index 63d0187575..0000000000 --- a/docs/api/listlocations.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -slug: 'listlocations' ---- - -## List Locations - -The following API call will list all the available Locations: - -```bash -curl --insecure -X POST \ - -H 'Authorization: Basic YWRtaW46YWRtaW4=' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - --url https://127.0.0.1/v1/management/backup/Locations/List \ -``` - -You will need the [authetication token](ref:authentication). diff --git a/docs/api/bulk-add-users.md b/docs/api/pmm-server-config/account-management/bulk-add-users.md similarity index 87% rename from docs/api/bulk-add-users.md rename to docs/api/pmm-server-config/account-management/bulk-add-users.md index a754d4365a..43aede9d08 100644 --- a/docs/api/bulk-add-users.md +++ b/docs/api/pmm-server-config/account-management/bulk-add-users.md @@ -1,8 +1,12 @@ --- -slug: "bulk-add-users" +title: Create user accounts +slug: bulk-add-users +category: 626bd6a45c6ea70129427eff +parentDoc: 626be9a93ab1240284d0d27d +order: 1 --- -## Bulk user creation +## Create multiple user accounts PMM Server will start up with a single user account, the administrator account. This account should not be for general use, because it allows complete control of @@ -57,14 +61,11 @@ This can be acheived with Ansible with a task such as: - 412 no_log: true ``` -The accepted status codes here will allow the task to pass when the user already -exists (412) as well as when the account is created (201). +The accepted status codes here will allow the task to pass when the user already exists (412) as well as when the account is created (201). -### Creating API tokens +### Create API tokens -Instead of login credentials, you can create API tokens instead, which are -associated with an organisation and can be used to create dashboards, or other -components. +Instead of login credentials, you can create API tokens, which are associated with an organisation and can be used to create dashboards, or other components. Here is an example that creates an admin API token for the `grafana-admin` user that was just created: @@ -92,7 +93,7 @@ This can be achieved in Ansible with a task such as: no_log: true ``` -### Combining this all together to create batch accounts +### Combining this all together to create multiple accounts For simplicity, we will only be using Ansible for this example. ```yaml diff --git a/docs/api/change-admin-password.md b/docs/api/pmm-server-config/account-management/change-admin-password.md similarity index 61% rename from docs/api/change-admin-password.md rename to docs/api/pmm-server-config/account-management/change-admin-password.md index 724169f860..de935a1838 100644 --- a/docs/api/change-admin-password.md +++ b/docs/api/pmm-server-config/account-management/change-admin-password.md @@ -1,24 +1,20 @@ --- -slug: "change-admin-password" +title: Change the administrator's password +slug: change-admin-password +category: 626bd6a45c6ea70129427eff +parentDoc: 626be9a93ab1240284d0d27d +order: 0 --- ## Changing the admin password -Your new PMM Server will start up with a default set of credentials for the administrator account. -When you first login via the UI, you will be prompted to change this to a new password in order to -secure the account. +Your new PMM Server will start up with a default set of credentials for the administrator account. When you first login via the UI, you will be prompted to change this to a new password in order to secure the account. -When automating the deployment and/or management of your PMM Server, it is prefereable to use the -available APIs instead of relying upon human interaction. +When automating the deployment and/or management of your PMM Server, it is prefereable to use the available APIs instead of relying upon human interaction. -The [authentication](#authentication) overview explains the different ways that you can -programmatically access the API, using either [basic](#use-an-api-key-in-basic-auth), or -[token-based](#authenticate) authentication. **Note:** for basic authentication, you can use the -same approach for standard credentials if you haven't yet created a token. +The [authentication](authentication) overview explains the different ways that you can programmatically access the API, using either [basic](authentication#basic-http-authentication), or [token-based](authentication#bearer-authentication) authentication. **Note:** for basic authentication, you can use the same approach for standard credentials if you haven't yet created a token. -**Note** Examples using cURL will be shown with the `--netrc` argument, which allows -credentials to be hidden from view in the processlist and shell history. Should you wish to -use credentials in the command instead then substitute `--netrc` for `--basic --user ':'` +**Note** Examples using cURL will be shown with the `--netrc` argument, which allows credentials to be hidden from view in the processlist and shell history. Should you wish to use credentials in the command instead then substitute `--netrc` for `--basic --user ':'` Here is an example `.netrc`: ``` @@ -29,15 +25,11 @@ password admin ### Check that the server is ready for you -When the server starts up, there are a number of tasks that execute before the server and API -are reliably available to the user. You can check whether the server is ready using the dedicated -endpoint, [`/v1/readyz`](https://percona-pmm.readme.io/reference/readiness): +When the server starts up, there are a number of tasks that execute before the server and API are reliably available to the user. You can check whether the server is ready using the dedicated endpoint, [`/v1/readyz`](https://percona-pmm.readme.io/reference/readiness): -```sh +```shell $ curl --silent https://127.0.0.1/v1/readyz -{ - -} +{} ``` If the server is not yet ready then you will see a response such as: @@ -69,11 +61,7 @@ You can check this using Ansible with a task such as: ### Changing the password following initial installation -**Caution:** Once you have changed the password, you need to use the new password -from then on. Should you be doing this for an account that is used elsewhere then -you may find that the account gets blocked due to too many failed login attemps. -You should disconnect any clients using the same account before proceeding to -avoid such issues. +**Caution:** Once you have changed the password, you need to use the new password from then on. Should you be doing this for an account that is used elsewhere then you may find that the account gets blocked due to too many failed login attemps. You should disconnect any clients using the same account before proceeding to avoid such issues. The [payload](https://grafana.com/docs/grafana/latest/http_api/user/#change-password) for changing a user's password is: ```json @@ -85,7 +73,7 @@ The [payload](https://grafana.com/docs/grafana/latest/http_api/user/#change-pass ``` Here is an example that changes the password from `admin` to `notAdminAnymore`: -```sh +```shell $ cat < /tmp/data.json { "oldPassword": "admin", @@ -117,4 +105,3 @@ This can be achieved in Ansible with a task such as: confirmNew: 'notAdminAnymore' no_log: true ``` - diff --git a/docs/api/pmm-server-configuration.md b/docs/api/pmm-server-config/overview.md similarity index 57% rename from docs/api/pmm-server-configuration.md rename to docs/api/pmm-server-config/overview.md index 84e619f563..69e4a9b27c 100644 --- a/docs/api/pmm-server-configuration.md +++ b/docs/api/pmm-server-config/overview.md @@ -1,5 +1,8 @@ --- -slug: 'pmm-server-configuration' +title: Overview +slug: pmm-server-configuration +category: 626bd6a45c6ea70129427eff +order: 0 --- This section will provide you with information on how to perform configuration and maintenance of a PMM Server. diff --git a/docs/api/pmm-server-config/pmm-server-settings.md b/docs/api/pmm-server-config/pmm-server-settings.md new file mode 100644 index 0000000000..e9923b15ca --- /dev/null +++ b/docs/api/pmm-server-config/pmm-server-settings.md @@ -0,0 +1,8 @@ +--- +title: PMM Server Settings +slug: pmm-server-settings +category: 626bd6a45c6ea70129427eff +order: 2 +--- + +This section will explain how to configure your PMM Server to get the most out of its functionality. diff --git a/docs/api/pmm-server-config/pmm-server-troubleshooting.md b/docs/api/pmm-server-config/pmm-server-troubleshooting.md new file mode 100644 index 0000000000..58e23de2d6 --- /dev/null +++ b/docs/api/pmm-server-config/pmm-server-troubleshooting.md @@ -0,0 +1,7 @@ +--- +title: Troubleshooting +slug: pmm-server-troubleshooting +category: 626bd6a45c6ea70129427eff +order: 4 +hidden: 0 +--- diff --git a/docs/api/pmm-server-upgrade.md b/docs/api/pmm-server-config/pmm-server-upgrade.md similarity index 78% rename from docs/api/pmm-server-upgrade.md rename to docs/api/pmm-server-config/pmm-server-upgrade.md index 3fcf3cac0b..ae5116a0d6 100644 --- a/docs/api/pmm-server-upgrade.md +++ b/docs/api/pmm-server-config/pmm-server-upgrade.md @@ -1,5 +1,8 @@ --- -slug: 'pmm-server-upgrade' +title: Upgrade your PMM Server +slug: pmm-server-upgrade +category: 626bd6a45c6ea70129427eff +order: 3 --- To get the most of PMM, you need to keep your PMM Server up-to-date. diff --git a/docs/api/logs.md b/docs/api/pmm-server-config/troubleshooting/logs.md similarity index 82% rename from docs/api/logs.md rename to docs/api/pmm-server-config/troubleshooting/logs.md index a681b54071..86909f0c87 100644 --- a/docs/api/logs.md +++ b/docs/api/pmm-server-config/troubleshooting/logs.md @@ -1,9 +1,12 @@ --- +title: Logs slug: "logs" +category: 626badcabbc59c02acc1a540 --- + Sometimes users need to troubleshoot an issue. PMM Server offers an ability to download the logs as well as configuration of its components. -You can download the logs either by calling this endpoint or by visiting a dedicated URL (ex: https://pmmdemo.percona.com/logs.zip) or via the **Settings UI** as explained in the [Troubleshooting](https://www.percona.com/doc/percona-monitoring-and-management/2.x/how-to/troubleshoot.html#client-server-connections) section of our docs. +You can download the logs either by calling this endpoint or by visiting a dedicated URL (ex: https://pmmdemo.percona.com/logs.zip) or via the **Settings UI** as explained in the [Troubleshooting](https://docs.percona.com/percona-monitoring-and-management/how-to/troubleshoot.html#client-server-connections) section of our docs. The structure of the logs is as follows: [block:code] @@ -21,6 +24,6 @@ The structure of the logs is as follows: { "type": "info", "title": "PMM Server Version", - "body": "PMM Server also dumps its version info to a special file `installed.json`. \n\n```bash\n% cat installed.json | jq\n{\n \"version\": \"2.26.0\",\n \"full_version\": \"2.26.0-17.2202021129.6914083.el7\",\n \"build_time\": \"2022-02-02T11:30:45Z\",\n \"repo\": \"local\"\n}\n```" + "body": "PMM Server also dumps its version info to a special file `installed.json`. \n\n```shell\n% cat installed.json | jq\n{\n \"version\": \"2.26.0\",\n \"full_version\": \"2.26.0-17.2202021129.6914083.el7\",\n \"build_time\": \"2022-02-02T11:30:45Z\",\n \"repo\": \"local\"\n}\n```" } [/block] diff --git a/docs/api/pmm-server-config/user-account-management.md b/docs/api/pmm-server-config/user-account-management.md new file mode 100644 index 0000000000..b5fac01365 --- /dev/null +++ b/docs/api/pmm-server-config/user-account-management.md @@ -0,0 +1,11 @@ +--- +title: User account management +slug: pmm-server-config-security +category: 626bd6a45c6ea70129427eff +order: 1 +--- + +The pages below explain more in detail how to perform user account management. + +- [Change admin password](ref:change-admin-password) +- [Bulk user account creation](ref:bulk-add-users) diff --git a/docs/api/authentication.md b/docs/api/welcome/authentication.md similarity index 88% rename from docs/api/authentication.md rename to docs/api/welcome/authentication.md index 2379589217..6693f8765d 100644 --- a/docs/api/authentication.md +++ b/docs/api/welcome/authentication.md @@ -1,5 +1,8 @@ --- -slug: 'authentication' +title: Authentication +slug: authentication +category: 651bd218baa868000c212203 +order: 1 --- ## Authentication @@ -15,35 +18,35 @@ In this section we will talk about two main authentication mechanisms: Basic authentication is a very simple way to authenticate a user. An API request must contain a header field in the form of `Authorization: Basic `, where `` is the Base64 encoding of ID (most often username or login) and password joined by a single colon `:`. -```bash +```shell echo -n admin:admin | base64 ``` Let's assume the username is `admin` and the password is also `admin`. Then the API call to get the PMM Server version info would be as follows: -```bash +```shell curl -X GET -H 'Authorization: Basic YWRtaW46YWRtaW4=' \ -H 'Content-Type: application/json' https://127.0.0.1/v1/version ``` If you use `curl` to make API calls, a simple equivalent to the command above is: -```bash +```shell curl -X GET -u admin:admin -H 'Content-Type: application/json' https://127.0.0.1/v1/version ``` ### Bearer Authentication -Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The bearer token is a cryptic API key, which can be generated by the server admin from the Settings UI or via a respective API call (read more about how to generate an API key). The client must send the API key in the `Authorization` header when making requests to protected resources: +Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The bearer token is a cryptic API key, which can be generated by the server admin from the Settings UI or via a respective API call (read more about how to generate an API key). The client must send the API key in the `Authorization` header when making requests to protected resources: -```bash +```shell curl -X GET -H 'Authorization: Bearer eyJrIjoiUXRkeDNMS1g1bFVyY0tUj1o0SmhBc3g4QUdTRVAwekoiLCJuIjoicG1tLXRlc3QiLCJpZCI6MX0=' \ -H 'Content-Type: application/json' https://127.0.0.1/v1/version ``` You can use the API key in basic authentication as well: -```bash +```shell curl -X GET -H 'Content-Type: application/json' \ https://api_key:eyJrIjoiUXRkeDNMS1g1bFVyY0tUj1o0SmhBc3g4QUdTRVAwekoiLCJuIjoicG1tLXRlc3QiLCJpZCI6MX0=@127.0.0.1/v1/version ``` @@ -58,7 +61,7 @@ It is possible to hide from the shell history: bash -```bash +```shell set +o history ``` @@ -80,13 +83,13 @@ password admin This can then be used as follows: -```bash +```shell curl --netrc -X GET -H 'Content-Type: application/json' https://127.0.0.1/v1/version ``` Should you wish to use a different file then the `--netrc-file` option needs to be used. If we have the credentials stored in `~/.netrc-pmm` then the command would become: -```bash +```shell curl --netrc --netrc-file ~/.netrc-pmm -X GET -H 'Content-Type: application/json' https://127.0.0.1/v1/version ``` diff --git a/docs/api/introduction.md b/docs/api/welcome/introduction.md similarity index 55% rename from docs/api/introduction.md rename to docs/api/welcome/introduction.md index 001f708d41..454c89171c 100644 --- a/docs/api/introduction.md +++ b/docs/api/welcome/introduction.md @@ -1,17 +1,20 @@ --- -slug: 'introduction' +title: Introduction +slug: introduction +category: 651bd218baa868000c212203 +order: 0 --- Percona Monitoring and Management (PMM) is an industry leading tool for helping Devs, DevOps, and DBA's make sense of and take action on their database environments. While you can accomplish many tasks using either the PMM user interface or CLI, leveraging the API allows you to integrate it more easily into your broader technology infrastructure. -This guide is designed to enable both those starting out and those who have already succeeded with API integrations but are looking to do more. You will find both our reference library of API endpoints as well as our guides on carrying out some more routine tasks. +This guide is designed to enable both those starting off and those who have already succeeded with API integrations but are looking to do more. You will find here our reference of API endpoints as well as our guides on carrying out some more routine tasks. -To give you an idea of what you can do with the PMM api you can: +To give you an idea of what you can do with PMM api, you can: -- add database instances to monitor, be it MYSQL, PostgreSQL, or MongoDB +- add database instances to monitoring, be it MySQL, PostgreSQL, or MongoDB - check the availability of PMM updates - update PMM and check if PMM is successfully updated or not -- change the configuration of the PMM server -- download PMM Server logs to troubleshoot an issue +- change the configuration of PMM server +- analyze query performance issues with Query Analytics - kick off a backup prior to a significant change -- spin up a new database to run tests after a code commit +- download PMM Server logs to troubleshoot an issue diff --git a/docs/api/monitoring.md b/docs/api/welcome/monitoring.md similarity index 57% rename from docs/api/monitoring.md rename to docs/api/welcome/monitoring.md index 7c89ebb1ab..55a9570353 100644 --- a/docs/api/monitoring.md +++ b/docs/api/welcome/monitoring.md @@ -1,10 +1,13 @@ --- -slug: 'monitoring' +title: Monitoring +slug: monitoring +category: 651bd218baa868000c212203 +order: 2 --- In order to get a Database (or Service in PMM terminology) monitored you need: -- [Install PMM](https://www.percona.com/doc/percona-monitoring-and-management/2.x/setting-up/server/index.html) +- [Install PMM](https://docs.percona.com/percona-monitoring-and-management/setting-up/server/index.html) - [PMM Server Configuration](ref:pmm-server-configuration) - [Register Node](ref:registernode) - [Add Service to Monitoring](ref:add-service-to-monitoring) diff --git a/docs/dbaas/olm.md b/docs/dbaas/olm.md index b13a27f121..9768ac7e8d 100644 --- a/docs/dbaas/olm.md +++ b/docs/dbaas/olm.md @@ -1,5 +1,5 @@ --- -slug: 'dbaas' +slug: dbaas --- ## How OLM (Operator Lifecycle Manager) works.