konokenj.cdk-api-mcp-server 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

cdk_api_mcp_server/resources/aws-cdk/constructs/aws-cdk-lib/aws-synthetics/integ.canary.ts

@@ -0,0 +1,144 @@
+/// !cdk-integ canary-one
+
+import * as path from 'path';
+import * as apigateway from 'aws-cdk-lib/aws-apigateway';
+import * as s3 from 'aws-cdk-lib/aws-s3';
+import * as cdk from 'aws-cdk-lib/core';
+import { Canary, Cleanup, Code, Runtime, Schedule, Test } from 'aws-cdk-lib/aws-synthetics';
+import { ExpectedResult, IntegTest } from '@aws-cdk/integ-tests-alpha';
+import { RemovalPolicy } from 'aws-cdk-lib';
+
+const app = new cdk.App();
+const stack = new cdk.Stack(app, 'canary-one');
+
+const bucket = new s3.Bucket(stack, 'MyTestBucket', {
+  removalPolicy: RemovalPolicy.DESTROY,
+  autoDeleteObjects: true,
+});
+const prefix = 'integ';
+
+const api = new apigateway.RestApi(stack, 'ApiGateway');
+api.root.addMethod('GET', new apigateway.MockIntegration({
+  integrationResponses: [{
+    statusCode: '200',
+  }],
+  passthroughBehavior: apigateway.PassthroughBehavior.NEVER,
+  requestTemplates: {
+    'application/json': '{ "statusCode": 200 }',
+  },
+}), {
+  methodResponses: [{ statusCode: '200' }],
+});
+
+const inlineAsset = new Canary(stack, 'InlineAsset', {
+  test: Test.custom({
+    handler: 'index.handler',
+    code: Code.fromInline(`
+      exports.handler = async () => {
+        console.log(\'hello world\');
+      };`),
+  }),
+  schedule: Schedule.rate(cdk.Duration.minutes(1)),
+  artifactsBucketLocation: { bucket, prefix },
+  runtime: Runtime.SYNTHETICS_NODEJS_PUPPETEER_7_0,
+  cleanup: Cleanup.LAMBDA,
+});
+
+const directoryAsset = new Canary(stack, 'DirectoryAsset', {
+  test: Test.custom({
+    handler: 'canary.handler',
+    code: Code.fromAsset(path.join(__dirname, 'canaries')),
+  }),
+  runtime: Runtime.SYNTHETICS_NODEJS_PUPPETEER_7_0,
+  environmentVariables: {
+    URL: api.url,
+  },
+  cleanup: Cleanup.LAMBDA,
+});
+
+const folderAsset = new Canary(stack, 'FolderAsset', {
+  test: Test.custom({
+    handler: 'folder/canary.functionName',
+    code: Code.fromAsset(path.join(__dirname, 'canaries')),
+  }),
+  runtime: Runtime.SYNTHETICS_NODEJS_PUPPETEER_7_0,
+  environmentVariables: {
+    URL: api.url,
+  },
+  cleanup: Cleanup.LAMBDA,
+});
+
+const zipAsset = new Canary(stack, 'ZipAsset', {
+  test: Test.custom({
+    handler: 'canary.handler',
+    code: Code.fromAsset(path.join(__dirname, 'canary.zip')),
+  }),
+  artifactsBucketLifecycleRules: [
+    {
+      expiration: cdk.Duration.days(30),
+    },
+  ],
+  runtime: Runtime.SYNTHETICS_NODEJS_PUPPETEER_7_0,
+  cleanup: Cleanup.LAMBDA,
+});
+
+const kebabToPascal = (text:string) => text.replace(/(^\w|[-./]\w)/g, (v) => v.replace(/[-./]/, '').toUpperCase());
+const createCanaryByRuntimes = (runtime: Runtime, handler?: string) =>
+  new Canary(stack, kebabToPascal(runtime.name + (handler ?? '')), {
+    test: Test.custom({
+      handler: handler ?? 'canary.handler',
+      code: Code.fromAsset(path.join(__dirname, 'canaries')),
+    }),
+    environmentVariables: {
+      URL: api.url,
+    },
+    runtime,
+    cleanup: Cleanup.LAMBDA,
+  });
+
+const puppeteer52 = createCanaryByRuntimes(Runtime.SYNTHETICS_NODEJS_PUPPETEER_5_2);
+const puppeteer62 = createCanaryByRuntimes(Runtime.SYNTHETICS_NODEJS_PUPPETEER_6_2);
+const puppeteer70 = createCanaryByRuntimes(Runtime.SYNTHETICS_NODEJS_PUPPETEER_7_0);
+const puppeteer80 = createCanaryByRuntimes(Runtime.SYNTHETICS_NODEJS_PUPPETEER_8_0);
+const puppeteer90 = createCanaryByRuntimes(Runtime.SYNTHETICS_NODEJS_PUPPETEER_9_0);
+const puppeteer91 = createCanaryByRuntimes(Runtime.SYNTHETICS_NODEJS_PUPPETEER_9_1);
+const playwright10 = createCanaryByRuntimes(Runtime.SYNTHETICS_NODEJS_PLAYWRIGHT_1_0);
+const playwright10_with_handler_name = createCanaryByRuntimes(Runtime.SYNTHETICS_NODEJS_PLAYWRIGHT_1_0, 'playwright/canary.handler');
+
+const selenium21 = createCanaryByRuntimes(Runtime.SYNTHETICS_PYTHON_SELENIUM_2_1);
+const selenium30 = createCanaryByRuntimes(Runtime.SYNTHETICS_PYTHON_SELENIUM_3_0);
+const selenium40 = createCanaryByRuntimes(Runtime.SYNTHETICS_PYTHON_SELENIUM_4_0);
+const selenium41 = createCanaryByRuntimes(Runtime.SYNTHETICS_PYTHON_SELENIUM_4_1);
+const selenium50 = createCanaryByRuntimes(Runtime.SYNTHETICS_PYTHON_SELENIUM_5_0);
+const selenium51 = createCanaryByRuntimes(Runtime.SYNTHETICS_PYTHON_SELENIUM_5_1);
+
+const test = new IntegTest(app, 'IntegCanaryTest', {
+  testCases: [stack],
+});
+
+// Assertion that all Canary's are Passed
+[
+  inlineAsset,
+  directoryAsset,
+  folderAsset,
+  zipAsset,
+  puppeteer52,
+  puppeteer62,
+  puppeteer70,
+  puppeteer80,
+  puppeteer90,
+  puppeteer91,
+  playwright10,
+  playwright10_with_handler_name,
+  selenium21,
+  selenium30,
+  selenium40,
+  selenium41,
+  selenium50,
+  selenium51,
+].forEach((canary) => test.assertions
+  .awsApiCall('Synthetics', 'getCanaryRuns', {
+    Name: canary.canaryName,
+  })
+  .assertAtPath('CanaryRuns.0.Status.State', ExpectedResult.stringLikeRegexp('PASSED'))
+  .waitForAssertions({ totalTimeout: cdk.Duration.minutes(5) }));

