security_groups

Creates, updates, deletes, gets or lists a security_groups resource.

Overview

Name	`security_groups`
Type	Resource
Id	`aws.ec2.security_groups`

Fields

The following fields are returned by SELECT queries:

describe_security_groups

Name	Datatype	Description
`description`	`string`	A description of the security group.
`group_id`	`string`	The ID of the security group.
`group_name`	`string`	The name of the security group.
`ip_permissions`	`string`	The inbound rules associated with the security group.
`ip_permissions_egress`	`string`	The outbound rules associated with the security group.
`owner_id`	`string`	The Amazon Web Services account ID of the owner of the security group.
`security_group_arn`	`string`	The ARN of the security group.
`tags`	`string`	Any tags assigned to the security group.
`vpc_id`	`string`	The ID of the VPC for the security group.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`describe_security_groups`	`select`	`region`	`GroupId`, `GroupName`, `NextToken`, `MaxResults`, `DryRun`, `Filter`	Describes the specified security groups or all of your security groups.
`create_security_group`	`insert`	`GroupDescription`, `GroupName`, `region`	`VpcId`, `TagSpecification`, `DryRun`	Creates a security group. A security group acts as a virtual firewall for your instance to control inbound and outbound traffic. For more information, see Amazon EC2 security groups in the Amazon EC2 User Guide and Security groups for your VPC in the Amazon VPC User Guide. When you create a security group, you specify a friendly name of your choice. You can't have two security groups for the same VPC with the same name. You have a default security group for use in your VPC. If you don't specify a security group when you launch an instance, the instance is launched into the appropriate default security group. A default security group includes a default rule that grants instances unrestricted network access to each other. You can add or remove rules from your security groups using AuthorizeSecurityGroupIngress, AuthorizeSecurityGroupEgress, RevokeSecurityGroupIngress, and RevokeSecurityGroupEgress. For more information about VPC security group limits, see Amazon VPC Limits.
`authorize_security_group_egress`	`update`	`GroupId`, `region`	`TagSpecification`, `DryRun`, `SourceSecurityGroupName`, `SourceSecurityGroupOwnerId`, `IpProtocol`, `FromPort`, `ToPort`, `CidrIp`, `IpPermissions`	Adds the specified outbound (egress) rules to a security group. An outbound rule permits instances to send traffic to the specified IPv4 or IPv6 address ranges, the IP address ranges specified by a prefix list, or the instances that are associated with a source security group. For more information, see Security group rules. You must specify exactly one of the following destinations: an IPv4 or IPv6 address range, a prefix list, or a security group. You must specify a protocol for each rule (for example, TCP). If the protocol is TCP or UDP, you must also specify a port or port range. If the protocol is ICMP or ICMPv6, you must also specify the ICMP type and code. Rule changes are propagated to instances associated with the security group as quickly as possible. However, a small delay might occur. For examples of rules that you can add to security groups for specific access scenarios, see Security group rules for different use cases in the Amazon EC2 User Guide. For information about security group quotas, see Amazon VPC quotas in the Amazon VPC User Guide.
`authorize_security_group_ingress`	`update`	`region`	`CidrIp`, `FromPort`, `GroupId`, `GroupName`, `IpPermissions`, `IpProtocol`, `SourceSecurityGroupName`, `SourceSecurityGroupOwnerId`, `ToPort`, `TagSpecification`, `DryRun`	Adds the specified inbound (ingress) rules to a security group. An inbound rule permits instances to receive traffic from the specified IPv4 or IPv6 address range, the IP address ranges that are specified by a prefix list, or the instances that are associated with a destination security group. For more information, see Security group rules. You must specify exactly one of the following sources: an IPv4 or IPv6 address range, a prefix list, or a security group. You must specify a protocol for each rule (for example, TCP). If the protocol is TCP or UDP, you must also specify a port or port range. If the protocol is ICMP or ICMPv6, you must also specify the ICMP/ICMPv6 type and code. Rule changes are propagated to instances associated with the security group as quickly as possible. However, a small delay might occur. For examples of rules that you can add to security groups for specific access scenarios, see Security group rules for different use cases in the Amazon EC2 User Guide. For more information about security group quotas, see Amazon VPC quotas in the Amazon VPC User Guide.
`delete_security_group`	`delete`	`region`	`GroupId`, `GroupName`, `DryRun`	Deletes a security group. If you attempt to delete a security group that is associated with an instance or network interface, is referenced by another security group in the same VPC, or has a VPC association, the operation fails with DependencyViolation.
`revoke_security_group_egress`	`exec`	`GroupId`, `region`	`SecurityGroupRuleId`, `DryRun`, `SourceSecurityGroupName`, `SourceSecurityGroupOwnerId`, `IpProtocol`, `FromPort`, `ToPort`, `CidrIp`, `IpPermissions`	Removes the specified outbound (egress) rules from the specified security group. You can specify rules using either rule IDs or security group rule properties. If you use rule properties, the values that you specify (for example, ports) must match the existing rule's values exactly. Each rule has a protocol, from and to ports, and destination (CIDR range, security group, or prefix list). For the TCP and UDP protocols, you must also specify the destination port or range of ports. For the ICMP protocol, you must also specify the ICMP type and code. If the security group rule has a description, you do not need to specify the description to revoke the rule. For a default VPC, if the values you specify do not match the existing rule's values, no error is returned, and the output describes the security group rules that were not revoked. Amazon Web Services recommends that you describe the security group to verify that the rules were removed. Rule changes are propagated to instances within the security group as quickly as possible. However, a small delay might occur.
`revoke_security_group_ingress`	`exec`	`region`	`CidrIp`, `FromPort`, `GroupId`, `GroupName`, `IpPermissions`, `IpProtocol`, `SourceSecurityGroupName`, `SourceSecurityGroupOwnerId`, `ToPort`, `SecurityGroupRuleId`, `DryRun`	Removes the specified inbound (ingress) rules from a security group. You can specify rules using either rule IDs or security group rule properties. If you use rule properties, the values that you specify (for example, ports) must match the existing rule's values exactly. Each rule has a protocol, from and to ports, and source (CIDR range, security group, or prefix list). For the TCP and UDP protocols, you must also specify the destination port or range of ports. For the ICMP protocol, you must also specify the ICMP type and code. If the security group rule has a description, you do not need to specify the description to revoke the rule. For a default VPC, if the values you specify do not match the existing rule's values, no error is returned, and the output describes the security group rules that were not revoked. For a non-default VPC, if the values you specify do not match the existing rule's values, an InvalidPermission.NotFound client error is returned, and no rules are revoked. Amazon Web Services recommends that you describe the security group to verify that the rules were removed. Rule changes are propagated to instances within the security group as quickly as possible. However, a small delay might occur.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
`GroupDescription`	`string`	A description for the security group. Constraints: Up to 255 characters in length Valid characters: a-z, A-Z, 0-9, spaces, and ._-:/()#,@[]+=&;{}!$*
`GroupId`	`string`	The ID of the security group.
`GroupName`	`string`	The name of the security group. Names are case-insensitive and must be unique within the VPC. Constraints: Up to 255 characters in length. Can't start with sg-. Valid characters: a-z, A-Z, 0-9, spaces, and ._-:/()#,@[]+=&;{}!$*
`region`	`string`	AWS region (default: us-east-1)
`CidrIp`	`string`	The CIDR IP address range. You can't specify this parameter when specifying a source security group.
`DryRun`	`boolean`	Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.
`Filter`	`array`	The filters. If using multiple filters for rules, the results include security groups for which any combination of rules - not necessarily a single rule - match all filters. description - The description of the security group. egress.ip-permission.cidr - An IPv4 CIDR block for an outbound security group rule. egress.ip-permission.from-port - For an outbound rule, the start of port range for the TCP and UDP protocols, or an ICMP type number. egress.ip-permission.group-id - The ID of a security group that has been referenced in an outbound security group rule. egress.ip-permission.group-name - The name of a security group that is referenced in an outbound security group rule. egress.ip-permission.ipv6-cidr - An IPv6 CIDR block for an outbound security group rule. egress.ip-permission.prefix-list-id - The ID of a prefix list to which a security group rule allows outbound access. egress.ip-permission.protocol - The IP protocol for an outbound security group rule (tcp \| udp \| icmp, a protocol number, or -1 for all protocols). egress.ip-permission.to-port - For an outbound rule, the end of port range for the TCP and UDP protocols, or an ICMP code. egress.ip-permission.user-id - The ID of an Amazon Web Services account that has been referenced in an outbound security group rule. group-id - The ID of the security group. group-name - The name of the security group. ip-permission.cidr - An IPv4 CIDR block for an inbound security group rule. ip-permission.from-port - For an inbound rule, the start of port range for the TCP and UDP protocols, or an ICMP type number. ip-permission.group-id - The ID of a security group that has been referenced in an inbound security group rule. ip-permission.group-name - The name of a security group that is referenced in an inbound security group rule. ip-permission.ipv6-cidr - An IPv6 CIDR block for an inbound security group rule. ip-permission.prefix-list-id - The ID of a prefix list from which a security group rule allows inbound access. ip-permission.protocol - The IP protocol for an inbound security group rule (tcp \| udp \| icmp, a protocol number, or -1 for all protocols). ip-permission.to-port - For an inbound rule, the end of port range for the TCP and UDP protocols, or an ICMP code. ip-permission.user-id - The ID of an Amazon Web Services account that has been referenced in an inbound security group rule. owner-id - The Amazon Web Services account ID of the owner of the security group. tag:`<key>` - The key/value combination of a tag assigned to the resource. Use the tag key in the filter name and the tag value as the filter value. For example, to find all resources that have a tag with the key Owner and the value TeamA, specify tag:Owner for the filter name and TeamA for the filter value. tag-key - The key of a tag assigned to the resource. Use this filter to find all resources assigned a tag with a specific key, regardless of the tag value. vpc-id - The ID of the VPC specified when the security group was created.
`FromPort`	`integer`	If the protocol is TCP or UDP, this is the start of the port range. If the protocol is ICMP, this is the ICMP type or -1 (all ICMP types).
`GroupId`	`string`	The ID of the security group.
`GroupName`	`string`	[Default VPC] The name of the security group. You must specify either the security group ID or the security group name in the request. For security groups in a nondefault VPC, you must specify the security group ID.
`IpPermissions`	`array`	The sets of IP permissions. You can't specify a source security group and a CIDR IP address range in the same set of permissions.
`IpProtocol`	`string`	The IP protocol name (tcp, udp, icmp) or number (see Protocol Numbers). Use -1 to specify all.
`MaxResults`	`integer`	The maximum number of items to return for this request. To get the next page of items, make another request with the token returned in the output. This value can be between 5 and 1000. If this parameter is not specified, then all items are returned. For more information, see Pagination.
`NextToken`	`string`	The token returned from a previous paginated request. Pagination continues from the end of the items returned by the previous request.
`SecurityGroupRuleId`	`array`	The IDs of the security group rules.
`SourceSecurityGroupName`	`string`	[Default VPC] The name of the source security group. You can't specify this parameter in combination with the following parameters: the CIDR IP address range, the start of the port range, the IP protocol, and the end of the port range. The source security group must be in the same VPC. To revoke a specific rule for an IP protocol and port range, use a set of IP permissions instead.
`SourceSecurityGroupOwnerId`	`string`	Not supported.
`TagSpecification`	`array`	The tags applied to the security group rule.
`ToPort`	`integer`	If the protocol is TCP or UDP, this is the end of the port range. If the protocol is ICMP, this is the ICMP code or -1 (all ICMP codes).
`VpcId`	`string`	The ID of the VPC. Required for a nondefault VPC.

