[voltdb] Switch to native VoltDB Python client

LICENSE-3rdparty.csv

@@ -80,4 +80,5 @@ tuf,PyPI,Apache-2.0,Copyright (c) 2010 New York University
 tuf,PyPI,MIT,Copyright (c) 2010 New York University
 urllib3,PyPI,MIT,Copyright (c) 2008-2020 Andrey Petrov and contributors.
 vertica-python,PyPI,Apache-2.0,"Copyright 2013 Justin Berka, Alex Kim, Siting Ren"
+voltdbclient,PyPI,MIT,Copyright (c) Volt Active Data <support@voltactivedata.com>
 wrapt,PyPI,BSD-3-Clause,"Copyright (c) 2013-2026, Graham Dumpleton"

agent_requirements.in

@@ -66,4 +66,5 @@ supervisor==4.3.0
 tuf==4.0.0
 urllib3==2.6.3
 vertica-python==1.4.0
+voltdbclient==14.2.0
 wrapt==2.1.2

voltdb/README.md

@@ -30,55 +30,81 @@ No additional installation is needed on your server.
 
 2. Edit the `voltdb.d/conf.yaml` file, in the `conf.d/` folder at the root of your Agent's configuration directory to start collecting your VoltDB performance data. See the [sample voltdb.d/conf.yaml][4] for all available configuration options.
 
+    The integration supports two transports. Pick the one that matches your network topology:
+
+    **Native binary client** - direct connection to a database node on the VoltDB client port (default `21212`), using the [VoltDB Python client][12]. Recommended when the Agent host can reach the database nodes directly:
+
     ```yaml
     init_config:
 
     instances:
-      - url: http://localhost:8080
+      - host: localhost
+        port: 21212
         username: datadog-agent
         password: "<PASSWORD>"
     ```
 
-3. [Restart the Agent][5].
+    For failover across cluster members, use `hosts` instead of `host`. The Agent connects to the first reachable entry and silently fails over to the others if the active node becomes unavailable:
 
-#### TLS support
-
-If [TLS/SSL][6] is enabled on the client HTTP port:
+    ```yaml
+    instances:
+      - hosts:
+          - voltdb-1.example:21212
+          - voltdb-2.example:21212
+          - voltdb-3.example:21212
+        username: datadog-agent
+        password: "<PASSWORD>"
+    ```
 
-1. Export your certificate CA file in PEM format:
+    **HTTP/JSON via the VoltDB Management Center (VMC)** - useful when database nodes aren't directly reachable but the VMC endpoint is, or when you prefer to keep the existing HTTP/JSON wire format. Set `url` to the VMC endpoint:
 
