aapctl command reference

The aapctl command-line interface (CLI) manages automation orchestrator installations on OpenShift.

Important

aapctl is a Technology Preview feature. Technology Preview features provide early access to upcoming product innovations, enabling you to test functionality and provide feedback during the development process. Technology Preview features are not fully supported under Red Hat production SLA and may not be functionally complete. Red Hat does not recommend using Technology Preview features in production. For more information on the support scope for Technology Preview features, see Technology Preview Features Support Scope.

Command structure
Copy link

aapctl command target [flags]

Each command operates on one of three targets:

Table 1. Command targets
Target Alias Description
ao automation-orchestrator Automation orchestrator only
aap-with-ao aap-plus Ansible Automation Platform plus automation orchestrator
aap -- Ansible Automation Platform only

version

Print the aapctl version.

$ aapctl version

This command accepts no flags.

preflight

Run preflight checks to verify cluster readiness before you install.

$ aapctl preflight ao
$ aapctl preflight aap-with-ao
$ aapctl preflight aap

Match the preflight target to your install target.

The preflight command runs the following checks:

  1. Kubeconfig file exists and is valid.
  2. Cluster API server is reachable.
  3. OpenShift Container Platform version meets the minimum requirement. See Automation orchestrator system requirements.
  4. At least one worker node is available. On hosted control-plane (HCP) clusters, the check passes with zero control-plane nodes.

Exits with code 0 if all checks pass, or code 1 on the first failure.

Table 2. preflight flags
Flag Default Description
--kubeconfig ~/.kube/config Path to kubeconfig file. Also respects theKUBECONFIG environment variable.

install
Copy link

Install operators and deploy resources on the cluster.

$ aapctl install ao
$ aapctl install aap-with-ao
$ aapctl install aap

You can safely re-run any install command. If a resource already exists, the command skips it and continues.

Table 3. install flags
Flag Short Default Description
--config -- Path to YAML configuration file.
--set -- Override a single config value (repeatable). Takes precedence over--config.
--interactive false Prompt for all configurable settings before applying.
--kubeconfig ~/.kube/config Path to kubeconfig file. Also respects theKUBECONFIG environment variable.
--dry-run false Render manifests to standard output instead of applying to the cluster.
--output -o -- Output format. Onlyyaml is supported. Requires--dry-run.
--timeout 30m Maximum time to wait for each operator to become ready.
--force false Overwrite existing resources instead of skipping them.
--no-wait false Apply resources without waiting for readiness. Operator Lifecycle Manager (OLM) InstallPlans are still approved.

Examples

Install automation orchestrator with a custom PostgreSQL host:

$ aapctl install ao \
    --set automation-orchestrator-cr.postgres.host=my-pg.example.com \
    --set automation-orchestrator-cr.postgres.sslMode=require

Install with the interactive wizard:

$ aapctl install ao --interactive

Preview manifests without applying:

$ aapctl install ao --dry-run -o yaml > manifests.yaml

Install using a configuration file:

$ aapctl install aap-with-ao --config my-config.yaml

config show

Print the full effective configuration for an install target. The output is valid YAML that you can save as a configuration file.

$ aapctl config show ao
$ aapctl config show aap-with-ao
$ aapctl config show aap
Table 4. config show flags
Flag Default Description
--config -- Path to YAML configuration file. Values from this file are merged into the defaults.
--set -- Override a single config value (repeatable). Takes precedence over--config.

Examples

View the default configuration:

$ aapctl config show ao

Preview configuration with overrides applied:

$ aapctl config show aap-with-ao --set cloudnative-pg-operator.enabled=true

Save defaults as a starting-point configuration file:

$ aapctl config show ao > my-config.yaml

status

Report the readiness of installed resources.

$ aapctl status ao
$ aapctl status aap-with-ao
$ aapctl status aap

The status command checks each resource and reports whether it is ready. Exits with code 0 if all resources are ready, or code 1 if any resource is not ready.