`SELECT` examples

describe_security_groups

Describes the specified security groups or all of your security groups.

SELECT
description,
group_id,
group_name,
ip_permissions,
ip_permissions_egress,
owner_id,
security_group_arn,
tags,
vpc_id
FROM aws.ec2.security_groups
WHERE region = '{{ region }}' -- required
AND GroupId = '{{ GroupId }}'
AND GroupName = '{{ GroupName }}'
AND NextToken = '{{ NextToken }}'
AND MaxResults = '{{ MaxResults }}'
AND DryRun = '{{ DryRun }}'
AND Filter = '{{ Filter }}'
;

`INSERT` examples

create_security_group
Manifest

Creates a security group. A security group acts as a virtual firewall for your instance to control inbound and outbound traffic. For more information, see Amazon EC2 security groups in the Amazon EC2 User Guide and Security groups for your VPC in the Amazon VPC User Guide. When you create a security group, you specify a friendly name of your choice. You can't have two security groups for the same VPC with the same name. You have a default security group for use in your VPC. If you don't specify a security group when you launch an instance, the instance is launched into the appropriate default security group. A default security group includes a default rule that grants instances unrestricted network access to each other. You can add or remove rules from your security groups using AuthorizeSecurityGroupIngress, AuthorizeSecurityGroupEgress, RevokeSecurityGroupIngress, and RevokeSecurityGroupEgress. For more information about VPC security group limits, see Amazon VPC Limits.

