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_tokensRevokes OAuth2 access tokens: of every user, or of one user with
--user <username>. Add--allto 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
writescope for a user and prints it once. For a read-only token, create it from API tokens and OAuth applications.cleanup_tokensDeletes 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.