Skip to content

Commit de31f9f

Browse files
authored
docs(ec2): document how to correctly make cross stack connection calls (#18796)
This PR adds documentation on how to correctly make cross stack connections. If the connection is not made in the correct stack it can lead to cyclic reference. fixes #5047 ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
1 parent 3432c45 commit de31f9f

File tree

1 file changed

+67
-0
lines changed

1 file changed

+67
-0
lines changed

packages/@aws-cdk/aws-ec2/README.md

+67
Original file line numberDiff line numberDiff line change
@@ -601,6 +601,73 @@ const sg = ec2.SecurityGroup.fromLookupById(this, 'SecurityGroupLookup', 'sg-123
601601

602602
The result of `SecurityGroup.fromLookupByName` and `SecurityGroup.fromLookupById` operations will be written to a file called `cdk.context.json`. You must commit this file to source control so that the lookup values are available in non-privileged environments such as CI build steps, and to ensure your template builds are repeatable.
603603

604+
### Cross Stack Connections
605+
606+
If you are attempting to add a connection from a peer in one stack to a peer in a different stack, sometimes it is necessary to ensure that you are making the connection in
607+
a specific stack in order to avoid a cyclic reference. If there are no other dependencies between stacks then it will not matter in which stack you make
608+
the connection, but if there are existing dependencies (i.e. stack1 already depends on stack2), then it is important to make the connection in the dependent stack (i.e. stack1).
609+
610+
Whenever you make a `connections` function call, the ingress and egress security group rules will be added to the stack that the calling object exists in.
611+
So if you are doing something like `peer1.connections.allowFrom(peer2)`, then the security group rules (both ingress and egress) will be created in `peer1`'s Stack.
612+
613+
As an example, if we wanted to allow a connection from a security group in one stack (egress) to a security group in a different stack (ingress),
614+
we would make the connection like:
615+
616+
**If Stack1 depends on Stack2**
617+
618+
```ts fixture=with-vpc
619+
// Stack 1
620+
declare const stack1: Stack;
621+
declare const stack2: Stack;
622+
623+
const sg1 = new ec2.SecurityGroup(stack1, 'SG1', {
624+
allowAllOutbound: false, // if this is `true` then no egress rule will be created
625+
vpc,
626+
});
627+
628+
// Stack 2
629+
const sg2 = new ec2.SecurityGroup(stack2, 'SG2', {
630+
allowAllOutbound: false, // if this is `true` then no egress rule will be created
631+
vpc,
632+
});
633+
634+
635+
// `connections.allowTo` on `sg1` since we want the
636+
// rules to be created in Stack1
637+
sg1.connections.allowTo(sg2, ec2.Port.tcp(3333));
638+
```
639+
640+
In this case both the Ingress Rule for `sg2` and the Egress Rule for `sg1` will both be created
641+
in `Stack 1` which avoids the cyclic reference.
642+
643+
644+
**If Stack2 depends on Stack1**
645+
646+
```ts fixture=with-vpc
647+
// Stack 1
648+
declare const stack1: Stack;
649+
declare const stack2: Stack;
650+
651+
const sg1 = new ec2.SecurityGroup(stack1, 'SG1', {
652+
allowAllOutbound: false, // if this is `true` then no egress rule will be created
653+
vpc,
654+
});
655+
656+
// Stack 2
657+
const sg2 = new ec2.SecurityGroup(stack2, 'SG2', {
658+
allowAllOutbound: false, // if this is `true` then no egress rule will be created
659+
vpc,
660+
});
661+
662+
663+
// `connections.allowFrom` on `sg2` since we want the
664+
// rules to be created in Stack2
665+
sg2.connections.allowFrom(sg1, ec2.Port.tcp(3333));
666+
```
667+
668+
In this case both the Ingress Rule for `sg2` and the Egress Rule for `sg1` will both be created
669+
in `Stack 2` which avoids the cyclic reference.
670+
604671
## Machine Images (AMIs)
605672

606673
AMIs control the OS that gets launched when you start your EC2 instance. The EC2

0 commit comments

Comments
 (0)