Skip to content

Commit c945be3

Browse files
evzzkevzzk
committed
Periodic doc update
1 parent 57b9275 commit c945be3

10 files changed

+476
-73
lines changed

‎v2/cli.md

Lines changed: 1 addition & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -67,55 +67,7 @@ Issue `cdk version` to display the version of the CDK CLI\. Provide this informa
6767

6868
## Version reporting<a name="version_reporting"></a>
6969

70-
To gain insight into how the AWS CDK is used, the constructs used by AWS CDK applications are collected and reported by using a resource identified as `AWS::CDK::Metadata`\. This resource is added to AWS CloudFormation templates, and can easily be reviewed\. This information can also be used by AWS to identify stacks using a construct with known security or reliability issues\. It can also be used to contact their users with important information\.
71-
72-
**Note**
73-
Before version 1\.93\.0, the AWS CDK reported the names and versions of the modules loaded during synthesis, instead of the constructs used in the stack\.
74-
75-
By default, the AWS CDK reports the use of constructs in the following NPM modules that are used in the stack:
76-
+ AWS CDK core module
77-
+ AWS Construct Library modules
78-
+ AWS Solutions Constructs module
79-
+ AWS Render Farm Deployment Kit module
80-
81-
The `AWS::CDK::Metadata` resource looks something like the following\.
82-
83-
```
84-
CDKMetadata:
85-
Type: "AWS::CDK::Metadata"
86-
Properties:
87-
Analytics: "v2:deflate64:H4sIAND9SGAAAzXKSw5AMBAA0L1b2PdzBYnEAdio3RglglY60zQi7u6TWL/XKmNUlxeQSOKwaPTBqrNhwEWU3hGHiCzK0dWWfAxoL/Fd8mvk+QkS/0X6BdjnCdgmOOQKWz+AqqLDt2Y3YMnLYWwAAAA="
88-
```
89-
90-
The `Analytics` property is a gzipped, base64\-encoded, prefix\-encoded list of the constructs in the stack\.
91-
92-
### Opt out of version reporting<a name="version_reporting_out"></a>
93-
94-
You can opt out of version reporting by using the CDK CLI or by configuring your project's `cdk.json` file\.
95-
96-
**To opt out of version reporting using the CDK CLI**
97-
+ Use the `--no-version-reporting` option with any CDK CLI command to opt out for a single command\. The following is an example of opting out during template synthesis:
98-
99-
```
100-
$ cdk synth --no-version-reporting
101-
```
102-
103-
Since the AWS CDK synthesizes templates automatically when you run `cdk deploy`, you should also use `--no-version-reporting` with the `cdk deploy` command\.
104-
105-
**To opt out of version reporting by configuring the `cdk.json` file**
106-
+ Set `versionReporting` to `false` in `./cdk.json` or `~/.cdk.json`\. This opts you out by default\. The following is an example:
107-
108-
```
109-
{
110-
"app": "...",
111-
"versionReporting": false
112-
}
113-
```
114-
115-
After configuring, you can override this behavior and opt in by specifying `--version-reporting` on an individual command\.
116-
117-
**Note**
118-
When you opt out of version reporting, the AWS CDK will not collect or report data on which constructs you are using\. Because of this, the AWS CDK will not be able to identify if you've been impacted by security issues and will not send you notifications for them\.
70+
To gain insight into how the AWS CDK is used, the constructs used by AWS CDK applications are collected and reported by using a resource identified as `AWS::CDK::Metadata`\. To learn more, see [Configure AWS CDK usage data reporting](usage-data.md)\.
11971

12072
## Authentication with AWS<a name="cli_auth"></a>
12173

