Install AlloyDB Omni on a VM

Note: Your use of AlloyDB Omni is subject to the agreement between you and Google that governs Google Cloud offerings. If you do not have a Google Cloud account, or have not otherwise entered into an agreement with Google that governs Google Cloud offerings, please do not proceed or download this software until you have done so. To create a Google Cloud account, see the Google Cloud homepage.

This page describes how to perform single instance installations of AlloyDB Omni on any Linux VM that supports container runtimes. If you need a multi-instance configuration of AlloyDB Omni, see High availability and data resilience.

Before you begin

Before you install AlloyDB Omni on your VM, do the following:

1. Read Plan your AlloyDB Omni installation on a VM.
2. Read Run AlloyDB Omni rootful or rootless and complete any necessary steps for rootful or rootless depending on which environment you choose.

Run AlloyDB Omni rootful or rootless

You can run AlloyDB Omni using either Docker or Podman. Both of these container engines can be run as rootful or rootless. Rootful refers to running Docker or Podman as the root user, while rootless refers to running them as a non-root, or unprivileged, user.

The mode you choose depends on the requirements and preferences you have for the environment. If simplicity is important, then rootful might be right for you. If you need the security of an unprivileged user, then rootless might be the right choice.

If you decide to run a rootful environment, you need to decide how to manage the user mapping between the container and your host machine. In practice, AlloyDB Omni runs processes as the postgres user, which has a UID and GID of 999. This means that you have two options to manage the user mapping:

• Do nothing. postgres will continue to not map to any user on your host machine.
• Create a user and user group with UID and GID of 999 so that postgres maps to that user and user group.

For rootless environments, postgres maps to a sub-UID and sub-GID that the host user and user group have access to (as defined in your /etc/subuid and /etc/subgid files). This means that you don't need to manage the user mapping.

Tip: For Linux command examples, # indicates running the command as root, while $ indicates running the command as an unprivileged user.

(Rootless) Configure sub-UID and sub-GID ranges

If your Linux image doesn't already have sub-UID and sub-GID ranges configured for your unprivileged user, then you must configure them to run AlloyDB Omni rootless.

1. If you are on a Debian system, install newuidmap and newgidmap binaries.

   apt-get install -y uidmap
   

2. Add a subuid entry for your rootless user.

   echo "ROOTLESS_USER:SUB_UID_RANGE_START:SUB_UID_RANGE_COUNT" >> /etc/subuid
   

   Replace the following variables:

   • ROOTLESS_USER: User that you want to run AlloyDB Omni as.
   • SUB_UID_RANGE_START: Lower number of the range of sub-UIDs you want to register for your user.
   • SUB_UID_RANGE_COUNT: Amount of sub-UIDs you want to register for your user. This value must be at least 999.

3. Add a subgid entry for your rootless user.

   echo "ROOTLESS_USER:SUB_GID_RANGE_START:SUB_GID_RANGE_COUNT" >> /etc/subgid
   

   Replace the following variables:

   • ROOTLESS_USER: User that you want to run AlloyDB Omni as.
   • SUB_GID_RANGE_START: Lower number of the range of sub-GIDs you want to register for your user.
   • SUB_GID_RANGE_COUNT: Amount of sub-GIDs you want to register for your user. This value must be at least 999.

4. If you are using Docker, run the following command as ROOTLESS_USER.

   /usr/bin/dockerd-rootless-setuptool.sh install 
   

5. If you are using Podman, let your user run services while not logged in.

   loginctl enable-linger ROOTLESS_USER
   

   Replace the following variable:

   • ROOTLESS_USER: User that you want to run AlloyDB Omni as.

6. Open a new shell so that the sub-UID and sub-GID changes take effect.

Create directory where AlloyDB Omni stores data

If you're using a storage system that does more than just run AlloyDB Omni, you can create the AlloyDB Omni directory on your device's existing file system. Otherwise, you can create a new file system on your dedicated device.

Existing file system

Docker

mkdir -p DATA_DIR

Docker

mkdir -p DATA_DIR

Podman

mkdir -p DATA_DIR

Podman

mkdir -p DATA_DIR

Replace the following variables:

• DATA_DIR: Host directory path that your data is stored in.

