Create and manage instances

Prerequisites

• You have a STACKIT customer account: Create a customer account
• You have a STACKIT user account: Create a user account
• You have a STACKIT project: Create a project

Instance properties

Independent of the method you choose to create and manage an instance, there are common properties of a PostgreSQL Flex instance.

Instance type

High availability is determined by the instance type and improved through horizontal scaling. Additionally, using a replica set ensures high availability.

Use case	Instance type
Development	Single (1 node)
Production (Normal)	Replica set (3 nodes)

You can up- and downgrade the PostgreSQL Flex instance anytime.

Flavor

Select the flavor that fits your workload. It’s safe to start with a smaller flavor and change to a bigger one afterwards. Depending on the instance type you have chosen, some flavors are not available. You can choose flavors from Tiny to X-Large, whereas every size has its CPU- or memory-optimized version. For a detailed reference of available flavors, read Flavors and performance classes of PostgreSQL Flex.

Performance class / storage class

With the performance class, you determine the properties of the underlying storage. This setting is completely independent of the flavor. The latter only affects CPU and RAM. For a detailed reference of available performance classes, read Flavors and performance classes of PostgreSQL Flex.

You can change the performance class with a clone only.

Disk size

With the disk size, you determine the initial size of the underlying storage. The default setting is 5 GB. You can safely apply this size and enlarge the disk afterwards.

You can’t shrink the PostgreSQL Flex disk size after creating the instance.

PostgreSQL version

With the PostgreSQL version select, you set which PostgreSQL version comes to play. STACKIT updates the PostgreSQL major version according to the releases of PostgreSQL, with a reasonable delay for implementing it. Read the Release notes for deprecation notices and announcements of new versions regularly. For safety reasons, STACKIT will deprecate PostgreSQL versions once they reach their EOL status. Furthermore, STACKIT applies minor updates for security reasons.

Daily backup schedule (UTC)

The system creates a daily snapshot of the database automatically. With this setting, you can control when this snapshot will be created. You can change it anytime.

ACL

With the ACL entries, you control which source IPs are allowed to connect to your instance. Note, that this is an additional security layer and does not replace the need for proper authentication and security best practices. There are two predefined entries: 193.148.160.0/19 and 45.129.40.0/21. They ensure that you can access your instance from STACKIT cloud services. If you want to access your instance from the public net, you need to add the client’s IPv4 address or subnet. The entries follow the CIDR notation. If you want to allow a single IP address (e.g. single host), then set 32as the subnet parameter. E.g. to allow a host with the source IPv4 address of 93.229.84.137, add 93.229.84.137/32 as ACL entry. At the moment, you can’t add IPv6 addresses.

Do not set 0.0.0.0/0 as an ACL IP, because then your instance can be accessed from every IP.

Create an instance

To create an instance, you first need to log into the STACKIT Portal.

STACKIT Portal

1. In the sidebar, click on PostgreSQL Flex.

2. In the bar on the top, click on Create PostgreSQL Flex.

   See Instance properties for a better understanding of all options.

3. After you configured everything to your needs, create your instance.

   For cost control, you can see a price estimation on the right hand site. To finally create the instance, click on Order fee-based. The system will add your newly created instance to the list of your PostgreSQL Flex instances. After a few seconds, your instance will change from Progressing… to Active. Congratulations, your PostgreSQL flex instance is up and running!

STACKIT CLI

Choose the flavor and storage class

First, determine which flavor and storage class you need. The available storage classes depend on the chosen flavor. To get a list of available flavors, execute stackit postgresflex options --flavors. Then you can get a list of available storage classes with stackit postgresflex options --storages --flavor-id <flavor-id>. To get the available storage classes for the flavor 4.32, execute:

stackit postgresflex options --storages --flavor-id 4.32

Choose the properties for your new instance

Flag	Options	Default	Optional
name	my-PostgreSQL-flex-instance
type	Single, replica, sharded	Replica	x
flavor-id	See Flavors and performance classes of PostgreSQL Flex
storage-class	See Flavors and performance classes of PostgreSQL Flex	premium-perf2-PostgreSQL	x
storage-size	Integer	10	x
version	7.0, 8.0	8.0	x
ACL	IPv4 and net in CIDR notation

You can also have a look at Flavors and performance classes of PostgreSQL Flex to learn more about the available flavors and performance classes.

You need to explicitly add the STACKIT networks 193.148.160.0/19 and 45.129.40.0/21 to your ACL to access your instance from other STACKIT services.

Execute the creation command

To create your instance, execute the following command:

stackit postgresflex instance create --name <name> --type <type> --flavor-id <flavor> --storage-class <storage-class> --storage-size <storage size> --version <version --acl <acl>

After executing the command, confirm with y.

When the instance is created succesfully, the CLI will return the instance ID:

Created instance for project "My-PostgreSQL-Project". Instance ID: 8db6a0f2-2b93-43f3-be54-464ee5a9fbed

Examples

Create an instance with minimum flags:

stackit postgresflex instance create --name my-PostgreSQL-instance --acl 193.148.160.0/19 --flavor-id 4.32