INSERT INTO aws.ec2.security_groups (
GroupDescription,
GroupName,
region,
VpcId,
TagSpecification,
DryRun
)
SELECT 
'{{ GroupDescription }}',
'{{ GroupName }}',
'{{ region }}',
'{{ VpcId }}',
'{{ TagSpecification }}',
'{{ DryRun }}'
RETURNING
group_id,
security_group_arn,
tags
;

# Description fields are for documentation purposes
- name: security_groups
props:
  - name: GroupDescription
    value: "{{ GroupDescription }}"
    description: Required parameter for the security_groups resource.
  - name: GroupName
    value: "{{ GroupName }}"
    description: Required parameter for the security_groups resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the security_groups resource.
  - name: VpcId
    value: "{{ VpcId }}"
    description: The ID of the VPC. Required for a nondefault VPC.
    description: The ID of the VPC. Required for a nondefault VPC.
  - name: TagSpecification
    value: "{{ TagSpecification }}"
    description: The tags to assign to the security group.
    description: The tags to assign to the security group.
  - name: DryRun
    value: {{ DryRun }}
    description: Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.
    description: Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

`UPDATE` examples

authorize_security_group_egress
authorize_security_group_ingress

Adds the specified outbound (egress) rules to a security group. An outbound rule permits instances to send traffic to the specified IPv4 or IPv6 address ranges, the IP address ranges specified by a prefix list, or the instances that are associated with a source security group. For more information, see Security group rules. You must specify exactly one of the following destinations: an IPv4 or IPv6 address range, a prefix list, or a security group. You must specify a protocol for each rule (for example, TCP). If the protocol is TCP or UDP, you must also specify a port or port range. If the protocol is ICMP or ICMPv6, you must also specify the ICMP type and code. Rule changes are propagated to instances associated with the security group as quickly as possible. However, a small delay might occur. For examples of rules that you can add to security groups for specific access scenarios, see Security group rules for different use cases in the Amazon EC2 User Guide. For information about security group quotas, see Amazon VPC quotas in the Amazon VPC User Guide.

