Install AlloyDB Omni software stack

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

For information about access to this release, see the access request page.

Select a documentation version: 18.1.0

• Current (18.1.0)
• 18.1.0

This page describes how to install the AlloyDB Omni software stack and its management components using the AlloyDB Omni orchestrator.

Before you begin

Before you install the components, make sure you have completed the following prerequisites:

• Install the orchestrator: make sure the AlloyDB Omni orchestrator Ansible collection or CLI is installed on your control node.
• Provision machines: you must have RHEL9 virtual machines provisioned according to your chosen architecture, such as standalone or high availability.
• Configure network and firewall: make sure all required ports are open between your nodes. This includes 5432 for database traffic, 2379/2380 for etcd, and the management ports 6703, 6702, and 6700 used by the Cluster Manager and Node Manager.

Prepare the deployment specification inventory

Note: For optional version parameters in the inventory file, the orchestrator installs the latest available version of the software by default if a specific version is not specified.

The orchestrator uses a deployment specification file in Ansible inventory format to understand your cluster topology. Create a file named deployment_spec.yaml with your node details.

alloydbomni:
  vars:
    cluster_manager:
      name: "MANAGEMENT_CLUSTER_NAME"
    etcd:
      setup: SETUP_ETCD
      config_forcewrite: FORCE_OVERWRITE_ETCD
      # version: ETCD_VERSION  # Optional: defaults to the latest version
      # repo_url: ETCD_REPOSITORY_URL  # Optional
      # repo_gpg_key_url: GPG_KEY  # Optional
    alloydbomni:
      major_version: "PG_VERSION" # Mandatory: for example, 18
      # version: ALLOYDB_OMNI_VERSION    # Optional: defaults to the latest version
      # repo_url: ALLOYDB_OMNI_COMMON_REPOSITORY_URL     # Optional
      # repo_gpg_key_url: GPG_KEY  # Optional
    alloydbomni_monitor:
      # version: ALLOYDB_OMNI_MONITOR_VERSION    # Optional: defaults to the latest version
      # repo_url: ALLOYDB_OMNI_COMMON_REPOSITORY_URL   # Optional
      # repo_gpg_key_url: GPG_KEY  # Optional
    alloydbomni_cluster_manager:
      # version: ALLOYDB_OMNI_CLUSTER_MANAGER_VERSION      # Optional: defaults to the latest version
      # repo_url: ALLOYDB_OMNI_ORCHESTRATOR_REPOSITORY_URL # Optional
      # repo_gpg_key_url: GPG_KEY  # Optional
    alloydbomni_node_manager:
      # version: ALLOYDB_OMNI_NODE_MANAGER_VERSION         # Optional: defaults to the latest version
      # repo_url: ALLOYDB_OMNI_ORCHESTRATOR_REPOSITORY_URL # Optional
      # repo_gpg_key_url: GPG_KEY  # Optional
    pgbouncer:
      # version: ALLOYDB_OMNI_PGBOUNCER_VERSION    # Optional
      # repo_url: ALLOYDB_OMNI_COMMON_REPOSITORY_URL   # Optional
      # repo_gpg_key_url: GPG_KEY  # Optional
    pgbackrest:
      # version: ALLOYDB_OMNI_PGBACKREST_VERSION   # Optional
      # repo_url: ALLOYDB_OMNI_COMMON_REPOSITORY_URL   # Optional
      # repo_gpg_key_url: GPG_KEY  # Optional

  children:
    primary_instance_nodes:
      hosts:
        DB_HOST_1:
        DB_HOST_2:
        DB_HOST_3:
    load_balancer_nodes:    # Optional. Host group for load balancer. If empty, no load balancer is configured.
      hosts:
        LB_HOST_1:
        LB_HOST_2:
    etcd_nodes:     # Optional: Host group where etcd is set up
      hosts:
        ETCD_HOST_1:
        ETCD_HOST_2:
        ETCD_HOST_3:
    cluster_manager_nodes:    # Optional: Host group for cluster manager
      hosts:
        CM_HOST_1:
        CM_HOST_2:
        CM_HOST_3:

Replace the following:

