What Is Perses? The Beginner's Guide to CNCF Dashboard-as-Code

CodexFuse Team · 2026-11-04T17:55:42.299Z · 10 min read min read

What Is Perses, Exactly?

Perses is an open-source dashboard tool for observability data, designed from the ground up so that dashboards are written as code instead of clicked together in a web UI. The official documentation puts it this way: "Perses is first and foremost a dashboard tool that you can use to display a variety of observability data. It currently supports Prometheus metrics, Tempo traces, Loki for logs, Pyroscope for profiling, bringing together all four observability pillars in one place."

The project's goal is bigger than one tool: Perses is an initiative to define an open, standardized dashboard specification — one format that any observability platform could read. It is a Cloud Native Computing Foundation project at the sandbox maturity level, which means it is early in its CNCF journey, and every component is licensed under the Apache 2.0 License. Perses explained in one sentence: a dashboard tool whose definitions are code, whose history lives in Git, and whose deployments run through pipelines.

If you already run Grafana dashboards for your services, Perses is best understood as the dashboard-as-code alternative: same job — visualizing metrics, logs, and traces — but a completely different workflow for creating and managing those dashboards.

Why Does Perses Exist?

Perses exists because of dashboard drift — the slow rot that hits hand-built dashboards. Someone clicks a panel into existence at 2 AM during an incident, changes a threshold in the UI, and nobody writes the change down. Multiply that across hundreds of dashboards and you get a monitoring setup nobody can rebuild, review, or trust.

The project was born inside Amadeus R&D, where the team was "managing thousands of dashboards" — over 5,000 in production use. They tried templating dashboards with Jsonnet, and it "didn't meet our scaling needs." So they built "a clean, human readable data model and a dedicated dashboard-as-code framework with supporting SDKs," then donated the project to the CNCF, "which accepted it, as we believed it was a missing piece in the observability landscape." That framing is the key to Perses: it was built by a team drowning in dashboards, not by a vendor trying to sell one.

The wider ecosystem noticed. Julius Volz, the creator of Prometheus, called Perses "a new OSS dashboard builder project with a GitOps-first approach and the goal of making it a Cloud Native Computing Foundation alternative to Grafana." It was unveiled at PromCon EU in September 2023 and accepted into the CNCF as a sandbox project on August 29, 2024.

What Does Perses Actually Do?

At its core, Perses renders observability data as dashboards. You define dashboards in a human-readable text format, store them in Git, validate them automatically, and deploy them wherever Perses runs — as a standalone server, or as Kubernetes Custom Resource Definitions managed by an operator.

The supported data sources cover all four observability pillars: Prometheus for metrics, Tempo for traces, Loki for logs, and Pyroscope for profiling. That breadth matters for a beginner: one dashboard can combine a request-latency chart (metrics), the trace behind a slow request (traces), and the application logs from that same window (logs), without leaving the tool.

Beyond the core, Perses ships a metrics explorer and a PromQL debugger, and its panels can be embedded into other interfaces — including the Prometheus UI itself — through published npm packages. The project also targets an "open specification for dashboards," meaning the format is designed so other tools could read and render Perses dashboards too.

What Is Dashboard-as-Code, and How Does Perses Implement It?

In short, dashboard as code means your dashboards are text files that live in version control, get reviewed in pull requests, and deploy through your normal CI/CD pipeline — the same way your infrastructure does. If a dashboard breaks, you git bisect. If a panel is wrong, you read the diff. That is the workflow Perses is built around.

You author dashboards with the CUE or Go SDKs, or directly in JSON/YAML. Here is the official minimal dashboard example, exactly as documented:

{
  "kind": "Dashboard",
  "metadata": {
    "name": "my-dashboard",
    "project": "default"
  },
  "spec": {
    "display": {
      "name": "My Dashboard"
    },
    "panels": {
      "panel1": {
        "kind": "Panel",
        "spec": {
          "display": {
            "name": "Sample Panel"
          },
          "plugin": {
            "kind": "TimeSeriesChart",
            "spec": {}
          }
        }
      }
    }
  }
}

A dashboard is just a named object with panels, and a panel is just a named object with a plugin. Because the format is fully specified, Perses "offers a complete static validation of the dashboard format" — and you can extend it with custom lint rules, so your team's dashboard conventions are enforced in CI rather than in code-review comments.

The workflow runs through percli, the Perses CLI. The documented flow is: percli dac setup to scaffold a dashboard-as-code project, percli dac build -f main.go -ojson (or -f my_dashboard.cue) to compile your dashboard definition, and percli apply -f built/my_dashboard.json to deploy it to the Perses server. percli dac watch gives you a live-rebuild loop while you develop. GitHub Actions gets reusable workflows for building and applying dashboards straight from a pull request.

Coming from Grafana? There is a migration path: percli migrate -f grafana-dashboard.json --online -o json > perses-dashboard.json converts an existing Grafana dashboard export into the Perses format, so you can move dashboards over one at a time instead of rebuilding them by hand.

Perses vs Grafana: How Do They Compare?

Perses and Grafana solve the same problem — visualizing observability data — with opposite philosophies. Grafana is the established default: a mature, UI-first platform where dashboards are built by dragging panels around in a browser. Perses is the code-first challenger: dashboards are authored as text, versioned in Git, and deployed by pipelines.

The differences that matter most to a beginner:

The license row deserves one line of explanation: Grafana is licensed under AGPLv3, while Perses is "100% open source and community-driven" under the Apache 2.0 License, which is friendlier to teams that embed or redistribute the software.

The honest caveat, from an independent October 2026 assessment: Perses remains "Sandbox, not graduated or even incubating, with a smaller plugin and prebuilt-dashboard ecosystem than Grafana's decade-deep library." If you need a specific plugin today, check whether Perses has it. For a deeper walkthrough of the incumbent, see our Grafana beginner guide.

