Package software.amazon.awscdk.services.redshift
Amazon Redshift Construct Library
---
All classes with the
Cfn
prefix in this module (CFN Resources) are always stable and safe to use.
The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the Semantic Versioning model and breaking changes will be announced in the release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.
Starting a Redshift Cluster Database
To set up a Redshift cluster, define a Cluster
. It will be launched in a VPC.
You can specify a VPC, otherwise one will be created. The nodes are always launched in private subnets and are encrypted by default.
import software.amazon.awscdk.services.ec2.*; Vpc vpc = new Vpc(this, "Vpc"); Cluster cluster = Cluster.Builder.create(this, "Redshift") .masterUser(Login.builder() .masterUsername("admin") .build()) .vpc(vpc) .build();
By default, the master password will be generated and stored in AWS Secrets Manager.
A default database named default_db
will be created in the cluster. To change the name of this database set the defaultDatabaseName
attribute in the constructor properties.
By default, the cluster will not be publicly accessible.
Depending on your use case, you can make the cluster publicly accessible with the publiclyAccessible
property.
Connecting
To control who can access the cluster, use the .connections
attribute. Redshift Clusters have
a default port, so you don't need to specify the port:
cluster.connections.allowDefaultPortFromAnyIpv4("Open to the world");
The endpoint to access your database cluster will be available as the .clusterEndpoint
attribute:
cluster.getClusterEndpoint().getSocketAddress();
Database Resources
This module allows for the creation of non-CloudFormation database resources such as users and tables. This allows you to manage identities, permissions, and stateful resources within your Redshift cluster from your CDK application.
Because these resources are not available in CloudFormation, this library leverages custom resources to manage them. In addition to the IAM permissions required to make Redshift service calls, the execution role for the custom resource handler requires database credentials to create resources within the cluster.
These database credentials can be supplied explicitly through the adminUser
properties
of the various database resource constructs. Alternatively, the credentials can be
automatically pulled from the Redshift cluster's default administrator
credentials. However, this option is only available if the password for the credentials
was generated by the CDK application (ie., no value vas provided for the masterPassword
property
of
Cluster.masterUser
).
Creating Users
Create a user within a Redshift cluster database by instantiating a User
construct. This
will generate a username and password, store the credentials in a AWS Secrets Manager
Secret
,
and make a query to the Redshift cluster to create a new database user with the
credentials.
User.Builder.create(this, "User") .cluster(cluster) .databaseName("databaseName") .build();
By default, the user credentials are encrypted with your AWS account's default Secrets
Manager encryption key. You can specify the encryption key used for this purpose by
supplying a key in the encryptionKey
property.
import software.amazon.awscdk.services.kms.*; Key encryptionKey = new Key(this, "Key"); User.Builder.create(this, "User") .encryptionKey(encryptionKey) .cluster(cluster) .databaseName("databaseName") .build();
By default, a username is automatically generated from the user construct ID and its path
in the construct tree. You can specify a particular username by providing a value for the
username
property. Usernames must be valid identifiers; see: Names and
identifiers in the Amazon
Redshift Database Developer Guide.
User.Builder.create(this, "User") .username("myuser") .cluster(cluster) .databaseName("databaseName") .build();
The user password is generated by AWS Secrets Manager using the default configuration
found in
secretsmanager.SecretStringGenerator
,
except with password length 30
and some SQL-incompliant characters excluded. The
plaintext for the password will never be present in the CDK application; instead, a
CloudFormation Dynamic
Reference
will be used wherever the password value is required.
Creating Tables
Create a table within a Redshift cluster database by instantiating a Table
construct. This will make a query to the Redshift cluster to create a new database table
with the supplied schema.
Table.Builder.create(this, "Table") .tableColumns(List.of(Column.builder().name("col1").dataType("varchar(4)").build(), Column.builder().name("col2").dataType("float").build())) .cluster(cluster) .databaseName("databaseName") .build();
The table can be configured to have distStyle attribute and a distKey column:
Table.Builder.create(this, "Table") .tableColumns(List.of(Column.builder().name("col1").dataType("varchar(4)").distKey(true).build(), Column.builder().name("col2").dataType("float").build())) .cluster(cluster) .databaseName("databaseName") .distStyle(TableDistStyle.KEY) .build();
The table can also be configured to have sortStyle attribute and sortKey columns:
Table.Builder.create(this, "Table") .tableColumns(List.of(Column.builder().name("col1").dataType("varchar(4)").sortKey(true).build(), Column.builder().name("col2").dataType("float").sortKey(true).build())) .cluster(cluster) .databaseName("databaseName") .sortStyle(TableSortStyle.COMPOUND) .build();
Granting Privileges
You can give a user privileges to perform certain actions on a table by using the
Table.grant()
method.
User user = User.Builder.create(this, "User") .cluster(cluster) .databaseName("databaseName") .build(); Table table = Table.Builder.create(this, "Table") .tableColumns(List.of(Column.builder().name("col1").dataType("varchar(4)").build(), Column.builder().name("col2").dataType("float").build())) .cluster(cluster) .databaseName("databaseName") .build(); table.grant(user, TableAction.DROP, TableAction.SELECT);
Take care when managing privileges via the CDK, as attempting to manage a user's
privileges on the same table in multiple CDK applications could lead to accidentally
overriding these permissions. Consider the following two CDK applications which both refer
to the same user and table. In application 1, the resources are created and the user is
given INSERT
permissions on the table:
String databaseName = "databaseName"; String username = "myuser"; String tableName = "mytable"; User user = User.Builder.create(this, "User") .username(username) .cluster(cluster) .databaseName(databaseName) .build(); Table table = Table.Builder.create(this, "Table") .tableColumns(List.of(Column.builder().name("col1").dataType("varchar(4)").build(), Column.builder().name("col2").dataType("float").build())) .cluster(cluster) .databaseName(databaseName) .build(); table.grant(user, TableAction.INSERT);
In application 2, the resources are imported and the user is given INSERT
permissions on
the table:
String databaseName = "databaseName"; String username = "myuser"; String tableName = "mytable"; IUser user = User.fromUserAttributes(this, "User", UserAttributes.builder() .username(username) .password(SecretValue.unsafePlainText("NOT_FOR_PRODUCTION")) .cluster(cluster) .databaseName(databaseName) .build()); ITable table = Table.fromTableAttributes(this, "Table", TableAttributes.builder() .tableName(tableName) .tableColumns(List.of(Column.builder().name("col1").dataType("varchar(4)").build(), Column.builder().name("col2").dataType("float").build())) .cluster(cluster) .databaseName("databaseName") .build()); table.grant(user, TableAction.INSERT);
Both applications attempt to grant the user the appropriate privilege on the table by
submitting a GRANT USER
SQL query to the Redshift cluster. Note that the latter of these
two calls will have no effect since the user has already been granted the privilege.
Now, if application 1 were to remove the call to grant
, a REVOKE USER
SQL query is
submitted to the Redshift cluster. In general, application 1 does not know that
application 2 has also granted this permission and thus cannot decide not to issue the
revocation. This leads to the undesirable state where application 2 still contains the
call to grant
but the user does not have the specified permission.
Note that this does not occur when duplicate privileges are granted within the same application, as such privileges are de-duplicated before any SQL query is submitted.
Rotating credentials
When the master password is generated and stored in AWS Secrets Manager, it can be rotated automatically:
cluster.addRotationSingleUser();
The multi user rotation scheme is also available:
User user = User.Builder.create(this, "User") .cluster(cluster) .databaseName("databaseName") .build(); cluster.addRotationMultiUser("MultiUserRotation", RotationMultiUserOptions.builder() .secret(user.getSecret()) .build());
-
ClassDescriptionA CloudFormation `AWS::Redshift::Cluster`.A fluent builder for
CfnCluster
.Describes a connection endpoint.A builder forCfnCluster.EndpointProperty
An implementation forCfnCluster.EndpointProperty
Specifies logging information, such as queries and connection attempts, for the specified Amazon Redshift cluster.A builder forCfnCluster.LoggingPropertiesProperty
An implementation forCfnCluster.LoggingPropertiesProperty
A CloudFormation `AWS::Redshift::ClusterParameterGroup`.A fluent builder forCfnClusterParameterGroup
.Describes a parameter in a cluster parameter group.A builder forCfnClusterParameterGroup.ParameterProperty
An implementation forCfnClusterParameterGroup.ParameterProperty
Properties for defining a `CfnClusterParameterGroup`.A builder forCfnClusterParameterGroupProps
An implementation forCfnClusterParameterGroupProps
Properties for defining a `CfnCluster`.A builder forCfnClusterProps
An implementation forCfnClusterProps
A CloudFormation `AWS::Redshift::ClusterSecurityGroup`.A fluent builder forCfnClusterSecurityGroup
.A CloudFormation `AWS::Redshift::ClusterSecurityGroupIngress`.A fluent builder forCfnClusterSecurityGroupIngress
.Properties for defining a `CfnClusterSecurityGroupIngress`.A builder forCfnClusterSecurityGroupIngressProps
An implementation forCfnClusterSecurityGroupIngressProps
Properties for defining a `CfnClusterSecurityGroup`.A builder forCfnClusterSecurityGroupProps
An implementation forCfnClusterSecurityGroupProps
A CloudFormation `AWS::Redshift::ClusterSubnetGroup`.A fluent builder forCfnClusterSubnetGroup
.Properties for defining a `CfnClusterSubnetGroup`.A builder forCfnClusterSubnetGroupProps
An implementation forCfnClusterSubnetGroupProps
A CloudFormation `AWS::Redshift::EndpointAccess`.A fluent builder forCfnEndpointAccess
.Describes a network interface.A builder forCfnEndpointAccess.NetworkInterfaceProperty
An implementation forCfnEndpointAccess.NetworkInterfaceProperty
The connection endpoint for connecting to an Amazon Redshift cluster through the proxy.A builder forCfnEndpointAccess.VpcEndpointProperty
An implementation forCfnEndpointAccess.VpcEndpointProperty
The security groups associated with the endpoint.A builder forCfnEndpointAccess.VpcSecurityGroupProperty
An implementation forCfnEndpointAccess.VpcSecurityGroupProperty
Properties for defining a `CfnEndpointAccess`.A builder forCfnEndpointAccessProps
An implementation forCfnEndpointAccessProps
A CloudFormation `AWS::Redshift::EndpointAuthorization`.A fluent builder forCfnEndpointAuthorization
.Properties for defining a `CfnEndpointAuthorization`.A builder forCfnEndpointAuthorizationProps
An implementation forCfnEndpointAuthorizationProps
A CloudFormation `AWS::Redshift::EventSubscription`.A fluent builder forCfnEventSubscription
.Properties for defining a `CfnEventSubscription`.A builder forCfnEventSubscriptionProps
An implementation forCfnEventSubscriptionProps
A CloudFormation `AWS::Redshift::ScheduledAction`.A fluent builder forCfnScheduledAction
.Describes a pause cluster operation.A builder forCfnScheduledAction.PauseClusterMessageProperty
An implementation forCfnScheduledAction.PauseClusterMessageProperty
Describes a resize cluster operation.A builder forCfnScheduledAction.ResizeClusterMessageProperty
An implementation forCfnScheduledAction.ResizeClusterMessageProperty
Describes a resume cluster operation.A builder forCfnScheduledAction.ResumeClusterMessageProperty
An implementation forCfnScheduledAction.ResumeClusterMessageProperty
The action type that specifies an Amazon Redshift API operation that is supported by the Amazon Redshift scheduler.A builder forCfnScheduledAction.ScheduledActionTypeProperty
An implementation forCfnScheduledAction.ScheduledActionTypeProperty
Properties for defining a `CfnScheduledAction`.A builder forCfnScheduledActionProps
An implementation forCfnScheduledActionProps
(experimental) Create a Redshift cluster a given number of nodes.(experimental) A fluent builder forCluster
.(experimental) Properties that describe an existing cluster instance.A builder forClusterAttributes
An implementation forClusterAttributes
(experimental) A cluster parameter group.(experimental) A fluent builder forClusterParameterGroup
.(experimental) Properties for a parameter group.A builder forClusterParameterGroupProps
An implementation forClusterParameterGroupProps
(experimental) Properties for a new database cluster.A builder forClusterProps
An implementation forClusterProps
(experimental) Class for creating a Redshift cluster subnet group.(experimental) A fluent builder forClusterSubnetGroup
.(experimental) Properties for creating a ClusterSubnetGroup.A builder forClusterSubnetGroupProps
An implementation forClusterSubnetGroupProps
(experimental) What cluster type to use.(experimental) A column in a Redshift table.A builder forColumn
An implementation forColumn
(experimental) Properties for accessing a Redshift database.A builder forDatabaseOptions
An implementation forDatabaseOptions
(experimental) A database secret.(experimental) A fluent builder forDatabaseSecret
.(experimental) Construction properties for a DatabaseSecret.A builder forDatabaseSecretProps
An implementation forDatabaseSecretProps
(experimental) Connection endpoint of a redshift cluster.(experimental) Create a Redshift Cluster with a given number of nodes.Internal default implementation forICluster
.A proxy class which represents a concrete javascript instance of this type.(experimental) A parameter group.Internal default implementation forIClusterParameterGroup
.A proxy class which represents a concrete javascript instance of this type.(experimental) Interface for a cluster subnet group.Internal default implementation forIClusterSubnetGroup
.A proxy class which represents a concrete javascript instance of this type.(experimental) Represents a table in a Redshift database.Internal default implementation forITable
.A proxy class which represents a concrete javascript instance of this type.(experimental) Represents a user in a Redshift database.Internal default implementation forIUser
.A proxy class which represents a concrete javascript instance of this type.(experimental) Username and password combination.A builder forLogin
An implementation forLogin
(experimental) Possible Node Types to use in the cluster used for defininginvalid @link
ClusterProps.nodeType
(experimental) Options to add the multi user rotation.A builder forRotationMultiUserOptions
An implementation forRotationMultiUserOptions
(experimental) A table in a Redshift cluster.(experimental) A fluent builder forTable
.(experimental) An action that a Redshift user can be granted privilege to perform on a table.(experimental) A full specification of a Redshift table that can be used to import it fluently into the CDK application.A builder forTableAttributes
An implementation forTableAttributes
(experimental) The data distribution style of a table.(experimental) Properties for configuring a Redshift table.A builder forTableProps
An implementation forTableProps
(experimental) The sort style of a table.(experimental) A user in a Redshift cluster.(experimental) A fluent builder forUser
.(experimental) A full specification of a Redshift user that can be used to import it fluently into the CDK application.A builder forUserAttributes
An implementation forUserAttributes
(experimental) Properties for configuring a Redshift user.A builder forUserProps
An implementation forUserProps