Skip to content

Spoke Creation

Operator runbook for the standard change New workload / spoke / application landing zone (spoke canvas). It gives the order of work from the request to a pull request that is ready for review. The fields, the JSON, what gets created and how to verify are in New spoke and the Spoke JSON reference. The review is in Spoke pull request review, the deployment in Spoke deployment.

1. Check the request

If the requester added a pull request with the spoke file, review it carefully for syntax and completeness, and go to Spoke pull request review. Otherwise check the request form. Do not start before it is complete.

Field Mandatory Example / note
Name yes The workload. Gives workloadShortName (at most 6 characters, cannot change later).
Rationale yes
Environment yes dev, tst, acc, prd, shared. One spoke per environment.
Usage type (production data yes or no) yes Decides the management group, and the pii tag when personal data is involved.
IP range yes For example a /24. Allocated from the IP plan, never invented.
Subnet name, size, delegations, service endpoints no Delegation names come from the schema list.
Which team needs access yes The name of an existing group in Entra ID.

If something is missing or unclear, ask the requester or the owner of the platform design.

2. Prepare

  1. Check the prerequisites of New spoke → Before you start: the subscription exists, the management group exists in the foundation configuration, the team groups exist, the approvals are in place, the address range is reserved in the IP plan.
  2. Create a branch from main in the configuration repository with the ticket number in the name, for example change/<ticket-id>-spoke-<workload>.

3. Create the spoke file

  1. Start from a template. Always take the latest spoke template or a recent working spoke of the same kind, and copy it. Do not edit the template itself.
  2. Name the file by the naming convention of your platform and make it unique across all sub-folders of the spokes/ folder, for example canvas_<workload>_<environment>.json. Some platforms use a pattern that also shows production or non-production. The file must be in a sub-folder.
  3. Fill in all fields with the values of the request: no placeholders must remain.
    • workloadShortName, environment, azureSubscriptionId, azureSubscriptionName, managementGroupId
    • tags with owner, department, workload, pii, costcentre and environment
    • adInfo with the team groups and the PIM modes
    • targetRegions, and the network entries in resourceconfiguration
    • optional blocks (storageaccount, keyvault, loganalytics, azdo) as agreed
  4. Use the placeholders ##wlshortname##, ##environment## and ##region## in resource names, as in the examples of the reference.

4. Validate

  1. Validate the file against the spoke schema (Edit the JSON files with schema support). Fix every error and warning.
  2. Check the file name against the naming convention.
  3. Cross-check every value with the request and with the source systems (IP plan, subscription, groups).
  4. Check that all required fields are filled in and that the optional ones are handled on purpose.
  5. Run the config tests locally if you can (Run the tests locally).
  6. Ask a colleague for a peer review before the pull request, for structure, completeness and correctness.

5. Commit, push and open the pull request

  1. Commit with a message that says which spoke and for whom, and push the branch.
  2. Open the pull request to main, with a title and description that say what the spoke is for. Link the ticket.
  3. The validation pipeline runs on the pull request. Fix what it reports and push again: the checks restart.
  4. When the checks are green, ask a second engineer for the review (Spoke pull request review).

6. Deploy

After approval and merge, deploy the spoke with the spoke pipeline: Spoke deployment. The spoke is complete when the pull request is merged and the pipeline run has finished and been verified.

7. Finish

  • Tell the requester what was created: the subscription name, the virtual network range, the group names and how to activate the role if PIM applies (What happens next).
  • Record complex configuration for later reference.
  • If the spoke gets managed VMs, add its folder to the list of spokes of the module pipeline (Managed VM module).
  • Firewall rules for the traffic of the spoke are separate changes (Firewall rules).

Subscription creation

The spoke pipeline needs an existing subscription ID. How the subscription is created depends on the process of the organisation (and in some platforms on a separate pipeline of the platform team): see New spoke → Before you start.