New Sandbox Subscription¶

Work in progress. This runbook is general guidance. The intended design is a deployment like a spoke, but with only a subscription and no spoke canvas. That flow does not exist yet in the codebase. Below is what you can do with the current code, and what you must do by hand.

Standard change: New Azure Sandbox Subscription

Intended effect: a new subscription for experiments, placed in the sandbox management group, with access for the requesting team. It gets no hub connection, no virtual network and no spoke resources.

Request fields¶

Field	Use
Subscription Name	Display name of the subscription
Rationale	Change record
Environment	Platform environment (`canary` / `prod`) whose `sandbox` management group is used
Which team needs access	Entra ID group that gets access
Comments

What the current code supports¶

Need	Supported by code?	How
Create the subscription	No (not through the pipelines, see New spoke)	Create it through your EA/MCA/CSP process.
Place it in the `sandbox` management group	Yes	`foundation` layer: `management_group_structure.sandbox.subscription_ids`
Team access (RBAC/PIM)	No	Assign roles by hand, or through your identity governance process.
Tags	No	Set them by hand.
Policies and monitoring	Inherited	Everything assigned at the `cloudplatform` management group applies, including the built-in compliance initiatives and the Service Health alert initiative if enabled there. Assignments on `landingzones` do not apply.

Alternative: a spoke without a hub connection¶

If the experiment needs the spoke baseline (network, groups, Key Vault, Log Analytics) but must not be connected to the hub or to other networks, create a normal spoke in a sandbox management group and set peerHub to false on its network (see the Spoke JSON reference). The spoke then has no virtual hub connection and therefore no route to other spokes, to on-premises networks or (through the hub firewall) to the internet. Check the DNS and routing behaviour of such a spoke before you promise a team that it works.

Steps¶

Create the subscription through your billing process. Note its subscription ID.
Add it to the sandbox management group. In <env-folder>/<primary region>/foundation.auto.tfvars, append the ID to the list:

management_group_structure = {
  # ...
  sandbox = {
    id               = "cloudplatform-sandbox"
    display_name     = "Sandbox"
    subscription_ids = [
      "11111111-1111-1111-1111-111111111111",
      "22222222-2222-2222-2222-222222222222"   # new
    ]
  },
  # ...
}

Run hub and read the foundation plan for the primary region. Expect one added azurerm_management_group_subscription_association.
Grant access by hand: assign the team's Entra ID group a role on the subscription, for example Contributor. Use PIM if your organization requires it.
Record the subscription, owner and expiry date in the change ticket. Sandboxes tend to outlive their purpose.

Caveats of `subscription_ids`¶

From infra/modules/management_groups/main.tf:

resource "azurerm_management_group_subscription_association" "this" {
  count           = length(var.management_group_subscription_association_subscription_ids)
  subscription_id = "/subscriptions/${element(var..._subscription_ids, count.index)}"
  lifecycle {
    ignore_changes = [management_group_id, subscription_id]
  }
}

The associations are addressed by list position (count.index), and changes to subscription_id are ignored.
Only append to the end of the list. Never remove or reorder entries. Removing an entry from the middle shifts the positions. Terraform then destroys the last association, which moves that subscription out of the management group. The remaining positions keep their old subscription in state.
To move a subscription out of sandbox, move it in Azure (portal or CLI) and leave the list as it is. Or plan the change and read the foundation plan very carefully.

Removing a sandbox subscription¶

Move it to the decommissioned management group:
by hand, or
by appending its ID to decommissioned.subscription_ids, with the same caveats as above.
Cancel it through your billing process.