workspaces

Creates, updates, deletes, gets or lists a workspaces resource.

Overview

Name	workspaces
Type	Resource
Id	aws.grafana.workspaces

Fields

The following fields are returned by SELECT queries:

describe_workspace

Name	Datatype	Description
id	string	The unique ID of this workspace. (pattern: <code>g-[0-9a-f]{10}</code>)
name	string	The name of the workspace. (pattern: <code>[a-zA-Z0-9-._~]{1,255}</code>)
account_access_type	string	Specifies whether the workspace can access Amazon Web Services resources in this Amazon Web Services account only, or whether it can also access Amazon Web Services resources in other accounts in the same organization. If this is ORGANIZATION, the workspaceOrganizationalUnits parameter specifies which organizational units the workspace can access. (CURRENT_ACCOUNT, ORGANIZATION)
authentication	object	A structure that describes whether the workspace uses SAML, IAM Identity Center, or both methods for user authentication.
created	string (date-time)	The date that the workspace was created.
data_sources	array	Specifies the Amazon Web Services data sources that have been configured to have IAM roles and permissions created to allow Amazon Managed Grafana to read data from these sources. This list is only used when the workspace was created through the Amazon Web Services console, and the permissionType is SERVICE_MANAGED.
degraded_workspace_reason	string	If the workspace is in the DEGRADED status, this field describes the reason the workspace is degraded.
description	string	The user-defined description of the workspace.
endpoint	string	The URL that users can use to access the Grafana console in the workspace.
free_trial_consumed	boolean	Specifies whether this workspace has already fully used its free trial for Grafana Enterprise. Amazon Managed Grafana workspaces no longer support Grafana Enterprise free trials.
free_trial_expiration	string (date-time)	If this workspace is currently in the free trial period for Grafana Enterprise, this value specifies when that free trial ends. Amazon Managed Grafana workspaces no longer support Grafana Enterprise free trials.
grafana_token	string	The token that ties this workspace to a Grafana Labs account. For more information, see Link your account with Grafana Labs.
grafana_version	string	The version of Grafana supported in this workspace.
ip_address_type	string	The type of IP addresses supported for connection to the workspace. Valid values are IPv4 and DualStack. (IPv4, DualStack)
kms_key_id	string	The ID or ARN of the Key Management Service key used for encrypting workspace data. (pattern: <code>[a-zA-Z0-9:/_-]+</code>)
license_expiration	string (date-time)	If this workspace has a full Grafana Enterprise license purchased through Amazon Web Services Marketplace, this specifies when the license ends and will need to be renewed. Purchasing the Enterprise plugins option through Amazon Managed Grafana does not have an expiration. It is valid until the license is removed.
license_type	string	Specifies whether this workspace has a full Grafana Enterprise license. Amazon Managed Grafana workspaces no longer support Grafana Enterprise free trials. (ENTERPRISE, ENTERPRISE_FREE_TRIAL)
modified	string (date-time)	The most recent date that the workspace was modified.
network_access_control	object	The configuration settings for network access to your workspace.
notification_destinations	array	The Amazon Web Services notification channels that Amazon Managed Grafana can automatically create IAM roles and permissions for, to allow Amazon Managed Grafana to use these channels.
organization_role_name	string	The name of the IAM role that is used to access resources through Organizations.
organizational_units	array	Specifies the organizational units that this workspace is allowed to use data sources from, if this workspace is in an account that is part of an organization.
permission_type	string	If this is SERVICE_MANAGED, and the workplace was created through the Amazon Managed Grafana console, then Amazon Managed Grafana automatically creates the IAM roles and provisions the permissions that the workspace needs to use Amazon Web Services data sources and notification channels. If this is CUSTOMER_MANAGED, you must manage those roles and permissions yourself. If you are working with a workspace in a member account of an organization and that account is not a delegated administrator account, and you want the workspace to access data sources in other Amazon Web Services accounts in the organization, this parameter must be set to CUSTOMER_MANAGED. For more information about converting between customer and service managed, see Managing permissions for data sources and notification channels. For more information about the roles and permissions that must be managed for customer managed workspaces, see Amazon Managed Grafana permissions and policies for Amazon Web Services data sources and notification channels (CUSTOMER_MANAGED, SERVICE_MANAGED)
stack_set_name	string	The name of the CloudFormation stack set that is used to generate IAM roles to be used for this workspace.
status	string	The current status of the workspace. (ACTIVE, CREATING, DELETING, FAILED, UPDATING, UPGRADING, DELETION_FAILED, CREATION_FAILED, UPDATE_FAILED, UPGRADE_FAILED, LICENSE_REMOVAL_FAILED, VERSION_UPDATING, VERSION_UPDATE_FAILED, DEGRADED)
tags	object	The list of tags associated with the workspace.
vpc_configuration	object	The configuration for connecting to data sources in a private VPC (Amazon Virtual Private Cloud).
workspace_role_arn	string	The IAM role that grants permissions to the Amazon Web Services resources that the workspace will view data from. This role must already exist.

