YugabyteDB

Sign in to the Azure portal and choose Create a resource. Search the Marketplace for YugabyteDB by SecureAnyCloud and select Create. Then work through the tabs:

• Basics: pick your subscription, resource group, region and size. Use Standard_B4ms or larger, because YugabyteDB needs at least 8 GiB of memory. Give it more for larger working sets.
• Administrator account: choose SSH public key and paste your key.
• Inbound port rules: allow SSH (22) only.
• Disks: the image's 40 GiB data disk (LUN 0) holds /var/lib/yugabyte. Make it as large as your data needs.

Choose Review + create, then Create. First boot takes about a minute once the VM is running.

# Accept the Marketplace terms once per subscription (required before the first CLI deployment)
az vm image terms accept --urn sac1647283583153:yugabytedb-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name yugabytedb \
  --image sac1647283583153:yugabytedb-ubuntu-24-04:default:latest \
  --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 create opens SSH (22) and nothing else. To make the data disk larger, resize it while the VM is deallocated. Then grow the file system once the VM is running again:

az vm deallocate --resource-group <your-rg> --name yugabytedb
az disk update --resource-group <your-rg> --name <data-disk-name> --size-gb 200
az vm start --resource-group <your-rg> --name yugabytedb
sudo resize2fs "$(findmnt -no SOURCE /var/lib/yugabyte)"

Connect over SSH as the administrator you chose at deployment:

ssh azureuser@<vm-public-ip>

Check that the address lookup, the first boot service, the master and the tablet server are all active:

systemctl is-active yugabytedb-address.service yugabytedb-firstboot.service yb-master.service yb-tserver.service

active active active active

Confirm that every YugabyteDB port listens on the loopback address and that only SSH is reachable from the network:

sudo ss -Htln | awk '{print $4}' | sort -V

0.0.0.0:22 127.0.0.1:5433 127.0.0.1:7000 127.0.0.1:7100 127.0.0.1:9000 127.0.0.1:9042 127.0.0.1:9100 127.0.0.1:12000 127.0.0.1:13000 127.0.0.53%lo:53 127.0.0.54:53 [::]:22

5433 is YSQL, 9042 is YCQL, 7100 and 9100 are the master's and tablet server's RPC ports, 7000 and 9000 their web consoles, and 13000 and 12000 the YSQL and YCQL metrics consoles. The port 53 lines are Ubuntu's local DNS resolver, also loopback only.

Next, use yb-admin, which connects over TLS with the VM's certificates, to show the master as the cluster's leader:

sudo -u yugabyte /opt/yugabyte/bin/yb-admin --master_addresses 127.0.0.1:7100 --certs_dir_name /etc/yugabyte/tls list_all_masters

Master UUID RPC Host/Port State Role Broadcast Host/Port 31f106e98b66484285455adf751ee3e9 127.0.0.1:7100 ALIVE LEADER 127.0.0.1:7100

Check that the cluster lives on the dedicated data disk:

lsblk -o NAME,SIZE,FSTYPE,LABEL,MOUNTPOINTS /dev/disk/azure/scsi1/lun0

NAME SIZE FSTYPE LABEL MOUNTPOINTS sdc 40G ext4 yugabyte-data /var/lib/yugabyte

The device name (sda, sdb or sdc) depends on the VM. /dev/disk/azure/scsi1/lun0 always points at the data disk.

Read your connection details from /root/yugabytedb-credentials.txt:

sudo grep -E '^YUGABYTEDB_(VERSION|YSQL_HOST|YSQL_PORT|YSQL_USER|YSQL_DATABASE|YCQL_PORT|YCQL_USER|TLS_CA)=' /root/yugabytedb-credentials.txt

YUGABYTEDB_VERSION=2025.2.8.0-b60 YUGABYTEDB_YSQL_HOST=127.0.0.1 YUGABYTEDB_YSQL_PORT=5433 YUGABYTEDB_YSQL_USER=yugabyte YUGABYTEDB_YSQL_DATABASE=yugabyte YUGABYTEDB_YCQL_PORT=9042 YUGABYTEDB_YCQL_USER=cassandra YUGABYTEDB_TLS_CA=/etc/yugabyte/tls/ca.crt