cdk_api_mcp_server/resources/aws-cdk/constructs/aws-cdk-lib/aws-synthetics/integ.vpc.ts

@@ -0,0 +1,29 @@
+/// !cdk-integ canary-vpc
+
+import * as path from 'path';
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import * as cdk from 'aws-cdk-lib/core';
+import * as synthetics from 'aws-cdk-lib/aws-synthetics';
+
+/*
+ * Stack verification steps:
+ *
+ * -- aws synthetics get-canary --name canary-vpc has state of 'RUNNING'
+ * -- aws synthetics get-canary --name canary-vpc has VpcId
+ */
+const app = new cdk.App();
+const stack = new cdk.Stack(app, 'canary-vpc');
+
+const vpc = new ec2.Vpc(stack, 'MyVpc', { maxAzs: 2, restrictDefaultSecurityGroup: false });
+
+new synthetics.Canary(stack, 'MyVpcCanary', {
+  canaryName: 'canary-vpc',
+  test: synthetics.Test.custom({
+    handler: 'canary.handler',
+    code: synthetics.Code.fromAsset(path.join(__dirname, 'canary.zip')),
+  }),
+  runtime: synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_3_8,
+  vpc,
+});
+
+app.synth();

cdk_api_mcp_server/resources/aws-cdk/constructs/aws-cdk-lib/cloud-assembly-schema/README.md

