Configuration

This chart is built around managing each pgEdge node as a CloudNativePG Cluster.

The chart contains a default clusterSpec in values.yaml which defines the required configuration for deploying pgEdge with CloudNativePG, including:

• deploying with the pgEdge Enterprise Postgres Images.
• loading and initializing required extensions for pgEdge Distributed Postgres.
• setting up required PostgreSQL configuration parameters.
• configuring client certificate authentication for managed users (app, admin, streaming_replica).
• allowing local connections for the app and admin users for testing / development purposes.

The simplest example values file, which deploys a single primary instance for each node, looks like this:

pgEdge:
  appName: pgedge
  nodes:
    - name: n1
      hostname: pgedge-n1-rw
    - name: n2
      hostname: pgedge-n2-rw
    - name: n3
      hostname: pgedge-n3-rw
  clusterSpec:
    storage:
      size: 1Gi

Each node in the nodes list supports the following properties:

As shown, The default clusterSpec can be overridden for all nodes with specific configuration required for your Kubernetes setup.

You can also override the clusterSpec for specific nodes if you require more granular control.

For example, to create a 3-node cluster with 3 instances on node n1 and single instances on nodes n2 and n3, you could use:

pgEdge:
  appName: pgedge
  nodes:
    - name: n1
      hostname: pgedge-n1-rw
      clusterSpec:
        instances: 3
        postgresql:
          synchronous:
            method: any
            number: 1
            dataDurability: required
    - name: n2
      hostname: pgedge-n2-rw
    - name: n3
      hostname: pgedge-n3-rw

This override behavior is enabled via mergeOverwrite in Helm. You should be mindful that lists are replaced, not merged.

If you override a list in the clusterSpec for a node, you must include all required elements in that list, pulling from the values file example, and using helm template to verify your configuration.

For more information about configuring CloudNativePG, see the CloudNativePG documentation.

Users and authentication

The chart creates several PostgreSQL roles, each with a specific purpose. Role management is built on top of CloudNativePG's PostgreSQL Role Management roles and Bootstrap configuration.

Customizing the database name and owner

The default application database is named app with an app owner. To use a different name, set pgEdge.clusterSpec.bootstrap.initdb.database and pgEdge.clusterSpec.bootstrap.initdb.owner:

pgEdge:
  clusterSpec:
    bootstrap:
      initdb:
        database: mydb
        owner: myuser

When changing the database or owner name, you must also override pg_hba and pg_ident to match, since these are plain values that cannot reference other values:

    postgresql:
      pg_hba:
        - hostssl mydb pgedge 0.0.0.0/0 cert
        - hostssl mydb admin 0.0.0.0/0 cert
        - hostssl mydb myuser 0.0.0.0/0 cert
        - hostssl all streaming_replica all cert map=cnpg_streaming_replica
      pg_ident:
        - local postgres admin
        - local postgres myuser

The client certificate for the owner (app-client-cert secret) will automatically use the correct commonName for the new owner.

Customizing the admin role

To change the admin role name, set pgEdge.adminUser and update the managed role definition to match:

pgEdge:
  adminUser: dbadmin
  clusterSpec:
    managed:
      roles:
        - name: dbadmin
          ensure: present
          comment: Admin role
          login: true
          superuser: true

The adminUser value must match a role defined in managed.roles with superuser: true. As with the database name, you must also update pg_hba and pg_ident to reference the new admin name.

Creating additional users

Additional users can be created using CloudNativePG's managed roles:

pgEdge:
  clusterSpec:
    managed:
      roles:
        - name: admin
          ensure: present
          login: true
          superuser: true
        - name: readonly
          ensure: present
          login: true
          superuser: false

New roles need corresponding pg_hba entries to connect. Add them to the pg_hba list in your values file.

Password authentication

By default, CloudNativePG generates a unique password for each managed user on each node, stored in a secret named pgedge-n#-<username>. This means the app user will have a different password on pgedge-n1 than on pgedge-n2.

If your application needs a consistent password across all nodes, you can pre-create a Kubernetes secret with the desired password and reference it in the role definition using passwordSecret. See the CloudNativePG managed roles documentation for details.

The pg_hba rules in this chart only allow cert authentication for remote connections, so passwords are only usable via local connections (e.g., kubectl cnpg psql). To fully disable password-based login for a managed role, set disablePassword: true in the role definition:

pgEdge:
  clusterSpec:
    managed:
      roles:
        - name: admin
          ensure: present
          login: true
          superuser: true
          disablePassword: true

Spock configuration

This chart contains a job to initialize Spock multi-master replication across all nodes once they are all available.

This job runs by default, waiting for any clusters associated with the current deployment to be ready before performing initialization.

If you wish to disable this behavior, you can set pgEdge.initSpock to false.

snowflake.node and lolor.node

This chart automatically configures snowflake.node and lolor.node based on the name property of each node.

For example, a node named n1 will have the following Postgres configuration applied to the node to ensure snowflake and lolor are configured appropriately:

  postgresql:
    parameters:
      lolor.node: "1"
      snowflake.node: "1"

If you wish to override this behavior, or plan to utilize alternate naming schemes for your node, you can set the ordinal property for each node:

pgEdge:
  appName: pgedge
  nodes:
    - name: a
      hostname: pgedge-a-rw
      ordinal: 1
    - name: b
      hostname: pgedge-b-rw
      ordinal: 2
    - name: c
      hostname: pgedge-c-rw
      ordinal: 3
  clusterSpec:
    storage:
      size: 1Gi

Extensions

This chart supports all extensions included in the standard flavor of the pgEdge Enterprise Postgres Image.

By default, shared_preload_libraries contains pg_stat_statements, snowflake, and spock. For additional extensions, you may need to override postgresql.shared_preload_libraries and set additional parameters in postgresql.parameters in your values.yaml to ensure the extension is loaded and configured properly.

output_plugin_libraries and older PostgreSQL minor versions

PostgreSQL 16.15, 17.11, 18.6, and newer minor versions add a new output_plugin_libraries allow-list that gates which logical decoding output plugins a server accepts. Its built-in default is pgoutput, test_decoding, which does not include spock_output. Without it on the list, Spock cannot create its replication slot and replication stops on the provider node.

This chart sets postgresql.parameters.output_plugin_libraries to pgoutput, test_decoding, spock_output by default, so that Spock keeps working once a node is running one of the patched minor versions. Since the chart defaults to a mutable image tag, a fresh install picks up a patched version automatically.

If you pin clusterSpec.imageName to a minor version older than the patched ones, override the parameter to null at the chart-wide level in your values file rather than removing the line:

pgEdge:
  clusterSpec:
    postgresql:
      parameters:
        output_plugin_libraries: null

A YAML value of null here deletes the corresponding key before Helm ever renders the manifest, so the parameter is omitted entirely rather than sent through as an empty string. If you need additional output plugins beyond spock_output, override the parameter with the full list you need instead of unsetting it.

Values reference

You can customize this Helm chart by specifying configuration parameters in your values.yaml file.

The following table lists all available options and their descriptions.