Instance pod configuration
==========================

.. raw:: html

   <!-- SPDX-License-Identifier: CC-BY-4.0 -->

Projected volumes
-----------------

CloudNativePG supports mounting custom files inside the Postgres pods
through ``.spec.projectedVolumeTemplate`` . This ability is useful for
several Postgres features and extensions that require additional data
files. In CloudNativePG, the ``.spec.projectedVolumeTemplate`` field is
a `projected volume <https://kubernetes.io/docs/concepts/storage/projected-volumes/>`_ 

template in Kubernetes that allows you to mount arbitrary data under the
``/projected`` folder in Postgres pods.

This simple example shows how to mount an existing TLS secret (named
``sample-secret`` ) as files into Postgres pods. The values for the
secret keys ``tls.crt`` and ``tls.key`` in ``sample-secret`` are mounted
as files into the paths ``/projected/certificate/tls.crt`` and
``/projected/certificate/tls.key`` in the Postgres pod.

.. code:: yaml

   apiVersion: postgresql.cnpg.io/v1
   kind: Cluster
   metadata:
     name: cluster-example-projected-volumes
   spec:
     instances: 3
     projectedVolumeTemplate:
       sources:
         - secret:
             name: sample-secret
             items:
               - key: tls.crt
                 path: certificate/tls.crt
               - key: tls.key
                 path: certificate/tls.key
     storage:
       size: 1Gi

You can find a complete example that uses a projected volume template to
mount the secret and ConfigMap in the deployment manifest.

::

   apiVersion: postgresql.cnpg.io/v1
   kind: Cluster
   metadata:
     name: cluster-example-projected-volume
   spec:
     instances: 3
     projectedVolumeTemplate:
       sources:
         - secret:
             name: sample-secret
             items:
               - key: tls.crt
                 path: certificate/tls.crt
               - key: tls.key
                 path: certificate/tls.key
         - configMap:
             name: sample-configmap
             items:
               - key: key1
                 path: config/key1
               - key: key2
                 path: config/key2
     storage:
       size: 1Gi

   - --
   apiVersion: v1
   data:
     tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNQekNDQWVXZ0F3SUJBZ0lRSHVDY2lKcDVkZis0dHZBcDBrTk9rekFLQmdncWhrak9QUVFEQWpCTk1TTXcKSVFZRFZRUUxFeHB3YjNOMFozSmxjM0ZzTFc5d1pYSmhkRzl5TFhONWMzUmxiVEVtTUNRR0ExVUVBeE1kY0c5egpkR2R5WlhOeGJDMXZjR1Z5WVhSdmNpMWpZUzF6WldOeVpYUXdIaGNOTWpJd09USTVNRGMxTVRBNVdoY05Nakl4Ck1qSTRNRGMxTVRBNVdqQk5NVXN3U1FZRFZRUURFMEp3YjNOMFozSmxjM0ZzTFc5d1pYSmhkRzl5TFhkbFltaHYKYjJzdGMyVnlkbWxqWlM1d2IzTjBaM0psYzNGc0xXOXdaWEpoZEc5eUxYTjVjM1JsYlM1emRtTXdXVEFUQmdjcQpoa2pPUFFJQkJnZ3Foa2pPUFFNQkJ3TkNBQVJRd2lhUm0wSmN4TzlBVlE0MVlqVlRqNUhDSVVFblFQOXNZRXFKCmYvNE1mVm53NkdDOThjNDNmQTVuS2UwSnQ5ZEV3QXREYktkdkRoeDlUTmIzdVY0K280R21NSUdqTUE0R0ExVWQKRHdFQi93UUVBd0lEcURBVEJnTlZIU1VFRERBS0JnZ3JCZ0VGQlFjREFUQU1CZ05WSFJNQkFmOEVBakFBTUI4RwpBMVVkSXdRWU1CYUFGQjN6cUVKbWFORENoRDdkWGptSWRlNEhUY0pFTUUwR0ExVWRFUVJHTUVTQ1FuQnZjM1JuCmNtVnpjV3d0YjNCbGNtRjBiM0l0ZDJWaWFHOXZheTF6WlhKMmFXTmxMbkJ2YzNSbmNtVnpjV3d0YjNCbGNtRjAKYjNJdGMzbHpkR1Z0TG5OMll6QUtCZ2dxaGtqT1BRUURBZ05JQURCRkFpQkMwS2M5WWxYelBpL0lhTkRnWHkwawpYTDJpNlZzSHRORTFxN3MzWXh6Mm53SWhBS2IxUW5EVTlqRnNVK0l5a292TitVU1ZpVm5vU2MvZ2RXWkxmMnhoCjZ2WUsKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=
     tls.key: LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1IY0NBUUVFSUtucWxVQjFqU2sxWW5VZzAyb0tGbXlRdDJLUEZwaFc0K1lmQUFmUFdRenVvQW9HQ0NxR1NNNDkKQXdFSG9VUURRZ0FFVU1JbWtadENYTVR2UUZVT05XSTFVNCtSd2lGQkowRC9iR0JLaVgvK0RIMVo4T2hndmZITwpOM3dPWnludENiZlhSTUFMUTJ5bmJ3NGNmVXpXOTdsZVBnPT0KLS0tLS1FTkQgRUMgUFJJVkFURSBLRVktLS0tLQo=
   kind: Secret
   metadata:
     name: sample-secret
   type: kubernetes.io/tls
   - --
   apiVersion: v1
   data:
     key1: value1
     key2: value2
     key3: value3
   kind: ConfigMap
   metadata:
     name: sample-configmap

