OpenText Analytics Database 26.2.x – Database management with VCluster

Admin: Database management with VCluster CLI

Mon, 01 Jan 0001 00:00:00 +0000

The VCluster CLI is a tool for administering a single database. This tool is bundled with OpenText™ Analytics Database installations. VCluster CLI communicates with database nodes by leveraging the REST APIs provided by Node Management Agent and HTTPS service.

Note

The VCluster CLI is targeted primarily for managing Eon Mode databases. While you can create and manage Enterprise Mode databases, the suite of commands for doing so is less complete. For a more complete set of Enterprise Mode management tools, see Administration tools reference.

Prerequisites

To use the VCluster CLI, you must first configure the Node Management Agent (NMA), including running the following command on all nodes:

$ /opt/vertica/bin/manage_node_agent.sh start node_management_agent

Note

If the database host is stopped and restarted, you must restart the NMA to ensure proper functionality.

Best practices

The majority of VCluster CLI commands use the configuration file, which is automatically created when you create a database. You should always use this configuration file when using VCluster CLI, either by ensuring that the configuration file is in the default location (/opt/vertica/config/vertica_cluster.yaml) or specifying it with --config.

To recreate a configuration file, use manage_config recover. This can be useful if you lose your configuration file or if it becomes corrupted.

To view your current configuration file, use manage_config show.

Important

The symbol "$" is stored as a numerical value when used in VCluster when used in a string. If you want to use the symbol as a character, use the escape characer "" before the symbol. If you have multiple "$" characters in a row, the escape character must be used before each one.

Admin: Database management with VCluster UI

Mon, 01 Jan 0001 00:00:00 +0000

The VCluster UI is a tool for administering your database. This tool is bundled with OpenText™ Analytics Database installations. VCluster UI works with the VCluster CLI to manage your database. It works with both the EON and Enterprise database types.

Setting up VCluster UI

Setting up the VCluster UI for your system depends on whether you already have a database set up and how you created your database: AdminTools or VCluster CLI. Use the section below that corresponds to your setup:

Configure VCluster server

To setup VCluster UI and create a new database:

Start the node management agent on all of the nodes:

$  /opt/vertica/bin/manage_node_agent.sh start node_management_agent

Here is an example script that can be used to start the node management agent on multiple nodes:

for x in 10.20.71.10 10.20.71.11 10.20.71.12 10.20.71.13; do echo "host is $x"; ssh $x /opt/vertica/bin/manage_node_agent.sh 
start node_management_agent; done;

Start the VCluster service on one of the hosts (this is the host that you will connect to in order to use VCluster):
```
$  /opt/vertica/bin/manage_vcluster_server.sh start vluster_server
```
This will create a certificate for the UI that you need to import into your browser.
Navigate to /opt/vertica/config/vcluster_server and download the admin.p12 certificate to the local machine where you intend to access the VCluster Web UI.
Note
```
If you need to create your own certificate, use the `vcluster_server --init` command.    
```
In a browser, import the certificate by going to Settings > Manage Certificate and add the admin.p12 certificate. The password for the default certificate is vertica.
Launch the VCluster Web UI by navigating to https://<hostname>:8665. When prompted, select the certificate that you just imported and click OK.
Click the link in the Dashboard to create your database.

Create a database from VCluster UI

After you click the link to create a database, you are directed to the Create Database page.
Choose Eon or Enterprise as the database type. The available fields change based on your selection.

Specify the details of your database.

Note

- Configuration parameters are mandatory when creating an Eon Mode database.
- The default time for **Startup Timeout** is 5 minutes.

Click Create.
In the Job Satus page, you can view the status of your new database.
Continue with Accessing the VCluster UI.

Access existing database from VCluster UI

Follow these steps if your database was created using the VCluster CLI:

Start the node management agent on all of the nodes:

$  /opt/vertica/bin/manage_node_agent.sh start node_management_agent

Here is an example script that can be used to start the node management agent on multiple nodes:

for x in 10.20.71.10 10.20.71.11 10.20.71.12 10.20.71.13; do echo "host is $x"; ssh $x /opt/vertica/bin/manage_node_agent.sh 
start node_management_agent; done;

Start the VCluster service on one of the hosts (this is the host that you will connect to in order to use VCluster):
```
$  /opt/vertica/bin/manage_vcluster_server.sh start vluster_server
```
This will create a certificate for the UI that you need to import into your browser.
Navigate to /opt/vertica/config/vcluster_server and download the admin.p12 certificate to the local machine where you intend to access the VCluster Web UI.
Note
```
If you need to create your own certificate, use the `vcluster_server --init` command.    
```
In a browser, import the certificate by going to Settings > Manage Certificate and add the admin.p12 certificate. The password for the default certificate is vertica.
Launch the VCluster Web UI by navigating to https://<hostname>:9090. When prompted, select the certificate that you just imported and click OK.

The VCluster Web Server leverages an embedded HTTPS service, which requires TLS authentication for secure access. Run the following commands to set the client-server TLS setting.

Enable TLS:

vsql -c "create authentication tls_for_all method 'tls' host tls '0.0.0.0/0';" 
vsql -c "grant authentication tls_for_all to public;"

Generate a CA private key and CA certificate (replacing the CA path with the correct information):

CREATE KEY ca_key TYPE 'RSA' LENGTH 2048;
CREATE CA CERTIFICATE ca_cert SUBJECT '/<CA path>/CN=Vertica Root CA' VALID FOR 3650 EXTENSIONS 'nsComment' = 'Self-signed root CA cert' KEY ca_key;

