Ctrlk

OCI multi-arch manifest

OCI multi-arch manifest for the LinuxGuard agent container image — docker manifest inspect output, supported platforms, image digest stability, and per-platform pull syntax.

The LinuxGuard agent container image is published as a single multi-platform OCI manifest. Pulling packages.linuxguard.io/linuxguard-agent:v3.0.0 from an amd64 host produces a different image digest than pulling the same tag from an arm64 host — but both digests are catalogued by the same manifest list, and operators can pin to either the multi-arch tag (host-architecture resolution) or to a per-platform digest (reproducibility).

Important: The multi-arch manifest covers linux/amd64 and linux/arm64 (full eBPF telemetry) plus linux/arm/v7 (binary published; eBPF probe is a zero-byte sentinel; agent runs in DegradedNoEBPFArch mode). RISC-V (linux/riscv64) is best-effort and may or may not be present in the manifest depending on the release build. See Multi-Architecture Support for the per-architecture capability matrix.

Inspecting the manifest

The OCI manifest list is inspected with docker manifest inspect (Docker 19.03+) or podman manifest inspect. The output enumerates every platform that resolves under the tag.

docker manifest inspect packages.linuxguard.io/linuxguard-agent:v3.0.0

Sample output (abbreviated):

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
  "manifests": [
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "size": 1234,
      "digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "size": 1234,
      "digest": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "platform": {
        "architecture": "arm64",
        "os": "linux",
        "variant": "v8"
      }
    },
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "size": 1234,
      "digest": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
      "platform": {
        "architecture": "arm",
        "os": "linux",
        "variant": "v7"
      }
    }
  ]
}

Each entry in manifests is a per-platform image manifest. The digest field is the immutable SHA-256 of THAT platform's image bytes — different from the tag-level digest (docker pull reports the platform digest, not the manifest-list digest).

Supported platforms

The platforms below resolve under packages.linuxguard.io/linuxguard-agent:vX.Y.Z for current releases. Verify against the live manifest before relying on any specific platform — the manifest is the source of truth.

Platform string

uname -m

Image content

eBPF telemetry

linux/amd64

x86_64

Statically-linked agent binary + compiled probes.bpf.o

Full

linux/arm64/v8

aarch64

Statically-linked agent binary + compiled probes.bpf.o

Full

linux/arm/v7

armv7l / armv6l / arm

Statically-linked agent binary + zero-byte probes.bpf.o sentinel

None — agent runs in DegradedNoEBPFArch mode

linux/riscv64

riscv64

Best-effort — may include probes.bpf.o or sentinel depending on the release build's toolchain

Conditional — verify per release