Dedicated device

1. Create a directory on the host where the disk will be mounted.

   mkdir -p MOUNT_POINT
   

   Replace the following variable:

   • MOUNT_POINT: Top-level directory path that should contain your AlloyDB Omni instance.

2. Create a gpt partition table with a single partition on the disk device.

   parted -s DEVICE_PATH mklabel gpt
   parted -s DEVICE_PATH mkpart primary 0% 100%

   Replace the following variable:

   • DEVICE_PATH: Path assigned by the operating system to the disk device.

3. Create a file system on the disk device. We recommend using the ext4 file system for AlloyDB Omni.

   mkfs.ext4 -q -m 1 -L FS_LABEL -F PARTITION_PATH
   

   Replace the following variables:

   • FS_LABEL: Label for the file system. The maximum length of an ext4 file system label is 16 characters.
   • PARTITION_PATH: Path for the disk partition used to store the container's data.

4. Mount the device and create an entry in the /etc/fstab file so that the disk is mounted after a reboot.

   echo -e "LABEL=FS_LABEL\tMOUNT_POINT\text4\tdefaults\t0 0" | tee -a /etc/fstab
   systemctl daemon-reload
   mount MOUNT_POINT

   Replace the following variables:

   • FS_LABEL: Label for the file system. The maximum length of an ext4 file system label is 16 characters.
   • MOUNT_POINT: Top-level directory path that should contain your AlloyDB Omni instance.

5. Create a data directory in the container specific file system.

   Rootful

   mkdir -p DATA_DIR
   

   Rootless

   mkdir -p DATA_DIR
   chown ROOTLESS_USER:ROOTLESS_GROUP DATA_DIR

   Replace the following variables:

   • DATA_DIR: Host directory path that your data is stored in.
   • ROOTLESS_USER: If you're using a rootless environment, then this is the user that you want to own the directory.
   • ROOTLESS_GROUP: If you're using a rootless environment, then this is the group that you want to own the directory.

Create the container

Docker

docker run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
-v DATA_DIR:/var/lib/postgresql/data \
-p HOST_PORT:5432 \
--restart=always \
google/alloydbomni:latest

Docker

docker run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
-v DATA_DIR:/var/lib/postgresql/data \
-p HOST_PORT:5432 \
--restart=always \
google/alloydbomni:latest

Podman

podman run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
-v DATA_DIR:/var/lib/postgresql/data \
-p HOST_PORT:5432 \
--restart=always \
docker.io/google/alloydbomni:latest

Podman

podman run -d --name CONTAINER_NAME \
-e POSTGRES_PASSWORD=NEW_PASSWORD \
-v DATA_DIR:/var/lib/postgresql/data \
-p HOST_PORT:5432 \
--restart=always \
docker.io/google/alloydbomni:latest

Replace the following variables:

• CONTAINER_NAME: Name you used for the directory in Create directory where AlloyDB Omni stores data.
• NEW_PASSWORD: Password assigned to the new container's postgres user after its creation.
• DATA_DIR: Host directory path that your data is stored in.
• HOST_PORT: TCP port on the host machine that the container should publish its own port 5432 to. To use the PostgreSQL default port on the host machine as well, specify 5432.

Connect to your instance

Depending on your environment, you can connect to your AlloyDB Omni instance either locally or remotely.

Connect locally

Docker

docker exec -it CONTAINER_NAME psql -U postgres

Docker

docker exec -it CONTAINER_NAME psql -U postgres

Podman

podman exec -it CONTAINER_NAME psql -U postgres

Podman

podman exec -it CONTAINER_NAME psql -U postgres

Replace the following variable:

• CONTAINER_NAME: Name you used for the directory in Create directory where AlloyDB Omni stores data.

Connect remotely

psql -U postgres -p HOST_PORT -h IP_ADDRESS_OR_FQDN

Replace the following variables:

• HOST_PORT: TCP port you used in Create the container.
• IP_ADDRESS_OR_FQDN: IP address or fully-qualified domain name for the host where AlloyDB Omni is running.

After running this command, you're asked for the password of the postgres account. Enter the password you used in Create the container.

What's next

• Customize your AlloyDB Omni installation