Platform Upgrade Guides (v4.4.0 to v4.12.x)¶

Version-specific steps for upgrading a customer configuration repository. Use them together with the generic procedure in What to do when a new version is released.

How to use these guides¶

The guides are cumulative. Read and do the guide of every version between your current and your target version, oldest first. A version that is not listed (for example v4.8 or v4.10) needs no special steps.
Do the portal clean-up before you continue with later steps. Removing a policy assignment or initiative needs permission at the management group. Request elevated access (PIM) first where your process requires it.
Paths are relative to the root of the configuration repository. Older versions used a parameters repository with the same layout. <env> stands for each platform environment folder (canary, prod) under environments/. Do every file step in each environment.
Some guides describe the older single-pipeline layout (pipelines/main.yaml). In the current layout the entry pipelines are hub, spoke, infrastructure and container (Pipelines and workflows). Where a step does not apply to your layout, the guide says so.
If you upgrade over several versions, plan once at the end rather than after each guide. Read the plan for unexpected destroys or replacements (Reading the spoke plans).

Version	From	Summary
v4.4.0	v4.3.x	Delete policy files, set state storage overrides, remove two policy objects in the portal
v4.5.0	v4.4.x	Entry pipeline: add the configuration repository as a resource and publish it
v4.5.1	v4.5.x	Remove custom alerting assignments, initiatives and `Deploy_*` definitions
v4.6.0 and v4.6.1	v4.5.x	Add `ghrunners.auto.tfvars`
v4.7.0	v4.6.x	Remove three Defender for Cloud assignments
v4.9.0	v4.7.x	Shorten tfvars paths, add a firewall variable, remove the `environment` parameter
v4.11.x	v4.9.x	Delete old DNS and BIO policy files, remove two assignments and two initiatives
v4.12.x	v4.11.x	Remove the private DNS zones assignment and initiative, check `firewall_policy_id`

Version 4.4.0¶

From v4.3.x. Policy and monitoring configuration moved into the code repository, so the copies in the configuration repository must go (history).

Remove files from the configuration repository¶

Do this for both environments/prod/ and environments/canary/.

Path under `environments/<env>/policies/`	Remove
`policy_assignments/01_management_groups/`	`policy_set_assignment_compliance_asc.json`, `policy_set_assignment_compliance_cis.json`, `policy_set_assignment_compliance_iso.json`, `policy_set_assignment_defender.json`, `policy_set_assignment_diagnostics.json`
`definitions/general/`	Every `policy_definition_es_deploy_diagnostics_*.json`, and `policy_definition_es_deploy_asc_securitycontacts.json`
`set_definitions/general/`	`policy_set_definition_defender_for_cloud.json`, `policy_set_definition_es_deploy_diagnostics_loganalytics.json`, `policy_set_definition_es_deploy_mdfc_config.json`

Set the state storage location if it is not the default¶

The platform now needs to know where the Terraform state storage account is. If yours matches all of the defaults below, do nothing.

Item	Default
Storage account name	`stlz<company short name>state001`
Resource group	`rg-<company short name>-tfstate-<location short name>-001`
Subscription	The management subscription

If any value differs, add these variables to environments/prod/global.tfvars (and the canary equivalent):

Variable	Value
`overwrite_state_storage_subscription_id`	The subscription ID of the state storage account
`overwrite_state_storage_rg_name`	The resource group name of the state storage account
`overwrite_state_storage_name`	The name of the state storage account

Remove two policy objects in the Azure portal¶

Open Azure Policy, then Authoring > Definitions.
Search for Deploy-MDFC-Config and open the initiative. On the Assignments tab, remove each assignment. Go back and delete the initiative.
Search for Deploy Microsoft Defender for Cloud Security Contacts and open the policy. Remove each assignment on the Assignments tab, then delete the definition.

Version 4.5.0¶

From v4.4.x. This guide applies to the older single-pipeline layout. It makes the pipeline check out the configuration repository explicitly and publish it as an artifact. The same release added GitHub as a source for the platform configuration.

In pipelines/main.yaml of the configuration repository:

Add the configuration repository as a resource, next to the code repository:

resources:
  repositories:
    - repository: <code repository resource name>
      type: git
      name: <project>/<code repository name>
      ref: refs/tags/<version>

    - repository: <configuration repository resource name>   # new
      type: git
      name: <configuration repository name>
      ref: $(Build.SourceBranch)

Make sure the name of the new resource is the real name of the configuration repository.

Change the first checkout step from self to the new resource:

- checkout: <configuration repository resource name>   # was: self
  path: s/customer
  fetchDepth: 0
  persistCredentials: true
  clean: true

- checkout: <code repository resource name>
  path: s/landingzone-core
  clean: true

Add a task that publishes the configuration as an artifact, after the existing firewall artifact task:

- task: PublishPipelineArtifact@1
  displayName: Publish Customer Content
  inputs:
    targetPath: '$(System.DefaultWorkingDirectory)/customer/'
    artifact: 'CustomerSource'
    publishLocation: 'pipeline'

The current entry pipelines (hub.yaml and the others) already check out the configuration repository. This guide is not needed for them.

Version 4.5.1¶

From v4.5.x. The alerting policies were replaced by Azure Monitor Baseline Alerts, so the old custom alerting objects must be removed (How alerting works). Request Owner access on the canary and prod platform through PIM first. Do the steps for both canary and prod.

