build-in-container.py

#!/usr/bin/env python3
"""Container-based CFEngine package builder.

Builds CFEngine packages inside Docker containers using the existing build
scripts. Each build runs in a fresh ephemeral container.
"""

import argparse
import datetime
import functools
import hashlib
import json
import logging
import os
import shutil
import subprocess
import sys
import urllib.request
from pathlib import Path

log = logging.getLogger("build-in-container")

IMAGE_REGISTRY = "ghcr.io/cfengine"
CONFIG_PATH = Path(__file__).resolve().parent / "platforms.json"

# Where --sftp-key is mounted. It cannot be mounted onto ~/.ssh/id_rsa directly:
# ssh rejects a key owned by neither the current user nor root, and the host file
# belongs to jenkins while the container runs as builder. The inner script copies
# it into place instead.
SFTP_KEY_PATH = "/run/secrets/sftp-cache-key"

# The platform whose image builds the source tarballs, and only those: it is the
# autotools in that image which decide their contents.
TARBALLS_PLATFORM = "tarballs"

# Architectures registry images are published for, unless a platform overrides
# it with an "architectures" list in platforms.json (e.g. the mingw cross-build,
# which always targets Windows x64 and only makes sense on amd64).
DEFAULT_ARCHITECTURES = ["linux/amd64", "linux/arm64"]


def platform_architectures(platform_config):
    """Return the docker platforms a registry image is published for."""
    return platform_config.get("architectures", DEFAULT_ARCHITECTURES)


@functools.cache
def get_config():
    """Load and cache platform configuration from platforms.json."""
    return json.loads(CONFIG_PATH.read_text())


def detect_source_dir():
    """Find the root directory containing all repos (parent of buildscripts/)."""
    script_dir = Path(__file__).resolve().parent
    # The script lives in buildscripts/, so the source dir is one level up
    source_dir = script_dir.parent
    if not (source_dir / "buildscripts").is_dir():
        log.error(f"Cannot find buildscripts/ in {source_dir}")
        sys.exit(1)
    return source_dir


def dockerfile_hash(dockerfile_path):
    """Compute SHA256 hash of a Dockerfile."""
    return hashlib.sha256(dockerfile_path.read_bytes()).hexdigest()


def image_needs_rebuild(image_tag, current_hash):
    """Check if the Docker image needs rebuilding based on Dockerfile hash."""
    result = subprocess.run(
        [
            "docker",
            "inspect",
            "--format",
            '{{index .Config.Labels "dockerfile-hash"}}',
            image_tag,
        ],
        capture_output=True,
        text=True,
        check=False,
    )
    if result.returncode != 0:
        return True  # Image doesn't exist
    stored_hash = result.stdout.strip()
    return stored_hash != current_hash


def build_image(platform_name, platform_config, script_dir, rebuild=False, arch=None):
    """Build the Docker image for the given platform."""
    image_tag = f"{platform_config['image_name']}:{platform_config['image_version']}"
    dockerfile_name = platform_config["dockerfile"]
    dockerfile_path = script_dir / "container" / dockerfile_name
    current_hash = dockerfile_hash(dockerfile_path)

    # A cached local image is only reusable when BOTH its Dockerfile hash and
    # its architecture match. The hash check (has the Dockerfile text changed?)
    # is arch-blind, and we only ever build single-arch images locally under one
    # shared tag. Without the arch check a leftover image from an --arch run
    # could be silently reused for a different target — or a host-arch build
    # could reuse an arm64 image left behind by an earlier --arch build.
    want_arch = arch if arch else host_docker_arch()
    if (
        not rebuild
        and not image_needs_rebuild(image_tag, current_hash)
        and image_provides_arch(image_tag, want_arch)
    ):
        log.info(f"Docker image {image_tag} is up to date.")
        return image_tag

    log.info(f"Building Docker image {image_tag}...")
    cmd = [
        "docker",
        "build",
        "-f",
        str(dockerfile_path),
        "--build-arg",
        f"BASE_IMAGE={platform_config['base_image']}@{platform_config['base_image_sha']}",
        "--label",
        f"dockerfile-hash={current_hash}",
        "-t",
        image_tag,
    ]

    if arch:
        cmd.extend(["--platform", arch])

    for key, value in platform_config.get("extra_build_args", {}).items():
        cmd.extend(["--build-arg", f"{key}={value}"])

    if rebuild:
        cmd.append("--no-cache")

    cmd.extend(["--network", "host"])

    # Expose ci/ as a named build context so the Dockerfile can COPY --from=ci
    # the shared toolchain installers without widening the main build context.
    cmd.extend(["--build-context", f"ci={script_dir / 'ci'}"])

    # Build context is the container/ directory
    cmd.append(str(script_dir / "container"))

    result = subprocess.run(cmd, check=False)
    if result.returncode != 0:
        log.error("Docker image build failed.")
        sys.exit(1)

    return image_tag


