Skip to main content

GETTING STARTED WITH GRAFANA

In this tutorial, we will pull the @keeb/grafana extension into a new Swamp repository, so that the repository has a behavior type for working with a Grafana server.

What we will build

We start from an empty Swamp repository and finish with the @keeb/grafana extension installed in it. The extension provides the @keeb/grafana/instance behavior type. Every Grafana task in the how-to guides starts from a behavior of this type.

Prerequisites

  • Swamp installed (see Install Swamp)
  • Signed in with swamp auth login
  • A terminal open in an empty directory where you have run swamp repo init

Pull the Grafana extension

We pull the extension from the registry into our repository:

swamp extension pull @keeb/grafana

You will see output like:

INF extension·pull: Pulling "@keeb/grafana"@"2026.07.18.1"
INF extension·pull: Identity verified: "@keeb/grafana"@"2026.07.18.1"
INF extension·pull: Pulled "@keeb/grafana"@"2026.07.18.1"
INF extension·pull: Extracted 7 files:

The extension is now part of this repository. Notice the extension name in the output. It is the name we will see on the registry page, and the behavior type it provides is called @keeb/grafana/instance.

What the behavior type expects

A behavior of type @keeb/grafana/instance needs one value before it can run: grafanaUrl, the address of the Grafana server, for example http://grafana.example.local:3000. A second value, apiKey, is optional. When a Grafana server needs an API key, the key is kept in a vault, as in the Storing Secrets tutorial, and is never written into the definition.

What we built

We pulled @keeb/grafana into a fresh Swamp repository. The repository now has the @keeb/grafana/instance behavior type, which connects to a Grafana server through its grafanaUrl. The how-to guides start from this point: push a dashboard JSON file to Grafana.