• MANAGEMENT_CLUSTER_NAME: the name of your management cluster. This can be the same as your database cluster name if they are installed on the same nodes, for example, my-management-cluster.
• SETUP_ETCD: specifies whether the orchestrator must configure and bootstrap the etcd cluster. When set to true, the orchestrator performs the initial etcd setup and initialization on the designated etcd nodes. If no etcd nodes are defined in your deployment_spec, it defaults to configuring etcd on the cluster manager nodes. This parameter corresponds to the etcd.setup key in the deployment specification.
• FORCE_OVERWRITE_ETCD: determines whether to replace an existing etcd configuration file during the setup process. Set to true to overwrite existing configuration file on the target nodes; otherwise, set to false(the default) to maintain the existing configuration and prevent unintended service disruptions.
• ETCD_VERSION: the version of the etcd package to install, for example, 3.4.13.
• ETCD_REPOSITORY_URL: the URL of the repository containing the etcd RPMs.
• PG_VERSION: the major PostgreSQL version of your AlloyDB Omni installation, for example, 18.
• ALLOYDB_OMNI_VERSION: the version of the AlloyDB Omni database engine to install, for example, 18.1.0. If omitted, the orchestrator installs the latest available version.
• ALLOYDB_OMNI_COMMON_REPO_URL: the URL of the common repository containing AlloyDB Omni, monitor, PgBouncer, and pgBackRest RPMs.
• GPG_KEY: the location of Google's public key for GNU Privacy Guard (GPG) verification—for example, https://dl.google.com/linux/linux_signing_key.pub. This can also be set as a path if the key is downloaded to a file on all VMs, for example, /tmp/linux_signing_key.pub.
• ALLOYDB_OMNI_MONITOR_VERSION: the version of the AlloyDB Omni monitor package to install. Defaults to the latest available version.
• ALLOYDB_OMNI_CLUSTER_MANAGER_VERSION: the version of the AlloyDB Omni cluster manager to install. If omitted, the orchestrator installs the latest available version.
• ALLOYDB_OMNI_ORCHESTRATOR_REPO_URL: the URL of the repository containing the AlloyDB Omni cluster manager and node manager RPMs.
• ALLOYDB_OMNI_NODE_MANAGER_VERSION: the version of the AlloyDB Omni node manager to install. If omitted, the orchestrator installs the latest available version.
• ALLOYDB_OMNI_PGBOUNCER_VERSION: the version of the PgBouncer package to install.
• ALLOYDB_OMNI_PGBACKREST_VERSION: the version of the pgBackRest package to install.
• DB_HOST_1, DB_HOST_2, DB_HOST_3: the IP addresses or fully qualified domain names (FQDNs) of the virtual machines designated as database nodes.
• LB_HOST_1, LB_HOST_2: the IP addresses or fully qualified domain names (FQDNs) of the virtual machines designated as load balancer nodes.
• ETCD_HOST_1, ETCD_HOST_2, ETCD_HOST_3: the IP addresses or FQDNs of the virtual machines designated as etcd nodes.
• CM_HOST_1, CM_HOST_2, CM_HOST_3: the IP addresses or FQDNs of the virtual machines designated as cluster manager nodes.

Install the components

You can install the AlloyDB Omni components and their dependencies using Ansible or by manually installing the software packages on each node.

Install AlloyDB Omni components using Ansible

The recommended method for installation is using the provided Ansible role.

1. Create a playbook named install.yaml that references the install role from the orchestrator collection.

     - name: Install AlloyDB Omni cluster components
       hosts: all
       vars:
         ansible_become: true
         ansible_user: SSH_USER
         ansible_ssh_private_key_file: SSH_KEY_PATH
       roles:
         - role: google.alloydbomni_orchestrator.install
   

   Replace the following:

   • SSH_USER: the username that you use to connect to the nodes in your cluster using SSH.
   • SSH_KEY_PATH: the path to the SSH private key file on your control node —for example, ~/.ssh/id_rsa.

2. Execute the playbook using your inventory file to download and install the RPMs across all specified nodes.

     ansible-playbook -i deployment_spec.yaml install.yaml
   

Note: The google.alloydbomni_orchestrator.install role configures the EPEL release repository on all nodes. Make sure that the epel-release yum repository is accessible.

Install AlloyDB Omni components manually

If you don't use Ansible, you must manually install the RPMs on each node in your cluster.

• REPO_GPG_KEY: the location of Google's public key for GNU Privacy Guard (GPG) verification, for example, https://dl.google.com/linux/linux_signing_key.pub. This can also be set as a path if the key is downloaded to a file on all VMs, for example, file:///tmp/linux_signing_key.pub.

Install AlloyDB Omni components on database nodes

1. On all database nodes, create a YUM repository configuration file named /etc/yum.repos.d/alloydb-omni.repo:

   [alloydbomni_core]
   name=AlloyDB Omni Core
   baseurl=ALLOYDB_OMNI_REPOSITORY_URL
   enabled=1
   repo_gpgcheck=0
   gpgcheck=1
   gpgkey=REPO_GPG_KEY
   
   [alloydbomni_common]
   name=AlloyDB Omni Common
   baseurl=ALLOYDB_OMNI_COMMON_REPOSITORY_URL
   enabled=1
   repo_gpgcheck=0
   gpgcheck=1
   gpgkey=REPO_GPG_KEY
   priority=1
   
   [alloydbomni_orchestrator]
   name=AlloyDB Omni Orchestrator
   baseurl=ALLOYDB_OMNI_ORCHESTRATOR_REPOSITORY_URL
   enabled=1
   repo_gpgcheck=0
   gpgcheck=1
   gpgkey=REPO_GPG_KEY
   

2. Install the components:

   sudo dnf install -y alloydbomniPG_VERSION alloydbomni_monitor alloydbomni_node_manager pgbackrest
   

3. (Optional) If you aren't using separate load balancer nodes, install pgbouncer and keepalived:

   sudo dnf install -y pgbouncer keepalived
   

Install AlloyDB Omni components on etcd nodes

