YugabyteDB on Ubuntu 24.04 on Azure User Guide

Overview

YugabyteDB is an open-source, distributed SQL database built for resilience, horizontal scalability and geo-distribution. It exposes two APIs over the same storage engine: YSQL, a fully PostgreSQL-compatible relational API on port 5433, and YCQL, a Cassandra-compatible API on port 9042. The cloudimg image installs YugabyteDB 2025.2.3.2 to /opt/yugabyte, runs it as a single standalone node via the bundled yugabyted node manager (which starts the master, the tserver and the web UI) under a dedicated yugabyte system user, binds the web UIs to loopback behind an nginx reverse proxy on TCP 80 with HTTP Basic auth, enables YSQL password authentication, persists all cluster data on a dedicated Azure data disk, and generates a unique password on the first boot of every VM. Backed by 24/7 cloudimg support.

What is included:

• YugabyteDB 2025.2.3.2 (single-node standalone via yugabyted) at /opt/yugabyte
• The PostgreSQL-compatible YSQL API on 5433 and the Cassandra-compatible YCQL API on 9042
• The yugabyted web UI and the master admin UI, fronted by nginx on :80 with HTTP Basic auth
• YSQL password authentication enabled, with a per-VM password for the yugabyte superuser in a root-only file
• A dedicated Azure data disk at /var/lib/yugabyte holding all cluster data, WAL and metadata — separate from the OS disk and re-provisioned with every VM
• yugabyted.service + nginx.service as systemd units, enabled and active
• The bundled ysqlsh and ycqlsh command-line clients
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Standard_B4ms (4 vCPU / 16 GiB RAM) is a good starting point; scale up for higher throughput. NSG inbound: allow 22/tcp from your management network, 80/tcp for the web UI, and — for remote database clients — 5433/tcp (YSQL) and 9042/tcp (YCQL). Front public exposure with TLS (see Enabling TLS).

Step 1 — Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for YugabyteDB by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). Review the dedicated data disk on the Disks tab, then Review + create → Create. After deployment, add NSG rules for 5433 and 9042 if you need remote client access.

Step 2 — Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name yugabytedb \
  --image <marketplace-image-urn> \
  --size Standard_B4ms \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name yugabytedb --port 80 --priority 1010
az vm open-port --resource-group <your-rg> --name yugabytedb --port 5433 --priority 1020
az vm open-port --resource-group <your-rg> --name yugabytedb --port 9042 --priority 1030

Step 3 — Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 — Confirm the services are running

systemctl is-active yugabyted.service nginx.service

Both services report active. YugabyteDB starts in under a minute and is ready to accept YSQL and YCQL traffic.

Step 5 — Retrieve your password

The password is generated uniquely on the first boot of your VM and written to a root-only file:

sudo cat /root/yugabytedb-credentials.txt

This file contains YUGABYTEDB_YSQL_USER (yugabyte), YUGABYTEDB_YSQL_PASSWORD, and YUGABYTEDB_WEB_USER (admin), plus the URLs for the web UI and the client connection strings. The same password authenticates both the YSQL superuser and the web UI. Store it somewhere safe.

Step 6 — Check the health endpoint

nginx serves an unauthenticated health endpoint for load balancers and probes:

curl -s http://localhost/health

It returns ok.

Step 7 — Open the web UI

Browse to http://<vm-public-ip>/ and sign in as admin with the password from Step 5. The yugabyted dashboard shows the node's overview — status, version, vCPU usage, tablet counts and live key metrics.

The master admin UI at http://<vm-public-ip>/master/ reports the cluster overview — universe UUID, replication factor, the running version and the master node:

The master UI's Tablet Servers view lists each node with its read/write throughput and tablet peers:

The master UI's Tables view lists the YSQL and system tables on the cluster:

Step 8 — Connect with ysqlsh

The image ships the bundled PostgreSQL-compatible client. Connect on the loopback YSQL listener using the password from Step 5:

PW=<YUGABYTEDB_YSQL_PASSWORD>
PGPASSWORD=$PW /opt/yugabyte/bin/ysqlsh -h 127.0.0.1 -p 5433 -U yugabyte -d yugabyte -c "SELECT version();"

