hunfabric/modules/net-vpc-firewall/README.md

Google Cloud VPC Firewall

This module allows creation and management of different types of firewall rules for a single VPC network:

• custom rules via the egress_rules and ingress_rules variables
• optional predefined rules that simplify prototyping via the default_rules_config variable

The predefined rules are enabled by default and set to the ranges of the GCP health checkers for HTTP/HTTPS, and the IAP forwarders for SSH. See the relevant section below on how to configure or disable them.

• Examples
  • Minimal open firewall
  • Custom rules
  • Controlling or turning off default rules
    • Overriding default tags and ranges
    • Disabling predefined rules
  • Including source and destination ranges
  • Rules Factory
• Variables
• Outputs

Examples

Minimal open firewall

This is often useful for prototyping or testing infrastructure, allowing open ingress from the private range, enabling SSH to private addresses from IAP, and HTTP/HTTPS from the health checkers.

module "firewall" {
  source     = "./fabric/modules/net-vpc-firewall"
  project_id = var.project_id
  network    = var.vpc.name
  default_rules_config = {
    admin_ranges = ["10.0.0.0/8"]
  }
}
# tftest modules=1 resources=4 inventory=basic.yaml e2e

Custom rules

This is an example of how to define custom rules, with a sample rule allowing open ingress for the NTP protocol to instances with the ntp-svc tag.

Some implicit defaults are used in the rules variable types and can be controlled by explicitly setting specific attributes:

• action is controlled via the deny attribute which defaults to true for egress and false for ingress
• priority defaults to 1000
• destination ranges (for egress) and source ranges (for ingress) default to ["0.0.0.0/0"] if not explicitly set or set to null, to disable the behaviour set ranges to the empty list ([])
• rules default to all protocols if not set

module "firewall" {
  source     = "./fabric/modules/net-vpc-firewall"
  project_id = var.project_id
  network    = var.vpc.name
  default_rules_config = {
    admin_ranges = ["10.0.0.0/8"]
  }
  egress_rules = {
    # implicit deny action
    allow-egress-rfc1918 = {
      deny        = false
      description = "Allow egress to RFC 1918 ranges."
      destination_ranges = [
        "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"
      ]
    }
    allow-egress-tag = {
      deny        = false
      description = "Allow egress from a specific tag to 0/0."
      targets     = ["target-tag"]
    }
    deny-egress-all = {
      description = "Block egress."
    }
  }
  ingress_rules = {
    # implicit allow action
    allow-ingress-ntp = {
      description = "Allow NTP service based on tag."
      targets     = ["ntp-svc"]
      rules       = [{ protocol = "udp", ports = [123] }]
    }
    allow-ingress-tag = {
      description   = "Allow ingress from a specific tag."
      source_ranges = []
      sources       = ["client-tag"]
      targets       = ["target-tag"]
    }
  }
}
# tftest modules=1 resources=9 inventory=custom-rules.yaml e2e

Controlling or turning off default rules

Predefined rules can be controlled or turned off via the default_rules_config variable.

Overriding default tags and ranges

Each protocol rule has a default set of tags and ranges:

• the health check range and the http-server/https-server tag for HTTP/HTTPS, matching tags set via GCP console flags on GCE instances
• the IAP forwarders range and ssh tag for SSH

Default tags and ranges can be overridden for each protocol, like shown here for SSH:

module "firewall" {
  source     = "./fabric/modules/net-vpc-firewall"
  project_id = var.project_id
  network    = var.vpc.name
  default_rules_config = {
    ssh_ranges = ["10.0.0.0/8"]
    ssh_tags   = ["ssh-default"]
  }
}
# tftest modules=1 resources=3 inventory=custom-ssh-default-rule.yaml e2e

Disabling predefined rules

Default rules can be disabled individually by specifying an empty set of ranges:

module "firewall" {
  source     = "./fabric/modules/net-vpc-firewall"
  project_id = var.project_id
  network    = var.vpc.name
  default_rules_config = {
    ssh_ranges = []
  }
}
# tftest modules=1 resources=2 inventory=no-ssh-default-rules.yaml e2e

Or the entire set of rules can be disabled via the disabled attribute:

