Quick start

You can test an EDB Postgres Distributed (PGD) cluster on your laptop or computer using EDB Postgres Distributed for Kubernetes on a single local Kubernetes cluster built with Kind .

Warning

These instructions are only for demonstration, testing, and practice purposes and must not be used in production.

This quick start shows you how to start an EDB Postgres Distributed cluster on your local Kubernetes installation so you can experiment with it.

Important

To connect to the Kubernetes cluster, make sure that you have kubectl installed on your machine. See the Kubernetes documentation on installing `kubectl <https://kubernetes.io/docs/tasks/tools/install-kubectl/>`_ .

Part 1 - Set up the local Kubernetes playground

Install Kind, a tool for running local Kubernetes clusters using Docker container nodes. (Kind stands for Kubernetes IN Docker.) If you already have access to a Kubernetes cluster, you can skip to Part 2.

Install Kind on your environment following the instructions in Kind Quick Start . Then, create a Kubernetes cluster:

kind create cluster --name pgd

Part 2 - Install EDB Postgres Distributed for Kubernetes

After you have a Kubernetes installation up and running on your laptop, you can install EDB Postgres Distributed for Kubernetes.

See Installation and upgrade for details.

Part 3 - Deploy a PGD cluster

As with any other deployment in Kubernetes, to deploy a PGD cluster you need to apply a configuration file that defines your desired PGDGroup resources that make up a PGD cluster.

Some sample files are included in the EDB CloudNativePG Global Cluster repository. The manifest contains the definition of a PGD cluster with two data groups and a global witness node spread across three regions. Each data group consists of two data nodes and a local witness node.

apiVersion: pgd.k8s.enterprisedb.io/v1beta1
kind: PGDGroup
metadata:
  name: region-a
spec:
  instances: 2
  proxyInstances: 2
  witnessInstances: 1
  pgd:
    parentGroup:
      name: world
      create: true
    discovery:
      - host: region-a-group
      - host: region-b-group
      - host: region-c-group
  cnp:
    storage:
      size: 1Gi
  connectivity:
    dns:
      additional:
        - domain: alternate.domain
        - domain: my.domain
          hostSuffix: -dc1
    tls:
      mode: verify-ca
      clientCert:
        caCertSecret: client-ca-key-pair
        certManager:
          spec:
            issuerRef:
              name: client-ca-issuer
              kind: Issuer
              group: cert-manager.io
      serverCert:
        caCertSecret: server-ca-key-pair
        certManager:
          spec:
            issuerRef:
              name: server-ca-issuer
              kind: Issuer
              group: cert-manager.io
- --
apiVersion: pgd.k8s.enterprisedb.io/v1beta1
kind: PGDGroup
metadata:
  name: region-b
spec:
  instances: 2
  proxyInstances: 2
  witnessInstances: 1
  pgd:
    parentGroup:
      name: world
    discovery:
      - host: region-a-group
      - host: region-b-group
      - host: region-c-group
  cnp:
    storage:
      size: 1Gi
  connectivity:
    tls:
      mode: verify-ca
      clientCert:
        caCertSecret: client-ca-key-pair
        certManager:
          spec:
            issuerRef:
              name: client-ca-issuer
              kind: Issuer
              group: cert-manager.io
      serverCert:
        caCertSecret: server-ca-key-pair
        certManager:
          spec:
            issuerRef:
              name: server-ca-issuer
              kind: Issuer
              group: cert-manager.io
- --
apiVersion: pgd.k8s.enterprisedb.io/v1beta1
kind: PGDGroup
metadata:
  name: region-c
spec:
  instances: 0
  proxyInstances: 0
  witnessInstances: 1
  pgd:
    parentGroup:
      name: world
    discovery:
      - host: region-a-group
      - host: region-b-group
      - host: region-c-group
  cnp:
    storage:
      size: 1Gi
  connectivity:
    tls:
      mode: verify-ca
      clientCert:
        caCertSecret: client-ca-key-pair
        certManager:
          spec:
            issuerRef:
              name: client-ca-issuer
              kind: Issuer
              group: cert-manager.io
      serverCert:
        caCertSecret: server-ca-key-pair
        certManager:
          spec:
            issuerRef:
              name: server-ca-issuer
              kind: Issuer
              group: cert-manager.io

You can deploy the flexible-3-regions example by saving it first and running:

kubectl apply -f flexible_3regions.yaml

You can check that the pods are being created using the get pods command:

kubectl get pods

The pods are being created as part of PGD nodes. As described in Architecture , they’re implemented on top of EDB CloudNativePG Cluster clusters.

You can list the clusters then, which shows the PGD nodes:

$ kubectl get clusters
NAME         AGE     INSTANCES   READY   STATUS                     PRIMARY
region-a-1   2m50s   1           1       Cluster in healthy state   region-a-1-1
region-a-2   118s    1           1       Cluster in healthy state   region-a-2-1
region-a-3   91s     1           1       Cluster in healthy state   region-a-3-1

Ultimately, the PGD nodes are created as part of the PGD groups that make up your PGD cluster.

$ kubectl get pgdgroups
NAME       DATA INSTANCES   WITNESS INSTANCES   PHASE                AGE
region-a   2                1                   PGDGroup - Healthy   4m50s
region-b   2                1                   PGDGroup - Healthy   4m50s
region-c   0                1                   PGDGroup - Healthy   4m50s

Notice how the region-c group is only a witness node.