Skip to content

Firewall Rules and IP Groups for Workload Teams

Traffic that leaves your spoke, enters it or goes to another spoke passes the central firewall, and the firewall blocks everything that no rule allows. This page helps you to ask for a rule, or, if your platform lets you, to prepare the change yourself as a pull request. What to ask, who must approve and which rule type to choose is already described on How to request. The design rules the platform team follows are in the Firewall rule and IP group guidelines. This page does not repeat them. It shows the files and the steps from your side.

Choose your route

Route You do The platform team does
Request Fill in the request fields on How to request in a ticket. Edits the files, has the change reviewed, deploys it.
Pull request Edit the files yourself, open a pull request, and link it to a ticket. Reviews, merges and deploys. You never complete your own pull request.

The pull request route needs access to the configuration repository. Ask your platform team whether it is open to you (How to request). Every rule still needs a ticket: the ticket is the change record and carries the approvals.

Before you start

  1. Know the traffic. Source (your spoke or subnet), destination (FQDN, address, service tag), port and protocol, and why you need it. For internet destinations, find the FQDN. An IP address of a public service can change.
  2. Know who approves. The owner of the destination approves rules between workloads. Security reviews many other rules. See Who requests which rule and What the review usually checks.
  3. Check what exists. A rule may already cover your traffic. Look in the files of your workload in the configuration repository.

The files in short

What Where One file is
Firewall rules firewall_rule_configuration/ (global) or <region>/firewall_rule_configuration/ (one region) One rule collection group
IP groups ip_groups/ (global) or <region>/ip_groups/ (one region) One IP group

Each platform environment has its own folders (canary and prod). A change goes in both, canary first. Your non-production and production traffic are usually separate rule collection groups, so that production data cannot flow to non-production.

Prepare a firewall rule

1. Find or create the file of your workload

Rules are organised per workload. Use the file of your workload and environment type. If there is none, the platform team tells you the folder and the priority range. Don't pick a priority yourself without checking: priorities must be unique and inside the range of the owner.

2. Write the rule

A rule collection group has three maps: NAT, network and application rule collections. All three must be present, also when they are empty. This is a rule in a network collection, and one in an application collection:

{
  "rule_collection_group": {
    "name": "app1-prod",
    "priority": 2100,
    "nat_rule_collections": {},
    "network_rule_collections": {
      "NetworkRules": {
        "priority": 110,
        "action": "Allow",
        "rules": {
          "app1-vm-to-servicebus": {
            "protocols": ["TCP"],
            "source_addresses": [],
            "source_ip_groups": ["ipgrp-app1-web-prod"],
            "destination_addresses": [],
            "destination_ip_groups": [],
            "destination_fqdns": ["<namespace>.servicebus.windows.net"],
            "destination_ports": ["443"]
          }
        }
      }
    },
    "application_rule_collections": {
      "ApplicationRules": {
        "priority": 120,
        "action": "Allow",
        "rules": {
          "app1-to-vendor-api": {
            "protocols": ["Https:443"],
            "source_addresses": [],
            "source_ip_groups": ["ipgrp-app1-web-prod"],
            "destination_fqdns": ["api.vendor.example"],
            "destination_fqdn_tags": []
          }
        }
      }
    }
  }
}

The numbers and names are examples. Use the ones your platform team gives you.

Rules of thumb:

  • Application rule for HTTP, HTTPS and SQL traffic to an FQDN. Network rule for everything else. The checklist is in Application or network rule.
  • One source type and one destination type per rule. Use either addresses or IP groups as the source, and either addresses, IP groups or FQDNs as the destination. Leave the other lists empty.
  • Exact ports, no wildcards. Don't ask for *, for Any, or for wide ranges without a reason.
  • FQDN instead of IP address for internet destinations.
  • A single ticket and pull request per rule collection group. Don't combine unrelated changes.
  • To replace a rule, add the new rule first and ask for the removal of the old one afterwards.

All properties, the allowed values and the limits are in Rule collection group JSON.

3. Use IP groups for sets of addresses

If more than one rule uses the same set of addresses, put them in an IP group and refer to it by name (below).

4. Check the file

Use an editor that knows the JSON schemas. It suggests the properties, lists the allowed values and underlines mistakes (Edit the JSON files with schema support). If you can, run the config tests of the repository as well (Run the tests locally).

5. Open the pull request

  • Branch name and title as your platform team agreed, for example [APP1] Add firewall rules - Service Bus connectivity.
  • Description: the traffic (from where, to where, which port and protocol), the reason, the environments, and the ticket.
  • Make the same change in the canary and the prod folder.
  • Wait for the checks of the pipeline, and fix what they report.
  • Do not complete the pull request yourself. The platform team reviews it with the checklist for firewall rules.

IP groups

An IP group is a named set of addresses and ranges. Rules refer to it by name, so that you change the addresses in one place.

When to use one, and when not, is in IP groups. In short: use one for a set that several rules use, that changes regularly, or that has one clear purpose (the web servers of one workload in production). Don't make one for the addresses of a single rule.

The file is small:

{
  "ip_group": {
    "name": "ipgrp-app1-web-prod",
    "cidrs": ["10.20.4.0/26"]
  }
}
  • name: unique, and in the naming scheme of your platform. It says what the addresses are.
  • cidrs: IPv4 addresses or ranges (a single host as /32).
  • Don't mix unrelated subnets in one group, and don't add addresses that are not agreed for the purpose.
  • Create the group in the same pull request as the rules that use it, or before.
  • To change the addresses of a group, edit the file. Every rule that uses it follows, so say in the pull request which rules are affected.
  • To rename or remove a group, ask the platform team to do it in two steps: first the rules, then the group.

The operator runbook is IP groups.

After the merge

  1. The platform team deploys to canary, checks the result and deploys to production. You are informed through the ticket (What happens next).
  2. Test the traffic from your workload, for example with curl or Test-NetConnection <destination> -Port <port>.
  3. If it does not work, check these before you ask for help: the rule exists in the firewall policy, the NSG of your subnet allows the traffic, the name resolves, and the destination accepts the connection. The platform team can look at the firewall logs for your source and destination (Read the firewall logs).
  4. Tell the platform team when the ticket can be closed.

Don't

  • Change firewall rules in the portal. The next deployment overwrites them.
  • Ask for a rule you don't need yet. If access is temporary, say so in the ticket and give the end date, so the rule can be removed.
  • Use rules to connect production and non-production.