Install the web UI

Select a documentation version:

This page shows how to install the AlloyDB Omni web user interface so that you can monitor the health and configuration of your self-managed database clusters. The web UI provides the following features:

Feature Description Containers (standalone) Kubernetes RPM (Linux) RPM orchestrator
Cluster selection A connectivity screen that lets you establish, register, and save connection credentials for access to target clusters. Supported Supported Supported Supported
Cluster overview Observation dashboard displaying all active cluster instances and telemetry graphs. Partial support. Telemetry graphs aren't supported Supported Supported Supported
Databases Overview page displaying catalog tables and database sizes on the cluster. Supported Supported Supported Supported
Columnar engine Configuration settings and scan execution statistics for analytical queries. Supported Supported Supported Supported
Database flags Observation board displaying active flags and configurations that deviate from default settings. Supported Supported Supported Supported
Query insights Telemetry and query performance dashboards displaying structural histograms and slow query lists. Supported Supported Supported Supported
System insights Telemetry charts displaying CPU consumption, memory footprints, and disk I/O. Not supported (standalone container only) Supported Supported Supported

Before you begin

Before you install the web UI, make sure that you do the following:

  1. Obtain the images for your deployment and download and install AlloyDB Omni so that you can use the web UI: Install AlloyDB Omni using containers.

  2. Configure the database user.

    The web UI relies on a limited user account, which has the pg_monitor role for accessing the database. Configure this user on each cluster by running the following commands in a psql session:

    CREATE ROLE alloydbui WITH LOGIN PASSWORD 'PASSWORD';
GRANT pg_monitor TO alloydbui WITH INHERIT TRUE;

  3. Configure Prometheus.

    To view chart data on the Overview and System Insights pages, including CPU usage, install and configure Prometheus. Note: A containerized monitoring agent isn't available when you deploy AlloyDB Omni as a standalone container. Prometheus chart metrics on the Overview and System Insights pages aren't supported when you connect to standalone container deployments.

Optional steps

To enable additional web UI features:

  • Query insights setup

    To use the query insights feature, enable the pg_stat_statements extension. In a psql session, run the following commands to configure the libraries:

    ALTER SYSTEM SET shared_preload_libraries=google_columnar_engine,google_job_scheduler,google_storage,google_db_advisor,pg_stat_statements;
ALTER SYSTEM SET pg_stat_statements.max = 10000;
ALTER SYSTEM SET pg_stat_statements.track_utility = on;
ALTER SYSTEM SET track_io_timing = on;

    Then, execute the following command in each database individually to create the extension:

    CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

    Restart the database for these changes to take effect. If you plan to enable the columnar engine, wait to restart until that setup is complete.

  • Columnar engine setup

    To access columnar engine data in the web UI, configure the engine as described in Columnar engine overview.

  • AlloyDB AI setup

    To use AlloyDB AI features in the web UI, grant the following permissions:

    • To populate vector indexes, grant the alloydbui user the SELECT permission on pg_stat_ann_indexes.
    • To display vector columns, grant the alloydbui user the SELECT permission on a table.
For more information, see Build generative AI applications using AlloyDB AI.

Install the web UI

You can install and run the web UI on any node; the web UI doesn't require a dedicated node. The full installation requires approximately 250 MB of disk space. After you obtain the images for your deployment and download AlloyDB Omni, you can install and run the web UI.

Install using Docker or Podman image

When you use AlloyDB Omni using containers, pull the Docker or Podman image:

Docker 

docker pull ALLOYDB_OMNI_UI_IMAGE_TAG

Podman 

podman pull ALLOYDB_OMNI_UI_IMAGE_TAG

Start the web UI

The web UI uses a Java Keystore to protect the 256-bit AES key that is used to encrypt connection data. When you start the web UI, specify an environment variable containing the password.

Start the web UI on containers

Run the following command to start the web UI container. Include the --add-host=host.docker.internal:host-gateway flag if you connect to an AlloyDB Omni installation on the same host machine:

Docker 

docker run --name alloydb-omni-ui \
  --add-host=host.docker.internal:host-gateway \
  -e ALLOYDB_OMNI_UI_KEYSTORE="PASSWORD" \
  -p 9080:9080 \
  ALLOYDB_OMNI_UI_IMAGE_TAG

Podman 

podman run --name alloydb-omni-ui \
  --add-host=host.docker.internal:host-gateway \
  -e ALLOYDB_OMNI_UI_KEYSTORE="PASSWORD" \
  -p 9080:9080 \
  ALLOYDB_OMNI_UI_IMAGE_TAG

Open the web UI

To view the web UI, open a browser at http://HOST:9080.

Replace HOST with the hostname or IP address of the node where the web UI is installed.

  • If you configured a custom base path using the optional ALLOYDB_OMNI_BASE_PATH environment variable (for example, when hosting behind an existing reverse proxy), then you must append the path to the URL: http://HOST:9080/BASE_PATH.

  • You can configure the base path without a leading slash—for example, ALLOYDB_OMNI_BASE_PATH=PATH. All of the following are valid alternatives:

    • /test/
    • test/
    • test
    • /test

Limitations

The web UI has the following limitations:

  • Overview charts and system insights aren't available when connecting to AlloyDB Omni standalone container deployments because a containerized monitoring agent isn't available for standalone container deployments. All other non-chart features and metrics remain fully functional.

  • To view columnar engine data for a given table, the alloydbui user needs at least one permission on that table, for example, SELECT.

  • To view vector index data, the alloydbui user needs the SELECT permission on pg_stat_ann_indexes.

  • To view vector column data for a given table, the alloydbui user needs the SELECT permission on that table.

Best practices and caveats

Follow these best practices and caveats when you install and configure the web UI:

  • Keystore password protection: The web UI generates a Java Keystore to protect the 256-bit AES database encryption key. Use a strong passphrase for ALLOYDB_OMNI_UI_KEYSTORE. Decryption errors occur if you transfer your configuration files and connect with a mismatching keystore password.
  • Prometheus metrics scraping: Configure the scrapers to poll target instances at standard ranges (15s to 30s) to query statistics without overloading database nodes.

    What's next