Create an instance with multiple entries in the ACL table:

stackit postgresflex instance create --name my-PostgreSQL-instance --acl 193.148.160.0/19,45.129.40.0/21,93.229.84.137/32 --flavor-id 4.32

Terraform

Choose the flavor and storage class

First, determine which flavor and storage class you need. The available storage classes depend on the chosen flavor. To get a list of available flavors, execute stackit postgresflex options --flavors. Then you can get a list of available storage classes with stackit postgresflex options --storages --flavor-id <flavor-id>. To get the available storage classes for the flavor 4.32, execute:

stackit postgresflex options --storages --flavor-id 4.32

Choose the properties for your new instance

Parameter	Options/Meaning	Default	Optional
name	my-postgresql-instance
type	Single, replica, sharded	Replica
flavor	See Flavors and performance classes of PostgreSQL Flex
storage	See Flavors and performance classes of PostgreSQL Flex	premium-perf2-PostgreSQL
version	18.0	18.0	x
acl	IPv4 and net in CIDR notation
database	Name of the primary database of the user
username	Name of the user
roles	readWrite, Read

Terraform is a descriptive method of deploying. Thus you configure the target state of your instance including databases and users. Terraform then decides, whether it needs to create, delete or edit any resources.

1. Verify, that Terraform or Opentofu is installed:

   terraform --version

   You get something like:

   Terraform v1.15.8
   on darwin_arm64

2. Create a folder for your Terraform project and change to that directory.

   mkdir stackit-terraform-postgresql
   cd stackit-terraform-postgresql

3. Copy your service account key file into the folder and rename it to service-account-key.json. This guide assumes that your downloaded key account file is in your download folder and has the name sa-key-ee76107b-8923-4661-9ae6-27417d5004f0.json. Change the next command according to your local environment.

   mv ~/Downloads/sa-key-ee76107b-8923-4661-9ae6-27417d5004f0.json ./service-account-key.json

4. Create main.tf.

   terraform {
       required_providers {
           stackit = {
               source  = "stackitcloud/stackit"
               version = "~> 0.30.0"  # Verwende die neueste Version
           }
       }
   }
   
   provider "stackit" {
       service_account_key_path = "./service-account-key.json"
       region = "eu01"
   }
   
   resource "stackit_postgresqlflex_instance" "example" {
       project_id = var.project_id
       name       = "my-postgresql-instance"
   
       acl = [
           "193.148.160.0/19",
           "45.129.40.0/21"
       ]
   
       backup_schedule = "0 2 * * *"  # Daily at 2am.
   
       flavor = {
           cpu          = 1
           ram          = 4
       }
   
       storage = {
           class = "premium-perf6-postgresql"
           size  = 5
       }
   
       version = "18.0"
   
       replicas = 1
   
       options = {
           type                       = "Single"
       }
   }
   
   resource "stackit_postgresql_user" "example_user" {
       project_id  = var.project_id
       instance_id = stackit_postgresqlflex_instance.example.instance_id
       username    = "myuser"
       database    = "default"
       roles       = ["readWrite"]
   }

   You can also have a look at Flavors and performance classes of PostgreSQL Flex to learn more about the available flavors and performance classes.

   You need to explicitly add the STACKIT networks 193.148.160.0/19 and 45.129.40.0/21 to your ACL to access your instance from other STACKIT services.

5. Create variables.tf.

   variable "project_id" {
       description = "STACKIT Project ID"
       type        = string
   }

6. Create terraform.tfvars.

   project_id = "<PROJECT_ID>"

7. Execute.

   terraform plan
   terraform apply

8. Check the output.

   You get something like this:

   ...
   
   Do you want to perform these actions?
   Terraform will perform the actions described above.
   Only 'yes' will be accepted to approve.
   
   Enter a value: yes
   
   stackit_postgresqlflex_instance.example: Creating...
   stackit_postgresqlflex_instance.example: Still creating... [10s elapsed]
   stackit_postgresqlflex_instance.example: Still creating... [20s elapsed]
   stackit_postgresqlflex_instance.example: Still creating... [30s elapsed]
   stackit_postgresqlflex_instance.example: Still creating... [40s elapsed]
   stackit_postgresqlflex_instance.example: Still creating... [50s elapsed]
   stackit_postgresqlflex_instance.example: Still creating... [1m0s elapsed]
   stackit_postgresqlflex_instance.example: Still creating... [1m10s elapsed]
   stackit_postgresqlflex_instance.example: Still creating... [1m20s elapsed]
   stackit_postgresqlflex_instance.example: Still creating... [1m30s elapsed]
   stackit_postgresqlflex_instance.example: Still creating... [1m40s elapsed]
   stackit_postgresqlflex_instance.example: Creation complete after 1m42s [id=118e6780-c9d0-48d0-87a3-044fe90c17c4,4cf6f720-1524-40dc-b76f-64e6533b1453]
   stackit_postgresqlflex_user.example_user: Creating...
   stackit_postgresqlflex_user.example_user: Creation complete after 1s [id=118e6780-c9d0-48d0-87a3-044fe90c17c4,4cf6f720-1524-40dc-b76f-64e6533b1453,8f1b5a44-5e10-4a3b-86ab-5377cfb711df]
   
   Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

