From e0a8a882435fc24d99874432d7ea1883e61341fe Mon Sep 17 00:00:00 2001 From: jamesmarshall24 Date: Wed, 3 Sep 2025 12:36:34 -0400 Subject: [PATCH] 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 --- .gitignore | 1 + config/crd/bases/awx.ansible.com_awxs.yaml | 16 +++++ .../awx-operator.clusterserviceversion.yaml | 7 +- dev/awx-cr/awx-db-configuration.cr.yml | 30 ++++++++ docs/user-guide/database-configuration.md | 71 ++++++++++++++++++- .../default/templates/awx_cr_molecule.yml.j2 | 5 ++ roles/installer/defaults/main.yml | 5 +- roles/installer/tasks/database.yml | 6 ++ .../postgres_extra_settings.yaml.j2 | 16 +++++ .../templates/statefulsets/postgres.yaml.j2 | 22 +++++- 10 files changed, 173 insertions(+), 6 deletions(-) create mode 100644 dev/awx-cr/awx-db-configuration.cr.yml create mode 100644 roles/installer/templates/configmaps/postgres_extra_settings.yaml.j2 diff --git a/.gitignore b/.gitignore index 67191a93..df03bddf 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,4 @@ gh-pages/ __pycache__ /site venv/* +hacking/ diff --git a/config/crd/bases/awx.ansible.com_awxs.yaml b/config/crd/bases/awx.ansible.com_awxs.yaml index 652a1b1e..1b90d2ca 100644 --- a/config/crd/bases/awx.ansible.com_awxs.yaml +++ b/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 diff --git a/config/manifests/bases/awx-operator.clusterserviceversion.yaml b/config/manifests/bases/awx-operator.clusterserviceversion.yaml index c493108d..006e8c14 100644 --- a/config/manifests/bases/awx-operator.clusterserviceversion.yaml +++ b/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 diff --git a/dev/awx-cr/awx-db-configuration.cr.yml b/dev/awx-cr/awx-db-configuration.cr.yml new file mode 100644 index 00000000..ed0c2845 --- /dev/null +++ b/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 diff --git a/docs/user-guide/database-configuration.md b/docs/user-guide/database-configuration.md index 6168e3eb..607fe4ad 100644 --- a/docs/user-guide/database-configuration.md +++ b/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: - - '-c' - - 'max_connections=1000' + postgres_extra_settings: + - setting: max_connections + 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 -n -- 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). diff --git a/molecule/default/templates/awx_cr_molecule.yml.j2 b/molecule/default/templates/awx_cr_molecule.yml.j2 index be8a8a35..a6089c59 100644 --- a/molecule/default/templates/awx_cr_molecule.yml.j2 +++ b/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" diff --git a/roles/installer/defaults/main.yml b/roles/installer/defaults/main.yml index c29bba91..df783597 100644 --- a/roles/installer/defaults/main.yml +++ b/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: | diff --git a/roles/installer/tasks/database.yml b/roles/installer/tasks/database.yml index 01a0a86d..db3841fa 100644 --- a/roles/installer/tasks/database.yml +++ b/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) diff --git a/roles/installer/templates/configmaps/postgres_extra_settings.yaml.j2 b/roles/installer/templates/configmaps/postgres_extra_settings.yaml.j2 new file mode 100644 index 00000000..d7b891c6 --- /dev/null +++ b/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 %} diff --git a/roles/installer/templates/statefulsets/postgres.yaml.j2 b/roles/installer/templates/statefulsets/postgres.yaml.j2 index 31b88d20..d1c93c9f 100644 --- a/roles/installer/templates/statefulsets/postgres.yaml.j2 +++ b/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: