Skip to main content
Version: Develop

Using a8s PostgreSQL

This chapter describes how to interact with a8s PostgreSQL using the Kubernetes API.

Pre-requisite​

  • kubectl

  • Data Service Custom Resources

    Before using the a8s PostgreSQL service, ensure the necessary custom resources are present in your Kubernetes cluster. Use the following commands to verify their existence:

    kubectl get postgresqlinstances.anynines.com

    kubectl get servicebindings.anynines.com

    kubectl get backups.anynines.com

    kubectl get restores.anynines.com

    If you encounter the following error:

    error: the server doesn't have a resource type "<resource-name>"

    This indicates that the corresponding resource is missing. To resolve this, you can follow the instructions here or reach out to a platform operator for assistance.

Create a PostgreSQL Service Instance​

To provision a PostgreSQL Service Instance, simply create a PostgreSQL Kubernetes Object by applying a Service Instance Claim.

Replace the placeholder values denoted by < > in the provided yaml file. Kindly select one of the supported values for spec.service and spec.plan. The supported values for service and plan can be found here.

The expose field is optional and allows you to control how the service is exposed:

  • Use LoadBalancer to expose the service externally (default behavior).
  • Use Internal to keep the service accessible only within the cluster.

Optional: To set up a clustered PostgreSQL with small specifications, apply the yaml manifest provided in the Example tab below. Feel free to modify the fields in order to create a different type of PostgreSQL database tailored to your requirements.

  apiVersion: anynines.com/v1
  kind: PostgresqlInstance
  metadata:
    name: <name>
    namespace: <namespace>
  spec:
    service: <service-name>
    plan: <plan-name>
    # expose is Optional, with the default value set to 'LoadBalancer'
    expose: <LoadBalancer|Internal>      
    compositionRef:
      name: a8s-postgresql

Applying this Kubernetes yaml manifest is as straightforward as working with any default Kubernetes resource.

kubectl apply -f <filename.yaml>

After applying the manifest, please allow some time for the remote resources to be deployed. If you've deployed the provided example, you should observe an output similar to the following:

kubectl get postgresqlinstances.anynines.com
NAME                          SYNCED   READY   CONNECTION-SECRET   AGE
example-a8s-postgresql        True     True                        9m

You can also obtain additional information about the status of PostgreSQL Objects using the following command:

kubectl describe postgresqlinstances.anynines.com
Name:         example-a8s-postgresql
Namespace:    default
...
Status:
  Conditions:
    Last Transition Time:  <timestamp>
    Reason:                ReconcileSuccess
    Status:                True
    Type:                  Synced
    Last Transition Time:  <timestamp>
    Reason:                Available
    Status:                True
    Type:                  Ready
  Managed:
    Cluster Status:  Running
    Ready Replicas:  1
info

No postgreSQL pod is running locally in the App Cluster.

Behind the scenes the Custom Resources synced up to the a8s Data Service Control Plane which ensures the database is provisioned and healthy. The status information reflecting the database status synced back to the App Cluster to signify service readiness.

Configuring Extensions in a PostgreSQL Database (Optional)​

You can configure a PostgreSQL database with extensions as needed. See the full list of supported PostgreSQL extensions here.

The following example demonstrates how to enable them:

  apiVersion: anynines.com/v1
  kind: PostgresqlInstance
  metadata:
    name: <name>
    namespace: <namespace>
  spec:
    service: <service-name>
    plan: <plan-name>
    parameters:
      <extension-key1>: <value>
      <extension-key2>: <value>
      <extension-key3>: <value>
    compositionRef:
      name: a8s-postgresql

Then, apply this yaml file using the same method described here.

Bind an Application to a PostgreSQL Database​

The ServiceBinding Custom Resource is all that you need to quickly start using the database. To target a specific PostgreSQL instance, set the spec.instanceRef field.

Optional: If you've followed the example from the previous step, where we create a PostgreSQL Kubernetes Object, you can now proceed to apply the yaml manifest provided in the Example tab below. This will bind the previously created PostgreSQL instance.

  apiVersion: anynines.com/v1
  kind: ServiceBinding
  metadata:
    name: <name>
    namespace: <namespace>
  spec:
    instanceRef: <postgresql-instance-name>
    serviceInstanceType: postgresql
    compositionRef:
      name: a8s-servicebinding

After the ServiceBinding becomes ready (typically in seconds), the Data Service automation creates two resources in the same namespace: a Secret named {service-binding-name}-service-binding and a ConfigMap named {service-binding-name}-connection. The Secret contains the required database credentials, while the ConfigMap holds the port and the name of the primary pod. You can retrieve this information by describing the respective Kubernetes resources.

