Class SecurityGroup
- All Implemented Interfaces:
IConstruct
,IDependable
,IResource
,IConnectable
,IPeer
,ISecurityGroup
,software.amazon.jsii.JsiiSerializable
,software.constructs.IConstruct
Security Groups act like a firewall with a set of rules, and are associated with any AWS resource that has or creates Elastic Network Interfaces (ENIs). A typical example of a resource that has a security group is an Instance (or Auto Scaling Group of instances)
If you are defining new infrastructure in CDK, there is a good chance you won't have to interact with this class at all. Like IAM Roles, Security Groups need to exist to control access between AWS resources, but CDK will automatically generate and populate them with least-privilege permissions for you so you can concentrate on your business logic.
All Constructs that require Security Groups will create one for you if you
don't specify one at construction. After construction, you can selectively
allow connections to and between constructs via--for example-- the instance.connections
object. Think of it as "allowing connections to your instance", rather than
"adding ingress rules a security group". See the Allowing
Connections
section in the library documentation for examples.
Direct manipulation of the Security Group through addIngressRule
and
addEgressRule
is possible, but mutation through the .connections
object
is recommended. If you peer two constructs with security groups this way,
appropriate rules will be created in both.
If you have an existing security group you want to use in your CDK application, you would import it like this:
ISecurityGroup securityGroup = SecurityGroup.fromSecurityGroupId(this, "SG", "sg-12345", SecurityGroupImportOptions.builder() .mutable(false) .build());
Example:
Vpc vpc; LaunchTemplate template = LaunchTemplate.Builder.create(this, "LaunchTemplate") .machineImage(MachineImage.latestAmazonLinux()) .securityGroup(SecurityGroup.Builder.create(this, "LaunchTemplateSG") .vpc(vpc) .build()) .build();
-
Nested Class Summary
Nested classes/interfaces inherited from class software.amazon.jsii.JsiiObject
software.amazon.jsii.JsiiObject.InitializationMode
Nested classes/interfaces inherited from interface software.amazon.awscdk.core.IConstruct
IConstruct.Jsii$Default
Nested classes/interfaces inherited from interface software.constructs.IConstruct
software.constructs.IConstruct.Jsii$Default
Nested classes/interfaces inherited from interface software.amazon.awscdk.core.IResource
IResource.Jsii$Default
Nested classes/interfaces inherited from interface software.amazon.awscdk.services.ec2.ISecurityGroup
ISecurityGroup.Jsii$Default, ISecurityGroup.Jsii$Proxy
-
Constructor Summary
ModifierConstructorDescriptionprotected
SecurityGroup
(software.amazon.jsii.JsiiObject.InitializationMode initializationMode) protected
SecurityGroup
(software.amazon.jsii.JsiiObjectRef objRef) SecurityGroup
(software.constructs.Construct scope, String id, SecurityGroupProps props) -
Method Summary
Modifier and TypeMethodDescriptionvoid
addEgressRule
(IPeer peer, Port connection) Add an egress rule for the current security group.void
addEgressRule
(IPeer peer, Port connection, String description) Add an egress rule for the current security group.void
addEgressRule
(IPeer peer, Port connection, String description, Boolean remoteRule) Add an egress rule for the current security group.void
addIngressRule
(IPeer peer, Port connection) Add an ingress rule for the current security group.void
addIngressRule
(IPeer peer, Port connection, String description) Add an ingress rule for the current security group.void
addIngressRule
(IPeer peer, Port connection, String description, Boolean remoteRule) Add an ingress rule for the current security group.protected com.fasterxml.jackson.databind.node.ObjectNode
determineRuleScope
(IPeer peer, Port connection, String fromTo) Determine where to parent a new ingress/egress rule.protected com.fasterxml.jackson.databind.node.ObjectNode
determineRuleScope
(IPeer peer, Port connection, String fromTo, Boolean remoteRule) Determine where to parent a new ingress/egress rule.static ISecurityGroup
fromLookup
(software.constructs.Construct scope, String id, String securityGroupId) Deprecated.static ISecurityGroup
fromLookupById
(software.constructs.Construct scope, String id, String securityGroupId) Look up a security group by id.static ISecurityGroup
fromLookupByName
(software.constructs.Construct scope, String id, String securityGroupName, IVpc vpc) Look up a security group by name.static ISecurityGroup
fromSecurityGroupId
(software.constructs.Construct scope, String id, String securityGroupId) Import an existing security group into this app.static ISecurityGroup
fromSecurityGroupId
(software.constructs.Construct scope, String id, String securityGroupId, SecurityGroupImportOptions options) Import an existing security group into this app.Whether the SecurityGroup has been configured to allow all outbound traffic.Whether the rule can be inlined into a SecurityGroup or not.The network connections associated with this resource.The ID of the security group.Deprecated.returns the security group ID, rather than the name.The VPC ID this security group is part of.A unique identifier for this connection peer.static Boolean
Return whether the indicated object is a security group.Produce the egress rule JSON for the given connection.Produce the ingress rule JSON for the given connection.Methods inherited from class software.amazon.awscdk.core.Resource
applyRemovalPolicy, generatePhysicalName, getEnv, getPhysicalName, getResourceArnAttribute, getResourceNameAttribute, getStack, isResource
Methods inherited from class software.amazon.awscdk.core.Construct
getNode, isConstruct, onPrepare, onSynthesize, onValidate, prepare, synthesize, validate
Methods inherited from class software.constructs.Construct
toString
Methods inherited from class software.amazon.jsii.JsiiObject
jsiiAsyncCall, jsiiAsyncCall, jsiiCall, jsiiCall, jsiiGet, jsiiGet, jsiiSet, jsiiStaticCall, jsiiStaticCall, jsiiStaticGet, jsiiStaticGet, jsiiStaticSet, jsiiStaticSet
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface software.amazon.awscdk.core.IConstruct
getNode
Methods inherited from interface software.amazon.awscdk.core.IResource
applyRemovalPolicy, getEnv, getStack
Methods inherited from interface software.amazon.jsii.JsiiSerializable
$jsii$toJson
-
Constructor Details
-
SecurityGroup
protected SecurityGroup(software.amazon.jsii.JsiiObjectRef objRef) -
SecurityGroup
protected SecurityGroup(software.amazon.jsii.JsiiObject.InitializationMode initializationMode) -
SecurityGroup
@Stability(Stable) public SecurityGroup(@NotNull software.constructs.Construct scope, @NotNull String id, @NotNull SecurityGroupProps props) - Parameters:
scope
- This parameter is required.id
- This parameter is required.props
- This parameter is required.
-
-
Method Details
-
fromLookup
@Stability(Deprecated) @Deprecated @NotNull public static ISecurityGroup fromLookup(@NotNull software.constructs.Construct scope, @NotNull String id, @NotNull String securityGroupId) Deprecated.UsefromLookupById()
instead(deprecated) Look up a security group by id.- Parameters:
scope
- This parameter is required.id
- This parameter is required.securityGroupId
- This parameter is required.
-
fromLookupById
@Stability(Stable) @NotNull public static ISecurityGroup fromLookupById(@NotNull software.constructs.Construct scope, @NotNull String id, @NotNull String securityGroupId) Look up a security group by id.- Parameters:
scope
- This parameter is required.id
- This parameter is required.securityGroupId
- This parameter is required.
-
fromLookupByName
@Stability(Stable) @NotNull public static ISecurityGroup fromLookupByName(@NotNull software.constructs.Construct scope, @NotNull String id, @NotNull String securityGroupName, @NotNull IVpc vpc) Look up a security group by name.- Parameters:
scope
- This parameter is required.id
- This parameter is required.securityGroupName
- This parameter is required.vpc
- This parameter is required.
-
fromSecurityGroupId
@Stability(Stable) @NotNull public static ISecurityGroup fromSecurityGroupId(@NotNull software.constructs.Construct scope, @NotNull String id, @NotNull String securityGroupId, @Nullable SecurityGroupImportOptions options) Import an existing security group into this app.This method will assume that the Security Group has a rule in it which allows all outbound traffic, and so will not add egress rules to the imported Security Group (only ingress rules).
If your existing Security Group needs to have egress rules added, pass the
allowAllOutbound: false
option on import.- Parameters:
scope
- This parameter is required.id
- This parameter is required.securityGroupId
- This parameter is required.options
-
-
fromSecurityGroupId
@Stability(Stable) @NotNull public static ISecurityGroup fromSecurityGroupId(@NotNull software.constructs.Construct scope, @NotNull String id, @NotNull String securityGroupId) Import an existing security group into this app.This method will assume that the Security Group has a rule in it which allows all outbound traffic, and so will not add egress rules to the imported Security Group (only ingress rules).
If your existing Security Group needs to have egress rules added, pass the
allowAllOutbound: false
option on import.- Parameters:
scope
- This parameter is required.id
- This parameter is required.securityGroupId
- This parameter is required.
-
isSecurityGroup
Return whether the indicated object is a security group.- Parameters:
x
- This parameter is required.
-
addEgressRule
@Stability(Stable) public void addEgressRule(@NotNull IPeer peer, @NotNull Port connection, @Nullable String description, @Nullable Boolean remoteRule) Add an egress rule for the current security group.remoteRule
controls where the Rule object is created if the peer is also a securityGroup and they are in different stack. If false (default) the rule object is created under the current SecurityGroup object. If true and the peer is also a SecurityGroup, the rule object is created under the remote SecurityGroup object.- Specified by:
addEgressRule
in interfaceISecurityGroup
- Parameters:
peer
- This parameter is required.connection
- This parameter is required.description
-remoteRule
-
-
addEgressRule
@Stability(Stable) public void addEgressRule(@NotNull IPeer peer, @NotNull Port connection, @Nullable String description) Add an egress rule for the current security group.remoteRule
controls where the Rule object is created if the peer is also a securityGroup and they are in different stack. If false (default) the rule object is created under the current SecurityGroup object. If true and the peer is also a SecurityGroup, the rule object is created under the remote SecurityGroup object.- Specified by:
addEgressRule
in interfaceISecurityGroup
- Parameters:
peer
- This parameter is required.connection
- This parameter is required.description
-
-
addEgressRule
Add an egress rule for the current security group.remoteRule
controls where the Rule object is created if the peer is also a securityGroup and they are in different stack. If false (default) the rule object is created under the current SecurityGroup object. If true and the peer is also a SecurityGroup, the rule object is created under the remote SecurityGroup object.- Specified by:
addEgressRule
in interfaceISecurityGroup
- Parameters:
peer
- This parameter is required.connection
- This parameter is required.
-
addIngressRule
@Stability(Stable) public void addIngressRule(@NotNull IPeer peer, @NotNull Port connection, @Nullable String description, @Nullable Boolean remoteRule) Add an ingress rule for the current security group.remoteRule
controls where the Rule object is created if the peer is also a securityGroup and they are in different stack. If false (default) the rule object is created under the current SecurityGroup object. If true and the peer is also a SecurityGroup, the rule object is created under the remote SecurityGroup object.- Specified by:
addIngressRule
in interfaceISecurityGroup
- Parameters:
peer
- This parameter is required.connection
- This parameter is required.description
-remoteRule
-
-
addIngressRule
@Stability(Stable) public void addIngressRule(@NotNull IPeer peer, @NotNull Port connection, @Nullable String description) Add an ingress rule for the current security group.remoteRule
controls where the Rule object is created if the peer is also a securityGroup and they are in different stack. If false (default) the rule object is created under the current SecurityGroup object. If true and the peer is also a SecurityGroup, the rule object is created under the remote SecurityGroup object.- Specified by:
addIngressRule
in interfaceISecurityGroup
- Parameters:
peer
- This parameter is required.connection
- This parameter is required.description
-
-
addIngressRule
Add an ingress rule for the current security group.remoteRule
controls where the Rule object is created if the peer is also a securityGroup and they are in different stack. If false (default) the rule object is created under the current SecurityGroup object. If true and the peer is also a SecurityGroup, the rule object is created under the remote SecurityGroup object.- Specified by:
addIngressRule
in interfaceISecurityGroup
- Parameters:
peer
- This parameter is required.connection
- This parameter is required.
-
determineRuleScope
@Stability(Stable) @NotNull protected com.fasterxml.jackson.databind.node.ObjectNode determineRuleScope(@NotNull IPeer peer, @NotNull Port connection, @NotNull String fromTo, @Nullable Boolean remoteRule) Determine where to parent a new ingress/egress rule.A SecurityGroup rule is parented under the group it's related to, UNLESS we're in a cross-stack scenario with another Security Group. In that case, we respect the 'remoteRule' flag and will parent under the other security group.
This is necessary to avoid cyclic dependencies between stacks, since both ingress and egress rules will reference both security groups, and a naive parenting will lead to the following situation:
╔════════════════════╗ ╔════════════════════╗ ║ ┌───────────┐ ║ ║ ┌───────────┐ ║ ║ │ GroupA │◀────╬─┐ ┌───╬───▶│ GroupB │ ║ ║ └───────────┘ ║ │ │ ║ └───────────┘ ║ ║ ▲ ║ │ │ ║ ▲ ║ ║ │ ║ │ │ ║ │ ║ ║ │ ║ │ │ ║ │ ║ ║ ┌───────────┐ ║ └───┼───╬────┌───────────┐ ║ ║ │ EgressA │─────╬─────┘ ║ │ IngressB │ ║ ║ └───────────┘ ║ ║ └───────────┘ ║ ║ ║ ║ ║ ╚════════════════════╝ ╚════════════════════╝
By having the ability to switch the parent, we avoid the cyclic reference by keeping all rules in a single stack.
If this happens, we also have to change the construct ID, because otherwise we might have two objects with the same ID if we have multiple reversed security group relationships.
╔═══════════════════════════════════╗ ║┌───────────┐ ║ ║│ GroupB │ ║ ║└───────────┘ ║ ║ ▲ ║ ║ │ ┌───────────┐ ║ ║ ├────"from A"──│ IngressB │ ║ ║ │ └───────────┘ ║ ║ │ ┌───────────┐ ║ ║ ├─────"to B"───│ EgressA │ ║ ║ │ └───────────┘ ║ ║ │ ┌───────────┐ ║ ║ └─────"to B"───│ EgressC │ ║ <-- oops ║ └───────────┘ ║ ╚═══════════════════════════════════╝
- Parameters:
peer
- This parameter is required.connection
- This parameter is required.fromTo
- This parameter is required.remoteRule
-
-
determineRuleScope
@Stability(Stable) @NotNull protected com.fasterxml.jackson.databind.node.ObjectNode determineRuleScope(@NotNull IPeer peer, @NotNull Port connection, @NotNull String fromTo) Determine where to parent a new ingress/egress rule.A SecurityGroup rule is parented under the group it's related to, UNLESS we're in a cross-stack scenario with another Security Group. In that case, we respect the 'remoteRule' flag and will parent under the other security group.
This is necessary to avoid cyclic dependencies between stacks, since both ingress and egress rules will reference both security groups, and a naive parenting will lead to the following situation:
╔════════════════════╗ ╔════════════════════╗ ║ ┌───────────┐ ║ ║ ┌───────────┐ ║ ║ │ GroupA │◀────╬─┐ ┌───╬───▶│ GroupB │ ║ ║ └───────────┘ ║ │ │ ║ └───────────┘ ║ ║ ▲ ║ │ │ ║ ▲ ║ ║ │ ║ │ │ ║ │ ║ ║ │ ║ │ │ ║ │ ║ ║ ┌───────────┐ ║ └───┼───╬────┌───────────┐ ║ ║ │ EgressA │─────╬─────┘ ║ │ IngressB │ ║ ║ └───────────┘ ║ ║ └───────────┘ ║ ║ ║ ║ ║ ╚════════════════════╝ ╚════════════════════╝
By having the ability to switch the parent, we avoid the cyclic reference by keeping all rules in a single stack.
If this happens, we also have to change the construct ID, because otherwise we might have two objects with the same ID if we have multiple reversed security group relationships.
╔═══════════════════════════════════╗ ║┌───────────┐ ║ ║│ GroupB │ ║ ║└───────────┘ ║ ║ ▲ ║ ║ │ ┌───────────┐ ║ ║ ├────"from A"──│ IngressB │ ║ ║ │ └───────────┘ ║ ║ │ ┌───────────┐ ║ ║ ├─────"to B"───│ EgressA │ ║ ║ │ └───────────┘ ║ ║ │ ┌───────────┐ ║ ║ └─────"to B"───│ EgressC │ ║ <-- oops ║ └───────────┘ ║ ╚═══════════════════════════════════╝
- Parameters:
peer
- This parameter is required.connection
- This parameter is required.fromTo
- This parameter is required.
-
toEgressRuleConfig
Produce the egress rule JSON for the given connection.- Specified by:
toEgressRuleConfig
in interfaceIPeer
-
toIngressRuleConfig
Produce the ingress rule JSON for the given connection.- Specified by:
toIngressRuleConfig
in interfaceIPeer
-
getAllowAllOutbound
Whether the SecurityGroup has been configured to allow all outbound traffic.- Specified by:
getAllowAllOutbound
in interfaceISecurityGroup
-
getCanInlineRule
Whether the rule can be inlined into a SecurityGroup or not.- Specified by:
getCanInlineRule
in interfaceIPeer
-
getConnections
The network connections associated with this resource.- Specified by:
getConnections
in interfaceIConnectable
-
getSecurityGroupId
The ID of the security group.- Specified by:
getSecurityGroupId
in interfaceISecurityGroup
-
getSecurityGroupName
Deprecated.returns the security group ID, rather than the name.(deprecated) An attribute that represents the security group name. -
getSecurityGroupVpcId
The VPC ID this security group is part of. -
getUniqueId
A unique identifier for this connection peer.- Specified by:
getUniqueId
in interfaceIPeer
-
getDefaultPort
-
fromLookupById()
instead