ec2_security_group – Manage EC2 VPC security groups.

Create, delete or update an EC2 VPC security group.

Examples

- name: Create a very simple security group in the default vpc,
        allows all outbound and internal traffic
  ec2_security_group:
    name: my-first-security
    description: Secure me.
  register: first_security_group

- name: Prohibit all egress traffic from the security group
  ec2_security_group:
    id: "{{ first_security_group.id }}"
    egress:
      rules: []
      clear_rules: true

- name: Prohibit internal traffic within the security group
  ec2_security_group:
    id: "{{ first_security_group.id }}"
    ingress:
      rules: []
      clear_rules: true

- name: Allow unidirectional cross-traffic between this and another security group
  ec2_security_group:
    id: "{{ first_security_group.id }}"
    egress:
      rules:
        - protocol: all
          security_groups:
            - id: sg-1

- name: Allow IPv6-only 80/tcp, ICMPv4 and ICMPv6 echo traffic to the security group
  ec2_security_group:
    id: "{{ first_security_group.id }}"
    ingress:
      rules:
        - protocol: tcp
          port: 80
          ip_ranges:
            - cidr: ::/0
        - protocol: udp
          port_from: 10000
          port_to: 10010
          ip_ranges:
            - cidr: 192.0.2.0/24
              description: Super Load Balancer 3000
        - protocol: icmp
          icmp_type: 8
          ip_ranges:
            - cidr: 0.0.0.0/0
        - protocol: icmpv6
          icmp_type: 8
          ip_ranges:
            - cidr: 0.0.0.0/0

- name: Remove a security group
  ec2_security_group:
    id: "{{ first_security_group.id }}"
    state: absent

Parameters

auth (optional)

Parameters for authenticating with the AWS service. Each of them may be defined via environment variables.

type: dict
access_key (optional)

The AWS access key ID. If not set, the value of the AWS_ACCESS_KEY environment variable will be checked.

Mutually exclusive with profile.

type: str
profile (optional)

The name of the AWS profile configured with aws configure.

Can be used instead of explicitly specifying your access credentials and region.

Use default to use the default profile.

Mutually exclusive with access_key and secret_key.

type: str
region (optional)

The name of the AWS region.

If not set, the value of the AWS_REGION environment variable will be checked.

If you set a profile that specifies a default region, that region is used and you can omit this parameter. Use this parameter to override the profile’s default region.

type: str
secret_key (optional)

The AWS secret access key. If not set, the value of the AWS_SECRET_KEY environment variable will be checked.

Mutually exclusive with profile.

type: str
url (optional)

The URL to the AWS service related to the resource. By default, this is automatically determined through the region parameter.

If not set explicitly, the value of the AWS_<SERVICE>_URL environment variable will be used.

The services currently supported are EC2 and S3.

type: str
clear_tags (optional)

Whether to clear any existing tags on the resource that are not explicitly stated in tags.

By default, existing tags are kept on the resource.

When this parameter is set to true, any pre-existing tags on the resource (including the name tag) are removed. To clear all tags except the name tag, make sure to provide the name parameter.

type: bool
description (required)

Short description of the AWS resource.

type: str
egress (optional)

Egress (outbound) security rules.

Note that by default, every newly created security group will include a default egress rule which permits all outbound traffic.

type: dict
clear_rules (optional)

Whether to clear rules not specified in the rules section.

In other words, whether to treat the rule definitions of this task as exclusive.

type: bool
rules (optional)

IP/ICMP filtering rules as a whitelist.

The default value for this module does not include includes the default rules AWS creates. When clearing all rules, take note that the rules created by default will also be cleared.

type: list
icmp_code (optional)

The ICMP code (subtype) for this rule. If this parameter is omitted, the default behaviour is to allow all ICMP codes.

Only used when protocol=[icmp, icmpv6]

When icmp_code is specified, icmp_type is required.

type: int
default: -1
icmp_type (optional)

The ICMP type for this rule. If this parameter is omitted, the default behaviour is to allow all ICMP types.

Only used when protocol=[icmp, icmpv6]

If specifying icmp_code, this parameter is required.

type: int
default: -1
ip_ranges (optional)

The IP ranges for this rule in CIDR notation.

type: list
cidr (required)

In CIDR notation, the IP range of this rule.

type: str
description (optional)

An optional description for this IP range.

type: str
port (optional)

The port specification for this rule.

Only used when protocol=[tcp, udp]

Mutually exclusive with port_from and port_to.

type: int
port_from (optional)

The start port (inclusive) of the port range of this rule.

Only used when protocol=[tcp, udp]

Mutually exclusive with port.

Requires port_to.

type: int
port_to (optional)

The start port (inclusive) of the port range of this rule.

Only used when protocol=[tcp, udp]

Mutually exclusive with port.

Requires port_from.

type: int
protocol (required)

What protocol this rule applies to.

type: str
choices: all, tcp, udp, icmp, icmpv6
security_groups (optional)

The security group IDs when using VPC peering.

A special ID value of self references the security group controlled by this task.

type: list
description (optional)

An optional description for this security group reference.

type: str
id (required)

The ID of the security group this rule references.

type: str
id (optional)

ID of the resource to perform the task on.

If specified, this parameter is used to identify the resource.

Omit this parameter when you are first creating the resource.

type: str
ingress (optional)

Ingress (inbound) security rules.

Note that AWS creates a default ingress rule, which allows all traffic from the same security group, but only in the default security group created when a VPC is created.

type: dict
clear_rules (optional)

Whether to clear rules not specified in the rules section.

In other words, whether to treat the rule definitions of this task as exclusive.

