Endpoints

The Node Management Agent exposes several endpoints for performing various database operations.

The Node Management Agent exposes several endpoints on port 5554 for performing various node operations.

For a static, publicly accessible copy of the documentation for all NMA endpoints, see NMA API Docs. This can be used as a general reference if you don't have access to a local instance of the NMA and its /api-docs/ endpoint.

Prerequisites

For all endpoints other than /api-docs/ and /v1/health, the Node Management Agent (NMA) authenticates users of its API with mutual TLS. The client and Vertica server must each provide the following so that the other party can verify their identity:

Private key
Certificate
Certificate authority (CA) certificate

Server configuration

If you installed Vertica with the install_vertica script, Vertica should already be configured for mutual TLS for NMA. The install_vertica script automatically creates the necessary keys and certificates in /opt/vertica/config/https_certs. These certificates are also used by the HTTPS service.

Note

The CA certificate, rootca.pem, is a self-signed certificate and is safe to use in production with the NMA. If you want to use custom certificates, see Custom certificates.

If you do not have files in /opt/vertica/config/https_certs, run install_vertica --generate-https-certs-only, specifying the hosts of every Vertica node with the --hosts option. This generates the keys and certificates in the /opt/vertica/config/https_certs directory on each of the specified hosts.

For example, for a Vertica cluster with nodes on hosts 192.0.2.100, 192.0.2.101, 192.0.2.102:

$ /opt/vertica/sbin/install_vertica --dba-user dbadmin \
    --dba-group verticadba \
    --hosts '192.0.2.100, 192.0.2.101, 192.0.2.102' \
    --ssh-identity '/home/dbadmin/.ssh/id_rsa' \
    --generate-https-certs-only

Client configuration

Copy the following files from /opt/vertica/config/https_certs to client machines that send requests to NMA:

dbadmin.key (private key)
dbadmin.pem (certificate)
rootca.pem (CA certificate)

You can then use these files when sending requests to the NMA. For example, to send a GET request to the /v1/health endpoint with curl:

$ curl https://localhost:5554/v1/health -k \
    --key /opt/vertica/config/https_certs/dbadmin.key \
    --cert /opt/vertica/config/https_certs/dbadmin.pem \
    --cacert /opt/vertica/config/https_certs/rootca.pem

If you want to use your browser to send requests to NMA, copy the PKCS #12 file dbadmin.p12 to your client machine and import it into your browser. This file packages the private key, certificate, and CA certificate together as one file. The steps for importing PKCS #12 files vary between browsers, so consult your browser's documentation for instructions.

Endpoints

The following are basic, general-purpose endpoints for interacting with your database, as opposed to the advanced endpoints exclusively documented by /api-docs/.

/v1/health (GET)

Send a GET request to /v1/health to verify the status of the NMA. This endpoint does not require authentication. If the NMA is running, /v1/health responds with {"healthy":"true"}:

$ curl https://localhost:5554/v1/health -k

{"healthy":"true"}

In general, /v1/health cannot return {"healthy":"false"}. In cases where NMA is not functioning properly, /v1/health will either hang or clients will fail to connect entirely:

$ curl https://localhost:5554/v1/health -k

curl: (7) Failed connect to localhost:5554; Connection refused

/v1/vertica/version (GET)

Send a GET request to /v1/vertica/version to retrieve the version of Vertica:

$ curl https://localhost:5554/v1/vertica/version -k \
    --key /opt/vertica/config/https_certs/dbadmin.key \
    --cert /opt/vertica/config/https_certs/dbadmin.pem \
    --cacert /opt/vertica/config/https_certs/rootca.pem

{"vertica_version":"Vertica Analytic Database v23.3.0-20230613"}

/v1/nma/shutdown (PUT)

Send a PUT request to /v1/shutdown to shut down the NMA:

$ curl -X PUT https://localhost:5554/v1/nma/shutdown -k \
    --key /opt/vertica/config/https_certs/dbadmin.key \
    --cert /opt/vertica/config/https_certs/dbadmin.pem \
    --cacert /opt/vertica/config/https_certs/rootca.pem

{"shutdown_error":"Null","shutdown_message":"NMA server stopped","shutdown_scheduled":"NMA server shutdown scheduled"}

/v1/vertica-processes/signal-vertica (POST)

Send a POST request to the /v1/vertica-processes/signal-vertica endpoint to send a KILL or TERM signal to the Vertica process. This endpoint takes the following query parameters:

signal_type: Either kill or term (default), the signal to send to the Vertica process.
catalog_path: The path of the catalog for the instance of Vertica to signal. Specify the catalog path when there is more than one database running on a single host, or if the NMA must distinguish between Vertica processes. For example, if there are old or stale Vertica processes on the target node.

To terminate the Vertica process:

$ curl -X POST https://localhost:5554/v1/vertica-processes/signal-vertica -k \
    --key /opt/vertica/config/https_certs/dbadmin.key \
    --cert /opt/vertica/config/https_certs/dbadmin.pem \
    --cacert /opt/vertica/config/https_certs/rootca.pem

{"status": "Signal has been sent to the Vertica process"}

To kill the Vertica process:

$ curl -X POST https://localhost:5554/v1/vertica-processes/signal-vertica?signal_type=kill -k \
    --key /opt/vertica/config/https_certs/dbadmin.key \
    --cert /opt/vertica/config/https_certs/dbadmin.pem \
    --cacert /opt/vertica/config/https_certs/rootca.pem

{"status": "Signal has been sent to the Vertica process"}

To kill the Vertica process with the catalog path /home/dbadmin/VMart/v_vmart_node0001_catalog/:

$ curl -X POST https://localhost:5554/v1/vertica-processes/signal-vertica?signal_type=kill&catalog_path=/home/dbadmin/VMart/v_vmart_node0001_catalog/ -k \
    --key /opt/vertica/config/https_certs/dbadmin.key \
    --cert /opt/vertica/config/https_certs/dbadmin.pem \
    --cacert /opt/vertica/config/https_certs/rootca.pem

{"status": "Signal has been sent to the Vertica process"}

/api-docs/ (GET)

Send a GET request to the /api-docs/ endpoint to get the Swagger UI documentation for all NMA endpoints. This endpoint does not require authentication and serves the documentation in .json, .yaml, and .html formats.

The /api-docs/ endpoint contains documentation for additional endpoints not listed on this page. These extra endpoints should only be used by advanced users and developers to manage and integrate their Vertica database with applications and scripts.

To retrieve the .json-formatted documentation, send a GET request to /api-docs/nma_swagger.json:

$ curl https://localhost:5554/api-docs/nma_swagger.json -k

To retrieve the .yaml-formatted documentation, send a GET request to /api-docs/nma_swagger.yaml:

$ curl https://localhost:5554/api-docs/nma_swagger.yaml -k

To retrieve the .html-formatted documentation, go to https://my_vertica_node:5554/api-docs/ with your web browser.