Ephemeral volumes
-----------------

CloudNativePG relies on `ephemeral volumes <https://kubernetes.io/docs/concepts/storage/ephemeral-volumes/>`_ 

for part of the internal activities. Ephemeral volumes exist for the
sole duration of a pod’s life, without persisting across pod restarts.

Volume Claim Template for Temporary Storage
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The operator uses by default an ``emptyDir`` volume, which can be
customized by using the ``.spec.ephemeralVolumesSizeLimit field`` . This
can be overridden by specifying a volume claim template in the
``.spec.ephemeralVolumeSource`` field.

In the following example, a ``1Gi`` ephemeral volume is set.

.. code:: yaml

   apiVersion: postgresql.cnpg.io/v1
   kind: Cluster
   metadata:
     name: cluster-example-ephemeral-volume-source
   spec:
     instances: 3
     ephemeralVolumeSource:
       volumeClaimTemplate:
         spec:
           accessModes: ["ReadWriteOnce"]
           # example storageClassName, replace with one existing in your Kubernetes cluster
           storageClassName: "scratch-storage-class"
           resources:
             requests:
               storage: 1Gi

Both ``.spec.emphemeralVolumeSource`` and
``.spec.ephemeralVolumesSizeLimit.temporaryData`` cannot be specified
simultaneously.

Volume for shared memory
^^^^^^^^^^^^^^^^^^^^^^^^

This volume is used as shared memory space for Postgres and as an
ephemeral type but stored in memory. You can configure an upper bound on
the size using the ``.spec.ephemeralVolumesSizeLimit.shm`` field in the
cluster spec. Use this field only in case of :ref:`PostgreSQL running with `posix` shared memory dynamic allocation <PostgreSQL Configuration>`  .

Environment variables
---------------------

You can customize some system behavior using environment variables. One
example is the ``LDAPCONF`` variable, which can point to a custom LDAP
configuration file. Another example is the ``TZ`` environment variable,
which represents the timezone used by the PostgreSQL container.

CloudNativePG allows you to set custom environment variables using the
``env`` and the ``envFrom`` stanza of the cluster specification.

This example defines a PostgreSQL cluster using the ``Australia/Sydney``
timezone as the default cluster-level timezone:

.. code:: yaml

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

     env:
     - name: TZ
       value: Australia/Sydney

     storage:
       size: 1Gi

The ``envFrom`` stanza can refer to ConfigMaps or secrets to use their
content as environment variables:

.. code:: yaml

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

     envFrom:
     - configMapRef:
         name: config-map-name
     - secretRef:
         name: secret-name

     storage:
       size: 1Gi

The operator doesn’t allow setting the following environment variables:

- ``POD_NAME``

- ``NAMESPACE``

- Any environment variable whose name starts with ``PG`` .

Any change in the ``env`` or in the ``envFrom`` section triggers a
rolling update of the PostgreSQL pods.

If the ``env`` or the ``envFrom`` section refers to a secret or a
ConfigMap, the operator doesn’t detect any changes in them and doesn’t
trigger a rollout. The kubelet uses the same behavior with pods, and you
must trigger the pod rollout manually.