ci: arm64-attach for cac-lsphp, cac-litespeed, shared-ols #56

Merged
jknapp merged 1 commits from feat/arm64-attach-ols into trunk 2026-11-20 14:32:37 +00:00
4 changed files with 189 additions and 23 deletions

No files matched your search

+115 -18
View File
@@ -1,6 +1,7 @@
name: Attach arm64 to an existing tag
run-name: attach arm64 to ${{ github.event.inputs.image }}:php${{ github.event.inputs.phpver }}
# Manual only (never on push): publishes an arm64 image for an EXISTING tag of cac or cac-fpm
run-name: attach arm64 to ${{ github.event.inputs.image }}:${{ github.event.inputs.phpver && format('php{0}', github.event.inputs.phpver) || 'latest' }}
# Manual only (never on push): publishes an arm64 image for an EXISTING tag of cac, cac-fpm,
# cac-lsphp, cac-litespeed (php<phpver>) or shared-ols (:latest)
# and merges it with the tag's CURRENT amd64 manifest into a new index. The amd64 image is
# NOT rebuilt and NOT touched: its manifest digest (and config, layers, attestation) stay
# byte-identical (with force=true the old arm64 is replaced and the amd64 attestation entry is not carried); only the tag's index digest changes. Use it to restore an arm64 entry that a
@@ -14,12 +15,13 @@ on:
workflow_dispatch:
inputs:
image:
description: 'cac or cac-fpm'
description: 'cac, cac-fpm, cac-lsphp, cac-litespeed or shared-ols'
required: true
type: string
phpver:
description: 'PHP version without dots: 82, 83, 84, 85 or 86 (tag = php<phpver>)'
required: true
description: 'PHP version without dots (tag = php<phpver>): 82-86 for cac and cac-fpm, 82-85 for cac-lsphp and cac-litespeed. Leave empty for shared-ols (tag = latest).'
required: false
default: ''
type: string
force:
description: 'true = replace an arm64 entry the tag already has (default: refuse)'
@@ -42,6 +44,8 @@ jobs:
uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
# Inputs reach the shell via env only, and are regex-checked before use.
# family=rpm: AlmaLinux images (cac, cac-fpm). family=ols: the LiteSpeed family, built FROM
# litespeedtech/openlitespeed (cac-lsphp, cac-litespeed, shared-ols).
- name: Validate inputs
id: v
env:
@@ -50,23 +54,31 @@ jobs:
IN_FORCE: ${{ github.event.inputs.force }}
run: |
set -euo pipefail
phpre='^8[2-6]$'; family=rpm; tag="php${IN_PHPVER}"; basephp="${IN_PHPVER}"
case "$IN_IMAGE" in
cac) dockerfile=Dockerfile; bins="/usr/sbin/httpd /usr/bin/php" ;;
cac-fpm) dockerfile=Dockerfile.fpm; bins="/usr/sbin/php-fpm /usr/bin/php" ;;
*) echo "::error::image must be cac or cac-fpm"; exit 1 ;;
cac-lsphp|cac-litespeed)
family=ols; phpre='^8[2-5]$'; dockerfile="Dockerfile.${IN_IMAGE#cac-}"
bins="/usr/local/lsws/bin/openlitespeed /usr/local/lsws/lsphp${IN_PHPVER}/bin/lsphp" ;;
shared-ols)
family=ols; dockerfile=Dockerfile.shared-ols; tag=latest; basephp=83; phpre='^(83)?$'
bins="/usr/local/lsws/bin/openlitespeed" ;;
*) echo "::error::image must be cac, cac-fpm, cac-lsphp, cac-litespeed or shared-ols"; exit 1 ;;
esac
[[ "$IN_PHPVER" =~ ^8[2-6]$ ]] || { echo "::error::phpver must be one of 82 83 84 85 86"; exit 1; }
[[ "$IN_PHPVER" =~ $phpre ]] || { echo "::error::phpver '${IN_PHPVER}' is not valid for ${IN_IMAGE} (pattern $phpre)"; exit 1; }
case "${IN_FORCE:-false}" in true|false) ;; *) echo "::error::force must be true or false"; exit 1 ;; esac
{
echo "repo=repo.anhonesthost.net/cloud-hosting-platform/${IN_IMAGE}"
echo "tag=php${IN_PHPVER}"
echo "tag=${tag}"
echo "image=${IN_IMAGE}"
echo "phpver=${IN_PHPVER}"
echo "phpver=${basephp}"
echo "family=${family}"
echo "dockerfile=${dockerfile}"
echo "bins=${bins}"
echo "force=${IN_FORCE:-false}"
} >> "$GITHUB_OUTPUT"
echo "attach arm64 to ${IN_IMAGE}:php${IN_PHPVER} (force=${IN_FORCE:-false})"
echo "attach arm64 to ${IN_IMAGE}:${tag} (family=${family}, force=${IN_FORCE:-false})"
- name: Login to Gitea
uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
@@ -78,7 +90,8 @@ jobs:
- name: Resolve base image digest (Docker Hub, direct)
id: base
env:
BASE_TAG: almalinux/10-base:latest
# OLS family: same pin as build-push.yaml (OLS_VERSION 1.8.4; shared-ols uses the lsphp83 tag).
BASE_TAG: ${{ steps.v.outputs.family == 'ols' && format('litespeedtech/openlitespeed:1.8.4-lsphp{0}', steps.v.outputs.phpver) || 'almalinux/10-base:latest' }}
run: |
set -uo pipefail
if ref=$(.gitea/scripts/resolve-base-image.sh "$BASE_TAG") && [[ "$ref" =~ ^[a-z0-9][a-z0-9._/-]*@sha256:[0-9a-f]{64}$ ]]; then
@@ -145,6 +158,7 @@ jobs:
# Same php.net floor as the normal build: the Dockerfile fails on anything older.
- name: Resolve current PHP release from php.net
if: steps.v.outputs.family == 'rpm'
id: phpmin
env:
PHPVER: ${{ steps.v.outputs.tag }}
@@ -157,6 +171,47 @@ jobs:
echo "php.net current ${branch}: ${min}"
echo "min=${min}" >> "$GITHUB_OUTPUT"
# OLS family (cac-lsphp, cac-litespeed): the arm64 image is built from the LiteSpeed PACKAGED
# lsphp (apt noble arm64), not from php.net source: LiteSpeed now ships the same PHP release
# the amd64 php.net-source images carry, so version, extensions and ini defaults are equal; the
# parity step below PROVES that against the existing amd64 image and refuses otherwise.
# EXPECT_* come from the arm64 index (the amd64 index may differ by hours). docs/arm64-ols-family.md
- name: Resolve build args
id: args
env:
FAMILY: ${{ steps.v.outputs.family }}
IMAGE: ${{ steps.v.outputs.image }}
PHPVER: ${{ steps.v.outputs.phpver }}
BASE_IMAGE: ${{ steps.base.outputs.image }}
PKG_CACHE: ${{ steps.pkgcache.outputs.url }}
BUST: ${{ steps.bust.outputs.value }}
PHPMIN: ${{ steps.phpmin.outputs.min }}
run: |
set -euo pipefail
{
echo "list<<ARGS_EOF"
echo "PHPVER=${PHPVER}"
echo "BASE_IMAGE=${BASE_IMAGE}"
echo "PKG_CACHE=${PKG_CACHE}"
if [ "$FAMILY" = rpm ]; then
echo "CACHE_BUST=${BUST}"
echo "EXPECT_PHP_MIN=${PHPMIN}"
else
echo "OLS_VERSION=1.8.4"
if [ "$IMAGE" != shared-ols ]; then
pkg=$(./scripts/lsphp-repo-version.sh "${PHPVER}" arm64)
[[ "$pkg" =~ ^[0-9][0-9A-Za-z.+~:-]*$ ]] || { echo "::error::no/malformed lsphp${PHPVER} arm64 package version '${pkg}'" >&2; exit 1; }
php="${pkg%%-*}"
[[ "$php" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "::error::malformed PHP version '${php}'" >&2; exit 1; }
echo "CACHE_BUST=${BUST}"
echo "EXPECT_LSPHP_PKG=${pkg}"
echo "EXPECT_PHP_VERSION=${php}"
echo "lsphp${PHPVER} arm64 package ${pkg}" >&2
fi
fi
echo "ARGS_EOF"
} >> "$GITHUB_OUTPUT"
# arm64 only, pushed UNTAGGED by digest. Required here (this run exists only for it): a
# failure fails the run and the tag is not touched.
- name: Build arm64 (push by digest)
@@ -166,12 +221,7 @@ jobs:
with:
file: ./${{ steps.v.outputs.dockerfile }}
platforms: linux/arm64
build-args: |
PHPVER=${{ steps.v.outputs.phpver }}
CACHE_BUST=${{ steps.bust.outputs.value }}
BASE_IMAGE=${{ steps.base.outputs.image }}
PKG_CACHE=${{ steps.pkgcache.outputs.url }}
EXPECT_PHP_MIN=${{ steps.phpmin.outputs.min }}
build-args: ${{ steps.args.outputs.list }}
outputs: type=image,name=repo.anhonesthost.net/cloud-hosting-platform/${{ steps.v.outputs.image }},push-by-digest=true,name-canonical=true,push=true
# The arm64 entry must contain AArch64 binaries and the existing amd64 entry x86-64 ones:
@@ -191,8 +241,9 @@ jobs:
python3 -I scripts/verify-image-arch.py --image "$REPO@$ARM64_DIGEST" --platform linux/arm64 "${bins[@]}"
python3 -I scripts/verify-image-arch.py --image "$REPO@$AMD64" --platform linux/amd64 "${bins[@]}"
# The new arm64 was built now, the amd64 entry earlier: refuse a PHP version skew between them.
# The new arm64 was built now, the amd64 entry earlier: refuse a version skew between them.
- name: PHP version parity (amd64 native, arm64 under QEMU)
if: steps.v.outputs.family == 'rpm'
env:
REPO: ${{ steps.v.outputs.repo }}
TAG: ${{ steps.v.outputs.tag }}
@@ -212,6 +263,52 @@ jobs:
[[ "$want" =~ ^[0-9]+\.[0-9]+\.[0-9]+ ]] || { echo "::error::cannot read the amd64 PHP version"; exit 1; }
[ "$want" = "$got" ] || { echo "::error::PHP version differs between the existing amd64 (${want}) and the new arm64 (${got}); not attaching. The amd64 image needs a rebuild first."; exit 1; }
# OLS family: the arm64 (packaged lsphp / OLS from the LiteSpeed repo and base image) must be
# observably the SAME PHP as the existing amd64 image (php.net-source or packaged): identical
# PHP_VERSION, SAPI, loaded extensions + versions and EVERY ini value, both with the image's
# config and with `-n` (compiled-in defaults). scripts/arm64-parity-probe.php runs natively on
# amd64 and under QEMU (a throwaway BuildKit RUN) on arm64; any difference prints as a diff
# and fails the run before the tag is touched. shared-ols runs no PHP: openlitespeed -v only.
- name: "Parity - same PHP / OLS as the existing amd64 image"
if: steps.v.outputs.family == 'ols'
env:
REPO: ${{ steps.v.outputs.repo }}
IMAGE: ${{ steps.v.outputs.image }}
PHPVER: ${{ steps.v.outputs.phpver }}
ARM64_DIGEST: ${{ steps.arm64.outputs.digest }}
AMD64: ${{ steps.plan.outputs.amd64 }}
run: |
set -euo pipefail
work=$(mktemp -d); mkdir -p "$work/ctx" "$work/out" "$work/amd"
cp scripts/arm64-parity-probe.php "$work/ctx/probe.php"
# OpenLiteSpeed: same release and module versions. The "(BUILD built: <date>)" stamp is LiteSpeed's
# own per-arch build time (differs by design), so it is stripped before comparing.
olsv='/usr/local/lsws/bin/openlitespeed -v 2>&1 | sed "s/ (BUILD built:.*)//"'
docker run --rm --platform linux/amd64 --entrypoint sh "$REPO@$AMD64" -c "$olsv" > "$work/amd/ols.txt"
printf 'FROM %s@%s AS src\nRUN (%s) > /ols.txt\nFROM scratch\nCOPY --from=src /ols.txt /ols.txt\n' "$REPO" "$ARM64_DIGEST" "$olsv" |
docker buildx build --platform linux/arm64 --output "type=local,dest=$work/out" -f - "$work/ctx"
echo "amd64 OLS: $(head -1 "$work/amd/ols.txt"); arm64 OLS: $(head -1 "$work/out/ols.txt")"
grep -q '^LiteSpeed/' "$work/amd/ols.txt" || { echo "::error::cannot read the amd64 openlitespeed version"; exit 1; }
diff -u "$work/amd/ols.txt" "$work/out/ols.txt" || { echo "::error::openlitespeed version/modules differ between amd64 and arm64; not attaching"; exit 1; }
[ "$IMAGE" != shared-ols ] || { echo "parity OK: OpenLiteSpeed version and modules identical (shared-ols runs no PHP)"; exit 0; }
ls_bin="/usr/local/lsws/lsphp${PHPVER}/bin/lsphp"
for mode in cfg n; do
flag=""; [ "$mode" = n ] && flag="-n"
# probe piped over stdin (not a bind mount: the job's docker daemon cannot see the workspace)
docker run --rm -i --platform linux/amd64 --entrypoint sh "$REPO@$AMD64" -c "cat > /tmp/probe.php; $ls_bin $flag /tmp/probe.php" < "$work/ctx/probe.php" > "$work/amd/$mode.txt"
done
# the same two runs on arm64, inside one BuildKit build (no binfmt for `docker run` here)
printf 'FROM %s@%s AS src\nCOPY probe.php /probe.php\nRUN %s /probe.php > /cfg.txt && %s -n /probe.php > /n.txt\nFROM scratch\nCOPY --from=src /cfg.txt /n.txt /\n' "$REPO" "$ARM64_DIGEST" "$ls_bin" "$ls_bin" |
docker buildx build --platform linux/arm64 --output "type=local,dest=$work/out" -f - "$work/ctx"
rc=0
for mode in cfg n; do
echo "== $mode: $(head -1 "$work/amd/$mode.txt") (amd64) vs $(head -1 "$work/out/$mode.txt") (arm64); $(grep -c '^ext ' "$work/amd/$mode.txt") / $(grep -c '^ext ' "$work/out/$mode.txt") extensions, $(grep -c '^ini ' "$work/amd/$mode.txt") / $(grep -c '^ini ' "$work/out/$mode.txt") ini values"
grep -q '^PHP_VERSION=[0-9]' "$work/amd/$mode.txt" || { echo "::error::cannot read the amd64 probe output ($mode)"; exit 1; }
diff -u "$work/amd/$mode.txt" "$work/out/$mode.txt" || rc=1
done
[ "$rc" = 0 ] || { echo "::error::the new arm64 is not the same PHP as the existing amd64 image (diff above); not attaching. Rebuild amd64 or fix the arm64 build first."; exit 1; }
echo "parity OK: version, SAPI, extensions and every ini value identical"
# Re-creates the tag index: existing amd64 entries by digest + the new arm64. Aborts if the
# tag moved since the plan; verifies the amd64 manifest digest is unchanged afterwards.
- name: Attach (create the new index)
+46
View File
@@ -0,0 +1,46 @@
# arm64 for the LiteSpeed family (cac-lsphp, cac-litespeed, shared-ols)
`arm64-attach.yaml` (manual dispatch, trunk only) attaches an arm64 image to an EXISTING tag
without rebuilding or touching the amd64 image. Inputs: `image` = cac-lsphp | cac-litespeed |
shared-ols, `phpver` = 82..85 (empty for shared-ols, whose tag is `latest`).
## How the arm64 image is built
Same Dockerfile (`Dockerfile.lsphp`, `Dockerfile.litespeed`, `Dockerfile.shared-ols`), same
`OLS_VERSION=1.8.4` base (`litespeedtech/openlitespeed:1.8.4-lsphpNN`, which has an arm64 variant),
built under QEMU on the x86 runner and pushed by digest, then merged into the tag's index.
The published amd64 tags were built from php.net source (`org.whp.lsphp-source=php.net`, emergency
path, docs/lsphp-source-emergency.md). The arm64 image is built from the PACKAGED lsphp (LiteSpeed
apt, noble arm64), not from source, because:
* LiteSpeed now ships the same PHP release for both architectures (8.2.36, 8.3.37, 8.4.28, 8.5.13,
all `-1+noble`), so the PHP version is identical to the amd64 image;
* compiling PHP under QEMU is slow and the source path's gates compare against a packaged lsphp
that is no longer older than the source one;
* the result is checked, not assumed: the workflow runs `scripts/arm64-parity-probe.php` natively in
the existing amd64 image and under QEMU in the new arm64 image and FAILS the run (tag untouched)
on any difference in PHP_VERSION, SAPI, the loaded extension list and versions, or any of the
~350 ini values (with the image's config and with `-n`). It also compares the OpenLiteSpeed
version and module versions (LiteSpeed's per-arch "BUILD built:" stamp is ignored).
Measured 2026-11-20 on cac-lsphp:php85: 418 lines identical.
`EXPECT_LSPHP_PKG` / `EXPECT_PHP_VERSION` come from the arm64 repo index
(`scripts/lsphp-repo-version.sh PHPVER arm64`), not the amd64 one.
Labels differ by design: the arm64 image says `org.whp.lsphp-source=litespeed-apt` and its own
package version. `php-emergency-guard.sh` reads the amd64 child only, so it is unaffected.
## Other guards (same as cac / cac-fpm)
plan pre-check (tag exists, one amd64 entry, no arm64 yet unless `force=true`), ELF machine check of
both platforms (openlitespeed + lsphp), tag-moved check, amd64 manifest digest verified unchanged
after the attach, runs serialised (concurrency group `arm64-attach`). `latest` is re-pointed only
if it was an exact alias of php85.
## Maintenance caveat
`build-push.yaml` and `lsphp-source-emergency.yaml` (without `build_arm64`) still publish these
tags amd64-only. A rebuild therefore replaces the tag with an index without arm64: re-run the
attach for that tag afterwards (the plan step refuses nothing in that case, the tag simply has no
arm64 entry again). Wiring an arm64 leg into those jobs is the permanent fix.
+22
View File
@@ -0,0 +1,22 @@
<?php
// arm64-parity-probe.php - facts that must be IDENTICAL between the existing amd64 image and the
// arm64 image attached to the same tag (version, SAPI, loaded extensions + versions, every ini
// value). Run twice by arm64-attach.yaml: `lsphp probe.php` (image config) and
// `lsphp -n probe.php` (compiled-in defaults only, e.g. session.upload_progress.enabled).
// Output is plain text so a failed parity check prints a readable diff. No timestamps/paths of
// the build host: only things a customer's PHP can observe.
echo 'PHP_VERSION=', PHP_VERSION, "\n";
echo 'PHP_VERSION_ID=', PHP_VERSION_ID, "\n";
echo 'SAPI=', php_sapi_name(), "\n";
echo 'ZTS=', (PHP_ZTS ? 1 : 0), ' DEBUG=', (PHP_DEBUG ? 1 : 0), ' INT_SIZE=', PHP_INT_SIZE, "\n";
echo 'EXTENSION_DIR=', ini_get('extension_dir'), "\n";
$ext = get_loaded_extensions();
sort($ext, SORT_STRING);
foreach ($ext as $e) {
echo 'ext ', $e, ' ', (phpversion($e) ?: '-'), "\n";
}
$ini = ini_get_all(null, false);
ksort($ini, SORT_STRING);
foreach ($ini as $k => $v) {
echo 'ini ', $k, '=', var_export($v, true), "\n";
}
+6 -5
View File
@@ -397,14 +397,15 @@ class AttachWorkflow(unittest.TestCase):
self.assertNotIn('${{', blk) # everything reaches the script through env:
self.assertNotIn('github.event.inputs', self.job.split('Validate inputs', 1)[1].split('Login to Gitea', 1)[1])
def test_only_images_cac_and_cac_fpm_and_php82_to_86(self):
def test_only_the_five_known_images_and_php_ranges(self):
v = step(self.job, 'Validate inputs')
self.assertRegex(v, r'cac\)\s+dockerfile=Dockerfile;')
self.assertRegex(v, r'cac-fpm\)\s+dockerfile=Dockerfile\.fpm;')
self.assertIn('^8[2-6]$', v)
self.assertEqual(re.findall(r'(?m)^ ([a-z-]+)\)', v), ['cac', 'cac-fpm'])
self.assertNotIn('litespeed', v)
self.assertNotIn('lsphp', v)
self.assertRegex(v, r'cac-lsphp\|cac-litespeed\)')
self.assertRegex(v, r'shared-ols\)')
self.assertIn("^8[2-5]$", v) # OLS family: 82-85 only
self.assertEqual(re.findall(r'(?m)^ ([a-z-]+)\)', v), ['cac', 'cac-fpm', 'shared-ols'])
def test_arm64_only_push_by_digest_no_tags(self):
self.assertEqual(len(re.findall(r'platforms: linux/', self.job)), 1)
@@ -420,7 +421,7 @@ class AttachWorkflow(unittest.TestCase):
def test_nothing_but_the_script_writes_a_tag(self):
for bad in ('imagetools create', 'docker push', 'docker tag', '/cac:latest', '/cac-fpm:latest', 'ghcr.io'):
self.assertNotIn(bad, self.job, bad)
self.assertEqual(self.job.count('docker buildx build'), 1) # only the local PHP-version probe
self.assertEqual(self.job.count('docker buildx build'), 3) # only the local probes: php version (rpm), OLS version (shared-ols), lsphp probe
self.assertIn('type=local,dest=', self.job)
self.assertNotIn('--push', self.job)
self.assertEqual(self.job.count('scripts/attach-arm64-index.sh'), 2) # plan (read-only) + attach