1. On all etcd nodes, create a YUM repository configuration file named /etc/yum.repos.d/alloydb-etcd.repo:

   [etcd]
   name=AlloyDB Omni ETCD
   baseurl=ETCD_REPOSITORY_URL
   enabled=1
   repo_gpgcheck=0
   gpgcheck=1
   gpgkey=REPO_GPG_KEY
   

2. Install etcd:

   sudo dnf install -y etcd
   

Install AlloyDB Omni components on cluster manager nodes

1. On all cluster manager nodes, create a YUM repository configuration file named /etc/yum.repos.d/alloydb-orchestrator.repo:

   [alloydbomni_orchestrator]
   name=AlloyDB Omni Orchestrator
   baseurl=ALLOYDB_OMNI_ORCHESTRATOR_REPOSITORY_URL
   enabled=1
   repo_gpgcheck=0
   gpgcheck=1
   gpgkey=REPO_GPG_KEY
   

2. Install the cluster manager:

   sudo dnf install -y alloydbomni_cluster_manager
   

Install AlloyDB Omni components on load balancer nodes

1. On all load balancer nodes, create a YUM repository configuration file named /etc/yum.repos.d/alloydb-omni-lb.repo:

   [pgbouncer]
   name=AlloyDB Omni Common
   baseurl=ALLOYDB_OMNI_COMMON_REPOSITORY_URL
   enabled=1
   repo_gpgcheck=0
   gpgcheck=1
   gpgkey=REPO_GPG_KEY
   priority=1
   
   [alloydbomni_node_manager]
   name=AlloyDB Omni Orchestrator
   baseurl=ALLOYDB_OMNI_ORCHESTRATOR_REPOSITORY_URL
   enabled=1
   repo_gpgcheck=0
   gpgcheck=1
   gpgkey=REPO_GPG_KEY
   

2. Install the load balancer components:

   sudo dnf install -y alloydbomni_node_manager keepalived pgbouncer haproxy
   

Summary of installed AlloyDB Omni components

The installation process deploys several key RPM packages depending on the node type:

Node type	Components installed	Notes
Primary instance nodes	alloydbomniPG_VERSION, alloydbomni_monitor, alloydbomni_node_manager, pgbouncer, pgbackrest	Components for the database engine, monitoring, and management.
Load Balancer nodes	haproxy	Optional. Installation skipped if load balancer nodes are not available.
Cluster manager nodes	alloydbomni_cluster_manager	Can be installed on database nodes if no dedicated nodes are available. If cluster manager nodes aren't specified, the cluster manager component is installed on the primary_instance_nodes.
etcd nodes	etcd	Can be installed on cluster manager nodes if needed. If etcd nodes aren't specified, etcd is installed on the cluster_manager_nodes

Uninstall the components

If you need to remove the AlloyDB Omni installation from your environment—for example, to decommission a cluster or to prepare for a clean reinstallation—then you can uninstall all of its software components. You uninstall AlloyDB Omni using Ansible or by manually removing the RPMs from each node.

Uninstall AlloyDB Omni components using Ansible

To remove the AlloyDB Omni software stack components using Ansible, use your existing inventory file and a playbook that references the google.alloydbomni_orchestrator.uninstall role.

1. Create a playbook named uninstall.yaml.

   - name: Uninstall AlloyDB Omni cluster
     hosts: all
     vars:
       ansible_become: true
       ansible_user: SSH_USER
       ansible_ssh_private_key_file: SSH_KEY_PATH
     roles:
       - role: google.alloydbomni_orchestrator.uninstall
   

   Replace the following:

   • SSH_USER: the username that you use to connect to the nodes in your cluster using SSH.
   • SSH_KEY_PATH: the path to the SSH private key file on your control node —for example, ~/.ssh/id_rsa.

2. Execute the playbook. You must pass cleanup_data=true and cleanup_config=true as extra variables to remove the configuration files and data directory.

   ansible-playbook -i deployment_spec.yaml uninstall.yaml -e "cleanup_data=true cleanup_config=true"
   

   Note: If the uninstall process fails due to inconsistencies in the cluster state, you can attempt a force uninstall by adding -e force=true to the command.

Uninstall AlloyDB Omni components manually

If you are using the AlloyDB Omni orchestrator CLI, you must manually remove the RPMs from each node.

1. On all database nodes, run the following command:

   sudo dnf remove -y alloydbomni_node_manager alloydbomniPG_VERSION alloydbomni_monitor pgbackrest keepalived pgbouncer
   

2. On all load balancer nodes, run the following command:

   sudo dnf remove -y alloydbomni_node_manager keepalived haproxy pgbouncer
   

3. On all cluster manager nodes, run the following command:

   sudo dnf remove -y alloydbomni_cluster_manager
   

4. Optional: On all etcd nodes, run the following command to uninstall etcd and clean etcd data:

   sudo dnf remove -y etcd
   sudo rm -rf /var/lib/etcd/data
   

What's next

• To bring your own certificate and key files for TLS, see How AlloyDB Omni uses TLS.

• Create an AlloyDB Omni cluster.