IP Groups (Add, Change, Remove)¶

Standard change: Create or change an IP group in the hub firewall configuration.

Effect: an IP group (azurerm_ip_group) is created, updated or deleted in the connectivity resource group of each region that deploys the file. Rules that refer to the group follow automatically. Only the firewall layer changes.

IP groups are the building blocks of firewall rules. For the design guidance (when to use a group, naming, renaming in two steps) see Firewall rule and IP group guidelines. For the rule files that use the groups, see Firewall rules. To edit the files with suggestions and validation, see Edit the JSON files with schema support.

Request fields¶

Request field	Where it goes	Notes
Name	`ip_group.name` and the file name	See naming. Unique in the platform environment.
Purpose	pull request description	What the group represents and which workload owns it.
Addresses	`ip_group.cidrs`	CIDR ranges or single IPv4 addresses.
Used by	pull request description	Which rules use the group, or will use it.
Environment	platform environment and region folder	Create the file in every platform environment that needs it (`canary` and `prod`).
Rationale	pull request / change record

Where the files are¶

IP group files are JSON files in an ip_groups folder. The location is set in <env-folder>/<region>/firewall.auto.tfvars (see Firewall rules):

Global groups in <env-folder>/ip_groups/, deployed to every region.
Regional groups in <env-folder>/<region>/ip_groups/. A regional file with the same file name as a global file replaces it in that region.

Keep the folder name ip_groups: the config tests find the groups by it. One file holds one IP group. Sub-folders per workload are allowed.

Some platforms keep all IP groups in the global folder only, because the groups are the same in every region. Choose one approach and document it. Each platform environment has its own folder, so the file must exist in both canary and prod.

IP group JSON¶

{
  "ip_group": {
    "name": "ipgrp-azure-app1-prod-web",
    "cidrs": [
      "10.20.4.0/26",
      "10.20.5.16/32"
    ]
  }
}

Property	Required	Rules
`ip_group`	yes	The only top-level property.
`name`	yes	Unique. It is the Azure name and the name that rules use to refer to the group.
`cidrs`	yes	A list of strings. Each string is an IPv4 address, optionally with a prefix length (`/0` to `/32`). A single host can be written with or without `/32`. Use one style consistently.

No other properties are allowed.

Naming¶

Use a pattern that tells the reader what the group contains. Two patterns are in use. Choose one for your platform:

Pattern	Example	Use
`ipgrp-<description>` for platform groups, `ipgrp-<workload>-<description>-<environment>` for workload groups	`ipgrp-hub`, `ipgrp-app1-web-prod`	Short. Used in the guidelines.
`ipgrp-<onprem or azure>-<workload>-<environment>-<use>`	`ipgrp-azure-app1-prod-web`, `ipgrp-onprem-dns`	Shows where the addresses live. Choose `azure` if both apply. Leave out the workload or environment when it does not apply.

Whatever you choose, the name says what the addresses are, not which rule uses them.

Create an IP group¶

Collect the request fields. Check that the group does not exist yet (search the ip_groups folders by address).
Create a branch (Making a change safely).
Create <name>.json in the ip_groups folder of the canary environment, and fill it in.
Validate the file against the schema (Edit the JSON files with schema support). Check the notation of every address.
Copy the file to the ip_groups folder of the prod environment (and to every region folder that needs it).
Run the config tests, commit and open a pull request. Reviewers use the IP group change runbook.
After approval, deploy canary, check the result, then deploy prod (deployment). The plan shows azurerm_ip_group added and nothing else.

If you create the group together with the rules that use it, put both in one pull request. The group must exist in the same deployment or in an earlier one.

Change an IP group¶

Edit the cidrs list in the file of the canary environment.
Make the same change in the prod file. Overwrite it with the validated file when the two environments are meant to be equal.
Pull request, review, deploy canary, verify, deploy prod.

Changing the addresses of a group changes every rule that uses the group. Read the list of rules that use it before you change it, and describe the effect in the pull request.

Rename or remove an IP group¶

A rule that refers to a group that no longer exists fails the deployment. Do it in two pull requests, as described in Rename or remove an IP group in two steps.

Do and don't¶

Do	Don't
Use a clear name that reflects the purpose.	Mix unrelated subnets in one group.
Validate the file against the schema.	Use addresses that are not scoped or agreed for the purpose.
Use the normal branch and pull request process.	Commit directly to `main` without review.
Keep the naming convention consistent across all groups.	Create a group for addresses that only one rule uses. Put them in the rule.
Test in `canary` first.	Rename or delete a group in the same change that updates the rules.

Verify¶

Azure portal → IP Groups in the connectivity resource group: the group exists and has the addresses.
Firewall Policies → the policy of the region → the rules that use the group show the group name.

Roll back¶

Revert the pull request and run hub again.

Common problems¶

Symptom	Cause
Config test `Referenced IP Group '<x>' should exist`	The name in the rule differs from the group name, or the file is not in a folder named `ip_groups`.
Schema error on `cidrs`	An entry is not an IPv4 address or CIDR, for example a missing octet or a prefix above `/32`.
Schema error on the file	A property other than `name` and `cidrs` is present, or `ip_group` is missing.
The plan wants to destroy and create the group	The `name` changed. The name is the identity of the group.
Rules still use old addresses	The change is not deployed to that platform environment or region yet.