Package software.amazon.awscdk.services.ec2

Class SecurityGroup

java.lang.Object
software.amazon.jsii.JsiiObject
software.constructs.Construct
software.amazon.awscdk.Resource
software.amazon.awscdk.services.ec2.SecurityGroup
All Implemented Interfaces:
IResource, IConnectable, IPeer, ISecurityGroup, software.amazon.jsii.JsiiSerializable, software.constructs.IConstruct, software.constructs.IDependable
@Generated(value="jsii-pacmak/1.104.0 (build e79254c)", date="2024-11-21T06:34:07.219Z") @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;
 SecurityGroup mySecurityGroup = SecurityGroup.Builder.create(this, "SecurityGroup").vpc(vpc).build();
 AutoScalingGroup.Builder.create(this, "ASG")
         .vpc(vpc)
         .instanceType(InstanceType.of(InstanceClass.BURSTABLE2, InstanceSize.MICRO))
         .machineImage(MachineImage.latestAmazonLinux2())
         .securityGroup(mySecurityGroup)
         .build();

  • 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

    • 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 RuleScope 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 RuleScope 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

    • getAllowAllIpv6Outbound

      @Stability(Stable) @NotNull public Boolean getAllowAllIpv6Outbound()
      Whether the SecurityGroup has been configured to allow all outbound ipv6 traffic.

    • 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

    • 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()