def registry_image_ref(platform_name):
    """Return the fully-qualified registry image reference for a platform."""
    platform = get_config()[platform_name]
    return f"{IMAGE_REGISTRY}/{platform['image_name']}:{platform['image_version']}"


def host_docker_arch():
    """Return the Docker daemon's native architecture (e.g. "amd64", "arm64")."""
    result = subprocess.run(
        ["docker", "version", "--format", "{{.Server.Arch}}"],
        capture_output=True,
        text=True,
        check=False,
    )
    return result.stdout.strip()


def image_arch(ref):
    """Return the architecture of a locally-present image, or None if absent."""
    result = subprocess.run(
        ["docker", "image", "inspect", "--format", "{{.Architecture}}", ref],
        capture_output=True,
        text=True,
        check=False,
    )
    if result.returncode != 0:
        return None
    return result.stdout.strip()


def image_provides_arch(ref, arch):
    """Check whether a locally-present image matches the requested arch.

    `arch` may be a full docker platform string ("linux/arm64") or a bare
    architecture ("arm64"); we compare its architecture component against the
    image's own reported architecture.
    """
    return image_arch(ref) == arch.rsplit("/", 1)[-1]


def pull_image(platform_name, arch=None):
    """Pull a pre-built image from the registry.

    Returns the image reference on success or None on failure. When an arch is
    requested, returns None if the registry image does not actually provide it
    (e.g. a legacy single-arch image), so the caller can fall back to a local
    build for the requested architecture.
    """
    ref = registry_image_ref(platform_name)
    log.info(f"Pulling image {ref}...")
    cmd = ["docker", "pull"]
    if arch:
        cmd.extend(["--platform", arch])
    cmd.append(ref)
    result = subprocess.run(
        cmd,
        capture_output=True,
        text=True,
        check=False,
    )
    if result.returncode != 0:
        return None
    if arch and not image_provides_arch(ref, arch):
        log.warning(f"Registry image {ref} does not provide {arch}.")
        return None
    return ref


def build_and_push_image(platform_name, platform_config, script_dir):
    """Build a multi-arch image with buildx and push it to the registry.

    Multi-arch manifests cannot be produced by `docker build` + `docker tag`
    (the local image store holds a single architecture), so this uses
    `docker buildx build --platform ... --push` to build every target
    architecture and push them under one manifest tag. Building a non-host
    architecture relies on QEMU/binfmt being registered on the build host.
    """
    image_name = platform_config["image_name"]
    version = datetime.datetime.now(datetime.timezone.utc).strftime("%Y%m%dT%H%M%SZ")
    ref = f"{IMAGE_REGISTRY}/{image_name}:{version}"

    dockerfile_path = script_dir / "container" / platform_config["dockerfile"]
    current_hash = dockerfile_hash(dockerfile_path)
    architectures = ",".join(platform_architectures(platform_config))

    log.info(f"Building and pushing multi-arch image {ref} ({architectures})...")
    cmd = [
        "docker",
        "buildx",
        "build",
        "--platform",
        architectures,
        "-f",
        str(dockerfile_path),
        "--build-arg",
        f"BASE_IMAGE={platform_config['base_image']}@{platform_config['base_image_sha']}",
        "--label",
        f"dockerfile-hash={current_hash}",
        "-t",
        ref,
    ]

    for key, value in platform_config.get("extra_build_args", {}).items():
        cmd.extend(["--build-arg", f"{key}={value}"])

    # Expose ci/ as a named build context so the Dockerfile can COPY --from=ci
    # the shared toolchain installers without widening the main build context.
    cmd.extend(["--build-context", f"ci={script_dir / 'ci'}"])

    # Build every architecture and push the resulting manifest in one step.
    cmd.append("--push")

    # Build context is the container/ directory
    cmd.append(str(script_dir / "container"))

    result = subprocess.run(cmd, check=False)
    if result.returncode != 0:
        log.error("Docker buildx build/push failed.")
        sys.exit(1)

    log.info(f"Update image_version to \"{version}\" in platforms.json.")