UPDATE aws.ec2.security_groups
SET 
-- No updatable properties
WHERE 
GroupId = '{{ GroupId }}' --required
AND region = '{{ region }}' --required
AND TagSpecification = '{{ TagSpecification}}'
AND DryRun = {{ DryRun}}
AND SourceSecurityGroupName = '{{ SourceSecurityGroupName}}'
AND SourceSecurityGroupOwnerId = '{{ SourceSecurityGroupOwnerId}}'
AND IpProtocol = '{{ IpProtocol}}'
AND FromPort = '{{ FromPort}}'
AND ToPort = '{{ ToPort}}'
AND CidrIp = '{{ CidrIp}}'
AND IpPermissions = '{{ IpPermissions}}'
RETURNING
return,
security_group_rules;

Adds the specified inbound (ingress) rules to a security group. An inbound rule permits instances to receive traffic from the specified IPv4 or IPv6 address range, the IP address ranges that are specified by a prefix list, or the instances that are associated with a destination security group. For more information, see Security group rules. You must specify exactly one of the following sources: an IPv4 or IPv6 address range, a prefix list, or a security group. You must specify a protocol for each rule (for example, TCP). If the protocol is TCP or UDP, you must also specify a port or port range. If the protocol is ICMP or ICMPv6, you must also specify the ICMP/ICMPv6 type and code. Rule changes are propagated to instances associated with the security group as quickly as possible. However, a small delay might occur. For examples of rules that you can add to security groups for specific access scenarios, see Security group rules for different use cases in the Amazon EC2 User Guide. For more information about security group quotas, see Amazon VPC quotas in the Amazon VPC User Guide.

