PostgreSQL

This section explains how to provision an AWS RDS PostgreSQL database using Klutch. It outlines the required and optional fields, important considerations when requesting a PostgreSQL instance, and provides examples to guide developers through the provisioning process.

Using Klutch to Provision an AWS RDS PostgreSQL Instance

Once the prerequisites are met, developers can request the provisioning of a PostgreSQL instance through Klutch.

To create a PostgreSQL database, use the PostgreSQLInstance claim template. You can refer to the examples below to understand how to define the required fields and customize optional settings.

Template

  apiVersion: rds.aws.anynines.com/v1
  kind: PostgresqlInstance
  metadata:
    name: "pg-db"
    namespace: "default"
  spec:
    # High-level plan and version selection
    serviceVersion: "17.4"
    plan: "single-nano"

    config:
      # Placement and scaling
      region: "eu-central-1"   #aws regions 
      publiclyAccessible: true

      tags:
        environment: "development"

      # Database details
      database:
        name: "hospital"

      # Compute and storage options
      compute:
        replicas:
          count: 2          # Number of read replicas (compatible with cluster plans only)
        allocatedStorage: 20    # GiB
        encryptedStorage: true   

Deploy the resource:

kubectl apply -f <your-file-name>

Basic Instance Example

  cat <<'EOF' > basic-instance-example.yaml
    apiVersion: rds.aws.anynines.com/v1
    kind: PostgresqlInstance
    metadata:
      name: example-instance
    spec:
      serviceVersion: "16.5"
      plan: "single-nano"
  EOF

Deploy the resource:

kubectl apply -f basic-instance-example.yaml

Clustered Instance Example

  cat <<'EOF' > clustered-example.yaml
    apiVersion: rds.aws.anynines.com/v1
    kind: PostgresqlInstance
    metadata:
      name: example-instance
    spec:
      serviceVersion: "17.5"
      plan: "cluster-nano"
      config:
        multiAZ: true
        compute:
          # If replica count is not set then it defaults to 1
          replicas:
            count: 2
        tags:
          env: dev
  EOF

Deploy the resource:

kubectl apply -f clustered-instance-example.yaml

What Klutch does:

The Klutch control plane provisions a PostgreSQL instance in the specified region. The AWS name for instance is derived from the PostgreSQLInstance claim name, with a unique suffix appended to ensure uniqueness and prevent naming collisions.

Check that the instance was created successfully:

kubectl get postgresqlinstances.rds.aws.anynines.com

Example output:

NAME                     SYNCED   READY   CONNECTION-SECRET     AGE
example-basic-instance   True     True                          10s

info

The CONNECTION-SECRET field remains empty because Klutch generates connection credentials via ServiceBinding resources.

If you want to see more details about the resource (e.g. the actual name of instance on AWS) you can use the command below and look for the status field.

kubectl describe postgresqlinstances.rds.aws.anynines.com example-basic-instance

Expand for more details about the PostgreSQLInstance's spec required fields

Field	Type	Description	Example Values
serviceVersion	string	Specifies the version of the service in major.minor format	17.5
plan	string	Specifies the combined compute and database configuration plan for the service	single-nano, cluster-nano

The table below show details about plan field:

Available Service Plans	Service Plan Details
single-nano	allocatedStorage: 20 (in GiB), storageType: gp2, instanceClass: db.t4g.micro
single-small	allocatedStorage: 40, storageType: gp2, instanceClass: db.t4g.small
single-medium	allocatedStorage: 100, storageType: gp2, instanceClass: db.t4g.medium
single-large	allocatedStorage: 200, storageType: gp2, instanceClass: db.t4g.xlarge

note

In addition to the single service plans, there are four cluster-based plan options: cluster-nano, cluster-small, cluster-medium, and cluster-large. The service plan specifications are identical to those of the single-node plans, with the exception of the replica field, which specifies the number of read-only replicas. Details of the replica field are provided in the Optional Fields table.

Expand for more details about the PostgreSQLInstance's spec optional fields

Field	Type	Description	Example Values
config.region	string	The region the PostgreSQL instance will be deployed to. The default region value is eu-central-1.	eu-central-1
config.publiclyAccessible	boolean	Indicates whether the service is accessible from the public internet. Default value is true.	true
config.multiAZ	boolean	Specifies if the Primary PostgreSQL instance is in multi-AZ. Default value is false.	true
config.tags	object	A key-value pair applied to a resource to hold metadata about that resource.	- env: "dev"
config.parameterGroup	object	Configures PostgreSQL runtime parameters such as connection and memory settings. For details, see Configure Parameter Groups.	maxConnections: 300
config.database.name	string	Specifies the name of the database. This value defaults to the claim name. It is not allowed to change the name of the database once set.	"hospital"
config.compute.replicas.count	integer	Specifies the number of service instance replicas to run for scaling and high availability. This value defaults to 1 if a cluster plan is used.	1
config.compute.allocatedStorage	integer	Specifies the allocated storage in gibibytes.	20
config.compute.storageType	string	Specified the type of storage. You can choose storage type from following types: standard, gp2, gp3, io1, io2	gp2
config.compute.encryptedStorage	boolean	Specifies whether the DB instance is encrypted. Default value is true.	true
config.compute.instanceClass	string	The instance type of the RDS instance. For detail on available options visit here	db.t4g.micro
config.versionUpgradePolicy.autoMinorUpgrade	boolean	Indicates that minor engine upgrades will be applied automatically to the DB instance during the maintenance window. Default value is true.	true
config.versionUpgradePolicy.allowMajorUpgrade	boolean	Indicates that major version upgrades are allowed. Changing this parameter does not cause downtime; the permission is updated asynchronously. Default value is false.	true
config.versionUpgradePolicy.maintenanceWindow	string	The window to perform maintenance in. Syntax: "ddd:hh24:mi-ddd:hh24:mi".	"Mon:00:00-Mon:03:00"
config.networking.subnetGroup.name	string	Specifies the name of the subnet.	default

Limitations

note

For cluster plans (cluster-*), Klutch sets the AWS RDS backupRetentionPeriod on the primary instance to 1 day by default to ensure replica provisioning works reliably.

To retain backups for longer periods, configure a ScheduledBackup resource and set spec.retentionDays to your required value. For examples, see Backup and Restore.

note

Restore plan behavior differs by restore mode:

• For point-in-time restore (PITR), no restore plan is required.
• For restore from backup (backupName or backupARN), fromBackup.plan is required and must be equal to or greater than the plan of the source primary instance.

Cleanup

To remove the PostgreSQLInstance resource, use the standard kubectl delete postgresqlinstances.rds.aws.anynines.com <resource-name> command. If you deployed the example manifests, run the following commands to delete the corresponding objects.

To delete the instance:

kubectl delete postgresqlinstances.rds.aws.anynines.com example-instance