View an instance

STACKIT Portal

1. In the sidebar, click on PostgreSQL Flex.
2. Click on the instance you’d like to view.

STACKIT CLI

To view an instance, execute with the following parameters:

Argument	Description
INSTANCE_ID	Instance ID of the instance you want to query

stackit postgresflex instance describe <INSTANCE_ID>

Example output:

 ID                    │ 8db6a0f2-2b93-43f3-be54-464ee5a9fbed
───────────────────────┼──────────────────────────────────────
 NAME                  │ my-PostgreSQL-instance
───────────────────────┼──────────────────────────────────────
 STATUS                │ READY
───────────────────────┼──────────────────────────────────────
 STORAGE SIZE (GB)     │ 10
───────────────────────┼──────────────────────────────────────
 VERSION               │ 8.0
───────────────────────┼──────────────────────────────────────
 ACL                   │ 93.229.84.137/32,93.229.85.0/24
───────────────────────┼──────────────────────────────────────
 FLAVOR DESCRIPTION    │ Medium, Memory optimized
───────────────────────┼──────────────────────────────────────
 TYPE                  │ Replica
───────────────────────┼──────────────────────────────────────
 REPLICAS              │ 3
───────────────────────┼──────────────────────────────────────
 CPU                   │ 4
───────────────────────┼──────────────────────────────────────
 RAM (GB)              │ 32
───────────────────────┼──────────────────────────────────────
 BACKUP SCHEDULE (UTC) │ 0 0/6 * * *

Terraform

Terraform is a descriptive method of deploying. Thus you configure the target state of your instance including databases and users. Terraform then decides, whether it needs to create, delete or edit any resources. Refer to the Terraform tab in Create an instance for deploying with Terraform.

Edit an instance

STACKIT Portal

To edit the Performance class, the Disk size, the PostgreSQL version and ACLs:

1. In the sidebar, click on PostgreSQL Flex.
2. Click on the instance you’d like to edit.
3. Next to General information, click on Edit.
4. Make the changes according to your needs and click on Save.
5. Wait for the database to become Active again.

To change the flavor:

1. In the sidebar, click on PostgreSQL Flex.
2. Click on the instance you’d like to edit.
3. In the sidebar, click on Flavor.
4. In the desired flavor pane, click on Change.
5. Confirm the price and click on Order fee-based.
6. Wait for the database to become Active again.

To change the backup schedule:

1. In the sidebar, click on PostgreSQL Flex.
2. Click on the instance you’d like to edit.
3. In the sidebar, click on Backups.
4. In the top right pane, click on Schedule.
5. Make the desired changes and click on Save.

For further information about changing the backup schedule, read Backup, restore and clone PostgreSQL Flex

STACKIT CLI

You can edit the following properties of an instance: acl, backup-schedule, cpu, flavor-id, name, ram, storage-class, storage-size, type and version. To get a reference to these flags, have a look at Create an instance.

The PostgreSQL Flex instance type and the storage size can only be upgraded.

To get a deeper understanding on the backup schedule, read Backup, restore, and clone PostgreSQL Flex

Argument	Description
INSTANCE_ID	Instance ID of the instance you want to query

Flags	Datatype	Unit
acl	Array of strings
backup-schedule	String
CPU	Integer	virtual core
flavor-id	String	-
name	String	-
ram	Integer	Gigabyte
storage-class	String	-
storage-size	Integer	Gigabyte
type	String	-
version	String	-

To edit the instance, execute the following command:

stackit postgresflex instance update <INSTANCE_ID> --<Flag Name> <Flag Value>

Example

stackit postgresflex instance update 8db6a0f2-2b93-43f3-be54-464ee5a9fbed --flavor-id 2.16

Terraform

Terraform is a descriptive method of deploying. Thus you configure the target state of your instance including databases and users. Terraform then decides, whether it needs to create, delete or edit any resources. Refer to the Terraform tab in Create an instance for deploying with Terraform.

Delete an instance

STACKIT Portal

You can delete an instance when it operates in its Active state. You cannot undo a deletion.

1. In the sidebar, click on PostgreSQL Flex.
2. In the pane of the instance you want to delete, click on the three-dots icon.
3. Click on Delete.
4. Enter the name of the instance and confirm with Delete.

STACKIT CLI

You can delete an instance when it operates in its READY-state. After executing this command, the operation cannot be undone. To delete an instance, execute:

Argument	Description
INSTANCE_ID	Instance ID of the instance you want to query

stackit postgresflex instance delete <INSTANCE_ID>

You get the following output:

Deleted instance "my-PostgreSQL-instance"

Terraform

Terraform is a descriptive method of deploying. Thus you configure the target state of your instance including databases and users. Terraform then decides, whether it needs to create, delete or edit any resources. Refer to the Terraform tab in Create an instance for deploying with Terraform.