internet/awx-operator
3
0
Fork 0
mirror of https://github.com/ansible/awx-operator.git synced 2026-05-07 13:52:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: overall minor renovations (#1874)

Browse Source 
* docs: simplify README.md and make index.md to refer to it
* docs: change order for pages in navigation and add missing pages
* docs: fix headings to improve navigation, transform notes to admonition, fix indentation, linting issues and minor issues
* docs: merge docs for using images from private registries
* docs: add example to integrate LDAP configuration via extra_settings_files
* Apply suggestions from code review
docs: apply suggested changes

Co-authored-by: Don Naro <dnaro@redhat.com>

* docs: update the doc site url as same as the url in https://www.ansible.com/ecosystem/
* docs: minor fixes for hpa page
* docs: expand note block
* docs: apply #1904 to README.md

---------

Co-authored-by: Don Naro <dnaro@redhat.com>
This commit is contained in:
kurokobo
2024-07-21 07:34:21 +09:00
committed by GitHub
parent 36cf9c23ea
commit 2b0221bbc6
51 changed files with 466 additions and 408 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
docs/user-guide/admin-user-account-configuration.md
View File

@@ -1,15 +1,15 @@
### Admin user account configuration
# Admin user account configuration
There are three variables that are customizable for the admin user account creation.
| Name | Description | Default |
| --------------------- | -------------------------------------------- | ---------------- |
| admin_user | Name of the admin user | admin |
| admin_email | Email of the admin user | test@example.com |
| admin_password_secret | Secret that contains the admin user password | Empty string |
| Name | Description | Default |
| --------------------- | -------------------------------------------- | ------------------ |
| admin_user | Name of the admin user | `admin` |
| admin_email | Email of the admin user | `test@example.com` |
| admin_password_secret | Secret that contains the admin user password | Empty string |
> :warning: **admin_password_secret must be a Kubernetes secret and not your text clear password**.
!!! warning
`admin_password_secret` must be a Kubernetes secret and not your text clear password.
If `admin_password_secret` is not provided, the operator will look for a secret named `<resourcename>-admin-password` for the admin password. If it is not present, the operator will generate a password and create a Secret from it named `<resourcename>-admin-password`.
@@ -28,16 +28,16 @@ stringData:
password: mysuperlongpassword
```
### Secret Key Configuration
## Secret Key Configuration
This key is used to encrypt sensitive data in the database.
| Name | Description | Default |
| ----------------- | ----------------------------------------------------- | ---------------- |
| secret_key_secret | Secret that contains the symmetric key for encryption | Generated |
| secret_key_secret | Secret that contains the symmetric key for encryption | Generated |
> :warning: **secret_key_secret must be a Kubernetes secret and not your text clear secret value**.
!!! warning
`secret_key_secret` must be a Kubernetes secret and not your text clear secret value.
If `secret_key_secret` is not provided, the operator will look for a secret named `<resourcename>-secret-key` for the secret key. If it is not present, the operator will generate a password and create a Secret from it named `<resourcename>-secret-key`. It is important to not delete this secret as it will be needed for upgrades and if the pods get scaled down at any point. If you are using a GitOps flow, you will want to pass a secret key secret.

4
docs/user-guide/advanced-configuration/adding-execution-nodes.md
View File

@@ -1,4 +0,0 @@
### Adding Execution Nodes
Starting with AWX Operator v0.30.0 and AWX v21.7.0, standalone execution nodes can be added to your deployments.
See [Managing Capacity With Instances](https://ansible.readthedocs.io/projects/awx/en/latest/administration/instances.html) chapter of the AWX Administration Guide for information about this feature.

8
docs/user-guide/advanced-configuration/assigning-awx-pods-to-specific-nodes.md
View File

@@ -1,4 +1,4 @@
#### Assigning AWX pods to specific nodes
# Assigning AWX pods to specific nodes
You can constrain the AWX pods created by the operator to run on a certain subset of nodes. `node_selector` and `postgres_selector` constrains
the AWX pods to run only on the nodes that match all the specified key/value pairs. `tolerations` and `postgres_tolerations` allow the AWX
@@ -6,8 +6,8 @@ pods to be scheduled onto nodes with matching taints.
The ability to specify topologySpreadConstraints is also allowed through `topology_spread_constraints`
If you want to use affinity rules for your AWX pod you can use the `affinity` option.
If you want to constrain the web and task pods individually, you can do so by specificying the deployment type before the specific setting. For
example, specifying `task_tolerations` will allow the AWX task pod to be scheduled onto nodes with matching taints.
If you want to constrain the web and task pods individually, you can do so by specifying the deployment type before the specific setting. For
example, specifying `task_tolerations` will allow the AWX task pod to be scheduled onto nodes with matching taints.
| Name | Description | Default |
| -------------------------------- | ---------------------------------------- | -------------------------------- |
@@ -89,7 +89,7 @@ spec:
topologyKey: topology.kubernetes.io/zone
```
#### Special Note on DB-Migration Job Scheduling
## Special Note on DB-Migration Job Scheduling
For the **db-migration job**, which applies database migrations at cluster startup, you can specify scheduling settings using the `task_*` configurations such as `task_node_selector`, `task_tolerations`, etc.
If these task-specific settings are not defined, the job will automatically use the global AWX configurations like `node_selector` and `tolerations`.

22
docs/user-guide/advanced-configuration/auto-upgrade.md
View File