Print a password when you need it, for example for a client on your own computer:

sudo grep -E '^YUGABYTEDB_(YSQL|YCQL)_PASSWORD=' /root/yugabytedb-credentials.txt

yugabyte is the YSQL superuser and cassandra is the YCQL superuser. YUGABYTEDB_TLS_CA_SHA256 in the same file is the SHA-256 fingerprint of this VM's certificate authority. YUGABYTEDB_TLS_CERT_NAMES lists the names that the server certificate carries (127.0.0.1, localhost, the VM's private address, its public address when Azure reports one, and its name).

Clients trust the database through the certificate /etc/yugabyte/tls/ca.crt. Check its fingerprint:

sudo openssl x509 -in /etc/yugabyte/tls/ca.crt -outform DER | sha256sum | awk '{print $1}'

<YUGABYTEDB_TLS_CA_SHA256>

Run yb-ysqlsh to start ysqlsh (YugabyteDB's psql) as yugabyte against 127.0.0.1:5433. It verifies the server's certificate and passes the password in a temporary root-only file:

sudo yb-ysqlsh -c 'SELECT version();'
sudo yb-ysqlsh -c 'SELECT ssl, version, cipher FROM pg_stat_ssl WHERE pid = pg_backend_pid();'

version -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- PostgreSQL 15.12-YB-2025.2.8.0-b0 on x86_64-pc-linux-gnu, compiled by clang version 19.1.0 (https://github.com/yugabyte/llvm-project.git a2a6b655e14e7fa1fcf1011a6cb29cb8575249c0), 64-bit (1 row) ssl | version | cipher -----+---------+------------------------ t | TLSv1.3 | TLS_AES_256_GCM_SHA384 (1 row)

Create a table split into three tablets, load rows, then run an aggregation with a window function:

sudo yb-ysqlsh -c "CREATE TABLE IF NOT EXISTS orders (id bigint PRIMARY KEY, region text NOT NULL, amount numeric(10,2) NOT NULL) SPLIT INTO 3 TABLETS;"
sudo yb-ysqlsh -c "INSERT INTO orders SELECT g, (ARRAY['EMEA','APAC','AMER'])[1 + g % 3], round((g * 7.31)::numeric % 500, 2) FROM generate_series(1, 3000) AS g ON CONFLICT (id) DO NOTHING;"
sudo yb-ysqlsh -c "SELECT region, count(*) AS orders, sum(amount) AS revenue, rank() OVER (ORDER BY sum(amount) DESC) AS rank FROM orders GROUP BY region ORDER BY rank;"
sudo yb-ysqlsh -c "SELECT num_tablets, num_hash_key_columns FROM yb_table_properties('orders'::regclass);"

CREATE TABLE INSERT 0 3000 region | orders | revenue | rank --------+--------+-----------+------ APAC | 1000 | 250345.00 | 1 AMER | 1000 | 248655.00 | 2 EMEA | 1000 | 247465.00 | 3 (3 rows) num_tablets | num_hash_key_columns -------------+---------------------- 3 | 1 (1 row)

Run sudo yb-ysqlsh with no options for an interactive session (\q quits).

For applications, create a dedicated role instead of using yugabyte. In an interactive session run CREATE ROLE app LOGIN;, then \password app. You type the password at a prompt, and it is sent to the server already hashed. Then run the GRANT statements your application needs.

Run yb-ycqlsh to start ycqlsh as cassandra against 127.0.0.1:9042 over verified TLS. It passes the password in a temporary root-only file:

sudo yb-ycqlsh -e "CREATE KEYSPACE IF NOT EXISTS shop; CREATE TABLE IF NOT EXISTS shop.carts (user_id int, item text, qty int, PRIMARY KEY ((user_id), item)); INSERT INTO shop.carts (user_id, item, qty) VALUES (1, 'keyboard', 1); INSERT INTO shop.carts (user_id, item, qty) VALUES (1, 'mouse', 2);"
sudo yb-ycqlsh -e "SELECT * FROM shop.carts WHERE user_id = 1;"

user_id | item | qty ---------+----------+----- 1 | keyboard | 1 1 | mouse | 2 (2 rows)

For applications, create a dedicated role in an interactive sudo yb-ycqlsh session. Type CREATE ROLE app WITH PASSWORD = '<password>' AND LOGIN = true; at the prompt, not on a command line. Then GRANT the role the keyspaces it needs.

Drop the example table and keyspace:

sudo yb-ysqlsh -c "DROP TABLE IF EXISTS orders;"
sudo yb-ycqlsh -e "DROP TABLE IF EXISTS shop.carts; DROP KEYSPACE IF EXISTS shop;"

DROP TABLE

Every port listens on 127.0.0.1. From your computer, forward the ports you need over SSH:

ssh -N -L 5433:127.0.0.1:5433 -L 9042:127.0.0.1:9042 -L 7000:127.0.0.1:7000 -L 9000:127.0.0.1:9000 azureuser@<vm-public-ip>

Copy the VM's certificate authority to your computer once: scp azureuser@<vm-public-ip>:/etc/yugabyte/tls/ca.crt yugabytedb-ca.crt. Then connect with any PostgreSQL client or driver, or with cqlsh/ycqlsh and the Cassandra drivers:

psql "host=127.0.0.1 port=5433 user=yugabyte dbname=yugabyte sslmode=verify-full sslrootcert=yugabytedb-ca.crt" SSL_CERTFILE=yugabytedb-ca.crt ycqlsh --ssl -u cassandra 127.0.0.1 9042

Enter the passwords from Step 5 when prompted. The certificate lists 127.0.0.1, so sslmode=verify-full works through the tunnel.

The web consoles are YugabyteDB's master console at http://127.0.0.1:7000/ (cluster overview, tablet servers, tables and tablets) and the tablet server console at http://127.0.0.1:9000/.

The web consoles (ports 7000, 9000, 12000 and 13000) have no login of their own, so anyone with a shell on the VM can read them. That is why they listen on localhost only. Open them through the SSH tunnel above, and never expose ports 7000, 9000, 12000 or 13000 to a network. Give shell access to the VM only to people you would trust with the database.

The Tablet Servers page lists the VM's tablet server 127.0.0.1:9000 as ALIVE, with its tablet peers and leaders.

The Tables page shows each YSQL and YCQL table with its on-disk size. Here that is the orders table from Step 6 (database yugabyte) and the carts table from Step 7 (keyspace shop).

The tablet server console on port 9000 lists the tablets the server hosts, with their tables, hash partitions, state, Raft roles and on-disk sizes. Scroll right to see the last two.

If applications in your virtual network must connect without SSH, bind the client ports to all interfaces. TLS and password authentication stay enforced. YSQL accepts only TLS connections with SCRAM passwords and refuses plaintext, and YCQL refuses unencrypted connections. Edit /etc/yugabyte/tserver.conf:

sudo sed -i 's#^--pgsql_proxy_bind_address=127.0.0.1:5433$#--pgsql_proxy_bind_address=0.0.0.0:5433#' /etc/yugabyte/tserver.conf
sudo sed -i 's#^--cql_proxy_bind_address=127.0.0.1:9042$#--cql_proxy_bind_address=0.0.0.0:9042#' /etc/yugabyte/tserver.conf
sudo systemctl restart yb-tserver.service

Then allow TCP 5433 (and 9042 for YCQL) in the VM's NSG from your own network only, never from * or Internet:

az network nsg rule create --resource-group <your-rg> --nsg-name <your-nsg> \
  --name allow-ysql-from-office --priority 1010 --direction Inbound --access Allow \
  --protocol Tcp --destination-port-ranges 5433 --source-address-prefixes <your-cidr>

Clients in your virtual network connect to the VM's private address with the certificate authority from Step 9, for example psql "host=<vm-private-ip> port=5433 user=yugabyte dbname=yugabyte sslmode=verify-full sslrootcert=yugabytedb-ca.crt".

The certificate names only the addresses in YUGABYTEDB_TLS_CERT_NAMES (Step 5), which the VM had at first boot. A dynamic public IP changes when the VM is deallocated, so use sslmode=verify-ca if you connect by an address or name that the certificate does not carry. Keep the RPC ports (7100, 9100) and the consoles on localhost unless you are building a multi-node cluster.

To close access again, put the two lines back to 127.0.0.1, restart yb-tserver and delete the NSG rule.

Check that YugabyteDB and its first boot service cannot reach the Azure Instance Metadata Service (169.254.169.254) or the WireServer (168.63.129.16). systemd lists the blocked addresses in no fixed order, so this command sorts them:

for u in yb-master yb-tserver yugabytedb-firstboot; do printf '%s: ' "$u"; systemctl show -p IPAddressDeny --value "$u.service" | tr ' ' '\n' | sort | tr '\n' ' '; echo; done

yb-master: 168.63.129.16/32 169.254.169.254/32 ::ffff:168.63.129.16/128 ::ffff:169.254.169.254/128 fd00:ec2::254/128 yb-tserver: 168.63.129.16/32 169.254.169.254/32 ::ffff:168.63.129.16/128 ::ffff:169.254.169.254/128 fd00:ec2::254/128 yugabytedb-firstboot: 168.63.129.16/32 169.254.169.254/32 ::ffff:168.63.129.16/128 ::ffff:169.254.169.254/128 fd00:ec2::254/128

The image's own probe proves it from inside the tablet server's control group, with a loopback connection as the control. The Azure Linux Agent is not blocked, so the VM itself keeps working with Azure:

sudo bash -c 'echo $$ > /sys/fs/cgroup$(systemctl show -p ControlGroup --value yb-tserver.service)/cgroup.procs; exec setpriv --reuid=yugabyte --regid=yugabyte --init-groups /usr/local/sbin/sac-egress-probe yb-tserver.service'

EGRESS-PROBE yb-tserver.service loopback=REACHABLE imds4=TimeoutError imds4mapped=TimeoutError imds6=ENETUNREACH wireserver=TimeoutError wireservermapped=TimeoutError verdict=BLOCKED

Check the tablet server's effective settings: authentication on for both APIs, TLS between clients and servers and between the servers, unencrypted connections refused, call home off, and the client ports on localhost:

curl -s 'http://127.0.0.1:9000/varz?raw=1' | grep -E '^--(callhome_enabled|ysql_enable_auth|use_cassandra_authentication|use_client_to_server_encryption|use_node_to_node_encryption|allow_insecure_connections|pgsql_proxy_bind_address|cql_proxy_bind_address)='

--allow_insecure_connections=false --callhome_enabled=false --cql_proxy_bind_address=127.0.0.1:9042 --pgsql_proxy_bind_address=127.0.0.1:5433 --use_cassandra_authentication=true --use_client_to_server_encryption=true --use_node_to_node_encryption=true --ysql_enable_auth=true

Confirm that YugabyteDB runs unprivileged:

ps -o user:9=,comm= -u yugabyte | sort | uniq -c sudo grep -E '^(CapEff|NoNewPrivs)' /proc/$(systemctl show -p MainPID --value yb-tserver.service)/status

5 yugabyte postgres 1 yugabyte yb-master 1 yugabyte yb-tserver CapEff: 0000000000000000 NoNewPrivs: 1

Finally, run the image's own round trip. It checks that the per-VM passwords work over verified TLS and that an analytic query returns exact results. It also checks that yugabyte/yugabyte, cassandra/cassandra, the password-less postgres role, anonymous YCQL, blank, common and random passwords and plaintext connections are refused, and that every port is loopback only:

sudo /usr/local/sbin/yugabytedb-roundtrip.sh | tail -1

OK-yugabytedb-roundtrip

Change a password without putting it on a command line. Open a root shell and type the new password at a hidden prompt. read is a shell built-in, so the value never appears in the process list. Then hand the statement to the database on standard input, and write the password into the credentials file with shell built-ins so yb-ysqlsh keeps working:

sudo -i read -rs -p 'New YSQL password: ' NEWPW; echo printf "ALTER ROLE yugabyte WITH PASSWORD '%s';\n" "$NEWPW" | yb-ysqlsh -q -f - C=/root/yugabytedb-credentials.txt while IFS= read -r l; do case "$l" in YUGABYTEDB_YSQL_PASSWORD=*) printf 'YUGABYTEDB_YSQL_PASSWORD=%s\n' "$NEWPW" ;; *) printf '%s\n' "$l" ;; esac; done < "$C" > "$C.new" && chmod 600 "$C.new" && mv "$C.new" "$C" unset NEWPW; yb-ysqlsh -c 'SELECT 1;' && exit

For YCQL, put the statement in a temporary root-only file that ycqlsh reads:

sudo -i read -rs -p 'New YCQL password: ' NEWPW; echo
T=$(mktemp /run/ycql.XXXXXX); printf "ALTER ROLE cassandra WITH PASSWORD = '%s';\n" "$NEWPW" > "$T"; yb-ycqlsh -f "$T"; shred -u "$T" C=/root/yugabytedb-credentials.txt while IFS= read -r l; do case "$l" in YUGABYTEDB_YCQL_PASSWORD=*) printf 'YUGABYTEDB_YCQL_PASSWORD=%s\n' "$NEWPW" ;; *) printf '%s\n' "$l" ;; esac; done < "$C" > "$C.new" && chmod 600 "$C.new" && mv "$C.new" "$C" unset NEWPW; yb-ycqlsh -e 'SELECT release_version FROM system.local;' && exit

Use letters and digits, because a quote character would end the SQL string. The round trip (Step 11) expects 32-character passwords and keeps passing until you change them. The database itself accepts any length.

• Back up with Azure snapshots of the data disk (consistent when you stop yb-tserver and yb-master first), with a logical YSQL dump, or with YugabyteDB's own distributed snapshots. This image does not include the YB Controller backup daemon (see "What this image leaves out"), so yb-admin and ysql_dump are the backup tools. To dump the schema and data of the yugabyte database to a root-only file, run sudo yb-ysql-dump > /root/yugabyte-$(date +%F).sql. To take a distributed snapshot, kept on the data disk, run:

sudo -u yugabyte /opt/yugabyte/bin/yb-admin --master_addresses 127.0.0.1:7100 --certs_dir_name /etc/yugabyte/tls create_database_snapshot ysql.yugabyte
sudo -u yugabyte /opt/yugabyte/bin/yb-admin --master_addresses 127.0.0.1:7100 --certs_dir_name /etc/yugabyte/tls list_snapshots

To take an Azure snapshot of the data disk, run:

az snapshot create --resource-group <your-rg> --name yugabytedb-data-$(date +%F) --source <data-disk-name>

• Memory: YugabyteDB sizes its caches from the VM's memory at start (--use_memory_defaults_optimized_for_ysql). Choose a larger VM size for larger working sets, and restart both services after resizing.
• Logs: run sudo journalctl -u yb-tserver.service -n 50, and read the server logs in /var/lib/yugabyte/logs/master and /var/lib/yugabyte/logs/tserver.
• Configuration: the servers read their flags from /etc/yugabyte/master.conf and /etc/yugabyte/tserver.conf. Restart the service after a change. Keep --callhome_enabled=false, --allow_insecure_connections=false and the authentication flags as they are.
• Certificates: the certificate authority's key /etc/yugabyte/tls/ca.key stays on the VM (root only), so you can sign certificates for more nodes. The servers use node.127.0.0.1.crt and node.127.0.0.1.key.
• A data disk the VM did not create: first boot refuses to touch a data disk that already holds data it did not create, for example one restored from a snapshot of another VM. The database services stay stopped until first boot has finished. The reason is in journalctl -u yugabytedb-firstboot.service.
• Updates: Ubuntu security updates install automatically. YugabyteDB is installed from the vendor's tarball in /opt/yugabyte. Upgrade it deliberately by following YugabyteDB's manual upgrade procedure after taking a snapshot of the data disk, and keep to the v2025.2 LTS series for long-term support.