From 5e11378cdcd6ed4beadb89910d39a0de4eecdb9a Mon Sep 17 00:00:00 2001 From: Eric Ames Date: Thu, 21 May 2026 11:44:25 -0700 Subject: [PATCH] docs: tell customers how to get ansible-playbook on every platform (#20) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The manual install doc listed ansible-core as a prerequisite without telling the customer how to obtain it — and ansible-core does not run natively on Windows, which left Windows customers stuck. Add an upfront "Get a shell with ansible-playbook" section to docs/install-manual.md. Recommend Azure Cloud Shell first: it ships with ansible-core preinstalled, runs from any browser including Windows, and is already adjacent to the customer's AAP. Below it, cover Linux (dnf/apt/pip), macOS (brew/pip), and Windows-via-WSL2 as alternatives with actual install commands. Also reframe the Hub-token prerequisite as optional. infra.aap_configuration is published on public Galaxy, so a customer with no Hub setup (e.g. in fresh Cloud Shell) can install the loader without configuring anything. The Hub token is only required if the user already routes Galaxy through Hub. install-with-ai.md updated in lockstep so both paths agree. No separate Windows install guide — a single doc with a platform section keeps the rest (env vars, loader invocation, verification) DRY across all OS targets. Closes #20. Co-Authored-By: Claude Opus 4.7 --- CHANGELOG.md | 7 +++ docs/install-manual.md | 94 ++++++++++++++++++++++++++++++++++++++--- docs/install-with-ai.md | 18 +++++--- 3 files changed, 105 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d8ff1fd..bbdea60 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -45,6 +45,13 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). source of the Azure / Google / Microsoft egress URLs in `websites.yml`. ### Changed +- `docs/install-manual.md` now opens with a "Get a shell with + `ansible-playbook`" section recommending **Azure Cloud Shell** (zero + install, browser-based, works from Windows, adjacent to the customer's + AAP), followed by Linux (`dnf`/`apt`/`pip`), macOS (`brew`/`pip`), and + Windows-via-WSL2 alternatives. Hub-token prereq reframed as optional — + the loader collection is on public Galaxy, no Hub setup required. + `docs/install-with-ai.md` updated to match. - Documentation caught up to code: README repo-layout tree + updated `schemes` example + Output section reflecting the firewall-rule punch list; `docs/install-manual.md` "(coming soon)" reference dropped now diff --git a/docs/install-manual.md b/docs/install-manual.md index a76f69b..2a9b3bf 100644 --- a/docs/install-manual.md +++ b/docs/install-manual.md @@ -13,14 +13,90 @@ If you'd rather have an AI agent walk you through this, see ## Prerequisites -- `ansible-core` (any 2.15+). The probe playbook itself uses only - `ansible.builtin`; the loader uses one extra collection (next step). -- A working `~/.ansible.cfg` (or `~/.ansible/ansible.cfg`) with a Red Hat - Automation Hub token in the `[galaxy_server.rh_certified]` section. This is - the standard developer setup at Red Hat — if you can already - `ansible-galaxy collection install` certified content, you're set. +- A shell with `ansible-playbook` (any `ansible-core` 2.15+). See + [the next section](#get-a-shell-with-ansible-playbook) for the easiest + way to get one on your platform — including Windows. - An AAP instance you can reach over the network, and permission to create Projects and Job Templates in it. +- *(Optional — Red Hat employees only)* A working `~/.ansible/ansible.cfg` + with an Automation Hub token in `[galaxy_server.rh_certified]`. The + `infra.aap_configuration` collection is published on public Galaxy, so a + Hub token is **not** required to install it — but if you already route + Galaxy through Hub, your existing config will be honored. + +## Get a shell with `ansible-playbook` + +Pick whichever fits your workstation. The rest of this guide is identical +once you have a shell with `ansible-playbook` in your PATH. + +### Easiest path: Azure Cloud Shell *(recommended, especially on Windows)* + +Azure provides a free browser-based shell with `ansible-core` already +installed. It runs inside Azure adjacent to your AAP, so network reach is +typically a non-issue, and there is nothing to install on your workstation. + +1. Open (or click the **>_** icon in the Azure + portal toolbar) and sign in with the same account you use for AAP. +2. Choose **Bash** (not PowerShell) when prompted. +3. Confirm Ansible is present: + ```bash + ansible --version + ``` +4. Clone this repo into your Cloud Shell home directory: + ```bash + git clone https://github.com/ericcames/url_checker.git + cd url_checker + ``` +5. Continue with [§1 below](#1-install-the-loader-collection). + +> Cloud Shell's home directory persists across sessions when you accept +> the offer to mount cloud storage on first use. If you skipped that, the +> install commands still work — you just re-clone next time. + +### Linux + +| Distro | Command | +|--------|---------| +| Fedora / RHEL 9+ / CentOS Stream | `sudo dnf install ansible-core` | +| Debian / Ubuntu 22.04+ | `sudo apt update && sudo apt install ansible-core` | +| Anything with Python 3.10+ | `python3 -m pip install --user ansible-core` | + +Verify: +```bash +ansible --version +``` + +### macOS + +```bash +brew install ansible # Homebrew (recommended) +# or +python3 -m pip install --user ansible-core +``` + +### Windows (via WSL2) + +`ansible-core` does not run natively on Windows. Either use Azure Cloud +Shell above (recommended) or install Windows Subsystem for Linux: + +1. In PowerShell (Administrator): + ```powershell + wsl --install + ``` + This installs Ubuntu by default. Reboot when prompted, then complete + the Ubuntu setup wizard. +2. From the new Ubuntu shell: + ```bash + sudo apt update + sudo apt install ansible-core git + ansible --version + ``` +3. Clone the repo inside WSL (not in the Windows filesystem): + ```bash + git clone https://github.com/ericcames/url_checker.git + cd url_checker + ``` +4. Continue with [§1 below](#1-install-the-loader-collection). ## 1. Install the loader collection @@ -98,6 +174,10 @@ list of firewall rules that need attention. - **`AAP_HOSTNAME and AAP_TOKEN must be exported`** — the loader's pre-task caught a missing env var. Re-export and re-run. - **`Could not find role 'infra.aap_configuration.dispatch'`** — step 1 didn't - install successfully. Check your `~/.ansible.cfg` Hub token, then re-run. + install successfully. Re-run `ansible-galaxy collection install -r + aap_config/requirements.yml` and watch for errors. If you have a + `~/.ansible/ansible.cfg` that routes Galaxy through Automation Hub, make + sure the Hub token is current (or temporarily move that file aside to + fall back to public Galaxy). - **Project sync fails inside AAP** — the AAP host can't reach `URL_CHECKER_SCM_URL`. Adjust the URL or open egress for it. diff --git a/docs/install-with-ai.md b/docs/install-with-ai.md index f171d1c..7cbcd2f 100644 --- a/docs/install-with-ai.md +++ b/docs/install-with-ai.md @@ -11,12 +11,15 @@ result** — a Project and a "URL Egress Check" Job Template in your AAP. ## Prerequisites - [Claude Code](https://docs.claude.com/en/docs/claude-code) installed and signed in. -- `ansible-core` (any 2.15+) on the same machine. -- A working `~/.ansible.cfg` (or `~/.ansible/ansible.cfg`) with a Red Hat - Automation Hub token in `[galaxy_server.rh_certified]`. Required to install - the loader collection. +- A shell with `ansible-playbook` (any `ansible-core` 2.15+). See + [install-manual.md → Get a shell with ansible-playbook](install-manual.md#get-a-shell-with-ansible-playbook) + for platform-specific install instructions, including the + Azure-Cloud-Shell path for Windows users. - An AAP instance you can reach and permission to create Projects and Job Templates in it. +- *(Optional — Red Hat employees only)* A working `~/.ansible/ansible.cfg` + with an Automation Hub token. The loader collection is on public Galaxy, + so a Hub token is **not** required. ## How it works @@ -64,9 +67,10 @@ result** — a Project and a "URL Egress Check" Job Template in your AAP. - **"`aap_config/` not found"** — the agent is not running from the repo root. `cd` into the cloned `url_checker` directory and re-invoke. -- **`ansible-galaxy` cannot install `infra.aap_configuration`** — your - `~/.ansible/ansible.cfg` is missing a Hub token. See - [install-manual.md prerequisites](install-manual.md#prerequisites). +- **`ansible-galaxy` cannot install `infra.aap_configuration`** — usually + network reach to `galaxy.ansible.com`. If you have a `~/.ansible/ansible.cfg` + routing Galaxy through Red Hat Automation Hub, make sure the Hub token is + current — or temporarily move that file aside to fall back to public Galaxy. - **Project sync `failed` after install** — your AAP cannot reach `https://github.com/ericcames/url_checker.git`. That's itself a useful egress signal — fix the firewall rule and re-trigger sync in the AAP UI.