Add postgres_extra_settings (#2071)

* Add hacking/ directory to .gitignore as it is commonly used for dev scripts
* Add postgres_extra_settings
* Add postgres_configuration_secret checksum to DB statefulset
* Docs for postgres_extra_settings, CI coverage, and examples
---------
Co-authored-by: Christian M. Adams <chadams@redhat.com>

.gitignore

@@ -11,3 +11,4 @@ gh-pages/
 __pycache__
 /site
 venv/*
+hacking/

config/crd/bases/awx.ansible.com_awxs.yaml

@@ -1828,9 +1828,25 @@ spec:
                 description: Assign a preexisting priority class to the postgres pod
                 type: string
               postgres_extra_args:
+                description: "(Deprecated, use postgres_extra_settings parameter) Define postgres configuration arguments to use"
                 type: array
                 items:
                   type: string
+              postgres_extra_settings:
+                description: "PostgreSQL configuration settings to be added to postgresql.conf"
+                type: array
+                items:
+                  type: object
+                  properties:
+                    setting:
+                      description: "PostgreSQL configuration parameter name"
+                      type: string
+                    value:
+                      description: "PostgreSQL configuration parameter value"
+                      type: string
+                  required:
+                    - setting
+                    - value
               postgres_data_volume_init:
                 description: Sets permissions on the /var/lib/pgdata/data for postgres container using an init container (not Openshift)
                 type: boolean

config/manifests/bases/awx-operator.clusterserviceversion.yaml

@@ -697,11 +697,16 @@ spec:
         x-descriptors:
         - urn:alm:descriptor:io.kubernetes:StorageClass
         - urn:alm:descriptor:com.tectonic.ui:advanced
-      - displayName: Postgres Extra Arguments
+      - displayName: Postgres Extra Arguments (Deprecated)
         path: postgres_extra_args
         x-descriptors:
         - urn:alm:descriptor:com.tectonic.ui:advanced
         - urn:alm:descriptor:com.tectonic.ui:hidden
+      - displayName: Postgres Extra Settings
+        path: postgres_extra_settings
+        x-descriptors:
+        - urn:alm:descriptor:com.tectonic.ui:advanced
+        - urn:alm:descriptor:com.tectonic.ui:hidden
       - description: Specify extra volumes to add to the postgres pod
         displayName: Postgres Extra Volumes
         path: postgres_extra_volumes

dev/awx-cr/awx-db-configuration.cr.yml

@@ -0,0 +1,30 @@
+---
+apiVersion: awx.ansible.com/v1beta1
+kind: AWX
+metadata:
+  name: awx
+spec:
+  service_type: clusterip
+  ingress_type: Route
+
+  postgres_extra_settings:
+    - setting: max_connections
+      value: "999"
+    - setting: ssl_ciphers
+      value: "HIGH:!aNULL:!MD5"
+
+  # requires custom-postgres-configuration secret to be pre-created
+  # postgres_configuration_secret: custom-postgres-configuration
+
+  postgres_resource_requirements:
+    requests:
+      cpu: 100m
+      memory: 256Mi
+    limits:
+      cpu: 800m
+      memory: 1Gi
+  postgres_storage_requirements:
+    requests:
+      storage: 20Gi
+    limits:
+      storage: 100Gi

docs/user-guide/database-configuration.md

@@ -69,6 +69,7 @@ The following variables are customizable for the managed PostgreSQL service
 | postgres_storage_requirements                 | PostgreSQL container storage requirements                       | requests: {storage: 8Gi}                |
 | postgres_storage_class                        | PostgreSQL PV storage class                                     | Empty string                            |
 | postgres_priority_class                       | Priority class used for PostgreSQL pod                          | Empty string                            |
+| postgres_extra_settings                       | PostgreSQL configuration settings to be added to postgresql.conf | `[]`                                    |
 
 Example of customization could be:
 
@@ -89,14 +90,78 @@ spec:
     limits:
       storage: 50Gi
   postgres_storage_class: fast-ssd
-  postgres_extra_args:
+  postgres_extra_settings:
-    - '-c'
+    - setting: max_connections
-    - 'max_connections=1000'
+      value: "1000"
 ```
 
 !!! note
     If `postgres_storage_class` is not defined, PostgreSQL will store it's data on a volume using the default storage class for your cluster.
 
+## PostgreSQL Extra Settings
+
+!!! warning "Deprecation Notice"
+    The `postgres_extra_args` parameter is **deprecated** and should no longer be used. Use `postgres_extra_settings` instead for configuring PostgreSQL parameters. The `postgres_extra_args` parameter will be removed in a future version of the AWX operator.
+
+You can customize PostgreSQL configuration by adding settings to the `postgresql.conf` file using the `postgres_extra_settings` parameter. This allows you to tune PostgreSQL performance, security, and behavior according to your specific requirements.
+
+The `postgres_extra_settings` parameter accepts an array of setting objects, where each object contains a `setting` name and its corresponding `value`.
+
+!!! note
+    The `postgres_extra_settings` parameter replaces the deprecated `postgres_extra_args` parameter and provides a more structured way to configure PostgreSQL settings.
+
+### Configuration Format
+
+```yaml
+spec:
+  postgres_extra_settings:
+    - setting: max_connections
+      value: "499"
+    - setting: ssl_ciphers
+      value: "HIGH:!aNULL:!MD5"
+```
+
+**Common PostgreSQL settings you might want to configure:**
+
+| Setting | Description | Example Value |
+|---------|-------------|---------------|
+| `max_connections` | Maximum number of concurrent connections | `"200"` |
+| `ssl_ciphers` | SSL cipher suites to use | `"HIGH:!aNULL:!MD5"` |
+| `shared_buffers` | Amount of memory for shared memory buffers | `"256MB"` |
+| `effective_cache_size` | Planner's assumption about effective cache size | `"1GB"` |
+| `work_mem` | Amount of memory for internal sort operations | `"4MB"` |
+| `maintenance_work_mem` | Memory for maintenance operations | `"64MB"` |
+| `checkpoint_completion_target` | Target for checkpoint completion | `"0.9"` |
+| `wal_buffers` | Amount of memory for WAL buffers | `"16MB"` |
+
+### Important Notes
+
+!!! warning
+    - Changes to `postgres_extra_settings` require a PostgreSQL pod restart to take effect.
+    - Some settings may require specific PostgreSQL versions or additional configuration.
+    - Always test configuration changes in a non-production environment first.
+
+!!! tip
+    - String values should be quoted in the YAML configuration.
+    - Numeric values can be provided as strings or numbers.
+    - Boolean values should be provided as strings ("on"/"off" or "true"/"false").
+
+For a complete list of available PostgreSQL configuration parameters, refer to the [PostgreSQL documentation](https://www.postgresql.org/docs/current/runtime-config.html).
+
+**Verification:**
+
+You can verify that your settings have been applied by connecting to the PostgreSQL database and running:
+
+```bash
+kubectl exec -it <postgres-pod-name> -n <namespace> -- psql
+```
+
+Then run the following query:
+
+```sql
+SELECT name, setting FROM pg_settings;
+```
+
 ## Note about overriding the postgres image
 
 We recommend you use the default image sclorg image. If you are coming from a deployment using the old postgres image from dockerhub (postgres:13), upgrading from awx-operator version 2.12.2 and below to 2.15.0+ will handle migrating your data to the new postgresql image (postgresql-15-c9s).

molecule/default/templates/awx_cr_molecule.yml.j2

@@ -49,3 +49,8 @@ spec:
 {% if additional_fields is defined %}
   {{ additional_fields | to_nice_yaml | indent(2) }}
 {% endif %}
+  postgres_extra_settings:
+    - setting: max_connections
+      value: "499"
+    - setting: ssl_ciphers
+      value: "HIGH:!aNULL:!MD5"

roles/installer/defaults/main.yml

@@ -422,8 +422,11 @@ projects_persistence: false
 # Define an existing PersistentVolumeClaim to use
 projects_existing_claim: ''
 #
-# Define postgres configuration arguments to use
+# Define postgres configuration arguments to use (Deprecated)
 postgres_extra_args: ''
+#
+# Define postgresql.conf configurations
+postgres_extra_settings: []
 
 postgres_data_volume_init: false
 postgres_init_container_commands: |

roles/installer/tasks/database.yml

@@ -2,6 +2,12 @@
 - name: Get database configuration
   include_tasks: database_configuration.yml
 
+- name: Create postgresql.conf ConfigMap
+  k8s:
+    apply: true
+    definition: "{{ lookup('template', 'configmaps/postgres_extra_settings.yaml.j2') }}"
+  when: postgres_extra_settings | length
+
 # It is possible that N-2 postgres pods may still be present in the namespace from previous upgrades.
 # So we have to take that into account and preferentially set the most recent one.
 - name: Get the old postgres pod (N-1)

roles/installer/templates/configmaps/postgres_extra_settings.yaml.j2

@@ -0,0 +1,16 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: '{{ ansible_operator_meta.name }}-postgres-extra-settings'
+  namespace: '{{ ansible_operator_meta.namespace }}'
+  labels:
+    {{ lookup("template", "../common/templates/labels/common.yaml.j2") | indent(width=4) | trim }}
+data:
+  99-overrides.conf: |
+{% for pg_setting in postgres_extra_settings %}
+{% if pg_setting.value is string %}
+    {{ pg_setting.setting }} = '{{ pg_setting.value }}'
+{% else %}
+    {{ pg_setting.setting }} = {{ pg_setting.value }}
+{% endif %}
+{% endfor %}

roles/installer/templates/statefulsets/postgres.yaml.j2

@@ -34,6 +34,11 @@ spec:
         app.kubernetes.io/component: 'database'
         app.kubernetes.io/part-of: '{{ ansible_operator_meta.name }}'
         app.kubernetes.io/managed-by: '{{ deployment_type }}-operator'
+      annotations:
+{% if postgres_extra_settings | length > 0 %}
+        checksum-postgres_extra_settings: "{{ lookup('template', 'configmaps/postgres_extra_settings.yaml.j2') | sha1 }}"
+{% endif %}
+        checksum-secret-postgres_configuration_secret: "{{ lookup('ansible.builtin.vars', 'pg_config', default='')["resources"][0]["data"] | default('') | sha1 }}"
 {% if postgres_annotations %}
         {{ postgres_annotations | indent(width=8) }}
 {% endif %}
@@ -137,6 +142,11 @@ spec:
             - name: postgres-{{ supported_pg_version }}
               mountPath: '{{ _postgres_data_path | dirname }}'
               subPath: '{{ _postgres_data_path | dirname | basename }}'
+{% if postgres_extra_settings | length > 0 %}
+            - name: pg-overrides
+              mountPath: /opt/app-root/src/postgresql-cfg
+              readOnly: true
+{% endif %}
 {% if postgres_extra_volume_mounts %}
             {{ postgres_extra_volume_mounts | indent(width=12, first=True) }}
 {% endif %}
@@ -149,9 +159,19 @@ spec:
       tolerations:
         {{ postgres_tolerations | indent(width=8) }}
 {% endif %}
-{% if postgres_extra_volumes %}
+{% if (postgres_extra_volumes | length + postgres_extra_settings | length) > 0 %}
       volumes:
+{% if postgres_extra_volumes %}
         {{ postgres_extra_volumes | indent(width=8, first=False) }}
+{% endif %}
+{% if postgres_extra_settings | length > 0 %}
+        - name: pg-overrides
+          configMap:
+            name: '{{ ansible_operator_meta.name }}-postgres-extra-settings'
+            items:
+              - key: 99-overrides.conf
+                path: 99-overrides.conf
+{% endif %}
 {% endif %}
   volumeClaimTemplates:
     - metadata: