@aws-cdk/core
Advanced tools
@aws-cdk/core is a foundational package for the AWS Cloud Development Kit (CDK), which allows developers to define cloud infrastructure using familiar programming languages. It provides a high-level object-oriented abstraction to define AWS resources imperatively.
Defining a Stack
A stack is a collection of AWS resources that you can manage as a single unit. In this example, we define a new stack called 'MyStack' and add it to the CDK application.
const cdk = require('@aws-cdk/core');
class MyStack extends cdk.Stack {
constructor(scope, id, props) {
super(scope, id, props);
// Define resources here
}
}
const app = new cdk.App();
new MyStack(app, 'MyStack');
app.synth();Adding an S3 Bucket
This example demonstrates how to add an S3 bucket to a stack. The bucket is versioned, meaning it keeps multiple versions of an object.
const cdk = require('@aws-cdk/core');
const s3 = require('@aws-cdk/aws-s3');
class MyStack extends cdk.Stack {
constructor(scope, id, props) {
super(scope, id, props);
new s3.Bucket(this, 'MyBucket', {
versioned: true
});
}
}
const app = new cdk.App();
new MyStack(app, 'MyStack');
app.synth();Defining IAM Roles
This example shows how to define an IAM role within a stack. The role is assumed by AWS Lambda and has the AWSLambdaBasicExecutionRole managed policy attached.
const cdk = require('@aws-cdk/core');
const iam = require('@aws-cdk/aws-iam');
class MyStack extends cdk.Stack {
constructor(scope, id, props) {
super(scope, id, props);
new iam.Role(this, 'MyRole', {
assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
managedPolicies: [iam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaBasicExecutionRole')]
});
}
}
const app = new cdk.App();
new MyStack(app, 'MyStack');
app.synth();Pulumi is an infrastructure as code tool that allows you to define cloud resources using general-purpose programming languages. Unlike AWS CDK, which is AWS-specific, Pulumi supports multiple cloud providers including AWS, Azure, and Google Cloud.
Terraform by HashiCorp is an open-source infrastructure as code software tool that provides a consistent CLI workflow to manage hundreds of cloud services. It uses a declarative language called HCL (HashiCorp Configuration Language) and supports multiple cloud providers, making it more versatile compared to AWS CDK.
The Serverless Framework is an open-source framework that allows you to build and deploy serverless applications on AWS Lambda and other serverless computing platforms. It focuses on serverless architectures and provides a higher-level abstraction compared to AWS CDK.
This library includes the basic building blocks of the AWS Cloud Development Kit (AWS CDK). It defines the core classes that are used in the rest of the AWS Construct Library.
See the AWS CDK Developer Guide for information of most of the capabilities of this library. The rest of this README will only cover topics not already covered in the Developer Guide.
To make specifications of time intervals unambiguous, a single class called
Duration is used throughout the AWS Construct Library by all constructs
that that take a time interval as a parameter (be it for a timeout, a
rate, or something else).
An instance of Duration is constructed by using one of the static factory methods on it:
Duration.seconds(300) // 5 minutes
Duration.minutes(5) // 5 minutes
Duration.hours(1) // 1 hour
Duration.days(7) // 7 days
Duration.parse('PT5M') // 5 minutes
To help avoid accidental storage of secrets as plain text, we use the SecretValue type to
represent secrets. Any construct that takes a value that should be a secret (such as
a password or an access key) will take a parameter of type SecretValue.
The best practice is to store secrets in AWS Secrets Manager and reference them using SecretValue.secretsManager:
const secret = SecretValue.secretsManager('secretId', {
jsonField: 'password' // optional: key of a JSON field to retrieve (defaults to all content),
versionId: 'id' // optional: id of the version (default AWSCURRENT)
versionStage: 'stage' // optional: version stage name (default AWSCURRENT)
});
Using AWS Secrets Manager is the recommended way to reference secrets in a CDK app.
SecretValue also supports the following secret sources:
SecretValue.plainText(secret): stores the secret as plain text in your app and the resulting template (not recommended).SecretValue.ssmSecure(param, version): refers to a secret stored as a SecureString in the SSM Parameter Store.SecretValue.cfnParameter(param): refers to a secret passed through a CloudFormation parameter (must have NoEcho: true).SecretValue.cfnDynamicReference(dynref): refers to a secret described by a CloudFormation dynamic reference (used by ssmSecure and secretsManager).Sometimes you will need to put together or pick apart Amazon Resource Names
(ARNs). The functions stack.formatArn() and stack.parseArn() exist for
this purpose.
formatArn() can be used to build an ARN from components. It will automatically
use the region and account of the stack you're calling it on:
// Builds "arn:<PARTITION>:lambda:<REGION>:<ACCOUNT>:function:MyFunction"
stack.formatArn({
service: 'lambda',
resource: 'function',
sep: ':',
resourceName: 'MyFunction'
});
parseArn() can be used to get a single component from an ARN. parseArn()
will correctly deal with both literal ARNs and deploy-time values (tokens),
but in case of a deploy-time value be aware that the result will be another
deploy-time value which cannot be inspected in the CDK application.
// Extracts the function name out of an AWS Lambda Function ARN
const arnComponents = stack.parseArn(arn, ':');
const functionName = arnComponents.resourceName;
Note that depending on the service, the resource separator can be either
: or /, and the resource name can be either the 6th or 7th
component in the ARN. When using these functions, you will need to know
the format of the ARN you are dealing with.
For an exhaustive list of ARN formats used in AWS, see AWS ARNs and Namespaces in the AWS General Reference.
Sometimes AWS resources depend on other resources, and the creation of one resource must be completed before the next one can be started.
In general, CloudFormation will correctly infer the dependency relationship between resources based on the property values that are used. In the cases where it doesn't, the AWS Construct Library will add the dependency relationship for you.
If you need to add an ordering dependency that is not automatically inferred,
you do so by adding a dependency relationship using
constructA.node.addDependency(constructB). This will add a dependency
relationship between all resources in the scope of constructA and all
resources in the scope of constructB.
If you want a single object to represent a set of constructs that are not
necessarily in the same scope, you can use a ConcreteDependable. The
following creates a single object that represents a dependency on two
construts, constructB and constructC:
// Declare the dependable object
const bAndC = new ConcreteDependable();
bAndC.add(constructB);
bAndC.add(constructC);
// Take the dependency
constructA.node.addDependency(bAndC);
Two different stack instances can have a dependency on one another. This
happens when an resource from one stack is referenced in another stack. In
that case, CDK records the cross-stack referencing of resources,
automatically produces the right CloudFormation primitives, and adds a
dependency between the two stacks. You can also manually add a dependency
between two stacks by using the stackA.addDependency(stackB) method.
A stack dependency has the following implications:
stackA is using resources from
stackB, the reverse is not possible anymore.stackA depends on stackB, running cdk deploy stackA will also
automatically deploy stackB.stackB's deployment will be performed before stackA's deployment.A CDK stack synthesizes to an AWS CloudFormation Template. This section explains how this module allows users to access low-level CloudFormation features when needed.
CloudFormation stack outputs and exports are created using
the CfnOutput class:
new CfnOutput(this, 'OutputName', {
value: bucket.bucketName,
description: 'The name of an S3 bucket', // Optional
exportName: 'Global.BucketName', // Registers a CloudFormation export
});
CloudFormation templates support the use of Parameters to customize a template. They enable CloudFormation users to input custom values to a template each time a stack is created or updated. While the CDK design philosophy favors using build-time parameterization, users may need to use CloudFormation in a number of cases (for example, when migrating an existing stack to the AWS CDK).
Template parameters can be added to a stack by using the CfnParameter class:
new CfnParameter(this, 'MyParameter', {
type: 'Number',
default: 1337,
// See the API reference for more configuration props
});
The value of parameters can then be obtained using one of the value methods.
As parameters are only resolved at deployment time, the values obtained are
placeholder tokens for the real value (Token.isUnresolved() would return true
for those):
const param = new CfnParameter(this, 'ParameterName', { /* config */ });
// If the parameter is a String
param.valueAsString;
// If the parameter is a Number
param.valueAsNumber;
// If the parameter is a List
param.valueAsList;
CloudFormation supports a number of pseudo parameters,
which resolve to useful values at deployment time. CloudFormation pseudo
parameters can be obtained from static members of the Aws class.
It is generally recommended to access pseudo parameters from the scope's stack
instead, which guarantees the values produced are qualifying the designated
stack, which is essential in cases where resources are shared cross-stack:
// "this" is the current construct
const stack = Stack.of(this);
stack.account; // Returns the AWS::AccountId for this stack (or the literal value if known)
stack.region; // Returns the AWS::Region for this stack (or the literal value if known)
stack.partition;
CloudFormation resources can also specify resource
attributes. The CfnResource class allows
accessing those though the cfnOptions property:
const rawBucket = new s3.CfnBucket(this, 'Bucket', { /* ... */ });
// -or-
const rawBucket = bucket.node.defaultChild as s3.CfnBucket;
// then
rawBucket.condition = new CfnCondition(this, 'EnableBucket', { /* ... */ });
rawBucket.cfnOptions.metadata = {
metadataKey: 'MetadataValue',
};
Resource dependencies (the DependsOn attribute) is modified using the
cfnResource.addDependsOn method:
const resourceA = new CfnResource(this, 'ResourceA', { /* ... */ });
const resourceB = new CfnResource(this, 'ResourceB', { /* ... */ });
resourceB.addDependsOn(resourceA);
CloudFormation supports intrinsic functions. These functions
can be accessed from the Fn class, which provides type-safe methods for each
intrinsic function as well as condition expressions:
// To use Fn::Base64
Fn.base64('SGVsbG8gQ0RLIQo=');
// To compose condition expressions:
const environmentParameter = new CfnParameter(this, 'Environment');
Fn.conditionAnd(
// The "Environment" CloudFormation template parameter evaluates to "Production"
Fn.conditionEquals('Production', environmentParameter),
// The AWS::Region pseudo-parameter value is NOT equal to "us-east-1"
Fn.conditionNot(Fn.conditionEquals('us-east-1', Aws.REGION)),
);
When working with deploy-time values (those for which Token.isUnresolved
returns true), idiomatic conditionals from the programming language cannot be
used (the value will not be known until deployment time). When conditional logic
needs to be expressed with un-resolved values, it is necessary to use
CloudFormation conditions by means of the CfnCondition class:
const environmentParameter = new CfnParameter(this, 'Environment');
const isProd = new CfnCondition(this, 'IsProduction', {
expression: Fn.conditionEquals('Production', environmentParameter),
});
// Configuration value that is a different string based on IsProduction
const stage = Fn.conditionIf(isProd.logicalId, 'Beta', 'Prod').toString();
// Make Bucket creation condition to IsProduction by accessing
// and overriding the CloudFormation resource
const bucket = new s3.Bucket(this, 'Bucket');
const cfnBucket = bucket.node.defaultChild as s3.CfnBucket;
cfnBucket.cfnOptions.condition = isProd;
CloudFormation mappings are created and queried using the
CfnMappings class:
const mapping = new CfnMapping(this, 'MappingTable', {
mapping: {
regionName: {
'us-east-1': 'US East (N. Virginia)',
'us-east-2': 'US East (Ohio)',
// ...
},
// ...
}
});
mapping.findInMap('regionName', Aws.REGION);
CloudFormation supports dynamically resolving values
for SSM parameters (including secure strings) and Secrets Manager. Encoding such
references is done using the CfnDynamicReference class:
new CfnDynamicReference(this, 'SecureStringValue', {
service: CfnDynamicReferenceService.SECRETS_MANAGER,
referenceKey: 'secret-id:secret-string:json-key:version-stage:version-id',
});
CloudFormation templates support a number of options, including which Macros or
Transforms to use when deploying the stack. Those can be
configured using the stack.templateOptions property:
const stack = new Stack(app, 'StackName');
stack.templateOptions.description = 'This will appear in the AWS console';
stack.templateOptions.transform = 'AWS::Serverless';
stack.templateOptions.metadata = {
metadataKey: 'MetadataValue',
};
The CfnResource class allows emitting arbitrary entries in the
[Resources][cfn-resources] section of the CloudFormation template.
new CfnResource(this, 'ResourceId', {
type: 'AWS::S3::Bucket',
properties: {
BucketName: 'bucket-name'
},
});
As for any other resource, the logical ID in the CloudFormation template will be generated by the AWS CDK, but the type and properties will be copied verbatim in the synthesized template.
When migrating a CloudFormation stack to the AWS CDK, it can be useful to
include fragments of an existing template verbatim in the synthesized template.
This can be achieved using the CfnInclude class.
new CfnInclude(this, 'ID', {
template: {
Resources: {
Bucket: {
Type: 'AWS::S3::Bucket',
Properties: {
BucketName: 'my-shiny-bucket'
}
}
}
},
});
1.12.0 (2019-10-07)
exclude option (#4354) (f96b2fb), closes #4353 #4353cloudmap.Service.fromServiceAttributes takes a newly
required argument namespace.FAQs
AWS Cloud Development Kit Core Library
The npm package @aws-cdk/core receives a total of 198,582 weekly downloads. As such, @aws-cdk/core popularity was classified as popular.
We found that @aws-cdk/core demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.