-
Notifications
You must be signed in to change notification settings - Fork 638
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: implement extra_settings_files (#1836)
* feat: implement extra_settings_files * fix: reduce duplicated code blocks by templates * docs: update docs for extra settings * docs: simplify the commands * docs: add notes for duplicated keys in setting files
- Loading branch information
Showing
12 changed files
with
199 additions
and
50 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
123 changes: 106 additions & 17 deletions
123
docs/user-guide/advanced-configuration/extra-settings.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,30 +1,119 @@ | ||
| #### 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. | ||
|
|
||
| !!! note | ||
| If the same setting is set in both `extra_settings` and `extra_settings_files`, the setting in `extra_settings_files` will take precedence. | ||
|
|
||
| ## 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 | `{}` | | ||
|
|
||
| !!! note | ||
| If the same setting is set in multiple files in `extra_settings_files`, it would be difficult to predict which would be adopted since these files are loaded in arbitrary order that [`glob`](https://docs.python.org/3/library/glob.html) returns. For a reliable setting, do not include the same key in more than one file. | ||
|
|
||
| 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 /PATH/TO/YOUR/custom_job_settings.py \ | ||
| --from-file /PATH/TO/YOUR/custom_system_settings.py | ||
| # Create Secret | ||
| kubectl create secret generic my-custom-passwords \ | ||
| --from-file /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: `<instance name>-<KEY>-configmap` | ||
| - Keys in Secrets: `<instance name>-<KEY>-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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
16 changes: 16 additions & 0 deletions
16
roles/installer/templates/common/volume_mounts/extra_settings_files.yaml.j2
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| {% if extra_settings_files.configmaps is defined and extra_settings_files.configmaps | length %} | ||
| {% for configmap in extra_settings_files.configmaps %} | ||
| - name: {{ ansible_operator_meta.name }}-{{ configmap.key | replace('_', '-') | replace('.', '-') | lower }}-configmap | ||
| mountPath: "/etc/tower/conf.d/{{ configmap.key }}" | ||
| subPath: {{ configmap.key }} | ||
| readOnly: true | ||
| {% endfor %} | ||
| {% endif %} | ||
| {% if extra_settings_files.secrets is defined and extra_settings_files.secrets | length %} | ||
| {% for secret in extra_settings_files.secrets %} | ||
| - name: {{ ansible_operator_meta.name }}-{{ secret.key | replace('_', '-') | replace('.', '-') | lower }}-secret | ||
| mountPath: "/etc/tower/conf.d/{{ secret.key }}" | ||
| subPath: {{ secret.key }} | ||
| readOnly: true | ||
| {% endfor %} | ||
| {% endif %} |
20 changes: 20 additions & 0 deletions
20
roles/installer/templates/common/volumes/extra_settings_files.yaml.j2
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| {% if extra_settings_files.configmaps is defined and extra_settings_files.configmaps | length %} | ||
| {% for configmap in extra_settings_files.configmaps %} | ||
| - name: {{ ansible_operator_meta.name }}-{{ configmap.key | replace('_', '-') | replace('.', '-') | lower }}-configmap | ||
| configMap: | ||
| name: {{ configmap.name }} | ||
| items: | ||
| - key: {{ configmap.key }} | ||
| path: {{ configmap.key }} | ||
| {% endfor %} | ||
| {% endif %} | ||
| {% if extra_settings_files.secrets is defined and extra_settings_files.secrets | length %} | ||
| {% for secret in extra_settings_files.secrets %} | ||
| - name: {{ ansible_operator_meta.name }}-{{ secret.key | replace('_', '-') | replace('.', '-') | lower }}-secret | ||
| secret: | ||
| secretName: {{ secret.name }} | ||
| items: | ||
| - key: {{ secret.key }} | ||
| path: {{ secret.key }} | ||
| {% endfor %} | ||
| {% endif %} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.