### Cluster Configuration Example

Source: https://cloudnative-pg.io/docs/assets/files/cluster-example-custom-94f5966f5354a7bcfe71245cdd76bd08.yaml

This example demonstrates the creation of a PostgreSQL cluster with custom configurations for instances, PostgreSQL parameters, pg_hba, primary update strategy, and storage.

```APIDOC
## POST /websites/cloudnative-pg_io/cluster

### Description
Creates a new PostgreSQL cluster with specified configurations.

### Method
POST

### Endpoint
/websites/cloudnative-pg_io/cluster

### Request Body
- **apiVersion** (string) - Required - The API version for the cluster resource.
- **kind** (string) - Required - The type of resource, which is 'Cluster'.
- **metadata** (object) - Required - Metadata for the cluster.
  - **name** (string) - Required - The name of the cluster.
- **spec** (object) - Required - Specification for the cluster.
  - **instances** (integer) - Required - The number of PostgreSQL instances.
  - **postgresql** (object) - Optional - PostgreSQL specific configurations.
    - **parameters** (object) - Optional - PostgreSQL configuration parameters.
      - **max_worker_processes** (string) - Optional - Maximum number of worker processes.
    - **pg_hba** (array) - Optional - pg_hba configuration rules.
      - (object) - Required - A single pg_hba rule.
        - **host** (string) - Required - Host specification.
        - **all** (string) - Required - Database specification.
        - **all** (string) - Required - User specification.
        - **all** (string) - Required - Address specification.
        - **md5** (string) - Required - Authentication method.
  - **primaryUpdateStrategy** (string) - Optional - Strategy for primary node updates (e.g., 'unsupervised', 'supervised').
  - **storage** (object) - Optional - Storage configuration.
    - **size** (string) - Required - The size of the storage for each instance (e.g., '1Gi').

### Request Example
```json
{
  "apiVersion": "postgresql.cnpg.io/v1",
  "kind": "Cluster",
  "metadata": {
    "name": "cluster-example-custom"
  },
  "spec": {
    "instances": 3,
    "postgresql": {
      "parameters": {
        "max_worker_processes": "60"
      },
      "pg_hba": [
        {
          "host": "all",
          "all": "all",
          "all": "all",
          "all": "md5"
        }
      ]
    },
    "primaryUpdateStrategy": "unsupervised",
    "storage": {
      "size": "1Gi"
    }
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the cluster creation.
- **message** (string) - A confirmation message.

#### Response Example
```json
{
  "status": "success",
  "message": "Cluster cluster-example-custom created successfully."
}
```
```

--------------------------------

### POST /websites/cloudnative-pg_io

Source: https://cloudnative-pg.io/docs/assets/files/cluster-example-security-context-27443290bd04e25fd8e1d5121a7386be.yaml

This example demonstrates how to customize both PodSecurityContext and Container SecurityContext for a PostgreSQL cluster. This is particularly useful when working with Pod Security Standards (PSS) or when you need to meet specific security requirements.

```APIDOC
## POST /websites/cloudnative-pg_io

### Description
This example demonstrates how to customize both PodSecurityContext and Container SecurityContext for a PostgreSQL cluster. This is particularly useful when working with Pod Security Standards (PSS) or when you need to meet specific security requirements.

### Method
POST

### Endpoint
/websites/cloudnative-pg_io

### Parameters
#### Request Body
- **apiVersion** (string) - Required - Specifies the API version for the PostgreSQL cluster resource.
- **kind** (string) - Required - Specifies the type of resource, which is 'Cluster' for PostgreSQL.
- **metadata** (object) - Required - Contains metadata for the cluster, including its name.
  - **name** (string) - Required - The name of the PostgreSQL cluster.
- **spec** (object) - Required - Contains the specification for the PostgreSQL cluster.
  - **instances** (integer) - Required - The number of PostgreSQL instances in the cluster.
  - **storage** (object) - Required - Defines the storage configuration for the cluster.
    - **size** (string) - Required - The size of the storage for each instance (e.g., '1Gi').
  - **podSecurityContext** (object) - Optional - Custom PodSecurityContext to be applied to all pods in the cluster.
    - **runAsUser** (integer) - Optional - The user ID to run the pods as.
    - **runAsGroup** (integer) - Optional - The group ID to run the pods as.
    - **fsGroup** (integer) - Optional - The group ID for the volume mounts.
    - **runAsNonRoot** (boolean) - Optional - Ensures pods run as a non-root user.
    - **supplementalGroups** (array) - Optional - A list of supplemental group IDs.
    - **fsGroupChangePolicy** (string) - Optional - Policy for changing fsGroup ownership.
  - **securityContext** (object) - Optional - Custom Container SecurityContext to be applied to all containers in the cluster pods.
    - **allowPrivilegeEscalation** (boolean) - Optional - Disallows privilege escalation.
    - **capabilities** (object) - Optional - Defines capabilities for the container.
      - **drop** (array) - Optional - Capabilities to drop from the container.
      - **add** (array) - Optional - Capabilities to add to the container.
    - **privileged** (boolean) - Optional - Whether the container runs in privileged mode.
    - **readOnlyRootFilesystem** (boolean) - Optional - Makes the root filesystem read-only.
    - **runAsNonRoot** (boolean) - Optional - Ensures containers run as a non-root user.

### Request Example
```json
{
  "apiVersion": "postgresql.cnpg.io/v1",
  "kind": "Cluster",
  "metadata": {
    "name": "cluster-security-context"
  },
  "spec": {
    "instances": 3,
    "storage": {
      "size": "1Gi"
    },
    "podSecurityContext": {
      "runAsUser": 26,
      "runAsGroup": 26,
      "fsGroup": 26,
      "runAsNonRoot": true,
      "supplementalGroups": [
        1000,
        2000
      ],
      "fsGroupChangePolicy": "OnRootMismatch"
    },
    "securityContext": {
      "allowPrivilegeEscalation": false,
      "capabilities": {
        "drop": [
          "ALL"
        ],
        "add": [
          "NET_BIND_SERVICE"
        ]
      },
      "privileged": false,
      "readOnlyRootFilesystem": true,
      "runAsNonRoot": true
    }
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the cluster creation.
- **message** (string) - A message describing the result of the operation.

#### Response Example
```json
{
  "status": "Success",
  "message": "PostgreSQL cluster 'cluster-security-context' created successfully."
}
```
```

--------------------------------

### Deploy PostGIS Cluster and Database with CNPG

Source: https://cloudnative-pg.io/docs/assets/files/postgis-example-665c2f2b838079a6eacc66697cab07a5.yaml

This configuration defines a PostgreSQL cluster using the PostGIS image and a database resource that automatically installs essential PostGIS extensions like postgis, postgis_topology, and fuzzystrmatch.

```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: postgis-example
spec:
  instances: 1
  imageName: ghcr.io/cloudnative-pg/postgis:18-3.6-system-trixie
  storage:
    size: 1Gi
  postgresql:
    parameters:
      log_statement: ddl
---
apiVersion: postgresql.cnpg.io/v1
kind: Database
metadata:
  name: postgis-example-app
spec:
  name: app
  owner: app
  cluster:
    name: postgis-example
  extensions:
  - name: postgis
  - name: postgis_topology
  - name: fuzzystrmatch
  - name: postgis_tiger_geocoder
```

--------------------------------

### Define External SQL Resources for Initialization

Source: https://cloudnative-pg.io/docs/assets/files/cluster-example-initdb-sql-refs-34070647c762ef482998cdcc955435dd.yaml

ConfigMaps and Secrets are used to store SQL scripts that can be referenced by the CloudNativePG cluster during the initialization phase. These resources allow for modular management of database setup scripts.

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: post-init-sql-configmap
data:
  configmap.sql: |
    create table configmaps (i integer);
    insert into configmaps (select generate_series(1,10000));
---
apiVersion: v1
kind: Secret
metadata:
  name: post-init-sql-secret
stringData:
  secret.sql: |
    create table secrets (i integer);
    insert into secrets (select generate_series(1,10000));
```

--------------------------------

### Configuring Cluster Initialization SQL

Source: https://cloudnative-pg.io/docs/assets/files/cluster-example-initdb-sql-refs-34070647c762ef482998cdcc955435dd.yaml

This snippet demonstrates how to configure the `bootstrap.initdb.postInitSQL`, `postInitTemplateSQL`, `postInitApplicationSQL`, and `postInitApplicationSQLRefs` fields within a CloudNativePG `Cluster` resource to run custom SQL during database initialization.

```APIDOC
## CloudNativePG Cluster Initialization with SQL

### Description
This section details how to configure a CloudNativePG `Cluster` resource to execute custom SQL scripts during the bootstrap process. This includes running inline SQL, SQL from ConfigMaps, and SQL from Secrets.

### Method
N/A (Kubernetes Resource Definition)

### Endpoint
N/A (Kubernetes Resource Definition)

### Parameters
#### Cluster Resource Specification (`spec`)
- **bootstrap.initdb.database** (string) - Optional - The name of the database to create. Defaults to `postgres`.
- **bootstrap.initdb.owner** (string) - Optional - The name of the user to own the database. Defaults to `postgres`.
- **bootstrap.initdb.postInitSQL** (array of strings) - Optional - An array of SQL commands to execute after the database is created and the owner is set. Each string is a SQL command.
- **bootstrap.initdb.postInitTemplateSQL** (array of strings) - Optional - An array of SQL commands to execute after `postInitSQL`. These commands are executed within the context of the `template1` database.
- **bootstrap.initdb.postInitApplicationSQL** (array of strings) - Optional - An array of SQL commands to execute after `postInitTemplateSQL`. These commands are executed within the context of the application database.
- **bootstrap.initdb.postInitApplicationSQLRefs** (object) - Optional - References to SQL scripts stored in ConfigMaps and Secrets.
  - **configMapRefs** (array of objects) - Optional - References to ConfigMaps containing SQL scripts.
    - **name** (string) - Required - The name of the ConfigMap.
    - **key** (string) - Required - The key within the ConfigMap that holds the SQL script.
  - **secretRefs** (array of objects) - Optional - References to Secrets containing SQL scripts.
    - **name** (string) - Required - The name of the Secret.
    - **key** (string) - Required - The key within the Secret that holds the SQL script.

### Request Example
```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example-initdb
spec:
  instances: 3
  bootstrap:
    initdb:
      database: appdb
      owner: appuser
      postInitSQL:
        - create table numbers (i integer)
        - insert into numbers (select generate_series(1,10000))
      postInitTemplateSQL:
        - create extension intarray
      postInitApplicationSQL:
        - create table application_numbers (i integer)
        - insert into application_numbers (select generate_series(1,10000))
      postInitApplicationSQLRefs:
        configMapRefs:
        - name: post-init-sql-configmap
          key: configmap.sql
        secretRefs:
        - name: post-init-sql-secret
          key: secret.sql
  storage:
    size: 1Gi
```

### Response
N/A (Kubernetes Resource Definition)

#### Success Response (200)
N/A

#### Response Example
N/A

### Related Resources
- [ConfigMap](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#configmap-v1-core) - Kubernetes ConfigMap resource.
- [Secret](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#secret-v1-core) - Kubernetes Secret resource.

```

--------------------------------

### Configure k9s Plugin for CloudNativePG Backups

Source: https://cloudnative-pg.io/docs/assets/files/plugins-27c6a80c5a835b4a893b11dfba3a87f5.yml

Sets up the 'b' shortcut in k9s to trigger a physical backup for a CloudNativePG cluster. Requires the cnpg kubectl plugin.

```yaml
plugins:
  cnpg-backup:
    shortCut: b
    description: Backup
    scopes:
      - cluster
    command: bash
    confirm: true
    background: false
    args:
      - -c
      - "kubectl cnpg backup $NAME -n $NAMESPACE --context \"$CONTEXT\" 2>&1 | less -R"
```

--------------------------------

### Cluster Configuration with Backup

Source: https://cloudnative-pg.io/docs/assets/files/cluster-example-with-backup-4d12e9ed6962079d7b1898a7004a8e0f.yaml

This snippet demonstrates the configuration of a PostgreSQL cluster using CloudNativePG, specifying instance count, storage, and Barman-based backup settings.

```APIDOC
## POST /apis/postgresql.cnpg.io/v1/clusters

### Description
Creates a new PostgreSQL cluster with specified configuration, including storage and backup settings.

### Method
POST

### Endpoint
/apis/postgresql.cnpg.io/v1/clusters

### Parameters
#### Request Body
- **apiVersion** (string) - Required - Specifies the API version, e.g., "postgresql.cnpg.io/v1".
- **kind** (string) - Required - Set to "Cluster" for creating a PostgreSQL cluster.
- **metadata** (object) - Required - Contains metadata for the cluster, including its name.
  - **name** (string) - Required - The name of the PostgreSQL cluster.
- **spec** (object) - Required - Specifies the desired state of the cluster.
  - **instances** (integer) - Required - The number of PostgreSQL instances in the cluster.
  - **primaryUpdateStrategy** (string) - Optional - Strategy for primary instance updates (e.g., "unsupervised").
  - **storage** (object) - Required - Configuration for persistent storage.
    - **storageClass** (string) - Required - The storage class to use for persistent volumes.
    - **size** (string) - Required - The size of the persistent storage (e.g., "1Gi").
  - **backup** (object) - Optional - Configuration for automated backups.
    - **barmanObjectStore** (object) - Required if backup is enabled - Configuration for Barman object store.
      - **destinationPath** (string) - Required - The destination path for backups (e.g., "s3://backups/").
      - **endpointURL** (string) - Required - The URL of the object store endpoint (e.g., "http://minio:9000").
      - **s3Credentials** (object) - Required - Credentials for accessing the S3 object store.
        - **accessKeyId** (object) - Required - Defines the Access Key ID.
          - **name** (string) - Required - The name of the Kubernetes secret containing the Access Key ID.
          - **key** (string) - Required - The key within the secret that holds the Access Key ID.
        - **secretAccessKey** (object) - Required - Defines the Secret Access Key.
          - **name** (string) - Required - The name of the Kubernetes secret containing the Secret Access Key.
          - **key** (string) - Required - The key within the secret that holds the Secret Access Key.
      - **wal** (object) - Optional - WAL (Write-Ahead Log) specific backup settings.
        - **compression** (string) - Optional - Compression method for WAL files (e.g., "gzip").
      - **data** (object) - Optional - Data specific backup settings.
        - **additionalCommandArgs** (array of strings) - Optional - Additional arguments for the backup command.

### Request Example
```json
{
  "apiVersion": "postgresql.cnpg.io/v1",
  "kind": "Cluster",
  "metadata": {
    "name": "cluster-example-with-backup"
  },
  "spec": {
    "instances": 3,
    "primaryUpdateStrategy": "unsupervised",
    "storage": {
      "storageClass": "csi-hostpath-sc",
      "size": "1Gi"
    },
    "backup": {
      "barmanObjectStore": {
        "destinationPath": "s3://backups/",
        "endpointURL": "http://minio:9000",
        "s3Credentials": {
          "accessKeyId": {
            "name": "minio",
            "key": "ACCESS_KEY_ID"
          },
          "secretAccessKey": {
            "name": "minio",
            "key": "ACCESS_SECRET_KEY"
          }
        },
        "wal": {
          "compression": "gzip"
        },
        "data": {
          "additionalCommandArgs": [
            "--min-chunk-size=5MB",
            "--read-timeout=60",
            "-vv"
          ]
        }
      }
    }
  }
}
```

### Response
#### Success Response (201 Created)
- **status** (object) - The status of the created cluster.
- **metadata** (object) - Metadata of the created cluster.

#### Response Example
```json
{
  "apiVersion": "postgresql.cnpg.io/v1",
  "kind": "Cluster",
  "metadata": {
    "name": "cluster-example-with-backup",
    "creationTimestamp": "2023-10-27T10:00:00Z",
    "namespace": "default"
  },
  "spec": {
    "instances": 3,
    "primaryUpdateStrategy": "unsupervised",
    "storage": {
      "storageClass": "csi-hostpath-sc",
      "size": "1Gi"
    },
    "backup": {
      "barmanObjectStore": {
        "destinationPath": "s3://backups/",
        "endpointURL": "http://minio:9000",
        "s3Credentials": {
          "accessKeyId": {
            "name": "minio",
            "key": "ACCESS_KEY_ID"
          },
          "secretAccessKey": {
            "name": "minio",
            "key": "ACCESS_SECRET_KEY"
          }
        },
        "wal": {
          "compression": "gzip"
        },
        "data": {
          "additionalCommandArgs": [
            "--min-chunk-size=5MB",
            "--read-timeout=60",
            "-vv"
          ]
        }
      }
    }
  },
  "status": {
    "ready": true,
    "phase": "Running"
  }
}
```
```

--------------------------------

### POST /apis/postgresql.cnpg.io/v1/subscriptions

Source: https://cloudnative-pg.io/docs/assets/files/subscription-example-9b16e47fb8492ebbc3cccb30b9967ff2.yaml

Creates a new Subscription resource to initiate logical replication from an external cluster to a local CloudNativePG database.

```APIDOC
## POST /apis/postgresql.cnpg.io/v1/subscriptions

### Description
Creates a Subscription resource to synchronize data from a publication in an external cluster to a local database.

### Method
POST

### Endpoint
/apis/postgresql.cnpg.io/v1/subscriptions

### Parameters
#### Request Body
- **metadata.name** (string) - Required - The name of the subscription resource.
- **spec.name** (string) - Required - The name of the subscription within the PostgreSQL database.
- **spec.dbname** (string) - Required - The target database name.
- **spec.publicationName** (string) - Required - The name of the publication on the source cluster.
- **spec.cluster.name** (string) - Required - The name of the local CloudNativePG cluster.
- **spec.externalClusterName** (string) - Required - The name of the external cluster reference.

### Request Example
{
  "apiVersion": "postgresql.cnpg.io/v1",
  "kind": "Subscription",
  "metadata": {
    "name": "subscription-sample"
  },
  "spec": {
    "name": "sub",
    "dbname": "app",
    "publicationName": "pub-all",
    "cluster": {
      "name": "cluster-example-dest"
    },
    "externalClusterName": "cluster-example"
  }
}

### Response
#### Success Response (201)
- **kind** (string) - The resource type created.
- **metadata** (object) - The metadata of the created subscription.
```

--------------------------------

### CloudNativePG Cluster Definition

Source: https://cloudnative-pg.io/docs/assets/files/cluster-example-full-1c66b816fb9168cb8645fd18c9f53fa1.yaml

Defines a full PostgreSQL cluster using CloudNativePG's Custom Resource Definition (CRD). It configures instances, parameters, bootstrap, secrets, storage, backups, resources, and affinity.

```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example-full
spec:
  description: "Example of cluster"
  imageName: ghcr.io/cloudnative-pg/postgresql:18.1-system-trixie
  # imagePullSecret is only required if the images are located in a private registry
  # imagePullSecrets:
  #   - name: private_registry_access
  instances: 3
  startDelay: 300
  stopDelay: 300
  primaryUpdateStrategy: unsupervised

  postgresql:
    parameters:
      shared_buffers: 256MB
      pg_stat_statements.max: '10000'
      pg_stat_statements.track: all
      auto_explain.log_min_duration: '10s'
    pg_hba:
      - host all all 10.244.0.0/16 md5

  bootstrap:
    initdb:
      database: app
      owner: app
      secret:
        name: cluster-example-app-user
    # Alternative bootstrap method: start from a backup
    #recovery:
    #  backup:
    #    name: backup-example

  enableSuperuserAccess: true
  superuserSecret:
    name: cluster-example-superuser

  storage:
    storageClass: standard
    size: 1Gi

  backup:
    barmanObjectStore:
      destinationPath: s3://cluster-example-full-backup/
      endpointURL: http://custom-endpoint:1234
      s3Credentials:
        accessKeyId:
          name: backup-creds
          key: ACCESS_KEY_ID
        secretAccessKey:
          name: backup-creds
          key: ACCESS_SECRET_KEY
      wal:
        compression: gzip
        encryption: AES256
      data:
        compression: gzip
        encryption: AES256
        immediateCheckpoint: false
        jobs: 2
    retentionPolicy: "30d"

  resources:
    requests:
      memory: "512Mi"
      cpu: "1"
    limits:
      memory: "1Gi"
      cpu: "2"

  affinity:
    enablePodAntiAffinity: true
    topologyKey: failure-domain.beta.kubernetes.io/zone

  nodeMaintenanceWindow:
    inProgress: false
    reusePVC: false

```

--------------------------------

### Cluster Configuration with Pod Selector References

Source: https://cloudnative-pg.io/docs/assets/files/cluster-example-pod-selector-refs-c547bd11289059b1502935a6a7289040.yaml

This snippet demonstrates the configuration of a CloudNativePG PostgreSQL cluster, including the definition of `podSelectorRefs` and their usage within `pg_hba` rules for dynamic IP resolution.

```APIDOC
## Cluster Configuration with Pod Selector References

### Description
This configuration defines a PostgreSQL cluster using CloudNativePG, showcasing the use of `podSelectorRefs` to dynamically manage `pg_hba` rules. The operator resolves matching pod IPs based on the provided selectors and expands `${podselector:NAME}` references in `pg_hba` rules into individual IP entries with appropriate subnet masks.

### Method
N/A (Kubernetes Resource Definition)

### Endpoint
N/A (Kubernetes Resource Definition)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **apiVersion** (string) - Required - The API version for the Cluster resource (e.g., `postgresql.cnpg.io/v1`).
- **kind** (string) - Required - The type of Kubernetes resource, which is `Cluster`.
- **metadata** (object) - Required - Standard Kubernetes metadata.
  - **name** (string) - Required - The name of the PostgreSQL cluster.
- **spec** (object) - Required - Specification for the PostgreSQL cluster.
  - **instances** (integer) - Optional - The number of PostgreSQL instances in the cluster.
  - **podSelectorRefs** (array) - Optional - A list of named pod label selectors.
    - **name** (string) - Required - The name to be used for referencing this selector.
    - **selector** (object) - Required - Kubernetes label selector.
      - **matchLabels** (object) - Optional - A set of labels for the selector.
  - **postgresql** (object) - Optional - PostgreSQL specific configuration.
    - **pg_hba** (array) - Optional - A list of `pg_hba` rules. Can include `${podselector:NAME}` syntax for dynamic expansion.
  - **primaryUpdateStrategy** (string) - Optional - The strategy for updating the primary instance.
  - **storage** (object) - Optional - Storage configuration for the cluster.
    - **size** (string) - Required - The size of the storage volume.
```

--------------------------------

### CloudNativePG Cluster Definition (YAML)

Source: https://cloudnative-pg.io/docs/assets/files/cluster-example-logical-destination-9ee6c6cd03f30a90b12d712654f840e6.yaml

Defines a PostgreSQL cluster using CloudNativePG. It configures the number of instances, storage size, and bootstrap settings, including importing schemas from an external cluster. Dependencies include the CloudNativePG operator being installed in the Kubernetes cluster.

```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example-dest
spec:
  instances: 1

  storage:
    size: 1Gi

  bootstrap:
    initdb:
      import:
        type: microservice
        schemaOnly: true
        databases:
          - app
        source:
          externalCluster: cluster-example

  externalClusters:
  - name: cluster-example
    connectionParameters:
      host: cluster-example-rw.default.svc
      user: app
      dbname: app
    password:
      name: cluster-example-app
      key: password

```

--------------------------------

### Configure k9s Plugin for CloudNativePG PSQL Shell

Source: https://cloudnative-pg.io/docs/assets/files/plugins-27c6a80c5a835b4a893b11dfba3a87f5.yml

Sets up the 'p' shortcut in k9s to connect to a CloudNativePG cluster via psql. Requires the cnpg kubectl plugin.

```yaml
plugins:
  cnpg-psql:
    shortCut: p
    description: PSQL shell
    scopes:
      - cluster
    command: bash
    background: false
    args:
      - -c
      - "kubectl cnpg psql $NAME -n $NAMESPACE --context $CONTEXT"
```

--------------------------------

### Configure CloudNativePG Replica Cluster

Source: https://cloudnative-pg.io/docs/assets/files/cluster-example-replica-streaming-88f13b112218be539758fa680129a4e2.yaml

This YAML configuration defines a PostgreSQL cluster intended to be a replica of an existing 'cluster-example'. It specifies the number of instances, bootstrapping method using pg_basebackup from the source cluster, and enables replica mode. It also details the connection parameters for the external primary cluster, including host, user, database, and SSL settings, along with references to Kubernetes secrets for SSL certificates.

```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-replica-example
spec:
  instances: 1

  bootstrap:
    pg_basebackup:
      source: cluster-example

  replica:
    enabled: true
    source: cluster-example

  storage:
    size: 1Gi
  # note the namespace 'default' in the host name `cluster-example-rw.default.svc`
  # remember to change accordingly with the namespace of the main cluster
  externalClusters:
  - name: cluster-example
    connectionParameters:
      host: cluster-example-rw.default.svc
      user: streaming_replica
      sslmode: verify-full
      dbname: postgres
    # NOTE: if this cluster is created in a different namespace than the main cluster
    # remember to create the `-replication` and `-ca` secrets in the follower namespace
    # before creating the follower cluster
    sslKey:
      name: cluster-example-replication
      key: tls.key
    sslCert:
      name: cluster-example-replication
      key: tls.crt
    sslRootCert:
      name: cluster-example-ca
      key: ca.crt

```

--------------------------------

### POST /apis/postgresql.cnpg.io/v1/clusters

Source: https://cloudnative-pg.io/docs/assets/files/cluster-example-logical-source-c3c43edeb5b8508033b480279a87fa14.yaml

Creates a new PostgreSQL cluster instance with defined storage, replication, and initialization SQL scripts.

```APIDOC
## POST /apis/postgresql.cnpg.io/v1/clusters

### Description
Creates a managed PostgreSQL cluster with specified instance count, container image, and post-initialization SQL commands.

### Method
POST

### Endpoint
/apis/postgresql.cnpg.io/v1/namespaces/{namespace}/clusters

### Parameters
#### Request Body
- **metadata** (object) - Required - Contains the name of the cluster.
- **spec.instances** (integer) - Required - Number of PostgreSQL instances.
- **spec.imageName** (string) - Required - The container image for PostgreSQL.
- **spec.storage.size** (string) - Required - Persistent volume size.
- **spec.bootstrap.initdb.postInitApplicationSQL** (array) - Optional - List of SQL commands to run after database initialization.

### Request Example
{
  "apiVersion": "postgresql.cnpg.io/v1",
  "kind": "Cluster",
  "metadata": { "name": "cluster-example" },
  "spec": {
    "instances": 3,
    "imageName": "ghcr.io/cloudnative-pg/postgresql:17",
    "storage": { "size": "1Gi" }
  }
}

### Response
#### Success Response (201)
- **metadata** (object) - The created cluster resource metadata.
```

--------------------------------

### Create Database with PostGIS Extensions

Source: https://cloudnative-pg.io/docs/assets/files/postgis-example-9b1eefd054d43e72e73bebb112c95f76.yaml

Create a database within the PostgreSQL cluster and enable multiple PostGIS-related extensions. This includes core PostGIS, raster, SFCGAL, fuzzystrmatch, address standardizer, and geocoder functionalities.

```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Database
metadata:
  name: postgis-example-app
spec:
  name: app
  owner: app
  cluster:
    name: postgis-example
  extensions:
  - name: postgis
    version: '3.6.1'
  - name: postgis_raster
  - name: postgis_sfcgal
  - name: fuzzystrmatch
  - name: address_standardizer
  - name: address_standardizer_data_us
  - name: postgis_tiger_geocoder
  - name: postgis_topology
```

--------------------------------

### Configure k9s Plugin for Pretty CloudNativePG Logs

Source: https://cloudnative-pg.io/docs/assets/files/plugins-27c6a80c5a835b4a893b11dfba3a87f5.yml

Sets up the 'Shift-L' shortcut in k9s to view CloudNativePG cluster logs in a pretty format. Requires the cnpg kubectl plugin.

```yaml
plugins:
  cnpg-logs-pretty:
    shortCut: Shift-L
    description: Logs pretty
    scopes:
      - cluster
    command: bash
    background: false
    args:
      - -c
      - "kubectl cnpg logs cluster $NAME -f -n $NAMESPACE --context $CONTEXT | kubectl cnpg logs pretty"
```

--------------------------------

### POST /apis/postgresql.cnpg.io/v1/clusters

Source: https://cloudnative-pg.io/docs/assets/files/cluster-example-with-tablespaces-5773262b1b0a376e85721b61290a2a9c.yaml

Creates a new PostgreSQL cluster instance with specific storage and tablespace configurations.

```APIDOC
## POST /apis/postgresql.cnpg.io/v1/clusters

### Description
Creates a new PostgreSQL cluster resource within the Kubernetes cluster, defining the number of instances and associated storage tablespaces.

### Method
POST

### Endpoint
/apis/postgresql.cnpg.io/v1/clusters

### Parameters
#### Request Body
- **metadata.name** (string) - Required - The name of the cluster.
- **spec.instances** (integer) - Required - The number of PostgreSQL instances to deploy.
- **spec.storage.size** (string) - Required - The size of the main storage volume.
- **spec.tablespaces** (array) - Optional - A list of tablespace configurations including name, storage size, and temporary status.

### Request Example
{
  "apiVersion": "postgresql.cnpg.io/v1",
  "kind": "Cluster",
  "metadata": { "name": "cluster-example-with-tablespaces" },
  "spec": {
    "instances": 3,
    "storage": { "size": "1Gi" },
    "tablespaces": [
      { "name": "atablespace", "storage": { "size": "1Gi", "storageClass": "standard" }, "temporary": true }
    ]
  }
}

### Response
#### Success Response (201)
- **kind** (string) - The resource type created.
- **metadata** (object) - The metadata of the created cluster.

#### Response Example
{
  "kind": "Cluster",
  "metadata": { "name": "cluster-example-with-tablespaces", "uid": "..." }
}
```

--------------------------------

### Configure k9s Plugin for CloudNativePG Cluster Logs

Source: https://cloudnative-pg.io/docs/assets/files/plugins-27c6a80c5a835b4a893b11dfba3a87f5.yml

Sets up the 'l' shortcut in k9s to view the logs of a CloudNativePG cluster. Requires the cnpg kubectl plugin.

```yaml
plugins:
  cnpg-logs:
    shortCut: l
    description: Logs
    scopes:
      - cluster
    command: bash
    background: false
    args:
      - -c
      - "kubectl cnpg logs cluster $NAME -f -n $NAMESPACE --context $CONTEXT"
```

--------------------------------

### Configure CloudNativePG Backup Resource (YAML)

Source: https://cloudnative-pg.io/docs/assets/files/backup-example-2b6af9a7e23b0a4a356a60f879102485.yaml

This YAML defines a Backup resource for CloudNativePG. It specifies the target PostgreSQL cluster for which the backup should be created. Ensure the 'cluster.name' matches your PostgreSQL cluster's name.

```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Backup
metadata:
  name: pg-backup-example
spec:
  cluster:
    name: pg-backup
```

--------------------------------

### Configure k9s Plugin for CloudNativePG Cluster Restart

Source: https://cloudnative-pg.io/docs/assets/files/plugins-27c6a80c5a835b4a893b11dfba3a87f5.yml

Sets up the 'Shift-R' shortcut in k9s to restart a CloudNativePG cluster. Requires the cnpg kubectl plugin.

```yaml
plugins:
  cnpg-restart:
    shortCut: Shift-R
    description: Restart
    confirm: true
    scopes:
      - cluster
    command: bash
    background: false
    args:
      - -c
      - "kubectl cnpg restart $NAME -n $NAMESPACE --context \"$CONTEXT\" 2>&1 | less -R"
```

--------------------------------

### Basic CloudNativePG Cluster Configuration

Source: https://cloudnative-pg.io/docs/assets/files/cluster-example-d6113e8c79d0310c021647d2435f3e55.yaml

Defines a minimal CloudNativePG cluster with 3 instances and 1Gi of storage. Ensure the correct API version and kind are specified.

```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example
spec:
  instances: 3

  storage:
    size: 1Gi


```

--------------------------------

### Configure a PostgreSQL Publication

Source: https://cloudnative-pg.io/docs/assets/files/cluster-example-logical-source-c3c43edeb5b8508033b480279a87fa14.yaml

This manifest creates a publication for logical replication targeting all tables within the specified database of the cluster.

```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Publication
metadata:
  name: cluster-example-pub
spec:
  name: pub
  dbname: app
  cluster:
    name: cluster-example
  target:
    allTables: true
```

--------------------------------

### Define CloudNativePG Cluster with Post-Initialization SQL

Source: https://cloudnative-pg.io/docs/assets/files/cluster-example-initdb-sql-refs-34070647c762ef482998cdcc955435dd.yaml

This YAML configuration defines a CloudNativePG cluster with specific bootstrap settings. It includes direct SQL execution, template initialization, and references to external SQL scripts stored in ConfigMaps and Secrets.

```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example-initdb
spec:
  instances: 3
  bootstrap:
    initdb:
      database: appdb
      owner: appuser
      postInitSQL:
        - create table numbers (i integer)
        - insert into numbers (select generate_series(1,10000))
      postInitTemplateSQL:
        - create extension intarray
      postInitApplicationSQL:
        - create table application_numbers (i integer)
        - insert into application_numbers (select generate_series(1,10000))
      postInitApplicationSQLRefs:
        configMapRefs:
        - name: post-init-sql-configmap
          key: configmap.sql
        secretRefs:
        - name: post-init-sql-secret
          key: secret.sql
  storage:
    size: 1Gi
```

--------------------------------

### Provision Database with PostGIS Extensions

Source: https://cloudnative-pg.io/docs/assets/files/postgis-example-3de373a644737e5743ab58e9d0858d08.yaml

This YAML manifest defines a Database resource within a CNPG cluster, enabling various PostGIS modules such as topology, raster, and geocoder extensions.

```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Database
metadata:
  name: postgis-example-app
spec:
  name: app
  owner: app
  cluster:
    name: postgis-example
  extensions:
  - name: postgis
    version: '3.6.1'
  - name: postgis_raster
  - name: postgis_sfcgal
  - name: fuzzystrmatch
  - name: address_standardizer
  - name: address_standardizer_data_us
  - name: postgis_tiger_geocoder
  - name: postgis_topology
```

--------------------------------

### Create a PostgreSQL Cluster with CloudNativePG

Source: https://cloudnative-pg.io/docs/assets/files/cluster-example-logical-source-52c1bb11d5fbb8263b05aa23c09463ba.yaml

This YAML defines a PostgreSQL cluster using CloudNativePG. It specifies the number of instances, the PostgreSQL image, storage size, and bootstrap configuration with custom SQL commands for table creation and schema management. It also defines a managed role 'app' with login and replication privileges.

```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example
spec:
  instances: 1

  imageName: ghcr.io/cloudnative-pg/postgresql:16

  storage:
    size: 1Gi

  bootstrap:
    initdb:
      postInitApplicationSQL:
        - CREATE TABLE numbers (i SERIAL PRIMARY KEY, m INTEGER)
        - INSERT INTO numbers (m) (SELECT generate_series(1,10000))
        - ALTER TABLE numbers OWNER TO app
        - CREATE TABLE numbers_two (i SERIAL PRIMARY KEY, m INTEGER)
        - INSERT INTO numbers_two (m) (SELECT generate_series(1,10000))
        - ALTER TABLE numbers_two OWNER TO app
        - CREATE SCHEMA another_schema
        - ALTER SCHEMA another_schema OWNER TO app
        - CREATE TABLE another_schema.numbers_three (i SERIAL PRIMARY KEY, m INTEGER)
        - INSERT INTO another_schema.numbers_three (m) (SELECT generate_series(1,10000))
        - ALTER TABLE another_schema.numbers_three OWNER TO app

  managed:
    roles:
      - name: app
        login: true
        replication: true

```

--------------------------------

### Create Backup with Volume Snapshot - Kubernetes YAML

Source: https://cloudnative-pg.io/docs/assets/files/backup-with-volume-snapshot-d1b63cca9f18275aed757608982169d2.yaml

This YAML manifest defines a Backup resource for CloudNativePG, configured to use the 'volumeSnapshot' method. It specifies the target cluster and the backup method. This is a declarative way to initiate a backup within a Kubernetes environment.

```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Backup
metadata:
  name: backup-with-volume-snapshot
spec:
  method: volumeSnapshot
  cluster:
    name: cluster-example-with-volume-snapshot

```

--------------------------------

### Configure k9s Plugin for CloudNativePG Cluster Reload

Source: https://cloudnative-pg.io/docs/assets/files/plugins-27c6a80c5a835b4a893b11dfba3a87f5.yml

Sets up the 'r' shortcut in k9s to reload a CloudNativePG cluster. Requires the cnpg kubectl plugin.

```yaml
plugins:
  cnpg-reload:
    shortCut: r
    description: Reload
    confirm: true
    scopes:
      - cluster
    command: bash
    background: false
    args:
      - -c
      - "kubectl cnpg reload $NAME -n $NAMESPACE --context \"$CONTEXT\" 2>&1 | less -R"
```

--------------------------------

### POST /apis/postgresql.cnpg.io/v1/publications

Source: https://cloudnative-pg.io/docs/assets/files/publication-example-objects-bced6dd35e3b3bd9c4873e1537be0f8f.yaml

Creates a new Publication resource to manage logical replication settings for a specific PostgreSQL cluster.

```APIDOC
## POST /apis/postgresql.cnpg.io/v1/publications

### Description
Creates a Publication resource that defines which tables or schemas are included in a logical replication publication for a CloudNativePG cluster.

### Method
POST

### Endpoint
/apis/postgresql.cnpg.io/v1/namespaces/{namespace}/publications

### Parameters
#### Request Body
- **apiVersion** (string) - Required - Must be postgresql.cnpg.io/v1
- **kind** (string) - Required - Must be Publication
- **metadata** (object) - Required - Standard Kubernetes metadata including name
- **spec** (object) - Required - The specification of the publication
  - **cluster** (object) - Required - Reference to the target cluster
  - **name** (string) - Optional - The name of the publication in PostgreSQL
  - **dbname** (string) - Required - The database name
  - **target** (object) - Required - Defines the objects included in the publication

### Request Example
{
  "apiVersion": "postgresql.cnpg.io/v1",
  "kind": "Publication",
  "metadata": {
    "name": "publication-example-objects"
  },
  "spec": {
    "cluster": {
      "name": "cluster-example"
    },
    "name": "pub-objects",
    "dbname": "app",
    "target": {
      "objects": [
        { "tablesInSchema": "public" },
        { "table": { "schema": "another_schema", "name": "numbers_three", "only": true } }
      ]
    }
  }
}

### Response
#### Success Response (201)
- **kind** (string) - Publication
- **metadata** (object) - Resource metadata
```

--------------------------------

### Create PostgreSQL Database

Source: https://cloudnative-pg.io/docs/assets/files/postgis-example-665c2f2b838079a6eacc66697cab07a5.yaml

This snippet defines a PostgreSQL database resource within a specified cluster. It includes database name, owner, and a list of desired PostgreSQL extensions.

```APIDOC
## Create PostgreSQL Database

### Description
Defines a PostgreSQL database within a cluster, specifying its name, owner, and extensions.

### Method
APPLY (Kubernetes Resource Definition)

### Endpoint
N/A (Kubernetes Resource)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **apiVersion** (string) - Required - Specifies the API version for the Database resource.
- **kind** (string) - Required - Set to 'Database' for PostgreSQL databases.
- **metadata** (object) - Required - Contains the name of the database resource.
  - **name** (string) - Required - The name of the Database resource.
- **spec** (object) - Required - Defines the database's specification.
  - **name** (string) - Required - The actual name of the PostgreSQL database.
  - **owner** (string) - Required - The PostgreSQL role that will own the database.
  - **cluster** (object) - Required - Specifies the target PostgreSQL cluster.
    - **name** (string) - Required - The name of the Cluster resource.
  - **extensions** (array) - Optional - A list of PostgreSQL extensions to be created in the database.
    - **name** (string) - Required - The name of the extension (e.g., 'postgis').
```

--------------------------------

### Configure PostgreSQL Cluster with PVC Template

Source: https://cloudnative-pg.io/docs/assets/files/cluster-pvc-template-dcdcabd135b2936a54f93bb5be0fefb3.yaml

Define a PostgreSQL cluster with 3 instances, specifying a persistent storage configuration using a PVC template. This includes storage size, access modes, resource requests, storage class, and volume mode.

```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: postgresql-pvc-template
spec:
  instances: 3

  # Example of rolling update strategy:
  # - unsupervised: automated update of the primary once all
  #                 replicas have been upgraded (default)
  # - supervised: requires manual supervision to perform
  #               the switchover of the primary
  primaryUpdateStrategy: unsupervised

  # Persistent storage configuration
  storage:
    size: 1Gi
    pvcTemplate:
      accessModes:
        - ReadWriteOnce
      resources:
        requests:
          storage: 1Gi
      storageClassName: standard
      volumeMode: Filesystem

```

--------------------------------

### Configure k9s Plugin to Wake Up Hibernated Cluster

Source: https://cloudnative-pg.io/docs/assets/files/plugins-27c6a80c5a835b4a893b11dfba3a87f5.yml

Sets up the 'Shift-H' shortcut in k9s to wake up a hibernated CloudNativePG cluster within a namespace. Assumes the cluster name matches the namespace name. Requires the cnpg kubectl plugin.

```yaml
plugins:
  cnpg-hibernate-off:
    shortCut: Shift-H
    description: Wake up hibernated cluster in this namespace
    confirm: true
    scopes:
      - namespace
    command: bash
    background: false
    args:
      - -c
      - "kubectl cnpg hibernate off $NAME -n $NAME --context \"$CONTEXT\" 2>&1 | less -R"
```