Add a rule

Add a rule to decide which backend group serves a request, for example to send /api to one group and everything else to another. A rule matches requests by path, method, header, or query parameter and forwards them to one backend group, or splits them between two or more to roll out a new version to a slice of traffic.

Before you begin

• A Load Balancer in the Running state. Add rule is available only then.
• At least one backend group. See Create a backend group. Until you add one, the Rules tab says “Rules forward to backend groups, and this load balancer has none yet. Create one on the Backend groups tab first.”
• Permission to update Load Balancers in the project. See TIR Access Control.

Until a rule forwards to a backend group, a Running Load Balancer answers every request with a 503 error. Its page offers Add a backend group and Add a routing rule to fix that.

Add the rule

Open the Load Balancer, select the Rules tab, and select Add rule.

1. In Rule name, enter a name. It is required and must be unique in the Load Balancer.
2. (Optional) In Priority, enter a number of 0 or more. Priority only breaks ties between equally specific rules: a more specific match always wins, whatever the priority. Among rules of the same specificity, a lower number is tried first, and a rule with its priority left blank, shown as “auto”, goes last.
3. Under When a request matches, select Add condition and choose a kind. A request must meet every condition to match the rule, and a rule with an empty condition list matches every request. You can remove any condition.
   • Path is starts with, is exactly, or matches regex, with a path such as /api/v2. Add it once.
   • Method is is one of, with comma-separated methods such as GET, POST. The methods accepted are GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE, and CONNECT. Add it once.
   • Header has a name, an operator (equals, matches regex, or is present), and a value. is present needs only the header name. You can add several.
   • Query param has a name, an operator (equals or matches regex), and a value. You can add several.
4. Under Forward to, choose a backend group in Select a backend group. A new rule starts with one group at 100%.
5. (Optional) To send some requests to a second group, select Split traffic with another group, and Add another group for more. Each row has a weight and a percentage, and you can remove a row.
   • A weight is a whole number of 0 or more. Weights are relative to each other, so they can add up to any total. Weights of 90 and 10 send roughly 90% of requests to the first group and 10% to the second, which is useful for trying a new version on a small share of users.
   • A group with weight 0 gets no requests.
   • Each group can be chosen in one row only.
   • All backend groups in one rule must use the same protocol: HTTP, HTTPS, or gRPC.
6. Select Add rule, or Save changes when you edit a rule.

You can save a rule once it has at least one backend group with a weight above 0 and lists each group only once. Method accepts only the methods listed above. A condition with an empty path, method list, or name is dropped when you save the rule.

The rule is listed on the Rules tab as Active, with the share of traffic each group gets when it forwards to more than one.

A rule applies to the E2E address and to a custom domain alike.

Edit or delete a rule

In the Actions menu of the rule, choose Edit or Delete. TIR applies an edit or a delete to the running Load Balancer. If that fails, TIR undoes the change and reports “Failed to update routing rule. Please try again later.” or “Failed to delete routing rule. Please try again later.”

A deleted rule stops matching at once, and its traffic falls through to the remaining rules, so check what is left before you delete.

Your Load Balancer now sends matching requests to your backends. To serve them on your own domain over HTTPS, see Use a custom domain and certificate. For help with a message, see Troubleshooting TIR Load Balancer.