Instance Pod Configuration
==========================

Projected Volumes
-----------------

CloudNativePG supports to mount custom files inside the Postgres pods
through ``.spec.projectedVolumeTemplate`` , this is useful for several
Postgres features and extensions that require additional data files. In
CloudNativePG, ``.spec.projectedVolumeTemplate`` field is a
 `projected volume <https://kubernetes.io/docs/concepts/storage/projected-volumes/>`_  template in kubernetes, which allows user to mount
arbitrary data under ``/projected`` folder in Postgres pods.

Here is a simple example about 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 will be mounted
as files into path ``/projected/certificate/tls.crt`` and
``/projected/certificate/tls.key`` in 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 using projected volume template to mount
Secret and Configmap in the

::

   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

deployment manifest.

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 for temporary storage
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

An ephemeral volume used for temporary storage. An upper bound on the
size can be configured via the
``spec.ephemeralVolumesSizeLimit.temporaryData`` field in the cluster
spec.

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

This volume is used as shared memory space for Postgres, also an
ephemeral type but stored in-memory. An upper bound on the size can be
configured via the ``spec.ephemeralVolumesSizeLimit.shm`` field in the
cluster spec. This is used only in case of :ref:`PostgreSQL running with `posix` shared memory dynamic allocation <PostgreSQL Configuration>`  .

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

Some system behavior can be customized using environment variables. One
example is the ``LDAPCONF`` variable, which may 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 the user to set custom environment variables via
the ``env`` and the ``envFrom`` stanza of the cluster specification.

The following is a definition of 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 will trigger a
rolling update of the PostgreSQL Pods.

If the ``env`` or the ``envFrom`` section refers to a Secret or a
ConfigMap, the operator will not detect any changes in them and will not
trigger a rollout. The Kubelet use the same behavior with Pods, and the
user is supposed to trigger the Pod rollout manually.