Remove the alerting policy assignments. In Azure Policy > Assignments, remove all five assignments named Xebia Custom - Alerting - *.
Remove the alerting policy initiatives. In Azure Policy > Definitions, remove all five definitions named Alerting-*.

Remove the Deploy_* policy definitions. Open an Azure PowerShell session (locally or in Cloud Shell) and run the command below for each environment, with the management group ID of that environment's platform:

$managementGroupId = "<management group id of the platform>"
Get-AzPolicyDefinition -ManagementGroupName $managementGroupId | Where-Object {$_.Name -Like "Deploy_*"} | Remove-AzPolicyDefinition -Force

Check what the filter matches first

The filter removes every custom policy definition at that management group whose name starts with Deploy_. Run the first part of the command without Remove-AzPolicyDefinition and read the list. Remove only definitions that the platform created.

Version 4.6.0 and 4.6.1¶

From v4.5.x. Version 4.6.0 added a layer with the network for GitHub-hosted runners. The layer needs a variables file even when it is not used.

For each environment and region you deploy, add environments/<env>/<region>/ghrunners.auto.tfvars:

# General
deploy_github_runners = false
location              = "northeurope"
location_short_name   = "neu"

# Virtual Network
virtual_network_address_space = null
virtual_network_dns_servers   = null

# Subnets
subnets = null

Set location and location_short_name to the region of the folder you are in. Keep deploy_github_runners = false unless the customer uses GitHub-hosted runners.

Current pipelines

The ghrunners layer exists in the code but is not part of the current hub pipeline. The file has no effect there (Deployment layers). Only older pipelines run it.

Version 4.7.0¶

From v4.6.x. In the Azure portal, open Azure Policy > Authoring > Assignments, search for these assignments, and delete them:

Xebia Default - Defender for Cloud v2 - connectivity
Xebia Default - Defender for Cloud v2 - identity
Xebia Default - Defender for Cloud v2 - management

Version 4.9.0¶

From v4.7.x. Three changes in the configuration repository.

Shorten the file paths in every tfvars file¶

Find every path that starts with ../../../../customer/ and remove that part. Do this in all *.tfvars files.

Old: ../../../../customer/environments/prod/firewall_rule_configuration
New: environments/prod/firewall_rule_configuration

Add a variable to every firewall tfvars file¶

In each firewall.auto.tfvars (one per region), add the variable below. Use prod or canary to match the environment folder of the file.

firewall_rule_collection_global_file_location = "environments/prod/firewall_rule_configuration"

Remove the environment parameter from the entry pipeline¶

In pipelines/main.yaml (single-pipeline layout):

At the template reference for the canary environment (environment_canary), remove the environment: canary parameter.
At the template reference for the production environment (environment_prod), remove the environment: prod parameter.

Version 4.11.x¶

From v4.9.x. The platform now ships its own private DNS policies, and the custom BIO initiative is gone.

Remove old DNS policy files¶

In both environments/canary/ and environments/prod/, remove:

the folders policies/policy_set_definitions/private_dns_zones and policies/policy_definitions/private_dns_zones;
the files policies/policy_set_definitions/general/policy_set_definition_es_deploy_private_dns_zones.json and policies/policy_set_definitions/general/policy_set_definition_es_enforce_encrypttransit.json;
the file policies/policy_assignments/01_management_groups/policy_set_assignment_xms_private_dns_zones.json.

Remove the old BIO initiative¶

In both environments, remove the folder policies/policy_set_definitions/bio_custom.

Remove policy objects in the Azure portal¶

Open Azure Policy > Assignments. Set the scope to the Landing Zones management group and remove the Alerting-LandingZone assignment.
Set the scope to the platform root management group (the cloudplatform group) and remove the XMS-Deploy-DNS-Zones assignment.
Open Definitions. Set the scope to Landing Zones and remove the Alerting-LandingZone initiative.
Set the scope to the platform root and remove the XMS-Deploy-DNS-Zones initiative.

Names and scopes

The initiative Alerting-LandingZone is also the name of an initiative in the current alerting design (Monitoring rules). The guide removes the old object, the one the previous version deployed. Check the scope and the assignment name before you delete.

Version 4.12.x¶

From v4.11.x. Two steps.

Remove the old private DNS zones objects in the Azure portal¶

Open Azure Policy > Assignments. Set the scope to Landing Zones and remove the XMMS-Private-DNS-Zones assignment.
Open Definitions. Set the scope to the platform root management group and remove the XMMS-Private-DNS-Zones initiative.

Verify the Application Gateway WAF policy ID¶

Every Application Gateway JSON file needs a valid firewall_policy_id.

Open every environments/*/*/application_gateways/*.json in the configuration repository.
If firewall_policy_id holds a valid WAF policy resource ID, for example /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Network/applicationGatewayWebApplicationFirewallPolicies/<waf-policy-name>, you are done with this file.
If it is null or an empty string, find the Application Gateway in the Azure portal by the name in the file and open it.
Open JSON View, select the latest API version, find "firewallPolicy" and copy its id value into the file.
In the pasted value, change ApplicationGatewayWebApplicationFirewallPolicies to applicationGatewayWebApplicationFirewallPolicies (a lower-case a at the start).
Repeat for every file, then commit and push.

See Application Gateway for the rest of the file.

After the guides¶

Run hub in Plan mode and read every layer (step 6).
Record the guides you followed on the work item.
If a step did not work as written, or a guide is missing, report it so that the guide can be corrected (Releasing).