‎v2/index.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@ sponsored by Amazon.
5757
+ [Create and apply permissions boundaries for the AWS CDK](customize-permissions-boundaries.md)
5858
+ [Troubleshoot AWS CDK bootstrapping issues](bootstrapping-troubleshoot.md)
5959
+ [Develop AWS CDK applications](develop.md)
60+
+ [Configure AWS CDK usage data reporting](usage-data.md)
6061
+ [Customize constructs from the AWS Construct Library](cfn_layer.md)
6162
+ [Get a value from an environment variable](get_env_var.md)
6263
+ [Use CloudFormation parameters to get a CloudFormation value](get_cfn_param.md)
@@ -74,6 +75,10 @@ sponsored by Amazon.
7475
+ [Continuous integration and delivery (CI/CD) using CDK Pipelines](cdk_pipeline.md)
7576
+ [Troubleshoot AWS CDK deployments](deploy-troubleshoot.md)
7677
+ [Test AWS CDK applications](testing.md)
78+
+ [Locally test and build AWS CDK applications with the AWS SAM CLI](testing-locally.md)
79+
+ [Getting started with locally testing](testing-locally-getting-started.md)
80+
+ [Local testing AWS CDK applications with AWS SAM](testing-locally-with-sam-cli.md)
81+
+ [Building AWS CDK applications with AWS SAM](testing-locally-build-with-sam-cli.md)
7782
+ [AWS CDK CLI reference](cli.md)
7883
+ [AWS CDK CLI command reference](ref-cli-cmd.md)
7984
+ [cdk acknowledge](ref-cli-cmd-ack.md)

‎v2/libraries.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ The Constructs library, commonly referred to as `constructs`, is a library for d
1616

1717
## The AWS CDK API reference<a name="libraries-reference"></a>
1818

