@robhan-cdk-lib/aws_grafana 0.0.0

package/lib/workspace.d.ts

@@ -0,0 +1,624 @@
+import { IPrefixList, ISecurityGroup, ISubnet, IVpcEndpoint } from 'aws-cdk-lib/aws-ec2';
+import { IRole } from 'aws-cdk-lib/aws-iam';
+import { Construct } from 'constructs';
+/**
+ * Specifies whether the workspace can access AWS resources in this AWS account only, or whether it
+ * can also access AWS resources in other accounts in the same organization. If this is
+ * ORGANIZATION, the OrganizationalUnits parameter specifies which organizational units the
+ * workspace can access.
+ */
+export declare enum AccountAccessType {
+    /**
+     * Access is limited to the current AWS account only.
+     */
+    CURRENT_ACCOUNT = "CURRENT_ACCOUNT",
+    /**
+     * Access is extended to the entire AWS organization.
+     */
+    ORGANIZATION = "ORGANIZATION"
+}
+/**
+ * Specifies whether this workspace uses SAML 2.0, AWS IAM Identity Center, or both to authenticate
+ * users for using the Grafana console within a workspace.
+ *
+ * @see https://docs.aws.amazon.com/grafana/latest/APIReference/API_CreateWorkspace.html
+ */
+export declare enum AuthenticationProviders {
+    /**
+     * AWS Single Sign-On authentication provider.
+     */
+    AWS_SSO = "AWS_SSO",
+    /**
+     * Security Assertion Markup Language (SAML) authentication provider.
+     */
+    SAML = "SAML"
+}
+/**
+ * The configuration settings for network access to your workspace.
+ */
+export interface NetworkAccessControl {
+    /**
+     * An array of prefix list IDs. A prefix list is a list of CIDR ranges of IP addresses. The IP
+     * addresses specified are allowed to access your workspace. If the list is not included in the
+     * configuration (passed an empty array) then no IP addresses are allowed to access the
+     * workspace.
+     *
+     * Maximum of 5 prefix lists allowed.
+     */
+    readonly prefixLists?: IPrefixList[];
+    /**
+     * An array of Amazon VPC endpoint IDs for the workspace. You can create VPC endpoints to your
+     * Amazon Managed Grafana workspace for access from within a VPC. If a NetworkAccessConfiguration
+     * is specified then only VPC endpoints specified here are allowed to access the workspace. If
+     * you pass in an empty array of strings, then no VPCs are allowed to access the workspace.
+     *
+     * Maximum of 5 VPC endpoints allowed.
+     */
+    readonly vpcEndpoints?: IVpcEndpoint[];
+}
+/**
+ * The AWS notification channels that Amazon Managed Grafana can automatically create IAM roles and
+ * permissions for, to allow Amazon Managed Grafana to use these channels.
+ */
+export declare enum NotificationDestinations {
+    /**
+     * Amazon Simple Notification Service (SNS) as notification destination.
+     */
+    SNS = "SNS"
+}
+/**
+ * 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 AWS 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 AWS accounts in the organization, this parameter must be set to CUSTOMER_MANAGED.
+ */
+export declare enum PermissionTypes {
+    /**
+     * Customer-managed permissions where you manage user access to Grafana.
+     */
+    CUSTOMER_MANAGED = "CUSTOMER_MANAGED",
+    /**
+     * Service-managed permissions where AWS manages user access to Grafana.
+     */
+    SERVICE_MANAGED = "SERVICE_MANAGED"
+}
+/**
+ * A structure that defines which attributes in the IdP assertion are to be used to define
+ * information about the users authenticated by the IdP to use the workspace.
+ *
+ * Each attribute must be a string with length between 1 and 256 characters.
+ */
+export interface SamlAssertionAttributes {
+    /**
+     * The name of the attribute within the SAML assertion to use as the email names for SAML users.
+     *
+     * Must be between 1 and 256 characters long.
+     */
+    readonly email: string;
+    /**
+     * The name of the attribute within the SAML assertion to use as the user full "friendly" names
+     * for user groups.
+     *
+     * Must be between 1 and 256 characters long.
+     */
+    readonly groups: string;
+    /**
+     * The name of the attribute within the SAML assertion to use as the login names for SAML users.
+     *
+     * Must be between 1 and 256 characters long.
+     */
+    readonly login: string;
+    /**
+     * The name of the attribute within the SAML assertion to use as the user full "friendly" names
+     * for SAML users.
+     *
+     * Must be between 1 and 256 characters long.
+     */
+    readonly name: string;
+    /**
+     * The name of the attribute within the SAML assertion to use as the user full "friendly" names
+     * for the users' organizations.
+     *
+     * Must be between 1 and 256 characters long.
+     */
+    readonly org: string;
+    /**
+     * The name of the attribute within the SAML assertion to use as the user roles.
+     *
+     * Must be between 1 and 256 characters long.
+     */
+    readonly role: string;
+}
+/**
+ * A structure containing the identity provider (IdP) metadata used to integrate the identity
+ * provider with this workspace.
+ */
+export interface SamlIdpMetadata {
+    /**
+     * The URL of the location containing the IdP metadata.
+     *
+     * Must be a string with length between 1 and 2048 characters.
+     */
+    readonly url?: string;
+    /**
+     * The full IdP metadata, in XML format.
+     */
+    readonly xml?: string;
+}
+/**
+ * A structure containing arrays that map group names in the SAML assertion to the Grafana Admin
+ * and Editor roles in the workspace.
+ */
+export interface SamlRoleValues {
+    /**
+     * A list of groups from the SAML assertion attribute to grant the Grafana Admin role to.
+     *
+     * Maximum of 256 elements.
+     */
+    readonly admin?: string[];
+    /**
+     * A list of groups from the SAML assertion attribute to grant the Grafana Editor role to.
+     *
+     * Maximum of 256 elements.
+     */
+    readonly editor?: string[];
+}
+/**
+ * If the workspace uses SAML, use this structure to map SAML assertion attributes to workspace
+ * user information and define which groups in the assertion attribute are to have the Admin and
+ * Editor roles in the workspace.
+ */
+export interface SamlConfiguration {
+    /**
+     * Lists which organizations defined in the SAML assertion are allowed to use the Amazon Managed
+     * Grafana workspace. If this is empty, all organizations in the assertion attribute have access.
+     *
+     * Must have between 1 and 256 elements.
+     */
+    readonly allowedOrganizations?: string[];
+    /**
+     * A structure that defines which attributes in the SAML assertion are to be used to define
+     * information about the users authenticated by that IdP to use the workspace.
+     */
+    readonly assertionAtrributes?: SamlAssertionAttributes;
+    /**
+     * A structure containing the identity provider (IdP) metadata used to integrate the identity
+     * provider with this workspace.
+     *
+     * Required field for SAML configuration.
+     */
+    readonly idpMetadata: SamlIdpMetadata;
+    /**
+     * How long a sign-on session by a SAML user is valid, before the user has to sign on again.
+     *
+     * Must be a positive number.
+     */
+    readonly loginValidityDuration?: number;
+    /**
+     * A structure containing arrays that map group names in the SAML assertion to the Grafana Admin
+     * and Editor roles in the workspace.
+     */
+    readonly roleValues?: SamlRoleValues;
+}
+/**
+ * The configuration settings for an Amazon VPC that contains data sources for your Grafana
+ * workspace to connect to.
+ */
+export interface VpcConfiguration {
+    /**
+     * The list of Amazon EC2 security groups attached to the Amazon VPC for your Grafana
+     * workspace to connect. Duplicates not allowed.
+     *
+     * Array Members: Minimum number of 1 items. Maximum number of 5 items.
+     *
+     * Required for VPC configuration.
+     */
+    readonly securityGroups: ISecurityGroup[];
+    /**
+     * The list of Amazon EC2 subnets created in the Amazon VPC for your Grafana workspace to
+     * connect. Duplicates not allowed.
+     *
+     * Array Members: Minimum number of 2 items. Maximum number of 6 items.
+     *
+     * Required for VPC configuration.
+     */
+    readonly subnets: ISubnet[];
+}
+/**
+ * Properties for creating an Amazon Managed Grafana workspace.
+ */
+export interface WorkspaceProps {
+    /**
+     * Type of account access for the workspace.
+     * Required field.
+     */
+    readonly accountAccessType: AccountAccessType;
+    /**
+     * Authentication providers to enable for the workspace.
+     * Required field.
+     */
+    readonly authenticationProviders: AuthenticationProviders[];
+    /**
+     * Client token for idempotent workspace creation.
+     * Must be 1-64 characters long and contain only printable ASCII characters.
+     */
+    readonly clientToken?: string;
+    /**
+     * List of data sources to enable for the workspace.
+     */
+    readonly dataSources?: string[];
+    /**
+     * Description of the workspace.
+     * Maximum length of 2048 characters.
+     */
+    readonly description?: string;
+    /**
+     * Grafana version for the workspace.
+     * Must be 1-255 characters long.
+     */
+    readonly grafanaVersion?: string;
+    /**
+     * Name of the workspace.
+     * Must be 1-255 characters long and contain only alphanumeric characters, hyphens, dots, underscores, and tildes.
+     */
+    readonly name?: string;
+    /**
+     * Network access control configuration for the workspace.
+     */
+    readonly networkAccessControl?: NetworkAccessControl;
+    /**
+     * Notification destinations to enable for the workspace.
+     */
+    readonly notificationDestinations?: NotificationDestinations[];
+    /**
+     * List of organizational units to include in the workspace.
+     */
+    readonly organizationalUnits?: string[];
+    /**
+     * Name of the IAM role to use for the organization.
+     * Maximum length of 2048 characters.
+     */
+    readonly organizationRoleName?: string;
+    /**
+     * Permission type for the workspace.
+     * Required field.
+     */
+    readonly permissionType: PermissionTypes;
+    /**
+     * Whether to enable the Grafana plugin admin page.
+     * Default: false
+     */
+    readonly pluginAdminEnabled?: boolean;
+    /**
+     * IAM role to use for the workspace.
+     */
+    readonly role?: IRole;
+    /**
+     * SAML configuration for the workspace.
+     */
+    readonly samlConfiguration?: SamlConfiguration;
+    /**
+     * Name of the CloudFormation stack set to use.
+     */
+    readonly stackSetName?: string;
+    /**
+     * VPC configuration for the workspace.
+     */
+    readonly vpcConfiguration?: VpcConfiguration;
+}
+/**
+ * Status of SAML configuration for a Grafana workspace.
+ */
+export declare enum SamlConfigurationStatuses {
+    /**
+     * SAML is configured for the workspace.
+     */
+    CONFIGURED = "CONFIGURED",
+    /**
+     * SAML is not configured for the workspace.
+     */
+    NOT_CONFIGURED = "NOT_CONFIGURED"
+}
+/**
+ * Status of a Grafana workspace.
+ */
+export declare enum Status {
+    /**
+     * Workspace is active and ready to use.
+     */
+    ACTIVE = "ACTIVE",
+    /**
+     * Workspace is being created.
+     */
+    CREATING = "CREATING",
+    /**
+     * Workspace is being deleted.
+     */
+    DELETING = "DELETING",
+    /**
+     * Workspace operation has failed.
+     */
+    FAILED = "FAILED",
+    /**
+     * Workspace is being updated.
+     */
+    UPDATING = "UPDATING",
+    /**
+     * Workspace is being upgraded.
+     */
+    UPGRADING = "UPGRADING",
+    /**
+     * Workspace deletion has failed.
+     */
+    DELETION_FAILED = "DELETION_FAILED",
+    /**
+     * Workspace creation has failed.
+     */
+    CREATION_FAILED = "CREATION_FAILED",
+    /**
+     * Workspace update has failed.
+     */
+    UPDATE_FAILED = "UPDATE_FAILED",
+    /**
+     * Workspace upgrade has failed.
+     */
+    UPGRADE_FAILED = "UPGRADE_FAILED",
+    /**
+     * License removal has failed.
+     */
+    LICENSE_REMOVAL_FAILED = "LICENSE_REMOVAL_FAILED"
+}
+/**
+ * Represents an Amazon Managed Grafana workspace.
+ *
+ * This class provides a high-level abstraction for creating and managing
+ * Amazon Managed Grafana workspaces using AWS CDK.
+ */
+export declare class Workspace extends Construct {
+    /**
+     * Validates the clientToken property.
+     *
+     * @param token - The client token to validate
+     * @returns An array of error messages if validation fails, or an empty array if valid
+     *
+     * Validation rules:
+     * - Must be a string
+     * - Must be between 1 and 64 characters long
+     * - Must contain only printable ASCII characters
+     */
+    private static validateClientToken;
+    /**
+     * Validates the description property.
+     *
+     * @param description - The description to validate
+     * @returns An array of error messages if validation fails, or an empty array if valid
+     *
+     * Validation rules:
+     * - Must be a string
+     * - Maximum length of 2048 characters
+     */
+    private static validateDescription;
+    /**
+     * Validates the grafanaVersion property.
+     *
+     * @param version - The Grafana version to validate
+     * @returns An array of error messages if validation fails, or an empty array if valid
+     *
+     * Validation rules:
+     * - Must be a string
+     * - Must be between 1 and 255 characters long
+     */
+    private static validateGrafanaVersion;
+    /**
+     * Validates the name property.
+     *
+     * @param name - The workspace name to validate
+     * @returns An array of error messages if validation fails, or an empty array if valid
+     *
+     * Validation rules:
+     * - Must be a string
+     * - Must be between 1 and 255 characters long
+     * - Can only contain alphanumeric characters, hyphens, dots, underscores, and tildes
+     */
+    private static validateName;
+    /**
+     * Validates the networkAccessControl property.
+     *
+     * @param nac - The network access control configuration to validate
+     * @returns An array of error messages if validation fails, or an empty array if valid
+     *
+     * Validation rules:
+     * - Must be an object
+     * - prefixLists (if present) must be an array with at most 5 items
+     * - vpcEndpoints (if present) must be an array with at most 5 items
+     */
+    private static validateNetworkAccessControl;
+    /**
+     * Validates the organizationRoleName property.
+     *
+     * @param roleName - The organization role name to validate
+     * @returns An array of error messages if validation fails, or an empty array if valid
+     *
+     * Validation rules:
+     * - Must be a string
+     * - Must be between 1 and 2048 characters long
+     */
+    private static validateOrganizationRoleName;
+    /**
+     * Validates the SAML assertion attributes.
+     *
+     * @param obj - The SAML assertion attributes to validate
+     * @returns An array of error messages if validation fails, or an empty array if valid
+     *
+     * Validation rules:
+     * - Must be an object
+     * - Each attribute must be a string
+     * - Each attribute must be between 1 and 256 characters long
+     * - Valid attribute keys are: 'email', 'groups', 'login', 'name', 'org', 'role'
+     */
+    private static validateSamlAssertionAttributes;
+    /**
+     * Validates the SAML IdP metadata.
+     *
+     * @param obj - The SAML IdP metadata to validate
+     * @returns An array of error messages if validation fails, or an empty array if valid
+     *
+     * Validation rules:
+     * - Must be an object
+     * - url (if present) must be a string between 1 and 2048 characters long
+     * - xml (if present) must be a string
+     */
+    private static validateSamlIdpMetadata;
+    /**
+     * Validates the SAML configuration.
+     *
+     * @param config - The SAML configuration to validate
+     * @returns An array of error messages if validation fails, or an empty array if valid
+     *
+     * Validation rules:
+     * - Must be an object
+     * - idpMetadata is required and must be valid
+     * - assertionAtrributes (if present) must be valid
+     * - allowedOrganizations (if present) must be an array of strings with 1-256 elements
+     * - loginValidityDuration (if present) must be a positive number
+     * - roleValues (if present) must be an object with valid admin and editor arrays
+     */
+    private static validateSamlConfiguration;
+    /**
+     * Validates the vpcConfiguration property.
+     *
+     * @param config - The VPC configuration to validate
+     * @returns An array of error messages if validation fails, or an empty array if valid
+     *
+     * Validation rules:
+     * - Must be an object
+     * - securityGroups is required and must be an array with 1-5 items
+     * - subnets is required and must be an array with 2-6 items
+     */
+    private static validateVpcConfiguration;
+    /**
+     * Validates all workspace properties.
+     *
+     * @param props - The workspace properties to validate
+     * @returns An array of error messages if validation fails, or an empty array if valid
+     *
+     * This method aggregates validation results from all individual property validators.
+     * It throws an error if props is not an object.
+     */
+    private static validateProps;
+    /**
+     * The type of account access for the workspace.
+     */
+    readonly accountAccessType: AccountAccessType;
+    /**
+     * Authentication providers enabled for the workspace.
+     */
+    readonly authenticationProviders: AuthenticationProviders[];
+    /**
+     * Client token used for idempotent workspace creation.
+     */
+    readonly clientToken?: string;
+    /**
+     * Data sources enabled for the workspace.
+     */
+    readonly dataSources?: string[];
+    /**
+     * Description of the workspace.
+     */
+    readonly description?: string;
+    /**
+     * Name of the workspace.
+     */
+    readonly name?: string;
+    /**
+     * Network access control configuration for the workspace.
+     */
+    readonly networkAccessControl?: NetworkAccessControl;
+    /**
+     * Notification destinations enabled for the workspace.
+     */
+    readonly notificationDestinations?: NotificationDestinations[];
+    /**
+     * Organizational units included in the workspace.
+     */
+    readonly organizationalUnits?: string[];
+    /**
+     * Name of the IAM role used for the organization.
+     */
+    readonly organizationRoleName?: string;
+    /**
+     * Permission type for the workspace.
+     */
+    readonly permissionType: PermissionTypes;
+    /**
+     * Whether the Grafana plugin admin page is enabled.
+     */
+    readonly pluginAdminEnabled?: boolean;
+    /**
+     * IAM role used for the workspace.
+     */
+    readonly role?: IRole;
+    /**
+     * SAML configuration for the workspace.
+     */
+    readonly samlConfiguration?: SamlConfiguration;
+    /**
+     * Name of the CloudFormation stack set used.
+     */
+    readonly stackSetName?: string;
+    /**
+     * VPC configuration for the workspace.
+     */
+    readonly vpcConfiguration?: VpcConfiguration;
+    /**
+     * The underlying CloudFormation resource.
+     */
+    private readonly workspace;
+    /**
+     * Timestamp when the workspace was created.
+     */
+    readonly creationTimestamp: string;
+    /**
+     * Endpoint URL for the Grafana workspace.
+     */
+    readonly endpoint: string;
+    /**
+     * Grafana version running in the workspace.
+     */
+    readonly grafanaVersion: string;
+    /**
+     * Unique identifier for the workspace.
+     */
+    readonly id: string;
+    /**
+     * Timestamp when the workspace was last modified.
+     */
+    readonly modificationTimestamp: string;
+    /**
+     * Status of SAML configuration for the workspace.
+     */
+    readonly samlConfigurationStatus: SamlConfigurationStatuses;
+    /**
+     * SSO client ID for the workspace.
+     */
+    readonly ssoClientId: string;
+    /**
+     * Current status of the workspace.
+     */
+    readonly status: Status;
+    /**
+     * Creates a new Amazon Managed Grafana workspace.
+     *
+     * @param scope - The scope in which to define this construct
+     * @param id - The scoped construct ID
+     * @param props - Configuration properties for the workspace
+     *
+     * @throws Error if any of the provided properties fail validation
+     */
+    constructor(scope: Construct, id: string, props: WorkspaceProps);
+}