module "firewall" {
  source     = "./fabric/modules/net-vpc-firewall"
  project_id = var.project_id
  network    = var.vpc.name
  default_rules_config = {
    disabled = true
  }
}
# tftest modules=0 resources=0 inventory=no-default-rules.yaml e2e

Including source and destination ranges

Custom rules now support including both source & destination ranges in ingress and egress rules:

module "firewall" {
  source     = "./fabric/modules/net-vpc-firewall"
  project_id = var.project_id
  network    = var.vpc.name
  default_rules_config = {
    disabled = true
  }
  egress_rules = {
    deny-egress-source-destination-ranges = {
      description        = "Deny egress using source and destination ranges"
      source_ranges      = ["10.132.0.0/20", "10.138.0.0/20"]
      destination_ranges = ["172.16.0.0/12"]
    }
  }
  ingress_rules = {
    allow-ingress-source-destination-ranges = {
      description        = "Allow ingress using source and destination ranges"
      source_ranges      = ["172.16.0.0/12"]
      destination_ranges = ["10.132.0.0/20", "10.138.0.0/20"]
    }
  }
}
# tftest modules=1 resources=2 inventory=local-ranges.yaml e2e

Rules Factory

The module includes a rules factory for massive creation of rules leveraging YaML configuration files. Each configuration file can optionally contain more than one rule which a structure that reflects the custom_rules variable.

module "firewall" {
  source     = "./fabric/modules/net-vpc-firewall"
  project_id = var.project_id
  network    = var.vpc.name
  factories_config = {
    rules_folder  = "configs/firewall/rules"
    cidr_tpl_file = "configs/firewall/cidrs.yaml"
  }
  default_rules_config = { disabled = true }
}
# tftest modules=1 resources=3 files=lbs,cidrs inventory=factory.yaml

ingress:
  allow-healthchecks:
    description: Allow ingress from healthchecks.
    source_ranges:
      - healthchecks
    targets: ["lb-backends"]
    rules:
      - protocol: tcp
        ports:
          - 80
          - 443
  allow-service-1-to-service-2:
    description: Allow ingress from service-1 SA
    targets: ["service-2"]
    use_service_accounts: true
    sources:
      - service-1@project-id.iam.gserviceaccount.com
    rules:
      - protocol: tcp
        ports:
          - 80
          - 443
egress:
  block-telnet:
    description: block outbound telnet
    deny: true
    rules:
      - protocol: tcp
        ports:
          - 23

# tftest-file id=lbs path=configs/firewall/rules/load_balancers.yaml schema=firewall-rules.schema.json

healthchecks:
  - 35.191.0.0/16
  - 130.211.0.0/22
  - 209.85.152.0/22
  - 209.85.204.0/22

# tftest-file id=cidrs path=configs/firewall/cidrs.yaml

Instead of using factories_config.cidr_tpl_file file, you can pass CIDR blocks directly in the named_ranges variable. This approach could be useful for dynamically generated CIDR blocks from outputs of other resources.

module "firewall" {
  source     = "./fabric/modules/net-vpc-firewall"
  project_id = var.project_id
  network    = var.vpc.name
  factories_config = {
    rules_folder = "configs/firewall/rules"
  }
  default_rules_config = { disabled = true }
  named_ranges = {
    healthchecks = [
      "35.191.0.0/16",
      "130.211.0.0/22",
      "209.85.152.0/22",
      "209.85.204.0/22",
    ]
  }
}
# tftest modules=1 resources=3 files=lbs inventory=factory.yaml

Variables

name	description	type	required	default
network	Name of the network this set of firewall rules applies to.	string	✓
project_id	Project id of the project that holds the network.	string	✓
default_rules_config	Optionally created convenience rules. Set the 'disabled' attribute to true, or individual rule attributes to empty lists to disable.	object({…})		{}
egress_rules	List of egress rule definitions, default to deny action. Null destination ranges will be replaced with 0/0.	map(object({…}))		{}
factories_config	Paths to data files and folders that enable factory functionality.	object({…})		{}
ingress_rules	List of ingress rule definitions, default to allow action. Null source ranges will be replaced with 0/0.	map(object({…}))		{}
named_ranges	Define mapping of names to ranges that can be used in custom rules.	map(list(string))		{…}

Outputs

name	description	sensitive
default_rules	Default rule resources.
rules	Custom rule resources.