For status ao, the command checks:

  • Namespace and OperatorGroup exist.
  • Subscription has a current ClusterServiceVersion (CSV).
  • The AutomationOrchestrator custom resource definition (CRD) is registered.
  • The AutomationOrchestrator custom resource has a Ready=True condition.
  • CloudNativePG Cluster has at least one ready instance (when enabled).
  • CloudNativePG Database custom resources are applied (when enabled).

For status aap-with-ao, the command checks all of the above plus the Ansible Automation Platform operator and custom resource.

Table 5. status flags
Flag Default Description
--config -- Path to YAML configuration file.
--set -- Override a single config value (repeatable).
--kubeconfig ~/.kube/config Path to kubeconfig file. Also respects theKUBECONFIG environment variable.

Examples

Check the status of an automation orchestrator deployment:

$ aapctl status ao

Check status with a custom configuration:

$ aapctl status ao --config my-config.yaml

uninstall
Copy link

Remove the resources that aapctl install created. Deletes resources in reverse installation order and prompts for confirmation before proceeding.

$ aapctl uninstall ao
$ aapctl uninstall aap-with-ao
$ aapctl uninstall aap

The command is safe to run multiple times. Resources that are already removed are silently skipped.

By default, the command preserves namespaces and deletes the following resources in reverse installation order:

  • Custom resource (AutomationOrchestrator, AnsibleAutomationPlatform, or both, depending on the target)
  • Operator Subscription, ClusterServiceVersion (CSV), and OperatorGroup for each installed operator
  • CloudNativePG Database and Cluster custom resources, database secrets, and CloudNativePG operator resources (when CloudNativePG was enabled during installation)
  • OpenTelemetry operator resources (when OpenTelemetry was enabled during installation)

Run aapctl uninstall <target> --dry-run -o yaml to see the exact list of resources before you proceed.

Table 6. uninstall flags
Flag Short Default Description
--config -- Path to YAML configuration file.
--set -- Override a single config value (repeatable).
--kubeconfig ~/.kube/config Path to kubeconfig file. Also respects theKUBECONFIG environment variable.
--dry-run false Print the resources that would be deleted without modifying the cluster.
--output -o -- Output format. Onlyyaml is supported. Requires--dry-run.
--force false Delete namespaces, clear finalizers, and force-terminate stuck namespaces. See Force removal.
--yes -y false Skip the confirmation prompt.

Force removal

By default, aapctl uninstall preserves namespaces and issues standard delete requests. Resources with operator-managed finalizers may remain in Terminating state if the managing operator was already removed.

Use --force when you need a clean-slate teardown or when resources are stuck in Terminating state.

With --force, aapctl performs the following additional actions:

  • Deletes namespaces, which cascade-deletes all resources inside them, including resources that aapctl did not create.
  • Clears metadata.finalizers on each resource before deletion, including operator ClusterServiceVersions that are stuck in the Deleting state.
  • Force-terminates namespaces that remain in Terminating state by clearing spec.finalizers.
Warning

The --force flag deletes entire namespaces. Any resources in those namespaces that were not created by aapctl, such as PersistentVolumeClaims or manually created resources, are also deleted. In environments where namespace provisioning requires a formal request process, you cannot reinstall until a new namespace is provisioned.

Run aapctl uninstall <target> --dry-run -o yaml before using --force to review which namespaces and resources will be removed.

Examples

Uninstall automation orchestrator:

$ aapctl uninstall ao

Preview what would be deleted:

$ aapctl uninstall ao --dry-run -o yaml

Uninstall without confirmation:

$ aapctl uninstall ao --yes

Force removal of stuck resources:

$ aapctl uninstall ao --force

If you enabled CloudNativePG during installation, pass the flag so that aapctl also removes those resources:

$ aapctl uninstall ao --set cloudnative-pg-operator.enabled=true