Deploy AlloyDB Omni on a single GCE VM

1. Introduction

This codelab shows how to deploy AlloyDB Omni on a single Google Compute Engine (GCE) virtual machine. At the end of this codelab, you will have provisioned a single GCE VM running Rocky Linux 9 and installed AlloyDB Omni using the official RPM packages. This virtual machine is loaded with all the development tools you'll need. It offers a persistent 20GB home directory, and runs on Google Cloud, greatly enhancing network performance and authentication.

Prerequisites

• Access to a Google Cloud Project and Cloud Shell from Cloud Console.
• Google Cloud SDK (gcloud) installed and configured. For details on installing gcloud, refer to gcloud-install

What you'll learn

• How to create and prepare a GCE VM for AlloyDB Omni using gcloud.
• How to install AlloyDB Omni RPMs on a single Linux node.
• How to bootstrap and configure AlloyDB Omni.
• How to verify the local database installation.

What you'll need

• Obtain a URL link to AlloyDB Omni RPMs. The links are sent to your email which includes the repository URL server. Initialize the following environment variable to keep the URL ready to use during the codelab.

  export ALLOYDB_OMNI_REPOSITORY_URL="..."
  

• A working terminal with access to Google Cloud. You can use Cloud Shell for this purpose.

2. Setup and Requirements

Project setup

Create a Google Cloud Project

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
2. Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project.

Start Cloud Shell

Although you can operate Google Cloud remotely from your laptop, in this codelab you use the Google Cloud Shell, a command-line environment running in the cloud.

1. Open the Google Cloud console and click the Cloud Shell icon on the top right toolbar.You can also open the Cloud Shell in one of the following ways:
   • If you're using the Google Cloud console, press G and then S.
   • Click this link.

It typically takes a few moments to provision and connect to the environment. When this operation completes, you see something similar to the following:

{: width="624"}

3. Create the Compute Engine VM

In this section, you create a single Compute Engine (GCE) virtual machine (VM) using the gcloud command-line tool. You use a Rocky Linux 9 image, which is fully compatible with AlloyDB Omni RPMs.

1. Define environment variables for your project ID, VM name, zone, and region.

   export PROJECT="your-project-id"
   export INSTANCE_NAME="alloydb-omni-vm"
   export ZONE="us-central1-c"
   export REGION="us-central1"
   

2. Sign in with using your Google Cloud account user, and configure the default project.

   gcloud auth login
   gcloud config set project $PROJECT
   

3. Create a firewall rule to allow SSH connections to your VM.

   gcloud compute firewall-rules create allow-ssh-alloydb-omni \
       --project=$PROJECT \
       --direction=INGRESS \
       --action=allow \
       --rules=tcp:22 \
       --source-ranges="0.0.0.0/0"
   

4. Since the VM is created without a public IP address, configure a Cloud Router and Cloud NAT gateway to let the VM access external package repositories and download required software.

   gcloud compute routers create alloydb-omni-router \
       --project=$PROJECT \
       --network=default \
       --region=$REGION
   
   gcloud compute routers nats create alloydb-omni-nat \
       --project=$PROJECT \
       --router=alloydb-omni-router \
       --region=$REGION \
       --nat-all-subnet-ip-ranges \
       --auto-allocate-nat-external-ips
   

5. Ensure that your VPC network has a valid default internet gateway route. In some shared or playground environments, default routes are occasionally removed by cleanup scripts. This route is required for Cloud NAT to forward outbound traffic to the internet.

   gcloud compute routes create default-internet-route \
       --project=$PROJECT \
       --network=default \
       --destination-range=0.0.0.0/0 \
       --next-hop-gateway=default-internet-gateway
   

6. Create the Compute Engine VM instance with the required specifications (16 vCPUs, 20GB balanced persistent disk, Rocky Linux 9). For enhanced security, we use the --no-address flag to ensure the VM is not assigned a public IP address.

   gcloud compute instances create $INSTANCE_NAME \
       --project=$PROJECT \
       --zone=$ZONE \
       --machine-type=n2-highmem-16 \
       --image-family=rocky-linux-9 \
       --image-project=rocky-linux-cloud \
       --boot-disk-size=20GB \
       --boot-disk-type=pd-balanced \
       --no-address
   

7. After the VM is created, verify the VM's status.

   gcloud compute instances list --filter="name=$INSTANCE_NAME" --project=$PROJECT
   

4. Prepare VM

In this section, you connect to your newly created VM and prepare the operating system environment, which includes setting up the data directory and configuring SELinux.

1. Connect to the VM over SSH using Identity-Aware Proxy (IAP). Since the VM doesn't have a public IP address, gcloud will automatically tunnel the SSH connection through IAP.

   gcloud compute ssh $INSTANCE_NAME --zone=$ZONE --project=$PROJECT --tunnel-through-iap
   

