Last modified July 9, 2026

Migrate Grafana organizations to v1alpha2

This guide shows you how to migrate your GrafanaOrganization resources from the v1alpha1 to the v1alpha2 API version. The v1alpha2 version introduces structured tenant configuration with granular access control. Existing v1alpha1 resources keep working through automatic conversion, but migrating lets you take advantage of the new features. For creating organizations in the first place, see creating a Grafana organization.

Key differences

Migration examples

Basic tenant migration:

# v1alpha1 format
spec:
  tenants:
  - "my-app"
  - "production"
  - "staging"

# v1alpha2 equivalent (full access)
spec:
  tenants:
  - name: "my-app"
    types:
    - data
    - alerting
  - name: "production"
    types:
    - data
    - alerting
  - name: "staging"
    types:
    - data
    - alerting

Taking advantage of granular access control:

# v1alpha2 with different access levels
spec:
  tenants:
  # Production: full access (data and alerting)
  - name: "production"
    types:
    - data
    - alerting
  # Development: metrics and logs only (no alerting)
  - name: "dev-metrics"
    types:
    - data
  # Staging: metrics and logs only
  - name: "staging"
    types:
    - data
  # Alert management: alerting functionality only
  - name: "alert-config"
    types:
    - alerting

Access types explained

• data: Provides access to metrics and logs data sources (Mimir and Loki) in Grafana
• alerting: Provides access to alerting functionality and alert management (Alertmanager) in Grafana

You can specify both types for full access, or use them separately for restricted access based on your security requirements.

Automatic migration behavior

When you update existing v1alpha1 resources, they’re automatically converted to v1alpha2:

• Each tenant string is converted to a TenantConfig object
• The name field is set to the original tenant string
• The types field defaults to ["data", "alerting"] (full access)

Migration best practices

1. Test first: Validate your v1alpha2 configuration in a non-production environment
2. Review access: Use the migration as an opportunity to review and refine tenant access permissions
3. Roll out gradually: Migrate one organization at a time to ensure smooth transitions
4. Monitor impact: Verify that users retain appropriate access after migration
5. Use granular access: Take advantage of the new access types to implement the principle of least privilege

See also

• Creating a Grafana organization: create and configure organizations
• GrafanaOrganization CRD reference: the full resource schema
• Multi-tenancy: how tenants isolate observability data