list_workspaces

Name	Datatype	Description
id	string	The unique ID of the workspace. (pattern: <code>g-[0-9a-f]{10}</code>)
name	string	The name of the workspace. (pattern: <code>[a-zA-Z0-9-._~]{1,255}</code>)
authentication	object	A structure containing information about the authentication methods used in the workspace.
created	string (date-time)	The date that the workspace was created.
description	string	The customer-entered description of the workspace.
endpoint	string	The URL endpoint to use to access the Grafana console in the workspace.
grafana_token	string	The token that ties this workspace to a Grafana Labs account. For more information, see Link your account with Grafana Labs.
grafana_version	string	The Grafana version that the workspace is running.
license_type	string	Specifies whether this workspace has a full Grafana Enterprise license. Amazon Managed Grafana workspaces no longer support Grafana Enterprise free trials. (ENTERPRISE, ENTERPRISE_FREE_TRIAL)
modified	string (date-time)	The most recent date that the workspace was modified.
notification_destinations	array	The Amazon Web Services notification channels that Amazon Managed Grafana can automatically create IAM roles and permissions for, which allows Amazon Managed Grafana to use these channels.
status	string	The current status of the workspace. (ACTIVE, CREATING, DELETING, FAILED, UPDATING, UPGRADING, DELETION_FAILED, CREATION_FAILED, UPDATE_FAILED, UPGRADE_FAILED, LICENSE_REMOVAL_FAILED, VERSION_UPDATING, VERSION_UPDATE_FAILED, DEGRADED)
tags	object	The list of tags associated with the workspace.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_workspace	select	workspace_id, region		Displays information about one Amazon Managed Grafana workspace.
list_workspaces	select	region	maxResults, nextToken	Returns a list of Amazon Managed Grafana workspaces in the account, with some information about each workspace. For more complete information about one workspace, use DescribeWorkspace.
create_workspace_api_key	insert	workspace_id, region, keyName, keyRole, secondsToLive		Creates a Grafana API key for the workspace. This key can be used to authenticate requests sent to the workspace's HTTP API. See https:​//docs.aws.amazon.com/grafana/latest/userguide/Using-Grafana-APIs.html for available APIs and example requests. In workspaces compatible with Grafana version 9 or above, use workspace service accounts instead of API keys. API keys will be removed in a future release.
create_workspace	insert	region, accountAccessType, permissionType, authenticationProviders		Creates a workspace. In a workspace, you can create Grafana dashboards and visualizations to analyze your metrics, logs, and traces. You don't have to build, package, or deploy any hardware to run the Grafana server. Don't use CreateWorkspace to modify an existing workspace. Instead, use UpdateWorkspace.
associate_license	update	workspace_id, license_type, region	Grafana-Token	Assigns a Grafana Enterprise license to a workspace. To upgrade, you must use ENTERPRISE for the licenseType, and pass in a valid Grafana Labs token for the grafanaToken. Upgrading to Grafana Enterprise incurs additional fees. For more information, see Upgrade a workspace to Grafana Enterprise.
update_workspace	update	workspace_id, region		Modifies an existing Amazon Managed Grafana workspace. If you use this operation and omit any optional parameters, the existing values of those parameters are not changed. To modify the user authentication methods that the workspace uses, such as SAML or IAM Identity Center, use UpdateWorkspaceAuthentication. To modify which users in the workspace have the Admin and Editor Grafana roles, use UpdatePermissions.
delete_workspace_api_key	delete	key_name, workspace_id, region		Deletes a Grafana API key for the workspace. In workspaces compatible with Grafana version 9 or above, use workspace service accounts instead of API keys. API keys will be removed in a future release.
delete_workspace	delete	workspace_id, region		Deletes an Amazon Managed Grafana workspace.
disassociate_license	exec	workspace_id, license_type, region		Removes the Grafana Enterprise license from a workspace.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
key_name	string	The name of the API key to delete.
license_type	string	The type of license to remove from the workspace.
region	string	AWS region (default: us-east-1)
workspace_id	string	The ID of the workspace to remove the Grafana Enterprise license from.
Grafana-Token	string	A token from Grafana Labs that ties your Amazon Web Services account with a Grafana Labs account. For more information, see Link your account with Grafana Labs.
maxResults	integer	The maximum number of workspaces to include in the results.
nextToken	string	The token for the next set of workspaces to return. (You receive this token from a previous ListWorkspaces operation.)

SELECT examples

describe_workspace

Displays information about one Amazon Managed Grafana workspace.