2. Define environment variables on the VM for the data directory and your AlloyDB Omni repository URL. Replace the URL with the one you received from the signup form.

   export PGDATA="/var/lib/alloydbomni"
   export ALLOYDB_OMNI_REPOSITORY_URL="..."
   

3. Create the data directory where AlloyDB Omni will store its database files.

   sudo mkdir -p $PGDATA
   

4. Install the policycoreutils-python-utils package so that the SELinux policy can be configured to allow the AlloyDB Omni database service to run properly.

   sudo dnf install -y policycoreutils-python-utils
   

5. Install AlloyDB Omni

With the VM prepared, you can now configure the package repository and install the AlloyDB Omni RPM package.

1. Configure the YUM repository on your VM by creating the repository configuration file.

   sudo tee /etc/yum.repos.d/alloydbomni.repo << EOF
   [alloydbomni]
   name=alloydbomni
   baseurl=$ALLOYDB_OMNI_REPOSITORY_URL
   enabled=1
   repo_gpgcheck=0
   gpgcheck=1
   gpgkey=https://dl.google.com/linux/linux_signing_key.pub
   EOF
   

2. Update the YUM cache to make sure that the new repository is recognized.

   sudo yum makecache
   

   Note: For the AlloyDB Omni RPM Preview release, package integrity is verified at the individual RPM level. To proceed with the YUM repository configuration, configure repo_gpgcheck=0 .
3. Install version 18 of the AlloyDB Omni RPM package.

   sudo dnf install -y alloydbomni18
   

6. Set up AlloyDB Omni

After you install the RPM package, you need to initialize, configure, and start the AlloyDB Omni database service.

1. Define a strong password for the PostgreSQL postgres administrator user.

   export PGPASSWORD="YourStrongPassword123!"
   

2. Initialize the AlloyDB Omni database instance.

   sudo PGPASSWORD=$PGPASSWORD PGDATA=$PGDATA /usr/lib/postgresql/18/bin/alloydbomni18-setup initdb
   

3. Configure SELinux file context to allow the AlloyDB Omni service to read and write data in your custom data directory, then restore the correct security context.

   sudo setenforce 0
   

4. Prepare the AlloyDB Omni database instance.

   sudo PGPASSWORD=$PGPASSWORD PGDATA=$PGDATA /usr/lib/postgresql/18/bin/alloydbomni18-setup preparedb
   

5. (Optional) For optimized execution of the AlloyDB Omni service, run the host setup utility to automatically configure recommended kernel and memory settings.

   sudo /usr/lib/postgresql/18/bin/alloydbomni18-setup-host
   

6. Enable and start the AlloyDB Omni systemd service.

   sudo systemctl enable alloydbomni18
   sudo systemctl start alloydbomni18
   

7. Verify that the AlloyDB Omni service is active and running successfully.

   sudo systemctl status alloydbomni18
   

   Verify that output indicating Active: active (running).

7. Verify AlloyDB Omni

To verify that your single-node AlloyDB Omni database is functioning correctly, connect to it using the standard PostgreSQL client (psql) installed with the package.

1. Connect to the local database instance as the postgres user. You are prompted for the password that you configured earlier.

   /usr/lib/postgresql/18/bin/psql -h localhost -U postgres -W
   

2. After the connection is established, run a basic SQL query to verify the database server version and to verify that AlloyDB Omni is running.

   postgres=# SELECT version();
   

   The resulting output indicates PostgreSQL 18 running with AlloyDB Omni.
3. Enter \q to exit the psql prompt.

8. Cleanup and Survey

After you finish the codelab, you can clean up the Google Cloud resources to avoid incurring unwanted charges.

1. Disconnect from your SSH session on the VM to return to your local Cloud Shell terminal.

   exit
   

2. Delete the Compute Engine VM instance.

   gcloud compute instances delete $INSTANCE_NAME --zone=$ZONE --project=$PROJECT --quiet
   

3. Delete the firewall rule created for SSH access.

   gcloud compute firewall-rules delete allow-ssh-alloydb-omni --project=$PROJECT --quiet
   

4. Delete the Cloud NAT gateway and Cloud Router.

   gcloud compute routers nats delete alloydb-omni-nat --router=alloydb-omni-router --region=$REGION --project=$PROJECT --quiet
   gcloud compute routers delete alloydb-omni-router --region=$REGION --project=$PROJECT --quiet
   

9. Congratulations

Congratulations on completing the codelab! You successfully deployed and configured AlloyDB Omni on a single Compute Engine virtual machine.

What we've covered

• How to provision and prepare a Compute Engine VM for AlloyDB Omni.
• How to configure the AlloyDB Omni package repository and install the RPMs.
• How to initialize, configure, and manage the AlloyDB Omni database service using systemd.
• How to verify the database functionality using standard PostgreSQL tools.

For more information, see the AlloyDB Omni overview.

10. Survey

How will you use this tutorial?

Only read through it Read it and complete the exercises