The response reports the running PostgreSQL-compatible server version that YSQL emulates.

Step 9 — Create a table and query it

YugabyteDB speaks standard PostgreSQL SQL. Create a small table, insert a row, and read it back:

PW=<YUGABYTEDB_YSQL_PASSWORD>
PGPASSWORD=$PW /opt/yugabyte/bin/ysqlsh -h 127.0.0.1 -p 5433 -U yugabyte -d yugabyte -c "CREATE TABLE IF NOT EXISTS device_metrics (device_id TEXT NOT NULL, region TEXT NOT NULL, temperature DOUBLE PRECISION, ts TIMESTAMPTZ NOT NULL DEFAULT now(), PRIMARY KEY (device_id, ts));"
PGPASSWORD=$PW /opt/yugabyte/bin/ysqlsh -h 127.0.0.1 -p 5433 -U yugabyte -d yugabyte -c "INSERT INTO device_metrics (device_id, region, temperature) VALUES ('device-1','eastus',23.5);"
PGPASSWORD=$PW /opt/yugabyte/bin/ysqlsh -h 127.0.0.1 -p 5433 -U yugabyte -d yugabyte -c "SELECT device_id, region, temperature, ts FROM device_metrics ORDER BY ts DESC LIMIT 5;"

Because every table is sharded into tablets and replicated by the YugabyteDB storage engine, the same data is durable and horizontally scalable as you add nodes.

Step 10 — Use the YCQL (Cassandra) API

YugabyteDB also exposes a Cassandra-compatible API on port 9042, sharing the same underlying distributed storage as YSQL — so you can pick the API that best fits each workload. Confirm the YCQL listener is accepting connections:

nc -z -v 127.0.0.1 9042

Connect interactively with the bundled ycqlsh client (run it from an interactive shell): /opt/yugabyte/bin/ycqlsh 127.0.0.1 9042, then run CQL such as DESCRIBE KEYSPACES;. Any Cassandra driver or cqlsh-compatible client can also connect to port 9042.

Step 11 — Connect a remote client

To reach YSQL from another host, open 5433 (and 9042 for YCQL) in the NSG (Step 2) and connect with any PostgreSQL client using the yugabyte user and the per-VM password. From your workstation (with psql installed), run:

PGPASSWORD=<YUGABYTEDB_YSQL_PASSWORD> psql -h <vm-public-ip> -p 5433 -U yugabyte -d yugabyte -c "SELECT 1;"

The yugabyte superuser and the per-VM password are the same credentials shown in /root/yugabytedb-credentials.txt.

Step 12 — Confirm data lives on the dedicated disk

All cluster data is stored on the dedicated Azure data disk so it survives OS changes and can be resized independently:

findmnt /var/lib/yugabyte

The mount is backed by a separate Azure data disk captured into the image and re-provisioned on every VM.

Enabling TLS

The nginx reverse proxy terminates plain HTTP on port 80 for the web UI, and YSQL/YCQL accept plain client connections by default. For public exposure, add a DNS name for the VM and either use the companion cloudimg nginx-ssl-certbot image as a TLS reverse proxy, or install certbot and extend the nginx site with a listen 443 ssl; server block. For database client traffic, enable YugabyteDB's node-to-client encryption and require SSL on the YSQL listener. Keep the web UIs bound to loopback so the only public surface is the authenticated, TLS-terminated proxy.

Maintenance

• Configuration: the yugabyted start flags (including --base_dir and ysql_enable_auth) are set in /etc/systemd/system/yugabyted.service. Edit it, run sudo systemctl daemon-reload, and sudo systemctl restart yugabyted to apply changes.
• Backups: snapshot the /var/lib/yugabyte data disk, or use YugabyteDB's ysql_dump / distributed backup tooling to copy data to Azure Blob Storage.
• Upgrades: replace the distribution under /opt/yugabyte with a newer release and restart the service.
• Security patches: unattended-upgrades remains enabled so the OS continues to receive security updates automatically.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.

YugabyteDB is a trademark of Yugabyte, Inc. This image is produced by cloudimg and is not affiliated with or endorsed by Yugabyte, Inc. YugabyteDB is distributed under the Apache License 2.0.