@@ -1,10 +1,10 @@
#### Auto upgrade
# Auto upgrade
With this parameter you can influence the behavior during an operator upgrade.
If set to `true`, the operator will upgrade the specific instance directly.
When the value is set to `false`, and we have a running deployment, the operator will not update the AWX instance.
This can be useful when you have multiple AWX instances which you want to upgrade step by step instead of all at once.
| Name | Description | Default |
| -------------| ---------------------------------- | ------- |
| auto_upgrade | Automatic upgrade of AWX instances | true |
@@ -12,11 +12,11 @@ This can be useful when you have multiple AWX instances which you want to upgrad
Example configuration of `auto_upgrade` parameter
```yaml
spec:
auto_upgrade: true
spec:
auto_upgrade: true
```
##### Upgrade of instances without auto upgrade
## Upgrade of instances without auto upgrade
There are two ways to upgrade instances which are marked with the 'auto_upgrade: false' flag.
@@ -28,8 +28,10 @@ Changing flags:
Delete the deployment:
- delete the deployment object of your AWX instance
```
$ kubectl -n awx delete deployment <yourInstanceName>
```
- wait until the instance gets redeployed
- delete the deployment object of your AWX instance
```sh
kubectl -n awx delete deployment <yourInstanceName>
```
- wait until the instance gets redeployed

27
docs/user-guide/advanced-configuration/container-probes.md
View File

@@ -1,19 +1,20 @@
#### Container Probes
# Container Probes
These parameters control the usage of liveness and readiness container probes for
the web and task containers.
> [!ALERT]
> All of probes are disabled by default for now, to enable it, set the *_period parameters. For example:
!!! tip
All of probes are disabled by default for now, to enable it, set the `*_period` parameters. For example:
```
```yaml
spec:
web_liveness_period: 15
web_readiness_period: 15
task_liveness_period: 15
task_readiness_period: 15
```
web_liveness_period: 15
web_readiness_period: 15
task_liveness_period: 15
task_readiness_period: 15
```
#### Web / Task Container Liveness Check
## Web / Task Container Liveness Check
The liveness probe queries the status of the supervisor daemon of the container. The probe will fail if it
detects one of the services in a state other than "RUNNING".
@@ -29,7 +30,7 @@ detects one of the services in a state other than "RUNNING".
| task_liveness_failure_threshold| Number of consecutive failure events to identify failure of container | 3 |
| task_liveness_timeout | Number of seconds to wait for a probe response from container | 1 |
#### Web Container Readiness Check
## Web Container Readiness Check
This is an HTTP check against the status endpoint to confirm the system is still able to respond to web requests.
@@ -40,7 +41,7 @@ This is an HTTP check against the status endpoint to confirm the system is still
| web_readiness_failure_threshold| Number of consecutive failure events to identify failure of container | 3 |
| web_readiness_timeout | Number of seconds to wait for a probe response from container | 1 |
#### Task Container Readiness Check
## Task Container Readiness Check
This is a command probe using the builtin check command of the awx-manage utility.

28
docs/user-guide/advanced-configuration/containers-resource-requirements.md
View File

