Skip to content

IP Group Change

Operator and reviewer runbook for the standard change Create or change an IP group. The files, the JSON, the naming and the verification are in IP groups. This page gives the order of work and the checks. The deployment is the same as for firewall rules (Firewall rule deployment), because both are in the firewall layer.

Operator: create a group

  1. Check the request. You need the purpose, the addresses (CIDR or single IPv4 addresses), the workload that owns the group, and which rules use or will use it. Check that the group does not exist yet.
  2. Create a branch from main in the configuration repository, with the ticket number in the name.
  3. Choose the name. Follow the naming scheme of your platform (Naming). The name must be unique.
  4. Create the file <name>.json in the ip_groups folder of the canary environment (global folder, or the region folder if the group is regional). Use the structure of IP group JSON.
  5. Validate the file with the schema in your editor (Edit the JSON files with schema support). Check every address and prefix. Don't mix in addresses that are not agreed for the purpose.
  6. Copy the file to the ip_groups folder of the prod environment (and to each region folder that needs it).
  7. Commit, push and open a pull request to main. Link the ticket, and describe the purpose and the users of the group.
  8. After the review, deploy: canary first, check the apply, then prod (Firewall rule deployment). The plan shows only azurerm_ip_group added.

Operator: change a group

  1. Branch from main.
  2. Edit the file in canary. Check which rules use the group: the change applies to all of them.
  3. Make sure the file in prod gets the same content. Copy the validated file over the existing one when the two should be equal.
  4. Commit, push, pull request. Describe the effect on the rules.
  5. Review, deploy canary, verify, deploy prod.

For a rename or a removal, use two pull requests: change or remove the references in the rules first and deploy, then rename or delete the group (two steps).

Reviewer checklist

Start with the general checks. Then, for every file:

Check Why
The file is in a folder named ip_groups, in both canary and prod The config tests and the deployment find groups by folder name.
The file name equals the group name, and the name follows the naming scheme Readability and traceability.
The JSON has ip_group with name and cidrs and nothing else The schema rejects other properties.
Every entry in cidrs is a valid IPv4 address or CIDR range, written in the same style Notation errors fail the deployment.
The addresses belong together and are agreed for the purpose A group with unrelated subnets opens more than intended.
No overlap with other groups that makes a rule unclear Rules should show clearly what they open.
The change in canary and prod is the same, or the difference is explained Environments drift apart otherwise.
For a rename or removal: no rule refers to the old name any more A rule with a missing group fails the deployment.
The pull request lists the rules that use the group, and the effect of the change A group change changes every rule that uses it.

Approve when all checks are in order. Otherwise send it back (how).

Troubleshooting

  • Schema or format errors. Compare the file with the schema. Typical causes: a missing octet, a prefix above /32, a property other than name and cidrs, a list written as one string.
  • IP address conflicts. Ask the owner of the IP plan which ranges are agreed. Don't guess.
  • Commit problems. Read the validation result of the pipeline and go back to the validation step.