diff --git a/packages/@aws-cdk/aws-appsync/README.md b/packages/@aws-cdk/aws-appsync/README.md index 6095e3657ef9d..56c4cf6e0504a 100644 --- a/packages/@aws-cdk/aws-appsync/README.md +++ b/packages/@aws-cdk/aws-appsync/README.md @@ -31,7 +31,7 @@ type demo { version: String! } type Query { - getDemos: [ test! ] + getDemos: [ demo! ] } input DemoInput { version: String! @@ -84,6 +84,69 @@ demoDS.createResolver({ }); ``` +## Aurora Serverless + +AppSync provides a data source for executing SQL commands against Amazon Aurora +Serverless clusters. You can use AppSync resolvers to execute SQL statements +against the Data API with GraphQL queries, mutations, and subscriptions. + +```ts +// Create username and password secret for DB Cluster +const secret = new rds.DatabaseSecret(stack, 'AuroraSecret', { + username: 'clusteradmin', +}); + +// Create the DB cluster, provide all values needed to customise the database. +const cluster = new rds.DatabaseCluster(stack, 'AuroraCluster', { + engine: rds.DatabaseClusterEngine.auroraMysql({ version: rds.AuroraMysqlEngineVersion.VER_2_07_1 }), + credentials: { username: 'clusteradmin' }, + clusterIdentifier: 'db-endpoint-test', + defaultDatabaseName: 'demos', +}); + +// Build a data source for AppSync to access the database. +const rdsDS = api.addRdsDataSource('rds', 'The rds data source', cluster, secret); + +// Set up a resolver for an RDS query. +rdsDS.createResolver({ + typeName: 'Query', + fieldName: 'getDemosRds', + requestMappingTemplate: MappingTemplate.fromString(` + { + "version": "2018-05-29", + "statements": [ + "SELECT * FROM demos" + ] + } + `), + responseMappingTemplate: MappingTemplate.fromString(` + $util.rds.toJsonObject($ctx.result) + `), +}); + +// Set up a resolver for an RDS mutation. +rdsDS.createResolver({ + typeName: 'Mutation', + fieldName: 'addDemoRds', + requestMappingTemplate: MappingTemplate.fromString(` + { + "version": "2018-05-29", + "statements": [ + "INSERT INTO demos VALUES (:id, :version)", + "SELECT * WHERE id = :id" + ], + "variableMap": { + ":id": $util.toJson($util.autoId()), + ":version": $util.toJson($ctx.args.version) + } + } + `), + responseMappingTemplate: MappingTemplate.fromString(` + $util.rds.toJsonObject($ctx.result) + `), +}); +``` + #### HTTP Endpoints GraphQL schema file `schema.graphql`: diff --git a/packages/@aws-cdk/aws-appsync/lib/data-source.ts b/packages/@aws-cdk/aws-appsync/lib/data-source.ts index babde4be0a3fb..e13136090b56c 100644 --- a/packages/@aws-cdk/aws-appsync/lib/data-source.ts +++ b/packages/@aws-cdk/aws-appsync/lib/data-source.ts @@ -1,7 +1,9 @@ import { ITable } from '@aws-cdk/aws-dynamodb'; -import { IGrantable, IPrincipal, IRole, Role, ServicePrincipal } from '@aws-cdk/aws-iam'; +import { Grant, IGrantable, IPrincipal, IRole, Role, ServicePrincipal } from '@aws-cdk/aws-iam'; import { IFunction } from '@aws-cdk/aws-lambda'; -import { IResolvable } from '@aws-cdk/core'; +import { IDatabaseCluster } from '@aws-cdk/aws-rds'; +import { ISecret } from '@aws-cdk/aws-secretsmanager'; +import { IResolvable, Stack } from '@aws-cdk/core'; import { Construct } from 'constructs'; import { CfnDataSource } from './appsync.generated'; import { IGraphqlApi } from './graphqlapi-base'; @@ -283,4 +285,56 @@ export class LambdaDataSource extends BackedDataSource { }); props.lambdaFunction.grantInvoke(this); } +} + +/** + * Properties for an AppSync RDS datasource + */ +export interface RdsDataSourceProps extends BackedDataSourceProps { + /** + * The database cluster to call to interact with this data source + */ + readonly databaseCluster: IDatabaseCluster; + /** + * The secret containing the credentials for the database + */ + readonly secretStore: ISecret; +} + +/** + * An AppSync datasource backed by RDS + */ +export class RdsDataSource extends BackedDataSource { + constructor(scope: Construct, id: string, props: RdsDataSourceProps) { + super(scope, id, props, { + type: 'RELATIONAL_DATABASE', + relationalDatabaseConfig: { + rdsHttpEndpointConfig: { + awsRegion: props.databaseCluster.stack.region, + dbClusterIdentifier: props.databaseCluster.clusterIdentifier, + awsSecretStoreArn: props.secretStore.secretArn, + }, + relationalDatabaseSourceType: 'RDS_HTTP_ENDPOINT', + }, + }); + props.secretStore.grantRead(this); + const clusterArn = Stack.of(this).formatArn({ + service: 'rds', + resource: `cluster:${props.databaseCluster.clusterIdentifier}`, + }); + // Change to grant with RDS grant becomes implemented + Grant.addToPrincipal({ + grantee: this, + actions: [ + 'rds-data:DeleteItems', + 'rds-data:ExecuteSql', + 'rds-data:ExecuteStatement', + 'rds-data:GetItems', + 'rds-data:InsertItems', + 'rds-data:UpdateItems', + ], + resourceArns: [clusterArn, `${clusterArn}:*`], + scope: this, + }); + } } \ No newline at end of file diff --git a/packages/@aws-cdk/aws-appsync/lib/graphqlapi-base.ts b/packages/@aws-cdk/aws-appsync/lib/graphqlapi-base.ts index 0525b51340fcd..288384c6454a5 100644 --- a/packages/@aws-cdk/aws-appsync/lib/graphqlapi-base.ts +++ b/packages/@aws-cdk/aws-appsync/lib/graphqlapi-base.ts @@ -1,7 +1,9 @@ import { ITable } from '@aws-cdk/aws-dynamodb'; import { IFunction } from '@aws-cdk/aws-lambda'; +import { IDatabaseCluster } from '@aws-cdk/aws-rds'; +import { ISecret } from '@aws-cdk/aws-secretsmanager'; import { CfnResource, IResource, Resource } from '@aws-cdk/core'; -import { DynamoDbDataSource, HttpDataSource, LambdaDataSource, NoneDataSource, AwsIamConfig } from './data-source'; +import { DynamoDbDataSource, HttpDataSource, LambdaDataSource, NoneDataSource, RdsDataSource, AwsIamConfig } from './data-source'; /** * Optional configuration for data sources @@ -90,6 +92,21 @@ export interface IGraphqlApi extends IResource { */ addLambdaDataSource(id: string, lambdaFunction: IFunction, options?: DataSourceOptions): LambdaDataSource; + /** + * add a new Rds data source to this API + * + * @param id The data source's id + * @param databaseCluster The database cluster to interact with this data source + * @param secretStore The secret store that contains the username and password for the database cluster + * @param options The optional configuration for this data source + */ + addRdsDataSource( + id: string, + databaseCluster: IDatabaseCluster, + secretStore: ISecret, + options?: DataSourceOptions + ): RdsDataSource; + /** * Add schema dependency if not imported * @@ -178,6 +195,28 @@ export abstract class GraphqlApiBase extends Resource implements IGraphqlApi { }); } + /** + * add a new Rds data source to this API + * @param id The data source's id + * @param databaseCluster The database cluster to interact with this data source + * @param secretStore The secret store that contains the username and password for the database cluster + * @param options The optional configuration for this data source + */ + public addRdsDataSource( + id: string, + databaseCluster: IDatabaseCluster, + secretStore: ISecret, + options?: DataSourceOptions, + ): RdsDataSource { + return new RdsDataSource(this, id, { + api: this, + name: options?.name, + description: options?.description, + databaseCluster, + secretStore, + }); + } + /** * Add schema dependency if not imported * diff --git a/packages/@aws-cdk/aws-appsync/package.json b/packages/@aws-cdk/aws-appsync/package.json index e581f2571e319..5c946b4afcd17 100644 --- a/packages/@aws-cdk/aws-appsync/package.json +++ b/packages/@aws-cdk/aws-appsync/package.json @@ -82,7 +82,10 @@ "dependencies": { "@aws-cdk/aws-cognito": "0.0.0", "@aws-cdk/aws-dynamodb": "0.0.0", + "@aws-cdk/aws-ec2": "0.0.0", + "@aws-cdk/aws-rds": "0.0.0", "@aws-cdk/aws-iam": "0.0.0", + "@aws-cdk/aws-secretsmanager": "0.0.0", "@aws-cdk/aws-lambda": "0.0.0", "@aws-cdk/aws-s3-assets": "0.0.0", "@aws-cdk/core": "0.0.0", @@ -92,10 +95,13 @@ "peerDependencies": { "@aws-cdk/aws-cognito": "0.0.0", "@aws-cdk/aws-dynamodb": "0.0.0", + "@aws-cdk/aws-ec2": "0.0.0", "@aws-cdk/aws-iam": "0.0.0", "@aws-cdk/aws-lambda": "0.0.0", "@aws-cdk/aws-s3-assets": "0.0.0", "@aws-cdk/core": "0.0.0", + "@aws-cdk/aws-rds": "0.0.0", + "@aws-cdk/aws-secretsmanager": "0.0.0", "constructs": "^3.2.0" }, "engines": { diff --git a/packages/@aws-cdk/aws-appsync/test/appsync-rds.test.ts b/packages/@aws-cdk/aws-appsync/test/appsync-rds.test.ts new file mode 100644 index 0000000000000..ba0d80d00037b --- /dev/null +++ b/packages/@aws-cdk/aws-appsync/test/appsync-rds.test.ts @@ -0,0 +1,206 @@ +import '@aws-cdk/assert/jest'; +import * as path from 'path'; +import { Vpc, SecurityGroup, SubnetType, InstanceType, InstanceClass, InstanceSize } from '@aws-cdk/aws-ec2'; +import { DatabaseSecret, DatabaseCluster, DatabaseClusterEngine, AuroraMysqlEngineVersion } from '@aws-cdk/aws-rds'; +import * as cdk from '@aws-cdk/core'; +import * as appsync from '../lib'; + +// GLOBAL GIVEN +let stack: cdk.Stack; +let api: appsync.GraphqlApi; +beforeEach(() => { + stack = new cdk.Stack(); + api = new appsync.GraphqlApi(stack, 'baseApi', { + name: 'api', + schema: new appsync.Schema({ + filePath: path.join(__dirname, 'appsync.test.graphql'), + }), + }); +}); + +describe('Rds Data Source configuration', () => { + // GIVEN + let secret: DatabaseSecret; + let cluster: DatabaseCluster; + beforeEach(() => { + const vpc = new Vpc(stack, 'Vpc', { maxAzs: 2 }); + const securityGroup = new SecurityGroup(stack, 'AuroraSecurityGroup', { + vpc, + allowAllOutbound: true, + }); + secret = new DatabaseSecret(stack, 'AuroraSecret', { + username: 'clusteradmin', + }); + cluster = new DatabaseCluster(stack, 'AuroraCluster', { + engine: DatabaseClusterEngine.auroraMysql({ version: AuroraMysqlEngineVersion.VER_2_07_1 }), + credentials: { username: 'clusteradmin' }, + clusterIdentifier: 'db-endpoint-test', + instanceProps: { + instanceType: InstanceType.of(InstanceClass.BURSTABLE2, InstanceSize.SMALL), + vpcSubnets: { subnetType: SubnetType.PRIVATE }, + vpc, + securityGroups: [securityGroup], + }, + defaultDatabaseName: 'Animals', + }); + }); + + test('appsync creates correct policy', () => { + // WHEN + api.addRdsDataSource('ds', cluster, secret); + + // THEN + expect(stack).toHaveResourceLike('AWS::IAM::Policy', { + PolicyDocument: { + Version: '2012-10-17', + Statement: [{ + Action: [ + 'secretsmanager:GetSecretValue', + 'secretsmanager:DescribeSecret', + ], + Effect: 'Allow', + Resource: { Ref: 'AuroraSecret41E6E877' }, + }, + { + Action: [ + 'rds-data:DeleteItems', + 'rds-data:ExecuteSql', + 'rds-data:ExecuteStatement', + 'rds-data:GetItems', + 'rds-data:InsertItems', + 'rds-data:UpdateItems', + ], + Effect: 'Allow', + Resource: [{ + 'Fn::Join': ['', ['arn:', + { Ref: 'AWS::Partition' }, + ':rds:', + { Ref: 'AWS::Region' }, + ':', + { Ref: 'AWS::AccountId' }, + ':cluster:', + { Ref: 'AuroraCluster23D869C0' }]], + }, + { + 'Fn::Join': ['', ['arn:', + { Ref: 'AWS::Partition' }, + ':rds:', + { Ref: 'AWS::Region' }, + ':', + { Ref: 'AWS::AccountId' }, + ':cluster:', + { Ref: 'AuroraCluster23D869C0' }, + ':*']], + }], + }], + }, + }); + }); + + test('default configuration produces name identical to the id', () => { + // WHEN + api.addRdsDataSource('ds', cluster, secret); + + // THEN + expect(stack).toHaveResourceLike('AWS::AppSync::DataSource', { + Type: 'RELATIONAL_DATABASE', + Name: 'ds', + }); + }); + + test('appsync configures name correctly', () => { + // WHEN + api.addRdsDataSource('ds', cluster, secret, { + name: 'custom', + }); + + // THEN + expect(stack).toHaveResourceLike('AWS::AppSync::DataSource', { + Type: 'RELATIONAL_DATABASE', + Name: 'custom', + }); + }); + + test('appsync configures name and description correctly', () => { + // WHEN + api.addRdsDataSource('ds', cluster, secret, { + name: 'custom', + description: 'custom description', + }); + + // THEN + expect(stack).toHaveResourceLike('AWS::AppSync::DataSource', { + Type: 'RELATIONAL_DATABASE', + Name: 'custom', + Description: 'custom description', + }); + }); + + test('appsync errors when creating multiple rds data sources with no configuration', () => { + // WHEN + const when = () => { + api.addRdsDataSource('ds', cluster, secret); + api.addRdsDataSource('ds', cluster, secret); + }; + + // THEN + expect(when).toThrow('There is already a Construct with name \'ds\' in GraphqlApi [baseApi]'); + }); +}); + +describe('adding rds data source from imported api', () => { + // GIVEN + let secret: DatabaseSecret; + let cluster: DatabaseCluster; + beforeEach(() => { + const vpc = new Vpc(stack, 'Vpc', { maxAzs: 2 }); + const securityGroup = new SecurityGroup(stack, 'AuroraSecurityGroup', { + vpc, + allowAllOutbound: true, + }); + secret = new DatabaseSecret(stack, 'AuroraSecret', { + username: 'clusteradmin', + }); + cluster = new DatabaseCluster(stack, 'AuroraCluster', { + engine: DatabaseClusterEngine.auroraMysql({ version: AuroraMysqlEngineVersion.VER_2_07_1 }), + credentials: { username: 'clusteradmin' }, + clusterIdentifier: 'db-endpoint-test', + instanceProps: { + instanceType: InstanceType.of(InstanceClass.BURSTABLE2, InstanceSize.SMALL), + vpcSubnets: { subnetType: SubnetType.PRIVATE }, + vpc, + securityGroups: [securityGroup], + }, + defaultDatabaseName: 'Animals', + }); + }); + + test('imported api can add RdsDbDataSource from id', () => { + // WHEN + const importedApi = appsync.GraphqlApi.fromGraphqlApiAttributes(stack, 'importedApi', { + graphqlApiId: api.apiId, + }); + importedApi.addRdsDataSource('ds', cluster, secret); + + // THEN + expect(stack).toHaveResourceLike('AWS::AppSync::DataSource', { + Type: 'RELATIONAL_DATABASE', + ApiId: { 'Fn::GetAtt': ['baseApiCDA4D43A', 'ApiId'] }, + }); + }); + + test('imported api can add RdsDataSource from attributes', () => { + // WHEN + const importedApi = appsync.GraphqlApi.fromGraphqlApiAttributes(stack, 'importedApi', { + graphqlApiId: api.apiId, + graphqlApiArn: api.arn, + }); + importedApi.addRdsDataSource('ds', cluster, secret); + + // THEN + expect(stack).toHaveResourceLike('AWS::AppSync::DataSource', { + Type: 'RELATIONAL_DATABASE', + ApiId: { 'Fn::GetAtt': ['baseApiCDA4D43A', 'ApiId'] }, + }); + }); +}); \ No newline at end of file