{"id":51681924,"url":"https://github.com/chhanz/al2023-preflight","last_synced_at":"2026-07-15T14:30:59.740Z","repository":{"id":369608515,"uuid":"1290518302","full_name":"chhanz/al2023-preflight","owner":"chhanz","description":"Read-only pre-flight assessment for migrating Amazon Linux 2 workloads to AL2023 — per-instance migration-difficulty grades, remediation hints, and fleet-wide wave planning","archived":false,"fork":false,"pushed_at":"2026-07-06T04:17:53.000Z","size":994,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-06T06:10:41.468Z","etag":null,"topics":["al2023","amazon-linux","assessment","aws","eol","migration"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chhanz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-06T02:38:22.000Z","updated_at":"2026-07-06T04:27:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/chhanz/al2023-preflight","commit_stats":null,"previous_names":["chhanz/al2023-preflight"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/chhanz/al2023-preflight","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chhanz%2Fal2023-preflight","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chhanz%2Fal2023-preflight/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chhanz%2Fal2023-preflight/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chhanz%2Fal2023-preflight/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chhanz","download_url":"https://codeload.github.com/chhanz/al2023-preflight/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chhanz%2Fal2023-preflight/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35509491,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-15T02:00:06.706Z","response_time":131,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["al2023","amazon-linux","assessment","aws","eol","migration"],"created_at":"2026-07-15T14:30:59.006Z","updated_at":"2026-07-15T14:30:59.734Z","avatar_url":"https://github.com/chhanz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# al2023-preflight\n\nRead-only pre-flight assessment for migrating Amazon Linux 2 workloads to\nAmazon Linux 2023.\n\nAL2 reached end of support on 2026-06-30, and there is no in-place upgrade\npath to AL2023 — the supported route is redeploying onto new AL2023\ninstances. `al2023-preflight` scans an AL2 instance **without changing\nanything** and reports what will break after the replatform: missing\npackages, EPEL dependencies, IMDSv1 callers, OpenSSL 1.0.x-linked binaries,\ncgroup v2 hazards, legacy TLS configuration, and more. Each finding comes\nwith a severity, an effort estimate, and a remediation hint, and every\ninstance receives an overall migration-difficulty grade (A–E) so fleets can\nbe scheduled in waves.\n\nThe assessment model is inspired by the pre-upgrade analysis of\n[leapp](https://github.com/oamg/leapp) (RHEL's in-place upgrade tool),\nreinterpreted for a redeploy-not-upgrade context.\n\n![Example HTML report](docs/images/report-example.png)\n\n## Requirements\n\n- Amazon Linux 2 host (non-AL2 hosts are rejected; override with `--force`)\n- Python 3.7+ (the AL2 system `python3`), standard library only — no\n  dependencies\n- Run as root for full fact collection (degrades gracefully without)\n\n## Usage\n\n```\n$ sudo python3 -m al2023_preflight.cli scan\n$ sudo python3 -m al2023_preflight.cli scan --json --html   # extra formats\n```\n\nReports are written to `/var/tmp/al2023-preflight` (change with `--output`)\nand named `{hostname}-report_{date}.{ext}`. By default only the\nhuman-readable `.txt` is written; `--json` adds the machine-readable report\n(fleet-aggregation input, schema v1 — see `docs/report-schema-v1.md`) and\n`--html` adds a single-file HTML report.\n\nExit codes: `0` clean, `1` findings, `2` blockers present (CI-friendly).\n\n## Fleet workflow\n\nAssess many instances, aggregate centrally, and plan migration waves:\n\n1. **Collect** — run a JSON scan on every AL2 host and gather the reports\n   into one directory. Two channels:\n   - **SSM** (recommended at scale): register `fleet/ssm-run-preflight.yaml`\n     once, then\n     `aws ssm send-command --document-name RunAL2023Preflight --targets Key=tag:\u003cyour-tag\u003e,Values=\u003cvalue\u003e ...`\n     — each host uploads its `{hostname}-report_{date}.json` to S3.\n     The instance role needs `s3:GetObject` on the tool object and\n     `s3:PutObject` on the report prefix (a bucket policy works well).\n   - **SSH fallback**: `./fleet/collect-ssh.sh \u003coutdir\u003e \u003chost1\u003e \u003chost2\u003e ...`\n2. **Aggregate**:\n   ```\n   $ python3 -m al2023_preflight.cli fleet-report --input \u003cdir\u003e \\\n       [--output fleet.txt] [--html dashboard.html]\n   ```\n   Produces the grade distribution, top-blocker frequency (keyed by stable\n   finding `key`), and wave suggestions (Wave 1: A/B now, Wave 2: C after\n   shared fixes, Wave 3: D per-team, Project: E rebuilds). `--html` writes\n   a single-file dashboard for management sharing. Only the newest report\n   per hostname is counted, so periodic re-scans naturally track progress.\n\n## Grades\n\n`A` (best) → `E` (worst). The grade summarizes how hard it is to replatform\nthe instance to AL2023.\n\n| Grade | Meaning | Criteria (blockers / score) | Estimated effort |\n|-------|---------|-----------------------------|------------------|\n| A | ready to replatform as-is | 0 blockers, score \u003c= 5 | days |\n| B | minor fixes required | 0 blockers, score \u003c= 20 | days |\n| C | moderate preparation required | \u003c= 1 blocker, score \u003c= 60 | weeks |\n| D | significant preparation required | score \u003c= 140 | weeks |\n| E | effectively a rebuild | score \u003e 140 | months |\n\nScoring: each finding scores `severity_weight × effort_weight` (severity\ninfo=0 / low=1 / medium=3 / high=6; effort trivial=1 / small=2 / medium=4 /\nlarge=8 / rebuild=16), and a **blocker** flag adds +10. A blocker means the\nworkload will fail on the new instance unless resolved first — it is\northogonal to severity, following leapp's inhibitor-as-flag design. The\ninstance score is the sum over all findings. Thresholds are heuristics\ntuned on real instances; treat the grade as a planning signal, not a\nguarantee.\n\n## Implemented checks\n\nepel-packages-in-use (triaged against AL2023 core and SPAL) ·\nextras-topics-in-use · packages-missing-in-al2023 · python2-dependents\n(shebang scan, `rpm --whatrequires` reverse lookup, live-process detection)\n· imdsv1-callers · libssl10-linked-binaries · cgroupv2-unsafe-runtimes ·\ncgroupv1-hardcoded-paths · userdata-bootstrap-breakage · i686-binaries ·\nthird-party-kernel-modules · ntp-to-chrony · rsyslog-remote-forwarding ·\nawslogs-agent-removed · sendmail-removed · auth-chain-changes ·\nnetwork-scripts-customization · cron-jobs-present · tls-legacy-config ·\nweak-signature-certs · awscli-v1-scripts · systemd-deprecated-directives ·\nthird-party-agents\n\n## Layout\n\n```\nal2023_preflight/\n├── engine.py         # message bus, check registry, Finding, grading\n├── facts.py          # read-only scanners (facts phase)\n├── checks.py         # judgement over facts (checks phase)\n├── report.py         # txt/json rendering; report_html.py for HTML\n├── fleet.py          # fleet aggregation; fleet_html.py for the dashboard\n├── cli.py            # scan / fleet-report subcommands\n└── data/\n    ├── knowledge.json           # AL2→AL2023 knowledge (extras topics,\n    │                            # removed pkgs, JVM cgroup-v2 minimums)\n    ├── al2023-core-packages.txt # AL2023 core package-existence DB\n    └── spal-packages.txt        # SPAL (EPEL9 rebuild) package-existence DB\ndocs/report-schema-v1.md         # frozen JSON report contract\nfleet/                           # SSM document + SSH collector\nscripts/refresh-package-db.sh    # regenerate the package DBs\ntests/test_demo.py               # end-to-end test over synthetic facts\n```\n\n## Knowledge-data refresh\n\nCheck accuracy tracks the freshness of `al2023_preflight/data/`. To\nrefresh, run `scripts/refresh-package-db.sh` on an up-to-date AL2023 host\nand commit the diff; each DB file carries a `# generated:` header\nidentifying its snapshot. A refresh pipeline aligned with the AL2023 AMI\nrelease cycle (quarterly) is planned: regenerate on each release, review\nthe diff, and push the updated data to this repository so deployed copies\npick up current data without code changes.\n\n## Test\n\n```\n$ python3 tests/test_demo.py\n```\n\nFeeds synthetic facts for a worst-case legacy host through every check and\nasserts all expected findings fire.\n\n## Limitations\n\n- **Not an official Amazon Linux / AWS tool.** This is an independent,\n  community project with no affiliation to, or endorsement by, Amazon Web\n  Services. AWS provides no automated AL2-to-AL2023 assessment tool; this\n  project fills that gap on a best-effort basis. Findings and remediation\n  hints are not AWS guidance — always cross-check against the official\n  [AL2023 documentation](https://docs.aws.amazon.com/linux/al2023/ug/).\n- **No application-level migration assessment.** The scan stops at the OS\n  layer: packages, repositories, linked libraries, system configuration,\n  provisioning scripts, and running interpreters. It does not analyze your\n  application source code, framework/library compatibility, database\n  engine behavior, or runtime business logic (e.g. code calling OpenSSL 3\n  removed APIs, or an app depending on version-specific behavior of a\n  package that AL2023 ships in a newer major version). A clean grade means\n  the OS-level replatform surface looks manageable — it does not certify\n  that the application will work. Always validate workloads on a real\n  AL2023 test instance before cutover.\n- Grades are planning signals calibrated on a limited instance sample.\n- SPAL-covered packages are provided as-is from upstream EPEL9, are not\n  covered by AWS Support Plans, and receive no AWS CVE tracking — review\n  before relying on them for production-critical services.\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchhanz%2Fal2023-preflight","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchhanz%2Fal2023-preflight","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchhanz%2Fal2023-preflight/lists"}