def latest_registry_version(image_name):
    """Query ghcr.io for the latest tag of an image."""
    # Anonymous token — no credentials needed for public images
    token_url = f"https://ghcr.io/token?scope=repository:cfengine/{image_name}:pull"
    token = json.loads(urllib.request.urlopen(token_url).read())["token"]

    tags_url = f"https://ghcr.io/v2/cfengine/{image_name}/tags/list"
    req = urllib.request.Request(
        tags_url, headers={"Authorization": f"Bearer {token}"}
    )
    tags = json.loads(urllib.request.urlopen(req).read()).get("tags", [])
    if not tags:
        return None
    return max(tags)


def update_platform_versions(platform_name=None):
    """Fetch latest image versions from the registry and update platforms.json."""
    config = get_config()

    platforms = [platform_name] if platform_name else list(config.keys())
    for name in platforms:
        image_name = config[name]["image_name"]
        latest = latest_registry_version(image_name)
        if latest is None:
            log.warning(f"No tags found for {image_name}, skipping.")
            continue
        old = config[name]["image_version"]
        if old == latest:
            log.info(f"{name}: already at {latest}")
        else:
            config[name]["image_version"] = latest
            log.info(f"{name}: {old} -> {latest}")

    CONFIG_PATH.write_text(json.dumps(config, indent=2) + "\n")


def latest_base_image_digest(base_image):
    """Fetch current manifest digest from Docker Hub for a base image."""
    # Docker Hub's v2 API path requires a namespace. Official images (ubuntu,
    # debian, ...) carry no namespace and live under "library/"; images that
    # already have an "org/name" namespace (e.g. rockylinux/rockylinux) are
    # used as-is.
    repo, tag = base_image.rsplit(":", 1)
    if "/" not in repo:
        repo = f"library/{repo}"

    # The v2 API requires a bearer token even for anonymous public pulls.
    token_url = (
        "https://auth.docker.io/token"
        f"?service=registry.docker.io&scope=repository:{repo}:pull"
    )
    token = json.loads(urllib.request.urlopen(token_url).read())["token"]

    # Accept only the OCI multi-arch index format: this gives the fat manifest
    # digest (what `docker pull` pins to) rather than an arch-specific one.
    # Docker Hub official images are all published as OCI indexes today; if an
    # image is ever served in the older Docker manifest.list.v2 format instead,
    # the registry will reject the request with 406.
    manifest_url = f"https://registry-1.docker.io/v2/{repo}/manifests/{tag}"
    accept = "application/vnd.oci.image.index.v1+json"

    # HEAD skips the manifest body; the digest comes back in a response header.
    req = urllib.request.Request(
        manifest_url,
        headers={"Authorization": f"Bearer {token}", "Accept": accept},
        method="HEAD",
    )
    with urllib.request.urlopen(req) as resp:
        return resp.headers.get("Docker-Content-Digest")


def update_base_image_shas(platform_name=None):
    """Update base_image_sha in platforms.json to the latest Docker Hub digest."""
    config = get_config()

    platforms = [platform_name] if platform_name else list(config.keys())
    for name in platforms:
        base_image = config[name]["base_image"]
        latest = latest_base_image_digest(base_image)
        if latest is None:
            log.warning(f"No digest returned for {base_image}, skipping.")
            continue
        old = config[name]["base_image_sha"]
        if old == latest:
            log.info(f"{name}: {base_image} already at {latest}")
        else:
            config[name]["base_image_sha"] = latest
            log.info(f"{name}: {base_image} {old} -> {latest}")

    CONFIG_PATH.write_text(json.dumps(config, indent=2) + "\n")