@@ -0,0 +1,55 @@
+# Cloud Assembly Schema
+
+This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.
+
+## Cloud Assembly
+
+The _Cloud Assembly_ is the output of the synthesis operation. It is produced as part of the
+[`cdk synth`](https://github.com/aws/aws-cdk/tree/main/packages/aws-cdk#cdk-synthesize)
+command, or the [`app.synth()`](https://github.com/aws/aws-cdk/blob/main/packages/@aws-cdk/core/lib/app.ts#L135) method invocation.
+
+Its essentially a set of files and directories, one of which is the `manifest.json` file. It defines the set of instructions that are
+needed in order to deploy the assembly directory.
+
+> For example, when `cdk deploy` is executed, the CLI reads this file and performs its instructions:
+>
+> - Build container images.
+> - Upload assets.
+> - Deploy CloudFormation templates.
+
+Therefore, the assembly is how the CDK class library and CDK CLI (or any other consumer) communicate. To ensure compatibility
+between the assembly and its consumers, we treat the manifest file as a well defined, versioned schema.
+
+## Schema
+
+This module contains the typescript structs that comprise the `manifest.json` file, as well as the
+generated [_json-schema_](./schema/cloud-assembly.schema.json).
+
+## Versioning
+
+The schema version is specified my the major version of the package release. It follows semantic versioning, but with a small twist.
+
+When we add instructions to the assembly, they are reflected in the manifest file and the _json-schema_ accordingly.
+Every such instruction, is crucial for ensuring the correct deployment behavior. This means that to properly deploy a cloud assembly,
+consumers must be aware of every such instruction modification.
+
+For this reason, every change to the schema, even though it might not strictly break validation of the _json-schema_ format,
+is considered `major` version bump. All changes that do not impact the schema are considered a `minor` version bump.
+
+## How to consume
+
+If you'd like to consume the [schema file](./schema/cloud-assembly.schema.json) in order to do validations on `manifest.json` files,
+simply download it from this repo and run it against standard _json-schema_ validators, such as [jsonschema](https://www.npmjs.com/package/jsonschema).
+
+Consumers must take into account the `major` version of the schema they are consuming. They should reject cloud assemblies
+with a `major` version that is higher than what they expect. While schema validation might pass on such assemblies, the deployment integrity
+cannot be guaranteed because some instructions will be ignored.
+
+> For example, if your consumer was built when the schema version was 2.0.0, you should reject deploying cloud assemblies with a
+> manifest version of 3.0.0.
+
+## Contributing
+
+The source code for this file has been moved to CDKLabs.
+
+See [Contribution Guide](https://github.com/cdklabs/cloud-assembly-schema/blob/main/CONTRIBUTING.md)

cdk_api_mcp_server/resources/aws-cdk/constructs/aws-cdk-lib/cloudformation-include/README.md

@@ -0,0 +1,468 @@
+# Include CloudFormation templates in the CDK
+
+
+
+This module contains a set of classes whose goal is to facilitate working
+with existing CloudFormation templates in the CDK.
+It can be thought of as an extension of the capabilities of the
+[`CfnInclude` class](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_core.CfnInclude.html).
+
+## Basic usage
+
+Assume we have a file with an existing template.
+It could be in JSON format, in a file `my-template.json`:
+
+```json
+{
+  "Resources": {
+    "Bucket": {
+      "Type": "AWS::S3::Bucket",
+      "Properties": {
+        "BucketName": "amzn-s3-demo-bucket"
+      }
+    }
+  }
+}
+```
+
+Or it could by in YAML format, in a file `my-template.yaml`:
+
+```yaml
+Resources:
+  Bucket:
+    Type: AWS::S3::Bucket
+    Properties:
+      BucketName: amzn-s3-demo-bucket
+```
+
+It can be included in a CDK application with the following code:
+
+```ts
+const cfnTemplate = new cfn_inc.CfnInclude(this, 'Template', {
+  templateFile: 'my-template.json',
+});
+```
+
+Or, if your template uses YAML:
+
+```ts
+const cfnTemplate = new cfn_inc.CfnInclude(this, 'Template', {
+  templateFile: 'my-template.yaml',
+});
+```
+
+**Note**: different YAML parsers sometimes don't agree on what exactly constitutes valid YAML.
+If you get a YAML exception when including your template,
+try converting it to JSON, and including that file instead.
+If you're downloading your template from the CloudFormation AWS Console,
+you can easily get it in JSON format by clicking the 'View in Designer'
+button on the 'Template' tab -
+once in Designer, select JSON in the "Choose template language"
+radio buttons on the bottom pane.
+
+This will add all resources from `my-template.json` / `my-template.yaml` into the CDK application,
+preserving their original logical IDs from the template file.
+
+Any resource from the included template can be retrieved by referring to it by its logical ID from the template.
+If you know the class of the CDK object that corresponds to that resource,
+you can cast the returned object to the correct type:
+
+```ts
+declare const cfnTemplate: cfn_inc.CfnInclude;
+const cfnBucket = cfnTemplate.getResource('Bucket') as s3.CfnBucket;
+// cfnBucket is of type s3.CfnBucket
+```
+
+Note that any resources not present in the latest version of the CloudFormation schema
+at the time of publishing the version of this module that you depend on,
+including [Custom Resources](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cfn-customresource.html),
+will be returned as instances of the class `CfnResource`,
+and so cannot be cast to a different resource type.
+
+Any modifications made to that resource will be reflected in the resulting CDK template;
+for example, the name of the bucket can be changed:
+
+```ts
+declare const cfnTemplate: cfn_inc.CfnInclude;
+const cfnBucket = cfnTemplate.getResource('Bucket') as s3.CfnBucket;
+cfnBucket.bucketName = 'amzn-s3-demo-bucket';
+```
+
+You can also refer to the resource when defining other constructs,
+including the higher-level ones
+(those whose name does not start with `Cfn`),
+for example:
+
+```ts
+declare const cfnTemplate: cfn_inc.CfnInclude;
+const cfnBucket = cfnTemplate.getResource('Bucket') as s3.CfnBucket;
+
+const role = new iam.Role(this, 'Role', {
+  assumedBy: new iam.AnyPrincipal(),
+});
+role.addToPolicy(new iam.PolicyStatement({
+  actions: ['s3:*'],
+  resources: [cfnBucket.attrArn],
+}));
+```
+
+## Migrating templates that use Transforms
+
+You can use this module to migrate templates that use
+[CloudFormation transforms](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-macros.html) -
+including the [Serverless transform](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/transform-aws-serverless.html).
+
+The CDK including process does not execute Transforms,
+and the `cdk diff` command by default compares against the original
+(meaning, unprocessed) template.
+So, if you're downloading the template to include from the CloudFormation AWS Console,
+make sure to download the unprocessed template
+(the "View processed template" checkbox is left **unchecked**, which is the default):
+
+![unprocessed template in the CloudFormation AWS Console](doc-images/unprocessed-template.png)
+
+However, certain unprocessed templates can fail when used with the `CfnInclude` class.
+The most common reason for the failure is that the unprocessed template can contain cycles between resources,
+which get removed after the Transform is processed,
+but is not allowed when being included (as pure CloudFormation does not permit cycles). To enable cycle processing behavior similar
+to cloudformation, set `allowCyclicalReferences` of CfnIncludeProps to true.
+
+
+When that happens, you should instead download the processed template from the CloudFormation AWS Console
+(make sure the "View processed template" checkbox is **checked** in that case):
+
+![processed template in the CloudFormation AWS Console](doc-images/processed-template.png)
+
+When you include that processed template in your CDK application,
+running `cdk diff` will now show a lot of differences with the deployed Stack,
+because `cdk diff` uses the unprocessed template by default.
+To alleviate that problem, you can pass the `--processed` switch to `cdk diff`,
+which will make the diff command compare against the processed template of the deployed Stack,
+which will give more precise results in this case.
+
+## Converting L1 resources to L2
+
+The resources the `getResource` method returns are what the CDK calls
+[Layer 1 resources](https://docs.aws.amazon.com/cdk/latest/guide/cfn_layer.html#cfn_layer_cfn)
+(like `CfnBucket`).
+However, in many places in the Construct Library,
+the CDK requires so-called Layer 2 resources, like `IBucket`.
+There are two ways of going from an L1 to an L2 resource.
+
+### Using`fromCfn*()` methods
+
+This is the preferred method of converting an L1 resource to an L2.
+It works by invoking a static method of the class of the L2 resource
+whose name starts with `fromCfn` -
+for example, for KMS Keys, that would be the `Kms.fromCfnKey()` method -
+and passing the L1 instance as an argument:
+
+```ts
+declare const cfnTemplate: cfn_inc.CfnInclude;
+const cfnKey = cfnTemplate.getResource('Key') as kms.CfnKey;
+const key = kms.Key.fromCfnKey(cfnKey);
+```
+
+This returns an instance of the `kms.IKey` type that can be passed anywhere in the CDK an `IKey` is expected.
+What is more, that `IKey` instance will be mutable -
+which means calling any mutating methods on it,
+like `addToResourcePolicy()`,
+will be reflected in the resulting template.
+
+Note that, in some cases, the `fromCfn*()` method might not be able to create an L2 from the underlying L1.
+This can happen when the underlying L1 heavily uses CloudFormation functions.
+For example, if you tried to create an L2 `IKey`
+from an L1 represented as this CloudFormation template:
+
+```json
+{
+  "Resources": {
+    "Key": {
+      "Type": "AWS::KMS::Key",
+      "Properties": {
+        "KeyPolicy": {
+          "Statement": [
+            {
+              "Fn::If": [
+                "Condition",
+                {
+                  "Action": "kms:if-action",
+                  "Resource": "*",
+                  "Principal": "*",
+                  "Effect": "Allow"
+                },
+                {
+                  "Action": "kms:else-action",
+                  "Resource": "*",
+                  "Principal": "*",
+                  "Effect": "Allow"
+                }
+              ]
+            }
+          ],
+          "Version": "2012-10-17"
+        }
+      }
+    }
+  }
+}
+```
+
+The `Key.fromCfnKey()` method does not know how to translate that into CDK L2 concepts,
+and would throw an exception.
+
+In those cases, you need the use the second method of converting an L1 to an L2.
+
+### Using `from*Name/Arn/Attributes()` methods
+
+If the resource you need does not have a `fromCfn*()` method,
+or if it does, but it throws an exception for your particular L1,
+you need to use the second method of converting an L1 resource to L2.
+
+Each L2 class has static factory methods with names like `from*Name()`,
+`from*Arn()`, and/or `from*Attributes()`.
+You can obtain an L2 resource from an L1 by passing the correct properties of the L1 as the arguments to those methods:
+
+```ts
+declare const cfnTemplate: cfn_inc.CfnInclude;
+
+// using from*Name()
+const cfnBucket = cfnTemplate.getResource('Bucket') as s3.CfnBucket;
+const bucket = s3.Bucket.fromBucketName(this, 'L2Bucket', cfnBucket.ref);
+
+// using from*Arn()
+const cfnKey = cfnTemplate.getResource('Key') as kms.CfnKey;
+const key = kms.Key.fromKeyArn(this, 'L2Key', cfnKey.attrArn);
+
+// using from*Attributes()
+declare const privateCfnSubnet1: ec2.CfnSubnet;
+declare const privateCfnSubnet2: ec2.CfnSubnet;
+const cfnVpc = cfnTemplate.getResource('Vpc') as ec2.CfnVPC;
+const vpc = ec2.Vpc.fromVpcAttributes(this, 'L2Vpc', {
+  vpcId: cfnVpc.ref,
+  availabilityZones: core.Fn.getAzs(),
+  privateSubnetIds: [privateCfnSubnet1.ref, privateCfnSubnet2.ref],
+});
+```
+
+As long as they just need to be referenced,
+and not changed in any way, everything should work;
+however, note that resources returned from those methods,
+unlike those returned by `fromCfn*()` methods,
+are immutable, which means calling any mutating methods on them will have no effect.
+You will have to mutate the underlying L1 in order to change them.
+
+## Non-resource template elements
+
+In addition to resources,
+you can also retrieve and mutate all other template elements:
+
+* [Parameters](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html):
+
+  ```ts
+  declare const cfnTemplate: cfn_inc.CfnInclude;
+  const param: core.CfnParameter = cfnTemplate.getParameter('MyParameter');
+
+  // mutating the parameter
+  param.default = 'MyDefault';
+  ```
+
+* [Conditions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/conditions-section-structure.html):
+
+  ```ts
+  declare const cfnTemplate: cfn_inc.CfnInclude;
+  const condition: core.CfnCondition = cfnTemplate.getCondition('MyCondition');
+
+  // mutating the condition
+  condition.expression = core.Fn.conditionEquals(1, 2);
+  ```
+
+* [Mappings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/mappings-section-structure.html):
+
+  ```ts
+  declare const cfnTemplate: cfn_inc.CfnInclude;
+  const mapping: core.CfnMapping = cfnTemplate.getMapping('MyMapping');
+
+  // mutating the mapping
+  mapping.setValue('my-region', 'AMI', 'ami-04681a1dbd79675a5');
+  ```
+
+* [Service Catalog template Rules](https://docs.aws.amazon.com/servicecatalog/latest/adminguide/reference-template_constraint_rules.html):
+
+  ```ts
+  declare const cfnTemplate: cfn_inc.CfnInclude;
+  const rule: core.CfnRule = cfnTemplate.getRule('MyRule');
+
+  // mutating the rule
+  declare const myParameter: core.CfnParameter;
+  rule.addAssertion(core.Fn.conditionContains(['m1.small'], myParameter.valueAsString),
+    'MyParameter has to be m1.small');
+  ```
+
+* [Outputs](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html):
+
+  ```ts
+  declare const cfnTemplate: cfn_inc.CfnInclude;
+  const output: core.CfnOutput = cfnTemplate.getOutput('MyOutput');
+
+  // mutating the output
+  declare const cfnBucket: s3.CfnBucket;
+  output.value = cfnBucket.attrArn;
+  ```
+
+* [Hooks for blue-green deployments](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/blue-green.html):
+
+  ```ts
+  declare const cfnTemplate: cfn_inc.CfnInclude;
+  const hook: core.CfnHook = cfnTemplate.getHook('MyOutput');
+
+  // mutating the hook
+  declare const myRole: iam.Role;
+  const codeDeployHook = hook as core.CfnCodeDeployBlueGreenHook;
+  codeDeployHook.serviceRole = myRole.roleArn;
+  ```
+
+## Parameter replacement
+
+If your existing template uses CloudFormation Parameters,
+you may want to remove them in favor of build-time values.
+You can do that using the `parameters` property:
+
+```ts
+new cfn_inc.CfnInclude(this, 'includeTemplate', {
+  templateFile: 'path/to/my/template',
+  parameters: {
+    'MyParam': 'my-value',
+  },
+});
+```
+
+This will replace all references to `MyParam` with the string `'my-value'`,
+and `MyParam` will be removed from the 'Parameters' section of the resulting template.
+
+## Nested Stacks
+
+This module also supports templates that use [nested stacks](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-nested-stacks.html).
+
+For example, if you have the following parent template:
+
+```json
+{
+  "Resources": {
+    "ChildStack": {
+      "Type": "AWS::CloudFormation::Stack",
+      "Properties": {
+        "TemplateURL": "https://my-s3-template-source.s3.amazonaws.com/child-stack.json"
+      }
+    }
+  }
+}
+```
+
+where the child template pointed to by `https://my-s3-template-source.s3.amazonaws.com/child-stack.json` is:
+
+```json
+{
+  "Resources": {
+    "MyBucket": {
+      "Type": "AWS::S3::Bucket"
+    }
+  }
+}
+```
+
+You can include both the parent stack,
+and the nested stack in your CDK application as follows:
+
+```ts
+const parentTemplate = new cfn_inc.CfnInclude(this, 'ParentStack', {
+  templateFile: 'path/to/my-parent-template.json',
+  loadNestedStacks: {
+    'ChildStack': {
+      templateFile: 'path/to/my-nested-template.json',
+    },
+  },
+});
+```
+
+Here, `path/to/my-nested-template.json`
+represents the path on disk to the downloaded template file from the original template URL of the nested stack
+(`https://my-s3-template-source.s3.amazonaws.com/child-stack.json`).
+In the CDK application,
+this file will be turned into an [Asset](https://docs.aws.amazon.com/cdk/latest/guide/assets.html),
+and the `TemplateURL` property of the nested stack resource
+will be modified to point to that asset.
+
+The included nested stack can be accessed with the `getNestedStack` method:
+
+```ts
+declare const parentTemplate: cfn_inc.CfnInclude;
+
+const includedChildStack = parentTemplate.getNestedStack('ChildStack');
+const childStack: core.NestedStack = includedChildStack.stack;
+const childTemplate: cfn_inc.CfnInclude = includedChildStack.includedTemplate;
+```
+
+Now you can reference resources from `ChildStack`,
+and modify them like any other included template:
+
+```ts
+declare const childTemplate: cfn_inc.CfnInclude;
+
+const cfnBucket = childTemplate.getResource('MyBucket') as s3.CfnBucket;
+cfnBucket.bucketName = 'amzn-s3-demo-bucket1';
+
+const role = new iam.Role(this, 'MyRole', {
+  assumedBy: new iam.AccountRootPrincipal(),
+});
+
+role.addToPolicy(new iam.PolicyStatement({
+  actions: [
+    's3:GetObject*',
+    's3:GetBucket*',
+    's3:List*',
+  ],
+  resources: [cfnBucket.attrArn],
+}));
+```
+
+You can also include the nested stack after the `CfnInclude` object was created,
+instead of doing it on construction:
+
+```ts
+declare const parentTemplate: cfn_inc.CfnInclude;
+const includedChildStack = parentTemplate.loadNestedStack('ChildTemplate', {
+  templateFile: 'path/to/my-nested-template.json',
+});
+```
+
+## Vending CloudFormation templates as Constructs
+
+In many cases, there are existing CloudFormation templates that are not entire applications,
+but more like specialized fragments, implementing a particular pattern or best practice.
+If you have templates like that,
+you can use the `CfnInclude` class to vend them as CDK Constructs:
+
+```ts nofixture
+import { Construct } from 'constructs';
+import * as cfn_inc from 'aws-cdk-lib/cloudformation-include';
+import * as path from 'path';
+
+export class MyConstruct extends Construct {
+  constructor(scope: Construct, id: string) {
+    super(scope, id);
+
+    // include a template inside the Construct
+    new cfn_inc.CfnInclude(this, 'MyConstruct', {
+      templateFile: path.join(__dirname, 'my-template.json'),
+      preserveLogicalIds: false, // <--- !!!
+    });
+  }
+}
+```
+
+Notice the `preserveLogicalIds` parameter -
+it makes sure the logical IDs of all the included template elements are re-named using CDK's algorithm,
+guaranteeing they are unique within your application.
+Without that parameter passed,
+instantiating `MyConstruct` twice in the same Stack would result in duplicated logical IDs.