Create the server private key and server certificate (replacing the server path and IP addresses with the correct information):

CREATE KEY server_key TYPE 'RSA' LENGTH 2048;
CREATE CERTIFICATE server_cert SUBJECT '/<server path>/CN=Vertica server alt/emailAddress=doesntmatter@example.com' SIGNED BY ca_cert EXTENSIONS 'nsComment' = 'Vertica/NMA server cert with IP hostname', 'extendedKeyUsage' = 'serverAuth,clientAuth', 'subjectAltName' = 'IP.1:x.x.x.x,IP.2:x.x.x.x,IP.3:x.x.x.x,IP.4:x.x.x.x' KEY server_key;

Alter the TLS configuration:

ALTER TLS CONFIGURATION server CERTIFICATE server_cert ADD CA CERTIFICATES ca_cert TLSMODE 'VERIFY_CA';
ALTER TLS CONFIGURATION server TLSMODE 'ENABLE';

Continue with Accessing the VCluster UI.

Access VCluster UI

To access VCluster UI, navigate to https://<hostname>:8665 using the server IP of the database host where you started the VCluster service. You are prompted to select the server certificate you imported to your browser previously.

Understanding VCluster UI

OpenText™ Analytics Database version information: Displays the current version of the database.
Help: Access the VCluster UI documentation and swagger documentation.
Left navigation: Shows the available pages and highlights the current page.
Landing page: Displays the different tiles to manage your database.

Admin: Migrate your database from AdminTools to VCluster

Mon, 01 Jan 0001 00:00:00 +0000

You can migrate an AdminTools managed database to VCluster, and then manage the database using the VCluster CLI or VCluster UI.

Prerequisites

A database created using AdminTools (Enterprise or Eon Mode)
Passwordless SSH access to all cluster nodes
Vertica version 24.3 or later (required for VCluster CLI migration)
Vertica version 25.3 or later (required for VCluster UI migration)
The following ports are open on all nodes:
- 5554: Node Management Agent (NMA)
- 8665: VCluster UI

Additional prerequisites for Eon Mode

Communal storage is configured (for example, S3 or S3-compatible storage such as MinIO)
Access key, secret key, and endpoint are available
Bucket path for communal storage (for example, s3:///)

Migrate your database from AdminTools to VCluster CLI

Start the node management agent on all of the nodes:

for x in <host1> <host2> <host3>; do echo "host is $x"; ssh $x /opt/vertica/bin/manage_node_agent.sh start node_management_agent; done;

Run the following command to convert the AdminTools managed database to VCluster:
```
admintools -t convert_to_vcluster
```
This command converts the AdminTools configuration to VCluster and generates the configuration file at /opt/vertica/config/vertica_cluster.yaml.

After conversion, use VCluster CLI commands to manage the database. You can verify the conversion by stopping and starting the database:

Stop the database:

vcluster stop_db --db-name <db-name>

Example output:

✔ Collect node information
✔ Collect cluster information
✔ Update node state from running database
✔ Collect information for all up nodes
✔ Stop database
✔ Verify database is not running
[INFO] Successfully stopped a database with name <db-name>

Start the database:

vcluster start_db --db-name <db-name>

Example output:

✔ Check NMA service health
✔ Verify database is running
✔ Collect nodes information
✔ Read catalog
✔ Check Vertica version
✔ Get contents of vertica.conf
✔ Get contents of spread.conf
✔ Start 3 node(s)
✔ Wait for 3 node(s) to come up: all nodes are up
✔ Collect node information
✔ Collect cluster information
✔ Update node state from running database
[INFO] Started database <db-name>

These commands confirm that the database is now managed by VCluster.

Migrate your database from AdminTools to VCluster UI

Follow these steps if your database was created using AdminTools:

Start the node management agent on all of the nodes:

$  /opt/vertica/bin/manage_node_agent.sh start node_management_agent

Here is an example script that can be used to start the node management agent on multiple nodes:

for x in 10.20.71.10 10.20.71.11 10.20.71.12 10.20.71.13; do echo "host is $x"; ssh $x /opt/vertica/bin/manage_node_agent.sh 
start node_management_agent; done;

Run the following script to convert the database configuration to be compatible with VCluster:
```
/opt/vertica/bin/vcluster manage_config recover --db-name migrate_to_vcluster --hosts <list of node IP address separated by commas> --catalog-path /scratch_b/disk_a  --depot-path /scratch_b/disk_a
```
This command registers the database with the VCluster Framework and generates the configuration file at /opt/vertica/config/vertica_cluster.yaml.
Start the VCluster service on one of the hosts (this is the host that you will connect to in order to use VCluster):
```
$  /opt/vertica/bin/manage_vcluster_server.sh start vcluster_server
```
This will create a certificate for the UI that you need to import into your browser.
Navigate to /opt/vertica/config/vcluster_server and download the admin.p12 certificate to the local machine where you intend to access the VCluster Web UI.
Note
```
If you need to create your own certificate, use the `vcluster_server --init` command.    
```
In a browser, import the certificate by going to Settings > Manage Certificate and add the admin.p12 certificate. The password for the default certificate is vertica.
Launch the VCluster Web UI by navigating to https://<hostname>:8665. When prompted, select the certificate that you just imported and click OK.