-    ```bash
-    keytool -exportcert -file /path/to/voltdb-ca.pem -keystore <KEYSTORE> -storepass <PASSWORD> -alias voltdb -rfc
+    ```yaml
+    instances:
+      - url: http://vmc.example.com:8080
+        username: datadog-agent
+        password: "<PASSWORD>"
     ```
 
-1. Export your certificate in PEM format:
+    The check picks the transport based on which option is set: `url` selects HTTP mode, `host`/`hosts` selects native mode. HTTP mode keeps all the options earlier releases supported (`password_hashed`, `tls_cert`, `tls_ca_cert`, `tls_verify`, `proxy`, `headers`, etc.) - see the [sample config][4] for the full list.
 
-    ```bash
-    openssl pkcs12 -nodes -in <KEYSTORE> -out /path/to/voltdb.pem -password pass:<PASSWORD>
-    ```
+    **Backwards compatibility**: existing configurations that point `url` at the legacy HTTP endpoint continue to work without changes. This release adds the native binary transport as an option; it does not remove the HTTP one. The `url`-style config still emits the same metrics and service checks against the same VMC or HTTP-enabled database node it always pointed at.
 
-    The resulting file should contain the _unencrypted_ private key and the certificate:
+3. [Restart the Agent][5].
 
-    ```
-    -----BEGIN PRIVATE KEY-----
-    <Private key contents...>
-    -----END PRIVATE KEY-----
-    -----BEGIN CERTIFICATE-----
-    <Certificate contents...>
-    -----END CERTIFICATE-----
-    ```
+#### TLS support
 
-2. In your instance configuration, point `url` to the TLS-enabled client endpoint, and set the `tls_cert` and `tls_ca_cert` options. For example:
+If [TLS/SSL][6] is enabled on the VoltDB client port, set `use_ssl: true` and point `ssl_config_file` at a VoltDB SSL properties file that describes how to locate the truststore (and optionally a client keystore for mutual TLS):
 
-    ```yaml
-    instances:
-    - # ...
-      url: https://localhost:8443
-      tls_cert: /path/to/voltdb.pem
-      tls_ca_cert: /path/to/voltdb-ca.pem
-    ```
+```yaml
+instances:
+  - host: localhost
+    port: 21212
+    username: datadog-agent
+    password: "<PASSWORD>"
+    use_ssl: true
+    ssl_config_file: /etc/voltdb/ssl.properties
+```
 
-3. [Restart the Agent][5].
+The properties file is the same format VoltDB's own tools (`sqlcmd`, `voltadmin`) consume. The native Python client supports Java keystores (`.jks`), PKCS12 (`.p12`/`.pfx`), and PEM. A minimal one-way TLS configuration looks like:
+
+```properties
+# /etc/voltdb/ssl.properties
+truststore=/etc/voltdb/certs/truststore.jks
+truststorepassword=<TRUSTSTORE_PASSWORD>
+```
+
+For mutual TLS, also add a keystore that identifies the Agent to the server:
+
+```properties
+truststore=/etc/voltdb/certs/truststore.jks
+truststorepassword=<TRUSTSTORE_PASSWORD>
+keystore=/etc/voltdb/certs/agent-keystore.jks
+keystorepassword=<KEYSTORE_PASSWORD>
+```
+
+If you have a PEM CA bundle instead of a Java keystore, you can either point `ssl_config_file` directly at the PEM file (it is treated as the truststore), or reference it explicitly with `cacerts=<PATH>` inside the properties file.
+
+When the Agent runs in a container, make sure the properties file and every path it references are mounted into the container. See the [VoltDB TLS/SSL documentation][6] for details on generating keystores with `keytool` and rotating certificates.
 
 #### Log collection
 
@@ -140,3 +166,5 @@ Need help? Contact [Datadog support][11].
 [9]: https://github.com/DataDog/integrations-core/blob/master/voltdb/metadata.csv
 [10]: https://github.com/DataDog/integrations-core/blob/master/voltdb/assets/service_checks.json
 [11]: https://docs.datadoghq.com/help/
+[12]: https://pypi.org/project/voltdbclient/
+[13]: https://docs.datadoghq.com/agent/configuration/secrets-management/

voltdb/assets/configuration/spec.yaml

@@ -11,24 +11,115 @@ files:
 
       - template: instances
         options:
+          - name: host
+            description: |
+              Host of the VoltDB cluster member to connect to via the native binary
+              protocol. Use this (with `port`) for direct connections to a database
+              node. Set `url` instead to talk to the VoltDB Management Center (VMC)
+              over HTTP/JSON. For failover across multiple cluster members, use
+              `hosts` instead.
+            fleet_configurable: true
+            display_priority: 5
+            value:
+              type: string
+              example: localhost
+
+          - name: hosts
+            description: |
+              List of VoltDB cluster members to try when connecting via the native
+              binary protocol. Each entry is either `hostname` (uses the global
+              `port`) or `hostname:port`. The Agent connects to the first
+              reachable entry and silently fails over to subsequent entries if
+              the active node becomes unavailable. Takes precedence over `host`.
+            fleet_configurable: true
+            display_priority: 5
+            value:
+              type: array
+              items:
+                type: string
+              example:
+                - voltdb-1.example:21212
+                - voltdb-2.example:21212
+                - voltdb-3.example:21212
+
           - name: url
-            description: URL to a VoltDB client endpoint.
+            description: |
+              URL of a VoltDB HTTP/JSON endpoint, typically served by the
+              VoltDB Management Center (VMC). When set, the integration uses the
+              HTTP/JSON transport instead of the native binary client. The
+              `username` and `password` options are required in this mode.
+
+              For direct connections to a database node, prefer `host` (and
+              optionally `port`), which uses the native Python client.
+            display_priority: 5
+            value:
+              type: string
+              example: http://localhost:8080
+
+          - name: port
+            description: |
+              Native client port of the VoltDB cluster member.
+
+              See: https://docs.voltdb.com/UsingVoltDB/HostConfigPortOpts.php
             fleet_configurable: true
-            formats: ["url"]
-            required: true
+            display_priority: 4
+            value:
+              type: integer
+              example: 21212
+
+          - name: username
+            description: The username to use to authenticate with VoltDB.
             display_priority: 3
             value:
               type: string
-              example: http://localhost:8080
+              example: <USERNAME>
 
-          - name: password_hashed
+          - name: password
+            description: The password to use to authenticate with VoltDB.
+            display_priority: 3
+            secret: true
+            value:
+              type: string
+              example: <PASSWORD>
+
+          - name: use_ssl
             description: |
-              Set to true if the `password` value refers to a hashed version of the password.
-            display_priority: 1
+              Set to `true` to connect to VoltDB using TLS.
+
+              See: https://docs.voltdb.com/UsingVoltDB/SecuritySSL.php
+            display_priority: 2
             value:
               type: boolean
               example: false
 
+          - name: ssl_config_file
+            description: |
+              Path to a VoltDB SSL configuration file that defines the Java keystore
+              and truststore files used by the native Python client.
+
+              See: https://docs.voltdb.com/UsingVoltDB/SecuritySSL.php
+            display_priority: 2
+            value:
+              type: string
+              example: <SSL_CONFIG_FILE_PATH>
+
+          - name: connect_timeout
+            description: Connection timeout (in seconds) when establishing the native client connection.
+            display_priority: 1
+            value:
+              type: number
+              example: 8
+
+          - name: procedure_timeout
+            description: |
+              Timeout (in seconds) for individual stored procedure calls. Set to
+              `0` to wait indefinitely for a response.
+            display_priority: 1
+            value:
+              type: number
+              example: 60
+              default: 60
+
           - name: statistics_components
             fleet_configurable: true
             description: |
@@ -70,14 +161,19 @@ files:
                 - SNAPSHOTSTATUS
                 - TABLE
 
+          - name: password_hashed
+            description: |
+              Only applicable to the HTTP/VMC transport (`url` is set). Set to
+              `true` if the `password` value is the SHA-256 hex digest of the
+              password instead of the cleartext. The native binary client does
+              not support pre-hashed passwords.
+            display_priority: 1
+            value:
+              type: boolean
+              example: false
+
           - template: instances/http
             overrides:
-              username.display_priority: 2
-              username.required: true
-              username.description: The username to use to authenticate with VoltDB.
-              password.display_priority: 2
-              password.required: true
-              password.description: The password to use to authenticate with VoltDB.
               auth_type.hidden: true
               ntlm_domain.hidden: true
               kerberos_auth.hidden: true
@@ -91,6 +187,9 @@ files:
               aws_region.hidden: true
               aws_host.hidden: true
               aws_service.hidden: true
+              username.hidden: true
+              password.hidden: true
+              connect_timeout.hidden: true
           - template: instances/db
           - template: instances/default
 

voltdb/changelog.d/23667.added

@@ -0,0 +1 @@
+Add support for the native [VoltDB Python client](https://pypi.org/project/voltdbclient/) (binary protocol on the VoltDB client port, default `21212`) for direct database-node connections. Configure with `host` (single node) or `hosts` (a list of cluster members for connect-time failover). Optional `port` provides a default for entries without one. TLS is configured through `use_ssl` and `ssl_config_file` pointing at a VoltDB SSL properties file (JKS, PKCS12, or PEM). Statistics columns are now resolved by name against the VoltDB response metadata so the check tolerates VoltDB releases that add or drop columns to `@Statistics` outputs. The existing HTTP/JSON transport (with `url`, `password_hashed`, PEM-based TLS, and proxy options) is fully preserved for users connecting through the VoltDB Management Center (VMC) — existing `url`-based configurations continue to work unchanged.