You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: v2/apps.md
+23-23Lines changed: 23 additions & 23 deletions
Original file line number
Diff line number
Diff line change
@@ -1,14 +1,14 @@
1
1
# AWS CDK apps<aname="apps"></a>
2
2
3
-
The AWS Cloud Development Kit \(AWS CDK\) application or *app* is a collection of one or more CDK [stacks](stacks.md)\. Stacks are a collection of one or more [constructs](constructs.md), which define AWS resources and properties\. Therefore, the overall grouping of your stacks and constructs are known as your CDK app\.
3
+
The AWS Cloud Development Kit (AWS CDK) application or *app* is a collection of one or more CDK [stacks](stacks.md). Stacks are a collection of one or more [constructs](constructs.md), which define AWS resources and properties. Therefore, the overall grouping of your stacks and constructs are known as your CDK app.
4
4
5
5
## How to create a CDK app<aname="apps-define"></a>
6
6
7
-
You create an app by defining an app instance in the application file of your [project](projects.md)\. To do this, you import and use the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.App.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.App.html) construct from the AWS Construct Library\. The `App` construct doesn't require any initialization arguments\. It is the only construct that can be used as the root\.
7
+
You create an app by defining an app instance in the application file of your [project](projects.md). To do this, you import and use the [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.App.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.App.html) construct from the AWS Construct Library. The `App` construct doesn't require any initialization arguments. It is the only construct that can be used as the root.
8
8
9
-
The `[App](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.App.html)` and `[Stack](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html)` classes from the AWS Construct Library are unique constructs\. Compared to other constructs, they don't configure AWS resources on their own\. Instead, they are used to provide context for your other constructs\. All constructs that represent AWS resources must be defined, directly or indirectly, within the scope of a `Stack` construct\.`Stack` constructs are defined within the scope of an `App` construct\.
9
+
The `[App](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.App.html)` and `[Stack](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html)` classes from the AWS Construct Library are unique constructs. Compared to other constructs, they don't configure AWS resources on their own. Instead, they are used to provide context for your other constructs. All constructs that represent AWS resources must be defined, directly or indirectly, within the scope of a `Stack` construct. `Stack` constructs are defined within the scope of an `App` construct.
10
10
11
-
Apps are then synthesized to create AWS CloudFormation templates for your stacks\. The following is an example:
11
+
Apps are then synthesized to create AWS CloudFormation templates for your stacks. The following is an example:
12
12
13
13
------
14
14
#### [ TypeScript ]
@@ -47,7 +47,7 @@ app.synth();
47
47
```
48
48
49
49
------
50
-
#### [ C\#]
50
+
#### [ C\$1]
51
51
52
52
```
53
53
var app = new App();
@@ -72,41 +72,41 @@ app.Synth(nil)
72
72
73
73
------
74
74
75
-
Stacks within a single app can easily refer to each other's resources and properties\. The AWS CDK infers dependencies between stacks so that they can be deployed in the correct order\. You can deploy any or all of the stacks within an app with a single `cdk deploy` command\.
75
+
Stacks within a single app can easily refer to each other's resources and properties. The AWS CDK infers dependencies between stacks so that they can be deployed in the correct order. You can deploy any or all of the stacks within an app with a single `cdk deploy` command.
76
76
77
77
## The construct tree<aname="apps-tree"></a>
78
78
79
-
Constructs are defined inside of other constructs using the `scope` argument that is passed to every construct, with the `App` class as the root\. In this way, an AWS CDK app defines a hierarchy of constructs known as the *construct tree*\.
79
+
Constructs are defined inside of other constructs using the `scope` argument that is passed to every construct, with the `App` class as the root. In this way, an AWS CDK app defines a hierarchy of constructs known as the *construct tree*.
80
80
81
-
The root of this tree is your app, which is an instance of the `App` class\. Within the app, you instantiate one or more stacks\. Within stacks, you instantiate constructs, which may themselves instantiate resources or other constructs, and so on down the tree\.
81
+
The root of this tree is your app, which is an instance of the `App` class. Within the app, you instantiate one or more stacks. Within stacks, you instantiate constructs, which may themselves instantiate resources or other constructs, and so on down the tree.
82
82
83
-
Constructs are *always* explicitly defined within the scope of another construct, which creates relationships between constructs\. Almost always, you should pass `this`\(in Python, `self`\) as the scope, indicating that the new construct is a child of the current construct\. The intended pattern is that you derive your construct from [https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Construct.html](https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Construct.html), then instantiate the constructs it uses in its constructor\.
83
+
Constructs are *always* explicitly defined within the scope of another construct, which creates relationships between constructs. Almost always, you should pass `this` (in Python, `self`) as the scope, indicating that the new construct is a child of the current construct. The intended pattern is that you derive your construct from [https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Construct.html](https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Construct.html), then instantiate the constructs it uses in its constructor.
84
84
85
-
Passing the scope explicitly allows each construct to add itself to the tree, with this behavior entirely contained within the [`Construct` base class](https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Construct.html)\. It works the same way in every language supported by the AWS CDK and does not require additional customization\.
85
+
Passing the scope explicitly allows each construct to add itself to the tree, with this behavior entirely contained within the [`Construct` base class](https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Construct.html). It works the same way in every language supported by the AWS CDK and does not require additional customization.
86
86
87
87
**Important**
88
-
Technically, it's possible to pass some scope other than `this` when instantiating a construct\. You can add constructs anywhere in the tree, or even in another stack in the same app\. For example, you could write a mixin\-style function that adds constructs to a scope passed in as an argument\. The practical difficulty here is that you can't easily ensure that the IDs you choose for your constructs are unique within someone else's scope\. The practice also makes your code more difficult to understand, maintain, and reuse\. Therefore, we recommend that you use the general structure of the construct tree\.
88
+
Technically, it's possible to pass some scope other than `this` when instantiating a construct. You can add constructs anywhere in the tree, or even in another stack in the same app. For example, you could write a mixin-style function that adds constructs to a scope passed in as an argument. The practical difficulty here is that you can't easily ensure that the IDs you choose for your constructs are unique within someone else's scope. The practice also makes your code more difficult to understand, maintain, and reuse. Therefore, we recommend that you use the general structure of the construct tree.
89
89
90
-
The AWS CDK uses the IDs of all constructs in the path from the tree's root to each child construct to generate the unique IDs required by AWS CloudFormation\. This approach means that construct IDs only need to be unique within their scope, rather than within the entire stack as in native AWS CloudFormation\. However, if you move a construct to a different scope, its generated stack\-unique ID changes, and AWS CloudFormation won't consider it the same resource\.
90
+
The AWS CDK uses the IDs of all constructs in the path from the tree's root to each child construct to generate the unique IDs required by AWS CloudFormation. This approach means that construct IDs only need to be unique within their scope, rather than within the entire stack as in native AWS CloudFormation. However, if you move a construct to a different scope, its generated stack-unique ID changes, and AWS CloudFormation won't consider it the same resource.
91
91
92
-
The construct tree is separate from the constructs that you define in your AWS CDK code\. However, it's accessible through any construct's `node` attribute, which is a reference to the node that represents that construct in the tree\. Each node is a [https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Node.html](https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Node.html) instance, the attributes of which provide access to the tree's root and to the node's parent scopes and children\.
92
+
The construct tree is separate from the constructs that you define in your AWS CDK code. However, it's accessible through any construct's `node` attribute, which is a reference to the node that represents that construct in the tree. Each node is a [https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Node.html](https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Node.html) instance, the attributes of which provide access to the tree's root and to the node's parent scopes and children.
93
93
94
-
1.`node.children` – The direct children of the construct\.
94
+
1.`node.children` – The direct children of the construct.
95
95
96
-
1.`node.id` – The identifier of the construct within its scope\.
96
+
1.`node.id` – The identifier of the construct within its scope.
97
97
98
-
1.`node.path` – The full path of the construct including the IDs of all of its parents\.
98
+
1.`node.path` – The full path of the construct including the IDs of all of its parents.
99
99
100
-
1.`node.root` – The root of the construct tree \(the app\)\.
100
+
1.`node.root` – The root of the construct tree (the app).
101
101
102
-
1.`node.scope` – The scope \(parent\) of the construct, or undefined if the node is the root\.
102
+
1.`node.scope` – The scope (parent) of the construct, or undefined if the node is the root.
103
103
104
-
1.`node.scopes` – All parents of the construct, up to the root\.
104
+
1.`node.scopes` – All parents of the construct, up to the root.
105
105
106
-
1.`node.uniqueId` – The unique alphanumeric identifier for this construct within the tree \(by default, generated from `node.path` and a hash\)\.
106
+
1.`node.uniqueId` – The unique alphanumeric identifier for this construct within the tree (by default, generated from `node.path` and a hash).
107
107
108
-
The construct tree defines an implicit order in which constructs are synthesized to resources in the final AWS CloudFormation template\. Where one resource must be created before another, AWS CloudFormation or the AWS Construct Library generally infers the dependency\. They then make sure that the resources are created in the right order\.
108
+
The construct tree defines an implicit order in which constructs are synthesized to resources in the final AWS CloudFormation template. Where one resource must be created before another, AWS CloudFormation or the AWS Construct Library generally infers the dependency. They then make sure that the resources are created in the right order.
109
109
110
-
You can also add an explicit dependency between two nodes by using `node.addDependency()`\. For more information, see [Dependencies](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html#dependencies) in the *AWS CDK API Reference*\.
110
+
You can also add an explicit dependency between two nodes by using `node.addDependency()`. For more information, see [Dependencies](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html#dependencies) in the *AWS CDK API Reference*.
111
111
112
-
The AWS CDK provides a simple way to visit every node in the construct tree and perform an operation on each one\. For more information, see [Aspects and the AWS CDK](aspects.md)\.
112
+
The AWS CDK provides a simple way to visit every node in the construct tree and perform an operation on each one. For more information, see [Aspects and the AWS CDK](aspects.md).
Copy file name to clipboardExpand all lines: v2/aspects.md
+16-16Lines changed: 16 additions & 16 deletions
Original file line number
Diff line number
Diff line change
@@ -1,8 +1,8 @@
1
1
# Aspects and the AWS CDK<aname="aspects"></a>
2
2
3
-
Aspects are a way to apply an operation to all constructs in a given scope\. The aspect could modify the constructs, such as by adding tags\. Or it could verify something about the state of the constructs, such as making sure that all buckets are encrypted\.
3
+
Aspects are a way to apply an operation to all constructs in a given scope. The aspect could modify the constructs, such as by adding tags. Or it could verify something about the state of the constructs, such as making sure that all buckets are encrypted.
4
4
5
-
To apply an aspect to a construct and all constructs in the same scope, call [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Aspects.html#static-ofscope](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Aspects.html#static-ofscope)`.of(SCOPE).add()` with a new aspect, as shown in the following example\.
5
+
To apply an aspect to a construct and all constructs in the same scope, call [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Aspects.html#static-ofscope](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Aspects.html#static-ofscope)`.of(SCOPE).add()` with a new aspect, as shown in the following example.
The AWS CDK uses aspects to [tag resources](tagging.md), but the framework can also be used for other purposes\. For example, you can use it to validate or change the AWS CloudFormation resources that are defined for you by higher\-level constructs\.
51
+
The AWS CDK uses aspects to [tag resources](tagging.md), but the framework can also be used for other purposes. For example, you can use it to validate or change the AWS CloudFormation resources that are defined for you by higher-level constructs.
52
52
53
-
## Aspects in detail<aname="aspects_detail"></a>
53
+
## Aspects in detail<aname="aspects-detail"></a>
54
54
55
-
Aspects employ the [visitor pattern](https://en.wikipedia.org/wiki/Visitor_pattern)\. An aspect is a class that implements the following interface\.
55
+
Aspects employ the [visitor pattern](https://en.wikipedia.org/wiki/Visitor_pattern). An aspect is a class that implements the following interface.
56
56
57
57
------
58
58
#### [ TypeScript ]
@@ -65,12 +65,12 @@ interface IAspect {
65
65
------
66
66
#### [ JavaScript ]
67
67
68
-
JavaScript doesn't have interfaces as a language feature\. Therefore, an aspect is simply an instance of a class having a `visit` method that accepts the node to be operated on\.
68
+
JavaScript doesn't have interfaces as a language feature. Therefore, an aspect is simply an instance of a class having a `visit` method that accepts the node to be operated on.
69
69
70
70
------
71
71
#### [ Python ]
72
72
73
-
Python doesn't have interfaces as a language feature\. Therefore, an aspect is simply an instance of a class having a `visit` method that accepts the node to be operated on\.
73
+
Python doesn't have interfaces as a language feature. Therefore, an aspect is simply an instance of a class having a `visit` method that accepts the node to be operated on.
74
74
75
75
------
76
76
#### [ Java ]
@@ -82,7 +82,7 @@ public interface IAspect {
82
82
```
83
83
84
84
------
85
-
#### [ C\#]
85
+
#### [ C\$1]
86
86
87
87
```
88
88
public interface IAspect
@@ -102,17 +102,17 @@ type IAspect interface {
102
102
103
103
------
104
104
105
-
When you call `Aspects.of(SCOPE).add(...)`, the construct adds the aspect to an internal list of aspects\. You can obtain the list with `Aspects.of(SCOPE)`\.
105
+
When you call `Aspects.of(SCOPE).add(...)`, the construct adds the aspect to an internal list of aspects. You can obtain the list with `Aspects.of(SCOPE)`.
106
106
107
-
During the [prepare phase](deploy.md#deploy-how-synth-app), the AWS CDK calls the `visit` method of the object for the construct and each of its children in top\-down order\.
107
+
During the [prepare phase](deploy.md#deploy-how-synth-app), the AWS CDK calls the `visit` method of the object for the construct and each of its children in top-down order.
108
108
109
-
The `visit` method is free to change anything in the construct\. In strongly typed languages, cast the received construct to a more specific type before accessing construct\-specific properties or methods\.
109
+
The `visit` method is free to change anything in the construct. In strongly typed languages, cast the received construct to a more specific type before accessing construct-specific properties or methods.
110
110
111
-
Aspects don't propagate across `Stage` construct boundaries, because `Stages` are self\-contained and immutable after definition\. Apply aspects on the `Stage` construct itself \(or lower\) if you want them to visit constructs inside the `Stage`\.
111
+
Aspects don't propagate across `Stage` construct boundaries, because `Stages` are self-contained and immutable after definition. Apply aspects on the `Stage` construct itself (or lower) if you want them to visit constructs inside the `Stage`.
112
112
113
-
## Example<aname="aspects_example"></a>
113
+
## Example<aname="aspects-example"></a>
114
114
115
-
The following example validates that all buckets created in the stack have versioning enabled\. The aspect adds an error annotation to the constructs that fail the validation\. This results in the synth operation failing and prevents deploying the resulting cloud assembly\.
115
+
The following example validates that all buckets created in the stack have versioning enabled. The aspect adds an error annotation to the constructs that fail the validation. This results in the synth operation failing and prevents deploying the resulting cloud assembly.
0 commit comments