Skip to main content
Keeping technical reference data accurate, up-to-date, and reusable across teams is harder than it looks—especially at scale. Meta-Upsun architecture At Upsun, many parts of our platform rely on reference information: supported runtime versions, service images, PHP extensions, public regions, deprecated versions, and more. These data sets power our documentation, validation tools, internal workflows, and are increasingly consumed by ecosystem tooling. Our clients also need this information for their own business automation (business operations and therefore increased demand). Many customers ask for this kind of information, and Meta-Upsun allows us to provide such info in a broader format. Over time, this information had grown fragmented. This post explains why we built Meta-Upsun, what problems it solves, how it fits into the future of Upsun’s documentation and tooling ecosystem, and how the Upsun platform—through its agile-friendly features—enabled us to deliver this solution in a very short timeframe.

​
The problem: reference data everywhere

Historically, Upsun’s technical reference data lived in multiple places:
  • YAML and JSON files embedded directly in the documentation repository
  • Registry files manually updated by Technical writers
  • Data duplicated or reinterpreted by external tools
  • Updates spread across several repositories, each with its own lifecycle
In total we were dealing with reference material scattered across 36 different Git repositories with branch variations for our internal images, plus 4 upstream API calls (including endoflife.date and the Upsun API) that fed version lifecycles and status. This approach had several drawbacks:
  • ❌ Manual updates were time-consuming and error-prone
  • ❌ Hard to find the source of truth for technical writers
  • ❌ Inconsistent data between docs, tooling, and internal usage
  • ❌ Poor reusability for teams outside the documentation pipeline
  • ❌ Slow iteration when adding or deprecating versions
As the number of supported services, runtimes, and regions increased, maintaining these files by hand simply didn’t scale anymore.

​
Introducing Meta-Upsun: Upsun reference, centralised

To address this, we built Meta-Upsun, a publicly exposed infrastructure component designed to centralise Upsun’s technical reference data in a single place. 👉 https://meta.upsun.com Meta-Upsun acts as a single source of information for everything that defines what Upsun supports. It provides:
  • A unified registry for images, runtimes, regions, and extensions
  • A read-only API, consumable by humans and machines
  • Granular access to specific data (for example, only PHP image versions)
  • Outputs in JSON or YAML, depending on your needs
The goal is simple: one canonical location for reference data, consumed everywhere else.

​
A read-only, versioned API

Meta-Upsun exposes its data through a versioned REST API:
  • 📘 OpenAPI / Scalar documentation 👉 https://meta.upsun.com/api-docs
  • 🔒 Read-only by design No write endpoints, no mutations from consumers.
  • 🧩 Granular access You can fetch:
    • All images or a single runtime
    • Only versions
    • Regions filtered by provider or geographic zone
    • PHP extensions per version and distribution
If you just want the complete image registry, the main endpoint is: Meta-Upsun Scalar - Get Image screenshot The Scalar UI lets you explore endpoints interactively and generate ready-to-run client snippets (curl, and other languages).

​
Reliability and validation built-in

Accuracy is critical for reference data. Meta-Upsun enforces it at multiple levels:
  • ✅ Schema validation of registry files (currently for registry.json, with more coming)
  • ✅ Human validation via pull requests: all updates go through PRs
  • ✅ Versioned endpoints, already used by the next generation of Upsun documentation
  • ✅ Consistent structure, enforced by OpenAPI and runtime validation
This combination gives us confidence that the data exposed by Meta-Upsun is both machine-safe and human-reviewed.

​
Aligning registry status with upstream support

In the early days the registry simply split versions into supported and deprecated buckets: 
"versions": {
  "deprecated": [
    "5.0",
    "3.1",
  ],
  "supported": [
    "8.0",
    "7.0",
    "6.0"
  ]
}
Supported meant Upsun shipped the image, and deprecated meant Upsun no longer actively supported it. That naming did not match the official runtime/service version taxonomy, so Meta-Upsun now classifies every version according to the upstream lifecycle, most of which we track via endoflife.date.
  • Active / supported – the version is still in upstream active support.
  • Deprecated – active support has ended, only critical security updates land.
  • Retired – the community considers the version end-of-life, we keep the image available “as-is” for roughly 180 days while customers switch, but we stop applying patches.
  • Decommissioned – the image is removed and can no longer be built; projects both old and new will fail to build against it.
"versions": {
  "8.5": {
    "upsun": {
      "status": "supported"
    }
  },
  "8.3": {
    "upsun": {
      "status": "deprecated"
    }
  },
  "8.1": {
    "upsun": {
      "status": "retired"
    }
  },
  "5.3": {
    "upsun": {
      "status": "decommissioned"
    }
  },
We still make sure the highest upstream image we offer is fully supported by Upsun, but Meta-Upsun now mirrors the official naming so that anyone consuming registry.json (human or machine) understands exactly where a version stands. We will cover this change in more depth in a follow-on episode that unpacks how Meta-Upsun now exposes the registry structure and what consumers should expect.

​
How Meta-Upsun fits into the ecosystem

Meta-Upsun is designed as a shared infrastructure layer. The typical consumers look like this: Meta-Upsun architecture

​
Powering the next generation of documentation

Meta-Upsun is already used internally as a foundation for future-facing projects. One concrete example: we are currently migrating our documentation stack. Instead of embedding reference data directly in Markdown files, the new documentation can consume Meta-Upsun’s API endpoints to display:
  • Supported, deprecated and retired versions
  • Runtime and service matrices
  • PHP extensions per version
  • Region availability
This ensures that the documentation always reflects the current state of the platform, without manual duplication.
This topic is covered in more detail in a dedicated blog post, which we’ll link here once published.

​
Leveraging Upsun’s agility

Upsun’s platform helped us move fast: we relied on its reusable infrastructure (CI/CD, environments, observability hooks, and deployment artifacts) to build Meta-Upsun iteratively, validate it in staging, and ship updates within days rather than weeks. This solution is a direct benefit of Upsun’s focus on enabling agile delivery for internal and customer-facing tooling. Several Upsun teammates contributed to this project, each bringing ideas or validations from their domain to help accelerate delivery.

​
What’s next

Meta-Upsun is not just a backend for documentation. It is designed to be consumed by:
  • Internal tooling
  • Validation pipelines
  • External teams and ecosystem tools
In the next article, we’ll dive into Meta-Upsun Version Updater, the automation layer that keeps Meta-Upsun aligned with upstream runtimes, service releases, and platform reality—without manual effort. Another upcoming episode will focus on the registry structure changes on Meta-Upsun and how we now align the version categorisation with upstream lifecycle terminology.
To learn more about Upsun, visit our comprehensive documentation.
Last modified on April 14, 2026