For example, if you've already applied the provided examples, once the ServiceBinding is successfully deployed, you can access the credentials and network details by describing the corresponding Kubernetes Secret and ConfigMap using the following commands:

kubectl get secret example-a8s-postgresql-service-binding -o yaml

Example output:

apiVersion: v1
data:
  database: <base64 encoded value>
  instance_service: <base64 encoded value>
  password: <base64 encoded value>
  username: <base64 encoded value>
...
kubectl get configmap example-a8s-postgresql-connection -o yaml

Example output:

apiVersion: v1
data:
  port: "5432"
  primary: example-a8s-postgresql-master.default
...

Backup a PostgreSQL Database​

The a9s platform provides an easy way to create backups and restore if needed. You can use the Kubernetes Custom Resources Backup and BackupPolicy from the anynines.com API group.

You have two options:

  1. Manual Backups: Use the Backup resource to create a one-time backup.
  2. Scheduled Backups: Use the BackupPolicy resource to define automated, recurring backups.

One-Time Backup​

To trigger a manual backup, target the specific Data Service Instance using the Backup resource as shown below:

  apiVersion: anynines.com/v1
  kind: Backup
  metadata:
    name: <name>
    namespace: <namespace>
  spec:
    instanceRef: <postgresql-instance-name>
    serviceInstanceType: postgresql
    compositionRef:
      name: a8s-backup

And then apply the yaml manifest:

kubectl apply -f <filename.yaml>

You can inspect the status of the backup to determine when it is complete, similar to how we did it for the PostgreSQL instance, using the following command:

kubectl get backup.anynines.com -o yaml

Example output:

apiVersion: anynines.com/v1
kind: Backup
...
status:
    ...
  managed:
    ...
      conditions:    
      - lastTransitionTime: "<timestamp>"
        message: Backup Completed
        reason: Complete
        status: "True"
        type: Complete

Scheduled Backups​

To set up automated, recurring backups, you can define a BackupPolicy.

  apiVersion: anynines.com/v1
  kind: BackupPolicy
  metadata:
    name: <policy-name>
    namespace: <namespace>
  spec:
    enabled: true
    scheduleConfig:
      type: "Cron"
      cron:
        expression: "<cron-expression>"
    backupOptions:
      maxRetries: "<retry-count>"
    retentionConfig:
      count: <number-of-backups-to-keep>
    instanceRef: <postgresql-instance-name>
    serviceInstanceType: postgresql
    # Optional: If omitted, defaults to 'a8s-backup'
    compositionRef:
      name: a8s-backup-policy

Field Descriptions

  • enabled: Activates the backup policy. If set to false, no backups will be created.
  • scheduleConfig:
    • type: "Cron" – Defines the scheduling method. Currently, only Cron expressions are supported.
    • cron.expression: A Cron expression that sets the backup schedule. For example, "*/5 * * * *" triggers a backup every 5 minutes.
  • backupOptions.maxRetries: Sets how many times a backup attempt is retried if it fails.
  • retentionConfig.count: Specifies how many backups to keep. Once this number is reached, the oldest backup is deleted automatically.

Restore a PostgreSQL Database Backup​

To restore a backup, you must apply a Restore from the API group anynines.com, targeting an existing PostgreSQL Backup. Below is the yaml file you can utilize for this purpose:

  apiVersion: anynines.com/v1
  kind: Restore
  metadata:
    name: <name>
  spec:
      backupRef: <backup-name>
      serviceInstanceType: postgresql
      compositionRef:
        name: a8s-restore

And then apply the yaml manifest:

kubectl apply -f <filename.yaml>

You can inspect the status of the restore with the following command:

kubectl get restore.anynines.com -o yaml
apiVersion: v1
items:
- apiVersion: anynines.com/v1
  kind: Restore
  ...
  status:
      ...
    managed:
      ...
      conditions:
      - lastTransitionTime: "<timestamp>"
        message: Restore completed
        reason: StatusPoll
        status: "True"
        type: Complete

Delete PostgreSQL Kubernetes Custom Resources​

Delete the Custom Resources using the kubectl delete command. Replace <resource-type> with the actual resource type and <resource-name> with the name of the Custom Resource you want to delete.

kubectl delete <resource-type> <resource-name>

Alternatively, you can use the following command to delete Custom Resources by specifying the filename of the yaml manifest:

kubectl delete -f <filename.yaml>