def cache_label(platform_name, role, arch):
    """Return the dependency cache namespace for a build.

    deps-packaging/pkg-cache namespaces cached dependencies by JOB_BASE_NAME,
    which a testing-pr matrix cell exports as "label=<axis value>". Building the
    same string here puts container-built dependencies in the same namespace as
    the ones testing-pr builds, so both jobs share buildcache.
    """
    hub = "_HUB" if role == "hub" else ""
    # The labels spell the architectures x86_64 and arm_64. See labels.txt.
    arch_token = {"amd64": "x86_64", "arm64": "arm_64"}[arch.rsplit("/", 1)[-1]]

    # The cross target's label carries neither an OS version nor _linux.
    if get_config()[platform_name].get("cross_target"):
        return f"PACKAGES{hub}_{arch_token}_mingw"

    # Platform names are <os>-<version>, matching the labels once the separator
    # is swapped, except that the labels say redhat where we say rhel.
    label_os = platform_name.replace("-", "_").replace("rhel_", "redhat_")
    return f"PACKAGES{hub}_{arch_token}_linux_{label_os}"


def platform_role_arch(label):
    """Return the (platform, role, arch) that cache_label() turns into label.

    Found by trying every combination rather than by parsing the label. That
    keeps cache_label() the only place that knows how a label is spelled, so the
    two cannot drift apart.
    """
    for platform_name, platform_config in get_config().items():
        for role in ("agent", "hub"):
            for arch in platform_architectures(platform_config):
                if cache_label(platform_name, role, arch) == label:
                    return platform_name, role, arch
    return None


def run_container(args, image_tag, source_dir, script_dir, label):
    """Run the build inside a Docker container."""
    # Keep the packages in a directory of their own, so that building several
    # platforms into one output directory does not mix them together. The
    # tarballs belong to no platform, so they sit beside those directories.
    subdir = "tarballs" if args.tarballs else label
    output_dir = Path(args.output_dir).resolve() / subdir
    cache_dir = Path(args.cache_dir).resolve()

    # Start from an empty directory. An earlier build's packages carry their own
    # version and build number, so this build does not always overwrite them.
    if output_dir.exists():
        shutil.rmtree(output_dir)

    # Pre-create host directories so Docker doesn't create them as root
    output_dir.mkdir(parents=True, exist_ok=True)
    cache_dir.mkdir(parents=True, exist_ok=True)

    cmd = ["docker", "run", "--rm", "--network", "host"]

    if args.arch:
        cmd.extend(["--platform", args.arch])

    if args.shell:
        cmd.extend(["-it"])

    # Mounts
    cmd.extend(
        [
            "-v",
            f"{source_dir}:/srv/source:ro",
            "-v",
            f"{cache_dir}:/home/builder/.cache/buildscripts_cache",
            "-v",
            f"{output_dir}:/output",
        ]
    )

    # Environment variables
    cmd.extend(
        [
            "-e",
            f"PROJECT={args.project}",
            "-e",
            f"BUILD_TYPE={args.build_type}",
            "-e",
            f"EXPLICIT_ROLE={args.role}",
            "-e",
            f"BUILD_NUMBER={args.build_number}",
            # Who to give the writable mounts back to. The container builds as
            # its own user, whose UID is not ours, so without this the packages
            # and the cache come out owned by a stranger.
            "-e",
            f"HOST_UID={os.getuid()}",
            "-e",
            f"HOST_GID={os.getgid()}",
        ]
    )

    if args.tarballs:
        cmd.extend(["-e", "TARBALLS=yes"])
    else:
        # JOB_BASE_NAME is used by deps-packaging/pkg-cache to derive the cache
        # label. Format: "label=<value>".
        cmd.extend(["-e", f"JOB_BASE_NAME=label={label}"])

    # The remote dependency cache is reachable by publickey only, and pkg-cache
    # aborts the build if an upload fails, so it stays off unless a key was
    # passed. Note that the key is readable by everything the build runs,
    # including each dependency's own build system.
    if args.sftp_key:
        key = Path(args.sftp_key).resolve()
        cmd.extend(["-v", f"{key}:{SFTP_KEY_PATH}:ro"])
    else:
        cmd.extend(["-e", "CACHE_IS_ONLY_LOCAL=yes"])

    if args.version:
        cmd.extend(["-e", f"EXPLICIT_VERSION={args.version}"])

    # Cross-compilation target (e.g. x64-mingw for Windows MSI builds). The
    # build-scripts derive OS/PACKAGING/ARCH from CROSS_TARGET; an env-set value
    # takes precedence over Jenkins label detection.
    cross_target = get_config()[args.platform].get("cross_target")
    if cross_target:
        cmd.extend(["-e", f"CROSS_TARGET={cross_target}"])

    cmd.append(image_tag)

    if args.shell:
        cmd.append("/bin/bash")
    else:
        cmd.append(str(Path("/srv/source/buildscripts/build-in-container-inner.sh")))

    result = subprocess.run(cmd, check=False)
    return result.returncode


