AAP Demo Quick Start
Deploy AAP to a local MicroShift cluster in minutes.
SECURITY NOTICE — DEVELOPMENT ENVIRONMENT ONLY
aap-demo is a LOCAL DEVELOPMENT tool and must NEVER be used in production.
Prerequisites
- CRC (OpenShift Local) — Download
- 16 GB RAM minimum — default VM allocation is 16 GB (override with
CRC_MEMORY=24576 aap-demo create for 24 GB). On Linux, aap-demo create
prompts for optional temp swap on memory-constrained hosts (see
scripts/README.md)
- Pull secret — download from the
Red Hat console,
then run:
mkdir -p ~/.aap-demo
cp ~/Downloads/pull-secret.txt ~/.aap-demo/pull-secret.txt
On Windows, the PowerShell launcher runs the maintained Bash CLI through Git
for Windows. Windows deploys and AO/Product Demo enablement also require jq
and a working Python runtime for shell wiring and demo provisioning. The
Windows preflight installs them with winget when they are missing:
winget install --id jqlang.jq -e --source winget
winget install --id Python.Python.3.12 -e --source winget
Linux and macOS keep their existing prerequisite behavior; Python remains
optional there when demo provisioning is not requested.
Install
git clone https://github.com/RedHatOfficial/aap-demo.git && cd aap-demo && ./install.sh && aap-demo deploy
aap-demo create provisions the MicroShift VM only. aap-demo deploy installs OLM and AAP
(use deploy for the typical path; create alone is for cluster-only setup).
Cluster credentials live at ~/.aap-demo/kubeconfig.microshift and are not merged into
~/.kube/config. If you relied on the old default kubeconfig behavior, run:
export KUBECONFIG=~/.aap-demo/kubeconfig.microshift
# or: aap-demo kubeconfig # refresh file and print export command
oc login writes into the kubeconfig named by KUBECONFIG. When that is the
aap-demo file, the current context can switch to a remote cluster. Cluster
commands then stop before they read or change that API, and tell you how to
switch back to the microshift or aap-demo context. aap-demo kubeconfig
refreshes the local file from the CRC VM. Set
AAP_DEMO_ALLOW_REMOTE_KUBECONFIG=true only when that remote API is intentional.
Status
aap-demo version # Tool version, commit, and build timestamp
aap-demo status # Show routes and credentials
AAP Demo Status
===============
Infra: OpenShift Local (CRC)
Cluster: running (crc-microshift)
Namespaces:
-----------
aap-operator 27/29 pods aap
AAP Deployments:
----------------
https://aap-aap-operator.apps.127.0.0.1.nip.io
Credentials:
------------
aap-operator: admin / <password>
Addons:
-------
mcp-server disabled
portal disabled
portal-operator disabled (AMD64 only)
setup-pah disabled
ao disabled
local-cache disabled
product-demos disabled
product-demo-satellite disabled
Addons to add additional functionality
aap-demo enable # List all addons
aap-demo enable portal # Installs Automation Portal
aap-demo enable portal-operator # Installs Operator-based Portal (Technology Preview; AMD64 only)
aap-demo enable setup-pah # Configures Private Automation Hub Credentials
aap-demo enable mcp-server # MCP server for AI assistants
aap-demo enable ao # Automation Orchestrator (GA; no aapctl required — see addons/ao/README.md)
aap-demo enable ao-pr-testing # PR validation workflow and read-only OpenShift MCP (requires AO)
aap-demo enable apme-eap # Early Access Program only for APME
aap-demo enable local-cache # Caches AAP containers locally so you don't re-download after destroy/create
# Ansible Product Demos - Official demo content from ansible/product-demos
aap-demo enable product-demos # Five domains at once (includes base; Satellite opt-in)
aap-demo enable product-demo-satellite # Satellite demos (requires a Satellite server)
aap-demo disable addon_name # Disables addon
The Windows wrapper currently defers Fleet and local image caching; those
addons remain available through the Linux/macOS Bash workflow.
When destroying a running cluster, aap-demo destroy asks whether to save the
container images locally. Confirming lets the next aap-demo deploy reuse the
cached containers instead of downloading them again. Existing cached images are
loaded automatically at the start of the next deploy.
Normal destroy/recreate flow:
aap-demo destroy # answer y at the cache prompt
aap-demo create
aap-demo deploy # automatically loads the saved cache
You do not need to run aap-demo enable local-cache load for this normal flow.
To manage the cache manually:
aap-demo enable local-cache load # one-shot reload into fresh VM
aap-demo enable local-cache # restore auto-load on future deploys
Common Commands
# Deployment
AAP_VERSION=2.7 aap-demo deploy # Deploy AAP 2.7 (default)
AAP_VERSION=2.6 aap-demo deploy # Deploy AAP 2.6
# Cluster management
aap-demo status # Show cluster status, routes, credentials
aap-demo stop # Stop the cluster
aap-demo start # Start the cluster
aap-demo ssh # SSH into the cluster node
aap-demo watch # Monitor deployment progress
aap-demo destroy # Delete entire cluster
# AAP Operator Idle
aap-demo idle true # Scale down AAP to save resources
aap-demo idle false # Scale back up
aap-demo idle # Check current idle state
# Troubleshooting
aap-demo diagnose # Quick health check (cluster, storage, SCCs, pods)
aap-demo must-gather # Collect full diagnostics (AAP + cluster)
aap-demo must-gather /tmp/d # Collect to specific directory
aap-demo repair # Fix after sleep/wake issues
aap-demo trust-ca # Fix ingress certificate trust without cluster repair
# Maintenance
aap-demo clean # Remove AAP deployment (keeps cluster)
aap-demo update # Pull latest code and reinstall
aap-demo help # Full command reference
Architecture
Architecture decisions are documented in docs/adr/, covering CLI design,
storage, OLM, addons, and cross-platform support.
macOS / Linux / Windows
- Networking: SSH (2222), API (6443), HTTP/HTTPS (443) — all on localhost
- Routes:
*.apps.127.0.0.1.nip.io (nip.io DNS, no /etc/hosts needed)
- TLS: MicroShift's ingress CA auto-trusted on macOS keychain / Linux ca-trust;
on Windows, run
aap-demo deploy from an elevated PowerShell (see
powershell/README.md)
Environment Variables
CRC_CPUS=8 # VM CPU count (default: 8)
CRC_MEMORY=16384 # VM memory in MiB (default: 16384)
CRC_DISK=100 # VM disk size in GiB (default: 100)
CRC_PV_SIZE=70 # Storage reserved for LVMS PVCs in GiB (default: 70, must be < CRC_DISK)
NAMESPACE=aap-operator # Target namespace
AAP_VERSION=2.7 # AAP version to deploy: 2.6 or 2.7
QUIET=true # Suppress disclaimer
Troubleshooting
aap-demo diagnose # Quick health check — finds common issues
aap-demo diagnose --ai # AI-powered analysis (requires claude CLI)
aap-demo must-gather # Collect full diagnostics for support
On MicroShift 4.22+, aap-demo deploy relaxes container signature verification for
registry.redhat.io inside the CRC VM so operator index images can pull. This is a
demo-only workaround and must not be used as a production pattern.
Clean Up
aap-demo clean # Remove AAP (keep cluster)
aap-demo destroy # Delete everything
./install.sh --uninstall # Remove aap-demo CLI
Documentation
Versioning
Feature PRs do not need to change VERSION. Update it deliberately when preparing
a release; CI only verifies that the checked-in value is valid semver. Development builds are
also identified by the commit SHA and build timestamp shown by aap-demo version.
aap-demo version # show current version + git build info
cz bump --increment PATCH # after ./scripts/setup-linting.sh (optional)
