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/core/acknowledge-warnings.md

@@ -0,0 +1,148 @@
+# Acknowledge Warnings
+
+## Status
+
+accepted
+
+## Context
+
+Construct authors can add messages that will be printed at synthesis. It
+possible to add three types of warnings:
+
+- `INFO`: Prints the info on synthesis
+- `WARN`: Prints the warning on synthesis. Can also throw an error if the `--strict`
+  argument is used
+- `ERROR`: Throws an error with the message
+
+Warning messages are typically used for two types of messages:
+
+1. Things that are errors (and will error on deployment) in some cases, but not all. For example, a warning is
+   used when > 10 managed policies are added to an IAM Role because that is the
+   initial limit for AWS accounts. An error is not used because it is possible
+   to increase the limit.
+2. Things that are not errors (and will deploy successfully), but might be
+   sub-optimal configuration. For example, a warning is used when an Serverless
+   V2 Aurora cluster is created and no reader instances are created in tiers
+   0-1. This is a valid configuration, but could cause availability issues in
+   certain scenarios.
+
+Users who are developing CDK applications may want to always use the `--strict`
+CLI argument to turn all warnings into errors. Currently this is not
+possible since as soon as one warning is not applicable they can no longer use
+`--strict`. Ideally they should be able to `acknowledge` warnings (similar to
+what they can do with notices) indicating that the warning is not applicable to
+them/they acknowledge the risk.
+
+```ts
+Annotations.of(this).acknowledgeWarning(
+  '@aws-cdk/aws-iam:maxPoliciesExceeded',
+  'A limit increase has been submitted',
+);
+```
+
+This would allow acknowledgements to live alongside the code so all developers
+on the code base would have the information readily available. This also allows
+the acknowledgement to be added at a certain `scope` and apply to all child
+constructs. Users would be able to acknowledge certain warnings for the entire
+app, or for a specific scope.
+
+## Constraints
+
+Warnings are currently added with the `Annotations` API.
+
+```ts
+Annotations.of(scope).addWarning('This is a warning');
+```
+
+`Annotations.of(scope)` creates a new instance of `Annotations` every time so
+there is no way to keep track of warnings added inside this object.
+
+Currently the storage mechanism for `Annotations` is the `Node` metadata. The
+warning is added to the node as node metadata which is read by the CLI after
+synthesis to print out the messages. This means that Annotations can be added
+during `synthesis`.
+
+Another constraint is that currently you add a warning with only the message.
+There is no unique identifier. This means that to add an acknowledgement the
+user would need to copy the entire message.
+
+## Decision
+
+We will deprecate the `addWarning` method and add a new method `addWarningV2`
+
+```ts
+  /**
+   * @param id the unique identifier for the warning. This can be used to acknowledge the warning
+   * @param message The warning message.
+   */
+  public addWarningV2(id: string, message: string): void
+```
+
+We will add a new method `acknowledgeWarning` that will allow users to
+acknowledge a specific warning by `id`.
+
+```ts
+  /**
+   * @param id - the id of the warning message to acknowledge
+   * @param message optional message to explain the reason for acknowledgement
+   */
+  public acknowledgeWarning(id: string, message?: string): void
+```
+
+We want warning acknowledgement to work both before and after the warning is actually emitted.
+
+We therefore do the following:
+
+- When a warning is acknowledged on a construct, we iterate over the already
+  added warnings and remove matching warnings. At the same time, we record
+  that this warning has been acknowledged on this construct tree.
+- When a warning is added, we only add it if it hasn't been acknowledged in
+  that location.
+
+## Alternatives
+
+### Filter at synthesis time
+
+Right now, we are filtering in every method call. We could defer the filtering
+to when we translate construct tree metadata to cloud assembly metadata.
+
+Right now, removing existing metadata entries requires accessing private APIs
+of the `constructs` library, which is not an ideal situation.
+
+At the same time, implementing it there would allow us to generate a suppression
+report. We can always still do this.
+
+### Use context and remove metadata
+
+Another alternative that was considered was to use context to set
+acknowledgements. This would look something like this:
+
+```ts
+public acknowledgeWarning(id: string, message?: string) {
+  this.scope.node.setContext(id, message ?? true); // can't do this today
+  this.scope.node.removeMetadata(id); // this method does not exist
+}
+public addWarningV2(id: string, message: string) {
+  if (this.scope.node.tryGetContext(id) === undefined) {
+    this.addMessage(...);
+  }
+}
+```
+
+There are two issues with this alternative.
+
+1. It is currently not possible to `node.setContext` once children are added. We
+   would have to first remove that limitation. I think this could lead to a lot
+   of issues where users have to keep track of _when_ context is added.
+2. We would have to implement the ability to `removeMetadata` from a node. This
+   functionality doesn't make much sense outside of this context (can't find
+   where anybody has asked for it). It also may require updating the metadata
+   types since currently there is no unique identifier for a given metadata
+   entry (other than the message).
+
+
+### Acknowledge via context
+
+There is currently no way to configure suppressed warnings via context, which
+might be useful to do at the application level (using `cdk.json`). We can always
+add this feature in the future if desired.