def parse_args():
    """Parse and validate command-line arguments."""
    parser = argparse.ArgumentParser(
        description="Build CFEngine packages in Docker containers."
    )
    parser.add_argument(
        "--platform",
        choices=list(get_config().keys()),
        help="Target platform",
    )
    parser.add_argument(
        "--label",
        help="Build what this Jenkins build label names, e.g. "
        "PACKAGES_HUB_x86_64_linux_debian_12. Sets --platform, --role and "
        "--arch, so it replaces all three. See build-scripts/labels.txt.",
    )
    parser.add_argument(
        "--project",
        choices=["community", "nova"],
        help="CFEngine edition",
    )
    parser.add_argument(
        "--role",
        choices=["agent", "hub"],
        help="Component to build",
    )
    parser.add_argument(
        "--build-type",
        dest="build_type",
        choices=["DEBUG", "RELEASE"],
        help="Build type",
    )
    parser.add_argument(
        "--list-platforms",
        action="store_true",
        help="List available platforms and exit",
    )
    parser.add_argument(
        "--arch",
        help="Override the container architecture, passed to docker's --platform "
        "(e.g. linux/amd64, linux/arm64). Default: host architecture.",
    )
    parser.add_argument(
        "--source-dir",
        help="Root directory containing repos (default: parent of buildscripts/)",
    )
    parser.add_argument(
        "--output-dir",
        default="./output",
        help="Output directory for packages (default: ./output)",
    )
    parser.add_argument(
        "--cache-dir",
        default=str(Path.home() / ".cache" / "cfengine" / "buildscripts"),
        help="Dependency cache directory",
    )
    parser.add_argument(
        "--tarballs",
        action="store_true",
        help="Build the source tarballs, into <output-dir>/tarballs, and nothing "
        "else. They are the same whichever platform builds them, so no other "
        "build produces them.",
    )
    parser.add_argument(
        "--sftp-key",
        dest="sftp_key",
        help="Private key for the remote dependency cache. Without it the build "
        "only uses the local cache under --cache-dir.",
    )
    parser.add_argument(
        "--rebuild-image",
        action="store_true",
        help="Force rebuild of Docker image (--no-cache)",
    )
    parser.add_argument(
        "--push-image",
        action="store_true",
        help="Build image and push to registry, then exit",
    )
    parser.add_argument(
        "--update",
        action="store_true",
        help="Fetch latest image version from registry and update platforms.json",
    )
    parser.add_argument(
        "--update-sha",
        dest="update_sha",
        action="store_true",
        help="Fetch latest base image digest from Docker Hub and update platforms.json",
    )
    parser.add_argument(
        "--shell",
        action="store_true",
        help="Drop into container shell for debugging",
    )
    parser.add_argument(
        "--build-number",
        default="1",
        help="Build number for package versioning (default: 1)",
    )
    parser.add_argument(
        "--version",
        help="Override version string",
    )
    args = parser.parse_args()

    if args.list_platforms:
        print("Available platforms:")
        for name, config in get_config().items():
            print(f"  {name:15s}  ({config['base_image']})")
        sys.exit(0)

    if args.update or args.update_sha:
        # --platform is optional for these modes; updates all if omitted
        return args

    if args.label:
        if args.tarballs:
            parser.error("--label and --tarballs build different things")
        if args.platform or args.role or args.arch:
            parser.error("--label already sets --platform, --role and --arch")
        found = platform_role_arch(args.label)
        if not found:
            parser.error(f"no platform builds {args.label}")
        args.platform, args.role, args.arch = found
        log.info(f"{args.label}: {args.platform} {args.role} {args.arch}")

    if args.tarballs:
        # The tarballs are built from core and masterfiles alone, in an image of
        # their own, so the platform, project and role are not choices here. The
        # build type is: it decides their version string.
        args.platform = TARBALLS_PLATFORM
        args.project = "community"
        args.role = args.role or "agent"
        if not args.build_type:
            parser.error("missing required argument --build-type")
        return args

    # --platform is always required (except --list-platforms/--update handled above)
    if not args.platform:
        parser.error("missing required argument --platform")

    if args.push_image:
        # No other arguments are required for --push-image
        return args

    # Validate remaining required arguments for build mode
    if not args.project:
        parser.error("missing required argument --project")
    if not args.role:
        parser.error("missing required argument --role")
    if not args.build_type:
        parser.error("missing required argument --build-type")

    # Cross-compiled Windows (mingw) builds are always Enterprise agent builds.
    if get_config()[args.platform].get("cross_target"):
        if args.project != "nova":
            parser.error(f"--platform {args.platform} requires --project nova")
        if args.role != "agent":
            parser.error(f"--platform {args.platform} requires --role agent")

    return args


