Documentation

9. Advanced Configurations for AWX Operator

This section contains reference information associated with advanced options available for you to configure your controller image:

9.1. Deploy a specific version of AWX

You can configure the following variables to deploy a specific version of your controller image:

Name

Description

image

Path of the image to pull

image_version

Image version to pull

image_pull_policy

The pull policy to adopt

image_pull_secret

The pull secret to use

ee_images

A list of EEs to register

redis_image

Path of the image to pull

redis_image_version

Image version to pull

Example of a custom configuration for deploying a specific version:

---
spec:
  ...
  image: myorg/my-custom-awx
  image_version: latest
  image_pull_policy: Always
  image_pull_secret: pull_secret_name
  ee_images:
    - name: my-custom-awx-ee
      image: myorg/my-custom-awx-ee

Note

The image and image_version are intended for local mirroring scenarios. Using a version of the controller other than the one bundled with the awx-operator is not supported. For the default values, check the main.yml file.

9.2. Set privileged tasks

Depending on the type of tasks that you will 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:

---
spec:
  ...
  task_privileged: true

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

Warning

Use at your own risk as this is the most relaxed SCC that is provided by OpenShift. Be sure to familiarize yourself with the security concerns that accompany this action.

9.3. Configure resource requirements

You can configure both the resource requirements for the task and the web containers - both the lower end (requests) and the upper end (limits).

Name

Description

Default

web_resource_requirements

Web container resource requirements

requests: {cpu: 1000m, memory: 2Gi}

task_resource_requirements

Task container resource requirements

requests: {cpu: 500m, memory: 1Gi}

ee_resource_requirements

EE control plane container resource requirements

requests: {cpu: 500m, memory: 1Gi}

Example of a custom configuration for resource requirements:

---
spec:
  ...
  web_resource_requirements:
    requests:
      cpu: 1000m
      memory: 2Gi
    limits:
      cpu: 2000m
      memory: 4Gi
  task_resource_requirements:
    requests:
      cpu: 500m
      memory: 1Gi
    limits:
      cpu: 1000m
      memory: 2Gi
  ee_resource_requirements:
    requests:
      cpu: 500m
      memory: 1Gi
    limits:
      cpu: 1000m
      memory: 2Gi

9.4. Assign pods to specific nodes

You can constrain the controller pods created by the operator to run on a certain subset of nodes.

  • node_selector and postgres_selector constrains the controller pods to run only on the nodes that match all the specified key/value pairs

  • tolerations and postgres_tolerations allow the controller pods to be scheduled onto nodes with matching taints. Refer to Taints and Tolerations in the Kubernetes documentation for further detail.

Name

Description

Default

postgres_image

Path of the image to pull

12

postgres_image_version

Image version to pull

12

node_selector

AWX pods’ nodeSelector

‘’

tolerations

AWX pods’ tolerations

‘’

postgres_selector

Postgres pods’ nodeSelector

‘’

postgres_tolerations

Postgres pods’ tolerations

‘’

Example of a custom configuration for constraining controller pods to specific nodes:

        ---
spec:
  ...
  node_selector: |
    disktype: ssd
    kubernetes.io/arch: amd64
    kubernetes.io/os: linux
  tolerations: |
    - key: "dedicated"
      operator: "Equal"
      value: "AWX"
      effect: "NoSchedule"
  postgres_selector: |
    disktype: ssd
    kubernetes.io/arch: amd64
    kubernetes.io/os: linux
  postgres_tolerations: |
    - key: "dedicated"
      operator: "Equal"
      value: "AWX"
      effect: "NoSchedule"

9.5. Trust a custom Certificate Authority

In cases which you need to trust a custom Certificate Authority (CA), there are few variables you can customize for the awx-operator.

Trusting a custom Certificate Authority allows the controller to access network services configured with SSL certificates issued locally, such as cloning a project from an internal Git server via HTTPS. It is common for these scenarios, experiencing the error unable to verify the first certificate.

Name

Description

Default

ldap_cacert_secret

LDAP Certificate Authority secret name

‘’

bundle_cacert_secret

Certificate Authority secret name

‘’

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 a custom configuration for trusting a CA:

---
spec:
  ...
  ldap_cacert_secret: <resourcename>-custom-certs
  bundle_cacert_secret: <resourcename>-custom-certs

To create the secret, use the command below:

# kubectl create secret generic <resourcename>-custom-certs \
    --from-file=ldap-ca.crt=<PATH/TO/YOUR/CA/PEM/FILE>  \
    --from-fle=bundle-ca.crt=<PATH/TO/YOUR/CA/PEM/FILE>