cdk_api_mcp_server/resources/aws-cdk/constructs/aws-cdk-lib/core/cross-region-stack-references.md

@@ -0,0 +1,270 @@
+# Cross Region Stack References
+
+## Status
+
+accepted
+
+## Context
+
+The CDK allows for you to natively (in code) reference resources between stacks. For example:
+
+```ts
+const bucket = new s3.Bucket(stack1, 'Bucket');
+const handler = new lambda.Function(stack2, 'Handler');
+bucket.grantRead(handler);
+```
+
+Here we have create an S3 bucket in one stack and natively referenced the bucket from a resource
+in a different stack. This works because CDK knows that this is a cross stack reference and will create the
+appropriate stack exports and imports. In this case it would create an `Export` in `stack1`.
+
+```json
+{
+ "Outputs": {
+  "ExportsOutputFnGetAttBucket83908E77Arn063C8555": {
+   "Value": {
+    "Fn::GetAtt": [
+     "Bucket83908E77",
+     "Arn"
+    ]
+   },
+   "Export": {
+    "Name": "stack1:ExportsOutputFnGetAttBucket83908E77Arn063C8555"
+   }
+  }
+ }
+}
+```
+
+And an "Import" in stack2
+
+```json
+{
+  "Resources": {
+    "HandlerServiceRoleDefaultPolicyCBD0CC91": {
+       "Type": "AWS::IAM::Policy",
+       "Properties": {
+         "PolicyDocument": {
+           "Statement": [
+              {
+                "Action": [
+                  "s3:GetBucket*",
+                  "s3:GetObject*",
+                  "s3:List*"
+                ],
+                "Effect": "Allow",
+                "Resource": [
+                  {
+                    "Fn::ImportValue": "stack1:ExportsOutputFnGetAttBucket83908E77Arn063C8555"
+                  },
+                  {
+                    "Fn::Join": [
+                      "",
+                      [
+                        {
+                          "Fn::ImportValue": "stack1:ExportsOutputFnGetAttBucket83908E77Arn063C8555"
+                        },
+                        "/*"
+                      ]
+                    ]
+                  }
+                ]
+              }
+           ],
+         "Version": "2012-10-17"
+         },
+         "PolicyName": "HandlerServiceRoleDefaultPolicyCBD0CC91",
+         "Roles": [
+           {
+             "Ref": "HandlerServiceRoleFCDC14AE"
+           }
+         ]
+       }
+    }
+  }
+}
+```
+
+If these stack exist in different regions this is no longer possible. This is due to
+an underlying limitation with CloudFormation, namely that Stack Exports/Imports do not
+work cross-region. There are some cases where cross region references are _required_
+by the AWS services themselves. A good example of this is AWS CloudFront. CloudFront is a global
+service and you can create a CloudFront distribution via CloudFormation in any AWS Region. Other
+resources that are used by CloudFront are required to be created in the `us-east-1` region.
+
+For example, lets say you have an application that you created in `us-east-2`.
+
+```ts
+const appStack = new Stack(app, 'AppStack', { env: { region: 'us-east-2' } });
+const service = new ApplicationLoadBalancedFargateService(appStack, 'Service');
+```
+
+If I want to add CloudFront to this application. I can add the distribution in the
+same Stack, but if I also want to add a ACM Certificate (why wouldn't I?) it becomes
+more difficult. In order to use a ACM Certificate with CloudFront, the certificate
+must be created in `us-east-1` regardless of what region you create the CloudFront
+distribution from.
+
+```ts
+const appStack = new Stack(app, 'AppStack', { env: { region: 'us-east-2' } });
+const service = new ApplicationLoadBalancedFargateService(appStack, 'Service');
+
+// this won't work!!!
+const certificate = new acm.Certificate(appStack, 'Cert');
+const distribution = new Distribution(appStack, 'Distribution', {
+  defaultBehavior: { origin: new LoadBalancerV2Origin(service.loadBalancer) },
+  certificate,
+});
+```
+
+To workaround this issue we have created things like the `DnsValidatedCertificate` construct
+which uses custom resources to create the certificate in `us-east-1`. This requires us
+to essentially maintain our own `Certificate` resource that maintains feature parity with the
+official `AWS::CertificateManager::Certificate` resource.
+
+Another example is the `aws-cloudfront.experimental` `EdgeFunction` construct. This takes
+a different approach to managing cross region resources. Instead of creating the resources with
+a custom resource, we instead create a support stack in `us-east-1` which creates the lambda
+function. We then use a custom resource to "lookup" the function arn in the Stack that creates the
+CloudFront distribution. This is becoming our recommended pattern for creating cross-region
+resources, so why not add an officially supported method for doing this.
+
+## Constraints
+
+The biggest constraint with implementing a solution is CloudFormation itself. A common
+request from CDK users is for the CDK to support [weak
+references](https://github.com/aws/aws-cdk-rfcs/issues/82). The reason we have not yet implemented
+this feature is that there are good reasons as to why strong references exist and are the only
+officially supported method.
+
+Let's walk through an example to illustrate. Suppose I had a Lambda function that referenced an S3
+bucket in some way (read data, write data, etc). CloudFormation will create a "strong" reference
+between these two resources.
+
+```ts
+const bucket = new s3.Bucket(stack1, 'Bucket', {
+  bucketName: 'amzn-s3-demo-bucket',
+});
+const handler = new lambda.Function(stack2, 'Handler', {
+  environment: {
+    BUCKET_NAME: bucket.bucketName,
+  },
+});
+bucket.grantRead(handler);
+```
+
+If I tried to update the bucket, for example changing the name from `amzn-s3-demo-bucket` to `amzn-s3-demo-bucket1`
+CloudFormation will fail the deployment for stack1 and prevent the bucket from being recreated. This
+is because it _knows_ that `stack2` is using the bucket. If it allows the bucket to change and the
+export to change you could end up in an unrecoverable state for `stack2`.
+
+```mermaid
+sequenceDiagram
+    Note over Stack1,Stack2: Initial Deployment
+    activate Stack2
+    Note over Stack1: Create export amzn-s3-demo-bucket
+    Stack2->>+Stack1: Read export amzn-s3-demo-bucket
+    Note over Stack2: Create Function
+    deactivate Stack2
+    Note over Stack1,Stack2: Second Deployment
+    activate Stack2
+    Note over Stack1: Delete export amzn-s3-demo-bucket
+    Note over Stack1: Create export amzn-s3-demo-bucket1
+    Stack2->>+Stack1: Read export amzn-s3-demo-bucket1
+    deactivate Stack2
+    Note over Stack2: Update Function Failed!
+    Stack2-->>+Stack2: Rollback
+    activate Stack2
+    Stack2->>+Stack1: Read export amzn-s3-demo-bucket
+    Note right of Stack1: Export doesn't exist!
+    deactivate Stack2
+    Note over Stack2: Stack rollback failed!
+    Note over Stack1,Stack2: We're stuck!!  
+```
+
+For the CDK to implement it's own concept of references it needs to take this into account.
+
+### Custom Resources
+
+This solution utilizes custom resources to manage outputs/imports, and custom resources come with
+their own constraints.
+
+- Custom resources are only executed when the properties change. There is no way to have the
+	resource execute on every deploy.
+
+- Custom resources only know about the current update (via `ResourceProperties`) and the previous update
+	(via `OldResourceProperties`). Custom resources cannot keep track of all prior updates, unless
+	we were to implement some external state mechanism.
+
+
+## Decision
+
+The CDK will natively support cross region stack references.
+
+```ts
+const appStack = new Stack(app, 'AppStack', { env: { region: 'us-east-2' } });
+const service = new ApplicationLoadBalancedFargateService(appStack, 'Service');
+
+// this will work!!!
+const certificate = new acm.Certificate(appStack, 'Cert');
+const distribution = new Distribution(appStack, 'Distribution', {
+  defaultBehavior: { origin: new LoadBalancerV2Origin(service.loadBalancer) },
+  certificate,
+});
+```
+
+Since it is not natively supported by CloudFormation we will use CloudFormation custom resources to
+perform the output/import. This behavior will not be enabled by default and will be controlled by an
+optional Stack property.
+
+```ts
+new Stack(app, 'MyStack', {
+  crossRegionReferences: true,
+});
+```
+
+### Outputs
+
+In order to "output" the value from the producing stack, a custom resource will be created in the
+producing stack which will create an SSM parameter with a generated name in the consuming region.
+For example the name might be `/cdk/exports/stack2/stack1useast1CertRefCert5C9F`.
+
+To implement strong references the custom resources will be allowed to create new outputs, but will
+only be allowed to update/delete existing outputs if the output has _not_ been imported. If it has
+been imported the stack update will fail (similar to the behavior of native exports). See
+[Imports](#imports) for how the import is performed.
+
+### Imports
+
+The consuming stack will then "import" the value via a SSM dynamic reference. This is possible
+because we know the name of the SSM parameter that the producing stack creates. This will look
+something like `{{resolve:ssm:/cdk/exports/stack2/stack1useast1CertRefCert5C9F}}`.
+
+A custom resource will also be created in the consuming stack that will be responsible for marking
+the SSM parameter as having been "imported". It will do so by adding a tag to the parameter,
+something like `aws-cdk:strong-ref=stack2`. If the value is no longer imported by the stack then the
+tag will be removed. The producing stack will use the presence of the tag to determine whether or
+not the output can be updated/deleted.
+
+Since the imports for a stack are exported as SSM parameters with the stack name as part of the name
+prefix, when the importing stack is deleted it will clean up and remove any SSM parameters under
+that prefix.
+
+## Alternatives
+
+This solution uses a push model where the producing stack "pushes" the output to the target region.
+One alternative that was considered was to use a pull model where the consuming stack would "pull"
+the output from the producing region. For example the producing stack could produce a normal
+CloudFormation export and then the consuming stack would have a custom resource the reads the
+exports.
+
+This alternative had several limitations:
+1. No way to implement strong references. CloudFormation would not know the export is being used and
+   would allow it to be updated/deleted.
+2. The consuming custom resource would need to run every time the stack is deployed. This would
+   require introducing a salt that would cause a template diff on every deploy (not ideal).
+
+## Consequences
+
+If we add support for cross region references we will need to support cross region references going
+forward. We will not be tied to this implementation though.

cdk_api_mcp_server/resources/aws-cdk/constructs/aws-cdk-lib/core/integ.cfn-mappings-find-in-map.ts

@@ -0,0 +1,49 @@
+import * as cdk from 'aws-cdk-lib/core';
+import { Bucket } from 'aws-cdk-lib/aws-s3';
+import { IntegTest } from '@aws-cdk/integ-tests-alpha';
+
+const app = new cdk.App();
+
+const stack = new cdk.Stack(app, 'core-cfn-mapping-1'/* ,{ env }*/);
+
+const backing = {
+  TopLevelKey1: {
+    SecondLevelKey1: 'Yes',
+    SecondLevelKey2: 'No',
+  },
+};
+
+const mapping = new cdk.CfnMapping(stack, 'Regular mapping', {
+  mapping: backing,
+});
+
+const lazyMapping = new cdk.CfnMapping(stack, 'Lazy mapping', {
+  mapping: backing,
+  lazy: true,
+});
+
+const defValue = 'foob';
+const defValue2 = 'bart';
+
+const mapYes = mapping.findInMap('TopLevelKey1', 'SecondLevelKey1', defValue); // resolve to 'Yes'
+const mapDefault = mapping.findInMap('TopLevelKey1', cdk.Aws.REGION, defValue); // resolve to 'foob'
+const mapFn = cdk.Fn.findInMap(mapping.logicalId, 'TopLevelKey1', 'SecondLevelKey3', defValue); // resolve to 'foob'
+
+const lazyNo = lazyMapping.findInMap('TopLevelKey1', 'SecondLevelKey2', defValue2); // short circuit to 'No'
+const lazyDefault = lazyMapping.findInMap('TopLevelKey2', 'SecondLevelKey2', defValue2); // short circuit to 'bart'
+const lazyResolve = lazyMapping.findInMap(cdk.Aws.REGION, 'SecondLevelKey2', defValue2); // resolve to 'bart'
+
+new cdk.CfnOutput(stack, 'Output0', { value: mapYes });
+new cdk.CfnOutput(stack, 'Output1', { value: mapDefault });
+new cdk.CfnOutput(stack, 'Output2', { value: mapFn });
+new cdk.CfnOutput(stack, 'Output3', { value: lazyNo });
+new cdk.CfnOutput(stack, 'Output4', { value: lazyDefault });
+new cdk.CfnOutput(stack, 'Output5', { value: lazyResolve });
+
+new Bucket(stack, 'CfnMappingFindInMapBucket');
+
+new IntegTest(app, 'CfnMappingFindInMapTest', {
+  testCases: [stack],
+});
+
+app.synth();

cdk_api_mcp_server/resources/aws-cdk/constructs/aws-cdk-lib/core/integ.cross-region-references.ts

@@ -0,0 +1,58 @@
+import * as cdk from 'aws-cdk-lib/core';
+import * as ssm from 'aws-cdk-lib/aws-ssm';
+import { IntegTest } from '@aws-cdk/integ-tests-alpha';
+
+const app = new cdk.App();
+
+const producingStack = new cdk.Stack(app, 'CrossRegionRefProducerInteg', {
+  crossRegionReferences: true,
+  env: {
+    region: 'us-east-1',
+  },
+});
+
+const stringValue = 'MY_PARAMETER_VALUE';
+
+// Physical name of resource referenced across envs must be known at synth time either
+// hardcoded or using `PhysicalName.GENERATE_IF_NEEDED`. Hardcode here cause SSM is weird
+// with generate if needed currently.
+const parameterName = 'KNOWN_PARAMETER_NAME';
+const param = new ssm.StringParameter(producingStack, 'SomeParameter', {
+  parameterName: parameterName,
+  stringValue,
+});
+
+const consumingStack = new cdk.Stack(app, 'CrossRegionRefConsumerInteg', {
+  crossRegionReferences: true,
+  env: {
+    region: 'us-east-2',
+  },
+});
+
+new ssm.StringParameter(consumingStack, 'SomeParameterMirrored', {
+  parameterName: parameterName,
+  stringValue: param.stringValue,
+});
+
+// Add an explicit dependency because otherwise IntegTest doesn't deploy the producing stack
+// and adding it to the list of `testCases` doesn't ensure order apparently.
+consumingStack.addDependency(producingStack);
+
+new IntegTest(app, 'CrossRegionSSMReferenceTest', {
+  testCases: [consumingStack],
+  // Explicitly deploy to us-east-2 to guarantee a cross stack reference, if you exclude this
+  // it doesn't respect the `env` parameter passed to the stack.
+  regions: ['us-east-2'],
+  diffAssets: true,
+});
+
+// The assertions stack doesn't support deploying to a specific region which causes it to fail,
+// verified manually for now.
+// const getParam = integ.assertions.awsApiCall('SSM', 'getParameter', {
+//   Name: referencingParam.parameterName,
+// });
+//
+// getParam.expect(ExpectedResult.objectLike({
+//   Type: 'String',
+//   Value: stringValue,
+// }));

cdk_api_mcp_server/resources/aws-cdk/constructs/aws-cdk-lib/core/integ.logical-id.ts

@@ -0,0 +1,22 @@
+import * as cdk from 'aws-cdk-lib/core';
+import * as integ from '@aws-cdk/integ-tests-alpha';
+import * as sqs from 'aws-cdk-lib/aws-sqs';
+
+/**
+ * This test creates resources using alphanumeric logical IDs.
+ */
+
+const app = new cdk.App();
+
+const stack = new cdk.Stack(app);
+
+new sqs.Queue(stack, '01234test', {
+  visibilityTimeout: cdk.Duration.seconds(300),
+});
+new sqs.Queue(stack, 'test01234', {
+  visibilityTimeout: cdk.Duration.seconds(300),
+});
+
+new integ.IntegTest(app, 'LogicalIdTest', {
+  testCases: [stack],
+});

cdk_api_mcp_server/resources/aws-cdk/constructs/aws-cdk-lib/core/integ.nested-stack-references.ts

@@ -0,0 +1,68 @@
+import * as cdk from 'aws-cdk-lib/core';
+import * as integ from '@aws-cdk/integ-tests-alpha';
+import * as s3 from 'aws-cdk-lib/aws-s3';
+
+const app = new cdk.App();
+const producer = new cdk.Stack(app, 'Producer');
+
+const nested = new cdk.NestedStack(producer, 'Nested');
+new s3.Bucket(nested, 'RequiredResource');
+
+const nestedString = new cdk.CfnParameter(nested, 'NestedString', {
+  type: 'String',
+  default: 'foo',
+});
+
+const nestedNumber = new cdk.CfnParameter(nested, 'NestedNumber', {
+  type: 'Number',
+  default: '123',
+});
+
+const nestedList = new cdk.CfnParameter(nested, 'NestedList', {
+  type: 'CommaDelimitedList',
+  default: 'foo,bar',
+});
+
+const consumer = new cdk.Stack(app, 'Consumer');
+new s3.Bucket(consumer, 'RequiredResource');
+
+new cdk.CfnOutput(consumer, 'StringReference', {
+  value: nestedString.valueAsString,
+});
+
+new cdk.CfnOutput(consumer, 'NumberReference', {
+  value: nestedNumber.valueAsString,
+});
+
+new cdk.CfnOutput(consumer, 'ListReference', {
+  value: cdk.Fn.join('$$', nestedList.valueAsList),
+});
+
+const testCase = new integ.IntegTest(app, 'NestedStackReferences', {
+  testCases: [producer, consumer],
+});
+
+const describe = testCase.assertions.awsApiCall('CloudFormation', 'describeStacks', {
+  StackName: consumer.stackName,
+});
+
+describe.expect(integ.ExpectedResult.objectLike({
+  Stacks: integ.Match.arrayWith([
+    integ.Match.objectLike({
+      Outputs: integ.Match.arrayWith([
+        integ.Match.objectLike({
+          OutputKey: 'NumberReference',
+          OutputValue: '123',
+        }),
+        integ.Match.objectLike({
+          OutputKey: 'StringReference',
+          OutputValue: 'foo',
+        }),
+        integ.Match.objectLike({
+          OutputKey: 'ListReference',
+          OutputValue: 'foo$$bar',
+        }),
+      ]),
+    }),
+  ]),
+}));