How to Run Your First Perses Dashboard in 5 Steps

This five-step Perses tutorial takes you from zero to a running dashboard, using the official container image. You need Docker on your machine — a local server or a VPS hosting plan both work.

1. Start the server. Run the official image: docker run --name perses --rm -p 127.0.0.1:8080:8080 persesdev/perses. This is the exact documented install command, and images are published for both amd64 and arm64.
2. Open the UI. Visit http://localhost:8080 in your browser. There is no login by default — you land straight in the Perses UI.
3. Create a project. Projects are the top-level namespace: every dashboard lives inside one. Create a project and give it a short, lowercase name.
4. Add a data source. Point Perses at something that produces data — a Prometheus instance for metrics is the natural first choice. The dashboard you build can only visualize data Perses can reach.
5. Deploy a dashboard. Build the minimal dashboard definition from the Dashboard-as-Code section above and apply it with percli (percli apply -f), or experiment in the UI first and export the definition to start versioning it. Open the dashboard in the browser and confirm the panel renders.

If you already have Grafana dashboards you like, use percli migrate to convert them instead of starting from scratch — then commit the results and let CI own them from there.

How Does Perses Run on Kubernetes?

The Perses Kubernetes story is what separates it from every other dashboard tool: dashboards are Custom Resource Definitions — first-class cluster objects, reviewed and versioned like everything else in GitOps. Perses is Kubernetes-native in the literal sense: dashboard definitions can be deployed as CRDs straight into application namespaces, and an operator reconciles them.

The prometheus-operator project ships Perses as an opt-in addon. It deploys the perses-operator plus four CRDs — Perses, PersesDashboard, PersesDatasource, and PersesGlobalDatasource — and the default setup loads 23 ready-made PersesDashboard resources from the community-mixins packages, covering Kubernetes, Prometheus, Alertmanager, and node-exporter dashboards. The Perses instance runs on port 8080, with authentication disabled by default, just like the bundled Grafana it can replace.

That last point is worth pausing on: you can already swap Grafana for Perses in a kube-prometheus stack today by setting grafana: {} in your jsonnet config and enabling the addon. It is opt-in, and the maintainers say it may be promoted to a built-in toggle once the integration matures.

Who Is Perses For — and Who Should Skip It?

Perses is for platform teams that already live in Git: teams running Kubernetes, practicing GitOps, and tired of dashboards that only exist in somebody's browser session. If your dashboards should be reviewable, reproducible, and restorable from a repo, Perses is built exactly for you.

Who should wait? If you are a solo developer who just wants a quick chart of server metrics, Grafana's point-and-click UI gets you there in minutes — Perses's code-first workflow adds setup cost you do not need yet. And because Perses is a CNCF sandbox project (accepted August 29, 2024; still sandbox as of November 2026), you should treat it like any young project: verify the plugin and datasource coverage your stack requires before committing.

The momentum is real, though. Perses ships as part of the Red Hat OpenShift observability stack, Red Hat and Chronosphere contribute to the project, Amadeus is rolling out the general-availability version across its own infrastructure, and vendors like Dash0 build on the Perses format as "the emerging CNCF standard" for dashboard configuration as code.

Sources

Every factual claim in this article was verified from a page fetched on 2026-11-04: the official Perses documentation at perses.dev (overview, dashboard-as-code getting-started, and in-a-container installation guides, docs labeled v0.55); the CNCF project page for Perses (cncf.io/projects/perses — sandbox acceptance August 29, 2024, first commit January 26, 2021); the Amadeus engineering blog post "Open Source Matters: Amadeus Perses" (amadeus.com); the Logz.io PromCon EU 2023 recap (Julius Volz quote, Amadeus rollout, 5,000+ dashboards); the AppsCode "Getting Started with Perses" guide (percli commands, migration command, Perses vs Grafana comparison); the prometheus-operator documentation for the perses addon (CRDs, port 8080, 23 default dashboard resources); the Prometheus documentation's Perses page (no-login default); the Dash0 changelog (Perses as emerging CNCF standard); the bex.co October 2026 observability comparison (ecosystem caveat); the Conf42 Kube Native 2024 slide deck (Perses goals and percli); and the perses.dev helm-charts documentation (minimal dashboard JSON example, quoted verbatim).

Frequently Asked Questions

Is Perses a replacement for Grafana?

It can be — the prometheus-operator addon exists precisely to replace Grafana with Perses in a kube-prometheus stack — but it is a younger, code-first alternative rather than a drop-in clone. Teams choose it for the GitOps workflow and Apache 2.0 license; they stay with Grafana for its decade-deep plugin library.

Does Perses store metrics itself?

No. Perses is a dashboard and visualization tool, not a metrics store. It reads data from external sources — Prometheus, Tempo, Loki, and Pyroscope — and renders it. Your metrics still live wherever they live today.

What is percli?

percli is the Perses command-line interface: the documented tool for interacting with the Perses API, scaffolding dashboard-as-code projects (percli dac setup), building dashboard definitions, linting them, migrating Grafana dashboards, and applying resources in CI/CD pipelines.

Is Perses production-ready?

It is a CNCF sandbox project, which signals early maturity — not a graduation stamp. That said, it ships in the Red Hat OpenShift observability stack, and Amadeus is rolling out a general-availability version across its own infrastructure, so real production use exists. Evaluate the plugin and datasource coverage your stack needs before committing.

What does dashboard as code mean in practice?

Your dashboards are text files in Git. You write them with the CUE or Go SDKs (or YAML/JSON directly), validate them with static checks in CI — including custom lint rules your team defines — and deploy them with percli or a Kubernetes operator. Changes go through pull requests; rollbacks are git reverts.