Application Gateway Change¶

Operator and reviewer runbook for the standard changes Add workload to Application Gateway and Changes to workload configuration within Application Gateway. The request fields, the full JSON and the effects are in Application Gateway. This page gives the order in which to edit, the checks, and the typical problems. The deployment is in Application Gateway deployment.

1. Check the request¶

Do not start before these fields are complete:

Field	Note
Workload name	Used in the names of the pool, setting, listener, rule and probe.
Backend address (IP or FQDN)	The backend must be reachable from the gateway subnet.
Listener URL and port (HTTP or HTTPS)	The public host name.
SSL certificate	Mandatory for an HTTPS listener. The certificate must already be in the gateway Key Vault (see step 4).
Redirect	Yes or no (for example HTTP to HTTPS).
Health probe	Standard, or custom with path, protocol and interval.
Custom error pages	Optional (for example for 502 and 403).

2. Prepare the change¶

Branch from main in the configuration repository, with the ticket number in the name.
Open the gateway file of the region: application_gateway_hub.json in the region's application_gateways/ folder. Use that exact name for the hub gateway: the config tests only check that file.
Make the same change for every platform environment that needs it, canary first.

3. Edit in this order¶

Each step adds or changes one map in the file. The names you give in an earlier step are the references in a later one, so use one naming pattern per workload (for example <workload>-pool, <workload>-https-settings).

Step	Map	What to do	Check
1	`backend_address_pools`	Add the pool with `ip_addresses` and/or `fqdns`.	IPv4 only for addresses.
2	`probes`	Only for a custom probe: protocol, host, path, interval, timeout, unhealthy threshold.	With a standard probe, `probe_name` in the HTTP setting stays `null`.
3	`backend_http_settings`	Port, protocol, host name, request timeout, probe name. Either a fixed `host_name`, or `pick_host_name_from_backend_address` set to `true` with `host_name` `null`.	A backend that is addressed over HTTPS needs a trusted certificate.
4	`ssl_certificates`	Reference the certificate by its Key Vault secret URI.	See below.
5	`http_listeners`	Host name, protocol, port, certificate.	The `protocol` and the `frontend_port_name` match: `Https` with the HTTPS port, `Http` with the HTTP port. An HTTPS listener has `ssl_certificate_name`.
6	`redirect_configurations`	Only if a redirect is requested.
7	`request_routing_rules`	Link listener, pool and setting (or the redirect).	A unique `priority`. Each listener is used by one rule only.

The certificate¶

The certificate must be imported in the Key Vault of the gateway before you deploy, as a Certificate in PFX format. The safest way is that the requester imports it: the PFX with its private key and password is then never sent to the platform team. Point the requester at Microsoft's tutorial for importing a certificate.

In the file, the certificate is a secret URI: https://<key vault>.vault.azure.net/secrets/<name>. How a URI with and without a version behaves is explained in Replace a certificate.
certificate_password_secret_id is null when the PFX has no password. If it has one, store the password as a secret in the same Key Vault and reference it in the same way.
Check the expiry date of the certificate and put it in the monitoring or calendar of the owner.

4. Validate, commit and open the pull request¶

Validate the JSON against the schema, and run the config tests (Edit the JSON files with schema support).
Check the routing logic once more: the references, the priorities and the listeners.
Commit with a clear message, push, and open the pull request. Link the ticket.
Check with the network and security owners of your organisation when the change publishes something new to the internet.

Reviewer checklist¶

Do the general checks first. Then:

Check	Why
Every reference points to an existing key: pool, setting, probe, listener, port, certificate, redirect	The deployment fails, or the gateway is changed in an unexpected way.
Each HTTPS listener has a certificate, and the secret exists in the gateway Key Vault	The listener cannot start without it.
Listener `protocol` and port match	A mismatch breaks the listener.
Routing rule priorities are unique and each listener is used once	Config test.
The backend address is valid and the backend path is open: a firewall rule from the gateway subnet and the NSG	Otherwise the backend is unhealthy and users see a 502.
The probe fits the backend: path, host, protocol	A wrong probe marks a good backend as unhealthy.
Nothing else changed: other workloads on the same gateway keep their entries	One file describes the whole gateway.
The change is in both `canary` and `prod` when applicable	Test on canary first.
No existing key is renamed by accident	Renaming a key renames the sub-resource.

Dos and don'ts¶

Do	Don't
Coordinate with the network and security teams before the change.	Forget to link an HTTPS listener to a certificate.
Review the expiry dates of certificates regularly.	Ignore conflicts between routing rules and pool assignments.
Check that the probe configuration is right.	Overlook the effect on the existing workloads on the same gateway.
Keep a record of the change.	Apply a change without testing it in the non-production environment first.

Troubleshooting¶

Symptom	Cause and action
The backend is unreachable	The pool has a wrong address, or the firewall or NSG blocks the gateway. Most of the time a firewall rule from the gateway subnet to the backend is needed (Firewall rules).
The listener does not work	It is linked to the wrong frontend IP configuration or port.
A certificate error	The certificate is not installed correctly, or it is tied to the wrong listener.