Package software.amazon.awscdk.services.ec2

Class SecurityGroup

java.lang.Object

software.amazon.jsii.JsiiObject

software.constructs.Construct

software.amazon.awscdk.core.Construct

software.amazon.awscdk.core.Resource

software.amazon.awscdk.services.ec2.SecurityGroup

All Implemented Interfaces:

IConstruct, IDependable, IResource, IConnectable, IPeer, ISecurityGroup, software.amazon.jsii.JsiiSerializable, software.constructs.IConstruct

@Generated(value="jsii-pacmak/1.84.0 (build 5404dcf)",
           date="2023-06-19T16:30:39.525Z")
@Stability(Stable)
public class SecurityGroup
extends Resource
implements ISecurityGroup

Creates an Amazon EC2 security group within a VPC.

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

Modifier and Type	Class	Description
static final class	SecurityGroup.Builder	A fluent builder for SecurityGroup.

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

Constructors

Modifier	Constructor	Description
protected	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 Type	Method	Description
void	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. Use fromLookupById() instead
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.
Boolean	getAllowAllOutbound()	Whether the SecurityGroup has been configured to allow all outbound traffic.
Boolean	getCanInlineRule()	Whether the rule can be inlined into a SecurityGroup or not.
Connections	getConnections()	The network connections associated with this resource.
Port	getDefaultPort()
String	getSecurityGroupId()	The ID of the security group.
String	getSecurityGroupName()	Deprecated. returns the security group ID, rather than the name.
String	getSecurityGroupVpcId()	The VPC ID this security group is part of.
String	getUniqueId()	A unique identifier for this connection peer.
static Boolean	isSecurityGroup(Object x)	Return whether the indicated object is a security group.
Object	toEgressRuleConfig()	Produce the egress rule JSON for the given connection.
Object	toIngressRuleConfig()	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.

Use fromLookupById() 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

@Stability(Stable)
@NotNull
public static Boolean isSecurityGroup(@NotNull
 Object x)

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 interface ISecurityGroup

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 interface ISecurityGroup

Parameters:

peer - This parameter is required.

connection - This parameter is required.

description -

addEgressRule

@Stability(Stable)
public void addEgressRule(@NotNull
 IPeer peer,
 @NotNull
 Port connection)

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 interface ISecurityGroup

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 interface ISecurityGroup

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 interface ISecurityGroup

Parameters:

peer - This parameter is required.

connection - This parameter is required.

description -

addIngressRule

@Stability(Stable)
public void addIngressRule(@NotNull
 IPeer peer,
 @NotNull
 Port connection)

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 interface ISecurityGroup

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

@Stability(Stable)
@NotNull
public Object toEgressRuleConfig()

Produce the egress rule JSON for the given connection.

Specified by:

toEgressRuleConfig in interface IPeer

toIngressRuleConfig

@Stability(Stable)
@NotNull
public Object toIngressRuleConfig()

Produce the ingress rule JSON for the given connection.

Specified by:

toIngressRuleConfig in interface IPeer

getAllowAllOutbound

@Stability(Stable)
@NotNull
public Boolean getAllowAllOutbound()

Whether the SecurityGroup has been configured to allow all outbound traffic.

Specified by:

getAllowAllOutbound in interface ISecurityGroup

getCanInlineRule

@Stability(Stable)
@NotNull
public Boolean getCanInlineRule()

Whether the rule can be inlined into a SecurityGroup or not.

Specified by:

getCanInlineRule in interface IPeer

getConnections

@Stability(Stable)
@NotNull
public Connections getConnections()

The network connections associated with this resource.

Specified by:

getConnections in interface IConnectable

getSecurityGroupId

@Stability(Stable)
@NotNull
public String getSecurityGroupId()

The ID of the security group.

Specified by:

getSecurityGroupId in interface ISecurityGroup

getSecurityGroupName

@Stability(Deprecated)
@Deprecated
@NotNull
public String getSecurityGroupName()

Deprecated.

returns the security group ID, rather than the name.

(deprecated) An attribute that represents the security group name.

getSecurityGroupVpcId

@Stability(Stable)
@NotNull
public String getSecurityGroupVpcId()

The VPC ID this security group is part of.

getUniqueId

@Stability(Stable)
@NotNull
public String getUniqueId()

A unique identifier for this connection peer.

Specified by:

getUniqueId in interface IPeer

getDefaultPort

@Stability(Stable)
@Nullable
public Port getDefaultPort()