UPDATE aws.ec2.security_groups
SET 
-- No updatable properties
WHERE 
region = '{{ region }}' --required
AND CidrIp = '{{ CidrIp}}'
AND FromPort = '{{ FromPort}}'
AND GroupId = '{{ GroupId}}'
AND GroupName = '{{ GroupName}}'
AND IpPermissions = '{{ IpPermissions}}'
AND IpProtocol = '{{ IpProtocol}}'
AND SourceSecurityGroupName = '{{ SourceSecurityGroupName}}'
AND SourceSecurityGroupOwnerId = '{{ SourceSecurityGroupOwnerId}}'
AND ToPort = '{{ ToPort}}'
AND TagSpecification = '{{ TagSpecification}}'
AND DryRun = {{ DryRun}}
RETURNING
return,
security_group_rules;

`DELETE` examples

delete_security_group

Deletes a security group. If you attempt to delete a security group that is associated with an instance or network interface, is referenced by another security group in the same VPC, or has a VPC association, the operation fails with DependencyViolation.

DELETE FROM aws.ec2.security_groups
WHERE region = '{{ region }}' --required
AND GroupId = '{{ GroupId }}'
AND GroupName = '{{ GroupName }}'
AND DryRun = '{{ DryRun }}'
;

Lifecycle Methods

revoke_security_group_egress
revoke_security_group_ingress

Removes the specified outbound (egress) rules from the specified security group. You can specify rules using either rule IDs or security group rule properties. If you use rule properties, the values that you specify (for example, ports) must match the existing rule's values exactly. Each rule has a protocol, from and to ports, and destination (CIDR range, security group, or prefix list). For the TCP and UDP protocols, you must also specify the destination port or range of ports. For the ICMP protocol, you must also specify the ICMP type and code. If the security group rule has a description, you do not need to specify the description to revoke the rule. For a default VPC, if the values you specify do not match the existing rule's values, no error is returned, and the output describes the security group rules that were not revoked. Amazon Web Services recommends that you describe the security group to verify that the rules were removed. Rule changes are propagated to instances within the security group as quickly as possible. However, a small delay might occur.

EXEC aws.ec2.security_groups.revoke_security_group_egress 
@GroupId='{{ GroupId }}' --required, 
@region='{{ region }}' --required, 
@SecurityGroupRuleId='{{ SecurityGroupRuleId }}', 
@DryRun={{ DryRun }}, 
@SourceSecurityGroupName='{{ SourceSecurityGroupName }}', 
@SourceSecurityGroupOwnerId='{{ SourceSecurityGroupOwnerId }}', 
@IpProtocol='{{ IpProtocol }}', 
@FromPort='{{ FromPort }}', 
@ToPort='{{ ToPort }}', 
@CidrIp='{{ CidrIp }}', 
@IpPermissions='{{ IpPermissions }}'
;

Removes the specified inbound (ingress) rules from a security group. You can specify rules using either rule IDs or security group rule properties. If you use rule properties, the values that you specify (for example, ports) must match the existing rule's values exactly. Each rule has a protocol, from and to ports, and source (CIDR range, security group, or prefix list). For the TCP and UDP protocols, you must also specify the destination port or range of ports. For the ICMP protocol, you must also specify the ICMP type and code. If the security group rule has a description, you do not need to specify the description to revoke the rule. For a default VPC, if the values you specify do not match the existing rule's values, no error is returned, and the output describes the security group rules that were not revoked. For a non-default VPC, if the values you specify do not match the existing rule's values, an InvalidPermission.NotFound client error is returned, and no rules are revoked. Amazon Web Services recommends that you describe the security group to verify that the rules were removed. Rule changes are propagated to instances within the security group as quickly as possible. However, a small delay might occur.

EXEC aws.ec2.security_groups.revoke_security_group_ingress 
@region='{{ region }}' --required, 
@CidrIp='{{ CidrIp }}', 
@FromPort='{{ FromPort }}', 
@GroupId='{{ GroupId }}', 
@GroupName='{{ GroupName }}', 
@IpPermissions='{{ IpPermissions }}', 
@IpProtocol='{{ IpProtocol }}', 
@SourceSecurityGroupName='{{ SourceSecurityGroupName }}', 
@SourceSecurityGroupOwnerId='{{ SourceSecurityGroupOwnerId }}', 
@ToPort='{{ ToPort }}', 
@SecurityGroupRuleId='{{ SecurityGroupRuleId }}', 
@DryRun={{ DryRun }}
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

DELETE examples​

Lifecycle Methods​