@@ -1,24 +1,4 @@
#### Containers HostAliases Requirements
Sometimes you might need to use [HostAliases](https://kubernetes.io/docs/tasks/network/customize-hosts-file-for-pods/) in web/task containers.
| Name | Description | Default |
| ------------ | --------------------- | ------- |
| host_aliases | A list of HostAliases | None |
Example of customization could be:
```yaml
---
spec:
...
host_aliases:
- ip: <name-of-your-ip>
hostnames:
- <name-of-your-domain>
```
#### Containers Resource Requirements
# Containers Resource Requirements
The resource requirements for both, the task and the web containers are configurable - both the lower end (requests) and the upper end (limits).
@@ -26,13 +6,12 @@ The resource requirements for both, the task and the web containers are configur
| ------------------------------------ | ------------------------------------------------------------ | ------------------------------------ |
| web_resource_requirements | Web container resource requirements | requests: {cpu: 100m, memory: 128Mi} |
| task_resource_requirements | Task container resource requirements | requests: {cpu: 100m, memory: 128Mi} |
| ee_resource_requirements | EE control plane container resource requirements | requests: {cpu: 50m, memory: 64Mi} |
| ee_resource_requirements | EE control plane container resource requirements | requests: {cpu: 50m, memory: 64Mi} |
| redis_resource_requirements | Redis container resource requirements | requests: {cpu: 100m, memory: 128Mi} |
| postgres_resource_requirements | Postgres container (and initContainer) resource requirements | requests: {cpu: 10m, memory: 64Mi} |
| rsyslog_resource_requirements | Rsyslog container resource requirements | requests: {cpu: 100m, memory: 128Mi} |
| init_container_resource_requirements | Init Container resource requirements | requests: {cpu: 100m, memory: 128Mi} |
Example of customization could be:
```yaml
@@ -86,8 +65,7 @@ spec:
memory: 2Gi
```
#### Limits and ResourceQuotas
## Limits and ResourceQuotas
If the cluster you are deploying in has a ResoruceQuota, you will need to configure resource limits for all of the pods deployed in that cluster. This can be done for AWX pods on the AWX spec in the manner shown above.

6
docs/user-guide/advanced-configuration/csrf-cookie-secure-setting.md
View File

@@ -1,4 +1,4 @@
#### CSRF Cookie Secure Setting
# CSRF Cookie Secure Setting
With `csrf_cookie_secure`, you can pass the value for `CSRF_COOKIE_SECURE` to `/etc/tower/settings.py`
@@ -9,6 +9,6 @@ With `csrf_cookie_secure`, you can pass the value for `CSRF_COOKIE_SECURE` to `/
Example configuration of the `csrf_cookie_secure` setting:
```yaml
spec:
csrf_cookie_secure: 'False'
spec:
csrf_cookie_secure: 'False'
```

6
docs/user-guide/advanced-configuration/custom-receptor-certs.md
View File

@@ -1,5 +1,4 @@
### Custom Receptor CA
# Custom Receptor CA
The control nodes on the K8S cluster will communicate with execution nodes via mutual TLS TCP connections, running via Receptor.
Execution nodes will verify incoming connections by ensuring the x509 certificate was issued by a trusted Certificate Authority (CA).
@@ -21,4 +20,5 @@ If this secret is created after AWX is deployed, run the following to restart th
kubectl rollout restart deployment awx-demo
```
**Important Note**, changing the receptor CA will break connections to any existing execution nodes. These nodes will enter an `unavailable` state, and jobs will not be able to run on them. Users will need to download and re-run the install bundle for each execution node. This will replace the TLS certificate files with those signed by the new CA. The execution nodes should then appear in a `ready` state after a few minutes.
!!! warning
Changing the receptor CA will break connections to any existing execution nodes. These nodes will enter an `unavailable` state, and jobs will not be able to run on them. Users will need to download and re-run the install bundle for each execution node. This will replace the TLS certificate files with those signed by the new CA. The execution nodes should then appear in a `ready` state after a few minutes.

43
docs/user-guide/advanced-configuration/default-execution-environments-from-private-registries.md
View File

@@ -1,43 +0,0 @@
#### Default execution environments from private registries
In order to register default execution environments from private registries, the Custom Resource needs to know about the pull credentials. Those credentials should be stored as a secret and either specified as `ee_pull_credentials_secret` at the CR spec level, or simply be present on the namespace under the name `<resourcename>-ee-pull-credentials` . Instance initialization will register a `Container registry` type credential on the deployed instance and assign it to the registered default execution environments.
The secret should be formatted as follows:
```yaml
---
apiVersion: v1
kind: Secret
metadata:
name: <resourcename>-ee-pull-credentials
namespace: <target namespace>
stringData:
url: <registry url. i.e. quay.io>
username: <username to connect as>
password: <password to connect with>
ssl_verify: <Optional attribute. Whether verify ssl connection or not. Accepted values "True" (default), "False" >
type: Opaque
```
##### Control plane ee from private registry
The images listed in "ee_images" will be added as globally available Execution Environments. The "control_plane_ee_image" will be used to run project updates. In order to use a private image for any of these you'll need to use `image_pull_secrets` to provide a list of k8s pull secrets to access it. Currently the same secret is used for any of these images supplied at install time.
You can create `image_pull_secret`
```
kubectl create secret <resoucename>-cp-pull-credentials regcred --docker-server=<your-registry-server> --docker-username=<your-name> --docker-password=<your-pword> --docker-email=<your-email>
```
If you need more control (for example, to set a namespace or a label on the new secret) then you can customize the Secret before storing it
Example spec file extra-config
```yaml
---
apiVersion: v1
kind: Secret
metadata:
name: <resoucename>-cp-pull-credentials
namespace: <target namespace>
data:
.dockerconfigjson: <base64 docker config>
type: kubernetes.io/dockerconfigjson
```

83
docs/user-guide/advanced-configuration/deploying-a-specific-version-of-awx.md
View File

@@ -1,20 +1,23 @@
#### Deploying a specific version of AWX
# Using images from private registries
There are a few variables that are customizable for awx the image management.
## Available variables to use images from private registries
| Name | Description | Default |
| ----------------------------- | ------------------------- | ------------------------------------------ |
| image | Path of the image to pull | quay.io/ansible/awx |
| image_version | Image version to pull | value of DEFAULT_AWX_VERSION or latest |
| image_pull_policy | The pull policy to adopt | IfNotPresent |
| image_pull_secrets | The pull secrets to use | None |
| ee_images | A list of EEs to register | quay.io/ansible/awx-ee:DEFAULT_AWX_VERSION |
| redis_image | Path of the image to pull | docker.io/redis |
| redis_image_version | Image version to pull | latest |
| control_plane_ee_image | Image version to pull | quay.io/ansible/awx-ee:DEFAULT_AWX_VERSION |
| init_container_image | Path of the image to pull | quay.io/ansible/awx-ee |
| init_container_image_version | Image version to pull | value of DEFAULT_AWX_VERSION or latest |
| init_projects_container_image | Image version to pull | quay.io/centos/centos:stream9 |
There are variables that are customizable for awx the image management.
| Name | Description | Default |
| ----------------------------- | ----------------------------- | ------------------------------------------ |
| image | Path of the image to pull | quay.io/ansible/awx |
| image_version | Image version to pull | value of DEFAULT_AWX_VERSION or latest |
| image_pull_policy | The pull policy to adopt | IfNotPresent |
| image_pull_secrets | The pull secrets to use | None |
| ee_images | A list of EEs to register | quay.io/ansible/awx-ee:DEFAULT_AWX_VERSION |
| ee_pull_credentials_secret | The pull secret for ee_images | None |
| redis_image | Path of the image to pull | docker.io/redis |
| redis_image_version | Image version to pull | latest |
| control_plane_ee_image | Image version to pull | quay.io/ansible/awx-ee:DEFAULT_AWX_VERSION |
| init_container_image | Path of the image to pull | quay.io/ansible/awx-ee |
| init_container_image_version | Image version to pull | value of DEFAULT_AWX_VERSION or latest |
| init_projects_container_image | Image version to pull | quay.io/centos/centos:stream9 |
Example of customization could be:
@@ -36,4 +39,52 @@ spec:
init_projects_container_image: myorg/my-mirrored-centos:stream9
```
**Note**: The `image` and `image_version` are intended for local mirroring scenarios. Please note that using a version of AWX other than the one bundled with the `awx-operator` is **not** supported. For the default values, check the [main.yml](https://github.com/ansible/awx-operator/blob/devel/roles/installer/defaults/main.yml) file.
!!! warning
The `image` and `image_version` are intended for local mirroring scenarios. Please note that using a version of AWX other than the one bundled with the `awx-operator` is **not** supported. For the default values, check the [main.yml](https://github.com/ansible/awx-operator/blob/devel/roles/installer/defaults/main.yml) file.
## Default execution environments from private registries
In order to register default execution environments from private registries, the Custom Resource needs to know about the pull credentials. Those credentials should be stored as a secret and either specified as `ee_pull_credentials_secret` at the CR spec level, or simply be present on the namespace under the name `<resourcename>-ee-pull-credentials` . Instance initialization will register a `Container registry` type credential on the deployed instance and assign it to the registered default execution environments.
The secret should be formatted as follows:
```yaml
---
apiVersion: v1
kind: Secret
metadata:
name: <resourcename>-ee-pull-credentials
namespace: <target namespace>
stringData:
url: <registry url. i.e. quay.io>
username: <username to connect as>
password: <password to connect with>
ssl_verify: <Optional attribute. Whether verify ssl connection or not. Accepted values "True" (default), "False" >
type: Opaque
```
## Control plane ee from private registry
The images listed in `ee_images` will be added as globally available Execution Environments. The `control_plane_ee_image` will be used to run project updates. In order to use a private image for any of these you'll need to use `image_pull_secrets` to provide a list of k8s pull secrets to access it. Currently the same secret is used for any of these images supplied at install time.
You can create `image_pull_secret`
```sh
kubectl create secret <resoucename>-cp-pull-credentials regcred --docker-server=<your-registry-server> --docker-username=<your-name> --docker-password=<your-pword> --docker-email=<your-email>
```
If you need more control (for example, to set a namespace or a label on the new secret) then you can customize the Secret before storing it
Example spec file extra-config
```yaml
---
apiVersion: v1
kind: Secret
metadata:
name: <resoucename>-cp-pull-credentials
namespace: <target namespace>
data:
.dockerconfigjson: <base64 docker config>
type: kubernetes.io/dockerconfigjson
```

7
docs/user-guide/advanced-configuration/disable-ipv6.md
View File

@@ -1,12 +1,13 @@
### Disable IPV6
Starting with AWX Operator release 0.24.0,[IPV6 was enabled in ngnix configuration](https://github.com/ansible/awx-operator/pull/950) which causes
# Disable IPv6
Starting with AWX Operator release 0.24.0, [IPv6 was enabled in ngnix configuration](https://github.com/ansible/awx-operator/pull/950) which causes
upgrades and installs to fail in environments where IPv6 is not allowed. Starting in 1.1.1 release, you can set the `ipv6_disabled` flag on the AWX
spec. If you need to use an AWX operator version between 0.24.0 and 1.1.1 in an IPv6 disabled environment, it is suggested to enabled ipv6 on worker
nodes.
In order to disable ipv6 on ngnix configuration (awx-web container), add following to the AWX spec.
The following variables are customizable
The following variables are customizable:
| Name | Description | Default |
| ------------- | ---------------------- | ------- |

94
docs/user-guide/advanced-configuration/enabling-ldap-integration-at-awx-bootstrap.md
View File

@@ -1,10 +1,97 @@
#### Enabling LDAP Integration at AWX bootstrap
# Enabling LDAP Integration at AWX bootstrap
A sample of extra settings can be found as below. All possible options can be found here: https://django-auth-ldap.readthedocs.io/en/latest/reference.html#settings
A sample of extra settings can be found as below. All possible options can be found here: <https://django-auth-ldap.readthedocs.io/en/latest/reference.html#settings>
> **NOTE:** These values are inserted into a Python file, so pay close attention to which values need quotes and which do not.
Refer to the [Extra Settings](./extra-settings.md) page for more information on how to configure extra settings.
!!! tip
To trust a custom Certificate Authority for your LDAP server, or to specify password LDAP bind DN, refer to the [Trusting a Custom Certificate Authority](./trusting-a-custom-certificate-authority.md) page.
## Configure LDAP integration via `extra_settings_files`
Create a Python file with arbitrary name, e.g. `custom_ldap_settings.py`, and add the following content for example:
```python title="custom_ldap_settings.py"
AUTH_LDAP_SERVER_URI = "ldaps://ad01.abc.com:636 ldaps://ad02.abc.com:636"
AUTH_LDAP_BIND_DN = "CN=LDAP User,OU=Service Accounts,DC=abc,DC=com"
AUTH_LDAP_USER_SEARCH = LDAPSearch(
"DC=abc,DC=com",
ldap.SCOPE_SUBTREE,
"(sAMAccountName=%(user)s)",
)
AUTH_LDAP_GROUP_SEARCH = LDAPSearch(
"OU=Groups,DC=abc,DC=com",
ldap.SCOPE_SUBTREE,
"(objectClass=group)",
)
AUTH_LDAP_GROUP_TYPE = GroupOfNamesType()
AUTH_LDAP_USER_ATTR_MAP = {
"first_name": "givenName",
"last_name": "sn",
"email": "mail",
}
AUTH_LDAP_REQUIRE_GROUP = "CN=operators,OU=Groups,DC=abc,DC=com"
AUTH_LDAP_USER_FLAGS_BY_GROUP = {
"is_superuser": ["CN=admin,OU=Groups,DC=abc,DC=com"],
}
AUTH_LDAP_ORGANIZATION_MAP = {
"abc": {
"admins": "CN=admin,OU=Groups,DC=abc,DC=com",
"remove_admins": False,
"remove_users": False,
"users": True,
}
}
AUTH_LDAP_TEAM_MAP = {
"admin": {
"organization": "abc",
"remove": True,
"users": "CN=admin,OU=Groups,DC=abc,DC=com",
}
}
```
Create a ConfigMap with the content of the above Python file.
```bash
kubectl create configmap custom-ldap-settings \
--from-file /PATH/TO/YOUR/custom_ldap_settings.py
```
Then specify this ConfigMap to the `extra_settings_files` parameter.
```yaml
spec:
extra_settings_files:
configmaps:
- name: custom-ldap-settings
key: custom_ldap_settings.py
```
!!! note
If you have embedded some sensitive information like passwords in the Python file, you can create and pass a Secret instead of a ConfigMap.
```bash
kubectl create secret generic custom-ldap-settings \
--from-file /PATH/TO/YOUR/custom_ldap_settings.py
```
```yaml
spec:
extra_settings_files:
secrets:
- name: custom-ldap-settings
key: custom_ldap_settings.py
```
## Configure LDAP integration via `extra_settings`
!!! note
These values are inserted into a Python file, so pay close attention to which values need quotes and which do not.
```yaml
spec:
extra_settings:
- setting: AUTH_LDAP_SERVER_URI
value: >-
"ldaps://ad01.abc.com:636 ldaps://ad02.abc.com:636"
@@ -35,7 +122,6 @@ A sample of extra settings can be found as below. All possible options can be fo
]
}
- setting: AUTH_LDAP_ORGANIZATION_MAP
value: {
"abc": {

5
docs/user-guide/advanced-configuration/exporting-environment-variables-to-containers.md
View File

@@ -1,4 +1,4 @@
#### Exporting Environment Variables to Containers
# Exporting Environment Variables to Containers
If you need to export custom environment variables to your containers.
@@ -9,7 +9,8 @@ If you need to export custom environment variables to your containers.
| rsyslog_extra_env | Environment variables to be added to Rsyslog container | '' |
| ee_extra_env | Environment variables to be added to EE container | '' |
> :warning: The `ee_extra_env` will only take effect to the globally available Execution Environments. For custom `ee`, please [customize the Pod spec](https://docs.ansible.com/ansible-tower/latest/html/administration/external_execution_envs.html#customize-the-pod-spec).
!!! warning
The `ee_extra_env` will only take effect to the globally available Execution Environments. For custom `ee`, please [customize the Pod spec](https://docs.ansible.com/ansible-tower/latest/html/administration/external_execution_envs.html#customize-the-pod-spec).
Example configuration of environment variables

15
docs/user-guide/advanced-configuration/horizontal-pod-autoscaler.md
View File

@@ -1,4 +1,4 @@
### Horizontal Pod Autoscaler (HPA)
# Horizontal Pod Autoscaler (HPA)
Horizontal Pod Autoscaler allows Kubernetes to scale the number of replicas of
deployments in response to configured metrics.
@@ -10,15 +10,12 @@ The use of the settings below will tell the operator to not manage the replicas
field on the identified deployments even if a replicas count has been set for those
properties in the operator resource.
| Name | Description | Default |
| -----------------------| ----------------------------------------- | ------- |
| web_manage_replicas | Indicates operator should control the | true |
| | replicas count for the web deployment. | |
| | | |
| task_manage_replicas | Indicates operator should control the | true |
| | replicas count for the task deployment. | |
| Name | Description | Default |
| ---------------------- | ----------------------------------------------------------------------------- | ------- |
| web_manage_replicas | Indicates operator should control the replicas count for the web deployment. | true |
| task_manage_replicas | Indicates operator should control the replicas count for the task deployment. | true |
#### Recommended Settings for HPA
## Recommended Settings for HPA
Please see the Kubernetes documentation on how to configure the horizontal pod
autoscaler.

19
docs/user-guide/advanced-configuration/host-aliases.md Normal file
View File

@@ -0,0 +1,19 @@
# HostAliases
Sometimes you might need to use [HostAliases](https://kubernetes.io/docs/tasks/network/customize-hosts-file-for-pods/) in web/task containers.
| Name | Description | Default |
| ------------ | --------------------- | ------- |
| host_aliases | A list of HostAliases | None |
Example of customization could be:
```yaml
---
spec:
...
host_aliases:
- ip: <name-of-your-ip>
hostnames:
- <name-of-your-domain>
```

0
docs/user-guide/advanced-configuration/mesh-ingress-instance-listener-address-on-awx-ui.png → docs/user-guide/advanced-configuration/images/mesh-ingress-instance-listener-address-on-awx-ui.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 162 KiB

After

Width:  |  Height:  |  Size: 162 KiB

0
docs/user-guide/advanced-configuration/mesh-ingress-instance-on-awx-ui.png → docs/user-guide/advanced-configuration/images/mesh-ingress-instance-on-awx-ui.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 162 KiB

After

Width:  |  Height:  |  Size: 162 KiB

0
docs/user-guide/advanced-configuration/peering-to-mesh-ingress-on-awx-ui.png → docs/user-guide/advanced-configuration/images/peering-to-mesh-ingress-on-awx-ui.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 205 KiB

After

Width:  |  Height:  |  Size: 205 KiB

14
docs/user-guide/advanced-configuration/labeling-operator-managed-objects.md
View File

@@ -1,15 +1,13 @@
#### Labeling operator managed objects
# Labeling operator managed objects
In certain situations labeling of Kubernetes objects managed by the operator
might be desired (e.g. for owner identification purposes). For that
`additional_labels` parameter could be used
In certain situations labeling of Kubernetes objects managed by the operator might be desired (e.g. for owner identification purposes).
For that `additional_labels` parameter could be used:
| Name | Description | Default |
| --------------------------- | ---------------------------------------------------------------------------------------- | ------- |
| additional_labels | Additional labels defined on the resource, which should be propagated to child resources | [] |
Example configuration where only `my/team` and `my/service` labels will be
propagated to child objects (`Deployment`, `Secret`s, `ServiceAccount`, etc):
Example configuration where only `my/team` and `my/service` labels will be propagated to child objects (`Deployment`, `Secret`s, `ServiceAccount`, etc):
```yaml
apiVersion: awx.ansible.com/v1beta1
@@ -22,7 +20,7 @@ metadata:
my/do-not-inherit: "yes"
spec:
additional_labels:
- my/team
- my/service
- my/team
- my/service
...
```

6
docs/user-guide/advanced-configuration/mesh-ingress.md
View File

@@ -168,7 +168,7 @@ spec:
After AWXMeshIngress has been successfully created, a new Instance with the same name will be registered to AWX and will be visible on the Instance UI page
![mesh ingress instance on AWX UI](mesh-ingress-instance-on-awx-ui.png)
![mesh ingress instance on AWX UI](./images/mesh-ingress-instance-on-awx-ui.png)
The Instance should have at least 2 listener addresses.
@@ -177,10 +177,10 @@ In this example, the mesh ingress has two listener addresses:
- one for internal, that is used for peering to by all control nodes (top)
- one for external, that is exposed to a route so external execution nodes can peer into it (bottom))
![mesh ingress instance listener address on awx ui](mesh-ingress-instance-listener-address-on-awx-ui.png)
![mesh ingress instance listener address on awx ui](./images/mesh-ingress-instance-listener-address-on-awx-ui.png)
When selecting peer for new instance the mesh ingress instance should now be present as a option.
![peering to mesh ingress on awx ui](peering-to-mesh-ingress-on-awx-ui.png)
![peering to mesh ingress on awx ui](./images/peering-to-mesh-ingress-on-awx-ui.png)
For more information about how to create external remote execution and hop nodes and configuring the mesh, see AWX Documentation on [Add a instance](https://ansible.readthedocs.io/projects/awx/en/latest/administration/instances.html#add-an-instance).

7
docs/user-guide/advanced-configuration/no-log.md
View File

@@ -1,4 +1,5 @@
#### No Log
# No Log
Configure no_log for tasks with no_log
| Name | Description | Default |
@@ -8,6 +9,6 @@ Configure no_log for tasks with no_log
Example configuration of `no_log` parameter
```yaml
spec:
no_log: true
spec:
no_log: true
```

2
docs/user-guide/advanced-configuration/persisting-projects-directory.md
View File

@@ -1,4 +1,4 @@
#### Persisting Projects Directory
# Persisting Projects Directory
In cases which you want to persist the `/var/lib/projects` directory, there are few variables that are customizable for the `awx-operator`.

41
docs/user-guide/advanced-configuration/pods-termination-grace-period.md
View File

@@ -1,38 +1,17 @@
#### Pods termination grace period
# Pods termination grace period
During deployment restarts or new rollouts, when old ReplicaSet Pods are being
terminated, the corresponding jobs which are managed (executed or controlled)
by old AWX Pods may end up in `Error` state as there is no mechanism to
transfer them to the newly spawned AWX Pods. To work around the problem one
could set `termination_grace_period_seconds` in AWX spec, which does the
following:
During deployment restarts or new rollouts, when old ReplicaSet Pods are being terminated, the corresponding jobs which are managed (executed or controlled) by old AWX Pods may end up in `Error` state as there is no mechanism to transfer them to the newly spawned AWX Pods.
To work around the problem one could set `termination_grace_period_seconds` in AWX spec, which does the following:
* It sets the corresponding
[`terminationGracePeriodSeconds`](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination)
Pod spec of the AWX Deployment to the value provided
- It sets the corresponding [`terminationGracePeriodSeconds`](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination) Pod spec of the AWX Deployment to the value provided
- The grace period is the duration in seconds after the processes running in the pod are sent a termination signal and the time when the processes are forcibly halted with a kill signal
> The grace period is the duration in seconds after the processes running in
> the pod are sent a termination signal and the time when the processes are
> forcibly halted with a kill signal
* It adds a
[`PreStop`](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#hook-handler-execution)
hook script, which will keep AWX Pods in terminating state until it finished,
up to `terminationGracePeriodSeconds`.
> This grace period applies to the total time it takes for both the PreStop
> hook to execute and for the Container to stop normally
While the hook script just waits until the corresponding AWX Pod (instance)
no longer has any managed jobs, in which case it finishes with success and
hands over the overall Pod termination process to normal AWX processes.
One may want to set this value to the maximum duration they accept to wait for
the affected Jobs to finish. Keeping in mind that such finishing jobs may
increase Pods termination time in such situations as `kubectl rollout restart`,
AWX upgrade by the operator, or Kubernetes [API-initiated
evictions](https://kubernetes.io/docs/concepts/scheduling-eviction/api-eviction/).
- It adds a [`PreStop`](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#hook-handler-execution) hook script, which will keep AWX Pods in terminating state until it finished, up to `terminationGracePeriodSeconds`.
- This grace period applies to the total time it takes for both the PreStop hook to execute and for the Container to stop normally
- While the hook script just waits until the corresponding AWX Pod (instance) no longer has any managed jobs, in which case it finishes with success and hands over the overall Pod termination process to normal AWX processes.
One may want to set this value to the maximum duration they accept to wait for the affected Jobs to finish.
Keeping in mind that such finishing jobs may increase Pods termination time in such situations as `kubectl rollout restart`, AWX upgrade by the operator, or Kubernetes [API-initiatedevictions](https://kubernetes.io/docs/concepts/scheduling-eviction/api-eviction/).
| Name | Description | Default |
| -------------------------------- | --------------------------------------------------------------- | ------- |

7
docs/user-guide/advanced-configuration/priority-classes.md
View File

@@ -1,15 +1,10 @@
#### Priority Classes
# Priority Classes
The AWX and Postgres pods can be assigned a custom PriorityClass to rank their importance compared to other pods in your cluster, which determines which pods get evicted first if resources are running low.
First, [create your PriorityClass](https://kubernetes.io/docs/concepts/scheduling-eviction/pod-priority-preemption/#priorityclass) if needed.
Then set the name of your priority class to the control plane and postgres pods as shown below.
```yaml
---
apiVersion: awx.ansible.com/v1beta1
kind: AWX
metadata:
name: awx-demo
spec:
...
control_plane_priority_class: awx-demo-high-priority

6
docs/user-guide/advanced-configuration/privileged-tasks.md
View File

@@ -1,4 +1,4 @@
#### Privileged Tasks
# Privileged Tasks
Depending on the type of tasks that you'll be running, you may find that you need the task pod to run as `privileged`. This can open yourself up to a variety of security concerns, so you should be aware (and verify that you have the privileges) to do this if necessary. In order to toggle this feature, you can add the following to your custom resource:
@@ -11,8 +11,8 @@ spec:
If you are attempting to do this on an OpenShift cluster, you will need to grant the `awx` ServiceAccount the `privileged` SCC, which can be done with:
```
$ oc adm policy add-scc-to-user privileged -z awx
```sh
oc adm policy add-scc-to-user privileged -z awx
```
Again, this is the most relaxed SCC that is provided by OpenShift, so be sure to familiarize yourself with the security concerns that accompany this action.

2
docs/user-guide/advanced-configuration/redis-container-capabilities.md
View File

@@ -1,4 +1,4 @@
#### Redis container capabilities
# Redis container capabilities
Depending on your kubernetes cluster and settings you might need to grant some capabilities to the redis container so it can start. Set the `redis_capabilities` option so the capabilities are added in the deployment.

6
docs/user-guide/advanced-configuration/scaling-the-web-and-task-pods-independently.md
View File

@@ -1,4 +1,4 @@
#### Scaling the Web and Task Pods independently
# Scaling the Web and Task Pods independently
You can scale replicas up or down for each deployment by using the `web_replicas` or `task_replicas` respectively. You can scale all pods across both deployments by using `replicas` as well. The logic behind these CRD keys acts as such:
@@ -7,7 +7,7 @@ You can scale replicas up or down for each deployment by using the `web_replicas
These new replicas can be constrained in a similar manner to previous single deployments by appending the particular deployment name in front of the constraint used. More about those new constraints can be found in the [Assigning AWX pods to specific nodes](./assigning-awx-pods-to-specific-nodes.md) page.
##### Horizontal Pod Autoscaling
## Horizontal Pod Autoscaling
The operator is capable of working with Kubernete's HPA capabilities. See [Horizontal Pod Autoscaler](./horizontal-pod-autoscaler.md)
The operator is capable of working with Kubernetes' HPA capabilities. See [Horizontal Pod Autoscaler](./horizontal-pod-autoscaler.md)
documentation for more information.

10
docs/user-guide/advanced-configuration/security-context.md
View File

@@ -1,12 +1,11 @@
#### Service Account
# Security Context
It is possible to modify some `SecurityContext` proprieties of the various deployments and stateful sets if needed.
| Name | Description | Default |
| ---------------------------------- | -------------------------------------------- | ------- |
| security_context_settings | SecurityContext for Task and Web deployments | {} |
| postgres_security_context_settings | SecurityContext for Task and Web deployments | {} |
| postgres_security_context_settings | SecurityContext for PostgreSQL container | {} |
Example configuration securityContext for the Task and Web deployments:
@@ -17,11 +16,6 @@ spec:
capabilities:
drop:
- ALL
```
```yaml
spec:
postgres_security_context_settings:
runAsNonRoot: true
```

8
docs/user-guide/advanced-configuration/service-account.md
View File

@@ -1,4 +1,4 @@
#### Service Account
# Service Account
If you need to modify some `ServiceAccount` proprieties
@@ -9,7 +9,7 @@ If you need to modify some `ServiceAccount` proprieties
Example configuration of environment variables
```yaml
spec:
service_account_annotations: |
eks.amazonaws.com/role-arn: arn:aws:iam::<ACCOUNT_ID>:role/<IAM_ROLE_NAME>
spec:
service_account_annotations: |
eks.amazonaws.com/role-arn: arn:aws:iam::<ACCOUNT_ID>:role/<IAM_ROLE_NAME>
```

2
docs/user-guide/advanced-configuration/session-cookie-secure-setting.md
View File

@@ -1,4 +1,4 @@
#### Session Cookie Secure Setting
# Session Cookie Secure Setting
With `session_cookie_secure`, you can pass the value for `SESSION_COOKIE_SECURE` to `/etc/tower/settings.py`

26
docs/user-guide/advanced-configuration/trusting-a-custom-certificate-authority.md
View File

@@ -1,15 +1,15 @@
#### Trusting a Custom Certificate Authority
# Trusting a Custom Certificate Authority
In cases which you need to trust a custom Certificate Authority, there are few variables you can customize for the `awx-operator`.
Trusting a custom Certificate Authority allows the AWX to access network services configured with SSL certificates issued locally, such as cloning a project from from an internal Git server via HTTPS. It is common for these scenarios, experiencing the error [unable to verify the first certificate](https://github.com/ansible/awx-operator/issues/376).
| Name | Description | Default |
| -------------------------------- | ---------------------------------------- | --------|
| ldap_cacert_secret | LDAP Certificate Authority secret name | '' |
| ldap_password_secret | LDAP BIND DN Password secret name | '' |
| bundle_cacert_secret | Certificate Authority secret name | '' |
Please note the `awx-operator` will look for the data field `ldap-ca.crt` in the specified secret when using the `ldap_cacert_secret`, whereas the data field `bundle-ca.crt` is required for `bundle_cacert_secret` parameter.
Example of customization could be:
@@ -26,15 +26,13 @@ spec:
Create the secret with `kustomization.yaml` file:
```yaml
....
...
secretGenerator:
- name: <resourcename>-custom-certs
files:
- bundle-ca.crt=<path+filename>
options:
disableNameSuffixHash: true
...
```
@@ -42,15 +40,15 @@ Create the secret with CLI:
* Certificate Authority secret
```
# kubectl create secret generic <resourcename>-custom-certs \
--from-file=ldap-ca.crt=<PATH/TO/YOUR/CA/PEM/FILE> \
--from-file=bundle-ca.crt=<PATH/TO/YOUR/CA/PEM/FILE>
```
```sh
kubectl create secret generic <resourcename>-custom-certs \
--from-file=ldap-ca.crt=<PATH/TO/YOUR/CA/PEM/FILE> \
--from-file=bundle-ca.crt=<PATH/TO/YOUR/CA/PEM/FILE>
```
* LDAP BIND DN Password secret
```
# kubectl create secret generic <resourcename>-ldap-password \
--from-literal=ldap-password=<your_ldap_dn_password>
```
```sh
kubectl create secret generic <resourcename>-ldap-password \
--from-literal=ldap-password=<your_ldap_dn_password>
```

29
docs/user-guide/database-configuration.md
View File

@@ -1,16 +1,15 @@
### Database Configuration
# Database Configuration
#### PostgreSQL Version
## PostgreSQL Version
The default PostgreSQL version for the version of AWX bundled with the latest version of the awx-operator is PostgreSQL 15. You can find this default for a given version by at the default value for [supported_pg_version](https://github.com/ansible/awx-operator/blob/ffba1b4712a0b03f1faedfa70e3a9ef0d443e4a6/roles/installer/vars/main.yml#L7).
We only have coverage for the default version of PostgreSQL. Newer versions of PostgreSQL will likely work, but should only be configured as an external database. If your database is managed by the awx-operator (default if you don't specify a `postgres_configuration_secret`), then you should not override the default version as this may cause issues when awx-operator tries to upgrade your postgresql pod.
#### External PostgreSQL Service
## External PostgreSQL Service
To configure AWX to use an external database, the Custom Resource needs to know about the connection details. To do this, create a k8s secret with those connection details and specify the name of the secret as `postgres_configuration_secret` at the CR spec level.
The secret should be formatted as follows:
```yaml
@@ -32,13 +31,16 @@ stringData:
type: Opaque
```
> Please ensure that the value for the variable `password` should _not_ contain single or double quotes (`'`, `"`) or backslashes (`\`) to avoid any issues during deployment, [backup](https://github.com/ansible/awx-operator/tree/devel/roles/backup) or [restoration](https://github.com/ansible/awx-operator/tree/devel/roles/restore).
!!! warning
Please ensure that the value for the variable `password` should _not_ contain single or double quotes (`'`, `"`) or backslashes (`\`) to avoid any issues during deployment, [backup](https://github.com/ansible/awx-operator/tree/devel/roles/backup) or [restoration](https://github.com/ansible/awx-operator/tree/devel/roles/restore).
> It is possible to set a specific username, password, port, or database, but still have the database managed by the operator. In this case, when creating the postgres-configuration secret, the `type: managed` field should be added.
!!! tip
It is possible to set a specific username, password, port, or database, but still have the database managed by the operator. In this case, when creating the postgres-configuration secret, the `type: managed` field should be added.
**Note**: The variable `sslmode` is valid for `external` databases only. The allowed values are: `prefer`, `disable`, `allow`, `require`, `verify-ca`, `verify-full`.
!!! note
The variable `sslmode` is valid for `external` databases only. The allowed values are: `prefer`, `disable`, `allow`, `require`, `verify-ca`, `verify-full`.
**Note**: The variable `target_session_attrs` is only useful for `clustered external` databases. The allowed values are: `any` (default), `read-write`, `read-only`, `primary`, `standby` and `prefer-standby`, whereby only `read-write` and `primary` really make sense in AWX use, as you want to connect to a database node that offers write support.
The variable `target_session_attrs` is only useful for `clustered external` databases. The allowed values are: `any` (default), `read-write`, `read-only`, `primary`, `standby` and `prefer-standby`, whereby only `read-write` and `primary` really make sense in AWX use, as you want to connect to a database node that offers write support.
Once the secret is created, you can specify it on your spec:
@@ -49,11 +51,11 @@ spec:
postgres_configuration_secret: <name-of-your-secret>
```
#### Migrating data from an old AWX instance
## Migrating data from an old AWX instance
For instructions on how to migrate from an older version of AWX, see [migration.md](../migration/migration.md).
#### Managed PostgreSQL Service
## Managed PostgreSQL Service
If you don't have access to an external PostgreSQL service, the AWX operator can deploy one for you along side the AWX instance itself.
@@ -92,9 +94,10 @@ spec:
- 'max_connections=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.
!!! 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.
#### Note about overriding the postgres image
## 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).
@@ -102,7 +105,7 @@ You can no longer configure a custom `postgres_data_path` because it is hardcode
If you override the postgres image to use a custom postgres image like postgres:15 for example, the default data directory path may be different. These images cannot be used interchangeably.
#### Initialize Postgres data volume
## Initialize Postgres data volume
When using a hostPath backed PVC and some other storage classes like longhorn storagfe, the postgres data directory needs to be accessible by the user in the postgres pod (UID 26).

17
docs/user-guide/network-and-tls-configuration.md
View File

@@ -1,6 +1,6 @@
### Network and TLS Configuration
# Network and TLS Configuration
#### Service Type
## Service Type
If the `service_type` is not specified, the `ClusterIP` service will be used for your AWX Tower service.
@@ -24,7 +24,7 @@ spec:
environment: testing
```
* LoadBalancer
### LoadBalancer
The following variables are customizable only when `service_type=LoadBalancer`
@@ -54,7 +54,7 @@ When setting up a Load Balancer for HTTPS you will be required to set the `loadb
The HTTPS Load Balancer also uses SSL termination at the Load Balancer level and will offload traffic to AWX over HTTP.
* NodePort
### NodePort
The following variables are customizable only when `service_type=NodePort`
@@ -69,7 +69,8 @@ spec:
service_type: NodePort
nodeport_port: 30080
```
#### Ingress Type
## Ingress Type
By default, the AWX operator is not opinionated and won't force a specific ingress type on you. So, when the `ingress_type` is not specified, it will default to `none` and nothing ingress-wise will be created.
@@ -84,7 +85,7 @@ spec:
ingress_type: none
```
* Generic Ingress Controller
### Generic Ingress Controller
The following variables are customizable when `ingress_type=ingress`. The `ingress` type creates an Ingress resource as [documented](https://kubernetes.io/docs/concepts/services-networking/ingress/) which can be shared with many other Ingress Controllers as [listed](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/).
@@ -112,7 +113,7 @@ spec:
environment: testing
```
##### Specialized Ingress Controller configuration
### Specialized Ingress Controller configuration
Some Ingress Controllers need a special configuration to fully support AWX, add the following value with the `ingress_controller` variable, if you are using one of these:
@@ -132,7 +133,7 @@ spec:
ingress_controller: contour
```
* Route
### Route
The following variables are customizable when `ingress_type=route`