Almost every company who sets up Grafana as part of an observability or data visualization service has multiple teams, divisions, or customers of their own to serve.
Each of these teams (we’ll use the term “teams” with a lowercase “t” as a shorthand for these teams/divisions/customers) needs to onboard, ideally as part of a self-serve flow; learn how to get started; and manage and share (or at least see) their own resources like data sources, dashboards, alerts, and even users. Additionally, operators of Grafana need a system that is easy to manage and automate through provisioning and APIs.
Several structures exist within Grafana to organize resources and permissions. Here, we are going to outline our recommendations and future plans for those who want to organize people and resources in Grafana to keep data secure, curate Grafana for their users, and minimize management overhead.
Why get organized?
Our users have told us that there are 4 primary reasons for organizing their people and resources in Grafana:
- Security: Customer A shouldn’t be able to see Customer B’s information.
- Simplicity: With everyone’s dashboards, alerts, etc. mixed together, things become disorderly.
- Cost attribution: They need to track and bill costs to their customers, departments, or divisions.
- Configuration/customization: Department A operates in a different way and wants to have a largely different configuration of their Grafana workspace (version, auth, plugins, etc.).
Our recommendations for organizing resources and people in Grafana differ, depending on these needs.
What is a “team”?
Every Grafana setup is different, but teams can look like this:
- For a Grafana Enterprise customer, a team of 4-8 operators might work on the observability service (including Grafana) itself. These users are generally administrators.
- Similarly, other service teams (like the team that manages a platform as a service or databases) are “two-pizza” teams, fewer than 20 people.
- The audiences for the observability data produced by these teams, like an engineering or devops organization or even an external customer, may be larger, generally in the dozens of users but going up to hundreds.
Best practices for organizing teams in Grafana
Here is how we recommend you organize people and teams in Grafana:
- We recommend you use Folders and Teams to organize, when possible, to manage access to Grafana’s core resources, like dashboards and alerts. Folders and Teams are the easiest organizational tools to manage, and they allow for flexible sharing between teams. We have plans to make folders and teams even more useful in the future.
- We recommend that you use Instances or Stacks to separate teams if you want true isolation — to make sure that no information leaks between teams. You can synchronize some resources between instances using provisioning.
- We rarely recommend Orgs as a way to separate teams, because they lack the flexibility of Folders and the actual isolation of Instances and Stacks. Also worth noting: Orgs are not available in Grafana Cloud. (Grafana Cloud uses the term “Organization” to refer to accounts on grafana.com, but this concept is different from Organizations within the Grafana application itself.)
Here’s what resources you can share and/or isolate using each method:
Folders and Teams
Folders are containers for resources. Currently you can place dashboards, library panels, and alerts into folders (but not other resources like data sources, annotations, reports, or playlists). You can create, view, edit, or admin permissions for folders that apply to all of the resources within them.
Teams are groups of users. You can grant permissions to teams which apply to all members of that team. (I’ll use “team” to refer to an actual group of people, and “Team” with a capital T to refer to the Grafana concept of Team, which groups users).
At a Grafana Enterprise customer, each team of SREs is assigned a Team in Grafana, which correlates with their services, represented as Kubernetes namespaces. The Observability team syncs their Active Directory group to a Grafana team, creates a folder for the team, and gives the team a data source with credentials to access their own namespace from Prometheus/Thanos.
In this case, we would suggest organizing and managing access to Grafana’s core resources like dashboards and alerts by using Folders and Teams.
- Folders and Teams can be provisioned using files or Grafana’s API, and teams can be synced from SSO providers like Active Directory and Google Oauth. That means it is possible to programmatically create a new team onboarding flow that creates a folder, synchronizes team members to a Team in Grafana from an SSO provider, grants the team access to some shared resources, and allows team members to create and manage their own dashboards, alerts, and shared panels.
- Teams also have their own preferences, so you can customize landing pages, time zones, and certain UI preferences for different groups of users. This makes Teams and Folders the most convenient, flexible way to manage onboarding and access.
The most important limitation is that only certain resources can be placed into folders, and therefore access-controlled using folder permissions. Some resources, like data sources, have their own permissions that can be granted to Teams, but others do not. If users create annotations, reports, alert notification channels, API keys, Snapshots, or Playlists, those resources are shared across all Teams.
Orgs provide a measure of isolation within Grafana. Their purpose is to provide completely separate experiences, which look like multiple instances of Grafana, within a single instance. Multiple Orgs are easier and cheaper to manage than multiple Instances of Grafana. However, we rarely recommend Orgs as a way to separate teams, because they lack the flexibility of Folders and the true isolation of Instances and Stacks. Orgs are also not available in Grafana Cloud, where we recommend the use of Stacks instead (see below).
A consumer technology company currently sets up a Grafana Org for each team that onboards to Grafana. Teams act largely independently of each other.
- Orgs are less flexible than Folders:
- Like Folders, Orgs separate access to resources, and they isolate more resources than Folders do. Unlike folders, you can’t choose what to share between them. Orgs isolate Teams, data sources, API keys, plugins, dashboards, folders, and other resources.
- Resources cannot be shared between Orgs, unless you write a program to provision or synchronize resources between them.
- A user must manually switch from one Org to another in order to see its dashboards, folders, etc. You can’t search or move content between Orgs.
- User management is more complicated between Orgs: a user must be separately added/provisioned and managed within each Org.
- Orgs are less isolated than Instances or Stacks:
- All orgs share the same Grafana configuration, meaning they cannot use different authentication providers (Google Auth in one and Okta in another, for example), feature toggles, custom branding, or other customizations that exist at the Instance level.
Grafana Instances and Grafana Cloud Stacks
Grafana Instances are completely isolated deployments of Grafana. Everything — configuration, users, and resources — is separate between Instances. We recommend that you use Instances to separate teams if you want true isolation. For example, you have two customers whose users should never see each other’s data. Grafana Cloud creates a new Grafana Instance (along with Grafana Cloud Metrics, Grafana Cloud Logs, and Grafana Cloud Traces tenants) for each stack.
You can use the API or provisioning to synchronize some data between Instances (like data sources).
A note on billing: A Grafana Enterprise license applies only to a single Instance, but you can purchase licenses for additional Instances for less than the cost of the first one. If a user is active in multiple Instances, they are counted as multiple active users from a licensing perspective.
An IoT company manages a separate Grafana instance for each of their customers, who are chemical plants. They sought to use one instance, but there was no way to separate annotations from each other using Folders or Teams, so they opted instead to operate several independent Instances.
Isolation has its pros and cons. If you want to share resources between multiple instances, you’ll need to use the API or provisioning for synchronization. Additionally, users will no longer truly be looking at a single pane of glass — it can become more complicated for teams to create alerts that link to a common dashboard, or collaborate on dashboards in the UI. It is also more time-consuming and complicated to manage multiple instances and stacks.
Grafana Cloud Organizations
A Grafana Cloud Organization is different from a Grafana Org. A Grafana Cloud Organization usually represents a whole company, and it can contain multiple stacks as well as centralized user management and billing. You might set up multiple Grafana Cloud Organizations if you’d like to separate billing, account management, and administration of all of the Grafana Cloud products you purchase from Grafana Labs. However, almost all Grafana Cloud users have just one Grafana Cloud Organization.
Grafana Labs plans to invest in solving the organizational problems users face in Grafana as they scale to new teams, departments, and divisions, for example by allowing you to place more kinds of Grafana resources into Folders. Eventually this will evolve into personalized experiences for Teams, with an emphasis on different functionality, products, and user flows.
We will invest most heavily in Folders and Teams as a way of organizing people in Grafana, with tools for you to organize more resources into folders, assign specific permissions to Teams, synchronize Teams with SSO providers, add Service Accounts (API keys) to Teams, allow Teams to manage their own resources and not those belonging to other Teams, and more.
We also plan to improve Grafana’s provisioning, APIs, and as-code functionality, to make it easier to manage resources between Instances.
We do not plan to invest heavily in Orgs, because Folders and Teams can provide similar functionality with greater flexibility.
If you’re not already using Grafana Cloud — the easiest way to get started with observability — sign up now for a free 14-day trial of Grafana Cloud Pro, with unlimited metrics, logs, traces, and users, long-term retention, and access to one Enterprise plugin.