9.6. Persist projects directory

In cases when you want to persist the /var/lib/projects directory, use these variables to customize this for the awx-operator:

Name

Description

Default

projects_persistence

Whether or not the /var/lib/projects directory will be persistent

false

projects_storage_class

Define the PersistentVolume storage class

‘’

projects_storage_size

Define the PersistentVolume size

8Gi

projects_storage_access_mode

Define the PersistentVolume access mode

ReadWriteMany

projects_existing_claim

Define an existing PersistentVolumeClaim to use (cannot be combined with projects_storage_*)

‘’

Example of a custom configuration for when the awx-operator automatically handles the persistent volume:

---
spec:
  ...
  projects_persistence: true
  projects_storage_class: rook-ceph
  projects_storage_size: 20Gi

9.7. Configure custom volume options

In cases where custom volumes and volume mounts are required to either overwrite defaults or mount configuration files, use the following variables to configure those values:

Name

Description

Default

extra_volumes

Specify extra volumes to add to the application pod

web_extra_volume_mounts

Specify volume mounts to add to the Web container

task_extra_volume_mounts

Specify volume mounts to add to the Task container

ee_extra_volume_mounts

Specify volume mounts to add to the Execution container

Note

The extra_volumes and ee_extra_volume_mounts variables will only take effect to the globally available execution environments. For custom execution environments, see the section to Customize the Pod spec.

See an example of a spec file for volumes and volume mounts in a subsequent section.

9.8. Register 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 must be formatted as follows:

---
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

9.8.1. Control plane ee from private registries

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 will need to use image_pull_secret to provide a k8s pull secret to access it. Currently, the same secret is used for any of these images supplied at install time.

You can create an image_pull_secret using the command below:

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), you can customize the Secret before storing it:

---
apiVersion: v1
kind: Secret
metadata:
  name: <resoucename>-cp-pull-credentials
  namespace: <target namespace>
data:
  .dockerconfigjson: <base64 docker config>
type: kubernetes.io/dockerconfigjson

Example of a spec file for extra-config:

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: <resourcename>-extra-config
  namespace: <target namespace>
data:
  ansible.cfg: |
     [defaults]
     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 of a spec file for volumes and volume mounts:

---
    spec:
    ...
      ee_extra_volume_mounts: |
        - name: ansible-cfg
          mountPath: /etc/ansible/ansible.cfg
          subPath: ansible.cfg

      task_extra_volume_mounts: |
        - name: custom-py
          mountPath: /etc/tower/conf.d/custom.py
          subPath: custom.py

      extra_volumes: |
        - name: ansible-cfg
          configMap:
            defaultMode: 420
            items:
              - key: ansible.cfg
                path: ansible.cfg
            name: <resourcename>-extra-config
        - name: custom-py
          configMap:
            defaultMode: 420
            items:
              - key: custom.py
                path: custom.py
            name: <resourcename>-extra-config

Note

Volume and VolumeMount names cannot contain underscores (_).

9.9. Export environment variables to containers

If you need to export custom environment variables to your containers, use these available options:

Name

Description

Default

task_extra_env

Environment variables to add to the Task container

web_extra_env

Environment variables to add to the Web container

ee_extra_env

Environment variables to add to the EE container

Note

The ee_extra_env variable will only take effect to the globally available execution environments. For custom execution environments, see the section to Customize the Pod spec.

Example configuration of environment variables:

spec:
  task_extra_env: |
    - name: MYCUSTOMVAR
      value: foo
  web_extra_env: |
    - name: MYCUSTOMVAR
      value: foo
  ee_extra_env: |
    - name: MYCUSTOMVAR
      value: foo

9.10. Configure 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.

Name

Description

Default

extra_settings

Extra settings

Example configuration of extra_settings parameter:

spec:
  extra_settings:
    - setting: MAX_PAGE_SIZE
      value: "500"

    - setting: AUTH_LDAP_BIND_DN
      value: "cn=admin,dc=example,dc=com"

9.11. Configure service account

If you need to modify some ServiceAccount properties, you can do so with this variable:

Name

Description

Default

service_account_annotations

Annotations to the ServiceAccount

Example configuration of service account variables:

spec:
  service_account_annotations: |
    eks.amazonaws.com/role-arn: arn:aws:iam::<ACCOUNT_ID>:role/<IAM_ROLE_NAME>