.. meta:: :description: Create, delete or update an EC2 VPC security group. .. _ec2_security_group_module: ec2_security_group -- Manage EC2 VPC security groups. ===================================================== Create, delete or update an EC2 VPC security group. Examples -------- .. code-block:: yaml+jinja - 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 See Also -------- .. seealso:: - :ref:`ec2_security_group_info_module` 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__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.