From 12a25b9eb127c11f612675fc2b8d6eff0426aa29 Mon Sep 17 00:00:00 2001 From: kurokobo <2920259+kurokobo@users.noreply.github.com> Date: Wed, 24 Apr 2024 22:29:45 +0900 Subject: [PATCH] docs: update docs for extra settings --- .../custom-volume-and-volume-mount-options.md | 37 ++---- .../advanced-configuration/extra-settings.md | 117 +++++++++++++++--- 2 files changed, 110 insertions(+), 44 deletions(-) diff --git a/docs/user-guide/advanced-configuration/custom-volume-and-volume-mount-options.md b/docs/user-guide/advanced-configuration/custom-volume-and-volume-mount-options.md index 95eb81772..90a1c5908 100644 --- a/docs/user-guide/advanced-configuration/custom-volume-and-volume-mount-options.md +++ b/docs/user-guide/advanced-configuration/custom-volume-and-volume-mount-options.md @@ -1,4 +1,4 @@ -#### Custom Volume and Volume Mount Options +## Custom Volume and Volume Mount Options In a scenario where custom volumes and volume mounts are required to either overwrite defaults or mount configuration files. @@ -31,10 +31,8 @@ data: remote_tmp = /tmp [ssh_connection] ssh_args = -C -o ControlMaster=auto -o ControlPersist=60s - custom.py: | - INSIGHTS_URL_BASE = "example.org" - AWX_CLEANUP_PATHS = True ``` + Example spec file for volumes and volume mounts ```yaml @@ -49,13 +47,6 @@ spec: - key: ansible.cfg path: ansible.cfg name: -extra-config - - name: custom-py - configMap: - defaultMode: 420 - items: - - key: custom.py - path: custom.py - name: -extra-config - name: shared-volume persistentVolumeClaim: claimName: my-external-volume-claim @@ -73,24 +64,17 @@ spec: - name: ansible-cfg mountPath: /etc/ansible/ansible.cfg subPath: ansible.cfg - - web_extra_volume_mounts: | - - name: custom-py - mountPath: /etc/tower/conf.d/custom.py - subPath: custom.py - - task_extra_volume_mounts: | - - name: custom-py - mountPath: /etc/tower/conf.d/custom.py - subPath: custom.py - - name: shared-volume - mountPath: /shared ``` !!! warning **Volume and VolumeMount names cannot contain underscores(_)** -##### Custom UWSGI Configuration +### Custom AWX Configuration + +Refer to the [Extra Settings](./extra-settings.md) documentation for customizing the AWX configuration. + +### Custom UWSGI Configuration + We allow the customization of two UWSGI parameters: * [processes](https://uwsgi-docs.readthedocs.io/en/latest/Options.html#processes) with `uwsgi_processes` (default 5) @@ -110,7 +94,7 @@ requests (more than 128) tend to come in a short period of time, but can all be handled before any other time outs may apply. Also see related nginx configuration. -##### Custom Nginx Configuration +### Custom Nginx Configuration Using the [extra_volumes feature](#custom-volume-and-volume-mount-options), it is possible to extend the nginx.conf. @@ -136,8 +120,7 @@ configuration. * [worker_connections](http://nginx.org/en/docs/ngx_core_module.html#worker_connections) with `nginx_worker_connections` (minimum of 1024) * [listen](https://nginx.org/en/docs/http/ngx_http_core_module.html#listen) with `nginx_listen_queue_size` (default same as uwsgi listen queue size) - -##### Custom Favicon +### Custom Favicon You can use custom volume mounts to mount in your own favicon to be displayed in your AWX browser tab. diff --git a/docs/user-guide/advanced-configuration/extra-settings.md b/docs/user-guide/advanced-configuration/extra-settings.md index 319cdfd28..83806cbae 100644 --- a/docs/user-guide/advanced-configuration/extra-settings.md +++ b/docs/user-guide/advanced-configuration/extra-settings.md @@ -1,30 +1,113 @@ -#### Extra Settings +## Extra Settings -With`extra_settings`, you can pass multiple custom settings via the `awx-operator`. The parameter `extra_settings` will be appended to the `/etc/tower/settings.py` and can be an alternative to the `extra_volumes` parameter. +With `extra_settings` and `extra_settings_files`, you can pass multiple custom settings to AWX via the AWX Operator. -| Name | Description | Default | -| -------------- | -------------- | ------- | -| extra_settings | Extra settings | '' | +!!! note + Parameters configured in `extra_settings` or `extra_settings_files` are set as read-only settings in AWX. As a result, they cannot be changed in the UI after deployment. -**Note:** Parameters configured in `extra_settings` are set as read-only settings in AWX. As a result, they cannot be changed in the UI after deployment. If you need to change the setting after the initial deployment, you need to change it on the AWX CR spec. + If you need to change the setting after the initial deployment, you need to change it on the AWX CR spec (for `extra_settings`) or corresponding ConfigMap or Secret (for `extra_settings_files`). After updating ConfigMap or Secret, you need to restart the AWX pods to apply the changes. + +### Add extra settings with `extra_settings` + +You can pass extra settings by specifying the pair of the setting name and value as the `extra_settings` parameter. + +The settings passed via `extra_settings` will be appended to the `/etc/tower/settings.py`. + +| Name | Description | Default | +| -------------- | -------------- | --------- | +| extra_settings | Extra settings | `[]` | Example configuration of `extra_settings` parameter ```yaml - spec: - extra_settings: - - setting: MAX_PAGE_SIZE - value: "500" +spec: + extra_settings: + - setting: MAX_PAGE_SIZE + value: "500" - - setting: AUTH_LDAP_BIND_DN - value: "cn=admin,dc=example,dc=com" + - setting: AUTH_LDAP_BIND_DN + value: "cn=admin,dc=example,dc=com" - - setting: LOG_AGGREGATOR_LEVEL - value: "'DEBUG'" + - setting: LOG_AGGREGATOR_LEVEL + value: "'DEBUG'" ``` Note for some settings, such as `LOG_AGGREGATOR_LEVEL`, the value may need double quotes. -!!! tip - Alternatively, you can pass any additional settings by mounting ConfigMaps or Secrets of the python files (`*.py`) that contain custom settings to under `/etc/tower/conf.d/` in the web and task pods. - See the example of `custom.py` in the [Custom Volume and Volume Mount Options](custom-volume-and-volume-mount-options.md) section. +### Add extra settings with `extra_settings_files` + +You can pass extra settings by specifying the additional settings files in the ConfigMaps or Secrets as the `extra_settings_files` parameter. + +The settings files passed via `extra_settings_files` will be mounted as the files under the `/etc/tower/conf.d`. + +| Name | Description | Default | +| -------------------- | -------------------- | --------- | +| extra_settings_files | Extra settings files | `{}` | + +Create ConfigMaps or Secrets that contain custom settings files (`*.py`). + +```python title="custom_job_settings.py" +AWX_TASK_ENV = { + "HTTPS_PROXY": "http://proxy.example.com:3128", + "HTTP_PROXY": "http://proxy.example.com:3128", + "NO_PROXY": "127.0.0.1,localhost,.example.com" +} +GALAXY_TASK_ENV = { + "ANSIBLE_FORCE_COLOR": "false", + "GIT_SSH_COMMAND": "ssh -o StrictHostKeyChecking=no", +} +``` + +```python title="custom_system_settings.py" +REMOTE_HOST_HEADERS = [ + "HTTP_X_FORWARDED_FOR", + "REMOTE_ADDR", + "REMOTE_HOST", +] +``` + +```python title="custom_passwords.py" +SUBSCRIPTIONS_PASSWORD = "my-super-secure-subscription-password123!" +REDHAT_PASSWORD = "my-super-secure-redhat-password123!" +``` + +```bash title="Create ConfigMap and Secret" +# Create ConfigMap +kubectl create configmap my-custom-settings \ + --from-file=custom_job_settings.py=/PATH/TO/YOUR/custom_job_settings.py \ + --from-file=custom_system_settings.py=/PATH/TO/YOUR/custom_system_settings.py + +# Create Secret +kubectl create secret generic my-custom-passwords \ + --from-file=custom_passwords.py=/PATH/TO/YOUR/custom_passwords.py +``` + +Then specify them in the AWX CR spec. Here is an example configuration of `extra_settings_files` parameter. + +```yaml +spec: + extra_settings_files: + configmaps: + - name: my-custom-settings # The name of the ConfigMap + key: custom_job_settings.py # The key in the ConfigMap, which means the file name + - name: my-custom-settings + key: custom_system_settings.py + secrets: + - name: my-custom-passwords # The name of the Secret + key: custom_passwords.py # The key in the Secret, which means the file name +``` + +!!! Warning "Restriction" + There are some restrictions on the ConfigMaps or Secrets used in `extra_settings_files`. + + - The keys in ConfigMaps or Secrets MUST be the name of python files and MUST end with `.py` + - The keys in ConfigMaps or Secrets MUST consists of alphanumeric characters, `-`, `_` or `.` + - The keys in ConfigMaps or Secrets are converted to the following strings, which MUST not exceed 63 characters + - Keys in ConfigMaps: `--configmap` + - Keys in Secrets: `--secret` + - Following keys are reserved and MUST NOT be used in ConfigMaps or Secrets + - `credentials.py` + - `execution_environments.py` + - `ldap.py` + + Refer to the Kubernetes documentations ([[1]](https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/config-map-v1/), [[2]](https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/secret-v1/), [[3]](https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/volume/), [[4]](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/)) for more information about character types and length restrictions.