Deploy PostgreSQL

This guide shows you how to use PostgreSQL, a powerful, open source object-relational database system.

To run it, follow these steps:

1. Install the kraft CLI tool and a container runtime engine, e.g. Docker.

2. Clone the examples repository and cd into the examples/postgres/ directory:

git clone https://github.com/kraftcloud/examples
cd examples/postgres/

Make sure to log into KraftCloud by setting your token and a metro close to you. We use fra0 (Frankfurt, 🇩🇪) in this guide:

# Set KraftCloud access token
export KRAFTCLOUD_TOKEN=token
# Set metro to Frankfurt, DE
export KRAFTCLOUD_METRO=fra0

When done, invoke the following command to deploy this application on KraftCloud:

kraft cloud deploy -e POSTGRES_PASSWORD=unikraft -p 5432:5432/tls -M 1024 .

The output shows the instance URL and other details:

[●] Deployed successfully!
 │
 ├────────── name: postgres-saan9
 ├────────── uuid: 3a1371f2-68c6-4187-84f8-c080f2b028ca
 ├───────── state: starting
 ├────────── fqdn: young-thunder-fbafrsxj.fra0.kraft.host
 ├───────── image: postgres@sha256:2476c0373d663d7604def7c35ffcb4ed4de8ab231309b4f20104b84f31570766
 ├──────── memory: 1024 MiB
 ├─ service group: young-thunder-fbafrsxj
 ├── private fqdn: postgres-saan9.internal
 ├──── private ip: 172.16.3.1
 └────────── args: wrapper.sh docker-entrypoint.sh postgres

In this case, the instance name is postgres-saan9 and the service group young-thunder-fbafrsxj. They are different for each run.

To test the deployment, first forward the port with the kraft cloud tunnel command. Be sure to use the service group returned by the kraft cloud deploy command:

kraft cloud tunnel young-thunder-fbafrsxj 5432:5432

Now, on a separate console, you can query PostgreSQL using psql. We assume the username is postgres and the password is unikraft:

psql -U postgres -h localhost

Use the unikraft password at the password prompt. You should see output similar to:

Password for user postgres:
psql (15.5 (Ubuntu 15.5-0ubuntu0.23.04.1), server 16.2)
WARNING: psql major version 15, server major version 16.
         Some psql features might not work.
Type "help" for help.

postgres=#

Use SQL and psql commands for your work.

To disconnect, simply kill the tunnel command with ctrl-C

Note

We use kraft cloud tunnel only when a service doesn’t support TLS and is not HTTP-based (we use TLS/SNI to determine the correct instance to send traffic to). Also note that tunnel command is not needed when connecting via an instance’s private IP/FQDN, ie, when a Postgre instance is used as a backend to another instance that acts as a frontend and which does support TLS.

At any point in time, you can list information about the instance:

kraft cloud instance list

NAME              FQDN                                         STATE    CREATED AT     IMAGE                                                      MEMORY   ARGS                                      BOOT TIME
postgres-saan9    young-thunder-fbafrsxj.fra0.kraft.host       running  6 minutes ago  razvan.unikraft.io/postgres@sha256:2476c0373d663d7604d...  1.0 GiB  wrapper.sh docker-entrypoint.sh postgres  603.42 ms

When done, you can remove the instance:

kraft cloud instance remove postgres-saan9

Note

PostgreSQL doesn’t currently support scale to 0. It’s work in progress.

Using Volumes

You can use volumes for data persistence for you PostgreSQL instance.

For that you would first create a volume:

kraft cloud volume create --name postgres --size 200

Then start the PostgreSQL instance and mount that volume:

kraft cloud deploy -e POSTGRES_PASSWORD=unikraft -e PGDATA=/volume/postgres -v postgres:/volume -p 5432:5432/tls -M 1024 .

Customize Your Deployment

Your deployment is a standard PostgreSQL installation. Customizing the deployment generally means providing a different environment.

An obvious one is to use a different database password when starting PostgreSQL. For that you use a different POSTGRES_PASSWORD environment variable when starting the PostgreSQL instance.

You could also use a different port or a different location to mount your volume.

And, of course, you can use the PostgreSQL instance in conjunction with a frontend service, see the guide here.

Learn More

Use the --help option for detailed information on using KraftCloud:

kraft cloud --help

Or visit the CLI Reference.