From a8246fff4391b042cc3cd9918048eb740cec428b Mon Sep 17 00:00:00 2001 From: Eric Ames Date: Tue, 2 Jun 2026 08:07:50 -0700 Subject: [PATCH] docs: add customer egress-notification email template (#24) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add docs/egress-notification-template.md — a reusable, genericized email for telling a customer which upstream endpoints their firewall must allow before a Managed AAP upgrade, based on a url_checker / SRE finding. Companion to example-output.md: that shows what the probe reports, this turns a report into a customer ask. Linked from the README; CHANGELOG entry added. Placeholders only — no customer names, URLs, IDs, or engagement specifics. Co-Authored-By: Claude Opus 4.8 --- CHANGELOG.md | 4 ++ README.md | 5 +- docs/egress-notification-template.md | 88 ++++++++++++++++++++++++++++ 3 files changed, 96 insertions(+), 1 deletion(-) create mode 100644 docs/egress-notification-template.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 65eba6a..01a4882 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,10 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - `docs/example-output.md` — full end-to-end transcripts of both a passing run (`32 of 32 URL probes passed.`) and a failing run (deduplicated firewall-rule punch list + non-zero exit), linked from the README `Output` section. (#22) +- `docs/egress-notification-template.md` — a reusable, genericized customer + email template for notifying a customer which endpoints their firewall must + allow ahead of a Managed AAP upgrade. Placeholders only, no customer + specifics; linked from the README. (#24) - README "Load into your AAP" section linking to the new docs. - `community.letsencrypt.org`, `access.redhat.com`, and `acs-mirror.azureedge.net` to the URL list. (`acs-mirror.azureedge.net` expects status `400` on a root diff --git a/README.md b/README.md index 74c4ed2..da1c953 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ docs/ install-manual.md — laptop/desktop install path for the AAP CaC install-with-ai.md — AI-assisted install path example-output.md — full pass/fail run transcripts + egress-notification-template.md — customer email template for egress fixes ``` ## Run it @@ -106,7 +107,9 @@ The play then fails with a non-zero exit code so the scheduled CI cron opens a tracking issue automatically. See [docs/example-output.md](docs/example-output.md) for full end-to-end -transcripts of both a passing run and a failing run. +transcripts of both a passing run and a failing run, and +[docs/egress-notification-template.md](docs/egress-notification-template.md) for +a reusable customer email template to drive the firewall fixes. ## References diff --git a/docs/egress-notification-template.md b/docs/egress-notification-template.md new file mode 100644 index 0000000..23bbcaa --- /dev/null +++ b/docs/egress-notification-template.md @@ -0,0 +1,88 @@ +# Customer egress-notification email template + +A reusable email for telling a customer which upstream endpoints their firewall +must allow (egress) before a Managed AAP upgrade, based on a `url_checker` / +Red Hat SRE finding. It pairs with [`example-output.md`](example-output.md): +that file shows *what the probe reports*; this one turns a report into a clear +customer ask. + +## How to use it + +1. Replace every `<...>` placeholder and `[name]` with the specifics for the + engagement. +2. List one row per blocked **endpoint** in the rules block; each endpoint + normally needs **both** tcp/80 and tcp/443 (see the KB rationale below). + State the total rule count (endpoints × 2) so the subject and body agree. +3. Attach the three reference files: `playbooks/main.yml`, + `playbooks/files/websites.yml`, and `docs/example-output.md`. +4. To send via Gmail with formatting, paste the body into a small HTML file, + open it in a browser, then select-all → copy → paste into the compose + window. (Gmail keeps inline styles; the subject is set separately.) + +## Guardrails + +- **No customer specifics in this file** — it stays generic. Customer names, + AAP URLs, cluster/instance IDs, and dates live only in the sent copy, never + committed here. +- **Match subject and body counts.** Subject counts *endpoints*; the body + states *rules* (endpoints × 2). Keep them consistent so "2 endpoints" and + "4 rules" don't read as a contradiction. +- **Stay within your role.** If you're presales, the template already frames + the check as self-service for the customer's team plus SRE verification — + don't offer to run anything in the customer's production environment. + +--- + +## Subject + +``` +Action required before your AAP upgrade — blocked endpoint(s) to allow +``` + +## Body + +Hi [name], + +Ahead of your upcoming **Ansible Automation Platform ** upgrade, the +Red Hat SRE team has confirmed — most recently on a re-check on **** — +that your Azure firewall is still **blocking egress to upstream +endpoint(s)** the managed upgrade requires. These need to be allowed **before** +your upgrade window, or the upgrade will be blocked. + +Each host must be reachable over **both** HTTP (tcp/80) and HTTPS (tcp/443) — +port 80 is largely a redirect to 443, but Red Hat cannot guarantee dependent +steps won't need it (per [Red Hat KB 6972355](https://access.redhat.com/articles/6972355)). + +**Firewall egress rules to add:** + +``` + allow tcp/80, allow tcp/443 + allow tcp/80, allow tcp/443 +``` + +That's rules across the host(s). + +**To confirm the fix, there's a simple self-service check.** Attached is a +small, dependency-free Ansible playbook that probes exactly these endpoints. On +any miss it prints a deduplicated, copy-paste-ready list of the precise +`allow tcp/ to ` rules still outstanding, then exits with a clear +pass/fail so there's no ambiguity about the result. Your team can run it from +any host with `ansible-core` once the rules are in place; the SRE team will also +verify on their side. The endpoint(s) above are already in its check list. + +Attached: +- `playbooks/main.yml` — the egress-check playbook (`ansible.builtin` only; runs + on a fresh box with `ansible-core`, no extra collections) +- `playbooks/files/websites.yml` — the list of endpoints it checks +- `docs/example-output.md` — full transcripts of a passing run and a failing + run, so you can see exactly what to expect + +It's also published here if that's easier than the attachments: +- Playbook: https://github.com/ericcames/url_checker/blob/main/playbooks/main.yml +- Example output: https://github.com/ericcames/url_checker/blob/main/docs/example-output.md + +Given the upgrade timing, the sooner these rules are added the better. I'm glad +to walk you or your team through how the check works — just let me know. + +Thanks, +Eric