# security-groups

Creates security groups with fully declarative ingress and egress rules, referenced by CIDR, security group, or self.

Provisions one or more security groups from a single map input, where each rule can source traffic from IPv4 CIDRs, IPv6 CIDRs, another security group in the same module call, an existing security group by ID, or the rule's own security group. A rule with multiple sources (e.g. two CIDRs) expands into one AWS resource per source, so nothing is silently dropped.

## Usage

```hcl
module "sg" {
  source  = "hcassc.jfrog.io/iac-tf-modules-virtual__networking/security-groups/aws"
  version = "0.1.0"

  vpc_id      = module.vpc.id
  name_prefix = "prod"

  security_groups = {
    web = {
      name_suffix = "web-sg"
      description = "Web tier"

      ingress_rules = [
        {
          description      = "HTTPS from internet"
          protocol         = "tcp"
          from_port        = 443
          to_port          = 443
          ipv4_cidr_blocks = ["0.0.0.0/0"]
        },
        {
          description = "Health check between web instances"
          protocol    = "tcp"
          from_port   = 8080
          to_port     = 8080
          self        = true
        },
      ]

      egress_rules = [
        {
          description   = "To db tier"
          protocol      = "tcp"
          from_port     = 5432
          to_port       = 5432
          source_sg_key = "db"
        },
      ]
    }

    db = {
      name_suffix = "db-sg"
      description = "DB tier"

      ingress_rules = [
        {
          description   = "Postgres from web tier"
          protocol      = "tcp"
          from_port     = 5432
          to_port       = 5432
          source_sg_key = "web"
        },
      ]
    }
  }
}
```

## Rule sources

Each ingress or egress rule sets one or more of the following. A rule must set at least one.

| Field              | Type           | Resolves to                                             |
| ------------------ | -------------- | ------------------------------------------------------- |
| `ipv4_cidr_blocks` | `list(string)` | One resource per CIDR                                   |
| `ipv6_cidr_blocks` | `list(string)` | One resource per CIDR                                   |
| `source_sg_key`    | `string`       | Another security group created by this same module call |
| `source_sg_id`     | `string`       | Any existing security group, by ID (e.g. `sg-0123abcd`) |
| `self`             | `bool`         | The rule's own security group                           |

<!-- BEGIN_TF_DOCS — DO NOT EDIT BELOW THIS LINE -->

## Requirements

| Name                                                                     | Version            |
| ------------------------------------------------------------------------ | ------------------ |
| <a name="requirement_terraform"></a> [terraform](#requirement_terraform) | >= 1.15.0, < 2.0.0 |
| <a name="requirement_aws"></a> [aws](#requirement_aws)                   | >= 6.0, < 7.0      |

## Providers

| Name                                             | Version       |
| ------------------------------------------------ | ------------- |
| <a name="provider_aws"></a> [aws](#provider_aws) | >= 6.0, < 7.0 |

## Resources

| Name                                                                                                                                                    | Type     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| [aws_security_group.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/security_group)                                   | resource |
| [aws_vpc_security_group_egress_rule.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc_security_group_egress_rule)   | resource |
| [aws_vpc_security_group_ingress_rule.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc_security_group_ingress_rule) | resource |

## Inputs

| Name                                                                           | Description                                                          | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Default | Required |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | :------: |
| <a name="input_name_prefix"></a> [name_prefix](#input_name_prefix)             | Prefix prepended to every security group name created by this module | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | n/a     |   yes    |
| <a name="input_vpc_id"></a> [vpc_id](#input_vpc_id)                            | ID of the VPC in which to create security groups                     | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | n/a     |   yes    |
| <a name="input_security_groups"></a> [security_groups](#input_security_groups) | Map of security group definitions                                    | <pre>map(object({<br/> name_suffix = string<br/> description = string<br/> ingress_rules = optional(list(object({<br/> description = optional(string, "")<br/> protocol = string<br/> from_port = number<br/> to_port = number<br/> ipv4_cidr_blocks = optional(list(string), [])<br/> ipv6_cidr_blocks = optional(list(string), [])<br/> source_sg_key = optional(string, null)<br/> source_sg_id = optional(string, null)<br/> self = optional(bool, false)<br/> })), [])<br/> egress_rules = optional(list(object({<br/> description = optional(string, "")<br/> protocol = string<br/> from_port = number<br/> to_port = number<br/> ipv4_cidr_blocks = optional(list(string), [])<br/> ipv6_cidr_blocks = optional(list(string), [])<br/> source_sg_key = optional(string, null)<br/> source_sg_id = optional(string, null)<br/> self = optional(bool, false)<br/> })), [])<br/> }))</pre> | `{}`    |    no    |
| <a name="input_tags"></a> [tags](#input_tags)                                  | Resource tags to apply to all resources                              | `map(string)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `{}`    |    no    |

## Outputs

| Name                                                                                | Description                                                                                                                                             |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a name="output_arn_list"></a> [arn_list](#output_arn_list)                         | Flat list of all security group ARNs                                                                                                                    |
| <a name="output_arns"></a> [arns](#output_arns)                                     | Map of security group logical key to ARN                                                                                                                |
| <a name="output_egress_rule_ids"></a> [egress_rule_ids](#output_egress_rule_ids)    | Map of egress rule key (sg_key-egress-idx-source_type-i) to security group rule ID                                                                      |
| <a name="output_id_list"></a> [id_list](#output_id_list)                            | Flat list of all security group IDs, for use in security_groups/vpc_security_group_ids arguments                                                        |
| <a name="output_ids"></a> [ids](#output_ids)                                        | Map of security group logical key to ID                                                                                                                 |
| <a name="output_ingress_rule_ids"></a> [ingress_rule_ids](#output_ingress_rule_ids) | Map of ingress rule key (sg_key-ingress-idx-source_type-i) to security group rule ID                                                                    |
| <a name="output_names"></a> [names](#output_names)                                  | Map of security group logical key to name                                                                                                               |
| <a name="output_rule_counts"></a> [rule_counts](#output_rule_counts)                | Map of security group logical key to its actual ingress/egress resource counts after expanding multi-source rules, for validating expected rules landed |
| <a name="output_vpc_id"></a> [vpc_id](#output_vpc_id)                               | VPC ID security groups were created in                                                                                                                  |

<!-- END_TF_DOCS — DO NOT EDIT ABOVE THIS LINE -->