SELECT
id,
name,
account_access_type,
authentication,
created,
data_sources,
degraded_workspace_reason,
description,
endpoint,
free_trial_consumed,
free_trial_expiration,
grafana_token,
grafana_version,
ip_address_type,
kms_key_id,
license_expiration,
license_type,
modified,
network_access_control,
notification_destinations,
organization_role_name,
organizational_units,
permission_type,
stack_set_name,
status,
tags,
vpc_configuration,
workspace_role_arn
FROM aws.grafana.workspaces
WHERE workspace_id = '{{ workspace_id }}' -- required
AND region = '{{ region }}' -- required
;

list_workspaces

Returns a list of Amazon Managed Grafana workspaces in the account, with some information about each workspace. For more complete information about one workspace, use DescribeWorkspace.

SELECT
id,
name,
authentication,
created,
description,
endpoint,
grafana_token,
grafana_version,
license_type,
modified,
notification_destinations,
status,
tags
FROM aws.grafana.workspaces
WHERE region = '{{ region }}' -- required
AND maxResults = '{{ maxResults }}'
AND nextToken = '{{ nextToken }}'
;

INSERT examples

create_workspace_api_key

Creates a Grafana API key for the workspace. This key can be used to authenticate requests sent to the workspace's HTTP API. See https://docs.aws.amazon.com/grafana/latest/userguide/Using-Grafana-APIs.html for available APIs and example requests. In workspaces compatible with Grafana version 9 or above, use workspace service accounts instead of API keys. API keys will be removed in a future release.

INSERT INTO aws.grafana.workspaces (
keyName,
keyRole,
secondsToLive,
workspace_id,
region
)
SELECT 
'{{ keyName }}' /* required */,
'{{ keyRole }}' /* required */,
{{ secondsToLive }} /* required */,
'{{ workspace_id }}',
'{{ region }}'
RETURNING
key,
key_name,
workspace_id
;

create_workspace

Creates a workspace. In a workspace, you can create Grafana dashboards and visualizations to analyze your metrics, logs, and traces. You don't have to build, package, or deploy any hardware to run the Grafana server. Don't use CreateWorkspace to modify an existing workspace. Instead, use UpdateWorkspace.

INSERT INTO aws.grafana.workspaces (
accountAccessType,
clientToken,
organizationRoleName,
permissionType,
stackSetName,
workspaceDataSources,
workspaceDescription,
workspaceName,
workspaceNotificationDestinations,
workspaceOrganizationalUnits,
workspaceRoleArn,
authenticationProviders,
tags,
vpcConfiguration,
configuration,
networkAccessControl,
grafanaVersion,
ipAddressType,
kmsKeyId,
region
)
SELECT 
'{{ accountAccessType }}' /* required */,
'{{ clientToken }}',
'{{ organizationRoleName }}',
'{{ permissionType }}' /* required */,
'{{ stackSetName }}',
'{{ workspaceDataSources }}',
'{{ workspaceDescription }}',
'{{ workspaceName }}',
'{{ workspaceNotificationDestinations }}',
'{{ workspaceOrganizationalUnits }}',
'{{ workspaceRoleArn }}',
'{{ authenticationProviders }}' /* required */,
'{{ tags }}',
'{{ vpcConfiguration }}',
'{{ configuration }}',
'{{ networkAccessControl }}',
'{{ grafanaVersion }}',
'{{ ipAddressType }}',
'{{ kmsKeyId }}',
'{{ region }}'
RETURNING
workspace
;

Manifest