type: bool
rules (optional)

IP/ICMP filtering rules as a whitelist.

The default value for this module does not include includes the default rules AWS creates. When clearing all rules, take note that the rules created by default will also be cleared.

type: list
icmp_code (optional)

The ICMP code (subtype) for this rule. If this parameter is omitted, the default behaviour is to allow all ICMP codes.

Only used when protocol=[icmp, icmpv6]

When icmp_code is specified, icmp_type is required.

type: int
default: -1
icmp_type (optional)

The ICMP type for this rule. If this parameter is omitted, the default behaviour is to allow all ICMP types.

Only used when protocol=[icmp, icmpv6]

If specifying icmp_code, this parameter is required.

type: int
default: -1
ip_ranges (optional)

The IP ranges for this rule in CIDR notation.

type: list
cidr (required)

In CIDR notation, the IP range of this rule.

type: str
description (optional)

An optional description for this IP range.

type: str
port (optional)

The port specification for this rule.

Only used when protocol=[tcp, udp]

Mutually exclusive with port_from and port_to.

type: int
port_from (optional)

The start port (inclusive) of the port range of this rule.

Only used when protocol=[tcp, udp]

Mutually exclusive with port.

Requires port_to.

type: int
port_to (optional)

The start port (inclusive) of the port range of this rule.

Only used when protocol=[tcp, udp]

Mutually exclusive with port.

Requires port_from.

type: int
protocol (required)

What protocol this rule applies to.

type: str
choices: all, tcp, udp, icmp, icmpv6
security_groups (optional)

The security group IDs when using VPC peering.

A special ID value of self references the security group controlled by this task.

type: list
description (optional)

An optional description for this security group reference.

type: str
id (required)

The ID of the security group this rule references.

type: str
name (optional)

The name for the security group.

Required when creating a security group or in combination with vpc to uniquely identify one.

Note that the security group name is not an AWS resource tag.

type: str
state (optional)

The desired state of the security group.

If absent, the security group is first detached from any instances and then deleted.

type: str
default: present
choices: present, absent
tags (optional)

Metadata for the AWS resource as key/value pairs.

Keys and values are case-sensitive.

type: dict
vpc (optional)

The ID of the VPC to assign this security group to.

If omitted, the default VPC is assumed.

When id is not specified, vpc will be used to identify a single security group in combination with name.

type: str

Return Values

object (success and I(state=present)), dict, {‘object’: {‘id’: ‘sg-df1b2aa66’, ‘name’: ‘my-first-secgroup’, ‘vpc’: ‘vpc-faff5721’, ‘description’: ‘A description for my first security group.’, ‘tags’: {‘MyCompany-Department’: ‘legal’}, ‘ingress’: {‘rules’: [{‘protocol’: ‘tcp’, ‘port_from’: 22, ‘port_to’: 22, ‘ip_ranges’: [{‘cidr’: ‘0.0.0.0/0’, ‘description’: ‘the world’}]}]}, ‘egress’: {‘rules’: [{‘protocol’: ‘icmp’, ‘icmp_type’: 8, ‘icmp_code’: 0, ‘security_groups’: [{‘id’: ‘sg-64508346’, ‘description’: ‘local sonar’}]}]}}}

An object representing an EC2 VPC security group.

id (always), str,

The ID of the security group.

name (always), str,

The name of the security group.

vpc (always), str,

The ID of the VPC this security group is assigned to.

description (always), str,

The security group’s description.

tags (always), dict,

The tags assigned to this security group.

ingress (always), dict,

Ingress (inbound) security rules.

rules (always), list,

Ingress (inbound) security rules.

Rules are normalized so each rule only contains one of security_groups or ip_ranges, and at most one element.

protocol (always), str,

The protocol this rule applies to.

port_from (when I(protocol=[tcp, udp])), int,

The start port (inclusive) of the port range of this rule.

port_to (when I(protocol=[tcp, udp])), int,

The start port (inclusive) of the port range of this rule.

icmp_type (when I(protocol=[icmp, icmpv6])), int,

The ICMP type for this rule.

icmp_code (when I(protocol=[icmp, icmpv6])), int,

The ICMP code (subtype) for this rule.

security_groups (when I(ip_range) is not present), list,

A list of a single security group ID and its description.

id (always), str,

The ID of the security group this rule references.

description (), str,

The description for this security group reference, if any.

ip_ranges (when I(security_group) is not present), list,

A list of a single IP range for this rule in CIDR notation.

cidr (always), str,

In CIDR notation, the IP range of this rule.

description (), str,

An optional description for this IP range.

egress (always), dict,

Egress (outbound) security rules.

rules (always), list,

Egress (outbound) security rules.

Rules are normalized so each rule only contains one of security_groups or ip_ranges, and at most one element.

protocol (always), str,

The protocol this rule applies to.

port_from (when I(protocol=[tcp, udp])), int,

The start port (inclusive) of the port range of this rule.

port_to (when I(protocol=[tcp, udp])), int,

The start port (inclusive) of the port range of this rule.

icmp_type (when I(protocol=[icmp, icmpv6])), int,

The ICMP type for this rule.

icmp_code (when I(protocol=[icmp, icmpv6])), int,

The ICMP code (subtype) for this rule.

security_groups (when I(ip_range) is not present), list,

A list of a single security group ID and its description.

id (always), str,

The ID of the security group this rule references.

description (), str,

The description for this security group reference, if any.

ip_ranges (when I(security_group) is not present), list,

A list of a single IP range for this rule in CIDR notation.

cidr (always), str,

In CIDR notation, the IP range of this rule.

description (), str,

An optional description for this IP range.