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:
- Read Plan your AlloyDB Omni installation on a VM.
- 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 thatpostgres
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.
(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.
If you are on a Debian system, install
newuidmap
andnewgidmap
binaries.apt-get install -y uidmap
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.
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.
If you are using Docker, run the following command as ROOTLESS_USER.
/usr/bin/dockerd-rootless-setuptool.sh install
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.
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
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.
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.
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 anext4
file system label is 16 characters.PARTITION_PATH
: Path for the disk partition used to store the container's data.
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 anext4
file system label is 16 characters.MOUNT_POINT
: Top-level directory path that should contain your AlloyDB Omni instance.
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'spostgres
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 port5432
to. To use the PostgreSQL default port on the host machine as well, specify5432
.
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.