def main():
    args = parse_args()

    logging.basicConfig(
        level=logging.INFO,
        format="%(message)s",
    )

    if args.update:
        update_platform_versions(args.platform)
        return

    if args.update_sha:
        update_base_image_shas(args.platform)
        return

    # Detect source directory
    if args.source_dir:
        source_dir = Path(args.source_dir).resolve()
    else:
        source_dir = detect_source_dir()

    script_dir = source_dir / "buildscripts"

    platform_config = get_config()[args.platform]

    if args.push_image:
        build_and_push_image(args.platform, platform_config, script_dir)
        return

    # Resolve image: pull from registry, fall back to local build. The registry
    # holds multi-arch manifests, so a pull with --platform selects the right
    # variant; if it isn't available (e.g. a legacy single-arch image) we build
    # the requested architecture locally.
    if args.rebuild_image:
        image_tag = build_image(
            args.platform, platform_config, script_dir, rebuild=True, arch=args.arch
        )
    else:
        image_tag = pull_image(args.platform, arch=args.arch)
        if image_tag is None:
            log.warning("Registry image unavailable, building image locally...")
            image_tag = build_image(
                args.platform, platform_config, script_dir, arch=args.arch
            )

    if not args.shell:
        log.info(
            f"Building {args.project} {args.role} for {args.platform} ({args.build_type})..."
        )

    # No dependencies are built for the tarballs, so they need no cache label.
    # The arch is the image's, not the host's, which differ under emulation.
    label = (
        None
        if args.tarballs
        else cache_label(args.platform, args.role, image_arch(image_tag))
    )

    # Run the container
    rc = run_container(args, image_tag, source_dir, script_dir, label)

    if rc != 0:
        log.error(f"Build failed (exit code {rc}).")
        sys.exit(rc)

    if not args.shell:
        output_dir = Path(args.output_dir).resolve() / ("tarballs" if args.tarballs else label)
        packages = (
            list(output_dir.glob("*.deb"))
            + list(output_dir.glob("*.rpm"))
            + list(output_dir.glob("*.msi"))
            + list(output_dir.glob("*.tar.gz"))
        )
        if not packages:
            log.error(f"Build produced nothing in {output_dir}.")
            sys.exit(1)

        log.info("Output packages:")
        for p in sorted(packages):
            log.info(f"  {p}")


if __name__ == "__main__":
    main()