# Manage workspaces, users, and policies in Amazon Managed Grafana To use Amazon Managed Grafana you create Grafana workspaces. A Grafana workspace is a logical Grafana server, where you can create Grafana dashboards and visualizations to analyze your metrics, logs, and traces. You add users and manage their permissions to administer, edit, or view the workspaces. You can upgrade your workspace to newer versions of Grafana, or update to add support for Enterprise plugins, giving your workspaces access more types of data sources. You can also manage the network access to your workspace. You can create and manage your Amazon Managed Grafana workspaces using CloudFormation. The topics in this section explain how to manage your workspaces, users, and policies in Amazon Managed Grafana. **Topics** + [Differences between Grafana versions](version-differences.md) + [Create an Amazon Managed Grafana workspace](AMG-create-workspace.md) + [Authenticate users in Amazon Managed Grafana workspaces](authentication-in-AMG.md) + [Update your workspace version](AMG-workspace-version-update.md) + [Manage access to Enterprise plugins](upgrade-to-enterprise-plugins.md) + [Migrate content between Amazon Managed Grafana workspaces](AMG-workspace-content-migration.md) + [Manage user and group access to Amazon Managed Grafana workspaces](AMG-manage-users-and-groups-AMG.md) + [Manage permissions for data sources and notification channels](AMG-datasource-and-notification.md) + [Creating Amazon Managed Grafana resources with AWS CloudFormation](creating-resources-with-cloudformation.md) + [Configure network access to your Amazon Managed Grafana workspace](AMG-configure-nac.md) + [Encryption at rest](AMG-encryption-at-rest.md) + [Connect to data sources or notification channels in Amazon VPC from Amazon Managed Grafana](AMG-configure-vpc.md) + [Configure a Amazon Managed Grafana workspace](AMG-configure-workspace.md) + [Delete a Amazon Managed Grafana workspace](AMG-edit-delete-workspace.md) # Differences between Grafana versions When [creating a Grafana workspace](AMG-create-workspace.md), you must choose a Grafana version to create. You can choose between versions compatible with Grafana versions 8, 9, 10, and 12. Each of these has added functionality from the previous version. The following topics describe the changes in versions 9, 10, and 12, including changes that might break functionality that you use in previous versions. **Note** You can read version-specific documentation for using your Grafana workspace in the [Working in Grafana version 12](using-grafana-v12.md), [Working in Grafana version 10](using-grafana-v10.md), [Working in Grafana version 9](using-grafana-v9.md), and [Working in Grafana version 8](using-grafana-v8.md) topics. For detailed notes by version, and more information from Grafana Labs, see [What's new in Grafana](https://grafana.com/docs/grafana/latest/whatsnew/) in the *Grafana Labs documentation*. ## Grafana version 12 The following features were added in Grafana version 12. **Drilldown apps** + **Metrics Drilldown** – A queryless, point-and-click experience for exploring Prometheus metric data. See [Metrics Drilldown](v12-drilldown-metrics.md). + **Logs Drilldown** – A queryless experience for browsing Loki logs with volume and text patterns. See [Logs Drilldown](v12-drilldown-logs.md). + **Traces Drilldown** – A queryless experience for exploring distributed Tempo traces. See [Traces Drilldown](v12-drilldown-traces.md). + **Profiles Drilldown** – A queryless experience for browsing Pyroscope profiling data. See [Profiles Drilldown](v12-drilldown-profiles.md). **Dashboards and visualizations** + **Scenes-powered dashboards** – The dashboard rendering engine has been rebuilt using the Scenes framework, providing improved performance, better template variable support, and more flexible layouts. + **New table visualization** – The table panel has been completely rebuilt for improved performance and new capabilities, including CSS cell styling, tooltip generation from table fields, an improved footer, a new Actions cell type for interactive buttons, and auto-formatted cell values in Cell Inspect. + **Canvas visualization improvements** – Canvas panels now support one-click data links and actions, dynamic connection directions, the ability to disable tooltips, and pan and zoom improvements, giving you more control over interactive data-driven layouts. + **Visualization actions** – You can now add interactive actions to visualizations that trigger API calls or navigate to URLs, with support for custom variables, one-click data links, and a new Actions cell type for table visualizations. + **Colored table rows with conditional formatting** – Table visualizations now support row-level conditional formatting, allowing you to color entire rows based on data values. + **Stat visualization percent change** – Stat panels now display percent change with configurable color mode options, making it easier to see trends at a glance. + **Legend support in bar gauge** – Bar gauge visualizations now support legends, improving readability when displaying multiple series. + **State timeline pagination** – State timeline visualizations now support pagination, making it easier to navigate large datasets. + **Redesigned dashboard filters** – Dashboard list filters have been redesigned for a more intuitive browsing experience. + **Switch variable type** – A new Switch variable type lets you quickly toggle between values in queries, simplifying dashboard interactions. + **Static options for query variables** – Query variables now support static options, giving you more control over variable values without requiring a data source query. + **Enhanced ad hoc filters** – Ad hoc filters now provide improved support across data sources, making it easier to dynamically filter dashboard data. + **Better time region control with Cron syntax** – Annotations now support Cron syntax for time regions, providing more precise control over time-based annotations. + **Improved geomap performance** – Geomap visualizations now render significantly faster with improved performance optimizations. + **Navigation bookmarks** – You can now bookmark frequently used pages in the navigation menu for quick access. + **Set threshold colors from query** – The Config from query transformation now supports setting threshold colors dynamically based on query results. + **Enhanced custom currency format** – A new custom currency format option lets you display exact financial values with precise decimal control. + **Server-configurable quick time ranges** – Administrators can now configure the quick time range options available in dashboard time pickers. + **Announcement banner** – Administrators can now display announcement banners to communicate important information to workspace users. **Transformations** + **Substring matcher in Filter by value** – The Filter by value transformation now includes a substring matcher, making it easier to filter data based on partial text matches. + **Trendline transformation** – A new Trendline transformation lets you spot patterns in your data by adding trend lines and moving averages to visualizations. + **Binary transformation for all number fields** – You can now apply the same binary transformation to all number fields in a table at once, reducing repetitive configuration. + **New regex option for Extract fields** – The Extract fields transformation now supports regular expressions, providing more powerful field extraction from text data. + **Transformation updates** – Multiple transformation improvements have been added, including new modes and usability enhancements across the transformation pipeline. + **Dashboard variables in all transformations** – Dashboard variables are now supported in all transformation types, expanding the flexibility of data processing pipelines. **Alerting** + **Keep Last State for Grafana Managed Alerting** – Alert rules can now be configured to keep their last state when a query returns no data or an error, preventing unnecessary alert state changes. + **Alert detail view redesign** – The alert rule detail view has been redesigned with a clearer layout and more actionable information. + **Alerting template selector** – A new template selector in the alerting UI makes it easier to choose and apply notification templates. + **Improved paused alert visibility** – Paused alert rules are now more clearly indicated in the UI, making it easier to identify which rules are not actively evaluating. + **Only available for Grafana-managed alerts: rule-specific silences** – You can now create silences that apply to specific alert rules with granular permissions, providing more targeted alert suppression. + **Recording rules for Grafana-managed alerts** – Recording rules are now available for Grafana-managed alerts, allowing you to precompute frequently used queries for better performance. This replaces the deprecated recorded queries feature. See [Configure recording rules](v12-alerting-configure-recordingrules.md). + **Alert rule version history** – Alert rules now maintain a version history, allowing you to track changes and revert to previous configurations. + **Grafana-managed alert rule "Recovering" state** – Alert rules now support a "Recovering" state that indicates when an alert condition is no longer firing but has not yet returned to normal. + **Alert rule improvements** – Grafana-managed alert rules include multiple usability improvements, including updated list pages, active time intervals, the ability to import rules from Prometheus YAML, and a redesigned settings page. **Explore and logs** + **New logs visualization** – A new logs visualization panel provides improved log rendering with a new field selector component for customizing which fields are displayed. + **JSON Log Line Viewer** – The Logs Drilldown app now includes a JSON viewer for structured log lines, making it easier to inspect JSON-formatted log data. + **Forward direction search for Loki** – Loki queries in Explore now support forward direction search, allowing you to search logs from oldest to newest. + **Correlations in Explore** – You can now add correlations to external URLs directly from Explore, enabling seamless navigation between data sources and external systems. See [Correlations in Grafana version 12](v12-correlations.md). **Data sources** + **Amazon Managed Service for Prometheus data source migration** – Starting with this release, Sigv4 authentication support in the Core Prometheus plugin has been deprecated. When you upgrade to Grafana version 12, all Amazon Managed Service for Prometheus data sources that were previously using the Core Prometheus plugin are automatically migrated to the Amazon Managed Service for Prometheus plugin. Any dashboards using these data sources are automatically updated to reflect this change. + **Amazon CloudWatch Logs Insights with PPL and SQL** – You can now query Amazon CloudWatch Logs Insights using PPL (Piped Processing Language) and SQL syntax in addition to the standard query language. + **Amazon CloudWatch Metric Insights cross-account support** – Amazon CloudWatch Metric Insights now supports cross-account observability, allowing you to query metrics across multiple AWS accounts. + **Amazon CloudWatch Logs Anomaly Detection and Pattern Analysis** – The Amazon CloudWatch data source now supports log anomaly detection and pattern analysis for identifying unusual patterns in your log data. + **OpenSearch PPL and Sample Queries** – The OpenSearch data source now supports PPL language and sample queries for easier query building. + **MSSQL Windows Active Directory authentication** – The Microsoft SQL Server data source now supports Windows Active Directory (Kerberos) authentication. + **Removal of old Tempo and Loki Search** – The legacy Tempo Search and Loki Search interfaces have been removed in favor of the TraceQL-powered search experience. + **BigQuery Service Account Impersonation** – The BigQuery data source now supports service account impersonation for more flexible authentication. + **Google Sheets template variables** – The Google Sheets data source now supports template variables for dynamic data queries. + **Time series macro support for SQL data sources** – The visual query builder for SQL data sources now supports time series macros, simplifying time-based queries. + **Unity Catalog support in Databricks** – The Grafana Databricks plugin now supports Unity Catalog for unified data governance. + **Honeycomb raw query support** – The Honeycomb data source now supports raw queries for advanced query capabilities. + **GitHub App authentication** – The GitHub data source now supports GitHub App authentication as an alternative to personal access tokens. **Authentication and security** + **API keys migrated to service accounts** – API keys have been fully deprecated and automatically migrated to service accounts, providing improved security and management capabilities. See [Using service accounts](v12-authenticating-grafana-apis.md#v12-service-accounts). + **OAuth and SAML session handling improvements** – Session handling for OAuth and SAML authentication providers has been improved for better reliability and security. + **Entra Workload Identity support** – Grafana now supports Microsoft Entra Workload Identity for authentication in Azure environments. + **OAuth2 for Alertmanager and Mimir** – You can now configure OAuth2 authentication in HTTP settings for vanilla Alertmanager and Mimir data sources. **Accessibility** + **GeoMap keyboard support** – GeoMap visualizations now support keyboard navigation for improved accessibility. + **Panel shortcut keyboard support** – Dashboard panels now support keyboard shortcuts for common actions. + **Heading and reduced motion improvements** – Heading structure has been improved for screen readers, and reduced motion support has been added for users who prefer minimal animation. **Breaking changes** **Important** **Legacy alerting is entirely removed** – Legacy alerting is completely removed in Amazon Managed Grafana v12, and workspaces with legacy alerting settings will fail to start. You must migrate from legacy alerting to Grafana Alerting before upgrading to v12. See [Migrating classic dashboard alerts to Grafana alerting](v10-alerting-use-grafana-alerts.md) and [Classic dashboard alerts](old-alerts-overview.md). **Important** **AngularJS support is removed** – AngularJS support is completely removed in Amazon Managed Grafana v12, so Angular-based plugins will not load and dashboards using them will display errors. You must migrate all Angular-based plugins to React alternatives before upgrading. See [Find plugins with the plugin catalog](grafana-plugins.md#plugin-catalog) for managing plugins in your workspace. **Important** **API keys are removed** – API keys are fully removed in Amazon Managed Grafana v12 in favor of service accounts, and existing API keys will no longer function. You must create service accounts to replace all API keys and update automation to use service account tokens before upgrading. See [Using service accounts](v12-authenticating-grafana-apis.md#v12-service-accounts). **Important** **Alert rule evaluation result limit** – The number of query evaluation results per alert rule is now limited to 500. If the condition query of an alert rule produces more results than this limit, the evaluation results in an error. To receive alerts when this error occurs, configure `Alert state if execution error or timeout` to `Error` under the alert rule's settings. See [State and health of alerting rules](v12-alerting-explore-state.md). **Important** **Annotations limited to 3 million** – The number of annotations is now limited to 3 million per workspace. If more than 3 million annotations are created, the oldest annotations will be deleted first. + **Input data source is removed** – The Input data source plugin has been completely removed, so you must migrate affected dashboards to the TestData data source before upgrading. See [TestData Documentation](https://grafana.com/docs/grafana/latest/datasources/testdata/) in the *Grafana Labs documentation*. + **Query filtering behavior changes** – The "Disable query" button is now "Hide response/Show response" and hidden queries' responses are no longer returned to panels, so review your query configurations and update panels if data is missing after upgrading. See [Query Filtering Changes](https://grafana.com/docs/grafana/latest/breaking-changes/breaking-changes-v11-0/#data-sources-query-filtering-changes) in the *Grafana Labs documentation*. + **Data source UIDs must follow stricter format** – Data source UIDs must now use only alphanumeric characters, hyphens, and underscores, so you should update any non-compliant UIDs and their dashboard references before upgrading. See [Stricter Data Source UID Format](https://grafana.com/docs/grafana/latest/whatsnew/whats-new-in-v12-0/#enforcing-stricter-data-source-uid-format) in the *Grafana Labs documentation*. + **Panel view URLs changed for repeated panels** – The URL format for viewing individual repeated panels has changed and old URLs will return "Panel not found" errors, so update any bookmarks or automation by opening panels in view mode to get the new URLs. See [Panel View URL Changes](https://grafana.com/docs/grafana/latest/breaking-changes/breaking-changes-v11-0/#changes-to-how-the-panel-view-url-is-generated-for-repeated-panels) in the *Grafana Labs documentation*. + **Folders with forward slashes require escaped matchers** – The introduction of subfolders can break alert rules tied to folders containing forward slashes, so update notification policies with escaped matchers (for example, `grafana_folder=MyFolder\/sub-folder`) or rename folders to remove forward slashes before upgrading. See [Creating dashboard folders](v12-dash-managing-dashboards.md#v12-dash-create-dashboard-folder) and [Configure notification policies](v12-alerting-configure-notification-policies.md). + **Alert template \$1value variable behavior changes** – The `$value` variable in alert notification templates now returns the query value when querying a single data source, so review alert templates that use `$value` and update formatting if needed. See [Templating labels and annotations](v12-alerting-overview-labels-templating.md). + **Alert rule access permissions relaxed** – Permission requirements for accessing alert rules have been relaxed. See [Using permissions](Grafana-permissions.md) and [What's new in Grafana v11.1](https://grafana.com/docs/grafana/latest/whatsnew/whats-new-in-v11-1/#removes-requirement-of-datasourcesquery-permission-for-reading-rules) in the *Grafana Labs documentation*. + **Recording rules enabled by default** – Recording rules are now enabled by default in Grafana Alerting. See [Configure recording rules](v12-alerting-configure-recordingrules.md). + **Internal Alertmanager config POST endpoint removed** – The POST endpoint for the internal Grafana Alertmanager config has been removed, so you must update API integrations to use the new provisioning endpoints (for example, `POST /api/v1/provisioning/alert-rules`) before upgrading. + **Viewer and Editor permissions expanded** – Viewers can now read and write annotations and Editors can create and delete annotations. See [Using permissions](Grafana-permissions.md). + **Creator permissions changed** – The permissions granted to the creator of a resource (such as a dashboard or folder) have changed, so review your access control settings after upgrading. See [Change to creator permissions](https://grafana.com/whats-new/2025-10-16-change-to-creator-permissions/) in the *Grafana Labs documentation*. + **API key associated permissions removed** – Permissions previously associated with API keys have been removed as part of the full migration to service accounts. See [Removal of API key associated permissions](https://grafana.com/whats-new/2025-10-03-removal-of-api-key-associated-permissions/) in the *Grafana Labs documentation*. + **SNS contact point migration** – SNS contact points are automatically migrated to a newer SNS notifier. This migration does not require any manual action. However, the contact point settings schema for SNS has changed. See [Create notification channel](v12-Grafana-API-AlertingNotificationChannels.md#v12-Grafana-API-AlertNotificationChannels-Create) for an example of the updated request format. + **Alert rule evaluation result limit** – The number of query evaluation results per alert rule is now limited to 500. If the condition query of an alert rule produces more results than this limit, the evaluation results in an error. To receive alerts when this error occurs, Configure `Alert state if execution error or timeout` to `Error` under the alert rule's settings. + **SigV4 authentication removed from Core Prometheus plugin** – SigV4 authentication support in the Core Prometheus plugin has been removed. When you upgrade to Grafana version 12, all Amazon Managed Service for Prometheus data sources that were previously using the Core Prometheus plugin are automatically migrated to the Amazon Managed Service for Prometheus plugin. Any dashboards using these data sources are automatically updated to reflect this change. See [Connect to an Amazon Managed Service for Prometheus data source](amazon-prometheus-data-source.md). Amazon Managed Grafana v12 includes features from open source Grafana v11.0 through v12.4. For AWS-specific features, see the Amazon Managed Grafana User Guide. For detailed information about what's new, see [What's new in Grafana](https://grafana.com/docs/grafana/latest/whatsnew/) for v11.x and v12.x in the *Grafana Labs documentation*. Versions 11.x and 12.x include changes that might break functionality, so test in a non-production environment before updating production workspaces. For more details on breaking changes, see the following topics in the *Grafana Labs documentation*: **Grafana 12** + [What's new in Grafana v12.4](https://grafana.com/docs/grafana/latest/whatsnew/whats-new-in-v12-4/) + [What's new in Grafana v12.3](https://grafana.com/docs/grafana/latest/whatsnew/whats-new-in-v12-3/) + [What's new in Grafana v12.2](https://grafana.com/docs/grafana/latest/whatsnew/whats-new-in-v12-2/) + [What's new in Grafana v12.1](https://grafana.com/docs/grafana/latest/whatsnew/whats-new-in-v12-1/) + [What's new in Grafana v12.0](https://grafana.com/docs/grafana/latest/whatsnew/whats-new-in-v12-0/) **Grafana 11** + [What's new in Grafana v11.6](https://grafana.com/docs/grafana/latest/whatsnew/whats-new-in-v11-6/) + [What's new in Grafana v11.5](https://grafana.com/docs/grafana/latest/whatsnew/whats-new-in-v11-5/) + [What's new in Grafana v11.4](https://grafana.com/docs/grafana/latest/whatsnew/whats-new-in-v11-4/) + [What's new in Grafana v11.3](https://grafana.com/docs/grafana/latest/whatsnew/whats-new-in-v11-3/) + [What's new in Grafana v11.2](https://grafana.com/docs/grafana/latest/whatsnew/whats-new-in-v11-2/) + [What's new in Grafana v11.1](https://grafana.com/docs/grafana/latest/whatsnew/whats-new-in-v11-1/) + [What's new in Grafana v11.0](https://grafana.com/docs/grafana/latest/whatsnew/whats-new-in-v11-0/) ## Grafana version 10 The following features were added in Grafana version 10. + **Correlations** – Correlations define how data in one data source is used to query data in another data source, and allow the Explore visualization to easily run queries related to the shown data. For more details, see [Correlations in Grafana version 10](v10-correlations.md). + **Subfolders** – When organizing your dashboards, you can now use subfolders to create a nested hierarchy. For more details, see [Creating dashboard folders](v10-dash-managing-dashboards.md#v10-dash-create-dashboard-folder). + **Alerts** – Grafana alerting now supports silencing alerts. Additionally, Grafana alerting no longer sends notifications 3 times. + **Alerting upgrade preview** – Before upgrading from classic dashboard alerts to Grafana alerts, you can see what your alerts will look like, and even make changes that are applied when migrating. For more details, see [Migrating classic dashboard alerts to Grafana alerting](v10-alerting-use-grafana-alerts.md). Grafana Labs has announced that Grafana version 11 and beyond will no longer support classic dashboard alerts. + **Support bundles** – Support bundles provide a simple way to collect information about your Grafana workspace to share with product support. You can quickly create a support bundle containing data about migrations, plugins, settings, and more. For more details, see [Gather information for support](support-bundles.md). + **New visualizations** – Three new visualizations are available. [XY Chart](v10-panels-xychart.md), [Datagrid](v10-panels-datagrid.md), and [Trend panel](v10-panels-trend.md) are all available for workspaces compatible with version 10. Version 9 workspaces can also use XY Charts. + **PagerDuty** – The Enterprise plugins now include a plugin for PagerDuty. + **Transformations redesign** – The transformations tab has an improved user experience and visual design. Transformations are categorized, and each transformation type has an illustration to help you choose the right one. + **Prometheus metric encyclopedia** – The metrics dropdown for Prometheus metrics in the Prometheus query builder has been replaced with a paginated and searchable metric *encyclopedia*. + **API key UI discontinued** – [Service accounts](v12-authenticating-grafana-apis.md#v12-service-accounts) are the recommended way to authenticate calls to the Grafana HTTP APIs. As part of Grafana Labs work toward discontinuing API keys, you can no longer create API keys through the workspace user interface. You can only create API keys through the AWS APIs. For more information about the discontinuation of API keys by Grafana Labs, see [APIKeys: Sunsetting of API keys](https://github.com/grafana/grafana/issues/53567) in the Grafana GitHub issues list. **Breaking changes** The Grafana version 10.4 release includes changes from Grafana versions 9.5 through 10.4. Grafana versions 10.0 and 10.3 had some changes that might break functionality in some cases. When updating to a new version, it is recommended to test in a non-production environment before updating your production workspaces. The following changes might affect some users updating to Grafana version 10. + **Angular discontinued** – Plugins that use Angular will no longer be supported in future releases of Grafana. In version 10, panels that use angular will show a banner stating that they use a discontinued feature, to give a notice that they won't work in future versions. + **Alias in CloudWatch removed** – Alias patterns in the CloudWatch query editor were replaced by Label (dynamic labels). Open any dashboard that uses the Alias field, and save it. Alias is migrated to Label automatically. + **Older plugins need to be upgraded** – The plugins for Athena and Amazon Redshift data source must be updated in Grafana v10 workspaces. The Athena data source plugin must be version 2.9.3 or newer; the Amazon Redshift data source plugin must be version 1.8.3 or newer. For information on installing or upgrading plugins, see [Find plugins with the plugin catalog](grafana-plugins.md#plugin-catalog). + **DoiT BigQuery plugin no longer supported** – The DoiT BigQuery data source plugin is no longer supported. Use the official Grafana Labs BigQuery data source plugin instead. + **Transformation changes** – Grafana version 10 has made a few bug fix changes to field names and keys. For full details, see [Transformation breaking changes](https://grafana.com/docs/grafana/latest/breaking-changes/breaking-changes-v10-3/#transformations) in the Grafana Labs documentation. + **Data source permissions APIs** – The endpoints for accessing data source permissions have changed. For full details, see [Data source permissions changes](https://grafana.com/docs/grafana/latest/breaking-changes/breaking-changes-v10-3/#data-source-permissions) in the Grafana Labs documentation. For more details on breaking changes, see the following topics in the *Grafana Labs documentation*: + [Breaking changes in Grafana v10.0](https://grafana.com/docs/grafana/latest/breaking-changes/breaking-changes-v10-0/) + [Breaking changes in Grafana v10.3](https://grafana.com/docs/grafana/latest/breaking-changes/breaking-changes-v10-3/) ## Grafana version 9 The following features were added in Grafana v9. + **Alerting**: Grafana-managed alert rules now supports group names. + **Explore**: Create a dashboard from within Explore view. + **Prometheus queries**: A new query builder for Prometheus queries (using PromQL) makes writing queries easier. + **Loki queries**: A new query builder for Loki queries (using LogQL) makes writing queries easier. + **API tokens / Service accounts**: Service accounts simplify machine access in Grafana, helping you to manage API tokens. + **Plugin management**: You can enable plugin management to install, remove, or update community plugins in your workspace. This gives you access to more data sources and visualizations, and gives you control over the version of each plugin that you use. + **Trace to metrics**: Configure a tracing data source to add links to metrics with queries and tags. + **Canvas panel**: A new panel visualization with static and dynamic elements to create data-driven, custom panels with images and overlain text. + **Reorganized interface**: Updated UI with easier navigation in the Grafana console. + **CloudWatch**: The Amazon CloudWatch data source can now monitor metrics across AWS accounts and across AWS Regions. + **Logs**: The interface for log details has been improved. + **General**: Bug fixes and minor improvements throughout. **Breaking changes** The Grafana version 9.4 release includes a range of new features and improvements, building upon previous versions. This version had some changes that might break functionality in some cases. When updating to a new version, we recommend you test in a non-production environment before updating your production workspaces. The following changes might affect some users updating to Grafana version 9.4. For a detailed list of these changes, see the [Grafana 9.4 changelog](https://github.com/grafana/grafana/blob/release-9.4.17/CHANGELOG.md) on *GitHub*. + **API discontinued** – The `/api/tsdb/query` API has been removed. **Action required:** Use `/api/ds/query` instead. See [Query a data source](https://grafana.com/docs/grafana/latest/http_api/data_source/#query-a-data-source) in the *Grafana public documentation* and Issue [\$149916](https://github.com/grafana/grafana/issues/49916) on *GitHub*. + **API endpoint changes** – Several alerting API endpoints now require data source UID instead of numeric ID. **Affected endpoints:** `api/v1/rule/test`, `api/prometheus/`, `api/ruler/`, `api/alertmanager/` **Action required:** Update API calls to use data source UID as path parameter. See Issues [\$148070](https://github.com/grafana/grafana/issues/48070), [\$148052](https://github.com/grafana/grafana/issues/48052), [\$148046](https://github.com/grafana/grafana/issues/48046), and [\$147978](https://github.com/grafana/grafana/issues/47978) on *GitHub*. + **Azure Monitor queries removed** – Application Insights and Insight Analytics queries are no longer supported. Deprecated in Grafana 8.0, removed in 9.0. Deprecated queries will not execute. **Action required:** See [Azure Monitor data source](https://grafana.com/docs/grafana/latest/datasources/azuremonitor/deprecated-application-insights/) in the *Grafana public documentation* for migration guidance. + **Browser access mode removed** – Browser access mode is no longer available for InfluxDB and Prometheus data sources. **Action required:** Switch to server access mode in your data source configuration. InfluxDB: Deprecated in 8.0.0, removed in 9.2.0. See Issue [\$153529](https://github.com/grafana/grafana/issues/53529) on *GitHub*. Prometheus: Deprecated in 7.4.0, removed in 9.2.0. See Issue [\$150162](https://github.com/grafana/grafana/issues/50162) on *GitHub*. + **Dashboard settings access restricted** – You can no longer open dashboard settings while editing panels. Dashboard settings are locked when panel edit mode is active. Close panel edit mode before accessing dashboard settings. See Issue [\$154746](https://github.com/grafana/grafana/issues/54746) on *GitHub*. + **Data source password encryption** – Unencrypted passwords are no longer supported. **Action required:** Use `secureJsonData.password` and `secureJsonData.basicAuthPassword`. Previously discontinued in v8.1.0. See Issue [\$149987](https://github.com/grafana/grafana/issues/49987) on *GitHub*. + **Default data source behavior** – Default data source selection no longer affects existing panels. Default data source only applies to new panels. Changing the default won't update existing dashboards. Previously saved panels retain their data source configuration. See Issue [\$145132](https://github.com/grafana/grafana/issues/45132) on *GitHub*. + **Elasticsearch interval property changed** – Query interval specification updated for Elasticsearch 7.x. Changed from `interval` to `fixed_interval` property. Provides consistency with Elasticsearch 8.x. Most queries won't show visible changes. See Issue [\$150297](https://github.com/grafana/grafana/issues/50297) on *GitHub*. + **Elasticsearch Raw document mode discontinued** – Display mode changes in Elasticsearch data source. **Action required:** Use **Raw Data** mode instead. See Issue [\$162236](https://github.com/grafana/grafana/issues/62236) on *GitHub*. + **Elasticsearch version support** – Older Elasticsearch versions are no longer supported. **Action required:** Upgrade Elasticsearch to version 7.10.0 or later. Versions below 7.10.0 are past end-of-life. See Issue [\$148715](https://github.com/grafana/grafana/issues/48715) on *GitHub*. + **Explore URL format discontinued** – Compact Explore URLs will be removed in a future release. **Action required:** Update hard coded links to use standard URL format. Compact URLs: `&left=["now-1h","now"...]`. Standard URLs: `&left={"datasource":"test"...}`. See Issue [\$150873](https://github.com/grafana/grafana/issues/50873) on *GitHub*. + **GitHub OAuth display changes** – GitHub name and login display updated. GitHub name appears as Grafana name. GitHub login appears as Grafana login. Improves user identification clarity. See Issue [\$145438](https://github.com/grafana/grafana/issues/45438) on *GitHub*. + **Heatmap panel implementation updated** – Heatmap panels use a new implementation starting in 9.1.0. Significantly improved rendering performance. Buckets are placed on reasonable borders (1m, 5m, 30s). Round cells are no longer supported. **Action required:** Test your heatmap panels after upgrade. Disable new implementation by setting `useLegacyHeatmapPanel` feature flag to true if needed. Add `?__feature.useLegacyHeatmapPanel=true` to dashboard URLs for testing. See Issue [\$150229](https://github.com/grafana/grafana/issues/50229) on *GitHub*. + **InfluxDB backend migration** – InfluxDB data parsing behavior has changed. The InfluxDB backend migration feature toggle (`influxdbBackendMigration`) is reintroduced due to backend processing issues. By default, InfluxDB data is parsed in the frontend. If you upgraded to 9.4.4 and added transformations on InfluxDB data, those panels will fail to render. **Action required:** Remove affected panels and recreate them, or edit the `time` field as `Time` in `panel.json` or `dashboard.json`. See Issue [\$164842](https://github.com/grafana/grafana/issues/64842) on *GitHub*. + **Log message format updated** – Log message structure has changed. `lvl` is now `level`. `eror` and `dbug` are now `error` and `debug`. Increased timestamp precision. Opt-out available with `oldlog` feature toggle (temporary). See Issue [\$147584](https://github.com/grafana/grafana/issues/47584) on *GitHub*. + **Loki data format optimization** – Loki logs data uses a more efficient dataframe format. Single dataframe with **labels** column instead of separate dataframes. Explore and logs panels work without changes. Other panels or transforms may need adjustment. **Action required:** Replace **labels to fields** transformation with **extract fields** transformation. See Issue [\$147153](https://github.com/grafana/grafana/issues/47153) on *GitHub*. + **NaN value handling** – Consistent `NaN` representation across Prometheus and Loki data sources. `NaN` values remain as `NaN` instead of converting to `null`. Change should be mostly invisible to users. Affects both dashboard and alerting paths. See Issues [\$149475](https://github.com/grafana/grafana/issues/49475) and [\$145389](https://github.com/grafana/grafana/issues/45389) on *GitHub*. + **Password reset links invalidated** – Existing password reset links won't work after upgrade. Password reset links sent before upgrade are invalid. Users must request new password reset links. Links expire after 2 hours. See Issue [\$142334](https://github.com/grafana/grafana/issues/42334) on *GitHub*. + **Reserved label prefix** – Labels starting with `grafana_` are reserved. Manually configured labels beginning with `grafana_` may be overwritten. Current reserved labels: `grafana_folder` (Title of the folder containing the alert). See Issue [\$150262 ](https://github.com/grafana/grafana/issues/50262) on *GitHub*. + **Transformation improvements** – **Rename by regex** transformation now supports global patterns. Global patterns use the format `//g`. Some transformations may behave differently. Wrap match strings in forward slashes for previous behavior: `(.*)` becomes `/(.*)/`. See Issue [\$148179 ](https://github.com/grafana/grafana/issues/48179) on *GitHub*. # Create an Amazon Managed Grafana workspace A *workspace* is a logical Grafana server. You can have as many as five workspaces in each Region in your account. **Necessary permissions** To create a workspace, you must be signed on to an AWS Identity and Access Management (IAM) principal that has the **AWSGrafanaAccountAdministrator** policy attached. To create your first workspace that uses IAM Identity Center for authorization, your IAM principal must also have these additional policies (or equivalent permissions) attached: + **AWSSSOMemberAccountAdministrator** + **AWSSSODirectoryAdministrator** For more information, see [Create and manage Amazon Managed Grafana workspaces and users in a single standalone account using IAM Identity Center](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-create-workspace-standalone). ## Creating a workspace The following steps take you through the process of creating a new Amazon Managed Grafana workspace. **To create a workspace in Amazon Managed Grafana** 1. Open the Amazon Managed Grafana console at [https://console.aws.amazon.com/grafana/](https://console.aws.amazon.com/grafana/). 1. Choose **Create workspace**. 1. In the **Workspace details** window, for **Workspace name**, enter a name for the workspace. Optionally, enter a description for the workspace. Optionally, add the tags you want to associate with this workspace. Tags help identify and organize workspaces and also can be used for controlling access to AWS resources. For example, you can assign a tag to the workspace and only a limited groups or roles can have the permission to access the workspace using the tag. For more information on tag-based access control, see [Controlling access to AWS resources using tags](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html) in IAM User Guide. ![\[Workspace details form with name field and optional tags section highlighted.\]](http://docs.aws.amazon.com/grafana/latest/userguide/images/tagworkspace.png) 1. Choose a **Grafana version** for the workspace. You can choose version 9, 10, or 12. To understand the differences between the versions, see [Differences between Grafana versions](version-differences.md). 1. Choose **Next**. 1. For **Authentication access**, select **AWS IAM Identity Center **, **Security Assertion Markup Language (SAML)**, or both. For more information, see [Authenticate users in Amazon Managed Grafana workspaces](authentication-in-AMG.md). + **IAM Identity Center** — If you select IAM Identity Center and you have not already enabled AWS IAM Identity Center in your account, you are prompted to enable it by creating your first IAM Identity Center user. IAM Identity Center handles user management for access to Amazon Managed Grafana workspaces. To enable IAM Identity Center, follow these steps: 1. Choose **Create user**. 1. Enter an email address, first name, and last name for the user, and choose **Create user**. For this tutorial, use the name and email address of the account that you want to use to try out Amazon Managed Grafana. You will receive an email message prompting you to create a password for this account for IAM Identity Center. **Important** The user that you create does not automatically have access to your Amazon Managed Grafana workspace. You provide the user with access to the workspace in the workspace details page in a later step. + **SAML** — If you select **SAML**, you complete the SAML setup after the workspace is created. 1. Choose **Service managed** or **Customer managed**. If you choose **Service managed**, Amazon Managed Grafana automatically creates the IAM roles and provisions the permissions that you need for the AWS data sources in this account that you choose to use for this workspace. If you want to manage these roles and permissions yourself, choose **Customer managed**. If you are creating a workspace in a member account of an organization, to be able to choose **Service managed** the member account must be a delegated administrator account in an organization. For more information about delegated administrator accounts, see [Register a delegated administrator](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-orgs-delegated-admin.html). 1. (Optional) You can choose to connect to an Amazon virtual private cloud (VPC) on this page, or you can connect to a VPC later. To learn more, see [Connect to data sources or notification channels in Amazon VPC from Amazon Managed Grafana](AMG-configure-vpc.md). 1. (Optional) You can choose other workspace configuration options on this page, including the following: + Enable [Grafana alerting](alerts-overview.md). Grafana alerting allows you to view Grafana alerts and alerts defined in Prometheus within a single alerts interface within your Grafana workspace. In workspaces running version 8 or 9, this will send multiple notifications for your Grafana alerts. If you use alerts defined in Grafana, we recommend creating your workspace as version 10.4 or later. + Allow Grafana admins to [manage plugins](grafana-plugins.md) for this workspace. If you don't enable plugin management, your admins will not be able to install, uninstall, or remove plugins for your workspace. You might be limited to the types of data sources and visualization panels you can use with Amazon Managed Grafana. You can also make these configuration changes after creating your workspace. To learn more about configuring your workspace, see [Configure a Amazon Managed Grafana workspace](AMG-configure-workspace.md). 1. (Optional) You can choose to add **Network access control** for your workspace. To add network access control, choose **Restricted access**. You can also enable network access control after you have created your workspace. For more information about network access control, see [Configure network access to your Amazon Managed Grafana workspace](AMG-configure-nac.md). 1. (Optional) By default, Amazon Managed Grafana automatically provides you with encryption at rest and does this using AWS-owned encryption keys. But you have the option to use a customer managed key that you create, own, and manage as an alternative. For more information, see [Encryption at rest](AMG-encryption-at-rest.md). 1. Choose **Next**. 1. If you chose **Service managed**, choose **Current account** to have Amazon Managed Grafana automatically create policies and permissions that allow it to read AWS data only in the current account. If you are creating a workspace in the management account or a delegated administrator account in an organization, you can choose **Organization** to have Amazon Managed Grafana automatically create policies and permissions that allow it to read AWS data in other accounts in the organizational units that you specify. For more information about delegated administrator accounts, see [Register a delegated administrator](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-orgs-delegated-admin.html). **Note** Creating resources such as Amazon Managed Grafana workspaces in the management account of an organization is against AWS security best practices. 1. If you chose **Organization**, and you are prompted to enable AWS CloudFormation StackSets, choose **Enable trusted access**. Then, add the AWS Organizations organizational units (OUs) that you want Amazon Managed Grafana to read data from. Amazon Managed Grafana can then read data from all accounts in each OU that you choose. 1. If you chose **Organization**, choose **Data sources and notification channels - optional**. 1. Select the AWS data sources that you want to query in this workspace. Selecting data sources enables Amazon Managed Grafana to create IAM roles and permissions that allow Amazon Managed Grafana to read data from these sources. You must still add the data sources in the Grafana workspace console. 1. (Optional) If you want Grafana alerts from this workspace to be sent to an Amazon Simple Notification Service (Amazon SNS) notification channel, select **Amazon SNS**. This enables Amazon Managed Grafana to create an IAM policy to publish to the Amazon SNS topics in your account with `TopicName` values that start with `grafana`. This does not completely set up Amazon SNS as a notification channel for the workspace. You can do that within the Grafana console in the workspace. 1. Choose **Next**. 1. Confirm the workspace details, and choose **Create workspace**. The workspace details page appears. Initially, the **Status** is **CREATING**. **Important** Wait until the status is **ACTIVE** before doing either of the following: Completing the SAML setup, if you are using SAML. Assigning your IAM Identity Center users access to the workspace, if you are using IAM Identity Center. You might need to refresh your browser to see the current status. 1. If you are using IAM Identity Center, do the following: 1. In the **Authentication** tab, choose **Assign new user or group**. 1. Select the check box next to the user that you want to grant workspace access to, and choose **Assign user**. 1. Select the check box next to the user, and choose **Make admin**. **Important** Assign at least one user as `Admin` for each workspace, in order to sign in to the Grafana workspace console to manage the workspace. 1. If you are using SAML, do the following: 1. In the **Authentication** tab, under **Security Assertion Markup Language (SAML)**, choose **Complete setup**. 1. For **Import method**, do one of the following: + Choose **URL** and enter the URL of the IdP metadata. + Choose **Upload or copy/paste**. If you are uploading the metadata, choose **Choose file** and select the metadata file. Or, if you are using copy and paste, copy the metadata into **Import the metadata**. 1. For **Assertion attribute role**, enter the name of the SAML assertion attribute from which to extract role information. 1. For **Admin role values**, either enter the user roles from your IdP who should all be granted the `Admin` role in the Amazon Managed Grafana workspace, or select **I want to opt-out of assigning admins to my workspace.** **Note** If you choose **I want to opt-out of assigning admins to my workspace.**, you won't be able to use the console to administer the workspace, including tasks such as managing data sources, users, and dashboard permissions. You can make administrative changes to the workspace only by using Amazon Managed Grafana APIs. 1. (Optional) To enter additional SAML settings, choose **Additional settings** and do one or more the following. All of these fields are optional. + For **Assertion attribute name**, specify the name of the attribute within the SAML assertion to use for the user full "friendly" names for SAML users. + For **Assertion attribute login**, specify the name of the attribute within the SAML assertion to use for the user sign-in names for SAML users. + For **Assertion attribute email**, specify the name of the attribute within the SAML assertion to use for the user email names for SAML users. + For **Login validity duration (in minutes)**, specify how long a SAML user's sign-in is valid before the user must sign in again. The default is 1 day, and the maximum is 30 days. + For **Assertion attribute organization**, specify the name of the attribute within the SAML assertion to use for the "friendly" name for user organizations. + For **Assertion attribute groups**, specify the name of the attribute within the SAML assertion to use for the "friendly" name for user groups. + For **Allowed organizations**, you can limit user access to only the users who are members of certain organizations in the IdP. Enter one or more organizations to allow, separating them with commas. + For **Editor role values**, enter the user roles from your IdP who should all be granted the `Editor` role in the Amazon Managed Grafana workspace. Enter one or more roles, separated by commas. 1. Choose **Save SAML configuration**. 1. In the workspace details page, choose the URL displayed under **Grafana workspace URL**. 1. Choosing the workspace URL takes you to the landing page for the Grafana workspace console. Do one of the following: + Choose **Sign in with SAML**, and enter the name and password. + Choose **Sign in with AWS IAM Identity Center**, and enter the email address and password of the user that you created earlier in this procedure. These credentials only work if you have responded to the email from Amazon Managed Grafana that prompted you to create a password for IAM Identity Center. You are now in your Grafana workspace, or logical Grafana server. You can start adding data sources to query, visualize, and analyze data. For more information, see [Use your Grafana workspace](AMG-working-with-Grafana-workspace.md). For more information on **Tip** You can automate the creation of Amazon Managed Grafana workspaces by using CloudFormation. For more detailed information see [Creating Amazon Managed Grafana resources with AWS CloudFormation](creating-resources-with-cloudformation.md). # Authenticate users in Amazon Managed Grafana workspaces Individual users sign into your workspaces, to edit and view your dashboards. You can assign users to your workspaces and [give them user, editor, or administrator permissions](AMG-manage-users-and-groups-AMG.md). To get started, you create (or use an existing) identity provider to authenticate users. Users are authenticated to use the Grafana console in an Amazon Managed Grafana workspace by single sign-on using your organization’s identity provider, instead of by using IAM. Each workspace can use one or both of the following authentication methods: + User credentials stored in identity providers (IdPs) that support Security Assertion Markup Language 2.0 (SAML 2.0) + AWS IAM Identity Center. AWS Single-sign-on (**AWS SSO**) was rebranded to **IAM Identity Center**. For each of your workspaces, you can use SAML, IAM Identity Center, or both. If you begin by using one method, you can switch to using the other. You must give your users (or groups that they belong to) permissions to the workspace before they can access functionality within the workspace. For more information about giving permissions to your users, see [Manage user and group access to Amazon Managed Grafana workspaces](AMG-manage-users-and-groups-AMG.md). **Topics** + [Use SAML with your Amazon Managed Grafana workspace](authentication-in-AMG-SAML.md) + [Use AWS IAM Identity Center with your Amazon Managed Grafana workspace](authentication-in-AMG-SSO.md) # Use SAML with your Amazon Managed Grafana workspace **Note** Amazon Managed Grafana does not currently support IdP initiated login for workspaces. You should set up your SAML applications with a blank Relay State. You can use SAML authentication to use your existing identity provider and offer single sign-on for logging into the Grafana console of your Amazon Managed Grafana workspaces. Rather than authenticating through IAM, SAML authentication for Amazon Managed Grafana lets you use third-party identity providers to log in, manage access control, search your data, and build visualizations. Amazon Managed Grafana supports identity providers that use the SAML 2.0 standard and have built and tested integration applications with Azure AD, CyberArk, Okta, OneLogin, and Ping Identity. For details about how to set up SAML authentication during workspace creation, see [Creating a workspace](AMG-create-workspace.md#creating-workspace). In the SAML authentication flow, an Amazon Managed Grafana workspace acts as the service provider (SP), and interacts with the IdP to obtain user information. For more information about SAML, see [Security Assertion Markup Language](https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language). You can map groups in your IdP to teams in the Amazon Managed Grafana workspace, and set fine-grained access permissions on those teams. You can also map organization roles that are defined in the IdP to roles in the Amazon Managed Grafana workspace. For example, if you have a **Developer** role defined in the IdP, you can map that role to the **Grafana Admin** role in the Amazon Managed Grafana workspace. **Note** When you create an Amazon Managed Grafana workspace that uses an IdP and SAML for authorization, you must be signed on to an IAM principal that has the **AWSGrafanaAccountAdministrator** policy attached. To sign in to the Amazon Managed Grafana workspace, a user visits the workspace's Grafana console home page and chooses **Log in using SAML**. The workspace reads the SAML configuration and redirects the user to the IdP for authentication. The user enters their sign-in credentials in the IdP portal, and if they are a valid user, the IdP issues a SAML assertion and redirects the user back to the Amazon Managed Grafana workspace. Amazon Managed Grafana verifies that the SAML assertion is valid, and the user is signed in and can use the workspace. Amazon Managed Grafana supports the following SAML 2.0 bindings: + From the service provider (SP) to the identity provider (IdP): + HTTP-POST binding + HTTP-Redirect binding + From the identity provider (IdP) to the service provider (SP): + HTTP-POST binding Amazon Managed Grafana supports signed and encrypted assertions, but does not support signed or encrypted requests. Amazon Managed Grafana supports SP-initiated requests, and does not support IdP-initiated requests. ## Assertion mapping During the SAML authentication flow, Amazon Managed Grafana receives the assertion consumer service (ACS) callback. The callback contains all relevant information for the user being authenticated, embedded in the SAML response. Amazon Managed Grafana parses the response to create (or update) the user within its internal database. When Amazon Managed Grafana maps the user information, it looks at the individual attributes within the assertion. You can think of these attributes as key-value pairs, although they contain more information than that. Amazon Managed Grafana provides configuration options so that you can modify which keys to look at for these values. You can use the Amazon Managed Grafana console to map the following SAML assertion attributes to values in Amazon Managed Grafana: + For **Assertion attribute role**, specify the name of the attribute within the SAML assertion to use as the user roles. + For **Assertion attribute name**, specify the name of the attribute within the SAML assertion to use for the user full "friendly" names for SAML users. + For **Assertion attribute login**, specify the name of the attribute within the SAML assertion to use for the user sign-in names for SAML users. + For **Assertion attribute email**, specify the name of the attribute within the SAML assertion to use for the user email names for SAML users. + For **Assertion attribute organization**, specify the name of the attribute within the SAML assertion to use for the "friendly" name for user organizations. + For **Assertion attribute groups**, specify the name of the attribute within the SAML assertion to use for the "friendly" name for user groups. + For **Allowed organizations**, you can limit user access to only the users who are members of certain organizations in the IdP. + For **Editor role values**, specify the user roles from your IdP who should all be granted the `Editor` role in the Amazon Managed Grafana workspace. ## Connecting to your identity provider The following external identity providers have been tested with Amazon Managed Grafana and provide applications directly in their app directories or galleries to help you configure Amazon Managed Grafana with SAML. **Topics** + [Assertion mapping](#AMG-SAML-Assertion-Mapping) + [Connecting to your identity provider](#authentication-in-AMG-SAML-providers) + [Configure Amazon Managed Grafana to use Azure AD](AMG-SAML-providers-Azure.md) + [Configure Amazon Managed Grafana to use CyberArk](AMG-SAML-providers-CyberArk.md) + [Configure Amazon Managed Grafana to use Okta](AMG-SAML-providers-okta.md) + [Configure Amazon Managed Grafana to use OneLogin](AMG-SAML-providers-onelogin.md) + [Configure Amazon Managed Grafana to use Ping Identity](AMG-SAML-providers-pingone.md) # Configure Amazon Managed Grafana to use Azure AD Use the following steps to configure Amazon Managed Grafana to use Azure Active Directory as an identity provider. These steps assume that you have already created your Amazon Managed Grafana workspace and you have made a note of the workspace *ID*, *URLs*, and *AWS Region*. ## Step 1: Steps to complete in Azure Active Directory Complete the following steps in Azure Active Directory. **To set up Azure Active Directory as an identity provider for Amazon Managed Grafana** 1. Sign in to the Azure console as an admin. 1. Choose **Azure Active Directory**. 1. Choose **Enterprise Applications**. 1. Search for **Amazon Managed Grafana SAML2.0**, and select it. 1. Select the application and choose **Setup**. 1. In the Azure Active Directory application configuration, choose **Users and groups**. 1. Assign the application to the users and groups that you want. 1. Choose **Single sign-on**. 1. Choose **Next** to get to the SAML configuration page. 1. Specify your SAML settings: + For **Identifier (Entity ID)**, paste in your **Service provider identifier** URL from the Amazon Managed Grafana workspace. + For **Reply URL (Assertion Consumer Service URL)**, paste in your **Service provider reply** from the Amazon Managed Grafana workspace. + Make sure that **Sign Assertion** is selected and that **Encrypt Assertion** is not selected. 1. In the **User Attributes & Claims** section, make sure that these attributes are mapped. They are case sensitive. + **mail** is set with **user.userprincipalname**. + **displayName** is set with **user.displayname**. + **Unique User Identifier** is set with **user.userprincipalname**. + Add any other attributes that you would to pass. For more information about the attributes that you can pass to Amazon Managed Grafana in the assertion mapping, see [Assertion mapping](authentication-in-AMG-SAML.md#AMG-SAML-Assertion-Mapping). 1. Copy the **SAML Metadata URL** for use in the Amazon Managed Grafana workspace configuration. ## Step 2: Steps to complete in Amazon Managed Grafana Complete the following steps in the Amazon Managed Grafana console. **To finish setting up Azure Active Directory as an identity provider for Amazon Managed Grafana** 1. Open the Amazon Managed Grafana console at [https://console.aws.amazon.com/grafana/](https://console.aws.amazon.com/grafana/home/). 1. In the navigation pane, choose the menu icon. 1. Choose **All workspaces**. 1. Choose the name of the workspace. 1. In the **Authentication** tab, choose **Setup SAML configuration**. 1. Under **Import the metadata**, choose **Upload or copy/paste** and paste the Azure Active Directory URL that you copied from **SAML Metadata URL** in the previous section. 1. Under **Assertion mapping**, do the following: + Make sure that **I want to opt-out of assigning admins to my workspace** is not selected. **Note** If you choose **I want to opt-out of assigning admins to my workspace**, you won't be able to use the Amazon Managed Grafana workspace console to administer the workspace, including tasks such as managing data sources, users, and dashboard permissions. You can make administrative changes to the workspace only by using Grafana APIs. + Set **Assertion attribute role** to the attribute name that you chose. + Set **Admin role values** to value corresponding to your admin users' roles. + (Optional) If you changed the default attributes in your Azure Active Directory application, expand **Additional settings - optional** and then set the new attribute names. By default, the Azure **displayName** attribute is passed as the **Name** attribute and the Ping Identity **mail** attribute is passed to both the **email** and **login** attributes. 1. Choose **Save SAML Configuration**. # Configure Amazon Managed Grafana to use CyberArk Use the following steps to configure Amazon Managed Grafana to use CyberArk as an identity provider. These steps assume that you have already created your Amazon Managed Grafana workspace and you have made a note of the workspace's ID, URLs, and Region. ## Step 1: Steps to complete in CyberArk Complete the following steps in CyberArk. **To set up CyberArk as an identity provider for Amazon Managed Grafana** 1. Sign in to the CyberArk Identity Admin Portal. 1. Choose **Apps**, **Web Apps**. 1. Choose **Add Web App**. 1. Search for **Amazon Managed Grafana for SAML2.0**, and choose **Add**. 1. In the CyberArk application configuration, go to the **Trust** section. 1. Under **Identity Provider Configuration**, choose **Metadata**. 1. Choose **Copy URL** and save the URL to use later in these steps. 1. Under **Service Provider Configuration**, choose **Manual Configuration**. 1. Specify your SAML settings: + For **SP Entity ID**, paste in your **Service provider identifier** URL from the Amazon Managed Grafana workspace. + For **Assertion Consumer Service (ACS) URL**, paste in your **Service provider reply** from the Amazon Managed Grafana workspace. + Set **Sign Response Assertion** to **Assertion**. + Make sure that **NameID Format** is **emailAddress**. 1. Choose **Save**. 1. In the **SAML Response** section, make sure that the Amazon Managed Grafana attribute is in **Application Name** and that the CyberArk attribute is in **Attribute Value**. Then make sure that the following attributes are mapped. They are case sensitive. + **displayName** is set with **LoginUser.DisplayName**. + **mail** is set with **LoginUser.Email**. + Add any other attributes that you would to pass. For more information about the attributes that you can pass to Amazon Managed Grafana in the assertion mapping, see [Assertion mapping](authentication-in-AMG-SAML.md#AMG-SAML-Assertion-Mapping). 1. Choose **Save**. 1. In the **Permissions** section, choose which users and groups to assign this application to, and then choose **Save**. ## Step 2: Steps to complete in Amazon Managed Grafana Complete the following steps in the Amazon Managed Grafana console. **To finishg setting up CyberArk as an identity provider for Amazon Managed Grafana** 1. Open the Amazon Managed Grafana console at [https://console.aws.amazon.com/grafana/](https://console.aws.amazon.com/grafana/home/). 1. In the navigation pane, choose the menu icon. 1. Choose **All workspaces**. 1. Choose the name of the workspace. 1. In the **Authentication** tab, choose **Setup SAML configuration**. 1. Under **Import the metadata**, choose **Upload or copy/paste** and paste the CyberArk URL that you copied in the previous procedure. 1. Under **Assertion mapping**, do the following: + Make sure that **I want to opt-out of assigning admins to my workspace** is not selected. **Note** If you choose **I want to opt-out of assigning admins to my workspace**, you won't be able to use the Amazon Managed Grafana workspace console to administer the workspace, including tasks such as managing data sources, users, and dashboard permissions. You can make administrative changes to the workspace only by using Grafana APIs. + Set **Assertion attribute role** to the attribute name that you chose. + Set **Admin role values** to value corresponding to your admin users' roles. + (Optional) If you changed the default attributes in your CyberArk application, expand **Additional settings - optional** and then set the new attribute names. By default, the CyberA **displayName** attribute is passed to the **name** attribute and the CyberArk **mail** attribute is passed to both the **email** and **login** attributes. 1. Choose **Save SAML Configuration**. # Configure Amazon Managed Grafana to use Okta Use the following steps to configure Amazon Managed Grafana to use Okta as an identity provider. These steps assume that you have already created your Amazon Managed Grafana workspace and you have made a note of the workspace's ID, URLs, and Region. ## Step 1: Steps to complete in Okta Complete the following steps in Okta. **To set up Okta as an identity provider for Amazon Managed Grafana** 1. Sign in to the Okta console as an admin. 1. In the left panel, choose **Applications**, **Applications**. 1. Choose **Browse App Catalog** and search for **Amazon Managed Grafana**. 1. Choose **Amazon Managed Grafana** and choose **Add**, **Done**. 1. Choose the application to start setting it up. 1. In the **Sign On** tab, choose **Edit**. 1. Under **Advanced Sign-on Settings**, enter your Amazon Managed Grafana workspace id and your Region in the **Name Space** and **Region** fields respectively. Your Amazon Managed Grafana workspace id and Region can be found in your Amazon Managed Grafana workspace url which is of the format ***workspace-id*.grafana-workspace.*Region*.amazonaws.com**. 1. Choose **Save**. 1. Under **SAML 2.0**, copy the URL for **Identity Provider metadata**. You use this later in this procedure in the Amazon Managed Grafana console. 1. In the **Assignments** tab, choose the **People** and **Groups** that you want to be able to use Amazon Managed Grafana. ## Step 2: Steps to complete in Amazon Managed Grafana Complete the following steps in the Amazon Managed Grafana console. **To finish setting up Okta as an identity provider for Amazon Managed Grafana** 1. Open the Amazon Managed Grafana console at [https://console.aws.amazon.com/grafana/](https://console.aws.amazon.com/grafana/home/). 1. In the navigation pane, choose the menu icon. 1. Choose **All workspaces**. 1. Choose the name of the workspace. 1. In the **Authentication** tab, choose **Complete Setup**. 1. Under **Import the meta data**, choose **Upload or copy/paste** and paste the Okta URL that you copied in the previous procedure. 1. Under **Assertion mapping**, do the following: + Make sure that **I want to opt-out of assigning admins to my workspace** is not selected. **Note** If you choose **I want to opt-out of assigning admins to my workspace**, you won't be able to use the Amazon Managed Grafana workspace console to administer the workspace, including tasks such as managing data sources, users, and dashboard permissions. You can make administrative changes to the workspace only by using Grafana APIs. + Set **Assertion attribute role** to the attribute name that you chose. + Set **Admin role values** to value corresponding to your admin users' roles. + (Optional) If you changed the default attributes in your Okta application, expand **Additional settings - optional** and then set the new attribute names. By default, the Okta **displayName** attribute is passed to the **name** attribute and the Okta **mail** attribute is passed to both the **email** and **login** attributes. 1. Choose **Save SAML Configuration**. # Configure Amazon Managed Grafana to use OneLogin Use the following steps to configure Amazon Managed Grafana to use OneLogin as an identity provider. These steps assume that you have already created your Amazon Managed Grafana workspace and you have made a note of the workspace's ID, URLs, and Region. ## Step 1: Steps to complete in OneLogin Complete the following steps in OneLogin. **To set up OneLogin as an identity provider for Amazon Managed Grafana** 1. Sign in to the OneLogin portal as an administrator. 1. Choose **Applications**, **Applications**, **Add app**. 1. Search for **Amazon Managed Service for Grafana**. 1. Assign a **Display name** of your choice and choose **Save**. 1. Navigate to **Configuration** and enter the Amazon Managed Grafana workspace ID in **Namespace**, and enter the Region of your Amazon Managed Grafana workspace. 1. In the **Configuration** tab, enter your Amazon Managed Grafana workspace URL. 1. You can leave the **adminRole** parameter as the default **No Default** and populate it using the **Rules** tab, if an admin requires a corresponding value in Amazon Managed Grafana. In this example, the **Assertion attribute role** would be set to **adminRole** in Amazon Managed Grafana, with a value of true. You can point this value to any attribute in your tenant. Click the **\$1** to add and configure parameters to meet your organization's requirements. 1. Choose the **Rules** tab, choose **Add Rule**, and give your Rule a name. In the **Conditions** field (the if statement), we add **Email contains [email address]**. In the **Actions** field (the then statement), we select **Set AdminRole in Amazon Managed Service** and we select **Macro** in the **Set adminRole** to dropdown, with a value of **true**. Your organization can choose different rules to resolve different use cases. 1. Choose **Save**. Go to **More Actions** and choose **Reapply entitlement mappings**. You must reappy mappings any time that you create or update rules. 1. Make a note of the **Issuer URL**, which you use later in the configuration in the Amazon Managed Grafana console. Then choose **Save**. 1. Choose the **Access** tab to assign the OneLogin roles that are to access Amazon Managed Grafana and select an app security policy. ## Step 2: Steps to complete in Amazon Managed Grafana Complete the following steps in the Amazon Managed Grafana console. **To finish setting up OneLogin as an identity provider for Amazon Managed Grafana** 1. Open the Amazon Managed Grafana console at [https://console.aws.amazon.com/grafana/](https://console.aws.amazon.com/grafana/home/). 1. In the navigation pane, choose the menu icon. 1. Choose **All workspaces**. 1. Choose the name of the workspace. 1. In the **Authentication** tab, choose **Setup SAML configuration**. 1. Under **Import the metadata**, choose **Upload or copy/paste** and paste the OneLogin Issuer URL that you copied from the OneLogin console in the previous procedure. 1. Under **Assertion mapping**, do the following: + Make sure that **I want to opt-out of assigning admins to my workspace** is not selected. **Note** If you choose **I want to opt-out of assigning admins to my workspace**, you won't be able to use the Amazon Managed Grafana workspace console to administer the workspace, including tasks such as managing data sources, users, and dashboard permissions. You can make administrative changes to the workspace only by using Grafana APIs. + Set **Assertion attribute role** to the attribute name that you chose. The default value for OneLogin is **adminRole**. + Set **Admin role values** to value corresponding to your admin users' roles. + (Optional) If you changed the default attributes in your OneLogin application, expand **Additional settings - optional** and then set the new attribute names. By default, the OneLogin **displayName** attribute is passed to the **name** attribute and the OneLogin **mail** attribute is passed to both the **email** and **login** attributes. 1. Choose **Save SAML Configuration**. # Configure Amazon Managed Grafana to use Ping Identity Use the following steps to configure Amazon Managed Grafana to use Ping Identity as an identity provider. These steps assume that you have already created your Amazon Managed Grafana workspace and you have made a note of the workspace's ID, URLs, and Region. ## Step 1: Steps to complete in Ping Identity Complete the following steps in Ping Identity. **To set up Ping Identity as an identity provider for Amazon Managed Grafana** 1. Sign in to the Ping Identity console as an admin. 1. Choose **Applications**. 1. Choose **Add Application**, **Search Application Catalog**. 1. Search for the **Amazon Managed Grafana for SAML** application, then choose it and choose **Setup**. 1. In the Ping Identity application, choose **Next** to get to the SAML configuration page. Then make the following SAML settings: + For **Assertion Consumer Service**, paste in your **Service provider reply URL** from the Amazon Managed Grafana workspace. + For **Entity ID**, paste in your **Service provider identifier** from the Amazon Managed Grafana workspace. + Make sure that **Sign Assertion** is selected and that **Encrypt Assertion** is not selected. 1. Choose **Continue to Next Step**. 1. In **SSO Attribute Mapping**, make sure that the Amazon Managed Grafana attribute is in **Application Attribute** and that the Ping Identity attribute is in the **Identity Bridge Attribute**. Then make the following settings: + **mail** must be **Email (Work)**. + **displayName** must be **Display Name**. + **SAML\$1SUBJECT** must be **Email (Work)**. And then for this attribute, choose **Advanced**, set the **Name ID Format to send to SP** to **urn:oasis:names:tc:SAML:2.0:nameid-format:transient** and choose **Save**. + Add in any other attribute that you would like to pass. + Add any other attributes that you would like to pass. For more information about the attributes that you can pass to Amazon Managed Grafana in the assertion mapping, see [Assertion mapping](authentication-in-AMG-SAML.md#AMG-SAML-Assertion-Mapping). 1. Choose **Continue to Next Step**. 1. In **Group Access**, choose which groups to assign this application to. 1. Choose **Continue to Next Step**. 1. Copy the **SAML Metadata URL** which starts with `https://admin- api.pingone.com/latest/metadata/`. You use this later in the configuration. 1. Choose **Finish**. ## Step 2: Steps to complete in Amazon Managed Grafana Complete the following steps in the Amazon Managed Grafana console. **To finish setting up Ping Identity as an identity provider for Amazon Managed Grafana** 1. Open the Amazon Managed Grafana console at [https://console.aws.amazon.com/grafana/](https://console.aws.amazon.com/grafana/home/). 1. In the navigation pane, choose the menu icon. 1. Choose **All workspaces**. 1. Choose the name of the workspace. 1. In the **Authentication** tab, choose **Setup SAML configuration**. 1. Under **Import the metadata**, choose **Upload or copy/paste** and paste the Ping URL that you copied in the previous procedure. 1. Under **Assertion mapping**, do the following: + Make sure that **I want to opt-out of assigning admins to my workspace** is not selected. **Note** If you choose **I want to opt-out of assigning admins to my workspace**, you won't be able to use the Amazon Managed Grafana workspace console to administer the workspace, including tasks such as managing data sources, users, and dashboard permissions. You can make administrative changes to the workspace only by using Grafana APIs. + Set **Assertion attribute role** to the attribute name that you chose. + Set **Admin role values** to value corresponding to your admin users' roles. + (Optional) If you changed the default attributes in your Ping Identity application, expand **Additional settings - optional** and then set the new attribute names. By default, the Ping Identity **displayName** attribute is passed to the **name** attribute and the Ping Identity **mail** attribute is passed to both the **email** and **login** attributes. 1. Choose **Save SAML Configuration**. # Use AWS IAM Identity Center with your Amazon Managed Grafana workspace Amazon Managed Grafana integrates with AWS IAM Identity Center to provide identity federation for your workforce. Using Amazon Managed Grafana and IAM Identity Center, users are redirected to their existing company directory to sign in with their existing credentials. Then, they are seamlessly signed in to their Amazon Managed Grafana workspace. This ensures that security settings such as password policies and two-factor authentication are enforced. Using IAM Identity Center does not impact your existing IAM configuration. If you do not have an existing user directory or prefer not to federate, IAM Identity Center offers an integrated user directory that you can use to create users and groups for Amazon Managed Grafana. Amazon Managed Grafana does not support the use of IAM users and roles to assign permissions within an Amazon Managed Grafana workspace. For more information about IAM Identity Center, see [What is AWS IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html). For more information about getting started with IAM Identity Center, see [Getting started](https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html). To use IAM Identity Center, you must also have AWS Organizations activated for the account. If needed, Amazon Managed Grafana can activate Organizations for you when you create your first workspace that is configured to use IAM Identity Center. ## Required permissions for scenarios using IAM Identity Center This section explains the policies that are required for using Amazon Managed Grafana with IAM Identity Center. The policies needed to administer Amazon Managed Grafana differ based on whether your AWS account is part of an organization or not. ### Create a Grafana administrator in AWS Organizations accounts To grant permissions to create and manage Amazon Managed Grafana workspaces in an organization, and to allow dependencies such as AWS IAM Identity Center, assign the following policies to a role. + Assign the **AWSGrafanaAccountAdministrator** IAM policy to allow administering Amazon Managed Grafana workspaces. + **AWSSSODirectoryAdministrator** allows the role to use IAM Identity Center when setting up Amazon Managed Grafana workspaces. + To allow creating and managing Amazon Managed Grafana workspaces across the entire organization, give the role the **AWSSSOMasterAccountAdministrator** IAM policy. Alternately, give the role the **AWSSSOMemberAccountAdministrator** IAM policy to allow creating and managing workspaces within a single member account of the organization. + You can also optionally give the role the **AWSMarketplaceManageSubscriptions** IAM policy (or equivalent permissions) if you want to allow the role to upgrade an Amazon Managed Grafana workspace to Grafana enterprise. If you want to use service-managed permissions when you create an Amazon Managed Grafana workspace, the role that creates the workspace must also have the `iam:CreateRole`, `iam:CreatePolicy`, and `iam:AttachRolePolicy` permissions. These are required to use CloudFormation StackSets to deploy policies that allow you to read data sources in the organization's accounts. **Important** Granting a user the `iam:CreateRole`, `iam:CreatePolicy`, and `iam:AttachRolePolicy` permissions gives that user full administrative access to your AWS account. For example, a user with these permissions can create a policy that has full permissions for all resources, and attach that policy to any role. Be very careful about who you grant these permissions to. To see the permissions granted to **AWSGrafanaAccountAdministrator**, see [AWS managed policy: AWSGrafanaAccountAdministrator](security-iam-awsmanpol.md#security-iam-awsmanpol-AWSGrafanaAccountAdministrator) ### Create and manage Amazon Managed Grafana workspaces and users in a single standalone account A standalone AWS account is an account that is not a member of an organization. For more information about AWS Organizations, see [What is AWS Organizations?](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_introduction.html) To grant permission to create and manage Amazon Managed Grafana workspaces and users in a standalone account, assign the following IAM policies to a role: + **AWSGrafanaAccountAdministrator** + **AWSSSOMasterAccountAdministrator** + **AWSOrganizationsFullAccess** + **AWSSSODirectoryAdministrator** **Important** Granting a role the **AWSOrganizationsFullAccess** policy gives that role full administrative access to your AWS account. Be very careful about who you grant these permissions to. To see the permissions granted to **AWSGrafanaAccountAdministrator**, see [AWS managed policy: AWSGrafanaAccountAdministrator](security-iam-awsmanpol.md#security-iam-awsmanpol-AWSGrafanaAccountAdministrator) # Update your workspace version You can update your Amazon Managed Grafana workspace to a newer version of Grafana in the Amazon Managed Grafana console in two ways. **Note** You can only update the version to a newer version of Grafana. You can't downgrade to a previously released version of Grafana. Updating your version of Grafana will not update the plugins that are installed in your workspace. You might need to individually update any plugins that are not compatible with the new version of Grafana. For details on viewing and managing plugins, see [Find plugins with the plugin catalog](grafana-plugins.md#plugin-catalog). For a list of changes in each version, see [Differences between Grafana versions](version-differences.md). **Option 1 - Update the version from the list of workspaces** 1. Open the Amazon Managed Grafana console at [https://console.aws.amazon.com/grafana](https://console.aws.amazon.com/grafana). 1. In the left navigation pane, choose the menu icon. 1. Choose **All workspaces**. 1. In the row containing the details for the workspace you want to update, choose **Update version**. Only workspaces that are eligible to be updated will include this option. **Warning** The update process is irreversible and can't be paused or canceled. We recommend testing the newer version in a non-production environment before updating a production workspace. During an update, you can't make changes to the workspace. 1. Choose a version number from the dropdown on the **Update version** screen and click **Update** to confirm. 1. Periodically check the status of your update on the **Workspaces** tab. The update process could take up to 10 minutes. During this process, the workspace will be in 'read only' mode. A banner update will display to indicate if your workspace update succeeded or failed. If your update failed, follow the action items outlined in the banner and try again. **Option 2 - Update the version from the workspace summary page** 1. Open the Amazon Managed Grafana console at [https://console.aws.amazon.com/grafana](https://console.aws.amazon.com/grafana). 1. In the left navigation pane, choose the menu icon. 1. Choose **All workspaces**. 1. Choose the hyperlinked **Workspace name** of the workspace you want to update. Only workspaces that are eligible to be updated will include this option. 1. Choose the **Update version** prompt in the **Summary** block. **Warning** The update process is irreversible and can't be paused or canceled. We recommend testing the newer version in a non-production environment before updating a production workspace. During an update, you can't make changes to the workspace. 1. Choose a version number from the dropdown on the **Update version** screen and click **Update** to confirm. 1. Periodically check the status of your update on the **Workspaces** tab. The update process could take up to 10 minutes. During this process, the workspace will be in 'read only' mode. A banner update will display to indicate if your workspace update succeeded or failed. If your update failed, follow the action items outlined in the banner and try again. **Note** You can also update the version using the [UpdateWorkspaceConfiguration](https://docs.aws.amazon.com/grafana/latest/APIReference/API_UpdateWorkspaceConfiguration.html) operation in the Amazon Managed Grafana API. If you run into issues with your updated workspace, see [Troubleshooting issues with updated workspaces](AMG-workspace-version-update-troubleshoot.md). # Troubleshooting issues with updated workspaces Your updated workspace should continue to work after updating. This section can help you track down possible issues after you update. + **Differences between versions.** Some functionality has changed between versions. + For a list of major changes between versions, including changes that may cause issues in functionality, see [Differences between Grafana versions](version-differences.md). + For documentation of version 9 specific functionality, see [Working in Grafana version 9](using-grafana-v9.md). For version 10, see [Working in Grafana version 10](using-grafana-v10.md). + **PostgreSQL TLS issue** If your **TLS/SSL Mode** was set to `require` in version 8, and you were only using a root certificate, you could experience TLS or certificate issues with the PostgreSQL data source after updating. Modify your TLS settings for your PostgreSQL data source (available in your Grafana workspace side menu, by choosing the **Configuration** icon, then **Data Sources**). + Change the **TLS/SSL Mode** to `verify-ca`. + Set **TLS/SSL Method** to `Certificate content`. + Set the **Root Certificate** to the root certificate for your PostgreSQL database server. This is the only field in which you should enter a certificate. # Manage access to Enterprise plugins You can use the Amazon Managed Grafana console to manage your workspace and gain access to Enterprise plugins. Upgrading gives you access to Enterprise plugins with support for data sources from a variety of third-party independent software vendors (ISVs), including the list below. An Enterprise license also gives you access to [Grafana Labs](https://grafana.com) consulting and support services. **Enterprise data sources available with Amazon Managed Grafana Enterprise plugins include:** + AppDynamics + Databricks + Datadog + Dynatrace + GitLab + Honeycomb + Jira + MongoDB + New Relic + Oracle Database + Salesforce + SAP/HANA + ServiceNow + Snowflake + Splunk + Splunk Infrastructure Monitoring (formerly SignalFx) + Wavefront For details about the Enterprise data source plugins available when you upgrade, see [Connect to Enterprise data sources](AMG-data-sources-enterprise.md). New plugins can be added at any time. For a complete and current list, you can use the [plugin catalog](grafana-plugins.md#manage-plugins) within your Amazon Managed Grafana workspace. When you create a workspace, by default it does not have access to Enterprise plugins, but you can upgrade at any time. If you want to have multiple Amazon Managed Grafana workspaces with Enterprise plugins, you must upgrade each of them. You can manage your Enterprise plugin license, including adding or removing your access through the **Manage Amazon Managed Grafana Enterprise** page. The process of managing access to Amazon Managed Grafana Enterprise plugins has changed. If you previously used AWS Marketplace, you may be interested in the [FAQ for AWS Marketplace Enterprise users](AMG-ws-mp-license-faq.md) topic. **Topics** + [Managing your access to Amazon Managed Grafana Enterprise plugins](AMG-workspace-manage-enterprise.md) + [Link your account with Grafana Labs](AMG-workspace-register-enterprise.md) + [FAQ for AWS Marketplace Enterprise users](AMG-ws-mp-license-faq.md) # Managing your access to Amazon Managed Grafana Enterprise plugins **To manage your access to Enterprise plugins** 1. Open the Amazon Managed Grafana console at [https://console.aws.amazon.com/grafana](https://console.aws.amazon.com/grafana). 1. In the left navigation pane, choose the menu icon. 1. Choose **All workspaces**. You can see the list of workspaces. For each workspace, the **Enterprise license** columns shows the type of license the workspace has (either no license, or the **Enterprise plugins** license. 1. Select the name of the workspace whose license you want to manage. This opens the workspace details page for that workspace. 1. In the summary, under **Enterprise License**, choose either **Manage** or **Upgrade to Amazon Managed Grafana Enterprise** (only one option is available, based on the current status of the Enterprise license). This opens the **Manage Amazon Managed Grafana Enterprise** page. You can choose between two options. The active option is marked with **(current)**. + **None** – This is the option to remove, or not have an Amazon Managed Grafana Enterprise license. If you currently have an Enterprise license, selecting this option for your workspace immediately removes access to the Enterprise plugins when you save. + **Enterprise plugins** – This allows you to install any Enterprise plugins to your workspace, as well as giving access to [Grafana Labs](https://grafana.com) consulting and support services. Installing Enterprise plugins in your workspace gives you access to additional [data sources](AMG-data-sources-enterprise.md). The first time that you choose this option, you must link your AWS account with a token from Grafana Labs, and are prompted to do so. For more information, see the next section, [Link your account with Grafana Labs](AMG-workspace-register-enterprise.md). Amazon Managed Grafana Enterprise plugin access includes user fees that are in addition to the prices for Amazon Managed Grafana. For detailed fee information, see the [Amazon Managed Grafana Pricing page](https://aws.amazon.com/grafana/pricing/). 1. After making your selection, choose **Save** to continue. # Link your account with Grafana Labs Workspaces upgraded to Amazon Managed Grafana Enterprise plugins get access to support and consulting from Grafana Labs. To access this feature, the AWS account must be linked with a Grafana Labs account token. You register your new or existing Grafana Labs account with AWS when you [upgrade to an Enterprise license](AMG-workspace-manage-enterprise.md). **Note** You only need to register your Grafana Labs account token one time per region. If your account was previously linked (for example, when upgrading a different workspace in the region to access Enterprise plugins), you are not prompted to link again. Linking consists of getting a token from a Grafana Labs account that is used in Amazon Managed Grafana to register the account. You can create a new account at Grafana Labs or use an existing one. We recommend that you copy and save your Grafana Labs token in a secure, convenient location for future use. **To link your Grafana Labs account** 1. Follow the instructions in [Managing your access to Amazon Managed Grafana Enterprise plugins](AMG-workspace-manage-enterprise.md) to upgrade your account with access Enterprise plugins. You are prompted to link your account by adding a token during the upgrade process. 1. If you already have a token, you can enter it directly. If you do not have a token, select **Get your token**. This opens the [Grafana Labs website](https://grafana.com/partners/amg/support) in a new browser tab. From the Grafana Labs website, you can sign into your Grafana Labs account (or create a new one), then get a token. 1. After you copy the token, return to the Amazon Managed Grafana browser tab or window. Enter the token in the **Grafana Labs Token** section. 1. You are now able to choose **Save** to complete your upgrade. **Reusing your token with other workspaces** If you have previously registered your Grafana Labs account and are prompted for a Grafana Labs token (for example, when upgrading a workspace in another region), you can use the same token to register each time, so that you do not need to create a new Grafana Labs account. If you have not saved your token, you may be able to retrieve it in one of these ways: + You can get the token by looking it up in your Grafana Labs account by going to [https://grafana.com/partners/amg/support](https://grafana.com/partners/amg/support), and choosing **My Account**. + You can get the token from an existing, already linked workspace, by using the [DescribeWorkspace](https://docs.aws.amazon.com/grafana/latest/APIReference/API_DescribeWorkspace.html) API to retrieve the token. + If the token is no longer available to you via either of those methods, you must [contact Grafana Labs support](https://grafana.com/contact). # FAQ for AWS Marketplace Enterprise users Previously, you may have purchased a license for Grafana Enterprise through AWS Marketplace. You can no longer purchase new licenses through AWS Marketplace, and you can not renew any license that was previously purchased through AWS Marketplace. The following FAQ may help you depending on the state of your AWS Marketplace license. ## I subscribed to a 30-day free trial from AWS Marketplace, but I haven't associated it with my workspace. Can I apply it now? No. The free trials are no longer supported in Amazon Managed Grafana. ## I purchased a 30-day free trial from AWS Marketplace, and I already associated it with my workspace. What will happen to my trial? Your free trial will continue until it expires. If you want to upgrade and use the Enterprise plugins, you can upgrade through the Amazon Managed Grafana console, as described in the previous section. ## I have a AWS Marketplace paid license that hasn't yet expired, but I want to use Amazon Managed Grafana managed Enterprise plugins. How do I do that? As long as you have a current AWS Marketplace license, you can only associate that license with your workspaces. You can only upgrade in the Amazon Managed Grafana console after your AWS Marketplace license expires (or you cancel it through AWS Marketplace). The following questions and answers provide more details. ## I purchased a full Grafana Enterprise license from AWS Marketplace and associated it with one or more workspaces. What will happen to those? When your license expires (after 30 days, unless you have autorenewal turned on), any Enterprise data sources that you are using in your workspace will stop working. If you wish to continue using Enterprise data sources, you can [upgrade to use Enterprise plugins](AMG-workspace-manage-enterprise.md) directly from the Amazon Managed Grafana console. ## It sounds like there will be downtime associated with my license expiring, where my workspace can't access any Enterprise plugins. How do I avoid that? There will be some downtime associated with your license expiring, as you switch to the new Enterprise plugins license. However, you can minimize this. **Note** The following steps need to be performed precisely to minimize downtime. We recommend that you read them carefully before beginning. To get the new [pricing](https://aws.amazon.com/grafana/pricing), we recommend that you upgrade to Amazon Managed Grafana Enterprise plugins, rather than continue using the AWS Marketplace license. **To switch from AWS Marketplace Enterprise license to Amazon Managed Grafana Enterprise plugins while minimizing downtime.** 1. To prepare, first go to the [Grafana Labs website](https://grafana.com/partners/amg/support), and sign into your account (or create a new one). Get your Grafana Labs token that you will use later in the process. For more details on this part of the process, see [Link your account with Grafana Labs](AMG-workspace-register-enterprise.md). 1. Sign into the [AWS Marketplace console](https://console.aws.amazon.com/marketplace/), and choose **Manage subscriptions** from the left menu. 1. Find the subscription that you want to switch, and choose **Manage**. This will bring up details about your subscription. **Note** This page shows your service end date. You can wait until you are nearing that date to continue these steps, to maximize use of your current subscription before canceling. 1. Choose **Actions**, and select **Cancel subscription**. This cancels your subscription in AWS Marketplace. However, you can continue to use the Enterprise data sources until Amazon Managed Grafana automatically removes your license at the end of the day (local time for your workspace). For more information about canceling subscriptions in AWS Marketplace, see [Cancel your product subscription](https://docs.aws.amazon.com/marketplace/latest/buyerguide/cancel-subscription.html) in the *AWS Marketplace Buyer Guide*. 1. After your subscription is canceled in AWS Marketplace, cancel it in Amazon Managed Grafana: 1. Sign into [the Amazon Managed Grafana console](https://console.aws.amazon.com/grafana). 1. From the left menu, choose **All workspaces**. 1. Choose the name of the workspace you are switching. 1. Under **Enterprise license**, choose **Manage**. 1. Choose **None** and then **Save**. This will remove the AWS Marketplace license from Amazon Managed Grafana When the Enterprise license is removed, you will no longer be able to access Enterprise plugins in your workspace. 1. You can now upgrade in the Amazon Managed Grafana console. Follow the instructions in the [Managing your access to Amazon Managed Grafana Enterprise plugins](AMG-workspace-manage-enterprise.md) topic, using the Grafana Labs token you created in the first step. **Note** Your workspace is not able to access Enterprise data sources from the time you cancel the license in Amazon Managed Grafana until when you upgrade to access Enterprise plugins. This is typically around 10-15 minutes, but can take longer, depending on how quickly you can perform these steps. Making sure that you have the Grafana Labs token ready will minimize this time. ## I have an AWS Marketplace license with autorenew. Will that continue? Yes. The AWS Marketplace subscription is retired, and you can't manually renew it, but if you had autorenew set up, it will continue until you turn it off. When you do that, you can upgrade, following the instructions in the previous answers. To get the new [pricing](https://aws.amazon.com/grafana/pricing), we recommend that you upgrade to Amazon Managed Grafana Enterprise plugins, rather than continue using the AWS Marketplace license. ## I have an AWS Marketplace license that I haven't yet associated with a workspace, can I use it? Yes, you can associate that AWS Marketplace license and use it until it expires. That will happen within 30 days, unless you turned on autorenew. See the previous questions and answers for more information. # Migrate content between Amazon Managed Grafana workspaces There are times that you want to migrate your content (including data sources, dashboards, folder, and alert rules) from one workspace to another. For example, you are migrating from an on-premise Grafana instance to an Amazon Managed Grafana workspace, and you want to migrate your existing content to the new workspace. Amazon Managed Grafana does not directly support migrating content between workspaces, however, AWS does provide an open-source migration utility that can handle this scenario by providing export and import functionality within a workspace or Grafana instance. This utility is called the **Amazon Managed Grafana Migrator**. For more information, see [Amazon Managed Grafana Migrator](https://github.com/aws-observability/amazon-managed-grafana-migrator) on GitHub. # Manage user and group access to Amazon Managed Grafana workspaces You access Amazon Managed Grafana workspaces with users that are set up in your Identity provider (IdP) or AWS IAM Identity Center. You must give those users (or groups that they belong to) permissions to the workspace. You can give them `User`, `Editor`, or `Admin` permissions. ## Grant permissions to a user or group **Prerequisites** + To grant a user or a user group access to Amazon Managed Grafana workspaces, the user or group must first be provisioned in an Identity provider (IdP) or in AWS IAM Identity Center. For more information, see [Authenticate users in Amazon Managed Grafana workspaces](authentication-in-AMG.md). + To manage user and group access, you must be signed in as a user that has the AWS Identity and Access Management (IAM) policy **AWSGrafanaWorkspacePermissionManagementV2**, or equivalent permissions. If you are managing users with IAM Identity Center, you must also have the **AWSSSOMemberAccountAdministrator** and **AWSSSODirectoryReadOnly** IAM policies, or equivalent permissions. For more information, see [Assign and unassign users access to Amazon Managed Grafana](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-assign-users). **To manage user access to a Grafana workspace using the Amazon Managed Grafana console** 1. Open the Amazon Managed Grafana console at [https://console.aws.amazon.com/grafana/](https://console.aws.amazon.com/grafana/home/). 1. In the left navigation pane, choose the menu icon. 1. Choose **All workspaces**. 1. Choose the name of the workspace that you want to manage. 1. Choose the **Authentication** tab. 1. If you are using IAM Identity Center in this workspace, choose **Configure users and user groups** and do one or more of the following: + To give a user access to the Amazon Managed Grafana workspace, select the check box next to the user, and choose **Assign user**. + To make a user an `Admin` of the workspace, choose **Make admin**. + To remove workspace access for a user, choose **Unassign user**. + To add groups of users such as an LDAP group, choose the **Assigned user groups** tab. Then, do one of the following: + To give all members of a group access to the Amazon Managed Grafana workspace, select the check box next to the group, and choose **Assign group**. + To give all members of a group the `Admin` role in the workspace, choose **Make admin**. + To remove workspace access for all members of a group, choose **Unassign group**. **Note** If you are using IAM Identity Center to manage users, use the IAM Identity Center console only to provision new users and groups. Use the Amazon Managed Grafana console or APIs to give or remove access to your Grafana workspaces. If IAM Identity Center and Amazon Managed Grafana get out of sync, you are presented with an option to **Resolve** any conflicts. For more information, see [Permission mismatch errors when configuring users and groups](#AMG-manage-users-and-groups-mismatch), below. 1. If you are using SAML in this workspace, choose **SAML configuration** and do one or more of the following: + For **Import method**, do one of the following: + Choose **URL** and enter the URL of the IdP metadata. + Choose **Upload or copy/paste**. If you are uploading the metadata, choose **Choose file** and select the metadata file. Or, if you are using copy and paste, copy the metadata into **Import the metadata**. + For **Assertion attribute role**, enter the name of the SAML assertion attribute from which to extract role information. + For **Admin role values**, either enter the user roles from your IdP who should all be granted the `Admin` role in the Amazon Managed Grafana workspace, or select **I want to opt-out of assigning admins to my workspace.** **Note** If you choose **I want to opt-out of assigning admins to my workspace.**, you won't be able to use the Amazon Managed Grafana console to administer the workspace, including tasks such as managing data sources, users, and dashboard permissions. You can make administrative changes to the workspace only by using Amazon Managed Grafana APIs. + (Optional) To enter additional SAML settings, choose **Additional settings** and do one or more the following, and then choose **Save SAML configuration**. All of these fields are optional. + For **Assertion attribute name**, specify the name of the attribute within the SAML assertion to use for the user full "friendly" names for SAML users. + For **Assertion attribute login**, specify the name of the attribute within the SAML assertion to use for the user sign-in names for SAML users. + For **Assertion attribute email**, specify the name of the attribute within the SAML assertion to use for the user email names for SAML users. + For **Login validity duration (in minutes)**, specify how long a SAML user's sign-in is valid before the user must sign in again. + For **Assertion attribute organization**, specify the name of the attribute within the SAML assertion to use for the "friendly" name for user organizations. + For **Assertion attribute groups**, specify the name of the attribute within the SAML assertion to use for the "friendly" name for user groups. + For **Allowed organizations**, you can limit user access to only the users who are members of certain organizations in the IdP. Enter one or more organizations to allow, separating them with commas. + For **Editor role values**, enter the user roles from your IdP who should all be granted the `Editor` role in the Amazon Managed Grafana workspace. Enter one or more roles, separated by commas. 1. Alternatively, to add groups of users such as an LDAP group, choose the **User Group** tab. Then, do one of the following: + To give all members of a group access to the Amazon Managed Grafana workspace, select the check box next to the group, and choose **Assign group**. + To give all members of a group the `Admin` role in the workspace, choose **Make admin**. + To remove workspace access for all members of a group, choose **Unassign group**. ## Permission mismatch errors when configuring users and groups You might run into mismatch errors when configuring users and groups in the Amazon Managed Grafana console. This indicates that Amazon Managed Grafana and IAM Identity Center are out of sync. In this case, Amazon Managed Grafana displays a warning and a choice to **Resolve** the mismatch. If you choose **Resolve**, Amazon Managed Grafana displays a dialog with a list of users that have permissions that are out of sync. Users that have been removed from IAM Identity Center show up as `Unknown user`, with a numeric ID in the dialog. For these users, the only way to fix the mismatch is to choose **Resolve**, and remove their permissions. Users that are still in IAM Identity Center, but no longer belong to a group with the access rights that they previously had, show up with their user name in the **Resolve** list. There are two ways to fix this issue. You can use the **Resolve** dialog to remove or reduce their access, or you can give them access by following the instructions in the previous section. ## Frequently asked questions about permissions mismatches **Why am I seeing an error stating mismatch in permissions in the **Configure Users and Groups** section of the Amazon Managed Grafana console?** You are seeing this message because a mismatch has been identified in users and group associations in IAM Identity Center and permissions in Amazon Managed Grafana for your workspace. You can add or remove users to your Grafana workspace from the Amazon Managed Grafana console (in the **Configure Users and Groups** tab), or from the IAM Identity Center console (**Application assignments** page). However, the Grafana user permissions can only be defined from Amazon Managed Grafana (using the Amazon Managed Grafana console or APIs), by assigning **Viewer**, **Editor**, or **Admin** permissions to the user or group. A user can belong to multiple groups with varying permissions, in which case their permission is based on the highest access level across all groups and permissions the user belongs to. Mismatched records can result from: + A user or group is deleted from IAM Identity Center, but not in Amazon Managed Grafana. These records show as **Unknown users** in the Amazon Managed Grafana console. + A user or group's association with Grafana is deleted in IAM Identity Center (under **Application assignments**), but not in Amazon Managed Grafana. + User permissions were previously updated from the Grafana workspace directly. Updates from the Grafana workspace are not supported in Amazon Managed Grafana. To avoid these mismatches, use the Amazon Managed Grafana console or Amazon Managed Grafana APIs to manage user and group permissions for your workspace. **I have previously updated the access levels for some of my team members from the Grafana workspace. Now I see that their access levels are reverted back to their older access level. Why am I seeing this and how do I resolve this?** This is most likely due to a mismatch that was identified between the user and group association in IAM Identity Center and the permission records Amazon Managed Grafana for your workspace. If your team members are experiencing different access levels, you or an admin for your Amazon Managed Grafana might have resolved the mismatch from the Amazon Managed Grafana console, removing the mismatched records. You can re-assign the required access levels from the Amazon Managed Grafana console or APIs to restore the desired permissions. **Note** User access management is not supported from the Grafana workspace. Use the Amazon Managed Grafana console or APIs to assign user or group permissions. **Why am I noticing changes in my access levels? For example, I previously had admin access, but now only have editor permissions.** An admin for your workspace might have changed your permissions. This can happen inadvertently in the case of a mismatch between your user and group associations in IAM Identity Center and your permissions in Amazon Managed Grafana. In this case, resolving the mismatch might have removed your higher access permissions. You can request an admin to re-assign the required access level from the Amazon Managed Grafana console. # Manage permissions for data sources and notification channels Your Amazon Managed Grafana workspace must have permission to access AWS data sources for your metrics and notification channels for your alerts. You can use the Amazon Managed Grafana console to have Amazon Managed Grafana automatically create AWS Identity and Access Management (IAM) policies and permissions for the AWS data sources and notification channels that you want to use in the Amazon Managed Grafana workspace. **To manage permissions and policies for data sources and notification channels** 1. Open the Amazon Managed Grafana console at [https://console.aws.amazon.com/grafana/](https://console.aws.amazon.com/grafana/home/). 1. In the left navigation pane, choose the menu icon. 1. Choose **All workspaces**. 1. Choose the name of the workspace that you want to manage. 1. To switch between using **Service managed** and **Customer managed** permissions, choose the edit icon for **IAM role** and then make your selection. For more information, see [Amazon Managed Grafana permissions and policies for AWS data sources](AMG-manage-permissions.md). If you change from **Service managed** permissions to **Customer managed** permissions, the roles and policies that Amazon Managed Grafana created for you are not deleted in the current account. If you were using **Service managed** permissions for an organization, the roles and policies in other accounts in the organization are deleted. 1. Choose the **Data sources** tab. 1. If you are using **Service managed** permissions, you can choose **Edit** next to **IAM permission access settings** to change whether your **Service managed** permissions apply to only the current account or to an entire organization. For more information, see [Amazon Managed Grafana permissions and policies for AWS data sources](AMG-manage-permissions.md). Under **Data sources**, select the AWS data sources that you want to query in this workspace. Selecting data sources enables Amazon Managed Grafana to create the IAM roles and permissions that allow Amazon Managed Grafana to read data from these sources. You must still add the data sources in the Grafana workspace console. To manage AWS services that can be used as notification channels, choose **Notification channels**. Select the AWS notification channel that you want to use in this workspace. Selecting a notification channel enables Amazon Managed Grafana to create IAM roles and permissions that allow Amazon Managed Grafana to use these services. You must still add the notification channels in the Grafana workspace console. **Note** For more information about using notifications, see [Manage your alert notifications](v9-alerting-managenotifications.md). # Creating Amazon Managed Grafana resources with AWS CloudFormation Amazon Managed Grafana is integrated with AWS CloudFormation, a service that helps you to model and set up your AWS resources so that you can spend less time creating and managing your resources and infrastructure. You create a template that describes all the AWS resources that you want (such as workspaces), and CloudFormation provisions and configures those resources for you. When you use CloudFormation, you can reuse your template to set up your Amazon Managed Grafana resources consistently and repeatedly. Describe your resources once, and then provision the same resources over and over in multiple AWS accounts and Regions. ## Amazon Managed Grafana and CloudFormation templates To provision and configure resources for Amazon Managed Grafana and related services, you must understand [CloudFormation templates](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html). Templates are formatted text files in JSON or YAML. These templates describe the resources that you want to provision in your CloudFormation stacks. If you're unfamiliar with JSON or YAML, you can use CloudFormation Designer to help you get started with CloudFormation templates. For more information, see [What is CloudFormation Designer?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/working-with-templates-cfn-designer.html) in the *AWS CloudFormation User Guide*. Amazon Managed Grafana supports creating workspaces in CloudFormation. For more information, including examples of JSON and YAML templates for workspaces, see the [Amazon Managed Grafana resource type reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-grafana-workspace.html) in the *AWS CloudFormation User Guide*. ## Learn more about CloudFormation To learn more about CloudFormation, see the following resources: + [AWS CloudFormation](https://aws.amazon.com/cloudformation/) + [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) + [CloudFormation API Reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/Welcome.html) + [AWS CloudFormation Command Line Interface User Guide](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/what-is-cloudformation-cli.html) # Configure network access to your Amazon Managed Grafana workspace You can control how users and hosts access your Grafana workspaces. Grafana requires all users to be authenticated and authorized. However, by default, Amazon Managed Grafana workspaces are open to all network traffic. You can configure network access control for a workspace, to control what network traffic is allowed to reach it. You can control traffic to your workspace in two ways. + **IP Addresses** (prefix lists) – You can create a [managed prefix list](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-managed-prefix-lists.html) with IP ranges that are allowed to access workspaces. Amazon Managed Grafana supports only public, IPv4 addresses for network access control. + **VPC endpoints** – You can create a list of VPC endpoints to your workspaces that are allowed to access a specific workspace. When you configure network access control, you must include at least one prefix list or VPC endpoint. Amazon Managed Grafana uses the prefix lists and VPC endpoints to decide which requests to the Grafana workspace are allowed to connect. The following diagram shows this filtering. ![\[An image showing Amazon Managed Grafana network access control allowing some requests and blocking others trying to access an Amazon Managed Grafana workspace.\]](http://docs.aws.amazon.com/grafana/latest/userguide/images/grafana-nac.png) Configuring network access control (**1**) for an Amazon Managed Grafana workspace specifies which requests should be allowed to access the workspace. Network access control can allow or block traffic by IP address (**2**), or by which interface endpoint is being used (**3**). The following section describes how to set up network access control. ## Configuring network access control You can add network access control to an existing workspace or configure it as part of the initial creation of the workspace. **Prerequisites** To set up network access control you must first create either an interface VPC endpoint for your workspaces, or at least one IP prefix list for the IP addresses that you want to allow. You can create both or more than one of both, as well. + **VPC endpoint** – You can create an interface VPC endpoint that gives access to all of your workspaces. After you have created the endpoint, you need the VPC endpoint ID for each endpoint you want to allow. VPC endpoint IDs have the format `vpce-1a2b3c4d`. For information about creating a VPC endpoint for your Grafana workspaces, see [Interface VPC endpoints](VPC-endpoints.md). To create a VPC endpoint specifically for your workspaces, use the `com.amazonaws.region.grafana-workspace` endpoint name. For VPC endpoints that you give access to your workspace, you can further limit their access by configuring security groups for the endpoints. To learn more, see [Associate security groups](https://docs.aws.amazon.com/vpc/latest/privatelink/interface-endpoints.html#associate-security-groups) and [Security group rules](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#SecurityGroupRules) in the *Amazon VPC documentation*. + **Managed prefix list** (for IP address ranges) – to allow IP addresses, you must create one or more prefix lists in Amazon VPC with the list of IP ranges to allow. There are a few limitations for prefix lists when used for Amazon Managed Grafana: + Each prefix list can contain up to 100 IP address ranges. + Private IP address ranges (for example, `10.0.0.0/16` are ignored. You can include private IP address ranges in a prefix list, but Amazon Managed Grafana ignores those when filtering traffic to the workspace. To allow those hosts to reach the workspace, create a VPC endpoint for your workspaces and give them access. + Amazon Managed Grafana only supports IPv4 addresses in prefix lists, not IPv6. IPv6 addresses are ignored. You create managed prefix lists through the [Amazon VPC Console](https://console.aws.amazon.com/vpc/home?#ManagedPrefixLists). After you have created the prefix lists, you need the prefix list ID for each list you want to allow in Amazon Managed Grafana. Prefix list IDs have the format `pl-1a2b3c4d`. For more information about creating prefix lists, see [Group CIDR blocks using managed prefix lists](https://docs.aws.amazon.com/vpc/latest/userguide/managed-prefix-lists.html) in the *Amazon Virtual Private Cloud User Guide*. + You must have the necessary permissions to configure or create an Amazon Managed Grafana workspace. For example, you could use the AWS managed policy, `AWSGrafanaAccountAdministrator`. After you have the list of IDs for the prefix lists or VPC endpoints that you want to give access to your workspace, you are ready to create the network access control configuration. **Note** If you enable network access control, but do not add a prefix list to the configuration, no access to your workspace is allowed, except through the allowed VPC endpoints. Similarly, if you enable network access control, but do not add a VPC endpoint to the configuration, no access to your workspace is allowed, except through the allowed IP addresses. You must include at least one prefix list or VPC endpoint in the network access control configuration, or you would not be able to access your workspace from anywhere. **To configure network access control for a workspace** 1. Open the [Amazon Managed Grafana console](https://console.aws.amazon.com/grafana/home/). 1. In the left navigation pane, choose **All workspaces**. 1. Select the name of the workspace that you want to configure network access control. 1. In the **Network access control** tab, under **Network access control**, choose **Restricted access** to configure network access control. **Note** You can access these same options while creating a workspace. 1. From the drop down select whether you are adding a **Prefix list** or a **VPC endpoint**. 1. Select the VPC endpoint or Prefix list ID that you want to add (alternatively, you can type the ID that you want to use. You must choose at least one. 1. To add more endpoints or lists, select **Add new resource** for each one you want to add. **Note** You can add up to 5 prefix lists and 5 VPC endpoints. 1. Choose **Save changes** to complete the setup. **Warning** If you have existing users of your workspace, include their IP ranges or VPC endpoints in the configuration, or they will lose access with a `403 Forbidden` error. It is recommended that you test existing access points after setting up or modifying the configuration of network access control. # Encryption at rest By default, Amazon Managed Grafana automatically provides you with encryption at rest and does this using AWS owned encryption keys. + **AWS owned keys** – Amazon Managed Grafana uses these keys to automatically encrypt data of your workspace. You can't view, manage or use AWS owned keys, or audit their use. However, you don't have to take any action or change any programs to protect the keys that encrypt your data. For more information, see [AWS-owned keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-owned-cmk) in the *AWS KMS Developer Guide*. Encryption of data at rest helps reduce the operational overhead and complexity that goes into protecting sensitive customer data, such as personally identifiable information. It allows you to build secure applications that meet strict encryption compliance and regulatory requirements. You can alternatively choose to use a customer managed key when you create your workspace: + **Customer managed keys** – Amazon Managed Grafana supports the use of a symmetric customer managed key that you create, own, and manage to encrypt the data in your workspace. Because you have full control of this encryption, you can perform such tasks as: + Establishing and maintaining key policies + Establishing and maintaining IAM policies and grants + Enabling and disabling key policies + Rotating key cryptographic material + Adding tags + Creating key aliases + Scheduling keys for deletion For more information, see [customer managed keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk) in the *AWS KMS Developer Guide* and [What is AWS KMS?](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html) Choose whether to use customer managed keys or AWS owned keys carefully. Workspaces created with customer managed keys can't be converted to use AWS owned keys later (and vice versa). **Note** Amazon Managed Grafana automatically enables encryption at rest using AWS owned keys to protect your data at no charge. However, AWS KMS charges apply for using a customer managed key. For more information about pricing, see [AWS KMS pricing](https://aws.amazon.com/kms/pricing/). **Important** If you disable the customer managed key or remove Amazon Managed Grafana access in the key policy, your workspace will become inaccessible. The workspace will remain in an `ACTIVE` state but will be functionally unavailable. You have 7 days to restore access by re-enabling the key or restoring the key policy. After 7 days, the workspace will transition to a `FAILED` state and can only be deleted. Scheduling a key for deletion in AWS KMS has a minimum waiting period of 7 days before the key is deleted. Once a key is deleted, it cannot be restored, and any workspace encrypted with that key will permanently lose access to its data. Customer managed key encryption is only available when creating new workspaces. Existing workspaces cannot be converted to use customer managed keys. You cannot modify a workspace's customer managed key after creation. ## How Amazon Managed Grafana uses grants in AWS KMS Amazon Managed Grafana requires grants to use your customer managed key. When you create an Amazon Managed Grafana workspace encrypted with a customer managed key, Amazon Managed Grafana creates grants on your behalf by sending [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) requests to AWS KMS. Grants in AWS KMS are used to give Amazon Managed Grafana access to the KMS key in your account, even when not called directly on your behalf (for example, when storing dashboard data or user configurations). Amazon Managed Grafana requires the grants to use your customer managed key for the following internal operations: + Send [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) requests to AWS KMS to create additional grants as needed. + Send [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) requests to AWS KMS to verify that the symmetric customer managed KMS key given when creating a workspace is valid. + Send [ReEncryptTo and ReEncryptFrom](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) requests to AWS KMS to re-encrypt data when moving between different encryption contexts. + Send [Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) requests to AWS KMS to encrypt data directly with your customer managed key. + Send [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) requests to AWS KMS to decrypt the encrypted data keys so that they can be used to encrypt your data. + Send [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) requests to AWS KMS to generate data keys encrypted by your customer managed key. + Send [GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) requests to AWS KMS to generate encrypted data keys without returning the plaintext version. + Send [RetireGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_RetireGrant.html) requests to AWS KMS to retire grants that are no longer needed. Amazon Managed Grafana creates grants to the AWS KMS key that allow Amazon Managed Grafana to use the key on your behalf. You can remove access to the key by changing the key policy, by disabling the key, or by revoking the grant. You should understand the consequences of these actions before performing them. This can cause data loss in your workspace. If you remove access to any of the grants in any way, Amazon Managed Grafana won't be able to access any of the data encrypted by the customer managed key, nor store new data sent to the workspace, which affects operations that are dependent on that data. New updates to the workspace will not be accessible and may be permanently lost. **Warning** If you disable the key, or remove Amazon Managed Grafana access in the key policy, the workspace data is no longer accessible. The workspace will remain in an `ACTIVE` state but will be functionally unavailable. New updates being sent to the workspace will not be accessible and may be permanently lost. You can restore access to the workspace data and resume receiving new data by re-enabling the key or restoring Amazon Managed Grafana access to the key within 7 days. After 7 days without access, the workspace will transition to a `FAILED` state. If you schedule the key for deletion in AWS KMS, the key will be deleted after the mandatory 7-day waiting period. Once deleted, the key cannot be restored, and the workspace data will be permanently inaccessible. If you *revoke* a grant, it can't be recreated, and the data in the workspace is lost permanently. Amazon Managed Grafana creates additional child grants through Amazon RDS due to its dependency on RDS for data storage. Revoking these RDS-related grants will have the same permanent data loss effect as revoking the primary Grafana grants. ## Step 1: Create a customer managed key You can create a symmetric customer managed key by using the AWS Management Console, or the AWS KMS APIs. The key must be in the same region as the Amazon Managed Grafana workspace and must be a symmetric key with `ENCRYPT_DECRYPT` key usage. **To create a symmetric customer managed key** + Follow the steps for [Creating symmetric customer managed key](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html#create-symmetric-cmk) in the *AWS KMS Developer Guide*. Key policies control access to your customer managed key. Every customer managed key must have exactly one key policy, which contains statements that determine who can use the key and how they can use it. When you create your customer managed key, you can specify a key policy. For more information, see [Managing access to customer managed keys](https://docs.aws.amazon.com/kms/latest/developerguide/control-access-overview.html#managing-access) in the *AWS KMS Developer Guide*. To use your customer managed key with your Amazon Managed Grafana workspaces, the following API operations must be permitted in the key policy: + [kms:CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) – Adds a grant to a customer managed key. Grants control access to a specified KMS key, which allows access to [grant operations](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#terms-grant-operations) Amazon Managed Grafana requires. For more information, see [Using Grants](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html) in the *AWS KMS Developer Guide*. This allows Amazon Managed Grafana to do the following: + Call `GenerateDataKey` to generate an encrypted data key and store it. + Call `Decrypt` to use the stored encrypted data key to access encrypted data. + [kms:DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) – Provides the customer managed key details to allow Amazon Managed Grafana to validate the key. The following are policy statement examples you can add for Amazon Managed Grafana: ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "Allow IAM Users and Roles to validate KMS key", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/root" }, "Action": [ "kms:DescribeKey", "kms:GenerateDataKey", "kms:Decrypt" ], "Resource": "*", "Condition": { "StringEquals": { "kms:ViaService": [ "grafana..amazonaws.com" ] } } }, { "Sid": "Allow IAM Users and Roles to create grant on KMS key", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/root" }, "Action": "kms:CreateGrant", "Resource": "*", "Condition": { "StringEquals": { "kms:ViaService": [ "grafana..amazonaws.com" ], "kms:GrantConstraintType": "EncryptionContextSubset" }, "ForAllValues:StringEquals": { "kms:GrantOperations": [ "CreateGrant", "RetireGrant", "Decrypt", "Encrypt", "GenerateDataKey", "GenerateDataKeyWithoutPlaintext", "ReEncryptFrom", "ReEncryptTo" ] } } } ] } ``` + For more information about specifying permissions in a policy, see the [AWS Key Management Service Developer Guide](https://docs.aws.amazon.com/kms/latest/developerguide/). + For more information about troubleshooting key access, see the [AWS Key Management Service Developer Guide](https://docs.aws.amazon.com/kms/latest/developerguide/). ## Step 2: Specifying a customer managed key for Amazon Managed Grafana When you create a workspace, you can specify the customer managed key by entering a KMS Key ARN, which Amazon Managed Grafana uses to encrypt the data stored by the workspace. 1. Open the Amazon Managed Grafana console at [https://console.aws.amazon.com/grafana/](https://console.aws.amazon.com/grafana/). 1. Choose **Create workspace**. 1. In the **Encryption** section, select **Customer managed key**. 1. Enter the ARN of your customer managed key in the **KMS Key ARN** field. 1. Complete the remaining workspace configuration and choose **Create workspace**. You can specify a customer managed key when creating a workspace using the `--kms-key-id` parameter: ``` aws grafana create-workspace \ --workspace-name "my-encrypted-workspace" \ --workspace-description "Workspace with customer managed encryption" \ --account-access-type "CURRENT_ACCOUNT" \ --authentication-providers "AWS_SSO" \ --permission-type "SERVICE_MANAGED" \ --kms-key-id "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" ``` ## Monitoring your encryption keys for Amazon Managed Grafana When you use an AWS KMS customer managed key with your Amazon Managed Grafana workspaces, you can use AWS CloudTrail or Amazon CloudWatch Logs to track requests that Amazon Managed Grafana sends to AWS KMS. The following examples are AWS CloudTrail events for `CreateGrant`, `DescribeKey`, `GenerateDataKey`, and `Decrypt` to monitor KMS operations called by Amazon Managed Grafana to access data encrypted by your customer managed key: When you use an AWS KMS customer managed key to encrypt your workspace, Amazon Managed Grafana sends `CreateGrant` requests on your behalf to access the KMS key you specified. The grants that Amazon Managed Grafana creates are specific to the resource associated with the AWS KMS customer managed key. The following example event records a `CreateGrant` operation: ``` { "eventVersion": "1.08", "userIdentity": { "type": "AssumedRole", "principalId": "TESTANDEXAMPLE:Sampleuser01", "arn": "arn:aws:sts::111122223333:assumed-role/Admin/Sampleuser01", "accountId": "111122223333", "accessKeyId": "EXAMPLE-KEY-ID1", "sessionContext": { "sessionIssuer": { "type": "Role", "principalId": "TESTANDEXAMPLE:Sampleuser01", "arn": "arn:aws:sts::111122223333:assumed-role/Admin/Sampleuser01", "accountId": "111122223333", "userName": "Admin" }, "webIdFederationData": {}, "attributes": { "mfaAuthenticated": "false", "creationDate": "2021-04-22T17:02:00Z" } }, "invokedBy": "grafana.amazonaws.com" }, "eventTime": "2021-04-22T17:07:02Z", "eventSource": "kms.amazonaws.com", "eventName": "CreateGrant", "awsRegion": "us-west-2", "sourceIPAddress": "172.12.34.56", "userAgent": "ExampleDesktop/1.0 (V1; OS)", "requestParameters": { "retiringPrincipal": "grafana.amazonaws.com", "operations": [ "CreateGrant", "DescribeKey", "ReEncryptTo", "ReEncryptFrom", "Encrypt", "Decrypt", "GenerateDataKey", "GenerateDataKeyWithoutPlaintext", "RetireGrant" ], "keyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE", "granteePrincipal": "grafana.amazonaws.com" }, "responseElements": { "grantId": "0ab0ac0d0b000f00ea00cc0a0e00fc00bce000c000f0000000c0bc0a0000aaafSAMPLE" }, "requestID": "ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE", "eventID": "ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE", "readOnly": false, "resources": [ { "accountId": "111122223333", "type": "AWS::KMS::Key", "ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE" } ], "eventType": "AwsApiCall", "managementEvent": true, "eventCategory": "Management", "recipientAccountId": "111122223333" } ``` Amazon Managed Grafana uses the `DescribeKey` operation to verify if the AWS KMS customer managed key associated with your workspace exists in the account and region. The following example event records the `DescribeKey` operation: ``` { "eventVersion": "1.08", "userIdentity": { "type": "AssumedRole", "principalId": "TESTANDEXAMPLE:Sampleuser01", "arn": "arn:aws:sts::111122223333:assumed-role/Admin/Sampleuser01", "accountId": "111122223333", "accessKeyId": "EXAMPLE-KEY-ID1", "sessionContext": { "sessionIssuer": { "type": "Role", "principalId": "TESTANDEXAMPLE:Sampleuser01", "arn": "arn:aws:sts::111122223333:assumed-role/Admin/Sampleuser01", "accountId": "111122223333", "userName": "Admin" }, "webIdFederationData": {}, "attributes": { "mfaAuthenticated": "false", "creationDate": "2021-04-22T17:02:00Z" } }, "invokedBy": "grafana.amazonaws.com" }, "eventTime": "2021-04-22T17:07:02Z", "eventSource": "kms.amazonaws.com", "eventName": "DescribeKey", "awsRegion": "us-west-2", "sourceIPAddress": "172.12.34.56", "userAgent": "ExampleDesktop/1.0 (V1; OS)", "requestParameters": { "keyId": "00dd0db0-0000-0000-ac00-b0c000SAMPLE" }, "responseElements": null, "requestID": "ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE", "eventID": "ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE", "readOnly": true, "resources": [ { "accountId": "111122223333", "type": "AWS::KMS::Key", "ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE" } ], "eventType": "AwsApiCall", "managementEvent": true, "eventCategory": "Management", "recipientAccountId": "111122223333" } ``` Amazon Managed Grafana uses the `GenerateDataKey` operation to generate data keys that are used to encrypt workspace data. The following example event records the `GenerateDataKey` operation: ``` { "eventVersion": "1.08", "userIdentity": { "type": "AssumedRole", "principalId": "TESTANDEXAMPLE:Sampleuser01", "arn": "arn:aws:sts::111122223333:assumed-role/Admin/Sampleuser01", "accountId": "111122223333", "accessKeyId": "EXAMPLE-KEY-ID1", "sessionContext": { "sessionIssuer": { "type": "Role", "principalId": "TESTANDEXAMPLE:Sampleuser01", "arn": "arn:aws:sts::111122223333:assumed-role/Admin/Sampleuser01", "accountId": "111122223333", "userName": "Admin" }, "webIdFederationData": {}, "attributes": { "mfaAuthenticated": "false", "creationDate": "2021-04-22T17:02:00Z" } }, "invokedBy": "grafana.amazonaws.com" }, "eventTime": "2021-04-22T17:07:02Z", "eventSource": "kms.amazonaws.com", "eventName": "GenerateDataKey", "awsRegion": "us-west-2", "sourceIPAddress": "172.12.34.56", "userAgent": "ExampleDesktop/1.0 (V1; OS)", "requestParameters": { "keyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE", "keySpec": "AES_256" }, "responseElements": null, "requestID": "ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE", "eventID": "ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE", "readOnly": false, "resources": [ { "accountId": "111122223333", "type": "AWS::KMS::Key", "ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE" } ], "eventType": "AwsApiCall", "managementEvent": true, "eventCategory": "Management", "recipientAccountId": "111122223333" } ``` Amazon Managed Grafana uses the `Decrypt` operation to decrypt encrypted data keys so that they can be used to decrypt workspace data. The following example event records the `Decrypt` operation: ``` { "eventVersion": "1.08", "userIdentity": { "type": "AssumedRole", "principalId": "TESTANDEXAMPLE:Sampleuser01", "arn": "arn:aws:sts::111122223333:assumed-role/Admin/Sampleuser01", "accountId": "111122223333", "accessKeyId": "EXAMPLE-KEY-ID1", "sessionContext": { "sessionIssuer": { "type": "Role", "principalId": "TESTANDEXAMPLE:Sampleuser01", "arn": "arn:aws:sts::111122223333:assumed-role/Admin/Sampleuser01", "accountId": "111122223333", "userName": "Admin" }, "webIdFederationData": {}, "attributes": { "mfaAuthenticated": "false", "creationDate": "2021-04-22T17:02:00Z" } }, "invokedBy": "grafana.amazonaws.com" }, "eventTime": "2021-04-22T17:07:02Z", "eventSource": "kms.amazonaws.com", "eventName": "Decrypt", "awsRegion": "us-west-2", "sourceIPAddress": "172.12.34.56", "userAgent": "ExampleDesktop/1.0 (V1; OS)", "requestParameters": { "encryptionContext": { "aws:grafana:workspace-id": "g-1234567890abcdef0" } }, "responseElements": null, "requestID": "ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE", "eventID": "ff000af-00eb-00ce-0e00-ea000fb0fba0SAMPLE", "readOnly": true, "resources": [ { "accountId": "111122223333", "type": "AWS::KMS::Key", "ARN": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-123456SAMPLE" } ], "eventType": "AwsApiCall", "managementEvent": true, "eventCategory": "Management", "recipientAccountId": "111122223333" } ``` ## Learn more The following resources provide more information about data encryption at rest. + For more information about AWS KMS basic concepts, see the [AWS KMS Developer Guide](https://docs.aws.amazon.com/kms/latest/developerguide/). + For more information about Security best practices for AWS KMS, see the [AWS KMS Developer Guide](https://docs.aws.amazon.com/kms/latest/developerguide/). # Connect to data sources or notification channels in Amazon VPC from Amazon Managed Grafana By default, traffic from your Amazon Managed Grafana workspace to data sources or notification channels flows via the public Internet. This limits the connectivity from your Amazon Managed Grafana workspace to services that are publicly accessible. **Note** When you have not configured a private VPC, and Amazon Managed Grafana is connecting to publicly accessible data sources, it connects to some AWS services in the same region via AWS PrivateLink. This includes services such as CloudWatch, Amazon Managed Service for Prometheus and AWS X-Ray. Traffic to those services does not flow via the public Internet. If you want to connect to private-facing data sources that are within a VPC, or keep traffic local to a VPC, you can connect your Amazon Managed Grafana workspace to the Amazon Virtual Private Cloud (Amazon VPC) hosting these data sources. After you configure the VPC data source connection, all traffic flows via your VPC. A *virtual private cloud* (VPC) is a virtual network dedicated to your AWS account. It is logically isolated from other virtual networks, including other VPCs and the public internet. Use Amazon VPC to create and manage your VPCs in the AWS Cloud. Amazon VPC gives you full control over your virtual networking environment, including resource placement, connectivity, and security. Amazon Managed Grafana data sources, and other resources, can be created in your VPC. For more information on Amazon VPC, see [What is Amazon VPC?](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) in the *Amazon Virtual Private Cloud User Guide*. **Note** If you want your Amazon Managed Grafana workspace to connect to data outside of the VPC, in another network or public Internet, you must add routing to the other network. For information about how to connect your VPC to another network, see [Connect your VPC to other networks](https://docs.aws.amazon.com/vpc/latest/userguide/extend-intro.html) in the *Amazon Virtual Private Cloud User Guide*. ## How VPC connectivity works [Amazon VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) gives you complete control over your virtual networking environment, including creating public-facing and private-facing *subnets* for your application to connect, and *security groups* to manage what services or resources have access to the subnets. To use Amazon Managed Grafana with resources in a VPC, you must create a connection to that VPC for the Amazon Managed Grafana workspace. After you set up the connection, Amazon Managed Grafana connects your workspace to each provided subnet in each Availability Zone in that VPC, and all traffic to or from the Amazon Managed Grafana workspace flows through the VPC. The following diagram shows how this connectivity looks, logically. ![\[An image showing Amazon Managed Grafana connecting to a VPC across multiple Availability Zones.\]](http://docs.aws.amazon.com/grafana/latest/userguide/images/grafana-vpc-connection.png) Amazon Managed Grafana creates a connection (**1**) per subnet (using an [elastic network interface](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html), or ENI) to connect to the VPC (**2**). The Amazon Managed Grafana VPC connection is associated with a set of security groups (**3**) that control the traffic between the VPC and your Amazon Managed Grafana workspace. All traffic is routed through the configured VPC, including alert destination and data source connectivity. To connect to data sources and alert destinations in other VPCs or the public Internet (**4**), create a [gateway](https://docs.aws.amazon.com/vpc/latest/userguide/extend-intro.html) (**5**) between the other network and your VPC. ## Create a connection to a VPC This section describes the steps to connect to a VPC from your existing Amazon Managed Grafana workspace. You can follow these same instructions when creating your workspace. For more information about creating a workspace, see [Create an Amazon Managed Grafana workspace](AMG-create-workspace.md). ### Prerequisites The following are prerequisites for establishing a connection to a VPC from an existing Amazon Managed Grafana workspace. + You must have the necessary permissions to configure or create an Amazon Managed Grafana workspace. For example, you could use the AWS managed policy, `AWSGrafanaAccountAdministrator`. + You must have a VPC setup in your account with at least two Availability Zones configured, with one *private subnet* configured for each. You must know the subnet and security group information for your VPC. **Note** [Local Zones](https://docs.aws.amazon.com/local-zones/latest/ug/what-is-aws-local-zones.html) and [Wavelength Zones](https://docs.aws.amazon.com/wavelength/latest/developerguide/what-is-wavelength.html) are not supported. [VPCs configured](https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html) with `Tenancy` set to `Dedicated` are not supported. **Important** A minimum of 15 available IP addresses must be in each subnet connected to your Amazon Managed Grafana workspace. We strongly recommend that you configure alarms to [monitor IP usage](https://docs.aws.amazon.com/vpc/latest/ipam/tracking-ip-addresses-ipam.html) in your VPC subnets. If the number of available IP addresses for a subnet falls below 15, you might experience the following issues: Inability to make configuration changes to your workspace until you free up additional IP addresses or attach subnets with additional IP addresses Your workspace will not be able to receive security updates or patches In rare scenarios, you could experience a complete availability loss for the workspace, resulting in non-functioning alerts and inaccessible dashboards + If you are connecting an existing Amazon Managed Grafana workspace that has data sources configured, we recommend that you have your VPC configured to connect to those data sources before connecting Amazon Managed Grafana to the VPC. This includes services such as CloudWatch that are connected through AWS PrivateLink. Otherwise, connectivity to those data sources is lost. + If your VPC already has multiple gateways to other networks, you might need to set up DNS resolution across the multiple gateways. For more information, see [Route 53 Resolver](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resolver.html). ### Connecting to a VPC from an existing Amazon Managed Grafana workspace The following procedure describes adding an Amazon VPC data source connection to an existing Amazon Managed Grafana workspace. **Note** When you configure the connection to Amazon VPC, it creates an IAM role. With this role, Amazon Managed Grafana can create connections to the VPC. The IAM role uses the service-linked role policy, `AmazonGrafanaServiceLinkedRolePolicy`. To learn more about service-linked roles, see [Service-linked role permissions for Amazon Managed Grafana](using-service-linked-roles.md#slr-permissions). **To connect to a VPC from an existing Amazon Managed Grafana workspace** 1. Open the [Amazon Managed Grafana console](https://console.aws.amazon.com/grafana/home/). 1. In the left navigation pane, choose **All workspaces**. 1. Select the name of the workspace that you want to add a VPC data source connection. 1. In the **Network access settings** tab, next to **Outbound VPC connection**, choose **Edit** to create your VPC connection. 1. Choose the **VPC** you want to connect. 1. Under **Mappings**, select the Availability Zones you want to use. You must choose at least two. 1. Select at least one *private subnet* in each Availability Zone. The subnets must support IPv4. 1. Select at least one **Security group** for your VPC. You can specify up to 5 security groups. Alternately, you can create a security group to apply to this connection. 1. Choose **Save changes** to complete the setup. Now that you have set up your VPC connection, you can add [Connect to data sources](AMG-data-sources.md) accessible from that VPC to your Amazon Managed Grafana workspace. **Changing outbound VPC settings** To change your settings, you can return to the **Network access settings** tab of your workspace configuration, or you can use the [UpdateWorkspace](https://docs.aws.amazon.com/grafana/latest/APIReference/API_UpdateWorkspace.html) API. **Important** Amazon Managed Grafana manages your VPC configuration for you. Do not edit these VPC settings using the Amazon EC2 console or APIs, or the settings will get out of sync. # Troubleshoot using VPC with Amazon Managed Grafana Answers to common questions regarding using Amazon Virtual Private Cloud (Amazon VPC) with Amazon Managed Grafana. ## When do I need to configure a VPC in Amazon Managed Grafana? You need to configure a VPC in Amazon Managed Grafana if you are trying to connect to a data source that is only available in a private VPC (that is not publicly accessible). For data sources that are publicly available, or have a public-facing endpoint, you do not need to configure a VPC. If you connect to Amazon CloudWatch, Amazon Managed Service for Prometheus, or AWS X-Ray, you do not need to configure a VPC. These data source are connected to Amazon Managed Grafana via AWS PrivateLink by default. ## Why are my existing data sources failing to connect after I configured a VPC with my Amazon Managed Grafana workspace? Your existing data sources are likely accessible through the public network and your Amazon VPC configuration does not allow access to the public network. After configuring the VPC connection in your Amazon Managed Grafana workspace, all traffic must flow through that VPC. This includes private data sources hosted within that VPC, data sources in another VPC, AWS Managed Services that are not available in the VPC, and internet-facing data sources. To resolve this issue, you must connect the other data sources to the VPC that you have configured: + For internet-facing data sources, connect the VPC to the internet. You can, for example, [Connect to the internet or other networks using NAT devices](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat.html) (from the *Amazon Virtual Private Cloud User Guide*). + For data sources in other VPCs, create a peering between the two VPCs. For more information, see [Connect VPCs using VPC peering](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-peering.html) (from the *Amazon Virtual Private Cloud User Guide*). + For AWS Managed Services that are not accessible in your VPC, such as CloudWatch, X-Ray, or Amazon Managed Service for Prometheus, you might need to create an interface VPC endpoint for that service in your VPC. For more information, see [Access an AWS service using an interface VPC endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html) in the *AWS PrivateLink Guide*. ## Can I use a VPC with dedicated tenancy? No, [VPCs configured](https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html) with `Tenancy` set to `Dedicated` are not supported. ## Can I connect both AWS Managed Services (such as Amazon Managed Service for Prometheus, CloudWatch, or X-Ray) and private data sources (including Amazon Redshift) to the same Amazon Managed Grafana workspace? Yes. You must configure connectivity to the AWS Managed Services in the same VPC as your private data sources (for example, using an [interface VPC endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html) or a [NAT Gateway](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat.html)), and configure your Amazon Managed Grafana workspace to connect to the same VPC. ## Why do I get a `502 Bad Gateway Error` when I am trying to connect to a data source after I configured the VPC in my Amazon Managed Grafana workspace? The following are the three most common reasons why your data source connection returns a `502` error. + **Security group error** — The security groups selected during VPC configuration in Amazon Managed Grafana must allow connectivity to the data source via inbound and outbound rules. To resolve this issues, make sure that the rules in both the data source security group and the Amazon Managed Grafana security group allow this connectivity. + **User permission error** — The assigned workspace user does not have the right permissions to query the data source. To resolve this issue, confirm that the user has the required IAM permissions to edit the workspace, and the correct data source policy to access and query the data from the hosting service. Permissions are available in the AWS Identity and Access Management (IAM) console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). + **Incorrect connection details provided** — The Amazon Managed Grafana workspace is unable to connect to your data source due to incorrect connection details provided. To resolve this issue, please confirm the information in the data source connection, including the data source authentication and endpoint URL, and retry the connection. ## Can I connect to multiple VPCs from the same Amazon Managed Grafana workspace? You can only configure a single VPC for a Amazon Managed Grafana workspace. To access data sources in a different VPC, or across regions, see the next question. ## How do I connect to data sources in a different VPC? How do I connect to data sources from a VPC that's in a different AWS Region or AWS account? You can use [VPC peering](https://docs.aws.amazon.com/vpc/latest/peering/what-is-vpc-peering.html) or [AWS Transit Gateway](https://docs.aws.amazon.com/vpc/latest/tgw/what-is-transit-gateway.html) to connect the cross-region or cross-account VPCs, then connect the VPC that is in the same AWS account and Region as your Amazon Managed Grafana workspace. Amazon Managed Grafana connects to the outside data sources as any other connection within the VPC. **Note** If VPC peering isn't an option for you, share your use case with your Account Manager, or send email to [aws-grafana-feedback@amazon.com](mailto:aws-grafana-feedback@amazon.com). ## When my Amazon Managed Grafana workspace is connected to a VPC will I still be able to connect to other public data sources? Yes. You can connect data sources from both your VPC and public data sources to a single Amazon Managed Grafana workspace at the same time. For public data sources, you must configure VPC connectivity via a [NAT Gateway](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat.html), or other [VPC connection](https://docs.aws.amazon.com/vpc/latest/userguide/extend-intro.html). Requests to public data sources traverse your VPC, giving you additional visibility and control over those requests. ## What should I do if I'm unable to update an Amazon Managed Grafana workspace due to insufficient IP addresses? You might encounter the following error when modifying your Amazon Managed Grafana workspace configuration: All subnets in the VPC configuration must have at least 15 available IP addresses. You will receive this error if one or more subnets connected to your workspace do not meet the minimum IP requirements. A minimum of 15 available IP addresses must be in each subnet connected to your workspace. When the number of available IP addresses for a subnet falls below 15, you might experience the following issues: + Inability to make configuration changes to your workspace until you free up additional IP addresses or attach subnets with additional IP addresses + Your workspace will not be able to receive security updates or patches + In rare scenarios, you could experience a complete availability loss for the workspace, resulting in non-functioning alerts and inaccessible dashboards **Mitigate IP exhaustion** 1. If a subnet has less than 15 available IP addresses, release IP addresses associated with instances or delete unused network interfaces to free up IP capacity. 1. If you are unable to free up IP addresses in the existing subnet, then you must replace the subnet with one that has at least 15 available IP addresses. We recommend using dedicated subnets for Amazon Managed Grafana. **Replace a subnet** 1. Open the [Amazon Managed Grafana console](https://console.aws.amazon.com/grafana). 1. In the left navigation pane, choose **All workspaces**, then select the name of your workspace. 1. In the **Network access control** tab, next to **Outbound VPC connection**, choose **Edit**. 1. Under **Mappings**, select the Availability Zone which contains the subnet with insufficient IP addresses. 1. In the dropdown, deselect the subnet with insufficient IP addresses and select a subnet with at least 15 available IP addresses. If necessary, create a new subnet in your VPC. For more information, see [Create a subnet](https://docs.aws.amazon.com/vpc/latest/userguide/create-subnets.html) in the *Amazon VPC User Guide*. 1. Choose **Save changes** to complete the setup. ## Before configuring a VPC connection my Grafana alerts were successfully being sent to downstream services, such as PagerDuty and Slack. After configuring VPC, why are my Grafana alerts not being delivered to these notification destinations? After you configure a VPC connection for an Amazon Managed Grafana workspace, all traffic to data sources in the workspace flows through the configured VPC. Make sure that the VPC has a route to reach these alert notification services. For example, alert notification destinations hosted by third parties might require connectivity to the Internet. Much like data sources, configure an Internet or AWS Transit Gateway, or other VPC connection to the external destination. ## Can I edit my VPC manually? Why does modifying my security group or subnet cause my Amazon Managed Grafana workspace to become unavailable? The Amazon Managed Grafana VPC connection uses the security groups and subnets to control the traffic allowed between the VPC and your Amazon Managed Grafana workspace. When the security group or subnet is modified or deleted from outside the Amazon Managed Grafana console (such as with the VPC console), the VPC connection in your Amazon Managed Grafana workspace stops protecting your workspace security, and the workspace becomes unreachable. To fix this issue, update the security groups configured for your Amazon Managed Grafana workspace in the Amazon Managed Grafana console. When viewing your workspace, select **Outbound VPC connection** on the **Network access control** tab to modify the subnets or security groups associated with the VPC connection. # Configure a Amazon Managed Grafana workspace Amazon Managed Grafana configuration can be separated into configuration of the Amazon Managed Grafana authentication and permissions, and configuration of the Grafana workspace. This section includes information regarding configuration of your Grafana workspace. For more information about configuring Amazon Managed Grafana authentication and permissions, see the following topics. + [Authenticate users in Amazon Managed Grafana workspaces](authentication-in-AMG.md) + [Manage user and group access to Amazon Managed Grafana workspaces](AMG-manage-users-and-groups-AMG.md) + [Users, teams, and permissions](Grafana-administration-authorization.md) You can modify the configuration of your Grafana workspace within Amazon Managed Grafana on the **Workspace configuration options** tab when viewing the properties of your workspace. Making configuration changes to your Grafana instance can cause the instance to restart to reload the new settings. After configuration changes are made, your users might need to refresh any browser pages that show the Grafana workspace. **Note** The same options are available to you when you first create your workspace. **To change the configuration of a Grafana workspace using the Amazon Managed Grafana console** 1. Open the Amazon Managed Grafana console at [https://console.aws.amazon.com/grafana/](https://console.aws.amazon.com/grafana/home/). 1. In the left navigation pane, choose the menu icon. 1. Choose **All workspaces**. 1. Choose the name of the workspace that you want to configure. This opens the details for that workspace. 1. Choose the **Workspace configuration options** tab to see the instance configuration options for your instance. 1. Select **Edit** next to either **Grafana alerting** or **Plugin management**. + **Grafana alerting** You can enable [Grafana alerting](v10-alerts.md). To view Prometheus alerts in your Grafana workspace, select the check box to **Turn Grafana alerting on**. In workspaces running version 8 or 9, this will send multiple notifications for your Grafana alerts. If you use alerts defined in Grafana, we recommend updating your workspace to version 10.4 or later. If you want to the classic Grafana alerts instead, *clear* the check box next to **Turn Grafana alerting on**. This turns on the [classic dashboard alerts](old-alerts-overview.md). Even if you don't turn Grafana alerting on, your existing Grafana alerts are evaluated. **Note** Classic dashboard alerts have been removed in Grafana version 12. In version 12 workspaces, Grafana alerting is always enabled and the toggle is no longer available. For more information, see [Migrating classic dashboard alerts to Grafana alerting](v10-alerting-use-grafana-alerts.md). + **Plugin management** To turn on plugin management, select the check box to **Turn plugin management on**. Turning plugin management on allows admins in your Amazon Managed Grafana workspace to install, update, or remove [plugins](grafana-plugins.md) using the Grafana plugin catalog. This option is only available for workspaces that support Grafana version 9 or newer. **Note** If you turn *off* Grafana alerting, you lose all changes made to the alerting configuration while Grafana alerting was on. This includes any new alert rules that you created. For more information about using Grafana alerting, and the effects of turning it on or off, see [Alerts in Grafana version 10](v10-alerts.md). The next section shows how to make changes to the Grafana instance configuration using the Amazon Managed Grafana API or the AWS CLI. ## Setting configuration with API or AWS CLI You can set the Grafana workspace configuration using the Amazon Managed Grafana API or the AWS CLI. **Note** The `configuration` is a JSON string to allow for future configuration settings which made be added later. ------ #### [ AWS CLI ] **To update Amazon Managed Grafana instance configuration using the AWS CLI** Run the following command to turn on the Grafana alerting and plugin management features for an instance. Replace the ** and ** strings with appropriate values for your instance. ``` aws grafana update-workspace-configuration \ --region region \ --workspace-id \ --configuration '{"plugins": {"pluginAdminEnabled": true}, "unifiedAlerting": {"enabled": true}}' ``` The configuration currently supports the following options. These turn Grafana alerting or plugin management on or off. + To enable Grafana alerting, use this configuration option: ``` --configuration '{"unifiedAlerting": { "enabled": true }}' ``` + To enable plugin management, use this configuration option: ``` --configuration '{"plugins": {"pluginAdminEnabled": true }}' ``` This option is only available in workspaces that support Grafana version 9 or newer. ------ #### [ Amazon Managed Grafana API ] **To update Amazon Managed Grafana instance configuration using the API** Use the following action to turn on the Grafana alerting and plugin management features for an instance. Replace the ** string with an appropriate value for your instance. ``` PUT /workspaces//configuration HTTP/1.1 Content-type: application/json { "configuration": "{ \"unifiedAlerting\": { \"enabled\": true }, \"plugins\": { \"pluginAdminEnabled\": true }}" } ``` The configuration currently supports the following options. These turn Grafana alerting or plugin management on or off. + To enable Grafana alerting, use this configuration option: ``` "configuration": "{\"unifiedAlerting\": { \"enabled\": true }}" ``` + To enable plugin management, use this option: ``` "plugins": "{\"pluginAdminEnabled\": true }" ``` This option is only available in workspaces that support Grafana version 9 or newer. ------ # Delete a Amazon Managed Grafana workspace If you delete an Amazon Managed Grafana workspace, all the configuration data for that workspace is also deleted. This includes dashboards, data source configuration, alerts, and snapshots. **To delete an Amazon Managed Grafana workspace** 1. Open the Amazon Managed Grafana console at [https://console.aws.amazon.com/grafana/](https://console.aws.amazon.com/grafana/home/). 1. In the left navigation pane, choose the menu icon. 1. Choose **All workspaces**. 1. Choose the name of the workspace that you want to delete. 1. Choose **Delete**. 1. To confirm the deletion, enter the name of the workspace and choose **Delete**. **Note** This procedure deletes a workspace. Other resources may not be deleted. For example, IAM roles that were in use by the workspace are not deleted (but may be unlocked if they are no longer in use).