Skip to content

Handle a Firewall Rule Request

Operator runbook for the standard changes Add new firewall rules and Change firewall rules. It takes you from a request in the ticket system to a pull request that is ready for review. The format of the files, the fields and the pipeline are in Firewall rules. The review is in Firewall rule pull request review, the deployment in Firewall rule deployment.

If the requester already made a pull request

A workload team that has access to the configuration repository can prepare the change itself (Firewall rules and IP groups for workload teams). Then the configuration change exists already. Skip to Validate the pull request and then start the review.

1. Check that the request is complete

There are two kinds of request: a new rule and a change to an existing rule. Do not start until the fields are complete. A missing field goes back to the requester.

Field New rule Existing rule Notes
Workload name or spoke yes yes Use it to find the file and the owner.
Rationale yes yes
Environment yes yes Production, non-production, or the platform environments.
Rule name yes The key of the rule in the file.
Protocols yes yes Network: TCP, UDP, ICMP, Any. Application: Http, Https, Mssql with a port.
Ports yes yes
Source yes yes Addresses or IP groups. Only one of the two types.
Destination yes yes Addresses, IP groups or FQDNs (network rule), FQDNs or FQDN tags (application rule). Only one type per rule.
Description and integration yes What the rule is for, and which other workload or on-premises system it connects to.

Two source types are not possible in this configuration: an FQDN as source, and a service tag as source. Ask the requester for the source address range or an IP group. FQDN tags are only used in application rules.

If a field is unclear, ask the requester or the owner of the platform design. Do not start before the request is complete.

2. Create a branch

Branch from main in the configuration repository and include the ticket number, as in Making a change safely: change/<ticket-id>-firewall-<workload>. Pull the branch to your machine.

3. Decide where the rule goes

Global or regional. A global rule is active in every region. A regional rule only in the region of the folder. DNS rules are global. A rule between two spokes in one region is regional. If you cannot decide, ask. See Global or regional rule.

Which file. Rules are in one file per rule collection group. The files are organised by workload and environment type, for example weu/<workload>/<workload>-prod.json, or by service, for example a file for the Bastion rules (Organise the configuration around workloads). Use the existing file of the workload when there is one.

If the rule collection group does not exist yet, create a folder for the workload in both platform environment folders (canary and prod), and a file in it. Give it a priority that is unused and inside the range of the owner (Priorities). Take the next free value. Check the existing files, and when in doubt the firewall policy in the Azure portal, because the config test only compares priorities inside one folder.

4. Choose the rule type and the objects

Question Answer
Is the traffic only HTTP, HTTPS or SQL (Mssql), and is the destination an FQDN? Use an application rule.
Anything else (other ports, IP destinations, internal traffic) Use a network rule.
Does a rule with the same purpose already exist? Check whether you can add an address to the IP group that the rule uses, instead of adding a new rule.
Should the rule apply to only one of several IP groups? Do not add destinations to an existing collection that serves several groups. Add a separate rule.
Is the destination on the internet? Use an FQDN or an FQDN tag, not an IP address.

Use an IP group for the source or destination whenever the same set of addresses occurs in more than one rule. Each spoke or workload should have an IP group from the start. Find existing groups in the ip_groups folders of the platform environment (and region). Create a missing group first, or in the same pull request (IP groups).

5. Edit the file

  • New rule: add a key to the rules map of the right collection. A collection has one type and one action. Fill in only one source type and one destination type, and leave the other lists empty ([]). Copy the structure from Rule collection group JSON.
  • Existing rule: find the rule by its name in the file and change the fields named in the request. Keep the name.
  • Make the same change in canary and prod.
  • When the new rule replaces another, add the new rule now and remove the old one in a later pull request. Never remove the old rule in the same change (Make firewall changes safely).
  • Validate the JSON with the schema in your editor (Edit the JSON files with schema support). The priority only needs attention when you create a new file: the config tests check it.

6. Open and validate the pull request

  1. Commit with a message that says what you changed and for whom, and push the branch.
  2. Open a pull request to main. Title and description: the workload, the traffic (from where, to where, which port) and the reason. Link the ticket, and search for the ticket by its title if your tool uses another identifier.
  3. Set auto-complete as described in Pull request review: do not resolve the work item after merging, and delete the source branch.
  4. The validation pipeline starts. Open the checks of the pull request and read the result. If it fails, fix the cause in your branch and push again. The pipeline runs again by itself.
  5. When the pipeline is green, ask a second engineer for the review.

7. After the review

Deploy as described in Firewall rule deployment, canary first.

Troubleshooting

Check What it tells you
Priorities of rule collection groups and collections They must not clash. A clash normally fails the deployment, but check anyway.
Rules that overlap The first match decides. A network rule that denies a port to an FQDN hides an application rule that allows it.
Destination is an IP address for an internet service The address can change and the rule stops matching. Use the FQDN.
Other filtering layers NSGs, ASGs and network interface settings can block the traffic after the firewall allows it.

More problems and their causes are in Common problems.