Skip to content

Configure Database Connection in Vault

Database nodes are a type of IO node used to read from and write to a database. To establish a connection, a database node retrieves connection details from a Vault key-value path.

This documentation explains how to set up these connections in Vault.

Tip

Database connections can be configured at the node level, or inherited from playpen or system-level defaults. For details on configuring a connection for database nodes, see Setting up Database Connections in the User Guide.

Interactive Setup via VOR CLI

VOR provides a CLI command, vor create secret, which interactively guides you through creating a database connection secret in Vault. This approach is recommended over manual creation because it ensures all required fields are properly filled and validates the database connection parameters before saving. Refer to the CLI documentation in the User Guide for more information.

Manual Configuration via Vault CLI

Use the following template command to create a secret for the database connection parameters in Vault:

echo '{
      "credential_path": "",
      "username": "",
      "password": "",
      "host": "",
      "port": 0,
      "name": "",
      "ssl": "",
      "allowed_groups": []
    }' | \
    vault kv put kv/node/<path> -

Important

  • The Vault path for each node must match the pattern kv/node/<name>.
  • If using credential_path, make sure the referenced secret exists in Vault.

Database Connection Field Descriptions

  • host (string: <required>): The hostname or IP address of the database server.
  • port (int: <required>): The database server's port number
  • name (string: <required>): The name of the database to connect to.
  • username (string): The username for database authentication. Required if credential_path is not provided.
  • password (string): The password for database authentication. Required if credential_path is not provided.
  • credential_path (string): The Vault path to the credentials. Provides more flexibility for using either dynamic secrets for short-lived credentials or static secrets without exposing them in the configuration. Required if username and password are not provided.

  • ssl (string): The SSL or encryption mode for the connection.
    PostgreSQL
    Accepted values are disable, allow, prefer,require,verify-ca, and verify-full. The default is prefer if not specified. See the PostgreSQL SSL documentation for details.
    MSSQL
    Accepted values are strict, disable, false, and true. The default is false if not specified. For more information, refer to the MSSQL Encrypt Connection Parameter.

  • allowed_groups (list): A list of VOR groups that are allowed to access this node. If not provided, all groups are allowed.

Setting a Global Database Connection

To set a global (system-level) database connection, define the database_conn_path variable in your Ansible inventory file (hosts.ini) during deployment. This variable should specify the Vault path (relative to kv/data/node) where the global database connection information is stored. All database nodes and playpens will use this path to retrieve their connection details by default, unless overridden at a more specific level.

Example Inventory Variable

In your hosts.ini file:

database_conn_path=vor/mssql

This will use the Vault secret at kv/data/node/vor/mssql for the global database connection.

Warning

  • Any database node or playpen without a specific connection configured will use the global connection set by database_conn_path.
  • Defining database_conn_path only sets the path to the global connection secret. You must still create this secret at the specified Vault path after deployment.