# Description fields are for documentation purposes
- name: workspaces
props:
  - name: workspace_id
    value: "{{ workspace_id }}"
    description: Required parameter for the workspaces resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the workspaces resource.
  - name: keyName
    value: "{{ keyName }}"
  - name: keyRole
    value: "{{ keyRole }}"
  - name: secondsToLive
    value: {{ secondsToLive }}
  - name: accountAccessType
    value: "{{ accountAccessType }}"
    valid_values: ['CURRENT_ACCOUNT', 'ORGANIZATION']
  - name: clientToken
    value: "{{ clientToken }}"
  - name: organizationRoleName
    value: "{{ organizationRoleName }}"
  - name: permissionType
    value: "{{ permissionType }}"
    valid_values: ['CUSTOMER_MANAGED', 'SERVICE_MANAGED']
  - name: stackSetName
    value: "{{ stackSetName }}"
  - name: workspaceDataSources
    value:
      - "{{ workspaceDataSources }}"
  - name: workspaceDescription
    value: "{{ workspaceDescription }}"
  - name: workspaceName
    value: "{{ workspaceName }}"
  - name: workspaceNotificationDestinations
    value:
      - "{{ workspaceNotificationDestinations }}"
  - name: workspaceOrganizationalUnits
    value:
      - "{{ workspaceOrganizationalUnits }}"
  - name: workspaceRoleArn
    value: "{{ workspaceRoleArn }}"
  - name: authenticationProviders
    value:
      - "{{ authenticationProviders }}"
  - name: tags
    value: "{{ tags }}"
  - name: vpcConfiguration
    description: |
      The configuration settings for an Amazon VPC that contains data sources for your Grafana workspace to connect to. Provided securityGroupIds and subnetIds must be part of the same VPC. Connecting to a private VPC is not yet available in the Asia Pacific (Seoul) Region (ap-northeast-2).
    value:
      securityGroupIds:
        - "{{ securityGroupIds }}"
      subnetIds:
        - "{{ subnetIds }}"
  - name: configuration
    value: "{{ configuration }}"
  - name: networkAccessControl
    description: |
      The configuration settings for in-bound network access to your workspace. When this is configured, only listed IP addresses and VPC endpoints will be able to access your workspace. Standard Grafana authentication and authorization are still required. Access is granted to a caller that is in either the IP address list or the VPC endpoint list - they do not need to be in both. If this is not configured, or is removed, then all IP addresses and VPC endpoints are allowed. Standard Grafana authentication and authorization are still required. While both prefixListIds and vpceIds are required, you can pass in an empty array of strings for either parameter if you do not want to allow any of that type. If both are passed as empty arrays, no traffic is allowed to the workspace, because only explicitly allowed connections are accepted.
    value:
      prefixListIds:
        - "{{ prefixListIds }}"
      vpceIds:
        - "{{ vpceIds }}"
  - name: grafanaVersion
    value: "{{ grafanaVersion }}"
  - name: ipAddressType
    value: "{{ ipAddressType }}"
    valid_values: ['IPv4', 'DualStack']
  - name: kmsKeyId
    value: "{{ kmsKeyId }}"

UPDATE examples

associate_license

Assigns a Grafana Enterprise license to a workspace. To upgrade, you must use ENTERPRISE for the licenseType, and pass in a valid Grafana Labs token for the grafanaToken. Upgrading to Grafana Enterprise incurs additional fees. For more information, see Upgrade a workspace to Grafana Enterprise.

UPDATE aws.grafana.workspaces
SET 
-- No updatable properties
WHERE 
workspace_id = '{{ workspace_id }}' --required
AND license_type = '{{ license_type }}' --required
AND region = '{{ region }}' --required
AND `Grafana-Token` = '{{ Grafana-Token}}'
RETURNING
workspace;

update_workspace

Modifies an existing Amazon Managed Grafana workspace. If you use this operation and omit any optional parameters, the existing values of those parameters are not changed. To modify the user authentication methods that the workspace uses, such as SAML or IAM Identity Center, use UpdateWorkspaceAuthentication. To modify which users in the workspace have the Admin and Editor Grafana roles, use UpdatePermissions.

UPDATE aws.grafana.workspaces
SET 
accountAccessType = '{{ accountAccessType }}',
organizationRoleName = '{{ organizationRoleName }}',
permissionType = '{{ permissionType }}',
stackSetName = '{{ stackSetName }}',
workspaceDataSources = '{{ workspaceDataSources }}',
workspaceDescription = '{{ workspaceDescription }}',
workspaceName = '{{ workspaceName }}',
workspaceNotificationDestinations = '{{ workspaceNotificationDestinations }}',
workspaceOrganizationalUnits = '{{ workspaceOrganizationalUnits }}',
workspaceRoleArn = '{{ workspaceRoleArn }}',
vpcConfiguration = '{{ vpcConfiguration }}',
removeVpcConfiguration = {{ removeVpcConfiguration }},
networkAccessControl = '{{ networkAccessControl }}',
removeNetworkAccessConfiguration = {{ removeNetworkAccessConfiguration }},
ipAddressType = '{{ ipAddressType }}'
WHERE 
workspace_id = '{{ workspace_id }}' --required
AND region = '{{ region }}' --required
RETURNING
workspace;

DELETE examples

delete_workspace_api_key

Deletes a Grafana API key for the workspace. In workspaces compatible with Grafana version 9 or above, use workspace service accounts instead of API keys. API keys will be removed in a future release.

DELETE FROM aws.grafana.workspaces
WHERE key_name = '{{ key_name }}' --required
AND workspace_id = '{{ workspace_id }}' --required
AND region = '{{ region }}' --required
;

delete_workspace

Deletes an Amazon Managed Grafana workspace.

DELETE FROM aws.grafana.workspaces
WHERE workspace_id = '{{ workspace_id }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

disassociate_license

Removes the Grafana Enterprise license from a workspace.

EXEC aws.grafana.workspaces.disassociate_license 
@workspace_id='{{ workspace_id }}' --required, 
@license_type='{{ license_type }}' --required, 
@region='{{ region }}' --required
;