19. The awx-manage Utility

The awx-manage utility performs advanced automation controller maintenance. It is installed in the controller image, not on the administrator’s workstation or the Kubernetes node. Prefer the UI, API and management jobs for routine work.

Run commands as the existing awx user in the controller task container. Set an explicit namespace and the controller resource name (spec.controller.name; by default <platform>-controller). The task Deployment and its main container are both named <controller>-task. For example, inspect command help without changing any data:

kubectl --context <context> -n <namespace> exec deploy/<controller>-task \
  -c <controller>-task -- awx-manage inventory_import --help

Use oc in place of kubectl on OpenShift. Every controller command below uses this execution context; replace the example inventory ID, paths and dates for your deployment. Do not install packages, edit generated configuration or run commands as root inside the controller container. The operator reconciles deployment configuration from KoiosPlatform.

Warning

Management commands can modify or permanently delete controller data. Review their help and scope and take a backup before maintenance; see Backup and Restore. Do not run them from an automation job as a replacement for the platform API.

19.1. Inventory Import

For normal inventory synchronization, use an inventory source backed by a project; see Inventory File Importing. Direct inventory_import is an advanced alternative for a file or directory already available to the controller task container.

To use awx-manage properly, you must first create an inventory in automation controller to use as the destination for the import.

The source path is inside the task container, not on the workstation that runs kubectl. Use an existing mounted inventory file or directory and verify its permissions; do not assume the example path exists or that a file copied into an ephemeral pod will persist.

The inventory_import command synchronizes an automation controller inventory object with a text-based inventory file, dynamic inventory script, or a directory of one or more of the above as supported by core Ansible.

When running this command, specify either an --inventory-id or --inventory-name, and the path to the Ansible inventory source (--source).

kubectl --context <context> -n <namespace> exec deploy/<controller>-task \
  -c <controller>-task -- awx-manage inventory_import \
  --source=<mounted-inventory-path> --inventory-id=<inventory-id>

By default, inventory data already stored in automation controller blends with data from the external source. To use only the external data, specify --overwrite. To specify that any existing hosts get variable data exclusively from the --source, specify --overwrite_vars. The default behavior adds any new variables from the external source, overwriting keys that already exist, but preserves any variables that were not sourced from the external data source.

kubectl --context <context> -n <namespace> exec deploy/<controller>-task \
  -c <controller>-task -- awx-manage inventory_import \
  --source=<mounted-inventory-path> --inventory-id=<inventory-id> --overwrite

Note

Edits and additions to Inventory host variables persist beyond an inventory sync as long as --overwrite_vars is not set.

19.2. Cleanup of old data

awx-manage has a variety of commands used to clean old data from automation controller. The automation controller administrators can use the Management Jobs interface for access or use the command line.

kubectl --context <context> -n <namespace> exec deploy/<controller>-task \
  -c <controller>-task -- awx-manage cleanup_jobs --help

The cleanup operation permanently deletes the job details and output older than the specified retention period; the example above only displays help.

kubectl --context <context> -n <namespace> exec deploy/<controller>-task \
  -c <controller>-task -- awx-manage cleanup_activitystream --help

The cleanup operation permanently deletes Activity Stream data older than the specified retention period; the example above only displays help.

19.3. Cluster management

Configure controller replicas and placement through KoiosPlatform; see Clustering. Manage external execution nodes through the platform’s Instances interface. Do not use internal instance-provisioning commands to manage pods owned by the operator.

19.4. Token and session management

Users log in to Koios Automation Platform through the platform gateway, and the gateway owns their sessions and OAuth2 tokens. awx-manage does not manage them: the controller commands expire_sessions and cleanup_sessions only act on sessions of the controller itself, not on platform logins, so they do not remove anyone’s access to the platform.

Manage tokens from API tokens and OAuth applications (UI and API) or with aap-gateway-manage in the gateway pod (container api of the <platform>-gateway Deployment):

$ kubectl --context <context> -n <namespace> exec deploy/<platform>-gateway -c api -- \
    aap-gateway-manage revoke_oauth2_tokens --user example_user --all
revoke_oauth2_tokens

Revokes OAuth2 access tokens: of every user, or of one user with --user <username>. Add --all to revoke their refresh tokens too. Revoking tokens does not end the user’s browser sessions.

create_oauth2_token --user <username>

Creates a personal access token with the write scope for a user and prints it once. For a read-only token, create it from API tokens and OAuth applications.

cleanup_tokens

Deletes expired and revoked tokens from the database.

Sessions end after Session Cookie Age, and Maximum Number of Simultaneous Logged In Sessions limits how many a user may have; both are gateway settings (see Sessions and passwords). aap-gateway-manage clearsessions deletes expired sessions from the session store.

19.5. Host metrics

To collect usage information about unique hosts automated across a time period, use this command:

kubectl --context <context> -n <namespace> exec deploy/<controller>-task \
  -c <controller>-task -- awx-manage host_metric \
  --since YYYY-MM-DD --until YYYY-MM-DD --json

The parameters --since and --until specify date ranges and are optional, but one of them has to be present. The --json flag specifies the output format and is optional.