19-
The [AWS CDK API reference](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html) contains official reference documentation for the AWS CDK Library, including the AWS Construct Library and Constructs library\. A version of the API refernce is provided for each supported programming language\.
19+
The [AWS CDK API reference](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html) contains official reference documentation for the AWS CDK Library, including the AWS Construct Library and Constructs library\. A version of the API reference is provided for each supported programming language\.
2020
+ For AWS CDK Library \(`aws-cdk-lib`\) documentation, see [aws\-cdk\-lib module](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html)\.
2121
+ Documentation for constructs in the AWS Construct Library are organized by AWS service in the following format: `aws-cdk-lib.<service>`\. For example, construct documentation for Amazon Simple Storage Service \(Amazon S3\), can be found at [aws\-cdk\-lib\.aws\_s3 module](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3-readme.html)\.
2222
+ For Constructs library \(constructs\) documentation, see [constructs module](https://docs.aws.amazon.com/cdk/api/v2/docs/constructs-readme.html)\.

‎v2/testing-locally-build-with-sam-cli.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Building AWS CDK applications with AWS SAM<a name="testing-locally-build-with-sam-cli"></a>
2+
3+
The AWS SAM CLI provides support for building Lambda functions and layers defined in your AWS CDK application with [sam build](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-build.html)\.
4+
5+
For Lambda functions that use zip artifacts, run `cdk synth` before you run `sam local` commands\. `sam build` isn't required\.
6+
7+
If your AWS CDK application uses functions with the image type, run `cdk synth` and then run `sam build` before you run `sam local` commands\. When you run `sam build`, AWS SAM doesn't build Lambda functions or layers that use runtime\-specific constructs, for example, [NodejsFunction](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs.NodejsFunction.html)\. `sam build` doesn't support [bundled assets](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.BundlingOptions.html)\.
8+
9+
## Example<a name="testing-locally-build-with-sam-cli-examples"></a>
10+
11+
Running the following command from the AWS CDK project root directory builds the application\.
12+
13+
```
14+
$ sam build -t ./cdk.out/CdkSamExampleStack.template.json
15+
```

‎v2/testing-locally-getting-started.md

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Getting started with locally testing<a name="testing-locally-getting-started"></a>
2+
3+
This topic describes what you need to use the AWS SAM CLI with AWS CDK applications, and it provides instructions for building and locally testing a simple AWS CDK application\.
4+
5+
## Prerequisites<a name="testing-locally-getting-started-prerequisites"></a>
6+
7+
To test locally, you must install the AWS SAM CLI\. see [Install the AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/getting_started.html) for installation instructions\.
8+
9+
## Creating and locally testing an AWS CDK application<a name="testing-locally-getting-started-tutorial"></a>
10+
11+
To locally test an AWS CDK application using the AWS SAM CLI, you must have an AWS CDK application that contains a Lambda function\. Use the following steps to create a basic AWS CDK application with a Lambda function\. For more information, see [Creating a serverless application using the AWS CDK](https://docs.aws.amazon.com/cdk/latest/guide/serverless_example.html) in the *AWS Cloud Development Kit \(AWS CDK\) Developer Guide*\.
12+
13+
### Step 1: Create an AWS CDK application<a name="testing-locally-getting-started-tutorial-init.title"></a>
14+
15+
For this tutorial, initialize an AWS CDK application that uses TypeScript\.
16+
17+
Command to run:
18+
19+
```
20+
$ mkdir cdk-sam-example
21+
$ cd cdk-sam-example
22+
$ cdk init app --language typescript
23+
```
24+
25+
### Step 2: Add a Lambda function to your application<a name="testing-locally-getting-started-tutorial-lambda.title"></a>
26+
27+
Replace the code in `lib/cdk-sam-example-stack.ts` with the following:
28+
29+
```
30+
import { Stack, StackProps } from 'aws-cdk-lib';
31+
import { Construct } from 'constructs';
32+
import * as lambda from 'aws-cdk-lib/aws-lambda';
33+
34+
export class CdkSamExampleStack extends Stack {
35+
constructor(scope: Construct, id: string, props?: StackProps) {
36+
super(scope, id, props);
37+
38+
new lambda.Function(this, 'MyFunction', {
39+
runtime: lambda.Runtime.PYTHON_3_12,
40+
handler: 'app.lambda_handler',
41+
code: lambda.Code.fromAsset('./my_function'),
42+
});
43+
}
44+
}
45+
```
46+
47+
### Step 3: Add your Lambda function code<a name="testing-locally-getting-started-tutorial-code.title"></a>
48+
49+
Create a directory named `my_function`\. In that directory, create a file named `app.py`\.
50+
51+
Command to run:
52+
53+
------
54+
#### [ OS and Linux ]
55+
56+
```
57+
$ mkdir my_function
58+
$ cd my_function
59+
$ touch app.py
60+
```
61+
62+
------
63+
#### [ Windows ]
64+
65+
```
66+
$ mkdir my_function
67+
$ cd my_function
68+
$ type nul > app.py
69+
```
70+
71+
------
72+
#### [ PowerShell ]
73+
74+
```
75+
$ mkdir my_function
76+
$ cd my_function
77+
$ New-Item -Path "app.py”
78+
```
79+
80+
------
81+
82+
Add the following code to `app.py`:
83+
84+
```
85+
def lambda_handler(event, context):
86+
return "Hello from SAM and the CDK!"
87+
```
88+
89+
### Step 4: Test your Lambda function<a name="testing-locally-getting-started-tutorial-function.title"></a>
90+
91+
You can use the AWS SAM CLI to locally invoke a Lambda function that you define in an AWS CDK application\. To do this, you need the function construct identifier and the path to your synthesized AWS CloudFormation template\.
92+
93+
Run the following command to go back to the `lib` directory:
94+
95+
```
96+
$ cd ..
97+
```
98+
99+
**Command to run:**
100+
101+
```
102+
$ cdk synth --no-staging
103+
```
104+
105+
```
106+
$ sam local invoke MyFunction --no-event -t ./cdk.out/CdkSamExampleStack.template.json
107+
```
108+
109+
**Example output:**
110+
111+
```
112+
Invoking app.lambda_handler (python3.9)
113+
114+
START RequestId: 5434c093-7182-4012-9b06-635011cac4f2 Version: $LATEST
115+
"Hello from SAM and the CDK!"
116+
END RequestId: 5434c093-7182-4012-9b06-635011cac4f2
117+
REPORT RequestId: 5434c093-7182-4012-9b06-635011cac4f2 Init Duration: 0.32 ms Duration: 177.47 ms Billed Duration: 178 ms Memory Size: 128 MB Max Memory Used: 128 MB
118+
```

‎v2/testing-locally-with-sam-cli.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Local testing AWS CDK applications with AWS SAM<a name="testing-locally-with-sam-cli"></a>
2+
3+
You can use the AWS SAM CLI to locally test your AWS CDK applications by running the following commands from the project root directory of your AWS CDK application:
4+
+ [sam local invoke](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-local-invoke.html)
5+
+ [sam local start\-api](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-local-start-api.html)
6+
+ [sam local start\-lambda](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-local-start-lambda.html)
7+
8+
Before you run any of the sam local commands with a AWS CDK application, you must run `cdk synth`\.
9+
10+
When running sam local invoke you need the function construct identifier that you want to invoke, and the path to your synthesized AWS CloudFormation template\. If your application uses nested stacks, to resolve naming conflicts, you also need the stack name where the function is defined\.
11+
12+
**Usage:**
13+
14+
```
15+
# Invoke the function FUNCTION_IDENTIFIER declared in the stack STACK_NAME
16+
$ sam local invoke [OPTIONS] [STACK_NAME/FUNCTION_IDENTIFIER]
17+
18+
# Start all APIs declared in the AWS CDK application
19+
$ sam local start-api -t ./cdk.out/CdkSamExampleStack.template.json [OPTIONS]
20+
21+
# Start a local endpoint that emulates AWS Lambda
22+
$ sam local start-lambda -t ./cdk.out/CdkSamExampleStack.template.json [OPTIONS]
23+
```
24+
25+
## Example<a name="testing-cdk-applications-examples"></a>
26+
27+
Consider stacks and functions that are declared with the following sample:
28+
29+
```
30+
app = new HelloCdkStack(app, "HelloCdkStack",
31+
...
32+
)
33+
class HelloCdkStack extends cdk.Stack {
34+
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
35+
...
36+
new lambda.Function(this, 'MyFunction', {
37+
...
38+
});
39+
40+
new HelloCdkNestedStack(this, 'HelloNestedStack' ,{
41+
...
42+
});
43+
}
44+
45+
class HelloCdkNestedStack extends cdk.NestedStack {
46+
constructor(scope: Construct, id: string, props?: cdk.NestedStackProps) {
47+
...
48+
new lambda.Function(this, 'MyFunction', {
49+
...
50+
});
51+
new lambda.Function(this, 'MyNestedFunction', {
52+
...
53+
});
54+
}
55+
```
56+
57+
The following commands locally invokes the Lambda functions defined in example presented above:
58+
59+
```
60+
# Invoke MyFunction from the HelloCdkStack
61+
$ sam local invoke -t ./cdk.out/HelloCdkStack.template.json MyFunction
62+
```
63+
64+
```
65+
# Invoke MyNestedFunction from the HelloCdkNestedStack
66+
$ sam local invoke -t ./cdk.out/HelloCdkStack.template.json MyNestedFunction
67+
```
68+
69+
```
70+
# Invoke MyFunction from the HelloCdkNestedStack
71+
$ sam local invoke -t ./cdk.out/HelloCdkStack.template.json HelloNestedStack/MyFunction
72+
```

‎v2/testing-locally.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Locally test and build AWS CDK applications with the AWS SAM CLI<a name="testing-locally"></a>
2+
3+
You can use the AWS SAM CLI to locally test and build serverless applications defined using the AWS Cloud Development Kit \(AWS CDK\)\. Because the AWS SAM CLI works within the AWS CDK project structure, you can still use the [AWS CDK CLI reference](cli.md) for creating, modifying, and deploying your AWS CDK applications\.
4+
5+
For details on using AWS SAM, see [Getting started with AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-getting-started.html) in the *AWS Serverless Application Model Developer Guide*\.
6+
7+
**Topics**
8+
+ [Getting started with locally testing](testing-locally-getting-started.md)
9+
+ [Local testing AWS CDK applications with AWS SAM](testing-locally-with-sam-cli.md)
10+
+ [Building AWS CDK applications with AWS SAM](testing-locally-build-with-sam-cli.md)

0 commit comments

Comments
 (0)