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

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.

ec2_security_group – Manage EC2 VPC security groups.¶

Examples¶

See Also¶

Parameters¶

Return Values¶