Not in the manifest:

  • linux/s390x — agent binary may build but is unverified for container deployment. Surface unsupported in v4.0.

  • linux/ppc64le — same as s390x.

  • windows/* — not supported; the agent is Linux-only.

  • darwin/* — not supported; the agent is Linux-only.

How pull-time platform resolution works

When you run docker pull packages.linuxguard.io/linuxguard-agent:v3.0.0 on a host without an explicit --platform flag, Docker:

  1. Fetches the manifest list (the JSON document shown above).

  2. Reads the host's architecture from runtime.GOARCH (which Docker's daemon obtains at startup).

  3. Selects the matching manifests[i].platform entry.

  4. Pulls THAT entry's image bytes by digest.

  5. Reports the per-platform digest as the pulled image's digest.

The same tag therefore produces different digests on different host architectures. This is by design — operators on heterogeneous fleets pin to the tag (e.g., :v3.0.0) and trust the manifest list to resolve per-host. Operators who require byte-identical deployments across the fleet pin to a specific per-platform digest (see § Pinning to a digest).

Per-platform pull syntax

To pull a specific platform on a host whose native architecture differs (e.g., pulling an arm64 image on an amd64 build host for cross-architecture testing), use the --platform flag:

Podman accepts the same flag with identical syntax:

Pulling a platform that does NOT exist in the manifest list (e.g., --platform linux/riscv64 when RISC-V is absent from the current release) produces:

Verify against docker manifest inspect first if you are not sure whether your target platform is present.

Pinning to a digest

The multi-arch tag (:v3.0.0) is convenient but produces different bytes per host architecture. For reproducibility — incident replay, audit trails, byte-identical deployments — pin to a specific per-platform digest:

The digest above is the manifests[i].digest value from the manifest-list inspection. Pinning to a digest:

  • Is reproducible — the same digest always resolves to the same bytes.

  • Is platform-specific — an amd64 digest cannot be pulled on an arm64 host (Docker will not auto-substitute).

  • Survives tag re-publishing — if a :v3.0.0 tag is moved to point at a different manifest list, the digest pin still resolves to the original bytes (until the registry garbage-collects them).

For multi-platform digest pinning across a heterogeneous fleet, pin one digest per platform and select per-host at deploy time:

Refresh the digests on each release. Pinning to a digest indefinitely deprives the cluster of upgrades — establish a cadence (e.g., re-pin on every minor release).

Pinning to the manifest-list digest

For tooling that prefers a single digest across all platforms, pin to the manifest list itself rather than to a per-platform manifest. The manifest-list digest is also reported by docker manifest inspect and crane digest:

The manifest-list digest is stable for the tag — re-publishing the tag with new platform images changes the manifest-list digest. Pinning to it gives you:

  • One digest across all platforms (heterogeneous fleets pin once).

  • Reproducibility — the manifest list is immutable once published.

  • Auto-platform resolution at pull time (Docker still picks the matching platform).

The trade-off: when a new minor release is published, the manifest-list digest changes. You pin to a specific manifest list, not to a specific binary; updates require re-pinning.

Image digest stability

Per-platform digests and manifest-list digests are immutable:

  • A given digest always resolves to the same bytes on the same registry.

  • Re-publishing a tag does NOT modify the digest of the prior manifest list — it creates a new manifest list with a new digest and updates the tag-to-digest mapping.

  • The registry MAY garbage-collect unreferenced digests (no tag points at them); this is registry policy. Pin to a digest of a tagged release if you need long-term retention guarantees.

The packages.linuxguard.io registry retains tagged release digests indefinitely. Untagged or development digests may be GC'd. If you pin to a digest, verify that the digest is referenced by at least one tag at the time of pinning.

Verifying the signed digest

Each per-platform manifest is signed at release time via cosign. Verify the signature on the digest you intend to deploy:

The signature verifies the digest as produced by the LinuxGuard release pipeline. A successful verification prints the certificate's subject and the Rekor transparency-log index. A failed verification means either the digest was not produced by the release pipeline (typosquatted registry, repository compromise) or the signature record is corrupt — do NOT deploy.

Cross-platform considerations

QEMU vs native builds

Multi-architecture OCI images produced via QEMU emulation may pass the build but exhibit different runtime characteristics on native hardware. Specifically:

  • Kernel-version differences — a QEMU build target may have built against a different host kernel than what the deployment target runs. eBPF helper availability is kernel-specific; the build's BTF resolution may select helpers that the deployment kernel does not support.

  • CPU feature drift — QEMU emulates a baseline CPU; native hardware may have additional instructions the binary was not built to use, OR may lack instructions the binary assumes (rare for the agent's static build, but possible for non-standard ARM SoCs).

Always run a linuxguard-agent probe on a representative target host before relying on a multi-arch image in production. The probe reports kernel, BPF, fanotify, netlink, audit, and capability availability for the running environment — if the probe degrades, the image does not match the kernel.

Cross-architecture pulls on Apple Silicon

macOS hosts running Docker Desktop on Apple Silicon (M-series CPUs) default to linux/arm64/v8 when pulling Linux images. To pull the amd64 variant (for build pipelines that target x86 deployment):

The image runs under QEMU emulation. Performance is degraded; use this only for build / test workflows, not for production.

Architecture-specific Docker Hub mirroring

If your environment mirrors packages.linuxguard.io to an internal registry, mirror by digest rather than by tag. Mirroring by tag re-publishes only the active platform's image; the manifest list is lost. Use crane copy (which preserves manifest lists) rather than docker pull + docker push (which does not):

crane copy preserves the full manifest list including all platform variants and signatures.

ARMv7 special handling

The ARMv7 variant (linux/arm/v7) ships the agent binary but a zero-byte sentinel in place of the compiled eBPF object. The runtime detects this at startup:

The agent then runs without eBPF — no behavioral telemetry, no auth events, no eBPF-derived file monitor. The agent does continue to provide configuration management, package inventory, syslog forwarding, and support-bundle collection.

If your compliance posture depends on continuous behavioral telemetry, ARMv7 deployments will NOT contribute that evidence. Treat ARMv7 hosts as a documented gap in the evidence chain — see Multi-Architecture Support § Operational Notes § Compliance Implications.

Cross-references

Next Step: Container deployment hub →

Related: Multi-Architecture Support | Distroless image reference | Container deployment hub | Supported Distributions

PreviousPodmanNextConfigure

Last updated

Was this helpful?